Digital PDFs

XX-AA716-98

February 1984

277 pages

Original

12MB

Document:	TSX-Plus 5.0 Reference Manual
Order Number:	XX-AA716-98
Revision:	0
Pages:	277
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/tsxPlus/manuals_5.0/TSX-Plus_5.0_Reference_Manual_Feb84.pdf

OCR Text

TSX·Plus
Reference Manual

s&h computer systems, inc.

TSX-Plus
Reference Manual

s&h computer systems, inc.

TSX-Plus
Reference Manual

Third Edition
First Printing -- February, 1984
Copyright (c) 1980, 1981, 1982, 1983, 1984.
S&H Computer Systems, Inc.
1027 17th Avenue South
Nashville, Tennessee USA
37212
(615)-327-3670
The information in this document is subject to change without notice and should
not be construed as a commitment by S & H Computer Systems Inc. S & H assumes
no responsibility for any errors that may appear in this document.
NOTE: TSX, TSX-Plus, COBOL-Plus, SORT-Plus and RTSORT are proprietary products
owned and developed by S&H Computer Systems, Inc., Nashville, Tennessee, USA.
The use of these products is governed by a licensing agreement that prohibits
the licensing or distribution of these products except by authorized dealers.
Unless otherwise noted in the licensing agreement, each copy of these products
may be used only with a single computer at a single site. S&H will seek legal
redress for any unauthorized use of these products.
Questions regarding the licensing arrangements for these products should be
addressed to S&H Computer Systems, Inc., 1027 17th Ave.
South, Nashville,
Tennessee 37212, (615)-327-3670, TELEX 786577 S AND H UD.
TSX, TSX-Plus, COBOL-Plus, SORT-Plus and RTSORT are trademarks of S&H Computer
Systems, Inc. DEC, RT-11, CTS-300, DIBOL and PDP-11 are trademarks of Digital
Equipment Corporation.
DBL is a trademark of Digital Information Systems
Corporation.

CONTENTS
INTRODUCTION
Management of system resources
Summary of chapter contents

1
2
4

Chapter 1
BASIC OPERATION
Logging on
Logging off
Control characters
Single line editor

9
9

10
11

12
Chapter 2

KEYBOARD COMMANDS
Keyboard command interpretation
User defined commands
User Command Interface
Keyboard commands
ACCESS Command
ASSIGN Command
BACKUP Command
BOOT Command
BYE Command
COBOL Command
COMPILE Command
COpy Command
CREATE Command
DATE Command
DEASSIGN Command
DELETE Command
DETACH Command
DIBOL Command
DIFFERENCES Command
DIRECTORY Command
DISMOUNT Command
DISPLAY Command
DUMP Command
EDIT Command
EXE CUTE Command
FORM Command
FORTRAN Command
HELP Command
INITIALIZE Command
KILL Command
KJOB Command
LIBRARY Command
LINK Command
MACRO Command
i

17
20
24
28
28
28

29
29
29
29
30
30
30

31
31
31
31
32
32
32
33

34
34
34
34
34
35
35
35

36
36
36
36
37

MAKE Command
MEMORY Command
MONITOR Command
MOUNT Command
MUNG Command
OFF Command
OPERATOR Command
PAUSE Command
PRINT Command
PROTECT Command
R Command
RENAME Command
RESET Command
RUN Command
SEND Command
SET Command
SET CACHE
SET CCL
SET CORTU1
SET EDIT
SET EMT
SET ERROR
SET HIPRCT
SET IND
SET INTIOC
SET IO
SET KMON
SET LANGUAGE
SET LD
SET LOG
SET LOGOFF
SET MAXPRIORITY •
SET NUMDC
SET PRIORITY
SET PROMPT
SET QUANxx
SET SIGNAL
SET SL
ASK
K52
KED
KEX
LEARN
LET
OFF
ON
RT11
SYSGEN
TTYIN
VT52
VT62
VT100
VT101
VT102

37
37
38
38
40
40
40
41
41
41
41
44
44
44
44
45
46
46
47
47
47
48
48
49
49
49
49
50
51
51
52
52
53
53
54
54
54
55
55
55
55
55
55
55
55
55
56
56
56
56
56
56
56
56
ii

\-lIDTH
SET TERMINAL
SET TT
ADM3A
DECWRITER
DEFER
DIABLO
ECHO
FORM
FORMO
GAG
HAZELTINE
LA36 •
LA120
LC
PAGE
QUIET
QUME
SCOPE
SINGLE
TAB
TAPE
VT50
VT52
VT100
WAIT
SET UCL
SET VM
SET WILDCARDS
SHOW Command
SHOW ALL
sno\-l ASSIGNS
SHOW CACHE
SHOW COMMANDS
SHOW CONFIGURATION
SHOW CORTIM •
SHOW DEVICES
SHOW HIPRCT
SHOW INTIOC
SHOW JOBS
SHOW MEMORY
SHOW MOUNTS
SHOW NUMDC
SHOW PRIORITY •
SHOW QUANxx •
SHOW QUEUE
SHOW RUN-TIMES
SHOW SUBSETS
SHOW TERMINALS
SHOW USE
SPOOL Command
SQUEEZE Command
SYSTAT Command
TECO Command

56
56
56
57
57
57
57
57
57
57
57
58
58
58
58
58
58

58
58
58
59
59
59

59
59
59
60
61
61
62
62
62
63
63
63
63
64
64
65
65
65
65
66
66
66
67
67
67
68
68
69
69
70
71
iii

TIME Command •
TYPE Command •
UCL Command
UNPROTECT Command
USE Command
WHO Command . • • • •
$STOP Command
$SHUTDOWN Command
RT-11 Commands not supported by TSX-Plus

72
72
72
72
72
72
72
73
73

Chapter 3
COMMAND FILES
Invoking command files
Parameter strings • • •
Comments in command files
Command file control characters
PAUSE Command • •
• • • •
DISPLAY Command • . • • • • • •

76
76
77
78

79
79

Chapter 4
VIRTUAL TIME-SHARING LINES AND DETACHED JOBS
Virtual lines .
• • ~ • • • •
Detached jobs •
• • •.
The DETACH Command
• • • • • •
Starting a detached job •
Checking detached job status
• •
Aborting a detached job • • • • •
Detached job control EMTs
• • • •
Starting a detached job
Aborting a detached job •
Checking detached job status

• • • • • •
••••
• • • •
• • • •
• •

81
81

82
83
83
84

85
85
85
87

Chapter .5
DEVICE SPOOLING
The concept of device spooling • • ••
•.••
Directing output to spooled devices • •
Operation of the spooler
• • • • • •
The SPOOL Command • • • • • •
FORM and LOCK functions
ALIGN function •
DELETE function
SKIP function
BACK function • • • •
STAT function
SING and MOLT functions
HOLD and NOHOLD functions
Use of special forms with spooled devices •
Form alignment procedure •• • • • • • • •
iv

89
89
89
89
90
90
91
91
91
92
92
92
93
95
96

Chapter 6
CONTROLLED TERMINAL OPTIONS
Terminal input/output handling
Program controlled terminal options • • • • • • • • • •
Set rubout filler character
Set VT52 and VT100 escape-letter activation
Define new activation character • • • • • • • • •
Control character echoing
Disable virtual line use • •
Control lower case input • • .
Control character echoing
Set transparency mode of output • • . • . • • .
Control command file input • • • • • • • • •
Reset activation character • • •
Set activation on field width
Turn on high-efficiency mode • . • • • • • • • •
Turn on single-character activation mode
Turn off single-character activation mode
Enable non-wait TT input testing •
Set field width limit
Control tape mode
• • • • •
Control line-feed echo following carriage-return

PROGRfu~

97
97

99
102
102
103
103
103
103
103
104
104
1 () I.

LV"","

104
104
105
105
105
, (). C.
l.VU

106
106

Chapter 7

TSX -Plus Et1T'S •
Determining if a job is under TSX-Plus
Determining the TSX-Plus line number
Determining the terminal type • • • •
Determining or changing the user name
Controlling the size of a job • • •
Obtaining TSX-Plus system values • • • •
Determining job status information
Setting job priority • • • • • • • •
Forcing [non]interactive job characteristics
Sending a message to another line •
Mount a file structure • • • • •
Dismount a file structure • • . • •
Set terminal read time-out value
Establish break sentinel control
Checking for terminal input errors
Checking for activation characters
Printing a block of characters • • • •
Accepting a block of characters • •
Program controlled terminal options •
Controlling high-efficiency terminal mode . .
Determining number of free spool blocks •
Set/Reset ODT activation mode • • • • •
Determining file directory information
Setting file creation time • • • • • • •
v

107
107
108
109
110
111
112

114
117
120
121
122
123
124
125
127
128
130
131
132
132
134
135
136
138

Chapter 8
TSX-Plus JOB ENVIRONMENT • • •
Virtual and physical memory • •
User virtual address mapping • • • •
Normal programs and virtual programs
Extended memory regions •
Shared run-time systems • •
Access to system I/O page • •
VM memory based pseudo-disk

141
141
142
143
143
144
145
145

Chapter 9
SHARED FILE RECORD LOCKING • •
Opening a shared file • •
Saving the status of a shared file channel • • • •
Waiting for a locked block
Trying to lock a block
• • • •
Unlocking a specific block • • • • • •
Unlocking all locked blocks in a file
Checking for writes to a shared file • • • •
Data caching • • • • • • • • • • • •

147
147
151
154
156
158
159
159
160

Chapter 10
MESSAGE COMMUNICATION FACILITIES
Message channels • • • • • • • • • • • •
Sending a message • • • • •
Checking for pending messages • • • • • • • •
Waiting for a message • • • • •

163
163
163
165
166

Chapter 11
REAL-TIME PROGRAM SUPPORT • • • • ••
•••••• • •
Accessing the I/O page • • • • • • • • • • • • • • • • • •
EMT to map the I/O page into the program •
••••
EMT to remap the program region to RMON
EMT to peek at the I/O page •• • • • •
EMT to poke into the I/O page • • • • • • • • • • • •
EMT to bit-set a value into the I/O page •
EMT to hit-clear a value into the I/O page • •
Mapping to a physical memory region
Requesting exclusive system control • • • • • • • •
Locking a job in memory • • • • • • •
Unlocking a job from memory • • • •
• • • • • • • • ••
Suspending/Resuming program execution
Converting a virtual address to a physical address
Specifying a program-abort device reset list • • • •
Setting processor priority level •• • • • • • • •
vi

169
169
170
172
172
174
175
177
178
180
182
183
183
184
185
186

Setting job execution priority •• • •
Connecting interrupts to real-time jobs •
Interrupt service routines • • •
Interrupt completion routines • • • • •
Releasing an interrupt connection ••
Scheduling a completion routine • •
Adapting real-time programs to TSX-Plus

186
188
191
196
200
201
202

Chapter 12
SHARED RUN-TIME SYSTEM SUPPORT • • • • •
Associating a run-time system with a job
Mapping a run-time system into a job's region •

203
203
205

Chapter 13
PERFORMANCE MONITOR FEATURE
Starting a performance analysis • •
Displaying the results of the analysis
Performance monitor control EMT's • • •
Initializing a performance analysis
Starting a performance analysis • • • •
Stopping a performance analysis • • • •
Terminating a performance analysis •

207
207
208
209
213
213
213

Chapter 14
TSX-Plus RESTRICTIONS
System service call (EMT) differences
Programs not supported by TSX-Plus • • • •

215
215
217

Appendix A
SETSIZ PROGRAM • • • • • • •
Running the SETSIZ program • • • •
Setting total allocation for a SAY file • • • • • • • • ••
Setting amount of dynamic memory space
Setting virtual-image flag in SAY file • • • •
Appendix B

vii

219
220
221
221
221

DIBOL TSX-PLUS SUPPORT SUBROUTINES •
Record locking subroutines
Opening a shared file
Locking and reading a record •
Writing a record • • •
• • • •
Unlocking records
• • • •
Closing a shared file
Record locking example • • • • • •
Modifying programs for TSX-Plus
Message communication subroutines •
Message channels • • • • • • •
Sending a message • • • • • • •
Checking for pending messages
Waiting for a message
Message examples •
Using the subroutines • • •
Miscellaneous functions • •
Determining the TSX-Plus line number •

223
223
223
224
225
226
226
226
226
226
226
227
228
228
229
229
229
229

Appendix C
FILTIM PROGRAM • • • • • • •

231
Appendix D

RT-11 & TSX-Plus EMT CODES
RT-11 EMT codes ••
TSX-Plus EMT codes

233
233
235
Appendix E

SUBROUTINES USED IN EXAMPLE PROGRAMS •
PRTOCT - Print an octal value •
PRTDEC - Print a decimal value
PRTDE2 - Print a 2 digit decimal value
PRTR50 - Print a RAD50 word at the terminal
DSPDAT - Print a date value at the terminal
DSPTI3 - Display a 3-second format time value
ACRTI3 - Convert a time value to special 3-second format

237
237
237
238
239
239
241
241

Appendix F
TSX-Plus USER ERROR MESSAGES

245
Appendix G

LOGICAL SUBSET DISKS • • • •

253

viii

Appendix H

JOB EXECUTION PRIORITIES • •

255

INTRODUCTION
TSX-Plus is a high-performance operating system for Digital Equipment Corporation PDP-II and LSI-II computers supporting up to 31 concurrent time-sharing
users. TSX-Plus provides a multi-user programming environment that is similar
to extended-memory (XM) RT-11.
1.

TSX-Plus keyboard commands are compatible with those of RT-11.

TSX-Plus supports most RT-11 system service calls (EMTs).

Most programs that run under RT-11 will run without modification
under TSX-Plus.
This includes RT-11 utility programs such as PIP,
DUP, DIR, LINK, and MACRO.

TSX-Plus uses RT-11 XM version device handlers.

TSX-Plus provides PLAS extended memory services such as virtual
overlays and virtual arrays, as well as support for extended memory
regions.

TSX-Plus can simultaneously support a wide variety of jobs and programming
languages including COBOL-Plus, FORTRAN, BASIC, DIBOL, DBL, Pascal, C, MACRO,
TECO and KED.
TSX-Plus is used in educational, business, scientific and
industrial environments.
It can concurrently support commercial users doing
transaction processing, engineering users performing scientific processing,
system programmers doing program development, and real-time process control.
Numerous application software packages compatible with TSX-Plus are available
from other vendors.
TSX-Plus supports RT-11 system service calls (EMTs) as its basic mode of
operation.
The result is low system overhead and substantially improved
performance over systems that emulate RT-11 services.
TSX-Plus overlaps
terminal interaction time, I/O wait time, and CPU execution time for all jobs
on the system. The result is a tremendous in~rease in the productivity of the
computer system.
In addition to the basic RT-11 functionality, TSX-Plus provides extended
features such as: shared file record locking; inter-job message communication;
program performance monitoring; command file parameters; logon and usage
accounting; directory and data caching; multitasking; and system I/O buffering.
This manual describes all the features unique to TSX-Plus as well as any
differences from RT-11. Many of the special features of TSX-Plus are available
as EMTs available to the MACRO programmer. Access to these features from other
languages requires the appropriate subroutine interfacing.
TSX-Plus wi 11 run on any PDP-II or LS 1-11 computer wi th memory management
hardware and at least 128Kb of memory.
The system must also have a disk
suitable for program swapping (the swapping disk can be used for regular file
storage as well).
Time-sharing lines can be connected to the system through
DL-11 or DZ-11 communication devices.
Both hard-wired and dial-up lines are
supported by TSX-Plus.

-1-

Introduction
MANAGEMENT OF SYSTEM RESOURCES
Memory Management
TSX-Plus uses the memory management facilities of PDP-II computers to keep
several user jobs in memory simultaneously and switch rapidly among them.
TSX-Plus protects the system by preventing user jobs from halting the machine
or storing outside their program regions. TSX-Plus provides several ways to
control the amount of memory used by individual jobs. Programs may be allowed
to use up to 64Kb of memory and, if additional space is needed, may also use
extended memory regions, virtual overlays and virtual arrays.
The system
manager may enable job-swapping to accommodate more user jobs than can fit in
existing memory.
Execution Scheduling
TSX-Plus provides fast response to interactive jobs but minimizes job-swapping
by use of an efficient job-scheduling algorithm.
TSX-Plus permits job
scheduling on both an absolute priori ty basis and by a method based on job
states. .For most applications, the method based on job states is preferred.
The state-driven method provides the most transparent time-sharing scheduling,
suitable for interactive environments.
The absolute priority method always
runs the highest priority executable job, when not servicing interrupts,
regardless of that job's state. This state-free method is most suitable for an
environment in which several real-time jobs must be assigned absolute priorities. TSX-Plus permits both kinds of jobs to co-exist in the same system, with
interactive jobs being scheduled whenever higher priority state-free jobs are
not executing.
Job priorities may be assigned over a range of 0 to 127. The lowest priority
jobs, typically 0 to 19, are reserved for fixed priority jobs which can soak up
system idle time without disturbing interactive or real-time jobs. The medium
priority range, typically 20 to 79, is assigned to interactive jobs which are
scheduled according to a unique and efficient algorithm which makes timesharing nearly transparent to several users.
The highest priority range,
typically 80 to 127, is reserved for jobs which must execute according to a
rigid priori ty scheme such as might be found in a real-time environment. In
addition, real-time jobs may execute interrupt service routines at fork level
processing or schedule interrupt completion routines to run as fixed-highpriority jobs.
Job scheduling is controlled by several system parameters relating job
priorities, system timing and other events.
The TSX-Plus System Manager's
Guide includes a more complete description of job priority and scheduling.
Directory and Data Caching
TSX-Plus provides a mechanism to speed up direc tory operations by caching
device directories.
This reduces disk I/O necessary to open existing files.
Caching of file data is also possible to further improve system throughput.
The information kept in the cache buffers is managed according to a leastrecently-used algorithm.
Directory and data caching are discussed in the
System Manager's Guide.

-2-

Introduction
System Administrative Control
TSX-Plus allows the system manager to limi t access to the system through a
logon facility and to restrict user access to peripheral devices.
These
features are described in the TSX-Plus System Manager's Guide.

-3-

Introduction
SUMMARY OF CHAPTER CONTENTS
Starting Time-sharing Sessions
Chapter 1 of this manual describes the procedure for starting and stopping a
time-sharing session with TSX-Plus; the special functions of some controlcharacters; and use of the single line editor for correction of typing errors
in command lines or data entrv fields.
Keyboard Commands
TSX-Plus responds to keyboard commands that are simple and natural (PRINT, RUN,
COMPILE, TYPE, etc.).
TSX-Plus also provides user-definable commands, and
includes support for a menu driven command interface. Chapter 2 discusses
command interpretation sequence, user-defined commands, the menu interface and
lists all TSX-Plus keyboard commands.
It provides full descriptions of
commands unique to TSX-Plus, describes differences between TSX-Plus and RT-ll
commands, and lists the RT-ll commands which are not supported by TSX-Plus.
Many of the commands are identical to their RT-ll counterparts and the RT-ll
System User's Guide should be consulted for detailed descriptions.
Command Files
Frequently used sets of commands may be stored in a disk file and executed by
invoking the command file. Parameters may be passed to the command file and
interpreted as though they were included at designated places in the file.
This provides an alternative way for users to create their own commands.
Command files are described in Chapter 3.
Virtual Lines and Detached Jobs
TSX-Plus provides a facility known as "virtual lines" that allows one timesharing user to simultaneously control several programs from a single terminal.
The user may logically switch among the primary and virtual lines at any time.
When a program that is not currently connected to a time-sharing line writes
output to the terminal, the output is stored in a system buffer. When the
buffer is filled, the program is suspended until the user reattaches to the
program and accepts the queued output. Virtual lines are useful in situations
in which it is desirable to run a long "number crunching" job without tying up
a terminal.
Detached jobs are similar, but are not associated wi th any
terminal. Virtual lines and detached jobs are discussed in Chapter 4.
Printer Spooling System
TSX-Plus provides a convenient and powerful facility for automatic spooling of
output to line printers and other devices.
The spooler may simultaneously
drive several devices. If the line printer is spooled, then simply directing
output to device "LP" from a program causes the output to be spooled. A
spooled file may designate the name of a form on which it is to be printed.
When a form change is required, the spooled device is suspended and a message
is sent to the operator requesting the form. After mounting the new form, the
operator may print a form alignment file. Once a form is mounted, all files
requiring the form are printed wi thout further operator intervention.
The
operator may also lock a particular form on the printer, preventing automatic
form change requests.
Keyboard commands are provided to check the status of

-4-

Introduction
spooled devices, delete files from the output queue, and reprint the most
recent portion of the current file.
Files sent to a spooled device may be
released to the printer as data becomes available or held until the output file
is closed. The spooling system is discussed in Chapter 5.
Program Controlled Terminal Options
TSX-Plus allows the programmer to modify terminal handling characteristics
during program execution.
For example, a program may disable character
echoing, use single character activation, use high efficiency output mode,
enable lower case input, activate on field width, or disable automatic echoing
of line-feed after carriage-return. These terminal options may be selected
either by issuing the appropriate EMT request or by writing a special sequence
of two or three characters to the terminal. Chapter 6 discusses the use of
terminal options during program execution,
TSX-Plus EMTs
TSX-Plus supports most of the system service calls (EMTs) provided by RT-ll
and, in addition, provides many more to utilize the special features of
TSX-Plus. For example, EMTs are provided to determine the TSX-Plus line number
and the user name, to send messages to another time-sharing line, to check for
terminal input errors, and to check for activation characters. EMTs related to
specific features, such as detached jobs or real-time programming, are
described in the relevant chapters. The TSX-Plus EMTs which are not closely
related to features described elsewhere are discussed in Chapter 7.
User Memory Mapping
TSX-Plus supports the use of extended memory regions through EMT calls
compatible with those provided by the RT-ll XM monitor. This allows the use of
virtual overlays and FORTRAN virtual arrays. Users can also expand programs to
use the full 16-bit virtual address space. That is, by giving up access to the
I/O page and direct access to fixed offsets in RMON, a program may address a
full 64Kb. User control of extended memory and virtual job space is discussed
in Chapter 8.
Shared Files and Data Caching
TSX-Plus provides-a-lile sharing mechanism whereby several cooperating programs
may coordinate their access to common data files.
Programs may request
different levels of shared file access, and control shared access on a
record-by-record basis.
Two methods of data caching are also provided:
1)
general data ca~hing which is enabled when devices are MOUNTed; and 2) record
caching which is only available to shared files.
Directory caching is also
enabled by the MOUNT request.
This accelerates directory searching for file
LOOKUPs. The use of shared files and data caching is described in Chapter 9.
Inter-program Message Communication
TSX-Plus offers a message communication facility that allows running programs
to

exchange

messages.

Messages

are

transmitted

through

named

"message

channels
A program can queue messages on one or more message channels.
Receiving programs can test for the presence of messages on a named channel and
can suspend their execution until a message arrives. A message can be queued
II •

-5-

Introduction
for a program that will run at a later time.
in Chapter 10

The message facility is discussed

Real-time Support
TSX-Plus provides real-time program support services that allow multiple
real-time programs to run concurrently with normal time-sharing operations.
Real-time programs may optionally lock themselves in memory, direc tly access
the I/O page, redefine their memory mapping, and connect device interrupts to
subroutines within the program. Real-time support is discussed in Chapter 11.
Shared Run-time System Support
TSX-Plus allows one or more shared run-time systems to be mapped into the
address space of multiple TSX-Plus time-sharing jobs. This saves memory space
when multiple users are running the same types of programs (e.g., COBOL-Plus or
DBL) and can also be used in situations where programs wish to communicate
through a shared data region. Shared run-time systems are discussed in Chapter
12.
Performance Analysis Facility
TSX-Plus includes a performance analysis facility that can be used to monitor
the execution of a program and determine what percentage of the run time is
spent within certain program regions. When the performance analysis facility
is being used, TSX-Plus examines the program being monitored at each clock tick
(50 or 60 times per second) and notes the value of the program counter. On
completion of the analysis, the TSX-Plus performance reporting program can
produce a histogram of the time spent in various parts of the moni tored
program. Performance analysis is discussed in Chapter 13.
Differences from RT-11
Some inevitable differences exist between RT-11 and TSX-Plus.
Chapter 2
describes the additional keyboard commands provided by TSX-Plus, the minor
differences in some commands, and the RT-11 keyboard commands not supported by
TSX-Plus.
Some other differences between RT-11 and TSX-Plus may not be
obvious.
The FORMAT utility is not supported. A few system service calls
(EMTs) behave slightly differently in the two systems and some RT-11 EMTs are
not supported by TSX-Plus (notably those supporting multi-terminal operations).
These differences are detailed in Chapter 14.
Appendices
Appendix A describes the SETSIZ utility program which may be used to control
the amount of memory available to programs. Appendix B describes a library of
subroutines which are available to the DIBOL user to take advantage of some of
the special features of TSX-Plus.
Appendix C describes the FILTIM utility
which displays directory information about files, including the file creation
time. Appendix D provides a table of EMT function and subfunction codes, and
brief descriptions of both RT-11 and TSX-Plus EMTs; these are useful in
conjunction with the SET EMT TRACE command. Appendix E contains listings of
common subroutines called by the example programs throughout this manual.
Appendix F contains explanations of monitor error messages; fatal system error
messages are covered in the TSX-Plus System Manager's Guide.
Appendix G

-6-

Introduction
describes the commands and techniques used to work with logical subset disks.
Appendix H describes job execution priorities.

-7-

-8-

1. BASIC OPERATION
1.1 Logging ~
Each user communicates wi th the TSX-P1us system through a time-sharing line
(often referred to in this manual simply as a "line") e The system manager may
designate lines to automatically initiate time-sharing whenever the system is
started. Otherwise, lines are started by typing a carriage return or contro1-C
at the terminal. In either case, when each line is first started, a greeting
message will be displayed at the terminal.
The system manager may assign a start-up command file to be executed whenever a
time-sharing line is started. A start-up command file contains initialization
commands for a line. It can end by either starting execution of some program,
or by waiting for a system command. (The keyboard monitor prompt is a period.)
It is possible for a start-up command file to lock a program to a line so that
on termination of the program the line is automatically logged off and an
optional log-off command file is executed.
Typing contro1-C will not abort
start-up or log-off command files.
The system manager may also require "log on" authorization. In this case, the
system manager assigns each user a user name (and project,programmer number)
and password.
After the greeting message, the message "Logon please:"
is
printed.
The user responds by typing the user name (or project,programmer
number) followed by carriage return. TSX-P1us then requests the password. The
password is not echoed to the terminal as it is typed. After the user name (or
project, programmer number) and password are validated, TSX-P1us types the
message "Welcome to the system".
The system manager may also designate a
"start-up" command file for each account to control system access and set
certain operating parameters.
The following example illustrates a typical log-on sequence.
typed by the user is underlined.

The information

(carriage return pressed)

(

)

(greeting message)

(
23-Jan-84
Line 112

)
13:39:50

Logon p1ease:JOHNSON
Password:MYPASS
Welcome to the system

(Password is not displayed.)

(TSX-P1us is now waiting for a system command.)
A user may adopt a new password while logging on. To do this, enter a slash
and the new password immediately after typing the old password.
The new
password must then be used for future 10gons. Passwords may be from 1 to 7
characters in length and must be composed only of letters and digits.
The
following example shows the password being changed from "OLDP" to "NEWP". Note
that neither the old nor the new password would actually be echoed.

-9-

Basic Operation
(carriage return pressed)

(

)

(greeting message)

(
20-Jun-83
Line 115

)
14:17:43

Logon please:107,24
Password:OLDP/NEWP
Welcome to the system

(Either user name or PPN may be used.)
(Passwords are not displayed.)

If the system manager has not required "log on" account authorization, then the
system will either execute a start-up command file or simply display the
monitor prompt (".") and wait for a system command to be entered.
1.2 Logging off
The OFF
session.

keyboard command is used

terminate

("log off")

time-sharing

The system manager may specify a "log off" command file to be executed whenever
a job logs off. Control-C will not abort a "log off" command file.

-10-

Basic Operation
1.3 Control characters
Certain control characters have special meaning to the system. These "control
characters" control certain terminal operations. They are entered by holding
down the "CTRL" key while pressing the selected character.
CTRL-C -

Interrupts the current program and returns control to the
keyboard monitor.
If the running program is not waiting for
input, two successive CTRL-C's are required to interrupt its
execution.
CTRL-C will not interrupt start-up or log-off
command files.

CTRL-O -

Suppresses program output to the
following conditions occurs:

terminal until one of

the

1) A second CTRL-O is typed
2) The program returns to the monitor
3) The running program issues a .RCTRLO EMT

CTRL-Q -

Resumes printing on the terminal from the point at which
printing was previously suspended by CTRL-S.
CTRL-Q has no
special effect if SET TT NOPAGE has been used.

CTRL-R -

C~uses the current characters in the terminal input buffer to be
displayed. This can be used to check the actual contents of an

input line when .rubou t editing has been done on the line.

CTRL-S

Temporar~.ly

suspends output to the terminal un"(~.1. 1.1KL-Q is
typed. CTRL-S has no special effect used if the SET TT NOPAGE
command has been issued.

CTRL-U -

Deletes the current input line.

CTRL-W -

Used to switch to a TSX-P1us virtual line.
more information on virtual lines.)

CTRL-Z -

Indicates end-of-fi1e when input is being read from device ItTT".

(See Chapter 4 for

The normal function of these keys may be altered during program execution.
Chapter 6 descriDes program controlled terminal options that influence these
functions.
When enabled, the single line editor defines additional special
purpose keys; see the next section for further information about the single
line editor.

-11-

Basic Operation
1.4 Single Line Editor
It is often desirable to correct typing mistakes made in the entry of command
input lines or to correct data entry fields while executing some program. This
can be done to a limited extent by use of the DELETE and Ctrl-U keys, however
much more editing capability is available if the "Single Line Editor" facility
is used.
To use the single line editor, the system manager must enable it
during the TSX-Plus system generation process. In addition, it must be turned
on for each time-sharing line before use. To use the single line editor, issue
the command:
SET SL ON
either in a start-up command file or as a keyboard command.
editor may be used only with VT100 or VT52 type terminals.

The single line

Several other SET options are available for use with the single line editor.
These are described in Chapter 2 in the section on keyboard commands.
The single line editor accepts special key commands to direct its operation.
Under TSX-Plus, there are two modes of operation of the single line edi tor:
normal mode (RT-11 compatible); and KED mode.
In normal mode, the TSX-Plus
single line editor is compatible with the RT-11 single line editor except for
the differences noted in the table at the end of this section. The following
tables summarize the functions performed by the editing control keys.

-12-

Basic Operation
Single Line Editor Key Functions
Normal (RT-11 compatible) Mode

+-------------------------------------------------------------------+
I
Primary Key Functions (Not prefixed by PF1)
I
+-------------+-----------------------------------------------------+
I
Key
I
Function
I
+-------------+-----------------------------------------------------+
Up arrow
Down arrow
Left arrow
Right arrow
BACK SPACE
DELETE
LINE FEED
RETURN
PF1
PF2
PF3
PF4
Ctrl-U
Ctrl-R

Retrieve previous input lines
Retrieve line from save buffer
Move cursor left one character
Move cursor right one character
Exchange char under cursor with char to right
Delete character to left of cursor
Delete word to left of cursor
Pass current line to running program
Used before other keys to perform second function
Not implemented
VT52: Delete from cursor to right end of line
VT100: Delete from cursor to right end of line
Delete from cursor to left end of line
Redisplay current line

+-------------+-----------------------------------------------------+
+-------------------------------------------------------------------+
Secondary Functions (Keys Prefixed by PF1)
+-------------+-----------------------------------------------------+
I
Key
I
Function
I
+-------------+-----------------------------------------------------+
I Up arrow
I Retrieve previous input lines (PF1 is ignored)
I

I Down arrow I Save current line in "save buffer" for recall later I
!
I Left arrow I Move cursor to left end of line
I Right arrow Move cursor to right end of line
I
! BACK SPACE
Exchange char under cursor with char to left
I
Retrieve last deleted character
I
I DELETE
I LINE FEED
Retrieve last deleted word
I
Truncate from cursor to end of line and execute
I
I RETURN
Ignored
I
I PF 1
Not implemented
I
I PF2
I PF3
VT52: Retrieve last deleted line
I
VT100: Retrieve last deleted line
I
I PF4
Retrieve last deleted line
I
I Ctrl-U

+-------------+-----------------------------------------------------+

-13-

Basic Operation
In addition to the normal (RT-ll compatible) mode of operation for the single
line editor, TSX-Plus also permits use of some of the keypad functions in a
fashion similar to KED (or K52).
These keypad operations are available in
addition to the functions described above for the single line editor. In order
to use the extended (KED) mode with the single line editor, issue the following
command:
SET SL KED
When the KED mode is enabled, the following
functions available to the single line editor.

tables describe the additional

Single Line Editor Key Functions
KED Mode

+-------------------------------------------------------------------+
I
Primary Key Functions (Not prefixed by PFl)
I
+-------------+-----------------------------------------------------+
I
Key
I
Function
I
+-------------+-----------------------------------------------------+
o
1
2
3
4
5
6
7
8
9

ENTER

Move cursor to left end of line
Move cursor one word in current direction
Move to end of line in current direction
VT100: Move cursor one char in current direction
Set direction forward (left to right)
Set direction backward (right to left)
VT52: Delete character under cursor
Not implemented
Not implemented
VT52: Delete word under cursor
VT100: Delete word under cursor
VT100: Delete character under cursor
Pass current line to running program

+-------------+-----------------------------------------------------+

-14-

Basic Operation

+-------------------------------------------------------------------+
I
Secondary Functions (Keys Prefixed by PFl)
I
+-------------+-----------------------------------------------------+
I
Key
I
Function
I
+-------------+-----------------------------------------------------+
I 0
I Delete from cursor to right end of line
I
I 1
I Change case of char under cursor
I
I 2
I Delete from cursor to right end of line
I
I 3
I Not implemented
I
I 4
I Move cursor to right end of line
I
I 5
I Move cursor to left end of line
I
I 6
I VT52: Retrieve last deleted character
I
I 7
I Not implemented
I
I 8
I Not implemented
I
I 9
I VT52: Retrieve last deleted word
I
I
I VT100: Retrieve last deleted word
I
I ,
I VT100: Retrieve last deleted character
I
! ENTER
I Truncate from cursor to end of line and execute
I
+-------------+-----------------------------------------------------+
To return the single line editor to the normal mode, issue the command:
SET SL NOKED
To disable the single line editor altogether, issue the command:
SET SL OFF
In addi tion to editing command lines, the single line editor may be used to
edi t data entry fields during program execution.
However, there are some
restrictions on such use. If any of the following conditions exist, then the
single line editor may NOT be used to edit program data fields:
1) The SET SL OFF command has been issued
2) Bit 4 (EDIT$, mask 20) is set in the Job Status Word (JSW)
3) Bit 12 (TTSPC$, mask 10000) is set in the JSW
4) The program is using hig'h-efficiency terminal mode

5) The program is using escape sequence activation
6) Input is being accepted via the .TTYIN EMT (except as below)

-15-

Basic Operation
In order to use the single line editor to edit data entry fields within
programs which accept input via the .TTYIN EMT, the following command must be
issued prior to execution of the program:
SET SL TTYIN
Since COBOL-Plus programs accept terminal input via the .TTYIN EMT, the
following steps must be used to edit data entry fields while executing
COBOL-Plus programs:
1) SET SL ON
2) SET SL TTYIN
3) From within the executing program, CALL "ESCAPE-OFF"
The TSX-Plus single line editor is generally compatible with that provided with
RT-11, with the following exceptions:
1)

The "Help" key (PF2) is not implemented.

The SET SL LEARN mode is not implemented.

The SET SL ASK option is ignored.
type information is used.)

The SET SL SYSGEN option is ignored.

The maximum width of a command line or input field that is accepted
is 80 characters. The SET SL WIDTH=n option is ignored.

The line feed key deletes the word to the left of the cursor.
Technically, characters to the left of the cursor are deleted until
one of the following delimiters is reached: space, tab, comma, or
equal sign.

The up arrow key can be used to retrieve either of the last two
lines. Pressing the up arrow key cycles between recalling the last
input line and the line prior to that.

Using the single line editor with .TTYIN input does not force a new
line.

The single line edi tor is implemented as a TSX-Plus overlay region
and does not require the SL pseudo-device handler.

-16-

(The current TSX-Plus terminal

2. KEYBOARD COMMANDS

2.1 Keyboard command interpretation
When a system command line is typed in, TSX-Plus attempts to interpret it by
sequentially applying the following rules:
1.

If the User Command Interface is in effect, then each time TSX-Plus
is ready to accept a keyboard command it passes control to the
current UCI program.
The UCI program may be selected with the SET
KMON UCI[=filnam] command.
See the description of SET KMON command
and the section in this chapter on the User Command Interface for
more information.

If the command line begins with an "at-sign" ("@"), TSX-Plus attempts
to execute a command file.
If no device is specified with the
command file name, device "DK:
is assumed.
The default extension
for command files is "COM".
If the SET KMON IND command has been
issued, command files will execute under the control of the IND
program.
Command files may be specified for execution as normal
command files, regardless of whether KMON is set IND or NOIND, by
starting the command with a dollar-sign (e.g. "$@filnam").
Conversely, command files can De rorced to execute under Lne LNU
utility, regardless of whether KMON is set IND or NOIND, by typing:
"IND filnam".
II

See Chapter 3 for
files by TSX-Plus.
3..

further information on the execution of command

If user-defined commands have been allowed during TSX-Plus generation, and if UCL is set FIRST either in TSGEN or subsequently by the
keyboard SET DeL FIRST command, then commands are checked at this
point to see if they are user-defined commands.
However, if the
first character on a command line is the underline character (" ")
then the command on that line is not checked to see if it is a
user-defined command.
See the next section for more information on

user-defined commands.
4.

TSX-Plus next attempts to identify a command as a standard system
command such as COPY, RUN, EXECUTE, etc. Commands may be abbreviated
to the minimum number of characters that uniquely specify the name.
Thus "COP" would be an acceptable abbreviation for COPY, but "CO"
would not because it could mean COpy or COMPILE.
"COPX" also would
not be identified as a system command.

If user-defined commands have been allowed during TSX-Plus generation, and if UCL is set MIDDLE either in TSGEN or subsequently by the
keyboard SET UCL MIDDLE command, then commands are checked at this
point to see if they are user-defined commands.
However, if the
first character on a command line is the underline charac ter ( .. ")
then the command on that line is not checked to see if it i s a
user-defined command.

-17-

Keyboard Commands
6.

If the command has not yet been identified, then TSX-Plus tries to
find a command file on device "DK:" that has the same name as the
command keyword. If no such command file is found on "DK:", TSX-Plus
looks for the command file on device "SY:".
In either case, if the
SET KMON IND keyboard command has been issued, it will be executed
under control of the IND program. When a command file is started in
this fashion (rather than explicitly specifying an at-sign before its
name), the command file listing is suppressed as if an implied "SET
TT QUIET" command was executed during command startup. This implied
listing suppression is temporary in effect and applies only to the
command file started in this fashion.
See Chapter 3 for more
information on command files.

If a command file. cannot be found, TSX-Plus looks for an executable
program (SAV file) on device "SY:"
that has the same name as the
command keyword.
If such a program is found, it is executed as if
there were an "R" command in front of the program name.
Note that
while both RT-11 and TSX-Plus allow a line of text input to be passed
to a program with the RUN command by specifying it after the program
name, TSX-Plus also allows this to be done wi th the "R" command and
with an implied "R" command line when the program name is specified
as the command keyword. See example 6 below.

If user-defined commands have been allowed during TSX-Plus generation, and if UCL is set LAST either in TSGEN or subsequently by the
keyboard SET UCL LAST command, then commands are checked to see if
they are user-defined commands at this point. However, if the first
character on a command line is the underline character ("_") then the
command on that line is not checked to see if it is a user-defined
command.

If a command has not been identified after all the above steps have
been tried, then it is reported as an unrecognizable command. The
error message is:
?KMON-F-Unrecognizable command

-18-

Keyboard Commands
The following list summarizes the sequence of events which occur in the
processing of keyboard commands
If a command can be recognized at any of
these steps, then the appropriate command is executed and the remaining steps
are skipped.
0

Call user command interface if one is active.
If command begins with "@", execute command file on DK:.
If DCL FIRST, check for user-defined command.
Check for system command.
If DCL MIDDLE, check for user-defined command.
Check for command file on DK:.
Check for command file on SY:.
Check for SAV file on SY:.
If DCL LAST, check for user-defined command.
Report unrecognizable command.
If user-defined command support has not been included in TSGEN, or if the SET
DCL NONE command has been issued, or if a command line begins with the
underscore character (;; "), then the command interpreter never attempts to
interpret a command as
user-defined command. Attempts to issue user-defined
commands under these conditions will also be reported as unrecognizable
commands.

Examples:
1.

Execute the command file

"TYV. DTTDf"'l<'

f"'AM"

V.I."'_.L U.1.'\.U,U. \".IVl.:.1

•

• @PURGE
2.

Run a program named "DUMP" on device "SY:" •
• R DUMP

Run a program named "PAYROL" on device "DX1:" •
• RDN DX1: PAYROL

List all files on "RK1:"
.DIR RK1:

Start a command file "SY:LOADIT.COM" and pass it the parameter string
"PROG2" •
• LOADIT PROG2

Execute the program
"A. TMP=B. TMP" •

"SY:PIP.SAV"

• PIP A.TMP=B.TMP
-19-

and

pass

the

input

line

Keyboard Commands
2.2 User-defined Commands
It is possible to define your own keyboard commands in terms of system commands
and other keyboard commands. New keyboard commands may be defined according to
the following syntax:
name :== string
where "name" is a 1 to 11 character command keyword which may consist of
letters, digits, and the underscore symbol ( .. "), and "string" is a string of
up to 80 characters which defines the body of the command.
For example, the following command would define the keyword "NOW" as being
equivalent to the TIME command:
NOW :== TIME
Multiple commands may be included in the body of a command definition by
separating them with the backslash character ("\"). For example:
NOW :== DATE\TIME
An up-arrow character ( ........ ) may be included in the command body to cause all
text on the command line following the command keyword to be inserted in the
command body at the posi tion of the up-arrow. For example, if a command is
defined as follows:
NAMES :== DIR/ORDER:NAME . .
Then, if this command is invoked by typing:
NAMES *.MAC
The resulting command will be equivalent to:
DIR/ORDER:NAME *.MAC
More than one up-arrow character may occur in the command body. The parameter
string specified when the command is invoked is substituted for each occurrence
of the u~-arrow character.
A user defined command may invoke other user-defined commands within its
definition provided that the definition does not calIon itself and provided
that the other commands are defined at the time the command is issued. For
example, the following command definitions would be legal:
NOW :== SHOW DATE\SHOW TIME
STATUS :== NOW\SYSTAT

-20-

Keyboard Commands
But, the following pair of commands would cause an infinite loop:
ONE :== TWO
TWO :== ONE
It is possible to allow abbreviation of user-defined commands.
To do this,
place an asterisk character ("*") within the keyword at the point of the
minimum length abbreviation. For example, the definition:
ST*ATUS :== NOW\SYSTAT
Would allow the STATUS command to be abbreviated to "STAT" or "ST" but not to
"S".
You can specify the order in which the TSX-Plus command interpreter checks for
user-defined commands by use of the SET UCL command. This command has four
forms:
SET UCL FIRST

SET UCL MIDDLE
SET UCL LAST
SET UCL NONE
If the SET UCL FIRST command is used, user-defined commands will be processed
before system commands.
This allows user-defined commands to replace system
commands

but makes

the

processing

system commands

slower.

This is the

required setting only if it is necessary to replace some system commands.
If the SET UCL MIDDLE command is used, user-defined commands aTe processed
after system commands but before checking for command files and SAV files with
names that match the command keyword. Using this setting, it is not possible
to replace a system command with a user command, but both system commands and
uSer-defined

commands

are processed relatively quickly.

This is the recom-

mended setting unless it is desirable to replace system commands.
If the SET UCL LAST command is used, a command will not be checked to see if it
is a user-defined command until after it is checked to see if it is a system
command, the name of a command file on DK, the name of a command file on SY, or
the name of a SAV file on SY.
Using this setting, it is not possible to
replace a system command with a user command and user commands cannot have the
same name as command files or SAV files. System commands are processed quickly
(the same speed as SET UCL MIDDLE), but the processing of user-defined commands
is slow.
This is the appropriate setting only if user-defined commands are
desired, but command files already exist whose names would conflict wi th
user-defined commands.
Existing command files which are short and merely
execute system commands should be replaced by user-defined commands.
If the SET UCL NONE command is used, user defined commands are never interpreted. In this mode, attempts to invoke user-defined commands will result in
the error:

-21-

Keyboard Commands
?KMON-F-Unrecognizable command
The following list illustrates where the FIRST/MIDDLE/LAST setting causes the
command interpreter to check for and process user-defined commands:
FIRST

--)

MIDDLE

--)

See if command is a system command
Look for command file on DK: with command name
Look for command file on SY: with command name
Look for SAV file on SY: with command name
LAST

--)

See the beginning of this chapter for
interpretation process.

further

information on the command

If an underscore character ("_") is typed in front of a keyboard command, this
is a signal to the system that the command is not to be interpreted as a
user-defined command.
For example, if the NOW command has been defined as
shown above, then the following command will be recognized as a user-defined
command and will cause the date and time to be displayed:
NOW
However, the following command would not be recognized as a user-defined
command and would be rejected as an undefined command since there is no NOW
command defined by the system (unless there is a command file or SAV file on
SY: with the name NOW):
NOW
There are two reasons for using the underscore prefix. If UCL has been set
FIRST, the underscore prefix can be used to speed up the processing of large
numbers of system commands that could be present in frequently executed command
files. For example, the NOW command could be defined as follows to cause it to
execute faster:
NOW

:==

DATE\ TIME

The second and more important reason for using the underscore prefix is to
allow user-defined commands to be defined which replace system commands but use
the system commands in their definitions. (Note that it is necessary to SET
UCL FIRST to allow system command replacement.) For example, the following
defini tion replaces the system DIRECTORY command wi th a user-defined command
that has the same name but which always orders the files alphabetically:
DIR*ECTORY

:==

DIR/ORDER:NAME ~

-22-

Keyboard Commands
If the body of this command were not preceded with the underscore character,
then it would be a circular definition and cause a futile loop.
A user-defined command can cause a command file to be executed. However the
command file invocation must be the last (or only) command defined within the
body of the command.
For example, the following definition causes all BAK
files to be deleted, and a command file named LOGOFF to be executed when the
OFF command is used (the LOGOFF command file could end with an " OFF" command
to do the actual logoff):
OFF :==

DEL *.BAK/NOQ\@LOGOFF

A user-defined command may be replaced at any time by simply entering a new
definition for the command. A command may be deleted by entering its name and
":==" wi thout a command body.
For example, the following command deletes the
definition of the NOW command:
NOW :==
The SHOW COMMANDS keyboard command may be used to display a list of all current
user-defined commands.
Commands defined by one time-sharing user are "local" to that user and do not
affect other users. However, when a virtual line is started the virtual line
"inherits" the user-defined commands that are in effect for the primary line at
the time that the virtual line is started. User-defined commands created while
on a

virtu.al

line are

not available

from

other

virtual lines or from the

primary line. All user-defined commands for a job are reset (forgotten) when
the job logs off.
The system manager must enable user-defined commands by setting the U$CL flag
in TSGEN and the program TSXUCL.SAV must be on SY:
in order to process
user-defined commands. The maximum number of commands which can be defined by
any job is set by the UCLMNC command in TSGEN. The default order for interpretation of user-defined commands during command processing is determined by
the TSGEN parameter UCLORD. This may be overridden by the keyboard command SET
UCL {FIRSTI}UDDLEILAST!NONE} for individual jobs.

-23-

Keyboard Commands
2.3 User Command Interface
The User Command Interface (UCI) allows a user-provided program to take over
the job of command acquisition from the TSX-Plus keyboard monitor. When UCI is
enabled, the user-written program will be called by the TSX-Plus keyboard
monitor each time it is ready to accept a new command.
It is then the
responsibility of the user-written program to prompt for a command and accept
it from the terminal.
The program may then perform the appropriate actions,
chain to other programs or pass commands on to the keyboard moni tor.
This
provides a mechanism for such applications as a command menu.
UCI is enabled with the command:
SET KMON UCI[=filnam]
which may be entered either from the keyboard or in a start-up command file.
If the optional "=filnam" is omitted, then the keyboard monitor passes command
control to the program SY:UKMON.SAV. This is appropriate when a common command
interface is desired for multiple lines. If different command interfaces are
desired for different lines, then the file name of the appropriate user-written
command interface may be specified.
After UCI is enabled, the TSX-Plus keyboard monitor will run the user-written
UCI program each time it needs a new command. The program must prompt the user
for a new command, accept the command, process it as desired and may optionally
pass the command to the TSX-Plus keyboard moni tor by doing a "special chain
exit". A special chain exit is performed by issuing the .EXIT request with bit
5 (mask 40) set in the job status word and with RO cleared. Any commands to be
executed by the keyboard monitor are passed through the chain data area. See
the RT-ll Programmer . . s Reference Manual for more information on "special chain
exits".
Commands passed to the TSX-Plus keyboard monitor in this fashion
behave as though the keyboard moni tor obtained them from a command file. A
command file name may also be passed to the keyboard moni tor by passing a
command of the form "@name". If a command file name is passed to the keyboard
monitor, then it must be the last or only command passed in the chain data
area.
When a command file name is passed in this manner, then all of the
commands included in the command file are executed by the keyboard monitor
before returning to the user-written UCI program for another command.
Keyboard command control may be returned to the TSX-Plus keyboard monitor by
the command:
SET KMON SYSTEM
The following program provides a simple example of the techniques for writing a
User Command Interface program.
This program accepts a command from the
keyboard and passes it through to the TSX-Plus keyboard moni tor if it is a
legal command.

-24-

Keyboard Commands
Example:
.TITLE
.ENABL

MYKMON
LC

Simple example of User Command Interface
Refuses to pass SET KMON SYSTEM, but otherwise does nothing but
pass commands thru to KMON •
•MCALL
JSW
SPXIT$
MONPTR
SYSGEN

BEL
BS

.PRINT,.EXIT,.GTLIN,.SCCA
;Job status word address
;Special exit flag to pass command to KMON
;Pointer to base of RMON
;Offset into RMON of SYSGEN options word

40
54

372

;ASCII bell
;ASCII backspace
;ASCII line feed
;ASCII form feed
;ASCII carriage return
;ASCII escape

10
12
14
15
33

FF
CR
ESC
START:

;Disable undefined globals
•DSABL GBL
.SCCA
IIAREA,IITTSTAT
;Inhibit control-C abort
;Get pointer to base of R}10N
@/IMONPTR,RO
MOV
TST
SYSGEN(RO)
;Are we running under TSX?
;Normal exit if not
QUIT
BPL
MOV
IITTYPE,RO
;Point to EMT arg block to
;Get TSX-Plus terminal type
375
EMT
RO
;Convert to word offset
ASL
;Legal types are unknown, VT52 and VT100
CMP
RO,1I4
lC
BLOS
....
CLR
RO
;If not VT52 or VT100, make unknown
;Save terminal type
RO,Rl
MOV
• PRINT CLRSCR(Rl)
;Clear the screen
;Display
simple menu
{IMENU
• PRINT
{/SETRUB ,RO
MOV
;Point to EMT arg block to
;Set rubout filler character
375
EMT
• PRINT CENTER(Rl)
;Move to screen center and clear the line
.GTLIN IIBUFFER, {IPROMPT ;Accept input line
;See if it's legal
CALL
MATCH
;Repeat if illegal command
BCS
2$
{11000, SP
MOV
;Ensure stack pointer safe
;Move command from buffer to chain data area
CALL
MOVCMD
ftSPXIT$, @f.fJSW
BIS
;Set special chain exit bit ~n JSW
RO
;Required for special chain exit
CLR
.EXIT
;And pass command to KMON
~

1$:

2$:

QUIT:

Simple matching. Easy to defeat by inserting extra spaces!!!
-25-

Keyboard Commands
MATCH:
1$:

2$:
9$:
10$:

MOV
MOV
TSTB
BEQ
CMPB
BNE
CMP
BLO
SEC
BR
CLC
RETURN

IIBUFFER,R2
IIILLCMD, R3
(R2)
2$
(R2)+, (R3)+
9$
R3,IIILLEND
1$

;Point to beginning of input buffer
jPoint to beginning of illegal command
jAt end of input string?
jYes, matched so far, probably illegal
jNo, test through end of illegal string
;No match, not illegal command
;Past end of illegal command?
;No, keep checking
;Strings match, signal illegal command

10$
;Strings don't match, signal legal command

Move command from input buffer to chain data area.
MOVCMD: MOV
MOV
1$:
MOVB
BNE
CLRB
BR
2$:
CMPB
BNE
CLRB
3$:
MOVB
CMP
BLO
CLRB
9$:
SUB
MOV
RETURN
AREA:
TTSTAT:
TTYPE:
SETRUB:
CLRSCR:
CENTER:
CLRUNK:
CLR52:
CLRI00:
CNTUNK:
CNT52:
CNTI00:

.BLKW
.WORD
• BYTE
.BYTE
•WORD
• WOR.D
.WORD
.WORD
.NLIST
.BYTE
• BYTE
.ASCII
.ASCII
.ASCII
.ASCII
.ASCII
.ASCII

IIBUFFER, R2

11512,R3
(R2)+,RO
2$
(R3)+
9$
RO,II'\
3$
RO
RO, (R3)+
R2 , liB UFEND
1$
-1(R3)

11512,R3
R3, @11510

;Point to beginning of input string
;Point to chain data area
;Get next char
;Continue if not nul
;If end of input command
; then done
;Command separator?
;No, move it
;Yes, replace with nul
;Move command into chain data area
jDon't want to overflow
jKeep moving if characters left
jMark end of command (ensure it is ASCIZ)
jHow many bytes did we move?
;Mark the number for .CHAIN

jGP EMT argument area
;Terminal status word for .SCCA
0,137
;EMT arg block to get terminal type
jEMT arg block to control terminal funtions
0,152
;Function code - set rubout filler
A
jRubout filler = underline
CLRUNK,CLR52,CLRI00
jTerminal specific screen clears
CNTUNK,CNT52,CNTI00
;Terminal specific move and clear
BEX
FF,FF,FF,CR,200
;Emulate clear screen with 3*(8LFs)
ESC,'H,ESC,'J,200
;VT52 clear screen sequence
<ESC>/[H/<ESC>/[J/<200> jVTI00 clear screen sequence

<CR><LF><LF><LF>I
<Esc>/Y% 1
<ESC>/KI
1
1<200>
<ESC>/[6;6fl

1<200>
;Line 6, column 1
;Erase to end of line
;Move to column 6
;Line 6, column 6
-26-

Keyboard Commands
.ASCII
.ASCII
PROMPT: .ASCII
.NLIST
.REPT
• BYTE
.ENDR
.LIST
• BYTE
ILLCMD: .ASCII
ILLEND:
BUFFER: • BLKB
BUFEND:
.END

MENU:

<ESC> 1 [2KI <200) ;Erase entire line
<LF><LF><LF>!
Simple Menu
*****
<BEL>/Command:

*****1<200)

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

32.
BS

;Backspace to beginning of field

<200>
ISET KMON SYSTEMI

;End of string
;Don't permit UCI disable

81.

;Command line input buffer

START

-27-

Keyboard Commands
2.4 Keyboard Commands
The keyboard commands accepted by TSX-Plus are listed below. Because many
commands are identical or very similar to those of RT-11, full descriptions are
only provided for TSX-Plus specific commands and for differences between
TSX-Plus and RT-11 commands.
Users should consult the RT-11 System User's
Guide for more information on keyboard commands.

The ACCESS Command
The ACCESS command is used to restrict user access to a particular set of files
or devices. It is only valid in start-up command files. Refer to the TSX-Plus
System Manager's Guide for further information about this command.

The ASSIGN Command
The ASSIGN command is used to associate a logical I/O device name wi th a
physical device. To simply assign a logical device name to a physical device,
the form of the ASSIGN command is the same as that under RT-11. For example,
to assign the logical device name "BIN" to physical device "DX1" the command
would be:
ASSIGN DX1 BIN
The following command would assign logical device "BIN" to a file named "PROG1"
on the system device:
ASSIGN SY:PROG1=BIN
It is also possible under TSX-Plus to assign a new logical name to a previously
assigned logical name.
The effect is to assign the new logical name to the
same physical device to which the previous assign was directed. For example,
the following sequence of ASSIGNs result in both logical devices "AA" and "BB"
being assigned to "DL1".
ASSIGN DL1 AA
ASSIGN A..~ BB
The ASSIGN command is frequently used to assign FORTRAN I/O uni t numbers to
selected devices.
To assign FORTRAN I/O unit number 1 to the terminal, the
command would be:
ASSIGN TT 1
The TSX-Plus ASSIGN command provides a useful extension. In addition to being
able to specify a physical device name, the user may specify a file name,
extension, and size.
If a file name and optional size are specified in
addition to the physical device name, the file name and size follow the device

-28-

Keyboard Commands
name.
For example, the following command assigns FORTRAN I/O unit number 1 to
a file named "PAYROL" on device "DXO" with a size of 43 blocks:
ASSIGN DXO:PAYROL[43]=1
A maximum of fifteen assignments may be in effect at any given time for each
user.

The BACKUP Command
The TSX--Plus BACKUP command has the same form and options as the RT-ll BACKUP
command.

The BOOT Command
-------The BOOT command

attempts to abort TSX-Plus and reboot RT-ll.
Due to the
variations in hardware and bootstrap ROMs, this command is unsupported.
The
BOOT command may either reboot RT-ll on your system or simply halt depending on
your particular hardware configuration.
Unlike the RT-ll BOOT command, no
device or file name may be specified wi th the TSX-Plus boot command; BOOT
always attempts to reboot from the system (SY) device.
Operator command
privilege is required to use this command. The BOOT command is equivalent to
the $STOP command.

The BYE Command
-------

The BYE command is used to log off a timesharing line.
OFF command.

It is equivalent to the

The COBOL Command
The COBOL command is used to compile a COBOL source program using the COBOLPlus compiler.
COBOL-Plus, a product of S&H Computer Systems, Inc., is sold
separately.
The defaul t extension for COBOL source programs is "CBL"; the
default extension for COBOL object files is "CBJ".
The COMPILE, LINK and
EXECUTE commands may also be used to compile and execute COBOL programs.
TSX-Plus will implicitly invoke the COBOL-Plus compiler and CBLINK link program
if the source program has the extension "CBL" or the object program has the
extension "CBJ".
Swi tches that can be used with the COBOL command are listed
below.

-29-

Keyboard Commands
Switch

Meaning

/ALLOCATE:size
/ANSI
/CARD
/CREF
/CROSS
/DCARDS
/INFORMATION
/LINENUMBER
/LIST [: name]

Specify size of list or object file.
Produce warning messages for non-ANSI feature use.
Source program is in card sequence format.
(Equivalent to /CROSS).
Produce a cross-reference of the source program.
Compile lines with "D" in the indicator field.
Print additional information at compilation end.
Enable source line information in object listing.
Produce a source program listing.
Format the cross-reference for 80 column display.
Specify name of object file.
Compile the program for use with the debugger.
Omit line number tracing and subscript checking.
Compile RM/COBOL(*) programs.
(Equivalent to /CARD).
Print only error messages on listing device.
Suppress warning messages.

/NARROW

/OBJECT [ : name]
/ONDEBUG
/PRODUCTION

/RM
/SEQUENCE
/SUMMARY

/WARN

See the COBOL-Plus reference manual for further information about the COBOL
command.
* RM/COBOL is a trademark of Ryan-McFarland Corporation.

The COMPILE Command
The COMPILE command invokes the appropriate language processor to compile the
specified source file. The TSX-Plus COMPILE command is the same as the RT-ll
COMPILE command except that it also recognizes programs wi th the extension
"CBL" as COBOL source programs and calls the COBOL-Plus compiler.
When
compiling a COBOL program, the switches that are legal with the COBOL command
may also be used with the COMPILE command. It is also possible to explicitly
specify that the COBOL-Plus compiler is to be called by using the "/COBOL"
switch with the COMPILE command.
The default compiler for files with the
extension "DBL" is DBL; this may be changed with the SET LANGUAGE command.

The COpy Command
----The TSX-Plus COpy command has the same form and options as the RT-ll COPY
command.

The CREATE Command
The TSX-Plus CREATE command has the same form and options as the RT-ll CREATE
command.

-30-

Keyboard Commands
The DATE Command
The TSX-Plus DATE command has the same form and options as the RT-ll DATE
command. Operator privilege is required to set the date.

The DEASS IGN Command
The TSX-Plus DEASSIGN command is equivalent to the RT-11 DEASSIGN command.
is used to dissociate a logical unit assignment.

The DELETE Command
The TSX-Plus DELETE command has the same form and options as the RT-11 DELETE
command.

The DETACH Command
The DETACH command is used to initiate execution of a command file as a
"detached" job, to abort a detached job or to check the status of a detached
job. The system manager may restrict the use of this command.
The form of the command used to start a detached job is:

DETACH file
where "file" is the name of a command file which is to be started as a detached
job. If a free detached-job line is available, the system starts, the command
file and prints a message indicating the detached job line number used.
Detached-job lines must be declared when TSX-Plus is generated.
The DETACH
command itself and detached command files do not inherit any logical device
assignments. If no device name is specified in the DETACH command, the command
file is assumed to be on the system device (SY:).
In the following example a command file named "CRUNCH" is started as a detached
job.
• DETACH CRUNCH
Job started on line #5
If the specified command file is not found, the start message will still
appear, but the job is not actually started. Any error message would have been
sent to the detached line, but is ignored since terminal output is not sent to
detached jobs. With no input, the detached job then aborts. The result is
that the detached job is not started and no warning appears.
Terminal output for detached jobs is normally discarded since they are not
attached to any terminal.
However, it is possible to collect the terminal
OULPUt from a detached job by sending it to a log file. This can be done by
-31-

Keyboard Commands
using the SET LOG FILE=filnam command in the detached job command file.
the SET LOG command for more information on terminal output logging.

See

The form of the DETACH command used to abort a detached job is:
DETACH/KILL line-number
where "line-number" is the number of the line assigned to the detached job.
The form of the DETACH command used to check the status of a detached job line
is:
DETACH/CHECK line-number
In response to this command, TSX-Plus will indicate whether a job is still
executing on the line.
See Chapter 4 for more information about detached jobs.

The DIBOL Command
The DIBOL command is used to compfle a DIBOL source program. The defaul t
compiler for programs with the extension "DBL" is DBL. This may be changed
with the SET LANGUAGE command. The TSX-Plus DIBOL command has the same form
and options as the RT-ll DIBOL command, except that the options /BUFFERING,
/LOG, /PAGE and /TABLES are not supported. Because of differences between
compiler switch options, DIBOL switches are not supported for use with DBL.

The DIFFERENCES Command
The DIFFERENCES command is used to compare two files. The TSX-Plus DIFFERENCES
command has the same form and options as the RT-ll DIFFERENCES command.

The DIRECTORY Command
The TSX-Plus DIRECTORY command has
DIRECTORY command.

the

-32-

same form and options as the RT-ll

Keyboard Commands
The DISMOUNT Command
The DISMOUNT command has three functions:
1) it tells TSX-Plus to stop
directory caching on a particular device; 2) it tells the system to stop doing
data caching on a device; 3) it dissociates a logical subset disk from its
assigned file. The form of the DISMOUNT command is:
DISMOUNT ddn
where "ddn" is the real or logically assigned name of the device.
If the device is a physical device or a logical name for a physical device,
then the DISMOUNT command removes the current job's entry from the m~unt table
for that device. If no other jobs have mounted the device, then directory and
data caching for that device are stopped. Files on a physical device may still
be accessed after it is DISMOUNTed, but access may be slower since the
directory is no longer cached. Note however, that if a job accesses a device
which it has not mounted, and another user INITIALIZEs or SQUEEZEs that device,
then reads will probably return garbage and writes will probably corrupt other
files. ALWAYS MOUNT A~nl DIRECTORY STRUCTu~D DEVICE WHICH YOU INTEND TO USE!
The INITIALIZE and SQUEEZE operations cannot be performed on a device which is
mounted by other users. If it is necessary to INITIALIZE or SQUEEZE a device
which is mounted by other users, then they must first DISMOUNT that device.
Remember that it is possible for a job which has not mounted a device to still
access that device.
After a device is INITIALIZEd or SQUEEZEd, then the
directory and

data caches· are

cleared

for

that

device

and if it is still

mounted, then caching is resumed.
Caching is not resumed if all jobs have
DISMOUNTed a device until some job reMOUNTs that device.
The following
information message is printed if a device is dismounted and the device is
still mounted by other users:
?KMON-I-Device is still mounted by other users
The SHOW MOUNTS command may be used
mounted.

to determine which

jobs have devices

In the case of logical subset disk assignments ("ddn" = LDO-LD7 or logical
names assigned to them), the effect of the DISMOUNT command is to stop
directory caching on the logical subset disk as described above and to remove
the device from the logical subset disk tables. In this case, files on the
logical subset disk are no longer accessible until the logical subset disk is
re-mounted.
This form of the command only affects the logical subset disks
belonging to the user who issues the command. If another job has mounted the
same logical subset disk, then the rules for physical devices with regard to
INITIALIZE and SQUEEZE also apply to the logical subset disk.

-33-

Keyboord Commands
The DISPLAY Command
The DISPLAY command is used wi thin a command file or user-defined command to
cause a line of text to be displayed on the terminal when the command is
executed.
This is useful in command files that are not being listed to keep
track of progress through the command file.
The form of the DISPLAY command
is:
DISPLAY comments
where "comments" can be any text string to be displayed on the terminal. See
the section on user-defined commands in this chapter and Chapter 3 for more
information on command files.

The DUMP Command
The TSX-Plus DUMP command has the same form and options as the RT-ll DUMP
command.

The EDIT Command
The TSX-Plus EDIT command
command.

has the same form and options as the RT-ll EDIT

The EXECUTE Command
The TSX-Plus EXECUTE command has the same form and options as the RT-ll EXECUTE
command.
It also recognizes programs with the extension "CBL" as COBOL source
programs and automatically invokes the COBOL-Plus compiler and linker.
Switches appropriate when using the COBOL-Plus compiler and linker are also
valid with EXECUTE.
See also the COBOL, COMPILE, DIBOL, FORTRAN, LINK and
MACRO commands.

The FORM Command
The FORM command is used to specify the default form name for subsequent files
sent to the spooler by the user. The form of the FORM command is:
FORM name
where "name" is the one to six character default form name to be used
files sent to the spooler until another FORM command is issued.
The
default form name is "STD". A form may also be requested within a file
the spooler. See Chapter 5 for more information on spooled devices and

-34-

for all
initial
sent to
forms.

Keyboard Commands
In the following example a FORTRAN listing will be generated for printing on a
form called "2-PART" •
• FORM 2-PART
.COMPILE/LIST TEST.FOR
.FORM STD

The FORTRAN Command
The TSX-Plus FORTRAN command has the same form and options as the RT-ll FORTRAN
command.

The HELP Command
The TSX-Plus HELP command has the same form and options as the RT-ll HELP
command.

The INITIALIZE Command
The TSX-Plus INITIALIZE command has the same form and options as the RT-ll
INITIALIZE command. However, the system device (booted device when TSX-Plus is
started) may not be initialized when running TSX-Plus. If it is necessary to
initialize the system device, it must be done under RT-ll. The resulting error
message is:
?KMON-F-This operation not legal with SY (system) device
A device cannot be ini tialized if any other user has MOUNTed the device.
Attempts to INITIALIZE a device which is mounted by another user will result in
the error message:
?KMON-F-Device is mounted by another user
If the device is only mounted by the job which ini tializes it, then the
directory and data caches are cleared after the operation and caching is
resumed.
The SHOW MOUNTS command may be used to determine which other users
have mounted a device. However, remember that is still possible for a job
which has not mounted a device to access that device. If such a job has a file
open before you initialize, then severe problems can arise. Great circumspection is necessary before initializing a device in a multi-user environme~t.
Do not initialize rashly. As a defensive measure, always MOUNT any disk device
which you plan to use.

-35-

Keyboard Commands
If terminal output logging is being done (see the SET LOG command) and the log
file is open on the device being initialized, then the log file is closed
before the device is initialized and the following warning message appears:
?KMON-W-Closing log file

The KILL Command
The KILL command is used to abort a timesharing job on another line. This has
the effect of aborting the execution of the job and forcing the logoff of the
line. Operator command privilege is required to use the KILL command. The
form of this command is:
KILL line-number
where "line-number" is the number of the job to be killed.

The KJOB Command
The KJOB command is used to log off a timesharing line.
the OFF command.

It is equivalent to

The LIBRARY Command
The TSX-Plus LIBRARY command has the same form and options as the RT-Il LIBRARY
command. 'It also can be used to build COBOL-Plus object program libraries; see
the COBOL-Plus Reference Manual for further information.

The LINK Command
The TSX-Plus LINK command has the same form and options as the RT-II LINK
command.
It also recognizes object files with the extension "CBJ" as COBOLPlus object files and then invokes the COBOL-Plus link program (CBLINK). The
COBOL-Plus linker may also be explici tly specified with the "/COBOL" swi tch.
See the COBOL-Plus Reference Manual for further information. Swi tches which
are unique to COBOL Plus-are:
Swi tch

Meaning

/NOPAGE
/NOSHARED
/SHARED
/SIZE
/VM
/XM

Do not swap data segments.
Do not use shared COBOL-Plus run-time library.
Always use shared COBOL-Plus run-time library.
Report the size of the largest data segment.
Use VM for run-time and program segmentation.
Load entire program and run-time into extended memory.

-36-

Keyboard Commands
The MACRO Command
The TSX-Plus MACRO command has the same form and options as the RT-ll YlACRO
command.

The MAKE Command
The MAKE command is used to create a new file wi th the TECO edi tor.
equivalent to the RT-11 MAKE command.

It is

Tne MEMORY Command
The MEMORY command is useduto control the amount of memory available to a job.
When a job initially "logs on" it receives a default memory allocation set by
the system manager.
The MEMORY command can be used to change the allocation
for the job. The form of the MEMORY command is:
MEMORY nn
Where "nn" is the number of k-bytes (Kb, 1024. bytes) of memory to be allocated
for the job. The maximum memory size that a job may use is set by the system
manager, but never exceeds 64Kb. When a running program performs a .SETTOP EMT
the top of memory address corresponds to the size last specified by a MEMORY
command. Note that .SETTOP EMT's do not actually affect the amount of memory
allocated co a job -- only the MEMORY command and a TSX-Plus EMT described in
Chapter 7 do that.
Programs are only allowed to use more than 56Kb of memory if they are
"virtual", meaning they do not directly access the RMON area, although they may
access it indirectly by use of the .GVAL and .PVAL EMT's.
Programs may
indicate that they are virtual by any of the following techniques:
1.

Set bit 10 (mask 2000) in the job status word (location 44) of the
SAY file.
See Appendix A for information about how the SETSIZ
program can be used to do this.

Use the Iv LINK switch (/XM switch for the LINK keyboard command)
which stores the RAD50 value for "VIR" in location 0 of the SAY file.

Store a memory allocation size greater than 56Kb in location 56 of
the SAY file.
See Appendix A for information about how the SETSIZ
program can do this.

If none of these conditions is met the program is restricted to 56Kb even if a
larger value is specified with the MEMORY command.
See Chapter 8 and Appendix A for more information on memory usage and virtual
images.

-37-

Keyboard Commands
A program may dynamically control the amount of memory allocated for the job by
use of the TSX-Plus EMT with function code 141 (described in Chapter 7). See
also the description of the SETSIZ program in Appendix A for information about
how the amount of memory to be allocated for a particular program can be stored
in the SAV file for the program.
If the MEMORY command is entered wi thout specifying a size, the current and
maximum memory allocation for the job is displayed. See also the description
of the SHOO' MEMORY command.

The MONITOR Command
The MONITOR command is used to cause TSX-Plus to begin a performance analysis.
See Chapter 13 for complete information about the TSX-Plus performance analysis
feature. The form of the MONITOR command is:
MONITOR base-address,top-address[,cell-size]/switches
where "base-address" is the lowest address in the program region being
monitored, "top-address" is the highest address in the region, and "cell-size"
is the number of bytes to group per histogram cell. The only valid switch is
"/1" which causes I/O wait time to be included in the analysis.

The MOUNT Command.
The MOUNT -command is used to: 1) begin directory caching on a file-structured
device; 2) enable data caching on a device; and 3) associate a logical subset
disk with a disk file.
Directory caching is a technique that speeds up file "lookups" by keeping
information about files in memory so that it is not necessary to access the
directory on the device each time a file is opened.
Data caching is a
technique used to speed up disk reads by keeping memory resident copies of
recently used file blocks. Both directory and data caching are enabled during
TSX-Plus system generation and activated when a device is MOUNTed. The form of
the MOUNT command to activate directory and data caching is:
MOUNT adn
where "ddn" is a physical device name such as "DL1:". The effect of this type
of MOUNT command is to tell TSX-Plus that it should begin directory and data
caching for the device being mounted.
The system device is automatically
MOUNTed for each user.
If caching is not wanted, then no MOUNT should be
performed, or the DISMOUNT command should be used to halt caching on a
previously mounted disk.

-38-

Keyboard Commands
The INITIALIZE and SQUEEZE operations cannot be performed on a device which is
mounted by other users. If it is necessary to INITIALIZE or SQUEEZE a device
which is mounted by other users, then they must first DISMOUNT that device.
Remember that it is possible for a job which has not mounted a device to still
access that device.
Once a MOUNT command is issued, caching is enabled for all users who access
files on the device (including users who have not MOUNTed the device). The
system maintains a table of all users who have mounted each device. See also
the DISMOUNT and SHOW MOUNTS commands.
Warning: If directory caching is enabled for a device, it is crucially
important that the DISMOUNT command be used to dismount the device before a
disk is replaced on the same drive.
If a new disk pack is inserted in the
drive without issuing the DISMOUNT command, TSX-Plus would try to access files
on the new pack according to the locations stored in the directory cache for
the old pack.
Directory caching causes a dramatic improvement in the speed of file "lookups"
but does not speed up file "enters", "deletes" or "renames". This is because
TSX-Plus always updates the directory on the device when it is altered. The
maximum number of devices whose directories may be cached and the number of
file entries that are kept in the directory cache are specified when TSX-Plus
is generated.
The second form of the MOUN~ command is u~ed to associate a logical subset disk
with a disk file. The form of the command is:
MOUNT[/[NO]WRITE] LDn filnam [logical-name]
where "LDn" is the logical subset disk, and n is in the range 0-7, "filnam" is
the name of a disk file containing the subset files, and "logical-name" is an
optional logical name to be assigned to the logical subset disk. The [NO]wKITE
option controls access to the logical subset disk. WRITE allows full access,
whereas NOWRITE allows read-only access.
WRITE access is allowed by default
unless the NOWRITE option is used. The default extension for the disk file to
be associated with a logical subset disk is "DSK".
File protection is
automatically set on the file specified to be a logical subset disk. When a
logical subset disk is mounted, directory and data caching are also begun for
it.
Each user may mount up to 8 logical subset disks at any time. The association
between a logical subset disk (LDO-LD7) and a file is "local" to each user.
For example, one user may associate LD2 with file DLl:MYDISK.DSK while another
user associates LD2 with file DLl:YORDSK.DSK.
Logical subset disks may be "nested", allowing one or more subsets to be
defined within other subsets. However, if this is done, the MOUNT commands
must be executed sequentially from outer-most to inner-most logical subset disk
and the unit numbers must be assigned sequentially from LDO to LD7.
-39-

Keyboard Commands
Example:
.MOUNT LDO MANUAL MAN
.CREATE-rDO:SUB.DSK]ALLOCATE:I00 •
•MOUNT/WRITE LD2 MAN:SUB
.INIT/NOQ LD2:
Other commands which refer to logical subset disks are: DISMOUNT, SET LDn
{CLEAN IWRITE INOWRITE} and SHOW SUBSETS. The ACCESS command may also be used
with logical subset disks in start-up command files.
The restrictions on
INITIALIZE and SQUEEZE operations also apply when another user has mounted the
same logical subset disk.
Logical subset disk support is integral to the file management functions of
TSX-Plus, and does not require the "LD" pseudo-device handler. Consequently,
it is independent of the version of RT-ll supporting TSX-Plus. See Appendix G
for more information on the use of logical subset disks.

The MUNG Command
The MUNG command is used to start a file of TECO commands.
equivalent to the RT-ll MUNG command.

The MUNG command is

The OFF Command
-------The OFF command is used to log off a time-sharing line, and to release a
virtual line (see the discussion of virtual lines in Chapter 4). The accumulated connect time and CPU time used during the session are printed during the
logoff processing. The BYE and KJOB commands are synonyms for the OFF command.
TSX-Plus automatically logs off dial-up lines if the telephone connection is
broken.
A special log-off command file may also be designated to execute
whenever a job logs off; see the TSX-Plus System Manager's Guide for more
information.
Example:
.OFF
Connect time=Ol:43:00

CPU=OO:12:03

The OPERATOR Command
The OPERATOR command is used to send a message to the operator's console. The
OPERATOR command works like the SEND command, but it is not necessary to know
the line number of the operator s terminal. The form of the OPERATOR command
is:

-40-

Keyboard Commands
OPERATOR message
For example, to send a disk mount message to the operator:
.OPERATOR PLEASE MOUNT PAYROLL MASTER DISK ON RK1

The PAUSE Command
The PAUSE command is used wi thin command files (see Chapter 3) to temporar'ily
suspend processing of the file. The form of the PAUSE command is:
PAUSE comments
where "comments" may be any string of characters. When a PAUSE command is
encountered within a command file, the PAUSE command is printed on the terminal
followed by"»". Execution of the command file is suspended until carriage
return is pressed. This gives the operator an opportunity to perform manual
operations such as mounting disks or tapes.

The PRINT Command
The TSX-Plus PRINT command has the same form and options as the RT-11 PRINT
command.

The PROTECT Command
The TSX-Plus PROTECT command has the same form and options as the RT-11 PROTECT
command.

The R Command
------The "R" command is used to start a program.

The form of the command is:

R[/switch] filnam [input-data]
If no device name is specified with the program name, TSX-Plus attempts to find
the specified program on "SY:". The amount of memory available to a program
can be controlled with the MEMORY command, or size information can be included
in its disk image. See the description of the SETSIZ program in Appendix A for
more information about how the amount of memory allocated for a program may'be
controlled. See also Chapter 8 for more information on the operating environment for programs under TSX-Plus.
A line of input may be passed to a program by specifying it as part of the "R"
command following the program name. If this is done the program will receive
the text string as its first line of input and will receive control-C as its

-41-

Keyboard Commands
second line of input.
(See example 2 below.) Note that only programs which
accept input with the .GTLIN, .CSISPC, and .CSIGEN requests can accept input in
this manner.
Single charac ter input (. TTYIN) does not normally accept data
from a command line; however, the program can be invoked with a command file
and accept all terminal input from the command file - see the section on
command file control characters in Chapter 3. Note also that text passed on
the command line will be reorganized iI it contains multiple words separated by
spaces. The first word will be placed as the input to a CSI command string and
the remainder of the line will be placed on the output side of the equal sign.
(See example 7 below.)
The valid switches for the R (and RUN) command are:
/DEBUG
-- Run program under control of debugger
/HIGH
-- Run program in high efficiency TTY mode
-- Lock program to line
/LOCK
/NONINTERACTIVE -- Run program in non-interactive mode
/SINGLECHAR
-- Run program with single-character activation
All switches can be abbreviated to a single character.
The /DEBUG switch causes the program being started to execute under control of
the TSODT debugging program. Before loading the program, a relocatable copy of
the TSODT program ("SY:TSODT.REL") is loaded into the upper-most portion of the
user . . s available memory space (reducing the memory space available to the
running program by about 4Kb). The program being started is then loaded into
the memory space below TSODT and control is passed to TSODT. TSODT responds by
printing 2 greeting message and waiting for a command from the terminal. At
this point register 0 ("$0") contains the address of the starting point of the
program. TSODT may be used to display or examine locations or set breakpoints
in the program.
The program is started with the TSODT "xxxxxx;G" command
(where "xxxxxx" is the starting address of the program). The /DEBUG swi tch
allows programs run under TSX-Plus to be debugged without special linking with
a debugging program.
Because of the mapping for TSKMON while TSODT is being
loaded, programs larger than 28Kb must be linked with TSODT for debugging
rather than use the /DEBUG switch.
Commands and functions of TSODT are
equivalent to those of ODT provided with RT-ll.
The /HIGH swi tch automatically enables the program to use high efficiency
terminal I/O. This disables much of the character testing done during terminal
operations and can increase terminal throughput. See the description of the
"R program. controlled terminal option in Chapter 6 for more information on
high efficiency terminal mode.
n

The /LOCK switch causes the program that is being started to be "locked" to the
time-sharing line so that the line is automatically logged off when the program
exi ts. If the "R/LOCK" command occurs wi thin a command file the command file
is terminated as the program is started and any additional information in the
command file is ignored. The most frequent use of this feature is in start-up
command files where a line is to be restricted to executing a particular
-42-

Keyboard Commands
program. If a locked program chains to another program, the program that was
chained to then becomes the locked program. See example 4 below.
The /NONINTERACTlVE switch prevents a program from receiving the priority boost
normally given to jobs on the completion of terminal input. This should be
used with programs which do heavy terminal I/O but which are not really
interactive jobs, such as file transfer programs. A program run wi th this
switch will execute at a lower priority and will not interfere with interactive
jobs. The effect of this swi tch is cleared when a program exits to KMON, but
the switch remains in effect if the program chains to another program.
The /SINGLECHAR switch causes a program to execute in "single character
activation" mode.
(See the discussion of activation characters in Chapter 6.)
Normally when programs are run under TSX-Plus they do not receive terminal
input until an "activation" character such as carriage-return has been entered.
This is true even if the program sets bi t 12 in the Job Status Word
Also,
TSX-Plus does not normally allow a program to test for terminal input without
stalling on the 5TTYIN EMT. However, the /SINGLECHAR switch causes TSX-Plus to
honor bits 6 and 12 of the Job Status Word, allowing the program to activate on
each character and test for terminal input without stalling. A program can
also cause TSX-Plus to honor JSW bits 6 and 12 by using the "u" and "s"
terminal control commands (see Chapter 6). The example program "STEALS" in the
section on requesting exclusive system control in Chapter 11 uses single
character activation in this way. KED and K52 are automatically run in single
character activation mode.
0

Examples:
1.

Run the program named "DUMP" on device "SY:" •
• R DUMP

Run the program named "PIP" on "SY:" and pass to it the
input line "A.TMP=B.TMP •

• PIP A.TMP=B.TMP
3.

Run the program named "SAMPLE" on "RK2:" •
•R RK2: SAMPLE

Start the execution of BASIC and force logoff on exit •
• R/LOCK BASIC

---

Start a program named PLA~~ and allow it to
use single character activation mode •
• R/SINGLE PLANE

-43-

Keyboard Commands
6.

Start a program named TRIAL in debug mode so that
it will be run under TSODT •
• R/DEBUG TRIAL
*TSX-oDT-V4*

*
7.

Start the program SY:GETLIN and pass it some input text •
• R GETLIN INPUT OUTPUT
The program GETLIN will receive the following text:
OUTPUT=INPUT

The RENAME Command
The TSX-Plus RENAME command has the same form and options as the RT-ll RENAME
command.

The RESET Command
The RESET command is used to reset the system usage statistics that are
displayed with the SYSTAT command. Data caching statistics are also reset by
the RESET command. This is useful when you want to monitor system performance
during a particular part of the day. Operator command privilege is required to
use the RESET command.
The TSX-Plus RESET command is NOT equivalent to the
RT-ll RESET command.

The RUN Command
---The RUN command is equivalent to the "R" command except that the default device
is "DK:"
instead of "SY:".
See the description of the
information about available switches.

"R"

command

for

The SEND Command
The SEND command is used to send messages between time-sharing terminals.
form of the command is:

The

SEND[,line#] message
where "line#" is the number of the line to which the message is to be sent. If
no line number is specified, the message is broadcast to all logged-on lines.
Jobs may inhibit the reception of messages while executing programs by using
the SET TT GAG command.
-44-

Keyboard Commands
Examples:
Ie

Send a message to all logged-on users:
.SEND- Bob, Call me when you get ~ chance.

Send a message to line number 2:
.SEND,2 Will you be on tonight?

When a SEND message is printed at a terminal, the message is preceded by the
number of the line that originated the message and the user name currently
associated with that line. For example, a message from line 1 might be printed
as follows:
01 (SYSMGR) -- Bob, Call me when you get a chance.
Keep in mind that several characters are used to identify the sending line and
user, with the result that a long message may be truncated.

The SET Command
--The SET command is used to set various options controlling system operation.
The general form of the SET command is:
SET device option
As with RT-11, the TSX-Plus SET command is used to specify options,for devices
such as line-printers and card-readers as well as setting certain system
parameters such as terminal control characteristics. When used to set device
options, the SET command has the same form as under RT-ll and may set the same
options (they are specified in the handler). The SET command causes the copy
of the device handler on the disk to be altered so that the effect of the
command becomes "permanent" (until another SET changes the parameter back).
The SET command also attempts to make the change to the copy of the handler
that is in memory with TSX-plus. If the handler is idle when the SET is done,
the change will be made; otherwise, a warning message:
?KMON-F-Handler active -- Can't update running copy
will be printed and the running copy of the handler is not altered. When a SET
is done to a device handler, blocks 0 and 1 of the handler are read from the
disk, the SET option is applied and then block 1 is written back to the disk
and moved over the copy of block 1 that is in memory.
If the vec tor of a
device is changed with the SET dd 'VECTOR=nnn command, TSX-Plus must be
restarted to function correctly. Operator command privilege is required to set
an option in a device handler. See the RT-ll System User's Guide for device
handler SET options.

-45-

Keyboard Commands
SET CACHE
The SET CACHE command is used to alter the number of blocks which may be held
in the generalized data cache.
This command does not alter the amount of
memory reserved for the data cache, bur only controls the number of blocks
within the limits allowed by the CACHE parameter selected during system
generation. This command is used by the system manager to determine the effect
of varying cache sizes on system performance. Operator privilege is necessary
to use this command. The form of this command is:
SET CACHE blocks
where "blocks" may range from 0 to the number of blocks reserved by the CACHE
parameter during system generation.

SET CCL
There are two types of system commands, low level commands such as RUN, SET,
ASSIGN and high level commands such as EXECUTE, COPY, DELETE, and DIRECTORY.
Low level commands are executed directly by TSX-Plus. High level commands are
translated into the appropriate low level commands before execution. The set
of high level commands is known as the Concise Command Language (CCL). The
"SET CCL" command can be used to observe the low level commands that are
produced by translating CCL commands. The form of this command is:
SET CCL [NO]TEST
When TSX-Plus is in CCL TEST mode, it will display at the terminal the low
level commands that are generated by a CCL command, but not execute them. The
"SET CCL NOTEST" command turns this mode off and TSX-Plus goes back to
executing CCL commands.
Test mode is very useful if you are having trouble
getting some complex CCL command to work and want to examine the low level
commands that are being generated.
Example:
.SET CCL TEST
.DIR/OUTPTIT?DIR.DAT/OCTAL/BLOCKS DLl:
R DIR
DK:DIR.DAT=DLl:*.*/O/B

"'c
.SET CCL NOTEST

-46-

Keyboard Commands
SET CORTIM
The SET CORTIM command is used to adjust the value of the CORTIM system control
parameter. This parameter controls the minimum memory residency time for jobs
just swapped into memory. See the TSX-Plus System Managers Guide for further
information about the CORTIM parameter. The form of this command is:
SET CORTIM value
where "value" is the time value specified in 0.1 second units. The current
value of the CORTIM parameter may be determined with the SHOW CORTIM command.
Operator command privilege is required to use this command.

SET EDIT
----The SET EDIT command is used to select which edit program will be invoked when
the system EDIT command is used.

The form of this command is:

SET EDIT option
where "option" may be EDIT, TECO, KED or K52.
The options KED and K52 are
actually synonymous; the KED edi tor is used if the terminal type has been
specified to be a VT100 and the K52 editor is used if the terminal type has
been specified to be a VT52. The terminal must be SET TT LC in order to use
KED or K52.

SET EMT
The SET EMT command is used to control tracing of EMT calls during
execution of a user program. The form of the command is:

the

SET EMT [NO]TRACE
When SET EMT TRACE is specified, a line of information about the EMT call is
displayed at the terminal each time an EMT is executed. The .TTYIN, .TTYOUT
and .PRINT EMTs, however, are not included in EMT traces.
EMT tracing is
disabled with the SET EMT NOTRACE command. Each line of information which is
displayed during EMT t racing contains: the virtual address of the EMT call,
the EMT code, function code, channel number (or sub-function code), and the
first 5 words in the EMT argument block. Only the first two items are defined
for all EMTs. The other items are defined only if used for the EMT currently
being traced.
As an example of EMT tracing, the LNTT program which displays
the current line number and terminal type (see Chapter 7) was traced as
follows:

-47-

Keyboard Commands
.SET EMT TRACE
------.RUN
LNTT

-----

001004

374

004

000

000000

000610

000000

001012

375

110

000

057400

001252

001262

001270

001277

001026 374 005 000 057400
TSX-Plus line number: 2
Terminal type:
001060 375 137 000 001252
VT-100

001252

001262

001270

001277

001262

001270

001277

001311

001262

001270

001277

001311

001072 350 016
.SET EMT NOTRACE

010

001270

----

Note that the .PRINT calls are not traced, since .TTYIN, .TTYOUT and .PRINT
EMTs are never traced. Appendix D contains a list of both RT-11 compatible and
TSX-Plus specific EMTs.

SET ERROR
The SET ERROR command is used to specify the level of error which will abort
command file execution. The form of this command is:
SET ERROR option
where "option" may be FATAL, SEVERE, ERROR, WARNING or NONE. Command files
being executed under the IND program are not normally aborted if errors occur
during execution; the SET IND ABORT command can be used to cause IND command
files to abort according to the same rules as for normal command files. The
TSX-Plus SET ERROR command functions in the same fashion as the RT-11 SET ERROR
command.

SET HIPRCT
The SET HIPRCT command is used to set the value of the HIPRCT system control
parameter. See the TSX-Plus System Manager's Guide for more information on the
effecL ot this parameter. The form of this command is:
SET HIPRCT value
where "value" sets the non-interactive job I/O counter. Operator privilege is
necessary to use this command. The HIPRCT parameter may be referenced by the
SET SIGNAL and SHOW commands. Refer to the TSX-Plus System Manager's Guide for
more information on job scheduling and performance optimization.

-48-

Keyboard Commands

SET IND
The SET IND [NO]ABORT command is used to control the execution of command files
under the control of the IND program when there is an error. Normally, command
files under the control of IND are not aborted when an error occurs, regardless
of the current SET ERROR level.
However, if the SET IND ABORT command is
issued, then command files under the control of the IND program will abort
under the same conditions as would normal command files. The SET IND NOABORT
command restores the default abort processing under IND control (no abort).

SET INTIOC
The SET INTIOC command is used to set the value of the INTIOC system control
parameter. See the TSX-Plus System Manager's Guide for more information on the
effect of this parameter. The form of this command is:
SET INTIOC value
"value" is the interactive job I/O counter.
Operator privilege is
necessary to use this command. The INTIOC parameter may be referenced by the
SET SIGNAL and SHOW commands. Refer to the TSX-Plus System Manager's Guide for
more information on job scheduling and performance optimization.

where

SET 10
The SET 10 [NO]ABORT command is used to select the method or nanaLlng I/O abort
requests.
If the SET 10 ABORT command is issued, then an I/O abort request
will call device handler abort entry points. If the SET 10 NOABORT command is
issued, then I/O abort requests will proceed through I/O rundown; that is, all
pending I/O will complete before the job is aborted. The initial setting of
this parameter 1S Selected during TSX-Plus system generation;
Operator
privilege is required to use this command. The method selected affects all
lines, not just the line from which the command is issued.

SET KMON
The SET KMON command is used to direc t the processing of commands from the
keyboard and from command files. The form of this command is:
SET KMON option
where the valid options are:
[NO]IND, UCI[=filnam] and SYSTEM. The chain of
events in command processing by TSX-Plus is described at the beginning of this
chapter.
The processing of indirect command files may either be controlled by TSX-Plus
or by the IND utility provided with RT-ll.
To cause command files to be

-49-

Keyboard Commands
processed by IND, use the command: SET KMON IND. To return to the normal mode
of TSX-Plus command file processing: SET KMON NOIND. Note that command files
which result in errors are not normally aborted, regardless of the SET ERROR
level, when executed under control of IND. The SET IND [NO]ABORT command can
used to control error abort of IND command files. Command files may be forced
to the normal TSX-Plus mode of execution regardless of whether KMON is set IND
or NOIND by calling them as:
$@filnam
Conversely, command files may be forced to execute under the
regardless of whether KMON is set IND or NOIND by calling them as:

IND utili ty

IND filnam
See Chapter 3 for more information on command file processing.
The other function of the SET KMON command is to control the user command
interface. It is possible for user written programs to accept and pre-process
keyboard commands before the TSKMON program. Command control is local to each
user.
That is, each job may select its own command processing method. The
User Command Interface may be enabled by the command:
SET KMON UCI[=filnam]
When UCI is in effect, then each time TSKMON is ready to accept a command it
passes control to the current UCI program. If the optional "=filnam" has been
omitted, then TSKMON passes command acquisition control to the program
SY:UKMON.SAV. If a file has been specified, then TSKMON passes control to that
program.
It is the responsibility of the user-written command interface
program to prompt for and accept command input lines. Commands may be further
passed on to TSKMON through the chain-data area by doing a special chain exit.
Command processing control is returned to TSKMON by the command:
SET KMON SYSTEM
See the example program in the section on the User Command Interface earlier in
this chapter for more information.

SET LANGUAGE
The SET LANGUAGE command is used to select DBL or DIBOL as the default compiler
for programs with the extension DBL. This also affects the COMPILE and EXECUTE
commands. The form of the command is:
SET LANGUAGE option
where "option" is DBL or DIBOL.

The default setting of this parameter is DBL.

-50-

Keyboard Commands
SET LD
The SET LD command is used to control writing to a logical subset disk and to
verify logical subset disk assignments. The form of the command is:
SET LDn option
where "LDn" is in the range of LDO to LD7, and "option" may be CLEAN, WRITE or
NOWRITE.
To prevent writing to a logical subset disk, SET LDn NOWRITE. To
allow writing to a logical subset disk, SET LDn WRITE. WRITE/NOWRITE control
is also an option of the MOUNT command. SET LDn CLEAN is used to verify and
correct logical subset disk assignments = An implicit SET LDn CLEAN is done by
TSX-Plus whenever the DUP utility program is run (e.g.
INIT and SQUEEZE
operations)..

See

the MOUNT

command

for

further

information

on the use of

logical subset disks.

SET LOG
It is possible to copy terminal output to a log file. ~ben terminal logging is
enabled, all output directed to the terminal is also written to the log file.
The only exception to this is high-efficiency terminal output which is not
logged. To initiate terminal logging issue the following command:
SET LOG FILE=name
where "name" is the file specification for the log file. The default extension
is ".LOG". For example, the following command would copy terminal output to a
file named "DK:RUNLST .. LOG":

SET LOG FILE=RUNLST
The following command causes terminal output to be copied to the line printer:
SET LOG FILE=LP:
Logging of terminal output may be stopped and
command:

the

log file closed by the

SET LOG CLOSE
The log file is automatically closed when another log file is opened or the job
logs off. The log file is also automatically closed if the device containing
the log file is initialized or squeezed; the following warning message appears:
?KMON-W-Closing log file

-51-

Keyboard Commands
It may be desirable to suspend and resume terminal output logging during some
operations without closing and reopening another log file.
To temporarily
suspend terminal logging t issue the command:
SET LOG NOWRITE
To resume terminal logging t issue the command:
SET LOG WRITE
It may be desirable at some times to reset the terminal log file. To clear the
contents of the log file without closing and deleting the file, issue the
command:
SET LOG CLEAN
Terminal logging is especially useful with detached jobs. Terminal output to
detached jobs is normally discarded since the job is not attached to any
terminal. However t when terminal logging is enabled for a detached job, then
the terminal output may be directed to a file or to a printer.

SET LOGOFF
The SET LOGOFF command is usea to associate a "log-off" command file with a
job. This command is only valid within start-up command files. The form of
this command is:
SET LOGOFF FILE=name
where "name" is the file specification of a command file to be executed when
the job logs off. Log-off command files, like start-up command files, cannot
be aborted by control-C. See the TSX-Plus System Manager's Guide for further
information about log-off command files.

SET MAXPRIORITY
The SET MAXPRIORITY command may be used to reduce the maximum priority allowed
to a job. When placed in a start-up command file, this command restricts the
maximum available priority for that job. This permits restriction of priority
on lines which do not use the LOGON facility. The form of this command is:
SET MAXPRIORITY value
where "value" is in the range of 0 to 127. If the current maximum job priority
is less than 127, then the current maximum priority is the upper limit for the
valid range of "value".
See the TSX-Plus System Manager s Guide for further
information about restricting job priority.

-52-

Keyboard Commands
SET NUMDC
The SET NUMDC command is used to control the number of buffers used for data
caching. The form of this command is
SET NUMDC value
where "value" is the number of buffers to use.. The initial value of the NUMDC
parameter is specified when the system is generated. The SET NUMDC command may
be used to restrict the number of data cache buffers actually used to a value
less than the number of buffers specified when the system was generated, but
may not exceed that value.
The SET NUMDC command does not alter the memory
space allocated for cache buffers, it merely controls the number of buffers
actually used. Operator command privilege is required to use this command.
The primary use of the SET NUMDC command is to determine the optimum number of
data cache buffers to include in a system.
To do this, the system can be
generated with a large number of data cache buffers and the SET NUMDC command
can be used to determine the minimum number which are actually needed to
provide effective performance. ~~en using this procedure, all files that are
being cached should be closed before the SET NUMDC command is issued.
See
Chapter 9 for a discussion of shared-file data caching.

SET PRIORITY
The SET PRIORITY command is used to set the execution priority for a timesharing job. The form of the command is:
SET PRIORITY value
where "value" may range from 0 to 127. The default priority assigned to a job
when not otherwise specified or restricted is 50. The maximum priority allowed
to a job may be restricted through the logon mechanism or the SET MAXPRIORITY
command.
The SHOW PRIORITY command can be used to display the current job
priority and the maximum authorized priority. The SYSTAT command also displays
current job priorities.
Job priorities may also be assigned from within an executing program with an
EMT. See Chapter 7 for more information on setting job priority from within a
program.
When a job is disassociated from the terminal by swi tching to a different
virtual line the job is reduced in priori ty by an amount determined during
system generation (the PRIVIR parameter).
The job priority value is used by the scheduler to determine which job has
precedence and should be run next. The priority value is only used when there
is more than one job in the same executable state queue. See Appendix H for
more information about job execution priorities.
See the TSX-Plus System
Manager's Guide for more information on job scheduling
0

-53-

Keyboard Commands
SET PROMPT
The SET PROMPT command is used to change the keyboard monitor prompt character.
The default character is a 'period ("."). The form of the command is:
SET PROMPT "string"
where "string" is a quoted string containing from 1 to 8 characters.
The
quoted string will subsequently be used as the keyboard monitor prompt string.
For example, in order to set the monitor prompt to a dollar sign followed by a
space (the standard VMS prompt string), use the following command:
SET PROMPT "$ ..
To restore the standard RT-11 prompt string, issue the command:

SET PROMPT " "

SET QUANxx
The SET QUANxx command is used to set the value of the system time-slice
control parameters (QUANO, QUAN1A, QUAN1B, QUAN1C, QUAN2, and QUAN3). See the
TSX-Plus System Manager's Guide for information about the effect of the these
parameters. The form of this command is:
SET QUANxx value
where "value" is the time value specified in 0.1 second units.
Operator
command privilege is required to use this command.
The value selected takes
effect for all jobs on the system, not just the job issuing the command. These
parameters may be referenced by the SET SIGNAL and SHOW commands.
See the
TSX-Plus System Manager's Guide for more information on job scheduling and
performance optimization.

SET SIGNAL
The SET SIGNAL command is used as an aid to system performance tuning.
form of the SET SIGNAL command is:

The

SET SIGNAL [NO]parameter
where "parameter" may be one of the system scheduling parameters:
HIPRCT,
INTIOC, QUANO, QUAN1, QUAN1A, QUAN1B, QUAN1C, QUAN2, or QUAN3.
Only one
parameter may be selected by each SET SIGNAL command, although with multiple
SET SIGNAL commands more than one parameter may be selected for signaling at
once.
Signaling may be disabled for any individual parameter by prefacing the
parameter with "NO".
Signaling may be halted for all parameters with the
command SET SIGNAL OFF.

-54-

Keyboard Commands
When signaling has been enabled for a system tuning parameter, the bell will be
rung at the terminal of the job for which signaling has been selected each time
the job changes state because it exceeds the value of the selected parameter.
The SET SIGNAL command functions on a 1ine-by-1ine basis and only affects the
line from which the command is issued.
The signaling feature is intended as an aid to the system manager in determining appropriate values of the system tuning parameters for a given job. See
the TSX-P1us System Manager's Guide for more information on use of the
signaling feature.

SET SL
---The SET SL command is used to control the ability to edit keyboard input lines.
The TSX-P1us SL facility is generally compatible with that provided with the
RT-ll "SL" editor. It allows editing of the current input line or field and
recall of the previous input line or field. See the section on the single line
edi tor in Chapter 1 for information vn the use of the single line editor. The
form of this SET command is:
SET SL option
where the options are described below.
Option

Meaning

ASK

This command is ignored.
The terminal type is determined from the
current TSX-P1us terminal type.

K52

This command enables "KED"-like extensions to the single line editor.
Note that the numeric keypad is set to application mode.

KED

This command enables "KED"-like extensions to the single line editor.
Note that the numeric keypad is set to application mode.

KEX

This command enables "KED"-like extensions to the single line editor.
Note that the numeric keypad is set to application mode.

[NO] LEARN This command is ignored.
implemented.

The single line editor LEARN mode is not

[NO]LET

This command is ignored.
single line editor.

The LET utility may not be used with the

OFF

This command turns off the single line editor.

This command turns on the single line editor.
in single-character activation mode.

-55-

Note that the job is

Keyboard Commands
RT11

This command disables the "KED"-like extensions to the single line
editor.

SYSGEN

This command is ignored. The single line editor is implemented as a
TSX-Plus system overlay region and does not require the SL pseudodevice handler.

[NO]TTYIN This command either enables (TTYIN) or disables (NOTTYIN) editing of
keyboard input being accepted via the .TTYIN EMT from within
programs.
VT52

This command is equivalent to SET TT VT52. Ensure that your terminal
responds to VT52 type control sequences before issuing this command •

VT62

. This command is equivalent to SET TT VT52. Ensure that your terminal
responds to VT52 type control sequences before issuing this command.

VT100

This command is equivalent to SET TT VT100.
Ensure that your
terminal responds to VT100 type control sequences before issuing this
command.

VT101

This command is equivalent to SET TT VT100.
Ensure that your
terminal responds to VT100 type control sequences before issuing this
command.

VT102

This command is equivalent to SET TT VT100.
Ensure that your
terminal responds to VT100 type control sequences before issuing this
command.

WIDTH=n

This command is ignored.
The maximum input line width that can be
used with the single line editor, either as a command line or in a
program data field, is 80 characters.

SET TERMINAL
The SET TERMINAL command is used to set various terminal parameters.
equivalent to the SET TT command.

It is

SET TT
The form of this SET command is:
SET TT [NO]option
to turn an option off and on.
Some options require a numeric parameter, in
which case they are specified as:
SET TT option=value
-56-

Keyboard Commands
Option

Meaning

ADM3A

Tells TSX-Plus that the terminal being used is a Lear Siegler ADM3A
and also has the effect of SET TT SCOPE, NOTAB, NOFORM.

DECWRITER Equivalent to the LA36 option.
[NO ]DEFER TSX-Plus offers two modes of character echoing -- "deferred" and
"immediate" (NODEFER).
If the user only types input to programs
while they are waiting for input, the two modes function identically.
However, if the user types input before the program finishes
processing the previous line of input, the two modes are different.
In immediate (NODEFER) mode the input characters are echoed immediately and may be printed even before the program prints the response
to the previous line. In deferred echo mode, the characters that are
typed ahead are accepted and held for the program, but are not echoed
to the terniinal until the program is ready to accept them. Under
standard RT-ll, EDIT, BASIC, and DIBOL programs run in deferred mode.
Most other programs use immediate echoing. Deferred echoing is the
preferred mode under TSX-Plus. See Chapter 6 for information about
how a program can control deferred echo mode.
DIABLO

Has the effect of SET TT NOSCOPE, FORM, NOTAB, PAGE. The QUME type
is equivalent.
When doing plot ting or printing wi th proportional
spacing, SET TT TAB.

[NO]ECHO

Controls echoing of characters to the terminal. See Chapter 6 for
information about how a program can control character echoing.

[NO]FORM

Controls conversion of form feed (FF) characters to line feeds. FORM
should be set with terminals whose hardware can respond to form feed
characters.
NOFORM should be used for terminals whose hardware
cannot handle form feed characters.
wnen NOFORl.'1 is set, form feed
characters are replaced by eight line feed characters.
T1

[NO ] FORMO The FORMO option causes TSX-Plus to first issue a form-feed when a
write is done to the terminal with a block number of zero. This is
convenient when producing multiple program listings to cause each
listing to begin at the top of a new page.
The NOFORMO option
disables special handling of block zero writes.
[NO]GAG

The GAG option inhibits messages sent from another line from being
displayed at the terminal. This is only in effect when the job is
executing a program.
Messages are not inhibited while in the
keyboard monitor. The NOGAG option allows messages to be displayed
at any time. The GAG option is useful for preventing messages from
interrupting jobs on hardcopy terminals, such as printers or
plotters, where a message could spoil the format. This command only
affects messages sent either with the SEND command or the EMT which
sends a message to another job.
This does not apply to message
communication channels.

-57-

Keyboard Commands
HAZELTINE Tells TSX-Plus that the terminal being used is a Hazeltine brand
terminal and also has the effect of SET TT SCOPE, NO TAB , NOFORM.
LA36

Tells TSX-Plus that the terminal being used is an LA36 and also has
the effect of SET TT NOSCOPE, NO TAB , NOFORM.

LA120

Tells TSX-Plus that the terminal being used is an LA120 and also has
the effect of SET TT PAGE, TAB, FORM, NOSCOPE.

[NO]LC

Allows lower case characters to be passed to a program. If LC is set
and bit 14 of the job status word is set to 1, input of lower case
characters from the terminal will be passed to the running program.
If the terminal is set NOLC or the Job Status Word bit 14 is clear,
lower case characters are translated to upper case. See Chapter 6
for information about how a program can control lower-case character
conversion. Note that in order to use the keypad editors KED and K52
the terminal must be SET TT LC.

[NO]PAGE

PAGE allows CTRL-S and CTRL-Q characters to suspend and restart
terminal output. When the terminal is set NO PAGE , CTRL-S and CTRL-Q
have no special effect and are passed directly to the running
program.

[NO]QUIET Setting the terminal QUIET suppresses the listing of command files as
they are executed. When the terminal is set NOQUIET, command file
lines are listed as they are executed. See Chapter 3 for additional
information on controlling command file listing.
QUME

Equivalent to the DIABLO type.
Has the effect of SET TT NOSCOPE,
FORM, NOTAB, PAGE. When doing plotting or printing with proportional
spacing, SET TT TAB.

[NO] SCOPE Tells TSX-Plus whether the terminal is a CRT device. Setting SCOPE
causes the DELETE key to echo as a backspace-space-backspace
sequence, erasing the previously typed character. See Chapter 6 for
information about how a program can specify an alternate "rubout
filler" character that will be used to overwrite characters being
erased when DELETE is typed. When the terminal is set NOSCOPE, the
DELETE key causes preceding characters to be echoed in reverse order
as tbey a~e removed from the input buffer, and CTRL-U echoes carriage
return, line feed. CTRL-R can be used to check the current contents
of the input buffer when doing rubout editing.
See Chapter 1 for
information on other special control characters.
[NO]SINGL Controls automatic single character activation for programs. If the
SET TT SINGLE command has been issued, then programs may control
single character activation on terminal input by toggling bit 12 in
the Job Status Word. The /SINGLE switch to the R[UN] command and the
"S" program controlled terminal option allow individual programs to
control single character activation.
The SET TT SINGLE command

-58-

Keyboard Commands
applies to all programs until the SET TT NOSINGLE command is issued.
If the SET TT NOSINGLE command is in effect, then programs may still
individually
control
single
character
activation
with
the
R[UN] /SINGLE swi tch or the "S" program controlled terminal option.
In all cases, the program must still set bit 12 in the Job Status
Word to achieve single character activation.
The SET TT SINGLE
command differs from the R[UN]/SINGLE switch in that it only affects
setting of single character activation (JSW bit 12), not terminal
no-wait input (JSW bit 6). The SET TT NOWAIT command may be used to
allow no-wait terminal input.
[NO]TAB

Controls conversion of TAB characters to multiple spaces. TAB should
be selected with terminals whose hardware can respond to TAB
characters.
When set NOTAB, TAB characters being sent to the
terminal are replaced by an appropriate number of spaces.

[NO]TAPE

TAPE tells TSX-Plus that the terminal line is connected to a paper
tape, cassette tape, floppy disk or other device that will respond to
X-ON/X-OFF (CTRL-Q/CTRL-S) control characters to start and stop
transmission.
Setting TAPE mode has three effects:
1) TSX-Plus
transmits an X-OFF character (CTRL-S) to the terminal when the line
input buffer fills to the point that there are only 20 free character
positions remaining; 2) TSX-Plus transmits an X-ON character (CTRL-Q)
to the terminal when a program begins waiting for more input from the
line and an X-OFF has previously been sent to the terminal; 3) linee-feed characters are completely ignored unless line~feed is declared
to be a user-defined activation character -- this is done so that
each line of input may be terminated by both a carriage-return and a
line-feed.
See Chapter 6 for information about how a' program can
turn tape mode on and off.

VT50

Equivalent to the VT52 option.

VT52

Tells TSX-Plus that the terminal being used is a VT52 (or VT100 in
VT52 mode) and also has the effect of SET TT SCOPE, TAB, PAGE,
NOFORM.

VT100

Tells TSX-Plus that the terminal being used is a VT100 (which must be
operating in VT100 mode -- not VT52 compatible mode) and also has the
effect of SET TT SCOPE, TAB, PAGE, NOFORM.

[NO ]WAIT

Normally, TSX-Plus blocks the execution of a program that does a
.TTYIN EMT if no activation character has been received even if the
program sets bit 6 in the Job Status Word which is supposed to mean
that the program can do non-blocking .TTYIN character tests. This is
done to prevent programs from "burning up" CPU time by constantly
looping back to test for terminal input.
If the NOWAIT option is
specified with the SET TT command, TSX-Plus will honor bit 6 in the
Job Status Word and allow the program to do non-blocking .TTYINs if
bi t 6 is set.
The example program "STEALS" in the section on

-59-

Keyboard Commands
requesting exclusive system control in Chapter 11 demonstrates the
program controlled terminal option to allow NOWAIT input.
All of these terminal options can be given initial settings for each line when
the TSX-Plus system is generated.
Each time a user logs onto a line, the
initial option settings are used. The options may be altered by using the SET
command, but when the user logs off, the options revert to their ini tial
setting specified in TSGEN. When a user initiates a virtual line, the initial
flag settings for the virtual line are copied from the current flag settings
for the user. Subsequent flag changes for a virtual line do not affec t flag
settings for the user's other lines.

SET UCL
You
specify the order in which the TSX-Plus command interpreter checks for
user-defined commands by use of the SET UCL command. This command has four
forms:

can

SET UCL FIRST
SET UCL MIDDLE
SET UCL LAST
SET UCL NONE
If the SET UCL FIRST command is used, user-defined commands will be processed
before system commands.
This allows user-defined commands to replace system
commands but makes the processing of system commands slower. This is the
required setting only if it is necessary to replace some system commands.
If the SET UCL MIDDLE command is used, user-defined commands are processed
after system commands but before checking for command files and SAV files with
names that match the command keyword. Using this setting, it is not possible
to replace a system command with a user command, but both system commands and
user-defined commands are processed relatively quickly.
This is the recommended setting unless it is desirable to replace system commands.
If the SET UCL LAST command is used, a command will not be checked to see if it
is a user-defined command until after it is checked to see if it is a system
command, the name of a command file on DK, the name of a command file on SY, or
the name of a SAV file on SY.
Using this setting, it is not possible to
replace a system command with a user command and user commands cannot have the
same name as command files or SAV files. System commands are processed quickly
(the same speed as SET UCL MIDDLE), but the processing of user-defined commands
is slow.
This is the appropriate setting only if user-defined commands are
desired, but command files already exist whose names would conflict wi th
user-defined commands.
Existing command files which are short and merely
execute system commands should be replaced by user-defined commands.
If the SET UCL NONE command is used, user defined commands are never interpreted. In this mode, attempts to invoke user-defined commands will result in
the error:

-60-

Keyboard Commands

?KMON-F-Unrecognizable command
The following list illustrates where the FIRST/MIDDLE/LAST setting causes the
command interpreter to check for and process user-defined commands:
FIRST

--)

See if command is a system command
MIDDLE --)
Look for command file on DK: with command name
Look for command file on SY: with command name
Look for SAV file on SY: with command name
L.\ST

--)

See the beginning of this
interpretation process.

chapter for

further

information on

the command

SET VM
The SET VM command is used to control the amount of memory available to the VM
pseudo-device.
The SET VM command is normally not necessary as VM will
automatically calculate the correct base address to use, starting just above
the last address used by TSX-Plus, and using all physical memory installed
above that address. The only form of this command is:
SET VM BASE=nnnnnn
where "nnnnnn" represents the octal value of bits 6 through 22 of the base
memory address which VM is allowed to use. For example, in a system with 1.5
megabyte of memory, to reserve the top 256 Kb of memory for use by VM the value
of "nnnnnn" should be 50000.
This corresponds to a base address for VM of
5000000. If this command is issued, then VM will use the higher of the address
specified by "nnnnnn" or the top of TSX-Plus. That is, it is not permitted to
set the base of VM to include the system overlay regions.

SET WILDCARDS
The SET WILDCARDS command is used to control substitution of missing parts of
file names. The form of the command is:
SET WILDCARDS option
where "option" is either IMPLICIT or EXPLICIT.
If IMPLICIT is chosen, then
file specifications which are incomplete will be treated as though the .,*"
character had been typed for the missing part of the specification. The only
parts of file specifications affected by this substitution are the file name
and the extension.
The device cannot be specified as a wildcard.
Most
keyboard commands which accept file names also accept wildcards. The following

-61-

Keyboard Commands
table demonstrates the interpretation of various
wildcards have been set IMPLICIT or EXPLICIT.
Command

IMPLICIT

EXPLICIT

-------

--------

cmd TEST. FOR
cmd TEST.*
cmd TEST
cmd TEST.
cmd *.FOR
cmd .FOR
cmd *.*
cmd *
cmd *
cmd

cmd TEST. FOR
cmd TEST.*
cmd TEST.*
cmd TEST.
cmd *.FOR
cmd *.FOR
cmd *.*
cmd *.*
cmd *.*
cmd *.*

cmd TEST.FOR
cmd TEST.*
cmd TEST
cmd TEST.
cmd *.FOR
cmd .FOR
cmd *.*
cmd *
cmd .*
cmd

file specifications when

where "cmd" is one of the keyboard commands which accepts wildcards in file
specifications, such as: COPY, DIRECTORY, PRINT, PROTECT, etc.
The system-wide default setting for wildcard interpretation may be selected in
TSGEN; see the TSX-Plus System Manager's Guide.

The SHOW Command
----The SHOW command is used to display information about the state of the system.
Each form of the SHOW command is described below.

SHOW ALL
The SHOW ALL command is equivalent to specifying all of: SHOW DEVICES, SHOW
ASSIGNS, SHOW JOBS, SHOW TERMINALS, SHOW MEMORY, SHOW SUBSETS, SHOW MOUNTS,
SH()ol RUN-TIMES.

SHOW ASSIGNS
The SHOW ASSIGNS command displays information
assignments that are currently in effect.
Example:
.SHOW ASSIGNS
Assignments:
SY - ) DLO:
CBL --) RKO:
TMP --) DL3:
DK --) LOa:

-62-

about

all

logical

device

Keyboard Commands
SHOW CACHE
---The SHOW CACHE command reports the total number of blocks available in the
generalized data cache buffer.
Example:
.SHOW CACHE
Number of blocks in data cache

1000

SHOW COMYJANDS
The SHOW COMMANDS command is used to display the currently available userdefined command definitions.
See the beginning of this chapter for more
information on declaring and using user-defined commands.
Note that escape
characters embedded in commands are represented by a dollar sign ("$").

Example:
• SHOW COMMANDS
C100
:== DISPLAY $[H$[J
DEF
: == -ASS .... DK
EXAM
: == -R KED .... /1
KPAD
:== -DISPLAY $=
LOG
:== -SET LOG FILE= ....
NEW
:== -R DIR .... /D
NOKPAD
:: ==- =DISPLAY $>
NOLOG
:== SET LOG CLOSE
:== =SPOOL LP,STAT
Q
:== SH SUB
SUB
TOME
:== -DISMO LDO\ ASS DL2 DK\ SH SUB
:== =DISMO LDO\-MOU LDO DL2:WORK DK\_SH SUB
WORK

SHOW CONFIGURATION
The SHOW CONFIGURATION causes
system characteristics.

display of

certain hardware and

operating

SHOW CORTIM
The SHOW CORTIM command displays the current value of the system parameter
CORTIM.
See the TSX-Plus System Manager's Guide for more information on the
significance of the CORTIM parameter.

-63-

Keyboard Commands
Example:
• SHOW CORTIM
2

SHOW DEVICE S
The SHOW DEVICES command displays information about which devices were
specified as being available when TSX-Plus was generated. For each device the
following items of information are displayed:
1.
2.

Device name
Device status word (See the RT-ll Programmer's Reference
Manual, .DSTATUS request, for a description of this value.)
Device handler base address
Device handler size (decimal bytes)
Device CSR (Control and Status Register) address
Device interrupt vector(s) address

3.
4.
5.
6.

The CSR and vector values are only displayed if the user issuing the SHOW
DEVICES command has operator privilege.
Some of this information is not
displayed for pseudo-devices such as TT, NL, and LD.
Example:
• SHOW DEVICES
Device

Status

Handler
base

Handler
size

CSR

Vector

------

-------

------

TT
DM

000004
102423
016011
102022
020003
000025
102446

065302
067746
077352
100474
101172

1316
3844
594
318
58

177440
172520
177170
177514

210
224
264
200

DX
LP
NL
LD

SHOW HTPRCT
The SHOW HIPRCT command displays the current value of the system parameter
HIPRCT.
See the TSX-Plus System Manager's Guide for more information on the
significance of the HIPRCT parameter.
Example:
• SHOW HIPRCT

LiO

-64-

Keyboard Commands
SHOW INTIOC
The SHOW INTIOC command displays the current value of the system parameter
INTIOCe
See the TSX-Plus System Manager . . s Guide for more information on the
significance of the INTIOC parameter.
Example:
• SHOW INTIOC
~

SHOW JOBS
The SHOW JOBS command displays intormation about jobs that are currently logged
onto the system.
The information displayed by this command is identical to
that displayed by the SYSTAT command.

SHOW MEMORY

The SHOW MEMORY command displays information about memory usage including the
total installed memory on the machine, the size of TSX-Plus and handlers, the
memory space available to user jobs and the current job memory allocation and
maximum authorized size. It also lists the size of the swappable job context
area which is a system table associated with each job.
Example:
.SHOW MEMORY

Total installed memory = 1280Kb
Size of unmapped TSX and handlers
Size of mapped TSX system regions
Total size of TSX and mapped data

38Kb
38Kb
80Kb

Size of sharable run-time systems

OKb

Size of data cache buffer area = 516Kb
Space available for user jobs = 683Kb
Swappable context area for each job = 4Kb
Current job memory limit
56Kb
Maximum job memory limit = 64Kb

SHOW MOUNTS
The SHOW MOUNTS command displays the names of those devices that have be-en
moun ted by use of the MOUNT command and whose direc tories are being cached.
TSX-Plus maintains a list of which jobs have mounted each device. This list is
used with the INITIALIZE and SQUEEZE commands to reduce the chance of data
destruction by altering a device directory while another job has a file open on
the device. For logical subset disks, the name of the file which contains the
device is_ also shown. Note that with nested logical subset disks, the table
formatting is relaxed.
-65-

Keyboard Commands
Example:
• SHOW MOUNTS
Device
1 2
DLO:
1 6
DL1:
8
DL2:SMADA
2 11
DL3:
11
DL3:WORK
DL3:WORK:TEMP 11
DL3:MANUAL 2

Associated jobs

6
9

9 10 11

SHOW NUMDC
The SHOW NUMDC command displays the current value of the system parameter
NUMDC.
See the TSX-Plus System Manager's Guide for more information on the
significance of the NUMDC parameter.
Example:
.SHOW NUMDC
-0-

SHOW PRIORITY
The SHOW PRIORITY command displays the current and maximum priority values for
a job. In addition, the range of priority values which are used for high and
low fixed priority jobs is shown. See Appendix H for further information about
job execution priorities.
Example:
.SHOW PRIORITY
Current priority = 50; maximum authorized priority
Low priority range = 0 to 19
High priority range = 80 to 127

127

SHOW QUANxx
The SHOW QUANxx command is used to display the current value of various system
tuning parameters.
The parameters which may be shown are:
QUANO, QUAN1,
QUAN1A, QUAN1B, QUAN1C, QUAN2, and QUAN3. Related tuning parameters which may
also be shown are: CACHE, CORTIM, HIPRCT, INTIOC, and NUMDC. See the TSX-Plus
System Manager's Guide for more information on the significance of the various
system tuning parameters.

-66-

Keyboard Commands
Example:
.SHOW QUAN3

-zo

SHOW QUEUE
The SHOW QUEUE command displays information about print files in the spool
queue.
The following information is displayed for each print file in the
queue: name of the device the file is queued for; an asterisk if the file is
currently being printed; the name of the file if a file name was specified with
the .ENTER -- otherwise the name of the program that created the file; the name
of the form on which the file is to be printed, the number of blocks in the
file remaining to be printed -- this will decrease as the file is printed. For
more information on printer spooling, see Chapter 5.
Example:
.SHOW QUEUE

Dev-Job
LP *
1
LP
5
LP
5

File
PLT50
EXTERN
PAYROL

Form
STD
STD
FORM3

Blocks
244
5
35

SHOW RUN-TIMES
The SHOW RUN-TL."vfES command causes the Q1splay of
run-time systems that were loaded with the system.

the names 0.£

the shared

Example:
• SHOW RUN-TIMES
CBRTS
RTCOM

SHOW SUBSETS
The SHOW SUBSETS command is used to obtain information about logical subset
disks which have been mounted. Only the logical subset disks which have been
mounted by the user are shown; those mounted by other users are not included.
The name of the logical subset disk, the file with which it is associated, the
file size, and an optional asterisk are displayed. If present, the asterisk
indicates that the file associated with the logical subset disk is missing. In
order to DISMOUNT a logical subset disk which is associated wi th a mi ssing
file, it is necessary to create or copy the missing file to the appropriate
device.
See the MOUNT and DISMOUNT commands and Appendix G for more information on logical subset disks.

-67-

Keyboard Commands
Example:
.SHOW SUBSETS
LDO --) DLl:MANUAL.DSK[2601]
LD2 --) LDO:SUB.DSK[100] *

SHOW TERMINALS
The SHOW TERMINALS command gives a display of the parameters of all primary
time-sharing terminal lines defined to TSX-Plus during system generation along
with some current characteristics.
ExamEle:
• SHOW TERMINALS
Unit
Type

Vector

CSR

Terminal

Speed

1
2
3
4*
5
6

Operator
Local
Local
Local
Local
Remote

DL
060
310
DL
DL
320
DZ-O 300
DZ-l 300
DZ-3 300

177560
176510
176520
160040
160040
160040

VT100
VT100
LA120
VT100
VT100
VT52

Active

User

Yes
No
Yes
Yes
No
No

SYSMGR

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

-------- -------- ------ --------N/A
N/A
N/A
9600
9600
1200

SMADA
GREG

The unit number indicates the number assigned to each line (determined by the
order of declaration during system generation).
The line which issued the
command is marked with an asterisk. The type of line may be: Operator - the
line which was declared to be the opera tor's console during TSX-Plus system
generation; Remote - any line which has been declared to be attached to a modem
during system generation; or Local - all other lines. The interface hardware
is indicated in the Vector column as either a DL(V)11 serial interface or a
DZ(V)11 multiplexor. DZ lines are further identified with the port number to
which the line is attached. The Vector and CSR addresses are those declared
during system generation. The Terminal identification is that which has been
declared to TSX-Plus either during system generation or via a later SET TT
<type) command. The Speed column indicates the baud rate specified for DZ type
lines; it is not available for DL type lines. Lines which are currently logged
on are marked with a "Yes" in the Active column and the owner is identified in
the User eolumn if possible.

SHOW USE
The SHOW USE command causes display of the accumulated connect time and CPU
usage for the current job since logon. The SHOW USE command is equivalent to
the USE command.

-68-

Keyboard Commands
Example:
.SHOW USE
---Connect=OO:50:00

CPU=OO:OO:23

The SPOOL Command
The SPOOL Command is used to control the operation of the spooling system. It
may only be used if device spooling is enabled when the system is generated.
The form of the SPOOL command is:
SPOOL device,function,parameter
where "device" is the name of a device that was specified to be spooled when
the system was generated, "function" denotes what function is to be performed,
and "parameter" provides additional information for some functions.
See
Chapter 5 for further information on the SPOOL command.

The SQUEEZE Command
The TSX-P1us SQUEEZE command has the same form and options as the RT-ll SQUEEZE
command. However, the system device (booted device when TSX-P1us is started)
may not be squeezed while running TSX-P1us. If it is necessary to squeeze the
system device, it must be done from RT-ll.
The following error message
appears:
?KMON-F-This operation not legal with SY (system) device
A device cannot be squeezed if any other user has MOUNTed the device. Attempts
to SQUEEZE a device which is mounted by another user will result in the error
message:
?KMON-F-Device is mounted by another user
The SHOW MOUNTS command may be used to determine which other jobs have the
device mounted.
If the device is mounted only by the job which squeezes it,
then the directory and data caches are cleared after the operation and caching
is resumed.
If terminal logging is being done (see the SET LOG command) and a log file is
open on the device being squeezed, the log file is automatically closed and the
following warning message appears:
?KMON-W-Closing log file
Warning: It is still possible to write to a device without first mounting it.
If one user has a file open on a device while another user squeezes the device,
th.e possibility of severe data corruption exists. If the user with the open

-69-

Keyboard Commands
file writes to the disk during or after the squeeze operation, the data will be
directed to locations on the disk according to the previous directory information. When the disk is squeezed, these locations are no longer appropriate
and write operations will probably corrupt other files. Never squeeze a disk
to which another user may be writing data.
As a defensive measure, always
MOUNT any device which you plan to use.

The SYSTAT Command
The SYSTAT (SYstem STATus) command displays information about the performance
of the system and information about each logged-on job.
The first line
indicates the amount of time since TSX-Plus was started or the RESET command
The second line of the system performance information shows a
was issued.
breakdown of the percent of total time spent running user jobs, wai ting for
user I/O, waiting for swapping I/O and waiting for something to do (idle time).
These percentages should add up to approximately 100% (less rounding errors).
The third line of system performance information shows the percent of the total
time that some user I/O and swapping I/O was being performed. The percentages
on this line are not expected to sum to 100 because they simply indicate how
much of the time some I/O was taking place without considering whether jobs
were running while the I/O was going on.
The difference between the I/O
percentages on the second line and the I/O wait percentages on the first line
is a measure of the amount of overlap of job execution with I/O that took
place. The RESET keyboard command may be used to reset these statistics so
that the statistics may be gathered over a desired interval of system execution.
The information displayed for running jobs consists of one line per job. The
first item is the job number, followed by an asterisk for the line to which you
are currently attached. The next item indicates the primary line and virtual
line number for each job. If the job is a primary line, then the line number
will correspond to the job number and the number in parentheses will be zero indicating relative virtual job number O.
If the job is a virtual job, the
line number will indicate the primary line from which it was started and the
virtual job number relative to the primary line in parentheses. Detached jobs
will be marked by "Det.". The next item is the current priority for each job.
A two-character state code is printed next, indicating the current state of the
job. The state codes and their meanings are as follows:

-70-

Keyboard Commands
State

Meaning

HI
IN
10
LO
MI
MS
RN
RT
SF
SL
SP
TI
TO
US

High priority non-interactive run state
Interactive state
Waiting for non-terminal I/O to finish
Fixed-low-priority run state
Waiting for mapped I/O buffer
Waiting for a message
Normal priority non-interactive run state
Fixed-high-priority run state
Waiting for access to a shared file
Doing a timed wait (.TWAIT) or .SPND
Waiting for free spool block or file entry
Waiting for input from the terminal
Waiting for the terminal to print output
Waiting for access to file management module

The characters
n1'1 ........... o'Y"llf-1"tT
\....U.L.

.L~L.L""'..LJ

"-Swap"

~T_T~'W""\'Y"'IoL:'\,:t

owapp~u

ru' ............ .f=
VUI.

V..L

are printed following
"1'"1'\0","'''''-':1'

1ll.\;;JJ.J,VL.J.

"_T"",lr";C"
..&...JV'-.1'\,...Lu

the state code if the job is

~;C''T'''\.''''''''tl'~A

U-Lup..LCLJ~U

h.'tT

IJJ

f-ho
'-.LL~

C"f-.-:II+-.o.

O,","CL'-~

n",.:Ia~.f=

'-VU"-

..L.L

+-'ho

,-J..l\;;.

job has locked itself in memory. The number of K-bytes of memory space used by
the job, shown next, includes ordinary job space, extended memory regions and
the job context block (currently 4Kb). This is followed by the connect time
and CPU time used so far by the job, and the name of the program being run on
the line.
Except for detached jobs, which are not associated with any
particular user or line, the last item indicates the user name. The user name
may be blank.
Example:
.SYSTAT
Uptime: 05:34:29
System use:
Run=10%, I/0-wait=8%, Swap-wait=O%, Idle=81%
I/O Activity: User 1/0=10%, Swapping 1/0=0%
Job

Line

Pri

1
2
5
8
10
11*

1(0)
2(9)
5(0)
8(0)
Det.
2(1)

State

Size

-------

-----50
40
84
50
50
50

TI-Swap
TI
SL-Lock
RN

MS-Swap
IN

33Kb
32Kb
16Kb
34Kb
60Kb
33Kb

Connect

CPU time

Program

User name

--------

-------

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

05:35:00
01:53:00
01:00:00
05:24:00
05:35:00
01:53:00

00:03:40
00:01:36
00:03:17
00:00:33
00:00:00
00:01:00

KMON
KED
LAB 3
COBOL
RTSORT
KMON

SYSMGR
ANDY
VOLPE
MITCHELL
ANDY

The TECO Command
The TECO command is used to initiate an editing session with the TEeO editor.
The TSX-Plus TECO command is equivalent to the RT-ll TECO command.

----------. ..,....,---- -----. . . .-=-

-71-

Keyboard Commands
The TIME Command
----The TSX-Plus TIME
command.

command has the same form and options as the RT-ll TIME
Operator command privilege is required to set the time.

The TYPE Command
The TSX-Plus TYPE command has the same form and options as the RT-ll TYPE
command.

The UCL Command
The UCL command is equivalent to the SHOW COMMANDS command.

The UNPROTECT Command
The UNPROTECT command is used to clear file protection status. The TSX-Plus
UNPROTECT command has the same form and options as the RT-ll UNPROTECT command.

The USE Command
---The USE command displays the accumulated connect time and CPU usage since
log-on.
Example:
.USE
Connect=02:25:00

CPU=OO:02:19

The WHO Command
The WHO command is used to display information about the system status and
logged-on jobs. The WHO command is equivalent to the SYSTAT command.

The $STOP Command
The $STOP command is used to halt the execution of TSX-Plus. On some hardware
configurations, this may also reboot RT-ll. The form of the command is:
$STOP
The $STOP command forces an immediate logoff of all users before stopping
TSX-Plus. Operator privilege is required to use this command. If other users
are logged on, the system will request verification before stopping.
Any

-72-

Keyboard Commands
response beginning with "Y" or "y" will halt TSX-Plus; any other response will
return to the monitor. For example:
.$STOP
Other users are logged on.
Are you sure you want to stop the system?!
Connect=Ol:14:22

CPU=OO:11:15

The $SHUTDOWN Command
The $SHUTDOWN command is similar to the $STOP command in that it is used to
stop TSX-Plus ,and may return control to RT-ll. However, it differs from $STOP
in the manner in which it stops TSX-Plus. $STOP forces the immediate logoff of
all users, $SHUTDOWN does not. Rather, it sets a flag which prevents any new
users from logging on and then waits for all logged on users to log off. When
the last user logs off, TSX-Plus is stopped and control may return to RT-ll.
The form of this command is:
$SHUTDOWN
Operator privilege is required to use this command.
2.5 RT-ll Commands not supported by TSX-Plus
The following RT-ll keyboard commands are not supported by TSX-Plus and are
ignored if issued: CLOSE, GT, INSTALL, LOAD, REMOVE, RESUME, SUSPEND, UNLOAD.
The following RT-ll keyboard commands are not supported by TSX-Plus and will
result in the "Unrecognizable command" error message: ABORT, B, D, E, FRUN,
GET, REENTER, SAVE, SRUN, START.
The following keyboard
TSX-Plus: BOOT, RESET.

commands

have

different

effects

under

RT-ll

and

The following switches are not supported by TSX-Plus with the DIBOL,
COMPILE/DIBOL or EXECUTE/DIBOL commands: /BUFFERING, /LOG, /PAGE, or /TABLES.
The following SET options are not supported by TSX-P Ius: EL, EXIT, or USR.
The following SET TT options are not supported by TSX-Plus: CONSOL, [NO]CRLF,
[NO]FB, or WIDTH.

-73-

-74-

3. COMMAND FILES

Certain series of keyboard commands may be executed together regularly, or may
be so complex that it is desirable to edit and proofread them before execution.
These needs are met by the facility known as indirect command files. These are
files containing a set of keyboard commands to be executed together. Command
files are invoked by providing the file name preceded by an "@" symbol in
response to the keyboard moni tor prompt.
Command files may also be invoked
without the "@" if their names do not conflict with system commands. See the
description of keyboard command interpretation in Chapter 2 for more information on how command files may be initiated.
TSX-Plus allows the specification of parameter strings to be inserted in a
command file. The parameters are stored by TSX-Plus and inserted in the text
of the command file at selected points as the command file is processed.
TSX=Plus also allows program data as well as system commands to be placed in a
command file. Under TSX-Plus it is possible to set up a command file so that
any request for data from device "TT" comes from the command file. This allows
EDIT and TECO (but not KED) commands to be placed in a command file.
Command files may be executed either using normal TSX-Plus interpretation or
under the control of the IND utility.

Either type of control may be specified

either implicitly or explicitly. The keyboard command SET KMON [NO]IND selects
the desired implici t control of command files.
If KMON is set IND, then
command files will normally execute under the control of the IND program. If
KMON is set NOIND, then command files will normally execute under TSX-Plus
control.
Regardless of the setting of KMON, a file may be executed under
control of IND by typing:
IND file
Regardless of the setting of KMON, a file may be started as a normal command
file (not under the control of IND) by typing:
$@ file
Examples:
1.

Execute the command file DK:DAILY.COM under
utility regardless of the setting of KMON:

control

the

IND

.IND DAILY
2.

Execute the command file DLl:WEEKLY.COM under normal TSX-Plus control
regardless of the setting of KMON:
.$@DL1:WEEKLY

-75-

Command Files
3.1 Invoking command files
A command file is invoked by typing:
@filename [paraml [param2 ••• [param6))))))
where "filename" is the name of the command file and "paraml", "param2", etc.
are optional parameter string arguments to the command file.
The default
extension for a command file is "COM".
When the name of a command file does not conflict with a system command, the
command file may be invoked by typing:
filename [paraml, ••• param6)
That is, the "@" may be left out. With or without the "@" sign, if no device
is specified device "DK" is first searched for the command file. Then, only
without the n@" sign, if the named file is not found, then TSX-Plus attempts to
locate the command file on device "SY". See Chapter 2 for a description of the
steps used by TSX-Plus to interpret keyboard commands.
Listing control for
command files differs whether the "@" sign is used or not. If the "@" is used,
then listing is controlled by the current value of the SET TT [NO)QUIET option.
If no "@" is used, then listing is disabled -- as if a SET TT QUIET had been
issued.
In either case, the command file itself can control its own listing
status with a SET TT [NO)QUIET command or with the control characters described
later in this chapter.
3.2 Parameter strings
Parameter strings are normally delimited by spaces.

Thus in the command:

@TSTRUN ABC 123.45 2/3
the string "ABC" is parameter 1, "123.45" is parameter 2 and "2/3" is parameter
3. In some cases it may be desirable to include spaces as part of a parameter
string.
If this is to be done, the first parameter must begin with the
character "\" (left leaning slash), and the left-slash must be used as the
parameter delimiter rather than spaces. For example, in the command line:
@TSTRUN \A STRING\OF PEARLS
parameter 1 is "A STRING" and parameter 2 is "OF PEARLS".
Up to six parameter strings may be specified when the command file is started.
The total number of characters in the combined parameter strings may not exceed

60.

-76-

Command Files
Parameter strings are inserted into the command file during execution at
locations specified by an up-arrow ( ........ ).
The parameter to be inserted is
designated by a digit (1 to 6) immediately following the ......... During execution
of the command file, the "up-arrow-digit" sequence is replaced by the parameter
string passed to the command file in the position specified by the digit. If a
parameter string is called for that was not specified when the command file was
invoked, the up-arrow-digit will be ignored and no characters will be inserted
in their place.
For example, consider the following command file named
TEST.COM:
R .. 1
.... 3= ... 2
When this command file is invoked with the following command:
@TEST FORTRAN PROG
the command file is executed as if it contained the commands:
R FORTRAN
=PROG
Command files may be nested.
That is, one command file may call another
command file.
When such a call occurs, the parameter strings for the outer
level (calling) command file are stored on a stack in TSX-Plus and then the
parameter strings for the called command file are set up.
When the called
command file finishes, the parameters for the calling command file are
restorea.
The maximum depth of nesting 18 governed by the size of the
parameter string stack and the length of the actual parameter strings.
A
nesting depth of 3 can be reached even with very long parameter strings. If no
parameters are specified, the nesting depth may go to about 7 levels.
The command file listing status (SET TT [NO]QUIET) is also stacked as command
files are nested. This means that an inner nested command file may have its
listing turned on or off. When its execution is completed and control returns
to the next outer level command file, the listing control is reset to the state
in effect when the inner command file was called. This is not done for the
outer-most command file, however, so the SET TT [NO]QUIET state in effect on
completion of the outer level command file remains in effect when control is
returned to the keyboard monitor.
3.3 Comments in command files
Comments may be included in command files following an exclamation point ( .. !").
Anything on a line in a command file following an exclamation point will be
treated as comment. For example, in a command file containing the lines:

-77-

Command Files
DISPLAY Watch out! Files may be destroyed.
PAUSE Hit RETURN to proceed
!Requires operator response
the resulting output would be:
Watch out
PAUSE Hit RETURN to proceed

When an exclamation mark (It! It) is used in a command file line to be input as
data to a program, then the exclamation mark and all text following it on the
input line are not passed to the program.
3.4 Command file control characters
Several combinations of characters take on special meaning when they are found
within a command file. The up-arrow character ( ....... ) followed by a letter is
replaced by the control character corresponding to the letter specified. Thus
..... C.. becomes control-C. The escape character may be represented by up-arrow,
dollar sign ( ..... $ .. ). The up-arrow character itself may be represented in the
command file by preceding it with another up-arrow (nAArt).
Several character combinations act as special commands to influence the
These commands take effect at the point of
execution of the command file.
their occurrence in the command file.
The characters in these special
sequences are not passed to programs.
Command
Sequence

Function

... (

Stop listing command file. This has the same effect as SET TT
QUIET, except that it only applies to the current command file.

Start listing command file. This has the same effect as SET TT
NOQUIET except that it only applies to the current command file.

Suppress all terminal output. Both the command file listing and
any program terminal output are suppressed. The ..... ( .. and '''')''
command sequences restart program generated output •

... )

Accept all terminal input from the command file. Command file
data is normally only passed to programs which request lines of
input (using the EMT calls:
.GTLIN, .CSISPC and .CSIGEN).
RT-ll handles command file data in this manner. Programs called
by a command file which request terminal input with the EMT
calls .TTYIN or .READ normally still expect to get this from the
terminal and cannot use command file data as input to these
requests.
The ..... ).. command sequence causes all subsequent
requests for terminal input to come from the--command file
regardless of which EMT is used. This allows data for appli-

-78-

Command Files
cation programs to be placed in a command file. It also allows
commands for TECO and EDIT to be placed in a command file. This
command only affects input requests that occur after TSX-Plus
reads the ...... >.. sequence. See also the description in Chapter 6
of the "N" and "0" program controlled terminal options that
affect command file input •

.. <

Return to standard data mode. Subsequent command file data will
only be passed to programs which do .GTLIN, .CSISPC or .CSIGEN
EMTs (standard RT-ll mode) •

.. Z

Control-Z is translated to control-C in command files.

3.5 PAUSE Command
The PAUSE command is provided to suspend the execution of a command file while
the operator performs some manual operation. The form of the PAUSE command is:

PAUSE comments
where "comments" may be any string of characters. When a PAUSE command is
executed, the PAUSE command is displayed at the terminal followed by"»".
Execution of the command file is then suspended until carriage return is typed.

3.6 DISPLAY Command
The DISPLAY command causes a line of text to be displayed at the terminal.
form of the DISPLAY command is:

The

DISPLAY comments
where "comments" may be any line of text to be printed at the terminal. This
is useful to mark progress through command files running in "quiet" mode (not
being listed).

-79-

-80-

4. VIRTUAL TIME-SHARING LINES AND DETACHED JOBS

4.1 Virtual Lines
TSX-Plus provides a facility known as "virtual lines" which allows one
time-sharing user to simultaneously control several running programs from a
single terminal. When initially logging on to TSX-Plus, the user is connected
to the "primary" time-sharing line, also called virtual line number 0 (zero).
At any time, the user may switch to a different virtual line. This has the
effect of logically disconnecting the time-sharing terminal from the current
virtual line and connecting it to a different logical line. Note that when
normal priority jobs are disconnected from a terminal by switching to a virtual
line, the priority of the disconnected job is reduced by an amount selected
during system generation. Jobs in either the fixed-high- or fixed-law-priority
ranges do not suffer this priority reduction.
If a program is running when the switch is made, its execution is not affected
(but it is given a lower CPU priority). If a program is running on a line that
is not not currently connected to the terminal and that program writes output
to the terminal, the output is not displayed at the terminal, but is instead
stored in a terminal output buffer. When this buffer is filled, the program is
suspended (and the job may be swapped out of memory) until the terminal is
reconnected to the virtua~ ~1ne. On a disconnected virtual line, if the output
buffer becomes full or if a program requests terminal input, the bell is rung
on the line which is currently connected to the terminal to indicate that a
virtual line needs service.
To swi tch to a virtual line, type control-W (hold down CTRL key and press W)
followed by a single digit (do not hold down CTRL while typing the digit). The
digit identifies which virtual line the user wishes to access= Other, users may
be using virtual lines of the same relative number without conflict.
The
CTRL~W digit sequence may be entered at any time - even in the middle of a line
of input. The command takes effect immediately and leaves the old line in an
undisturbed state. (On later return to the primary line, CTRL-R may be used to
display a partial input line which had already been typed.) TSX-Plus responds
to CTRL-W, digit by printing "n)" on the terminal, where "n" is the relative
number of the virtual line that has just been accessede Note that the relative
virtual line number does not correspond to the job number. The SYSTAT command
may be used to determine the job number and, for virtual lines, to determine
the primary line from which virtual lines were started and their virtual line
numbers relative to the primary line. The primary line can always be accessed
with the sequence "<CTRL-W)O", since the primary line is virtual line number O.
(Note that the system manager may select a signal character other than
control-W to indicate a request to switch to a virtual line.)
If a start-up command file was specified for the primary line, it will also be
executed when the virtual line is initiated. If the LOGON program is run as
part of the start-up command file for a virtual line, it will automatically log
the user on to the account specified when logging onto the primary line.
Therefore, logical assignments made in a start-up or LOGON command file are
defined for the vi rtual line.
However, other logical assignments are not
inherited by the virtual line.
Any user defined commands in effect for the
primary line are inherited by a virtual line when it is started.

-81-

Virtual Lines & Detached Jobs
The user logs off a virtual line by typing the "OFF" command. When a user logs
off a virtual line other than the primary line, that virtual line is returned
to the pool of free lines and the user is automa tically reconnec ted to the
primary line. When a user logs off the primary line, not only is the primary
line released, but any virtual lines the user may have been using are also
released, and the user is disconnected from the system.
Note that it is
possible (and frequently desirable) to switch back and forth between the
primary line and one or more virtual lines without logging off any.
The total number of virtual lines and the maximum number of virtual lines which
any user may utilize at a given time are determined by the system manager. An
attempt to log on to a virtual line number higher than the maximum allowed for
each user, is ignored. The CTRL-W, digit sequence is also ignored if the user
is already connected to the maximum number of virtual lines allowed or if no
free virtual lines are available.
Virtual lines are quite useful in situations where the user wishes to execute a
long "number crunching" job without tying up a line. Simply start the long job
and switch to another virtual line. The CPU priority of the disconnected job
is reduced so that it interferes little with normal time-sharing operations,
but rather "soaks up" idle CPU time. Such low priority jobs run only when no
high priority jobs are running.
The keypad editors KED and K52 use the CTRL-W key to repaint the screen. Under
TSX-Plus, use two successive CTRL-W's to repaint the screen with these editors.
A conflict arises when switching to a virtual line while in a keypad editor and
performing another editing job on the second virtual line. When exiting the
second edit job, the editor automatically restores the terminal from alternate
(application) keypad mode to numeric keypad mode. Then, on returning to the
first editing job, it is not possible to use keypad commands since the keys no
longer generate the correct sequences. To avoid this, either do not use keypad
editors on more than one virtual line simultaneously, or restore the terminal
to alternate keypad mode before returning to the original editing job. To set
either VT-IOO or VT-52 type terminals to the alternate keypad mode, send the
two character sequence "(ESC)=" to the terminal.
4.2 Detached jobs
The TSX-Plus Detached job facility is similar to the virtual line facility:
they both allow a ti1'Jlesharing user to execute several jobs simultaneou'sly. The
major difference between detached jobs and virtual lines is that you may switch
back and forth among virtual lines, but once a detached job is started it is
dissociated from any terminal.
Detached jobs operate more like a "batch"
facility. ALL terminal input for a detached job must come from a command file.
Any terminal output generated by a detached job is discarded.
However,
terminal logging may be enabled for detached jobs to accept their terminal
output; see the SET LOG command.

-82-

Virtual Lines & Detached Jobs
The differences between virtual lines and detached jobs are summarized below.
1.

Wi th virtual lines, terminal communication may be swi tched between
several running jobs. A detached job must receive all its terminal
input from a command file and any terminal output it generates is
discarded (unless terminal logging directs the output to a log file).
If a detached job requests ~erminal input and is unable to obtain it
from a command file, the job is terminated.

Virtual lines are "owned" by a physical line. When the physical line
logs off, the virtual lines also log off.
Detached jobs are not
associated with any physical line.
Once started, any or all
time-sharing users may log off without affecting detached jobs.

Detached jobs may be started automatically when TSX-Plus is initiated. Virtual line jobs must be started by time-sharing users after
TSX-Plus is running.

When a detached job reaches the end of its command tile and asks for
more terminal input, the job is aborted and the detached job slot is
freed. Virtual lines wait for more input.

There are three ways to start detached jobs:
1) during system generation
specify a command file to be started as a detached job whenever TSX-Plus is
started; 2) use the keyboard DETACH command; 3) use the TSX-Plus EMT to start a
oeLached JOD from a running program.
Detached jobs that are initiated
automatically when the system is started run with operator privilege. Detached
jobs initiated by use of the DETACH command or the EMT inherit the privilege of
the user starting them.
4.2.1 The DETACH command.
The DETACH command is used to start a detached job, check its status and abort
the job. The system manager may restrict the use of the DETACH command.
4.2.1.1 Starting a detached job: The form of the DETACH command used to start a
detached job is:
DETACH file-spec
where "file-spec" is the name of a command file to be executed as a detached
job.
The default device is "SY:" and the default extension is "COM". The
default disk "DK" is not used because no logical assignments are passed to the
detached job, either in the detach command itself or in the commandfile
started with it. When a request is made to start a detached job, TSX-Plus
searches for a free detached job slot. The total number of such job slots is
established when TSX-Plus is generated. If a free slot is found, the job is
started and a message is printed saying which job slot was used. This number
may be used later to reference the detached job. The SYSTAT command also
indicates detached job line numbers and flags detached jobs with "Det.... A

-83-

Virtual Lines & Detached Jobs
detached job started by use of the DETACH command inherits the privileges (but
not any logical assignments nor any logical subset disks declared after logon)
of the user who is starting the job. If "file-spec" is preceded by the symbol
"@", then the first line of the command file will be used by the detached job,
but any rema1n1ng commands in the file will be associated with the job
currently connected to the terminal.
Neither the DETACH command itself nor the command file started with it inherit
any logical device assignments.
Examples:
1. Start a command file "SY:PURGE.COM" as a detached job •

• DETACH PURGE
Job started on line #9

2. Start a command file named "RKl:STATS.NEW" •
• DETACH RKl:STATS.NEW
Job started on line #8
3. Start the first line of "SY:MAKIT.COM" as a detached job,
and use subsequent lines as an ordinary command file •
• DETACH @MAKIT
Job started on line #9
The system manager determines the number of slots available for detached jobs
and who may use detached jobs. The job numbers assigned to detached jobs start
after the slots reserved for primary time-sharing lines.
Virtual lines are
assigned line numbers above any slots reserved for detached jobs.

4.2.1.2 Checking the status of a detached job:
used to check the status of a~etached job is:

The form of the DETACH command

DETACH/CHECK line-number
where "line-number" is the job slot number listed when the job was started.
TSX-Plus displays the status (active or free) of the detached job.
Examples:
1. Check the status of the job on line #4 •
• DETACH/CHECK ~
Line is active

-84-

Virtual Lines & Detached Jobs
2. Check the status of the job on line #5 •
• DETACH/CHECK 5
Line is free

4.2.1.3 Aborting a detached job:
a running detached job is:

The form of the DETACH command used to abort

DETACH/KILL line-number
where "line-number" is the job slot number listed when the job was started.
For example, to kill the detached job on line #4:
.DETACH/KILL 4
Job aborted

4.2.2 Detached job control EMTs.
TSX-Plus provides a set of EMTs that can be used to control the operation of
detached jObs. Using these EMTs 1t 1S possible to start a detached job, kill a
detached job and check the status of a detached job.
4.2.2.1 Starting A Detached Job: This EMT can be used to start the execution
of a detached job:- The form of the EMT is:
EMT

375

with RO pointing to the following argument block:
• BYTE
•WORD

0,132
name-address

where "name-address"

is the address

of an area containing the name of the

command file to be started as a detached job:

The command file name must be

stored in ASCIZ form and may contain an extension. If a free detached job line
is available, the specified command file is initiated as a detached job and the
number of the detached job line is returned in RO. A detached job started by
use of this EMT inherits the privileges of the job that is executing the EMT.
If there are no free detached job lines, the carry bit will be set on return.
Example:
• TITLE
.ENABL

STRTDJ
LC

;Start a job on a TSX-Plus detached line
CR
LF
ERRBYT

15
12
52

-85-

Virtual Lines & Detached Jobs
.MCALL

.ENTER,.WRITW,.CLOSE, .PRINT,.EXIT

START: CLR
Rl
;Channel number
;No .FETCH is necessary under TSX-Plus, handlers are always resident.
1$:
.ENTER #AREA,Rl,#FILRSO,#1
;Open a one block file
ion first free channel.
BCC
;Branch on successful .ENTER
2$
TSTB
@IIERRBYT
;Wby didn't .ENTER work?
BNE
NOROOM
jError = 1 :not enough room for file
INC
Rl
jTry next higher channel
CMP
Rl, til 7
jLast channel? .CDFN not supported by
;TSX-Plus, so legal channels are 0-IS.
BLE
jOK, retry on next channel
1$
• PRINT IINCA
;Ran out of channels
DONE
BR
2$:

.WRITW
BCS
• CLOSE
MOV
EMT
BCS
BR

IIAREA,RI,#COMNDS,II«CMDEND-COMNDS+I>/2>,1I0
WRTERR
jBad write?
Rl
jClose the file
#STRTDJ,RO
jPoint to EMT arguments to
37S
;Start the detached job
DTCHER
;Bad start of detached job?
DONE

NOROOM: • PRINT
BR
WRTERR: • PRINT
.CLOSE
BR
DTCHE~: • PRINT
.EXIT
DONE:

#NER
DONE
#BADWRT
Rl
DONE
IIBADDET

AREA:
.BLKW
STRTDJ: • BYTE
• WORD
.NLIST
FILRSO: .RADSO
FILNAM: .ASCIZ
COMNDS: .ASCIZ
CMDEND:
NER:
.ASCIZ
.ASCIZ
NCA:
BADWRT: .ASCIZ
BADDET: .ASCIZ

S
;EMT Argument area
0,132
;EMT arguments to start a detached job
FILNAM
;Pointer to name of command file
BEX
/SY CKSTATCOM/ ;RADSO name of command file to be detached
/SY: CKSTAT. COM/ ;ASCII name of command file to be detached
/R CKSTAT/<IS><12> ;Start a monitoring program

.END

;Not enough room error
; • WRITW error
;STRTDJ error

/?STRTDJ-F-Not enough room for command file./<7>
/?STRTDJ-F-No channels available for command file./<7>
/?STRTDJ-F-Error writing command file./<7>
/?STRTDJ-F-Error starting detached job./<7>
START

-86-

Virtual Lines & Detached Jobs
4.2.2.2 Aborting a detached job:
The form of the EMT is:

EMT

This EMT may be used to abort a detached job.

375

with RO pointing to the following argument block:
• BYTE
.l~ORD

2,132
job-number

where "job-number" is the job number of the detached job to be killed. If the
job number is not valid for detached jobs, the carry flag will be set on return
and the EMT error byte will be set to 1.
Example:
.TITLE
.ENABL

CKABDJ
LC

Check status of a detached job and abort it if running
•MCALL

.EXIT,.PRINT

START:

MOV
EMT
BCC
• PRINT
.EXIT

tlSTATDJ,RO
375
1$
IINOTON

;Point to EMT arg block to
;Check status of a detached job
;If still on, kill it
;Else, say it isn't active

1$:

MOV
BCS

IIABRTDJ,RO
375
ABERR

ePRINT

IIKILLED

;Point to EMT arg block to
;Abort detached job
;Since we checked, should never err
;Say we killed it

EMT
.EXIT
ABERR:

• PRINT
.EXIT

• ASCIZ

;EMT arg value to check detached job status
1,132
;Line number of detached job to be checked
9.
2,132
;EMT arg value to abort a detached job
;Line number of detached job to be killed
9.
BEX
/?CKABDJ-F-Invalid detached job number/<7>
/?CKABDJ-I-No detached job on line 119/<7>
/Detached job on line *9 killed.!

.END

START

STATDJ: .BYTE
•WORD
ABRTDJ: .BYTE
•WORD
.NLIST
ABERMS: .ASCIZ
NOTON: .ASCIZ
KILLED:

IIABERMS

-87-

Virtual Lines & Detached Jobs
4.2.2.3 Checking the status of a detached job: This EMT may be used to check
the status of a detached job.--The form of the EMT is:

EMT

375

with RO pointing to the following argument block:
• BYTE
• WORD

1,132
job-number

where "job-number" is the number of the detached job to be checked. If the
detached job is still active the EMT returns with the carry-flag cleared. If
the detached job has terminated and the detached job line is free, the EMT
returns with the carry-flag set.
Example:
See the example program CKABDJ in the previous section.

-88-

5. DEVICE SPOOLING

5.1 The concept of device spooling
Device spooling is a technique that provides more efficient use of slow
peripheral devices. Data sent to spooled devices is automatically redirected
to a high speed disk file for temporary storage and sent to the slow device
when it is ready to accept it. This allows a program generating data for the
spooled device to continue processing without being slowed down by the
peripheral. TSX-Plus optionally provides automatic spooling to output devices
such as printers, card punches and plotters. Several devices may be spooled on
a system.
When a program directs output to a spooled device, the output is diverted by
TSX-Plus to a spool disk data file. An entry is made in a spool file table
indicating a spool file is ready for the spooled device. When the spooled
device becomes free, the spool file is copied by TSX-Plus to the device. All
of the processing is automatic and the user does not have to be concerned with
its operation.
In fact, a user can run programs without waiting for their
output to be printed. Devices to be spooled must be declared when the system
is generated.
Spooled device handlers such as LP must be set to the "HANG" mode of operation
to work properly with the TSX-Plus spooler.
This can be done with the SET
command. For example:
.SET LP HANG
Since the SET command actually stores this information permanently In the disk
copy of the device handler, it need only be issued once.
5.2 Directing output to spooled devices
Output is directed to a spooled device in exactly the same way it would be
directed to the device if it were not spooled.
For example, if the line
printer (LP) were spooled, the following commands would send a FORTRAN listing
to the printer:
.R FORTRA
*TEST,LP:=TEST
The name of a spooled device may be used in a MACRO .ENTER command just as a
non-spooled device would.
Any number of users may simultaneously write to a spooled aevice without
conflict.
TSX-Plus separates the output from each user and prints it in an
orderly fashion. A user may direct output through several I/O channels to the
same or different spooled devices.
5.3 Operation of the spooler
The spooling system consists of a memory resident spool file control table
which contains information concerning the user's spool file and a single system

-89-

Device Spooling
managed spool data disk file which contains the user's intercepted output.
Every time a user opens an output channel to a spooled device, a new entry is
created in the spool file control table.
Output records directed through
separate channels to the same device have separate entries in the spool file
control table.
Placement in this table is governed by the processing of the
user's open request for the spooled device.
The total number of spooled files that may be in existence is specified when
TSX-Plus is generated. A spooled file is created when an I/O channel is opened
to a spooled device; the file remains in existence until all of the output is
processed by the spooled device.
If a program opens a channel to a spooled
device and the spool file control table already contains the maximum number of
spooled files, the program is suspended until a slot becomes available in the
spool file control table.
All output directed to spooled devices is stored in a common disk data file.
The total file space that is available for spooled data is specified when the
TSX-Plus system is generated.
Space within this disk file is dynamically
allocated as needed on a block by block basis. Each block contains 508 bytes
of user's output data. Therefore, write requests smaller than 508 bytes will
be combined into one spool data block. A write request larger than 508 bytes
will be split into more than one spool data blocks. If the spool data file is
totally filled, programs writing to the spooled device will be suspended until
space becomes available.
Actual output to the spooled devices is processed on a sequential firstin/first-out basis. Since output is actually coming from the disk file, each
I/O request to the device handler is the size of the spool data block (508
bytes).
While spooled files are being printed, TSX-Plus maintains a list of
the blocks most recently printed. The length of this list is specified by the
number of backup blocks declared during system generation.
When the list
becomes full, the oldest block is deallocated and the new block is added. When
the entire spooled file has been successfully written, the entire list is
deallocated.
5.4 The SPOOL Command
The SPOOL command is used to control the operation of the spooling system.
form of the SPOOL command is:

The

SPOOL device,function,parameter
where "device" is the name of a spooled device, "function" indicates the
operation to be performed, and "parameter" is an optional item of information
used with some functions. Each of the available functions is described below.
The FORM and LOCK Functions
The FORMand LOCK functions are used to specify the name of the currently
mounted form.
The form name is specified in the "parameter" field of the
command.
The FORM fURction allows TSX-Plus to request a form mount when a
-90-

Device Spooling
different form is needed. The LOCK function specifies that the form is to be
locked on the printer and disables form mount request messages.
Examples:
.SPOOL LP,FORM,BILLS
.SPOOL LP,LOCK,BILLS
.SPOOL LP,FORM,STD
Note the difference between the FORM keyboard command and the SPOOL command
with the FORM or LOCK functions. The FORM command is used by the TSX-Plus user
to specify the default form name to be used for subsequent spool files. The
SPOOL FORM/LOCK commands are used by the TSX-Plus operator to tell the spooling
system which form is currently mounted.
The ALIGN Function
The ALIGN function is used to print a form alignment file on a spooled device.
The name of the alignment file is specified in the "parameter" field of the
command. The default file extension for form alignment files is "ALN".
Examples:
• SPOOL
• SPOOL
• SPOOL

LP,ALIGN, BILLS
LP,ALIGN,RK1:PAYROL.DAT
LP,ALIGN,DX:RPORT2

The DELETE Function
The DELETE function is used to abort printing of the file curr~ntly being
printed on the indicated spooled device. The spooler waits for the most recent
I/O request to complete before deallocating all disk data blocks associated
with the deleted spool file.
The DEL function has no effect if no file is
currently being printed.
Examples:
.SPOOL
.SPOOL

LP,DELETE
LS,DELETE

The SKIP Function
---------The SKIP function causes the spooler to skip over the next n blocks in the
spool file that is currently being printed, where E. is specified in the
parameter field of the instruction. Each block in the spool data file contains
508. characters. Printing of the file continues after the indicated number of
blocks have been skipped.

-91-

Device Spooling
Examples:
.SPOOL
• SPOOL

LP,SKIP,lO
LP,SKIP,lOO

The BACK Function
The BACK function causes the spooler to skip backward in the spool file a
number of blocks and then resume printing at that point. The number of blocks
involved is specified when TSX-Plus is generated. Each block in the spool data
file contains 508. characters.
This function is particularly useful for
recovering from paper tears or remounts. The spooler will finish printing the
current block before backing up.
Examples:
.SPOOL
• SPOOL

LP,BACK
LS,BACK

The STAT Function
The STAT function is used to determine the status of a spooled device.
Information returned includes: the condition of the spooler (active, idle, or
waiting for a form mount); the name of the currently mounted form; and
information about files waiting to be printed on the device. The SHOW QUEUE
command may also be used to display information about files in the spooler
queue.
Example:
.SPOOL LP,STAT
Spooler idle
Currently mounted form = STD
No files in queue
The SING and MULT Functions
The SING and MULT functions control how the spooler will handle multiple files
queued for the same form.
In "MULT" mode (the initial setting) no form mount
request message is generated if a spool file is found that needs the currently
mounted form. Processing of the file begins automatically.
In "SING" mode a form mount request is generated for every file even if the
file needs the currently mounted form. This is useful where equipment setup or
form alignment is needed for every file.
Examples:
.SPOOL
.SPOOL

LP,SING
LP,MULT

-92-

Device Spooling
I

The HOLD and NOHOLD Functions
Aspoolecf(fevi ce that is in the HOLD mode will not begin to process a spool
file until the file is completely created and the I/O channel associated with
the file is nlosed. A spooled device that is in NOHOLD mode will begin to
process a spool file as the file is being created. In NOHOLD mode, the spooler
will begin to process a file sooner; however, if the file is being created
slowly, the spooled device will remain busy (and unavailable to other users)
for as long as it takes to finish generating the file. If the spool storage
file is completely filled, the spooler will attempt to free space by beginning
to process open spool files even if HOLD is in effect.
The default [NO]HOLD mode is established when the TSX-Plus system is generated.

A (NO]HOLD command remains in effect until another [NO]HOLD command is issued
or the system is restarted.
Examples:
.SPOOL

LP,NOHOLD

.SPOOL LP,HOLD
It is also possible to dynamically request that a file being printed through
the spooler be either held until the file is closed or begin printing as data
is made available from the program. This could be used in a situation where
NOHOLD is the normal condition, but a program which uses the printer generates
data slowly.
If data were passed to the printer as soon as available, then
printer output from all other jobs would be delayed until the slow job closes
the output.
This can be avoided by the having the slow program selec t hold
mode for its output. Tnen, other jobs can proceed to use the printer without
being delayed by the slow job. The form of the EMT to select hold or nohold
mode on an individual file basis is:

EMT

375

with RO pointing to the following argument block:
• BYTE
• WORD
• WORD

chan,151

flag

where "chan" is the channel number which has been used to open the print file
and "flag" indicates whether the file is to be printed as it is generated or
held until the file is closed. If "flag"=O, the output is printed as generated
(equivalent to NOHOLD); if "flag"=l, then the output is not printed until the
file is closed. This EMT must be issued after a channel has been opened to the
printer (through the spooler), but before any data has been written to it. If
the channel is open to any non-spooled device; then the EMT is ignored.

-93-

Device Spooling
Example:
.TITLE
.ENABL

SPHOLD
LC

Demonstrate the EMT to hold spooler output until the file is closed
•MCALL

.CSISPC,.LOOKUP,.READW,.WRITW,.CLOSE,.EXIT
;EMT error code byte location
.CSISPC #OUTSPC,#DEFEXT,#O
;Get name of file to copy
BCS
START
jProceed unless error
MOV
#INSPC,Rl
jPoint to first input filspc
OPNFIL: .LOOKUP IIAREA, 110, Rl
jTry to open input file
BCS
START
;Get a new command on error
MOV
IIOUTSPC, R2
jPoint to output filspc
I/ . . RLP , (R2)+
MOV
;Put LP: in output filspc
ADD
112, Rl
jPoint to input filspc filename
MOV
(Rl)+, (R2)+
;Move file name into LP filspc
(Rl )+, (R2)+
; (not necessary, but convenient)
MOV
TST
(Rl)+
;Skip over file extension
;Open channel to printer (spooled)
•LOOKUP #AREA,#l,#OUTSPC
BCC
NOHOLD
;Proceed unless error
;Close input file
GIVEUP: .CLOSE #0
.EXIT
;And give up
ERRBYT
START:

= 52

Tell spooler to hold file until it is closed
(must be issued before any writes to file)
NOHOLD: MOV
EMT
CLR
.READW
6$:
BCS
.WRITW
BCC
• CLOSE
BR
INC
8$:
BR
NXTFIL:- • CLOSE
• CLOSE
TST
BNE
BR

#SPHOLD,RO
;Point to EMT arg block to
375
;Hold output until close
R2
jInitialize block pointer
#AREA,#0,#BUFFER,#256.,R2 ;Copy a block from the file
NXTFIL
;Try next file on error
#AREA,#1,#BUFFER,#256.,#0 ;Copy the file block to LP
8$
jError?
#1
;Close print file
GIVEUP
jForget it
R2
jPoint to next block
Q$
jAnd get next block
#0
;Close input file
#1
;and print file
2(Rl)
jAny input file?
OPNFIL
jRepeat if so
START
;Else ask for more files

AREA:
.BLKW
SPHOLD: • BYTE
•WORD
HNH:
• WORD
OUTSPC: .BLKW

10
1,151

15.

;General EMT arg block area
;EMT arg block to hold spool output
jon channel 1 until file is closed
jHNH=O immed; HNH=l hold til close
jOutput file specs

-94-

Device Spooling
INS PC : • BLK'"w
DEFEXT : . WORD
BUFFER: .BLKW
.END

24.
0)0,,0,0

256.
START

;Input file specs
;No default file types
;I/O buffer area

5.5 Use of special forms with spooled devices
Output files directed to spooled devices are queued and held until the spooled
device becomes free.
Because of this, a special procedure is required to
synchronize the mounting of a special form with the printing of a file that
requires the form.
it the t1rst character in a tile directed to a spooled device is a right square
bracket ( .. ] .. ), TSX-Plus will interpret the folluwing one to six characters in
the file as the name of the form on which the file should be printed. Form
names may be from one to six characters in length and must be specified
immediately following the initial square bracket character. The form name must
be terminated with a carriage return, line feed. Square bracket characters are
not significant to the spooler in any position other than the first character
of the file.
If a spooled file does not begin wi th a right square bracket character,
TSX-Plus uses the form name that was last specified by the user with a FORM
command (see Chapter 2).
If no FORM command has been issued by the user,
TSX-Plus uses the form name "STD" for the file.
Each time TSX-Plus selects a file to be printed on a spooled device, it first
looks for a waiting file that requires the form currently mounted on the
spooled device.
If several such files are available, the oldest one is
started.
If no file can be found that requires the currently mounted form,
TSX-Plus selects the oldest file requiring a different form and issues a form
mount request. The message appears on the the operator's terminal as:
"Mount 'xxxxxx' form on dd"
where "xxxxxx" represents the form name and "dd" is the spooled device.
The
terminal to which the message is directed is the one declared as the operator's
console when the TSX-Plus system was generated.
Once the form mount request message is sent, the spooler for the device
requiring the new form is suspended.
In order to restart the spooler the
operator must issue a SPOOL-FORM or SPOOL-LOCK command.
These commands tell
the spooler that a particular form has been mounted and is ready for use. The
operator does not have to mount the form called for in the form mount request.
He may mount any form he desires, in which case TSX-Plus will search for a
spool file that needs the form actually mounted.
The SPOOL-FORM and SPOOL-LOCK commands are both used by the operator to
indicate which form has been mounted; however, there is a difference in the
effect of the two commands. After processing all files that need the currently

-95-

Device Spooling
mounted form, TSX-Plus checks for files requiring a different form. If there
are any, it checks to see if the current form was mounted using a SPOOL-FORM or
SPOOL-LOCK command. If a SPOOL-FORM command was used, TSX-Plus issu,es a form
mount request message.
If a SPOOL-LOCK command was used, TSX-Plus considers
the current form to be locked on the printer and does not issue a form mount
message; rather, it waits for new spool files to be created that need the
currently mounted form.
5.6 Form alignment procedure
iolhen mounting a new form it is usually necessary to verify the correct
positioning of the form before starting production printing on the form. The
SPOOL-ALIGN command provides this facility.
The SPOOL-ALIGN command allows the TSX-Plus operator to specify a form
alignment file to be printed on the indicated spooled device. Form alignment
files are printed immediately without regard to the name of the currently
mounted form.
The SPOOL-ALIGN command may be issued repeatedly if several
attempts are required to mount a form.
Alignment files are created by the user and may contain any desired information.
Typically they contain a short sample output file that matches a
particular form. Alignment files should not contain a form name specification.
The normal sequence of operations involving a form mount is as follows:
1.

TSX-Plus
spooler.

issues

form-mount

request

message

and

suspends

the

The operator mounts the desired form and issues one or more SPOOLALIGN commands to verify its positioning.

Once the form is correctly positioned, the operator issues a
SPOOL-FORM or SPOOL-LOCK command to tell TSX-Plus which form has been
mounted.

TSX-Plus begins
mounted form.

printing the oldest file that needs the currently

The SPOOL-ALIGN command may be issued at any time, but it is typically used
between a form-mount message and a SPOOL-FORM or SPOOL-LOCK command.

-96-

6. PROGRAM CONTROLLED TERMINAL OPTIONS

6.1 Terminal input/output handling
The terminal keyboard and screen provide the principal interface between a
time-sharing user and the TSX-Plus operating system~
TSX-Plus accepts
characters from the keyboard, echoes them to the screen, and stores them in a
separate buffer for each time-sharing user.
Then, when a program (either a
user written program, or a utility, or the operating system keyboard monitor)
requests input from the terminal, characters are removed from the internal
buffer and passed to the program. The low-level requests for input from a
program can call for a single character (. TTYIN), or for an entire line
(.GTLIN, .CSIGEN, .CSISPC), or for a whole block of characters (.READ). Since
the requests for a whole line of input are most common, TSX-Plus improves
overall efficiency for many users by retaining characters typed at the keyboard
in an internal buffer until a special character is typed which indicates that
the line of input is complete. This special character, which indicates that
keyboard input is ready, is called an activation character.
The standard
activation characters are carriage return and line feed. In addition, several
control keys will also cause immediate system response. For example, control-C
is used to abort the execution of a running program. If the program is waiting
for input, one control-C will cause an immediate abort. If the program is not
waiting for input, it is necessary to type two control-C's to get the system's
attention and abort a programo
vfuen a program requests terminal input, TSX-Plus puts the program in a
suspended state until an activation character is typed. This state, in which a
program is waiting for input, but no activation character has been typed, is
identified as the TI state by the SYSTAT command. When characters are typed at
the terminal, TSX-Plus responds quickly and stores them in the terminal input
buffer for that line, then returns to process other jobs which need its
attention. Thus, the amount of time the CPU spends processing input characters
is kept to a minimum, and the amount of CPU time used by a program in the TI
state is also very small.
Some programs, however, request single charac ters
with the .TTYIN request. Normally, these programs are treated by TSX-Plus just
as those requesting lines of input (e.g.
.GTLIN requests). That is, the job
is suspended,

input characters are stored in the terminal input buffer, and

characters are only passed to the program after an activation character is
typed~
If a program requests a character with a single oTTYIN, the user can
type as many characters as the terminal input buffer will hold (allocated
during system generation), but the program will remain suspended and no
characters are passed to the program. Then, when an activation is typed, the
program is restored to an active state, the first character in the input buffer
is passed to the program and processing continues. If the program requested no
more characters, then on exit the remainder of the input buffer, including the
activation character, would be passed to the next program (usually the keyboard
monitor) which would try to interpret them.
This may result in an invalid
command error message.
TSX-Plus allows the programmer a wide variety of ways to influence the normal
input scheme outlined above.
One of the most common is the use of "single
character activation".
Wi th this technique, all characters are regarded as
activation characters. That is, if a program requests a single character with
a .TTYIN, then as soon as a character is typed and becomes available in the

-97-

Terminal Control
input buffer, it is passed to the program and the program resumes execution.
The standard way to request single character activation under RT-11 is by
setting bit 12 in the user's Job Status Word (JSW).
However, under TSX-Plus,
this is not by itself sufficient to cause single character activation.
The
reason is that quite a few programs designed for a single user environment use
this in a way that causes constant looping back and consequently "burns up" a
large amount of processor time. In a single user environment, this is of minor
importance since no other jobs are trying to use the processor at the same
time.
Of course, in a mul ti -user system, this is wasteful and should be
avoided.
Therefore, under TSX-Plus, set ting JSW bit 12 is not by itself
sufficient to initiate single character activation.
It is necessary BOTH to
set bit 12 and to issue a special command to TSX-Plus indicating that single
character activation is actually desired.
This may be done either by specifying single character activation when running the program (see the /SINGLECt~R
switch described under the R command), or with the SET TT SINGLE command, or
with the "s" program controlled terminal option described in this chapter.
The situation in which a program requests single characters but none are
available in the input buffer also receives special treatment.
The single
character input request is eventually coded as EMT 340.
The. TTYIN request
repeats this request until a character is finally obtained, whereas the .TTINR
request supposedly permits processing to continue if no character is available.
In fact, however, the EMT 340 call will itself suspend the job until a
character is available from the input buffer.
This is referred to as
"stalling" on a • TTYIN.
The purpose is to avoid the unnecessary looping back
to get a character.
Under RT-11, if the programmer decides not to wait for a
character to become available, but rather proceed with execution, it is only
necessary to set bit 6 (100 octal) in the Job Status Word.
Again, some
programs abuse this technique and would waste the system resources in a
time-sharing environment.
So, TSX-Plus requires confirmation that the user is
aware of the extra system load that could be caused by the constant looping
back checking for a character.
This may be done either as a system command
(SET TT NOWAIT), or with the /SINGLECHAR swi tch when running the program, or
wi thin a program by using the program controlled terminal option "U". All of
these methods cause TSX-Plus to honor bi t 6 in the JSW.
If nowai t input is
truly desired under TSX-Plus, it is necessary BOTH to set bit 6 in the JSW and
to tell TSX-Plus to use nowait input (R[UN]/SINGLECHAR, or SET TT NOWAIT, or
the "U" terminal option).
TSX-Plus allQIals many other ways of modifying terminal input and output for
special circumstances.
These are provided to allow maximum versatility in the
system while still maintaining the high efficiency needed in a multi-user
environment.
The programmer communicates the need for special terminal
handling to the system through the use of special "program controlled terminal
options". These are described individually in the next section.

-98-

Terminal Control
6.2 Program controlled terminal options
The following table lists the functions which may be modified during program
execution.
Function
Character

A
B

C
D
E

H
I

L
M
N

o
P

Q
R

s
T
U

W
X

Y
Z

Meaning
Set rubout filler character.
Enable VT52 & VT100 escape-letter activation.
Disable VT52 & VT100 escape-letter activation.
Define new activation character.
Turn on character echoing.
Turn off character echoing.
Disable virtual lines.
Enable lower case input.
Disable lower case input.
Enable deferred character echo mode.
Disable deferred character echo mode.
Set transparency mode for output.
Suspend command file input.
Restart command file input.
Reset activation character.
Set activation on field width.
Turn on high-efficiency TTY mode.
Turn on single~character activation mode.
Turn off single-character activation mode.
Enable no-wait TT input test.
Set field width limit.
Turn tape mode on
Turn tape mode off
Disable echo of line-feed after carriage-return
Enable echo of line-feed after carriage-return

These functions have a temporary effect in that they are automatically reset to
their normal values when a program exits to the keyboard monitor. They are not
reset if the program chains to another program until control is finally
returned to the monitor.
Some terminal options (notably high-efficiency and
single-character modes) ar~ incompatible with and override some other terminal
options.
TSX-Plus provides two methods for a running program to dynamically alter some
of the parameter settings relating to the user's timesharing line.
The
preferred method of selecting these functions is to use the TSX-Plus EMT for
that purpose. This is readily available from MACRO programs and an appropriate
MACRO subroutine should be linked into jobs written in other languages. The
form of the EMT to select program controlled terminal options is:

EMT

375

-99-

Terminal Control
with RO pointing to the following argument block:
• BYTE
• WORD
• WORD

0,152
function-code
argument-value

where "function-code" is the character from the table above which selects the
terminal option, and "argument-value" may be a third value used only with some
of the functions.
An advantage of the EMT method of selecting program
controlled terminal options is that they may be used even when the terminal is
in high-efficiency mode.
Example:
.TITLE
.ENABL

EMTMTH
LC

Demonstrate TSX-Plus program controlled terminal options using
the EMT method •
• MCALL
.GLOBL

.GVAL,.PRINT,.EXIT,.TTYIN
PRTDEC

Determine and display current lead-in char
Default = 35, but don't count on it
START:

• GVAL
MOV
• PRINT
MOV
CALL
• PRINT

fIAREA, 11-4 •

RO,R1
IILEADIS
R1,RO
PRTDEC
f/LEADND

;Determine current leadin character
;Save it
;"Current lead-in is"
;Retrieve lead-in char value
;Display it

Set rubout filler character
MOV
EMT

IISETRUB,RO
375

;Point to EMT arg block to
;Set rubout filler character

Now demonstrate the cu~rent rubout filler character
Back ~pace is the default, which we changed to underline

1$:

2$:

IITRYIT

• PRINT
MOV
.TTYIN
CMPB
BEQ

RO,/112
2$

CMP

R1,IIBUFEND

BLO

• PRINT

#THANKS

fIBUFFER, R1

;"Enter some and delete them"
;Point to input buffer
;Get next char into input buffer
;End of input (CR/LF pair)?
;Yes, terminate input
;Buffer overflow?
;Get more if not

-100-

Terminal Control
.EXIT
.BLKW
SETRUB: • BYTE
• WORD
•WORD
TRYIT: .ASCII
.ASCII
.ASCII
LEADIS: .ASCII
LEADND: .ASCIZ
THANKS: .ASCIZ

AREA:

BUFFER: • BLKB

10
0,152

;General EMT arg block
;EMT arg block to
'A
;Set rubout filler character
; to underline
IEnter some characters at the prompt and then I
lerase them with/<15><12>/DELETE or Control-U.I
I They should be replaced with underlines.I<15><12>1*1<200>
IWe don't care that the current lead-in char is 1<200>
1.1
<15><12>/sTOP -- Thank you.1
81 •

BUFEND:
.END

START

When it is not practical to incorporate the EMT method of selecting program
controlled terminal options into a program, an alternate method using a
"lead-in" character may be used.
This is conveniently done by sending a
sequence of characters to the terminal using the normal terminal output
operations of the language. Examples are the FORTRAN TYPE, COBOL-Plus DISPLAY,
BASIC PRINT, and Pascal WRITE statements. Program controlled terminal options
are selected by having the running program send the lead-in character immediately followed by the function character and for some functions a third
character defining the argument value for the function. TSX-Plus intercepts
the

lead~in

character and the one or two following characters and sets the

appropriate terminal option.
It does riot pass these intercepted characters
through to the terminal. The default value for the lead-in character is the
ASCII GS character (octal value 35; decimal value 29). However, the lead-in
character may be redefined during system generation when the value conflicts
with other uses of the system. For example, some graphics terminals use the GS
character as either a command or parameter value. Programmers should not rely
on the default value of the lead-in character, but may obtain the current value
of the lead-in character from the .GVAL request with an offset of -4. Note
that when in high-efficiency mode (set with either the RUN/HIGH switch or the
"R" program controlled terminal option) output character checking is disabled
and the lead-in character method of selecting program controlled terminal
options is disabled; in this case, the lead-in character, function-code
character, and argument value character are passed through to the terminal.
When in high-efficiency mode, the EMT method of selecting program controlled
terminal options is still functional. See Chapter 7 for information on turning
high-efficiency terminal mode off by means of an EMT.
Example:
PROGRAM LEADIN
C

C Demonstrate TSX-Plus program controlled terminal options using
C the "lead-in" character method.

-101-

Terminal Control
BYTE
LEADIN(2)
INTEGER ILEAD
EQUIVALENCE (ILEAD,LEADIN(l))
C

C Determine and display current lead-in char
C Default = 29, but don't count on it
C

ILEAD = ISPY(-4)
TYPE 820,LEADIN(1)

!.GVAL with offset = -4.
!Display the current lead-in char value

C Set rubout filler character
C

TYPE 800,LEADIN(1),'A','_'
C

C Now demonstrate the current rubout filler character
C Back space is the default, which we changed to underline
C

TYPE 810
ACCEPT 830

!Ask for something to be erased
!Wait for input before exiting

STOP 'Thank you.
800
810
1
1
820
830

FORMAT(lH+,A1,$)
FORMAT(lHO,'Enter some characters at the prompt and then'
'erase them with'/' DELETE or Control-U.',
' They should be replaced with underlines.'/' *',$)
FORMAT(' The current value of the lead-in character is ',13,'.')
FORMAT(40H
)
END

The following paragraphs explain the uses of each of the program controlled
terminal option function-codes. Any of these options may be selected by either
the EMT method or by the lead-in character method.
6.2.i "A" function--Set rubout filler character.
When a scope type terminal is being used, the normal response of TSX-Plus to a
DELETE character is to echo backspace-space-backspace which replaces the last
character typed wi th a space. TSX-Plus responds to a CTRL-U charac ter in a
similar fashion, echoing a series of backspaces and spaces. Some programs that
display forms use underscores or periods to indicate the fields where the user
may enter values. In this case it is desirable for TSX-Plus to echo backspacecharacter-backspace for DELETE and CTRL-U where "character" may be period or
underscore as used in the form.
The character to use as a rubout filler is
specified by the argument-value with the EMT method or by the third character
with the lead-in character method.
6.2.2 "B" & "c" functions--Set VT52 & VT100 escape-letter activation.
VT52 and VT100 terminals are equipped with a set of special function keys
marked with arrows and other symbols. When pressed, they transmit two or three
character escape sequences. The "B" function tells TSX-Plus to consider these
-102-

Terminal Control
as activation sequences. The escape character and the letter are not echoed to
the terminal, but are passed to the user program. The "c" func tion disables
this processing and causes escape to be treated as a normal character (initi~l
setting).
6.2.3 "D" function--Define new activation character.
Under normal circumstances TSX-Plus only schedules a job for execution and
passes it a line of input when an "activation" character such as carriage
return is received.
The "D" function provides the user with the ability to
define a set of activation characters in addition to carriage return.
The new activation character is specified by the argument-value with the EMT
method or by the third character with the lead-in character method.
The
maximum number of activation characters that a program may define is specified
when the TSX-Plus system is generated.
Using this te~hnique, any character may be defined as an activation character,
including such characters as letters, DELETE, CTRL-U, and CTRL-C.
When a
user-defined activation character is received, it is not echoed but is placed
in the user's input buffer which is then passed to the running program.
By specifying CTRL-C as an activation character, a program may lock itself to a
terminal in such a fashion that the user may not break out of the program in an
uncontrolled manner.
If carriage return is)specified as a user activation character, neither it nor
a following line feed will be echoed to the terminal. TSX-Plus will also not
add a line feed to the input passed to the program.
6.2.4 "E" and "F" functions--Control character echoing.
The "E--.oa.rid"~functions are used to turn on and off character echoing. The
"E" function turns it on, and the "F" function turns it off. An example of a
possible use is to turn off echoing while a password is being entered.
6.2.5 "R" function--Disable virtual line use.
The "H":function disables the virtual line facility for the time-sharing line.
6.2.6 "I" and "J" functions--Control lower case input.
The "rn-function allows lower case characters to be passed to the running
program. The "J" function causes TSX-Plus to translate lower case letters to
upper case letters.
The SET TT [NO] LC keyboard command also performs these
functions.
6.2.7 "K" and "L" functions--Control character echoing.
The "K" function causes TSX-Plus to enter "deferred" character echo mode.
ttL"

function causes

TSX-Plus

enter

immediate

character

echo

mode.

The
Any

characters in the input buffer which have not been echoed when the "L" function
is selected will be immediately echoed.
See the description of the SET TT
[NO]DEFER command for an explanation of deferred echo mode.

-103-

Terminal Control
6.2.8 "M" function--Set transparency mode of output.
If transparency mode is set, TSX-Plus will pass through each transmitted
character without performing any special checking or processing. Transparency
mode allows the user's program to send any 7-bit character to the terminal.
Note that once transparency mode is set on, TSX-Plus will no longer recognize
the lead-in character (octal 35, which means a program control function
follows). The only way to turn off transparency mode is to exit to KMON.
6.2.9 "N" and "0" Functions--Control command file input.
When a comman~le is being used to run programs (see Chapter 3), input which
would normally come from the user's terminal is instead drawn from the command
file. Occasionally, it is desirable to allow a program running from a command
file to accept input from the user's terminal rather than the command file.
The "N" function suspends input from the command file so that subsequent input
operations will be diverted to the terminal. The "0'" function redirects input
to the command file. These functions are ignored by TSX-Plus if the program is
not being run from a command file.
6.2.10 "P" function--Reset activation character.
The "p'Tfunction performs the complement operation to the "D" function. The
"P" function is used to remove an activation character that was previously
defined by the "D" function. The character to be removed from the activation
character list is defined by the argument-value with the EMT method or by the
third character with the lead-in character method.
Only activation characters that were previously defined by the "D" function may
be removed by the "P" function.
6.2.11 "Q" function--Set activation on field width.
The "Q'~nction allows the user todefine the width of an input field so that
activa tion wi 11 occur if the user types in as many charac ters as the field
width, even if no activation character is entered.
The field width is
specified by the ASCII code value of the argument-value with the EMT method or
of the third character with the lead-in character method.
If an activation
character is entered before the field is filled, the program will be activated
as usual. Each time activation occurs the field width is reset and must be set
again for the next field by reissuing the "Q" function.
For example, the
following sequence of characters could be sent to TSX-Plus to establish a field
width of 43 characters:
"(lead-in>Q+". Note that the character "+" has the
ASCII code of 053 (octal) which is 43 decimal.
6.2.12 "R·' func tion--Turn on high-efficiency terminal mode.
The "R~unction causes TSX-Plus to place the line in "high efficiency"
terminal mode. The effect of this is to disable most of the character testing
overhead that is done by TSX-Plus as characters are transmitted and received by
the line.
Before entering high-efficiency mode the program must declare a
user-defined activation character that will signal the end of an input record.
Once a program has entered high-efficiency mode, characters sent to the
terminal are processed with minimum system overhead.
For example, tab
characters are not expanded to spaces. Also, TSX-Plus does not check to see if
-104-

Terminal Control
the character being sent is the TSX-Plus terminal control "leadin" character.
This means that the lead-in character method may not be used to control
terminal options until the program exits or the EMT to turn off high efficiency
mode is used (see Chapter 7). Characters received from the terminal are passed
to the program with minimum processing:
they are not echoed; and control
characters such as DELETE, control-U, control-C, control-Wand carriage-return
are all treated as ordinary characters and passed directly to the program.
High-efficiency mode terminal I/O is designed to facilitate machine-to-machine
communication; it is also useful for dealing with buffered terminals that
transmit a page of information at a time.
6.2.13 "S" function--Turn on single-character activation mode.
"S~unction causes TSX-Plus to allow a program to do single-character
activation by setting bit 12 in the Job Status Word. Normally TSX-Plus stores
characters received from the terminal and only activates the program and passes
the characters to it when an activation character, such as carriage-return, is
received.
It does this even if bit 12 is set in the Job Status Word, which
under RT-11 causes the program to be passed characters one-by-one as they are
receivea trom the terminal. The "S" function can be used to cause TSX-Plus to
honor bit 12 in the Job Status Word.
If JSW bit 12 is set and the program is
in single-character activation mode, TSX-Plus passes characters one-by-one to
the program as they are received and does not echo the characters to the
terminal. The /SINGLECHAR switch for the R[UN] command and the SET TT SINGLE
C,ommand can also be used to cause TSX-Plus to honor JSW bi t 12. Since the
high-efficiency mode implies certain terminal characteristics (such as buffered
input and no echo), it is not possible to override these inherent modes by
using other function codes.
The

6.2.14 "T" function--Turn off single-character activation mode.
The "T" function is the complement of the "S" function. It turns off singlecharacter activation mode.
6.2.15 "U" function--Enable non-wait TT input testing.
The "U'~unction causes TSX-Plus toallow a program to do a • TTINR EMT tha t
will return with the carry bit set if no terminal input is pending. Normally
TSX-Plus suspends the execution of a program if it attempts to obtain a
terminal character by doing a .TTINR EMT and no input characters are available.
It does this even if bit 6 of the Job Status Word is set, which under RT-11
would enable non-blocking .TTINR . . s.
This is done to prevent programs from
burning up CPU time by constantly looping back to see if terminal input is
available. The "u" function causes TSX-Plus to honor bit 6 in the Job Status
Word and allows a program to do a .TTINR to check for pending TT input without
blocking if none is available. The SET TT NOWAIT command and the /SINGLECHAR
swi tch for the R[UN] command also perform this function. Because the single
character terminal option determines several terminal operating modes (such as
no echo and transparent input), it is incompatible with other terminal
functions which would conflict wi th the implied single-character operation.
See the description of special terminal mode in the RT-11 Programmer . . s
Reference Manual.

-105-

Terminal Control
6.2.16 "V" function--Set field width limit.
The "V" function is used to set a limit on the number of characters that can be
entered in the next terminal input field. Once the "V" function is used to set
a field limit, if the user types in more characters to the field than the
specified limit, the excess characters are discarded and the bell is rung
rather than echoing the characters.
An activation character still must be
entered to complete the input. The field width is specified by the ASCII code
value of the argument-value with the EMT method or of the third character with
the lead-in character method.
The field size limit is automatically reset
after each field is accepted and must be re-specified for each field to which a
limit is to be applied. Note the difference between the "Q" and "V" functions.
The "Q" function sets a field size which causes automatic activation when the
field is filled; the "V" function sets a field size which causes characters to
be discarded if they exceed the field size.
6.2.17 "w" and "X" functions--Control tape mode.
The "W~u~ion turns on "tape" mode and the "X" function turns it off.
"Tape" mode can be used when a line is connected to a paper tape, cassette
tape, floppy disk or other device that responds to X-ON/X-OFF characters to
start and stop transmission.
Turning on tape mode has three effects:
1) TSX-Plus sends an X-OFF character (CTRL-S) to the terminal when the terminal
input buffer fills to the point that only 10 free character positions remain;
2) TSX-Plus sends an X-ON character (CTRL-Q) to the terminal when a program
begins waiting for input from the line and an X-OFF has been sent previously;
3) line-feed characters are ignored unless line-feed is declared to be a
user-defined activation character -- this is done so that each line of input
may be terminated by both a carriage-return and a line-feed.
The SET TT
[NO]TAPE keyboard command may also be used to control tape mode.
6.2.18 "Y" and .. z.. functions--Control line-feed echo.
The "Y" function is used to disable the echoing of a line-feed character when a
carriage-return is received.
Normally, when TSX-Plus receives a carriagereturn character, it echoes carriage-return and line-feed charac ters to the
terminal and passes carriage-return and line-feed characters to the program.
The "Y" function alters this behavior so that it only echoes carriage-return
but still passes both carriage-return and line-feed to the program.
This
function can be used to advantage with programs that do cursor positioning and
which do not want line-feed echoed because it might cause the screen display to
scroll up a line.
The "z.. function restores the line-feed echoing to its
normal mode.

-106-

7. TSX-Plus EMT'S
TSX-Plus provides several system service calls (EMTs) in addition to those
compatible with RT-ll. In order to take advantage of the special features of
TSX-Plus~ programs written to run under both TSX-Plus and RT-ll should check to
see if they are under TSX-Plus. This chapter describes the preferred method of
checking and goes on to describe several of the special EMTs provided by
TSX-Plus. EMTs which relate specifically to features described elsewhere in
this manual are included in the appropriate chapters.
7.1 Determining if ~ job is running under TSX-Plus
In cooperation with Digital Equipment Corporation, a bit has been allocated in
the RT-ll sysgen options word at fixed offset 372 into the RMON.
The high
order bit (bit 15; mask 100000) of this word will be set (1) if the current
monitor is TSX-Plus version 5.0 or later.
This bit will be clear if the
monitor is any version of RT-11. Testing this bit is the preferred method of
determining if a job is running under TSX-Plus. However, if a program is
expected to also be used under older versions of TSX-Plus, then an alternative
method is necessary. For older versions of TSX-Plus, first issue the .SERR
request to trap invalid EMT requests and then issue the TSX-Plus EMT to
determine the time-sharing line number.
If the job is running under RT-ll,
this EMT will be invalid and the carry bit (indicating an error) will be set on
return. If the job is running under TSX-Plus, then the EMT will return without
error and the line number will be in RO.
Example:
• TITLE

TSXE NV

.ENABL

Demonstrate preferred method of determining whether job is
running under TSX-Plus or RT-11
•MCALL

.PRINT,.EXIT,.SERR,.HERR
;Job Status Word address
;Pointer to base of RMON
jIndex into RMON for sysgen features

JSW
RMON
SYSGEN

= 54
= 372

START:

• PRINT

/fUNDER

;"Running under"

This is the preferred method, but will not work prior to
TSX-Plus version 5.0
MOV
TST
BPL

RMON,R1
SYSGEN(R1)
RT11

;Point to base of RMON
;See if running under TSX-Plus
;Branch if running under RT-l1

This is the old method, but will work correctly with
all versions of TSX-Plus
.SERR

;Trap invalid EMT error
-107-

TSX-Plus EMTs
MOV

IITSXLN,RO
375
RT11

jPoint to EMT arg block to
jDetermine TSX-Plus line number
;Branch if running under RT-11

• PRINT
• EXIT

IITSXPLS

; "TSX-Plus"

• HERR
• PRINT
.EXIT

IINOTPLS

;Reset SERR trap
j"RT-11"

EMT

BCS

. RT11:

TSXLN:

• BYTE
.NLIST
UNDER: .ASCII
TSXPLS: .ASCIZ
NOTPLS: .ASCIZ
.END

0,110
;EMT arg block to get line number
BEX
/Monitor is /<200>
/TSX-Plus./
/RT-11./
START

7.2 Determining the TSX-Plus line number
The following EMT will return in RO the number of the line to which the job is
attached. Physical lines are numbered consecutively starting at 1 in the same
order as specified when TSX-Plus is generated. Detached job lines occur next
and virtual lines are numbered last.
The form of the EMT is:
EMT

375

with RO pointing to the following argument area:

• BYTE

0,110

Example:
.TITLE LNTT
.ENABL- 1£
What TSX line number is this terminal attached to?
And what type terminal does TSX-Plus think it is?
•MCALL
.GLOBL
START:

.SERR
MOV
EMT

.PRINT,.EXIT,.TTYOUT,.SERR,.HERR
PRTDEC
jSubroutine to print a word in decimal

IITSXLN,RO
375

jAre we under TSX-Plus?
jStop error aborts
jSet up EMT request to
jGet TSX-Plus line number
-108-

TSX-Plus EMTs
NOTTSX
RO,LINE

jIf error, not under TSX-Plus
;Save it
;Enable error aborts
jDisplay line number message
;Recall line number
;Display line number

BCS
MOV
• HERR
• PRINT
MOV
CALL

IILINMSG
LINE,RO
PRTDEC

• PRINT
MOV
EMT

liT RMMS G
IITTYPE,RO
375

ASL
• PRINT
.EXIT

RO
TYPE(RO)

NOTTSX: .PRINT
• EXIT

IITSXERR

;Say we are not under TSX-Plus

jStorage for TSX line number
;Storage for TSX term type code
;TSX line number EMT parameters
;TSX term type EMT parameters

LINE:
TERM:
TSXLN:
TTYPE:

• WORD
eWORD
• BYTE
• BYTE

o
0,110
0,137

;Display term type message
;Set up EMT request to
;Get terminal type from TSX-Plus
jReturns into RO
jConvert to word offset
jPrint type from index into table
JAIl done

; Table of pointers to TSX term type names
• EVEN
• WORD
U~~,v~52,v~lOO,HAZEL,ADM3A,LA36,LA120,DIABLO,Qu11E
TYPE:
.NLIST BEX
LINMSG: .ASCII ITSX-Plus line number: 1(200)
TRMMSG: .ASCII (15)<12)/Terminal type: /(200)
TSXERR: .ASCIZ /?LNTT-F-Not running under TSX-Plus/
UNK:
.ASCIZ /Unknown/
VT52:
.ASCIZ /VT-52/
tM"1 nn.
.ASCIZ /\TT-IOO/
HAZEL: .ASCIZ /Hazeltine/
ADM3A: .ASCIZ /ADM3A/
LA36:
.ASCIZ /LA36/
LA120: .ASCIZ /LA120/
DIABLO: .ASCIZ /Diablo/
jDiablo and Qume are equivalent
jDiablo and Qume are equivalent
.ASCIZ /Qume/
QUME:
V.L.l.vv.

.END

START

7.3 Determining the terminal type
The following EMT will return in RO a value that indicates what type of
time-sharing terminal is being used with the line. The form of the EMT is:

-109-

TSX-Plus EMTs
EMT

375

with RO pointing to the following argument block:
• BYTE

0,137

The terminal type is specified either when the TSX-Plus system is generated or
by use of the SET TT command (e.g., SET TT VT100). The terminal type codes
which are currently defined are listed below. The types Diablo and Qume are
functionally equivalent.
Terminal-type

Code

------------(Unknown)
VT52
VT100
Hazeltine
ADM3A
LA36
LA120
Diablo & Qume

0
1
2
3
4
5
6
7

A type code of 0 (zero) is returned if the terminal type is unknown.
Example:
See the example program LNTT in the section on determining the TSX-Plus line
number.
7.4 Determining or changing the ~ ~
vllien using the LOGON system access program, each user is assigned both a user
name and a project, programmer number. TSX-Plus provides an EMT which allows
an application program to obtain the user name or (with operator privilege) to
change it. User names may be up to twelve characters in length. If the LOGON"
program is not used, the user name will initially be blank, although it may be
changed to a non-blank name. The form of the EMT is:
EMT

375

with RO pointing to the following argument block to determine the user name:
• BYTE

• WORD

0,147
buff-addr

where "buff-addr" is a pointer to a 12 byte area to contain the user name which
is returned.
To change the current user name,
argument block:

RO should instead point to the following

-110-

TSX-Plus EMTs
. BYTE
.l.JORD

1,147
buff-addr

where "buff-addr" is a pointer to a 12 byte area containing the new user name.
Operator privilege is required to change the user name. If changing the user
name is attempted without operator privilege, the the name will not be changed
and the carry bit will be set on return.
Example:
.TITLE
.ENABL

GSUNAM
LC

Demonstrate TSX-Plus EMT to get/set user name
ERRBYT

START:

1$:
GSUNA..~:

NAMADD:
NAMBUF:
NEWNAM:
NAMEIS:
NOPRIV:

= 52

;EMT error code location

•MCALL

• PRINT, . EXIT

• PRINT
MOV
EMT
.PRINT

IINA..~EIS

IIGSUNAM ,RO
375
IINAMBUF

jPreface user name
;Point to EMT arg block to
jGet user name
;And display it

MOV
INCB
MOV
EMT
BCC

IINEWNAM, NAMADD
GSUNAM
IIGSUNAM,RO
375
1$

; Point to new user name
jSet low bit to set name
; Point to EMT arg block to
;Set new user name
;Error?

• PRINT
.EXIT

IINOPRIV

;Must have operator privilege

.NLIST
• BYTE
• WORD
.BLKW
• WORD
.ASCII
.ASCII
.ASCIZ
.END

BEX
0,147
NAMBUF

;EMT arg block to get user name
jPointer to receive area
6
;Six word name area (12 bytes)
0
jMake it ASCIZ
/CHAUNCY
/ ;The new name (12 bytes)
/Your current user name is: /<200)
/Operator privilege necessary to set user name./
START

7.5 Controlling the size of ~ job
under RT-li, the .SETTOP EMT is used to set the top address of a job. The
TSX-Plus .SETTOP EMT does not actually alter the memory space allocated to a
job but simply checks to see if the requested top of memory is wi thin the
region actually allocated to the job and if not returns the address of the top
of the allocated job region. The TSX-Plus .SETTOP EMT was implemented this way
-111-

TSX-Plus EMTs
because many programs written for RT-11 routinely request all of memory when
they start regardless of how much space they actually need.
The memory space actually allocated for a job can be controlled by use of the
"MEMORY" keyboard command or by use of the EMT described below. The memory
size specified by the most recently executed MEMORY keyboard command is
considered to be the "normal" size of the job. The EMT described here can be
used to alter the memory space allocated to a job but the job size reverts to
the normal size when the job exits or c~ains to another program.
The form of the EMT used to change a job's size is:

EMT

375

with RO pointing to the following argument area:
• BYTE
•WORD

0,141
top-address

where "top-address" is the requested top address for the job. If this address
is larger than the allowed size of a job, the job will be expanded to the
largest possible size. On return from the EMT, RO contains the address of the
highest available word in the program space.
A program is not allowed to change its size if it was started by use of the
"RUN/DEBUG" command or the system was generated without allowing program
swapping.
In either of these cases the EMT operates exac tly like a • SETTOP
request (i.e., the requested program top address will not be allowed to exceed
the normal program size).
See also the description of the SETS-IZ program in Appendix A for information
about how the default memory allocation for a program can be built into the SAV
file for the program.
Example:
See the example
information.

program

CKSTAT

the

section on determining

job status

7.6 Obtaining TSX-Flus system values
The .GVAL EMT that is normally used to obtain RT-ll system values can also be
used to obtain TSX-Plus system values. Although a simulated RMON is normally
mapped into each job so that it may directly access fixed offsets into RMON,
the .GVAL function is the preferred method for obtaining system values. Under
TSX-Plus, the simulated RMON need not be mapped into a job's virtual address
space (see Chapter 8).
The .GVAL EMT will still function correctly even if
RMON is not mapped into the job.
In addition to the positive offset values
which are documented for use with RT-1l, the following negative offset values
may be used to obtain TSX-Plus system values:
-112-

TSX-Plus EMTs
Offset
-2~

-4.
-6.
-8.
-10.
-12.

-14.
-16.
-18.
-20.
-22.

-24.
-26.
-28.

Value
Job number
"Lead-in" character used for terminal control options
1 if privileged job; 0 if non-privileged job
1 if PAR 7 mapped to I/O page; 0 otherwise
Project number job is logged on under
Programmer number job is logged on under
TSX-Plus incremental license number
Current job priority
Maximum allowed job priority
Number of blocks per job in SY:TSXUCL.TSX
Job number of primary line (0 for primary line)
Name of system device (RADSO)
(may not correspond to current SY assignment)
Minimum fixed-high-priority value
Maximum fixed-low-priority value

As with the standard .GVAL function, the system values are returned in RO.
Example:
.TITLE
.ENABL

TSGVAL
LC

;Demonstrate usage of .GVAL with both positive (RT-II)
; and negative (TSX-Plus) offsets
• MCALL

.GVAL, .PRINT,.EXIT

.GLOBL
.GLOBL

PRTDEC
PRTRSO

SYSGEN

= 372

START:

• GVAL
TST
BPL
• PRINT
• GVAL
CALL
• PRINT
• GVAL
CALL
• PRINT
•GVAL
CALL
• GVAL
TST
BEQ

;Subroutine to print a word in decimal
;Subroutine to print a RADSO word
;RMON offset to sysgen options word

IIAREA,IISYSGEN
RO

9$
IlL ICENS
IIAREA, 11-14 •
PRTDEC
IISYSTEM
flAREA, 11-24.
PRTRSO
IIJOBNUM
IIAREA,II-2

PRTDEC
IIAREA, 11-22.
RO

;Examine system options word
;See if we are running TSX-Plus
;Exit if not
; "License II is"
;Obtain last 4 digits of license II
;And display it
;"Started from"
;Get system device
;And display it
; "Job II is"
;Get TSX-Plus job number
;Display the job number
;See if this is the primary line
;0 if primary
;Done if so
-113-

TSX-Plus EMTs
• PRINT
.EXIT

9$:

AREA:

.BLKW
.NLIST
LICENS: .ASCII
SYSTEM: .ASCII
JOBNUM: .ASCII
VIRT:
.ASCII
.END

/lVIRT

;Else say virtual job

2
;2 word EMT arg area
BEX
ITSX-Plus license number 1<200>
<15><12>/TSX-Plus started from 1<200>
1:1<15><12>/TSX-Plus line number 1<200>
1 (This is a virtual line)/<200>
START

7.7 Determining job status information
The information about various jobs on the system which is displayed by the
SYSTAT command may also be obtained by application programs.
An EMT is
provided wi th several subfunctions to obtain the desired job status information. This EMT may obtain information about any job on the system, not only
itself. The form of the EMT is:
EMT

375

with RO pointing to the following argument block:
• BYTE
• BYTE
• WORD

0,144
line-#,sub-function
buf-address

where "line-II" is the number of the time-sharing line about which information
is to be returned.
Line numbers are in the range 1 up to the highest valid
line number for the system. "Sub-function" is a function code which indicates
the type of information to be returned by the EMT (see below). "buf-address"
is the address of the first word of a 2 word buffer area into which the
returned value is stored. Note: some of the functions only return a single
word value in which case the value is returned into the first word of the
buffer area.
If an error occurs during the execution of the EMT, the carry-flag is set on
return and the following .error codes indicate the type of error:
Errors:
Code

o
1
2

Meaning
Indicated line number is not currently logged on.
Invalid sub-function code.
Invalid line number (0 or higher than largest valid line number).

Each of the sub-functions is described below:

-114-

TSX-Plus EMTs
Subfunction # a -- Check status of line. The value returned contains bit flags
------ -that indicate the status of the jobe The following bit flags are defined:
000001
000002
000100
000200

This is a virtual line.
This is a detached job line.
Job has locked itself in memory.
Job has operator privilege.

Subfunction # 1 -- Get job's execution state. This subfunction returns a code
that indicates-a-rob's current execution state. The following code values are
defined:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Non-interactive high priorlLY run state.
Normal priority run state.
Fixed-low-priority run state.
Waiting on input from the terminal.
Waiting for output to be written to terminal.
Doing a timed wait.
Suspended because .SPND EMT done.
Waiting for access to a shared file.
Waiting for a inter-job message.
Waiting for access to USR (file management) module.
Waiting for non-terminal I/O to finish.
Waiting for access to spool file.
Interactive high priority run state.
Fixed-high-priority run state.
Waiting for memory expansion.

Subfunction # 2 -- Determine amount of memory used by job. This function
returns the number of 256-word blocks Of memory that are currently being used
by the job, including PLAS regions.
Subfunction # 3 -- Determine connect time for job. This function returns the
number of mi~t~s1that a job has been logged onto the system.

Subfunction II 4 -- Determine position of job in memory. This function returns
the 256-word-biO~number of the start of the memory area allocated to the job.
Subfunction # 5 -- Get name of program being run by job. This function returns
a 2 word value. -The two words contain the RAD50 value for the name of the
program currently being run by the job.
Subfunction II 6 -- Get project and programmer number for job. This function
returns a two word value. The first word contains the project number that the
job is logged on under; the second word contains the programmer number.

-115-

TSX-Plus EMTs
Subfunction # 7 -- Get CPU time used by job. This function returns a two word
value that c;n~ins the number of clock-ticks of CPU time used by the job. The
firs t word contains the high-order 16-bi ts of the value, the second word
contains the low-order 16-bits.
Subfunction # 8 -- Get current job execution priority. This function returns
one word that contains the current job execution priority level (0-127).
Example:
.TITLE
.ENABL

CKSTAT
LC

Demonstration of MEMTOP, JSTAT and SNDMSG EMTs of TSX-Plus
ERRBYT
PRGNAM

;EMT error code location
;JSTAT subfunction code to get prog. name

52
= 5

•MCALL

.TWAIT,.EXIT

MOV
#MEMTOP,RO
;Point to EMT arg block to
375
;Set job size
EMT
;Only works in swapping environment, otherwise behaves like .SETTOP
RO,#HILIM
;See if we got what we wanted
CMP
BHIS
AGAIN
;Go on if so
;else quit (can't disp err msg from det line)
.EXIT

START:

AGAIN:
CHECK:

MOVB
#1,LINE
;Check all lines starting with #1
HJSTAT,RO
;Point to EMT arg block
MOV
EMT
375
;Get name of job being run
BCS
ERRTYP
;Go find out what kind of error
CMP
BUFADD,DUNJUN
;Is this line goofing off?
BNE
NEXT
;No, proceed
CMP
BUFADD+2,DUNJUN+2 ;May be, check for sure
BNE
NEXT
;No, proceed
;Send a message to the offending line
; (Each message must be < 88. bytes)
MOVB
LINE,YOOHOO
;Who is the guilty party?
MOV
#MESAGl,MSGADD ;Prepare part one of message
MOY
t~END,RO
;Point to EMT arg block to
~r
375
;Send a message to that line
MOV
HMESAG2,MSGADD ;Prepare for part two of the message
MOV
HSEND,RO
;Point to EMT arg block to
EMT
375
;Send part 2 of message
MOV
HMESAG3,MSGADD ;Prepare for part three of the message
MOV
#SEND,RO
;Point to EMT arg block to
EMT
375
;Send part 3 of message
MOV
#MESAG4,MSGADD ;Prepare for part four of the message
MOV
HSEND,RO
;Point to EMT arg block to
EMT
375
;Send part 4 of message
-116-

TSX-Plus EMTs
NEXT:

INCB
CMPB
BGT

LINE
LlNE,MAXLIN
SLEEP

CHECK

SLEEP:

• TWAIT
BR
ERRTYP: CMPB
BLT
BEQ
MOVB
DECB
BR
2$ :

.EXIT

MEMTOP:

IIAREA, liT lME
AGAIN
@/lERRBYT , 111
NEXT
2$
LINE,MAXLIN
tw'f...AXLIN
SLEEP

0,141
HILIM
0,144

;Try next line
;Have we checked them all?
;Yes, wait awhile
;Go check the rest of the lines
;Come back in 5 minutes
;And try again
;Which error is it
;0 --) line not logged on, try next line
;1 --) invalid sub-function code, give up
;2 --) line) last valid line
;Largest valid line number
;should only happen first time
;Invalid code should never happen
;Might as well kill job
;Argument block for MEMTOP EMT
jUpper address limit
;Argument for JSTAT EMT
;TSX-Plus line number to be checked
;EMT subfunction
;Address of 2-word buffer for returned value
;2 word buffer to hold stat result
;Maximum number of lines under TSX-Plus
;Will be altered to max valid line II
;EMT arg block to send a message
;Destination line number
;Message to be sent
;.TI~AIT arg area
;time high word
;5min * 60.sec/min * 60.ticks/sec

SEND:
YOOHOO:
MSGADD:

BYTE
• WORD
• BYTE
• BYTE
.BYTE
• WORD
.BLKW
.BYTE
• EVEN
• BYTE
.WORD
.WORD

MESAGI

AREA:

• BLK'"w

TIME:

MESAG4:

• WORD
•WORD
.NLIST
.RAD50
.ASCII
.ASCII
.ASCIZ
.ASCII
.ASCIZ
.ASCII
.ASCIZ
.ASCIZ

5*60.*60 •
BEX
/DUNJUN/
;Name of illicit program
<7)<15)<12)
/**********************************/<15)<12)
/*
*/<15)<12)
/* Continued use of this system */<15)<12)
/* for game playing will result */<15)<12)
/* in loss of user privileges!! */<15)<12)
/*
*/<15)<12)
/**********************************/<15)<12)<7)

HILIM:

.END

START

JSTAT:
SUBFUN:
BUFADD:
MAXLIN:

DUNJUN:
MESAGl:

MESAG2:
MESAG3:

PRGNAt\f
BUFADD
2

30.
0,127

7.8 Setting job priority
Jobs may be assigned priority values in the r.ange 0 to 127 to control their
execution scheduling relative to other jobs. The priority values are arranged
in three groups: the fixed-low-priority group consists of priority values from
o up to the value specified by the PRILOW sysgen parameter; the fixed-highpriority group ranges from the value specified for the PRIHI sysgen parameter
-117-

TSX-Plus EMTs
up to 127; the middle priority group ranges from (PRILOW+1) to (PRIHI-1).
following diagram illustrates the priority groups:

The

+-------------+

-->1
1 Fixed
high
1
1 priorities
PRIHI -->1

127

1
1
1
1
1

+-------------+

1
I Normal
job
PRIDEF -->1
I priorities
I

1
I
I
1
1

+-------------+
PRILOW -->1
1
Fixed
1
I
low
1
I
1 priorities 1
0

-->1

+-------------+
Job scheduling is performed differently for jobs in the fixed-high-priority and
fixed-low-priority groups than for jobs with normal interactive priorities.
Jobs with priorities in the fixed-low-priority group (0 to PRILOW) and the
fixed-high-priority group (PRIHI to 127) execute at fixed priority values.
That is, the priority absolutely controls the scheduling of the job for
execution relative to other jobs. A job with a fixed priority is allowed to
execute as long as it wishes until a higher priority job becomes active.
The fixed-high-priority group is intended for use by real-time programs. The
fixed-low-priority group is intended for use by very low priori ty background
tasks. Normal time-sharing jobs should not be assigned priorities in either of
the fixed priority groups.
The middle group of priorities from (PRILOW+1) to (PRIHI-1) are intended to be
used by normal, interactive, time-sharing jobs.
Jobs with these assigned
priorities are scheduled in a more sophisticated manner than the fixed-priority
jobs. In addition to the assigned priority, external events such as terminal
input completion, I/O completion, and timer quantum expiration play a role in
determining the effective scheduling priority.
vfuen a job with a normal priority switches to a virtual line, the priority of
the disconnected job is reduced by the amount specified by the PRIVIR sysgen
parameter. This causes jobs that are not connected to terminals to execute at
a lower priority than jobs that are. This priority reduction does not apply to
jobs with priorities in the fixed-high-priority group or the fixed-low-priority
group. The priority reduction is also constrained so that the priority of jobs
in the normal job PFiority range will never be reduced below the value of
(PRILOW+1) •
-118-

TSX-Plus EMTs
The following EMT can be used to set the job priority from within a program.
The job priority can also be set from the keyboard wi th the SET PRIORITY
command.
The current job priority, maximum allowed priority, and fixed-highand fixed-low-priority boundaries may be determined wi th the .GVAL request.
See the TSX-Plus System Manager's Guide for more information on the significance of priority in job scheduling. The form of this EMT is:
EMT

375

with RO pointing to the following EMT argument block:
• BYTE
.\-JORD

0,150
value

where "value" is the priority value for the job. The valid range of priorities
is 0 to 127 (decimal).
The maximum job priority may be restricted by the
system manager.
If a job attempts to set its priority above its maximum
allowed priority, its priori ty will be set to the maximum allowed. This EMT
does not return any errors.
Example:
.TITLE
.ENABL

GSPRI
LC

Demonstrate EMT to set job priority

.MCALL
.GLOBL
CURPRI
MAXPRI

-16.
-18.

START:

• PRINT
• GVAL
MOV
CALL
• PRINT
• GVAL
MOV
CALL
ADD
CMP

IS:

BLE
MOV
MOV
MOV
EMT
• PRINT
~GVAL

.GVAL,.GTLIN,.PRINT,.EXIT
PRTDEC
;GVAL offset to get current priority
;GVAL offset to get maximum priority
IlcURIS
IIAREA,IICURPRI

RO,R1
PRTDEC
IIMAXIS
IIAREA,IIMAXPRI

RO,R2
PRTDEC
1110. ,R1
R1,R2

1$
R2,Rl
Rl,NEWPRI
IISETPRI,RO
375
IINEWIS
IIAREA,IICURPRI

;"current priority is"
;Obtain current job priority in RO
;Save it
; and display it
;"maximum priority 1S
;Obtain maximum allowable job priority
jSave it
j and display it
jTry to boost priority by 10
jUnless exceeds maximum
jUse 10 larger if (= maxpri
jElse use maxpri
;Set new priority in EMT arg block
jPoint to EMT arg block to
jSset new job priority
;"new priority is"
;Obtain new priority
-119-

TSX-Plus EMTs
CALL
• EXIT

PRTDEC

AREA:
.BLKW
SETPRI: • BYTE
NEWPRI: • WORD

10
0,150
50.

CURlS:
MAXIS:
NEWIS:

and display it
;General EMT arg block
;EMT arg block to set job priority
;New job priority goes here

.NLIST
.ASCII
.ASCII
.ASCII

BEX
/Current job priority = /<200>
<15><12>/MaximUDi job priority
/<200>
<15><12>/- New - job priority = /<200>

.END

START

7.9 Forcing [non]interactive job characteristics
The following EMT can be used to cause a job to be scheduled either as an
interactive job or as a non-interactive job. Programs which do a large amount
of terminal input, but which are not truly interactive jobs in the usual sense,
such as file transfer programs, should use this EMT to avoid excessive
interference with normal interactive time-sharing jobs. This feature may also
be selected wi th the R[UN] /NONINTERACTlVE command. See the TSX-Plus System
Manager's Guide for more information on job scheduling and the significance of
interactive vs. non-interactive jobs.
The form of this EMT is:
EMT

375

with RO pointing to the following argument block:
• BYTE
•WORD
•WORD

0,153
mode

If the value of "mode" is 0, then the job will never be scheduled as an
interactive job.
If "mode" is 1, then the job will be scheduled as other
interactive jobs are, dependent on terminal input.
Example:
.TITLE
.ENABL

NONINT
LC

Demonstrate EMT to schedule job as interactive or non-interactive
•MCALL
JSW
TTSPC

44
10000

.TTYIN,.TTYOUT,.PRINT,.EXIT
;Job Status Word address
;TT special mode bit (single-char)
-120-

TSX-Plus EMTs
CTRLZ

= 32

START:

MOV
EMT
BIS

IISINGLE,RO
375
IITTSPC,@IIJSW

jPoint to EMT arg block to
;Turn on single character activation
;Finish turning on single char mode

MOV
EMT

IfNONINT, RO
375

;Point to EMT arg block to
;Schedule this as non-interactive job

• PRINT
.TTYIN
CMPB

If SLOW

RO,lfCTRLZ

;"May be slow now if system busy"
;Get a char
;If CTRL-Z

lH;'()
...........
'(

"'y

1$:

;ASCII CTRL-Z (move on command)

?<:

·'T'hon

;Else echo it back (we have to echo
; when in single char mode)
;And repeat

.TTYOUT
BR

3$:

MOV
111, SELECT
#N()NTN'T' RO
MOV
EMT
375
• PRINT IIFAST
.TTYIN
RO,IICTRLZ
CMPB
BEQ
4$
• TTYOUT
BR
3$

4$:

• EXIT

2$:

11 ..... ,...., ................... ,

SINGLE: • BYTE
• WORD
•WORD
NONINT: .BYTE
SELECT: .WORD
•WORD
.NLIST
SLOW:
.ASCII
.ASCII
.ASCII
.ASCIZ
FAST:
.ASCIZ
.END

0,152
'S

°0,153

°BEX
°

... , , _

..... .L.L'-&..L

mr\'t7o

An
....,a.&.

LU,,'Y"""

;Want to be interactive now
·Pn;n~

,~~~~~-

~n
-~

RMT

~~~~

~r~

~-o

hln~k
--~~~

~n
-~

;Schedule this as an interactive job
;"See how mUGh faster now"
;Get a char
;If CTRL-Z
;Then move on
;Else echo it back
;And repeat

jEMT arg block to set term option
;Single char activation
;EMT arg block to sched as [non]interactive
;Initially make non-interactive

IType some characters in now. If the system has several I
linteractive jobsl<15><12>
Iresponse will be slow. (Control-Z to get out I
lof this mode.)1
<15><12>/Try again. Response should be much better.1
START

7.10 Sending a message to another line
The following EMT can be used to cause a message to display on another line's
terminal.
(This is a different feature than message communication channels.)
The form of the EMT is:

-121-

TSX-Plus EMTs
EMT

375

with RO pointing to the following argument block:
• BYTE
• WORD
• WORD

0,127
line-number
message-address

where "line-number" is the number of the line to which the message is to be
sent and "message-address" is the address of the start of the message text that
must be in ASCIZ form. The message length must be less than 88 bytes.
Example:
See the example program CKSTAT in the section on determining
job status information.
7.11 Mount a file structure
This EMT is used to tell TSX-Plus that a file structure is being mounted and
that TSX-Plus should begin caching the file directory for the device.
The
effect of this EMT is the same as doing a system ~lOUNT keyboard command. The
form of the EMT is:
EMT 375
with RO pointing to the following argument block:
• BYTE
• WORD
•WORD

0,134
device-spec-address

where "device-spec-address" is the address of a word containing the RAD50 form
of the name of the device on which the file structure is being mounted. If
there is no room left in the table of mounted devices, the carry bit is set on
return and the error code returned is 1.
Example:
.TITLE
.ENABL

MOl1~

Demonstrate TSX-Plus EMT to "MOUNT" (do directory caching on) a device

•MCALL

;SYSLIB RAD50 conversion subroutine
;ASCII Backspace
.PRINT,.GTLIN,.EXIT

.GTLIN
MOV

#BUFFER,#PROMPT ;Ask for name of device
#R50BLK,R5
;Point to arg block for next call

.GLOBL

BS
START:

= 10

IRAD50

-122-

TSX-Plus EMTs
CALL
MOV
EMT
BCC

IRAD50
{IMOUNT ~RO
375
START

;Convert ASCII device name to RAD50
;Point to EMT arg block to
;Mount a file structure (directory caching)
;Ask for more if OK

• PRINT
.EXIT

IINOGOOD

;Say it was not good

.NLIST
• BYTE
• WORD
.WORD
R50BLK: • WORD
.1·mRD
• WORD
•WORD
THREE: • WORD
DEVNAM: •WORD

MOUNT:

BUFFER: .BLKB

PROMPT: .ASCII
NOGOOD: .ASCIZ
.END

BEX
0,134
;EMT arg block to mount a file structure
DEVNAI1
;Pointer to RAD50 name of device
0
jRequired 0 argument
jNumber of args for IRAD50 call
3
THREE
;Pointer to number of chars to convert
;Pointer to chars to convert
BUFFER
DEVNAH
;Pointer to RAD50 name of device
3
;Number of chars to convert
0
;RAD50 representation of device name
80.
;GTLIN input buffer
/Name of device to be mounted:
:/<BS><BS><BS><BS><200>
/Attempt to MOUNT too many devices./<7>
START

7.12 Dismount a file structure

---

This EMT can be used

to tell
directory caching on a
particular drive.
The effect of this EMT is the same as a DISMOUNT keyboard
command. The form of the EMT is:

EMT

375

with RO pointing to an argument block of the following form:
• BYTE
•WORD
• WORD

0,135
device-spec-address

v7here "device-spec-address" is the address of a word containing the RAD50 name
of the device to be dismounted.
Example:
.TITLE
.ENABL

DISMNT
LC

Demonstrate TSX-Plus EMT to "DISMOUNT" (stop caching on) a device
.GLOBL
BS

IRAD50

= 10
•MCALL

;SYSLIB RAD50 conversion subroutine
;ASCII Backspace

.GTLIN
-123-

TSX-Plus EMTs
START:

.GTLIN
MOV
CALL
MOV
EMT
BR

.NLIST
DISMNT: • BYTE
• WORD
•WORD
R50BLK: • WORD
•WORD
• WORD
• WORD
THREE: • WORD
DEVNAM: •WORD
BUFFER: .BLKB
PROMPT: .ASCII
.END

IIBUFFER,IIPROMPT
IIR50BLK, R5
IRAD50
IIDISMNT, RO
375
START

;Ask for name of device
;Point to arg block for next call
;Convert ASCII device name to RAD50
;Point to EMT arg block to
;dismount a file structure (stop caching)
;Repeat (no errors returned)

BEX
0,135
DEVNAM

;EMT arg block to dismount a file structure
;Pointer to RAD50 name of device
0
;Required 0 argument
3
;Number of args for IRAD50 call
THREE
;Pointer to number of chars to convert
BUFFER
;Pointer to chars to convert
DEVNAM
;Pointer to RAD50 name of device
3
;Number of chars to convert
0
;RAD50 representation of device name
80.
;GTLIN input buffer
/Name of device to be dismounted:
:/<BS><BS><BS><BS><200>
START

7.13 Set terminal read time-out value
This EMT can be used to specify a time-out value that is to be applied to the
next terminal input operation. This EMT allows you to specify the maximum time
that will be allowed to pass between the time that you issue a command to get
input from the terminal and the time that an activation character ,is received
to terminate the input field.
You also specify wi th this EMT a special
activation character that is returned as the terminating character for the
field if the input operation times out without receiving an activation
character from the terminal. The form of the EMT is:
EMT

375

with RO pointing to the following argument block:
• BYTE
•,.yORD
• WORD

0,117
time-value
activation-character

where "time-value" is the time-out value specified in 0.5 second units and
"activation-character" is a single character value that is to be returned as
the last character of the field if a time-out occurs. The time value specified
with this EMT only applies to the next terminal input field. The time value is
reset when the next field is received from the terminal or the time-out occurs.
h new time-out value must be specified for each input field that is to be time
controlled.

-124-

TSX-Plus EMT~
Example:
.TITLE

DUNJUN

Demonstrate use of terminal input time-out testing
•MCALL

.TTYOUT,.TTYIN,.EXIT,.PRINT

START:

.TTYOUT #'?

1$:

MOV
EMT
.TTYIN

tlSETTTO,RO
375

CMP

RO,#<15)
1$
RO,#<12)
START
RO,II'Q
1$
#nONE

BEQ
CMP
BEQ
CMP
BNE
• PRINT

;and line feeds
;prompt for next char
;Should we quit?
;No, get next char
;Quit or time-out
; Bye

• EXIT
SETTTO: .BYTE
• WORD
.WORD
DONE:

;Point to EMT arg block to
;Set terminal input time-out
;Get a character from the terminal
;Skip over carriage returns

0,117
6*60.*2

.NLIST
.ASCIZ

BEX
/STOP - /

.END

START

;EMT arg block
;6.min * 60.sec/min * 2.half-sec-units/sec
;Activation character on time-out

See also the example program CKTTIE 1.n the section on checking
input errors.
7.14 Establishing break sentinel control
The following EMT can be used to declare a completion routine that will be
triggered when the "Break" key is pressed. The form of the EMT is
EMT

375

with RO pointing to the following argument block:
0,133
brkchr
cplrtn

• BYTE

•WORD
• WORD

where "brkchr is a user defined character that is to be declared the "Break"
character and "cplrtn" is the address of the completion routine that is to be
lt

-125-

TSX-Plus EMTs
called when the break character is received from the terminal. The specified
completion routine will be called if the user presses ei ther the key labeled
"BREAK" (which transmits a long space) or types the character that is declared
as the user-specified break character (brkchr).
If no user-specified break
character is wanted, specify the value 0 (zero) for "brkchr" in the argument
block and only the real "BREAK" key will be activated.
Note that on some
systems the console terminal "BREAK" key causes entry to the hardware ODT
module and for this reason cannot be used with this TSX-P1us function. Only
one break routine may be specified at a time for each user. If a break routine
was previously specified, it is cancelled when a new routine is declared. If
an address of 0 (zero) is specified as the address of the completion routine
(cplrtn), any previously specified break routine is cancelled and the break key
connection is cancelled. A break routine can be used to signal an asynchronous
request for service to a running program. A good example of its use would be
to trigger entry to an interactive debugging program.
Example:
.TITLE

BRKSNT

jDemo use of break sentinel control

START:

• MCALL
.ENABL

.PRINT,.TWAIT,.EXIT
LC

MOV

IIBRKSNT,RO
375

jPoint to argument area to
;Establish break sentinel control

• PRINT
• TWAIT

IlMESSAG

IIAREA,IITIME

jPrompt for key
;Give the user 2 seconds to hit the break key

TST
BNE
.PRINT

YES
DONE
IINOBRK

;Ever see a break?
;Yes, all done
;No, never saw it

IIGOTBRK

;Say we caught the break
jRemember it
;And continue
;Completion routines are ALWAYS exited with
;RTS PC under TSX-Plus, NEVER via RTI

EMT

DONE:

.EXIT

CMPRTN: .PRINT
MOV
RETlJB,N

1I1,YES

BRKSNT: • BYTE
•WORD
• WORD

• WORD

YES:

0,133
CMPRTN

jEMT arg value block to break sentinel control
;Declare only 'BREAK' key as break char
;Address of completion routine to be called
;when system notices break
;Flag for break seen

-126-

TSX-Plus EMTs
AREA:

• BLK'"w

;2 word arg area for .TwAIT

TIME:

• WORD
• WORD

o
2. *60 •

;high word of time
;2 sec * 60.tics/sec

.NLIST
MESSAG: .ASCIZ
GOTBRK: .ASCIZ
NOBRK: .ASCIZ
.END

BEX
/You have 2 seconds to hit the break key./
<15><12>/Break key pressed./
/Never saw the break key./
START

7.15 Checking for terminal input errors
The following EMT can be used to determine if any terminal input errors have
occurred. The form of the EMT is:
EMT

375

with RO pointing to the following argument block:
• BYTE

0,116

On return from the EMT, the carry-flag is set if an input error has occurred
since the line logged on or since the last time a check was made for input
errors.
The two types of errors that a:re monitored by this EMT are hardware
reported errors (parity, silo-overflow, etc.) and characters lost due to
TSX-Plus input buffer overflow.
Example:
.. TITLE CKTTIE
~ENABL

;Check for terminal input errors
.MCALL

.PRINT,.TTYIN,.EXIT

START:

• PRINT #PROMPT
;Ask to overflow buffer
MOV
#100.,R1
;Set up counter for input loop
MOV
#SETTTO,RO
;Point to EMT arg block to
EMT
375
;Set terminal time out for 0.5 secs
;Note that this is reset after every activation character!!!
;Start requesting characters. Input characters are stacked in the user
;input buffer until an activation character is seen (e.g. carriage return).
iSo, all we have to do to overflow is enter more than the input buffer
;size (defined in TSGEN either by DINSPC or with the BUFSIZ macro)
;and type in too many before activating.
;Use a time-out so we don't have to hit return.
1$:
.TTYIN
;Get a character from the terminal
-127-

TSX-Plus EMTs
CMPB
RO,#37
;Was it time-out activation char?
BEQ
TIMOUT
;Yes, exit loop
SOB
R1,1$
jRepeat for 100. characters
jFor a system with input buffer size=100. in TSGEN, we should be
jable to overflow the buffer before ~e see an activation char
TIMOUT: MOV
#CKTTIE,RO
;Point to EMT arg block to
EMT
375
jCheck for terminal input errors
BCS
HADERR
;Say we had errors
.PRINT #NOERR
jSay we had no errors
.EXIT
HADERR: • PRINT IIYESERR
;Error message
;Did we fill the buffer?
R1,113
CMP
jNote that last two chars of input buffer are reserved
;for activation chars. Any excess input is discarded.
BLE
TOOMNY
;Yes, buffer overflow
;No, hardware error message
tlHDWERR
• PRINT
.EXIT
TOOMNY: • PRINT IloVFERR
;Buffer overflow message
• EXIT
SETTTO: • BYTE
• WORD
• WORD
CKTTIE: • BYTE
.NLIST
YESERR: .ASCIZ
OVFERR: .ASCIZ
HDWERR: • ASCIZ
NOERR: .ASCIZ
PROMPT: .ASCIZ
.END

0,117
;EMT arg block to set terminal time out
20 •
;to 10 seconds (20 half sec units)
37
;Passed as activation char on time-out
;EMT arg block to check for input errors
0,116
BEX
<15)<12)/There were errors during terminal input./<7)
/(Probably input buffer overflow.)/
/(Probably hardware error ••• parity, stop bits, dqta bits)/
<15)<12)/There were no terminal input errors./
/Please enter more than 100 input characters and wait • • • /
START

7.16 Checking for activation characters
The following EMT can be used to determine if any activation characters have
been received by the line but not yet accepted by the program. The form of the
EMT is:
EMT

375

with RO pointing to the following argument block:
• BYTE

0,123

If there are pending activation characters, the carry-flag is cleared on return
from the EMT; if there are no pending activation characters, the carry-flag is
set on return from the EMT.

-128-

TSX-Plus EMTs
Example:
.TITLE
.ENABL

CKACT
LC

;Demonstrate use of check for activation characters
LEAD IN

START:

35
•MCALL

;TSX-Plus program controlled terminal
;option lead-in character
.PRINT,.EXIT,.GTLIN,.TWAIT,.TTYOUT

• PRINT

IIPROf-IPT

"GTLIN

f'BUFFER

CMP
BNE
• PRINT
.EXIT

BUFFER,EX
1$
IIBYE

.BLKW
.WORD
• BYTE
• BLKB

10.
0,1.*60.
0,123
81.

;Request some characters
;And disallow deferred echoing
;00 some processing. Simulated here by .TWAIT
MOV
1180.,R1
;Line length counter
1$:
.TTYOUT II'.
;Tick, tock
DEC
R1
;End of line?
BNE
2$
;No, go on
eTTYOUT #<15>
;New line
.TTYOUT 11(12)
MOV
1180. , R1
;Reset line length counter
• TWA IT IIAREA,IITIME
;Wait 1 second here
2$:
,
Processing
;Point to EMT arg block to
MOV
IICKACT, RO
EMT
375
;Check for pending activation characters
BCS
1$
;Continue if input not complete

AREA:
TIME:
CKACT:
BUFFER:

.NLIST
.EVEN
EX:
.ASCII
PROMPT: .ASCII
.ASCIZ
.ASCIZ
BYE:
.END

;Collect the pending input
Do something with it
jExit command?
;No, continue processing

;EMT arg block
;l.sec * 60.tics/sec
;EMT arg block for activation char check
;Local input buffer

BEX
/EX/
(LEADIN)/L/
jDisallow deferred echoing
/Please enter up to 80 characters, then RETURN:/
/Thank you./
START

-129-

TSX-Plus EMTs
7.17 Sending ~ block of characters to the terminal
The following EMT can be used to efficiently send a block of characters to the
terminal. The form of the EMT is:
EMT

375

with RO pointing to the following argument block:
• BYTE
•WORD
•WORD

0,114
buffer
count

where "buffer" is the address of the buffer containing the charac ters to be
sent and "count" is a count of the number of characters to be sent. This EMT
is much more efficient to use than a series of .TTYOUT EMT's -- it has the same
efficiency as a .PRINT EMT but it uses a count of the number of characters to
send rather than having the character string in ASCIZ form.
Example:
.TITLE
.ENABL

TTOBLK
LC

;Demonstration of the use of the TSX-Plus EMT to send a block of
jcharacters to the terminal •

START:

•MCALL

.EXIT

MOV

IITTOBLK, RO
375

EMT

;Point to EMT arg block to
;Send a block of chars to the terminal

.EXIT
TTOBLK: • BYTE
• WORD
•WORD
.NLIST
BUFFER: .ASCII
.ASCII
.ASCII
.ASCII
.ASCII
.ASCII
BUFEND:
.END

0,114
jEMT arg block to send a block of chars
jPointer to character buffer
BUFFER
<BUFEND-BUFFER> ;Count of characters to be output
BEX
IThis EMT is used to send a block of characters I
Ito the terminal.I<15><12>
lIt is similar to • PRINT, except that it uses I
la count of characters/<15><12>
Irather than a special terminating character I
1«0> or <200».1<15><12>
START

-130-

TSX-Plus EMTs
7.18 Accepting ~ block of characters from the terminal
The following EMT can be used to accept all characters from the terminal input
buffer up to and including the last activation character entered. The form of
the EMT is:
EMT

375

with RO pointing to the following argument block:
• BYTE

• WORD
• WORD

0,115
buffer
size

where "buffer" is the address of the buffer where the characters are to be
stored and "size" is the size of the buffer (number of bytes). This EMT causes
a program to wait until an activation character is entered and then returns all
characters received up to and including the last activation character.
On
return RO contains a count of the number of characters received.
If I:ne
specified buffer overflows, the carry-flag is set on return.
This EMT is
substantially more efficient than doing a series of .TTYIN EMTs; it is
particularly well suited for accepting input from page buffered terminals.
Example:
.TITLE
.ENABL

TTIBLK
LC

;Demonstrates the use of TSX-Plus EMT to accept a block of charact~rs
;from a terminal •
• MCALL

.EXIT,.PRINT,.TTYIN

II PROMPT
;Request input
#TTIBLK,RO
;Point to EMT arg block to
375
EMT
;Accept a block of chars from the terminal
MOV
RO,Rl
;Save input character count
;Char count includes activation char (and LF after CR)
BCC
1$
;Buffer overflow on input?
;Yes, warn user
• PRINT IloVFLOW
1$:
ADD
#BUFFER,Rl
jPoint past last char in buffer
CLRB
(Rl)
;Make the input ASCIZ
• PRINT IIBUFFER
;Reproduce the input
• EXIT

START:

• PRINT
MOV

TTIBLK: .BYTE
• WORD
• WORD

0,115
;EMT arg block to accept block from terminal
BUFFER
;Start of input buffer
<BUFEND-BUFFER) ;Length of buffer in chars (May not exceed
;input buffer size declared in TSGEN.)

-131-

TSX-Plus EMTs
.NLIST
PROMPT: .ASCIZ
OVFLOW: .ASCIZ
BUFFER: .ASCII
.ASCII
BUFEND: .ASCII
.END

BEX
/70 character input buffer ready./
/?TTIBLK-F-Buffer overflow/
/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/
;35 chars
/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/
; 35 char s
/??/
;TTIBLK will never write over these
START

7.19 Program controlled terminal options
Programs may dynamically change various parameters related to terminal control.
The following EMT may be used to set various program controlled terminal
options:
EMT

375

with RO pointing to the following argument block:
• BYTE
• WORD
• WORD

0,152
function-code
argument-value

where "function-code" is a character which specifies which option is to be set
or changed, and "argument-value" specifies a value used only by some options.
See the section on program controlled terminal options earlier in this manual
for more information on the specific options which may be selected and details
on their effects.
7.20 Turning high-efficiency terminal mode on and off
TSX-Plus offers a "high-efficiency" mode of terminal operation that eliminates
a substantial amount of system overhead for terminal character processing by
reducing the amount of processing that is done on each character. When in
high-efficiency mode, characters are sent directly to the terminal with minimum
handling by TSX-Plus; operations such as expanding tabs to spaces and formfeeds to line-feeds are omitted as well as input processing such as echoing
characters and recognizing control characters such as DELETE, control-U and
control-C.
The only characters treated specially on input are user-defined
activation characters and the user-specified break character. At least one
user specified activation character must be declared if high-efficiency mode is
to be used. This form of terminal I/O is designed to facilitate high-speed
machine-to-machine communication.
It can be used effectively to communicate
The form of the EMT used to control highwi th buffered mode terminals.
efficiency mode is:

-132-

TSX-Plus EMTs
EMT

375

with RO pointing to the following argument block:
• BYTE

code,120

where "code" is 1 to turn high-efficiency mode on and 0 to turn it offo
Example:
• TITLE
.ENABL

HIEFF
LC

jDemonstrate the use of TSX-Plus Hi-efficiency terminal mode
START:

.MCALL
• PRINT
• PRINT
MOV
EMT
MOV
EMT

MOVB
MOVB
INC
MOV
MOV
EMT
CLRB
MOV
EMT

• EXIT, • PRINT
IIDCLCC
II PROMPT

jMake AC an activation char
jAsk for input
IIHTRFF_RO
;Point
to EMT arg block to
.. ----- ;Turn on hi-efficiency mode
375
jPoint to EMT arg block to
IITTIBLK, RO
jAccept a block of characters
375
jActual character count returned in RO
Do something useful with the input?
#15,<BUFFER-1>(RO) jReplace the activation char with
#12,BUFFER(RO) jCarriage return, line feed
RO
jCount LF for output
RO i <TTOBLK+4>
;Set up count for output
#TTOBLK,RO
jPoint to EMT arg block to
375
;Display a block of characters
HIEFF
;Get ready to turn hi-eff off
#HIEFF,RO
;Point to EMT arg block to
375
jTurn off hi-efficiency mode
~---

.EXIT
jEMT arg block to turn hi-eff mode on (off)
HIEFF: • BYTE
1,120
jEMT arg block to accept a block of chars
TTIBLK: .BYTE
0,115
jPointer to input buffer
.WORD
BUFFER
jNumber of chars to input
• WORD
BUFS IZ
jEMT arg block to display a block of chars
TTOBLK: .BYTE
0,114
jPointer to buffer for output
• WORD
BUFFER
jSize of buffer to output
.WORD
BUFSIZ
;1/0
buffer - Cannot exceed line's I/O
BUFFER: .BLKB
82.
BUFSIZ = • - BUFFER
buffer sizes declared in TSGEN
jSpacer in case of buffer overfill
.WORD
.NLIST BEX
DCLCC: .ASCII <35><'D><3><200> jDeclare AC as special activation char
PROMPT: .ASCII /Please enter 1 line of characters (AC ends)./<15><12>
.ASCIZ /No special processing or echoing will be done./

-133-

TSX-Plus EMTs
.END

START

7.21 Determining number of free blocks in spool file
The following EMT will return in RO the number of free blocks in the spool
file. The form of the EMT is:
EMT

375

with RO pointing to the following argument area:
• BYTE

0,107

Example:
• TITLE
.ENABL

SPLFRE
LC

jDemonstrate EMT to determine number of free spool blocks

START:

•MCALL

• PRINT, • EXIT

• PRINT
MOV
EMT

IISPLFRE, RO

CALL
• PRINT
• EXIT
.NLIST
SPLFRE: • BYTE
NUMFRE: .ASCII
BLOKS: .ASCIZ
• EVEN
PRTDEC: MOV
MOV
MOV
MOV
MOVB
1$:

CLR

DIV
ADD

MOVB
MOV
BNE
• PRINT
MOV
MOV

IINUMFRE
375
PRTDEC
IIBLOKS

jPreface number message
jPoint to EMT arg block to
jDetermine number of free spool blocks
jNumber is returned in RO
jDisplay the number
jEnd of message

BEX
0,107
jEMT arg to get 1/ free spool blocks
/The spool file has /<200>
/ free blocks./
R1,-(SP)
R2,-(SP)
RO,R1
IIBUFEND,R2
11200, (R2)
RO
1110. ,RO
11'0,R1
R1,-(R2)
RO,R1
1$

R2
(SP)+,R2
(SP)+,R1

;Get copy of number in R1
;Point to end of conversion buffer
;Set end for .PRINT
;Clear high word for DIV
jGet low digit
;Convert low digit to ASCII
jPut into buffer
;Get rest of number
;Repeat for all digits
jDisplay the result

-134-

TSX-Plus EMTs
RETURN
.BLKB
BUFEND: .WORD
.END

o
START

7.22 Set/Reset ODT activation mode
The following EMT can be used to set TSX-Plus to activate on characters that
are appropriate to ODT. In this mode TSX-Plus considers all characters to be
activation characters except digits, ',', '$', and , . The form of the EMT
is:
EMT

375

with RO pointing to the following argument area:
• BYTE

code, 111

where "code" = 1 to turn on ODT activation mode, and "code"
normal mode.

o to reset to

Example:
.TITLE
.ENABL

ACTODT
LC

;Demonstrate EMT which sets aDT activation mode
• MCALL
START:
1$ :

2$:

• PRINT
MOV
EMT
CALL
CMPB
BNE
• PRINT
CLRB
MOV
EMT
CALL
CMPB
BNE

• PRINT, • EXIT
IIODTTYP
fIACTODT, RO

375
GETLIN
BUFFER, fl'Q
1$
flREGTYP
ACTODT
flACTODT ,RO
375
GETLIN
BUFFER,U'Q
2$

;Say we are entering ODT activation mode
;Point to EMT arg block to
;Set ODT activation mode
;Get some terminal input
jBack to regular mode?
;No, get more lines
;Say we are going back to regular activation
jMake arg block into RESET mode request
jPoint to EMT arg block to
jReset ODT activation mode
jGet more input
jWant to quit?
;No, repeat

.EXIT
GETLIN: • PRINT
MOV
EMT

flpROMPT

IITTIBLK,RO
375

jRequest some input
;Point to EMT arg block to
;Accept a block of characters
-135-

TSX-Plus EMTs
CLRB
• PRINT
RETURN
ACTODT: • BYTE
TTIBLK: • BYTE
• WORD
• WORD
.NLIST
ODTTYP: .ASCIZ
REGTYP: .ASCIZ
PROMPT: .ASCII
• EVEN
BUFFER: .BLKB
• BYTE
• END

BUFFER(RO)
liB UFFER

;Make input string ASCIZ
;And echo same string back

;EMT arg block to SET/RESET ODT act'n mode
1t 111
;EMT arg block to get block input from term
Ot l15
BUFFER
;Pointer to input buffer
79.
;Number of input chars requested
BEX
/Starting ODT activation mode./
/Restoring regular activation mode./
/? /<200>
79.
0
START

;TTIBLK input buffer
;CLRB could go here on full buffer

7.23 Determining file directory information
This EMT returns directory information about a file.
EMT

The form of the EMT is:

375

with RO pointing to the following argument block:
• BYTE
•WORD
• WORD

chan,145
dblk
rblk

where "chan" is a channel number in the range 0-16 (octal) that is currently
not in use, "dblk" is the address of a 4-word block containing the RAD50 file
specification (device, file name, extension), and "rblk" is the address of a
7-word block that will receive the information about the file. The information
returned in "rblk" is:
Word 1 :
Word 2:
Word 3:
Word 4:
Word 5:
Word 6:
Word 7:
Errors:
Code
0
1
2

Size of the file (number of blocks).
O-->File not protected; l-->File is protected.
File creation date (standard RT-11 date format).
File creation time (number of 3-second units).
Starting block number of file.
Unused (reserved)
Unused (reserved)
Meaning
Channel is currently in use.
Unable to locate specified file.
Specified device is not file structured.

-136-

TSX-Plus EMTs
Example:
• TITLE
.ENABL

FILIr-.-rr
LC

Demonstrate TSX-Plus EMT to return information about a file
•MCALL
.GLOBL

.PRINT,.EXIT,.CSISPC,.TTYOUT
DSPDAT,DSPTI3

ERRBYT

= 52

START:

jGet file name
.CSISPC #ODTSPC,#DEFLT, #0, #BUFFER
;Point to EMT arg block to
#FILINF,RO
MOV
375
;Get information about a file
EMT
5$
;Nc error?
BCC
@#ERRBYT,R1
jWhat error
MOVB
R1
;Convert to word index
ASL
wPRINT
• EXIT

5$:
10$:

MOV
#BUFFER,RO
TSTB
(RO)+
BNE
10$
MOVB
#200,-(RO)
• PRINT {IBUFFER
.TTYOUT 11'[
FILSIZ,RO
MOV
PRTDEC
CALL
PRTCTD
TST
15$
BEQ
.TTYOUT II'p
.TTYOUT II' ]
• PRINT IisPACE2
MOV
FILDAT,RO
DSPDAT
CALL
• PRINT IisPACE2
MOV
FILTIM,RO
DSPTI3
CALL
.PRINT IisPACE2
MOV
FILLOC,RO
PRTDEC
CALL
.EXIT

15$:

.NLIST
FILINF: .BYTE
• WORD
•WORD
FILS IZ: • WORD
PRTCTD: .WORD

;EMT error code location

BEX
0,145
INSPC
FILSIZ

o
o

;Find the end of the file spec.
;End?
;No, keep looking
jNo CR,LF at end
;File name
;File Slze

;Was file protected?

;File creation date
jDisplay date
;File creation time (3 sec resolution)
;Display special 3-sec time
;File starting block #

;EMT arg block to get file info.
;Pointer to RAD50 file name
;Pointer to 7 word result buffer
;File size
;Protected=l, unprotected=O
-137-

TSX-Plus EMTs
FILDAT: .WORD
FILTIM: • WORD
FILLOC: .WORD
•WORD
OUT SPC: • BLKW
INSPC: .BLKW
DEFLT: •WORD
FIERR: • WORD
•WORD
•WORD
BUFFER: • BLKB
SPACE2: .ASCII
ClNUSE: .ASCIZ
NOFILE: .ASCIZ
BADDEV: .ASCIZ
.END

°°
°0,0
15.

;File date (standard format)
jFile time (special 3-sec format)
;File starting block number
;Pad for 2 reserved words
jOutput file specifications
;Input file specifications
;No default extensions
jEMT error message table

24.
0,0,0,0
CINUSE
NOFILE
BADDEV
81.
jlnput string buffer
/ /<200>
/?FILINF-F-Channel in use./
/?FILINF-F-Can't find file./
/?FILINF-F-Non-directory device./
START

7.24 Setting file creation time
The time that a file is created is stored along wi th other directory information under TSX-Plus. In order to pack the time into a single word, TSX-Plus
represents the file creation time in three second units. For example, if a
file was created at 11:13:22, then the special time representation would be
13467 (decimal).
11 hr * 60 min/hr * 60 sec/min = 39600
780
13 min
* 60 sec/min
22 sec
22
40402 seconds
40402 sec / 3 sec/unit = 13467 3-sec units
A utility program is provided wi th TSX-Plus to display the creation time and
other directory information about a file. See Appendix C for more information
on the FILTIM utility.
The creation date and time for a file are automatically stored by TSX-Plus in
the directory entry for the file at the time that the file is closed after
being created.
.An EMT 1"s provided for those unusual si tua tions where a
different creation time is to be specified for a file after the file is
created. The form of this EMT is:
EMT

375

-138-

TSX-Plus EMTs
with RO pointing to the following argument block:
• BYTE
•WORD
•WORD

chan,146
dblk
time

where "chan" is the number of an unused channel, "dblk" is the address of a
4-word block containing the RAD50 file specification, and "time" is the time
value (in 3-second units since midnight) that is to be set as the creation time
for the file.
Errors:
Code

Meaning
Channel is currently in use.
Unable to locate specified file.
Specified device is not file structured.

1
2
Example:

.TITLE
.ENABL

SFTIM
LC

Demonstrate TSX-Plus EMT to set file creation time
.MCALL
.GLOBL

.PRINT,.CSISPC,.EXIT,.GTLIN
ACRTI3
jSubroutine to convert hh:mm:ss to special
;3-sec internal time format in RO

ERRBYT

= 52

;EMT error code location

START:

• PRINT IIGETNAM
.CSISPC IloUTSPC,IIDEFLT
.GTLIN

1$:

MOV
CALL
BCC
• PRINT
.EXIT
MOV
MOV
EMT
BCC
MOVB
ASL
• PRINT

2$:

• EXIT

SFTIM:

.NLIST
• BYTE

;Prompt for file name
;Get file name in RAD50
IIBUFFER,IIGETTIM ;Prompt for and get a time
jPoint to time input buffer
IIBUFFER, RO
ACRTI3
;Get special time in RO
;Time error?
1$
IIBADTIM
;Yes, incorrect format

RO,NEWTIM
IISFTIM,RO
375
@IIERRBYT,RO
RO
SFTERR(RO)

;Save special time
jPoint to EMT arg block to
jSet creation time in file
jError?
jYes, get error code
;Convert to word offset
jExplain

BEX
0,146

;EMT arg block to set file creation time

-139-

TSX-Plus EMTs
NEWTIM:
OUTSPC:
INSPC:
DEFLT:
SFTERR:
BUFFER:
GETNAM:
GETTIM:
BADTIM:
INUSE:
NOFILE:
BADDEV:

• WORD
•WORD
.BLKW
• BLKW
•WORD
•WORD
•WORD
•WORD
.BLKB
.ASCII
.ASCII
.ASCIZ
.ASCIZ
.ASCIZ
.ASCIZ
.END

INSPC

o
15.
24 •

;Pointer to RAD50 file name
;Will contain new creation time
;.CSISPC output files
;.CSISPC input files (first is the one)
;Default file extensions
;SFTIM error message table

0,0,0,0
INUSE
NOFILE
BADDEV
81.
;.GTLIN input buffer - holds time hh:mm:ss
/Set creation time in file: /<200)
/New creation time: /<200)
/?SFTIM-F-Invalid time./
/?SFTIM-F-Channel in use./
/?SFTIM-F-Can't find file./
/?SFTIM-F-Non-directory device./
START

-140-

8. TSX-Plus JOB ENVIRONMENT

8.1 Virtual and physical memory
The memory space that is accessible by a job is known as the virtual address
space for the job. Because of the architectural design of the PDP-11 computer
which uses 16 bits to represent a virtual memory address, the maximum amount of
virtual address space that can be accessed at one time by a job is limited to
65,536 (64K) bytes. Thus, the virtual addresses for a job range from 000000 to
177777 (octal).
The actual amount of virtual address space available to a job may be as large
as 64Kb but it may be restricted to less than this amount.
The following
factors control the size of the virtual address space available to a job:
1)

The maximum amount of memory allowed for each job as determined by
the HIMEM system generation parameter.

The amount of memory specified with the MEMORY keyboard command
(initialized by the DFLMEM system generation parameter).

The memory limit reserved
program (see Appendix A).

The amount of memory acquired by use of the TSX-Plus EMT that expands
or contracts the job space.

in the disk file

image by the

SETSIZ

The physical address space for a PDP=ll computer is not limited to 64Kb. The
maximum physical address space depends on the model of PDP-11 and the amount of
memory installed on the computer. LSI-11/23 and 11/34 computers can access up
to 256Kb of physical memory. The ll/23-Plus, 11/73, 11/24 and 11/44 computers
can access up to 4Mb of memory.
The process by which an address in the job's virtual address space is transformed into an address in the physical address space is known as mapping~ The
mapping of the virtual address space for a job into the physical memory space
assigned to the job is performed by the memory management hardware facility of
the PDP-II computer.
This facility divides the virtual address space into 8
sec tions, called page s, each of which can address up to 8Kb of memory. The
mapping of a page-or-virtual address space to a page of physical address space
is accomplished by setting up information in a page address register (PAR).
There is one page address register for each of the 8 virtual address pages.
These registers are not directly accessible by a user job but are loaded by the
TSX-Plus system when it starts a program, changes the size of a program, or
swi tches execution between different jobs.
The relationship between the 8
pages of memory and the corresponding sections of virtual address is shown in
the following table:

-141-

TSX-Plus Environment
Page

Virtual address range

--------------------0
1
2
3
4
5
6
7

000000 020000 040000 060000 100000 120000 140000 160000 -

017777
037777
057777
077777
117777
137777
157777
177777

Because of the design of the memory management system in the PDP-11, it is not
possible to divide the v1rtual address space more finely than 8 pages of 8Kb
each.
However, it is possible to map each page of virtual address space into
any section of physical memory.
(This facility allows TSX-Plus to keep
multiple user jobs in physical memory and to switch rapidly among them by
reloading the page address registers.)
8.2 User virtual address mapping
The virtual address space accessed by a
gories:
1)

Normal program
programs.

Simulated RMON.
This is the virtual address region from 160000 to
177777 that is mapped to a simulated RMON (RT-11 resident monitor).

Extended memory windows.
Programs can create regions in physical
memory and then cause one or more pages of virtual address space to
be mapped to the regions.

Shared run-time systems.
Several TSX-Plus jobs can cause a portion
of their virtual address space to be mapped to the same area of
physical memory.
This allows several users to execute the same
program or share common data without having to allocate a separate
area of physical memory for each user.

System I/O page.
TSX-Plus real-time programs may map the system I/O
page into their virtual address space.

These categories
sections.

space which

virtual

address

job can be divided into five cate-

used

space

-142-

are

instructions

discussed

and

the

data

for

following

TSX-Plus Environment
8.3 Normal programs and virtual programs
Programs run under TSX-Plus may be divided into two categories:
normal
programs and virtual programs.
The only difference between the two types of
programs is the manner in which TSX-Plus handles page 7 (addresses 160000 to
177777) of the virtual address space. In the case of normal programs, page 7
is mapped to a simulated RMON. RMON is the name of the resident RT-ll monitor.
When running under RT-ll this is the actual system control program.
When
running under TSX-Plus, the simulated RMON does not contain any of the
instructions that are part of RT-ll but contains only a table that provides
information about the system and the job. This information includes such items
as the system version number, and information about the hardware configuration.
The cells in this table are known as &~ON fixed offsets. Their position within
the table and their contents are documented in the RT-ll Software Support
Manual, although not all cells are relevant to or maintained by TSX-Plus.
The address of the base of the simulated RMON table is stored in location 54 of
the job's virtual address space. Modern RT-ll and TSX-Plus programs should not
directly access the &~ON table but rather should use the .GVAL EMT to obtain
values from the table.
However, since some older programs and some RT-ll
utility programs directly access the RMON tables, it is mapped through page 7
for normal programs.
As a resul t, normal programs are rest ric ted to using
pages 0 to 6 (56Kb) for their own instructions and data.
Virtual programs are programs that do not require direct access to the
simulated R~ON table. These programs may still access the ~MON values with the
.GVAL and .PVAL EMTs. Since direct access to the simulated RMON is not needed,
page 7 is available for the program to use for its OWll instructions and data,
thus providing a total of 64Kb of virtual address space.
A, program may
indicate that it is a virtual program by any of the following techniques:
1)

Set bit 10 (VIRT$ -- mask 2000) in the Job Status Word (location 44)
of the SAY file. See Appendix A for information about how this bit
can be set by use of the SETSIZ program.

Use the Iv LINK switch (/XM switch for the LINK keyboard command)
which stores the RAD50 value for "VIR" in location 0 of the SAV file.

Use the TSX-Plus SETSIZ program (see Appendix A) and indicate that
more than 56Kb of memory is to be used for the program.

8.4 Extended memory regions
Programs running under TSX-Plus have available the Programmed Logical Address
Space (PLAS) facility that is provided by the RT-lIXM monitor. This facility
allows a program to allocate regions of physical memory and then create virtual
windows that can be used to access the regions. There are 7 system service
calls (EMTs) provided for PLAS support:

-143-

TSX-Plus Environment
.CRRG
.ELRG
• CRAW

.ELAW
• MAP

.UNMAP
.GMCX

Create a region
Eliminate a region
Create a virtual address window
Eliminate a virtual address window
Map a virtual window to a region
Unmap a virtual window
Get information about the status of a window

A region is an area of physical memory set aside for use by a job in addition
to its normal job space. The .CRRG EMT is used by a program to request that a
region be created. The size of a region is not restricted to 64Kb and may be
as large as the physical memory installed on the system (less the space used by
the TSX-Plus system, device handlers, tables, and the remainder of the
program). Up to 8 regions may be created by each job.
In order to access a region, a program must use the .CRAW and .MAP EMTs to
create a virtual window and map the virtual window to a selected portion of the
region. A virtual window is a sec tion of virtual address space mapped to a
region rather than to the normal job physical address space. Up to 8 virtual
address windows can be created by each job. The same virtual window (i.e., the
same range of virtual addresses) may be mapped to different regions or
different sections of the same region at different times by use of the .MAP
EMT. This allows a program to selectively access different sections of code or
data in extended memory regions during the course of its execution.
When an extended memory region is created by use of the .CRRG EMT, space is
allocated in physical memory and in a TSX-Plus region swap file. Whenever a
job is swapped out of memory, its extended memory regions are swapped to the
region swap file. Space in the region swap file is allocated and deallocated
dynamically as regions are created and eliminated.
In order to create a
region, space must be available in physical memory and in the region swap file.
The PLAS facility is most commonly used implicitly through the virtual overlay
and virtual array features. Using the PLAS facilities, it is possible for a
single job to use all of the physical memory space available on a system
(exclusive of the space used by the TSX-Plus system, handlers, tables, etc.).
Proper use of the PLAS facilities such as with reasonable size virtual overlays
or arrays can lead to substantial performance improvements for programs.
Excessive use of memory space with the PLAS facility can lead to excessive job
swapping and degraded system performance.

8.5 Shared run-time systems

A shared run-time system is a program or data area in physical memory that can
be accessed by multiple TSX-Plus jobs. Shared run-time systems are somewhat
s,imilar to extended memory regions in that they are both allocated in extended
memory areas and must be accessed by mapping a portion of the jobs virtual
address space to the physical memory area.
The difference is that extended
memory regions are private to the job that creates them and may not be accessed
by any other job.
Shared run-time systems can be simul taneously accessed
-144-

TSX-Plus Environment
(hence "shared") by any number of TSX-Plus jobs. Another difference between
regions and shared run-time systems is that regions can be created dynamically
and can be swapped out of memory; shared run-t ime systems are specified when
the system is generated and reside in memory as long as the system is running.
See Chapter 12 for more information on shared run-time systems.
8.6 Access ~ system I/O page
The system I/O page is an BKb section of addresses which is not connected with
ordinary memory but rather is used to control peripheral devices and hardware
operation. Access to the I/O page is risky in that a program can interfere
with peripheral devices and cause system crashes. For this reason, programs do
not ordinarily have access to the I/O page. However, a program that is running
with TSX-Plus real-time privilege may issue a system service call to cause page
7 (160000-177777) of the job's virtual address space to be mapped to the system
I/O page. See Chapter 11 for more information on real-time programs.

B.7 VM pseudo-device handler
While the VM handler is not actually mapped into a job's memory space~ its use
can dramatically increase job performance. The VM handler enables the use of a
portion of physical memory as a pseudo-disk device. This permits very rapid
access to programs and data which are placed on the VM unit. For programs such
as compilers which heavily utilize overlay segments, a considerable speed-up
can be achieved by loading them onto the VM device. A similar improvement for
overlaid programs can also be obtained wi th the general data cache facility.

However, when the data cache is full the least recently used blocks are lost.
The presence of particular programs and their overlay segments in memory can be
guaranteed by copying them to the VM pseudo-device.
Another example of the
usefulness of the VM device is with compilers which heavily use temporary work
files.
Depending on the number of write operations, which are not helped by
general data caching, significant improvements in speed can be obtained by
directing the work files to the VM pseudo-device~

In order to use the VM device, it must be included in the device definitions
during TSX-Plus system generation. An upper limit must also be placed on the
amount of memory available to TSX-Plus.
The physical memory above that
available to TSX-Plus can then be used as a memory based pseudo-disk. If for
some reason, it is desirable to use less than all of the memory above the top
of TSX-Plus, the SET VM BASE command can be used to restrict the memory
available to VM. Each time TSX-Plus is restarted, VM must be initialized just
as you would for a new physical disk or a fresh logical subset disk.
For
example:
INITIALIZE VM:
Only one unit (VMO:) is available; however, logical subset disks may be created
within the VM pseudo-device to partition it if necessary. On initialization,
the VM handler automatically determines the amount of memory available to it.

-145-

TSX-Plus Environment
See the TSX-Plus System Manager's Guide for more information on the use of data
caching (general and shared files) and the VM pseudo-disk.

-146-

9. SHARED FILE RECORD LOCKING
TSX-Plus allows several programs to have the same file open simultaneously. In
order to control access to such files, TSX-Plus provides system calls to "lock"
shared files and records wi thin shared files.
Through the record locking
facility a program may gain exclusive access to one or more blocks in a file by
locking those blocks. Other users attempting to lock the same blocks will be
denied access until the first user releases the locked blocks. The TSX-Plus
shared file facility also provides data caching on blocks being read from
shared files.
Note that shared file access protection is only meaningful for cooperating jobs
requesting shared access. This scheme does not prevent other jobs from opening
or writing to files if those jobs do not adhere to the file sharing protocol.
The usual protocol for updating a shared file being accessed by several users
is as follows.
1) Open file.
2) Tell TSX-Plus that file is "shared" •
3) Lock all blocks in file which contain desired record.

4) Read locked blocks into memory.
5) Make uEdate to record.
6) Write updated blocks to file.
7) Unlock blocks.

8) Repeat steps 3-7 as needed.
9) Close file.

DIBOL record locking procedures
Subroutines to control record locking from within DIBOL programs are provided
with TSX-Plus. These are discussed in Appendix B.
Record locking from other languages
Record locking may be interfaced to other languages with appropriate subroutine
calls.
Record locking under COBOL-Plus is built into the run-time library
provided with COBOL-Plus.
The remainder of this chapter describes the
techniques used to control shared file access and record locking.
9.1 Opening ~ shared file
Before a file can be used wi th shared access it must be opened by using a
standard .LOOKUP EMT.
After the file has been successfully opened, the
following EMT may be used to declare the file to be opened for shared access.
The form of this EMT is:
EMT

375

with RO pointing tv the following argument area:
• BYTE

• WORD

chan,125
access-code

where "chan" is the number of the I/O channel open to the desired file and
"access-code" is a value indicating the type of access protection desired for
the file. The following access codes are recognized:

-147-

Shared File Record Locking
Code

Protection

Access

---------- ------0
1
2
3
4
5

Exclusive
Exclusive
Protected
Protected
Shared
Shared

Input
Update
Input
Update
Input
Update

The access-code specifies two things: The type of access that you intend to
make to the file (input only or update) and the type of access that you are
willing to grant to other users of the file.
There are three protection
classes:
Exclusive, Protected and Shared.
Exclusive access means that you
demand exclusive access to the file and will allow no other users to access the
file in any fashion (input or update). Protected access means that you will
allow other users to open the file for input but wish to prohibit any other
users from opening the file for update.
Shared access means that you are
willing to allow other users to open the file for both input and update access.
When this EMT is executed, TSX-Plus checks your specified protection mode and
access type with that previously declared for the file by other users. If an
access conflict arises because of your specified access characteristics an
error code of 4 is returned for the EMT. If no access conflict is detected,
your specified access code is saved with the file and will be used to check for
conflicts with future shared access requests issued by other users.
Normally all files that are declared to TSX-Plus using this EMT are enabled for
use of the data caching facility (see description below). However, in some
cases it may be desirable to suppress data caching for certain files.
For
example, sequential access files usually benefit little from data caching and
enabling data caching for these files causes the data cache buffers to be used
non-productively when they could be providing a better service for other types
of files.
To disable data caching for a file set bit 8 (octal 400) in the
access-code word. When shared access is declared with bit 8 set, new data is
not brought into the data cache when the file is read. However, if the data
being read is already stored in the cache because of a read by another user, it
is used. When data being written to a file is currently stored in the cache,
the data in the cache is updated even if the file is declared to be non-cached.
It is possible to have several channels simultaneously open to different shared
files. The exact number of channels that can be open to shared files and the
total number of shared files that may be opened are specified when the TSX-Plus
system is generated.
Once all access to a shared file is completed, the I/O channel should be closed
using the standard .CLOSE or .PURGE EMT's.
See the next section for information about saving the status of a channel that has been opened to a shared
file.

-148-

Shared File Record Locking
The error codes that can be returned by this EMT are listed below:
Errors:
Code

Meaning
Channel has not been opened to a file.
Too many channels opened to shared files.
Too many shared files open.
File protection-access conflict

1
2
3
4
Example:

.TITLE
.ENABL

SHARED
LC

This program cooperates with the example program (SHARE2) in the
following section to demonstrate shared file access protection •
• MCALL
, MCALL

• PRINT,.GTLIN,.TWAIT,.EXIT,.READW
,LOOKUP,.CLOSE,.SAVESTATUS,.REOPEN,.PURGE

ERRBYT = 52
EXUP = 1.
PRIN = 2.
BUFSIZ = 256.
START:

1$:

.LOOKUP #AREA,#O,#SHRI jOpen SHRl.DAT
jBranch if OK
BCC
1$
• PR INT IILKPERR
;Lookup error message
• EXIT
MOV
#EXUP,<SHRFIL+2> ;Set Exclusive, Update access
#SHRFIL,RO
;Point to EMT arg block to
MOV
EHT

Bce
JMP

2$ :

3$:

4$:

;EMT error byte
;Shared file access code: Exclusive, Update
;Shared file access code: Protected, Input
;Number of words in a disk block

375

jDeclare SHRl.DAT as a shared file

;with Exclusive and Update access
2$
;Branch if sharing OK
EMTERR
;Explain the error and quit
#AREA,#O,#BUFFER,#BUFSIZ,#O ;Read block 0 of SHRl.DAT
3$
;Branch if read OK
#RDWERR
;Say there was a read error

.READW
BCe
• PRINT
.EXIT
•PRINT #BUFFER
;Print out the file (must have 0 or 200 byte)
.SAVESTATUS #AREA,#0,#BLOK1 ;Save channel 0 status for reuse
Bce
4$
;Branch if savestatus OK
.PRINT #SVSERR
;Savestatus error message
.EXIT
MOV
fISAVSHR,RO
;Point to EMT arg block to
375
;Save shared file status
EMT
;Purge the channel for reuse
• PURGE 110
•LOOKUP IIAREA, 110, IIsHR2 jOpen SHR2.DAT
;Branch if OK
BCe
5$
-149-

Shared File Record Locking

5$:

• PRINT
• EXIT
MOV
MOV
EMT
BCC
JMP

IILKPER2

;Say bad lookup on SHR2

#PRIN,<SHRFIL+2> ;Set Shared, Input access
IISHRFIL,RO
;Point to EMT arg block to
375
;Declare SHR2.DAT as a shared file
6$
;Branch on no error
EMTER2
;Say error on SHR2 sharing
IIAREA,IIO,IIBUFFER,#BUFSIZ,IIO ;Read block 0 of SHR2.DAT
7$
;Branch if read OK
IIRDWER2
;Say read error on SHR2

.READW
BCC
• PRINT
.EXIT
7$:
• PRINT IIBUFFER
;Print out the contents (1 line, null filled)
.PRINT #PROMPT
;Say it's time to try companion program
.TWAIT IIAREA,#TIME
;Wait 30 seconds to run other program
.PURGE #0
;Now, release SHR2
.GTLIN IIBUFFER,#PRMPT2 ;Wait for return from virtual line
;This job will be suspended for output while gone to virtual line
.REOPEN #AREA,#O,IIBLOK1 ;And get SHR1 back
.READW IIAREA, 110, IIBUFFER, IIBUFS IZ, 111 0; Read in second block of SHR1
• PRINT IIBUFFER
;And print it to prove status was saved
.CLOSE 110
;Release SHR1
.EXIT
EMTER2: MOV
IISHR2NM,FILNUM ;Point to alternate file error
EMTERR: MOVB
@IIERRBYT , RO
;Get the error type
DEC
RO
;Zero offset
ASL
RO
;Convert to word offset
• PRINT SHRERR(RO)
;Print the appropriate error message
• PRINT FILNUM
;And the file name
.EXIT
6$:

AREA:
BLOK 1 :
FILNUM:
TIME:
SHRERR:

SHR1 :
SHR2:
SHRFIL:
SAVSHR:
NOTOPN:
XSSCHN:
XSSFIL:
AXSCON:
SHR1NM:
SHR2NM:

.BLKW
• BLKW
.WORD
• WORD
.WORD
• WORD
• WORD
• WORD
.NLIST
•RAD50
.RAD50
.BYTE
• WORD
.BYTE
.ASCII
.ASCII
.ASCII
.ASCII
.ASCIZ
.ASCIZ

10
5

;EMT arg block area
jSavestatus area for SHR1.DAT
;File name for error message
;30.sec * 60.tics/sec
;Pointer to EMT error messages

SHR1NM
0,30.*60 •
NOTOPN
XSSCHN
XSSFIL
AXSCON
BEX
IDK SHRl DATI ;File descriptor for SHR1.DAT
IDK SHR2 DATI ;File descriptor for SHR2.DAT
0,125
;EMT arg block to declare shared file
1
;Exclusive Update access (GETS CHANGED)
0,122
;EMT arg block to save shared file status
IAttempt to share unopened channel/<7><200>
IToo many channels opened to shared files/<7><200>
IToo many shared files open/<7><200>
IAttempt to protect already protected shared file/<7><200>
I: SHR1.DATI
I: SHR2.DATI
-150-

Shared File Record Locking
LKPERR:
LKPER2:
SVSERR:
RDWERR:
RDWER2:
PROMPT:

.ASCIZ
.ASCIZ
.ASCIZ
.ASCIZ
.ASCIZ
.ASCII
.ASCII
.ASCIZ
PRMPT2: .ASCII
BUFFER: .BLKW
.END

/Lookup error for SHR1.DAT/<7>
/Lookup error for SHR2.DAT/<7>
/Error occurred attempting to save SHRl.DAT file status/<7>
/Error occurred while readIng SHR1.DAT/<7>
/Error occurred while reading SHR2.DAT/<7>
/Go to a virtual line and RUN SHARE2 which attempts /<15><12>
Ito share the same files (SHR1.DAT, SHR2.DAT)./<15><12>
/Waiting 30 seconds • • • • • /<7>
/When you have returned, hit RETURN to continue/<200>
BUFSIZ
START

See also the example program SHARE2 in the section on saving the status of a
shared file channel.
9.2 Saving the status of a shared file channel
A standard • SAVESTATUS EMT may be used to save the status of a shared file
channel. If this is done, all blocks that are being held locked in the file
remain locked until the channel is reopened and the blocks are unlocked (see
below) •
When using a single channel number to access several shared files it is
convenient to initially do a .LOOKUP on each file, then declare the file to be
shared (EM"T above), and then do a .SAVESTATUS. The channel being used to
access the set of files can then be switched from one file to another by doing
a .PURGE followed by a .REOPEN. However, before doing the • PURGE , TSX-Plus
must be told that you wish to save the shared-file status Of the file,
otherwise all locked blocks will be unlocked and the file will be removed from
the shared-file list. The form of the EMT used to perform this function is:
EM.'!

375

with RO pointing to the following argument block:
• BYTE

chan,122

where "chan" is the I/O channel number. The effect of this EMT is to suspend
the connection between the shared file information table and the I/O channel.
Any blocks that are currently locked in the file remain locked until the
channel is reopened to the file (by using a standard .REOPEN EMT). After
saving a shared file status, the channel may be freed by using a .PURGE EMT.

-151-

Shared File Record Locking
Example:
.TITLE
.ENABL

SHARE 2
LC

This program cooperates with the example program (SHARED) in the
previous section to demonstrate saving of shared file status with
the .SAVESTATUS EMT •
• MCALL
•MCALL

.LOOKUP,.PRINT,.EXIT,.READW
.CLOSE,.TWAIT

ERRBYT
BUFSIZ

52
256.

jEMT error byte
;Size of disk file block

START:

.LOOKUP #AREA,#0,#SHR1
BCC
1$
• PRINT #LKPERR
BR
3$

;Try to open a file which is access locked
;Branch if OK
jSay couldn't get the file
;Go on to try second file

1$:

MOV
EMT
BCC
CALL
• PRINT
• CLOSE
BR

#SHRFIL,RO
375
2$
EXPLER
#INSHR1
110
3$

;Point to EMT arg block to
;Declare file for shared access
;If got the file, branch to read it
;Else explain why
jSay we can't share SHR1
;Release channel 0
jGo on to next file

2$:

.READW
• PRINT
• CLOSE

IIAREA,#O,#BUFFER,IIBUFSIZ,IIO jTry to read block 0 of SHR1
IIBUFFER
jDisplay it for kicks
110
jDone with SHR1 for the moment

3$:

.LOOKUP IIAREA,1I0,#SHR2
BCC
4$
• PRINT #LKPER2
BR
6$

jTry to open SHR2
jBranch if OK
jSay we couldn't even open it
jGo on to try SHR1 again

4$:

MOV

IISHRFIL,RO

EMT

375

BCC
CALL
• PRINT
.TWAIT
BR

5$
EXPLER

jPoint to EMT arg block to
jDeclare file for shared access
jAccess Input, Update to show lockout
; though we don't write in this example
;Branch if we can share it
;Explain why not
jSay we will try again later
jWait 5 seconds and
;Try again

.READW
• PRINT
.CLOSE

#AREA,#O,#BUFFER,IIBUFSIZ,IIO jRead block 0 of SHR2
IIBUFFER
jProve that we got it
#0
jDone with SHR2

5$:

IIAGAIN
IIAREA,IITIME

-152-

Shared File Record Locking
6$:

.LOOKUP #AREA,#0,#SHR1
BCC
7$
.PRINT #LKPERR
.EXIT

;Try SHR1 again
jBranch if it worked
jSay we couldn't do it

7$:

MOV
EMT
BCC
CALL
• PRINT
BR

#SHRFIL,RO
375
10$
EXPLER
ffsTLLOK
11$

;Point to EMT arg block to
;Declare shared file
jBranch if OK
jAnd explain the error
;Say it was still locked
;And quit

10$:

.READW
.PRINT
• CLOSE

#AREA,#O,#BUFFER,#BUFSIZ,#l ;Read in block 1
#BUFFER
jAnd display it
#0
;Done with SHR1

11$:

• EXIT
EXPLER: MOVB
DEC
ASL
• PRINT
RETURN
.NLIST

AREA:

.BLKW

@#ERRBYT,RO
RO
RO
SHRERR(RO)

jFind out why can't share it
jConvert to zero index
jMake into word offset
jSay why we couldn't get it

BEX

jEMT arg block
;EMT arg block to declare file shared
jAccess Shared, Update
jShared file error message pointers

SHRFIL: .BYTE

0,125

•WORD
SHRERR: .WORD
• WORD
• WORD
; WORD
TIME:
•WORD
SHR1:
.RAD50
SHR2:
.RAD50
NOTOPN: .ASCIZ
XSSFCH: .ASCIZ
XSSFOP: .ASCIZ
AXSCON: .ASCIZ
INSHR1: .ASCIZ
LKPERR: • ASC IZ
LKPER2 : • ASC IZ
AGAIN: .ASCIZ
STLLOK: .ASCIZ

5
NOTOPN
XSSFCH
XSSFOP
AXSCON
0,5.*60.
j5.sec * 60.tics/sec
IDK SHR1 DATI jInput file #1 name
IDK SHR2 DATI jInput file #2 name
ICannot share unopened filel
IToo many channels opened to shared filesl
IToo many shared files openl
IShared file protected by another jobl
IOn first try at SHR1.DATI
IUnable to lookup SHR1.DATI
IUnable to lookup SHR2.DATI
ICan't access SHR2.DAT, will try again in 5 secondsl
IOn second try at SHR1.DATI

.EVEN

BUFFER: .BLKW

BUFSIZ

• END

START

;Input read buffer

-153-

Shared File Record Locking
See also the example program SHARED in the section on opening a shared file.
9.3 Waiting for ~ locked block
The following EMT can be used to lock a specific block in a file.
If the
requested block is locked by another job, the requesting job will be suspended
until the desired block becomes available. The form of the EMT is:
EMT

375

with RO pointing to the following area:
• BYTE
• WORD

chan,102
block

where "chan" is the number .of an I/O channel that has previously been declared
to be open to a shared file and "block" is the number of the block in the file
to be locked. Other blocks in the file which were previously locked remain
locked. The maximum number of blocks which may be simultaneously held locked
is specified when TSX-Plus is generated. A block number of -1 (octal 177777)
can be used to request that all blocks in the file be locked. If several users
request the same block, access will be granted sequentially in the order that
the requests are received.
Errors:
Code

Meaning
Channel is not open to a shared file
Request to lock too many blocks in file

1
2
Example:

.TITLE
.ENABL

LOCKW
LC

This program cooperates with the example program (LOCK) in the next
section to demonstrate shared file record locking •
• MCALL

.PRINT,.EXIT,.TWAIT,.LOOKUP,.READW,.CLOSE
;EMT error code byte
;Words per disk block

52
ERRBYT
BUFSIZ = 256.
START:

•LOOKUP IIAREA, 110, IIsHR1
BCC
1$
• PRINT IILKPERR
.EXIT

1$:

MOV
EMT

IISHRFIL, RO
375

;Open SHR1.DAT
;Branch if OK
;Say bad lookup
;Point to EMT arg block to
jDeclare shared file
-154-

Shared File Record Locking

2$:
3$:

4$:

BCC
MOVB
DEC
ASL
• PRINT
.CLOSE
.EXIT

jBranch if OK
;Get the error code
jMake zero index
jConvert to word offset
;Print the error message
jGive back the channel

IILOCKW,RO
jPoint to EMT arg block to
MOV
375
jLock block 0 of SHR1.DAT
EMT
;(Job is suspended until block available to be locked)
BCC
5$
jBranch when block is ready
CHPB

!a#roT"'oT"'o"nnm .J~,
I.:;7r £.1\.1\.D 1. 1. , lr 1.

BHI
• PRINT
BR
• PRINT

BR
5$:

3$
@IIERRBYT,RO
RO
RO
SHRERR(RO)
110

• PRINT
.TWAIT
MOV
EMT
BCC

;wl1ich error?

jToo many blocks locked?
jWasn't open to shared file!
;Give up
2$
IlxSLKBL
jToo many locked blocks in file
j(Defined by MXLBLK parameter in TSGEN)
;Give up
2$
IfSFCNOP

If PROMPT
IfAREA , tlSEC20

IfUNLOCK,RO
375
6$

jSwitch lines to attempt access
;Wait 20 seconds before unlocking
; Point to EMT arg block to
;Unlock a single block
jBranch if OK
jWasn't shared file!
;Give up

• PRINT

IlsFCNOP

• TWAIT
MOV
EMT
BCC
• PRINT
.READW
• PRINT
.READW
• PRINT
BR

IfAREA, IIsEC10
IICKWSHR, RO
375
8$

8$:

• PRINT

IINOCHNG

jSay nothing has changed

DONE:

• CLOSE
.EXIT

110

jFree up channel

6$ :

.NLIST
.BLKW
AREA:
SHRFIL: • BYTE
•WORD
LOCKW: • BYTE
•WORD

;Wait 10 seconds for companion
;Point to EMT arg block to
jCheck for writes to shared file
jlf none, wrap up
IICILA.NGD
;Say we have new data
IfAREA,#O,#BUFFER,IIBUFSIZ,IfO ;Get block
If BUFFER
;Show current contents block 0
IfARE A, If 0, IfBUFFER,IIBUFSIZ, III jGet block 1
IIBUFFER
;Show contents block 1
DONE

BEX
10
0,125
4
0,102
0

;EMT arg block area
jEMT arg block to declare shared file
jAccess Shared, Input
jEMT arg block to lock shared file block
;Block number to be locked
-155-

Shared File Record Locking
UNLOCK: .BYTE
• WORD
CKWSHR: .BYTE
SHRERR: .WORD
•WORD
• WORD
• WORD
SHRl:
.RAD50
SEC20: .WORD
SECI0: .WORD
NOTOPN: .ASCIZ
XSSFCH: .ASCIZ
XSSFOP: .ASCIZ
AXSCON: .ASCIZ
LKPERR: •ASC IZ
SFCNOP: .ASCIZ
XSLKBL: .ASCIZ
CHANGD: .ASCIZ
NOCHNG: .ASCIZ
PROMPT: .ASCII
.ASCIZ
• EVEN
BUFFER: • BLKW
.END

0,113

;EMT arg block to unlock shared file block
;Block number to be unlocked
;EMT arg block to check writes to shared file
;Shared file error message table

°0,121

NOTOPN
XSSFCH
XSSFOP
AXSCON
/DK SHRI DAT/ ;File name to be shared
0,20.*60.
;20.sec * 60.tics/sec
0,10.*60.
;10.sec * 60.tics/se~
/Channel not opened to shared file/<7>
/Too many channels opened to shared files/<7>
/Too many shared files open/<7>
/File protection access conflict/<7>
/Unable to open SHRl.DAT/
/Can't lock or unlock block not open to shared file/
/Can't lock so many blocks in one file/
/Data has been written to file. Contents follow:/
/Data in file is unchanged/
/Block
in SHRl.DAT will remain locked for 20 sec/<15><12>
/Go to another line and RUN TLOCK to test it/<7>

BUFSIZ
START

9.4 Trying to lock ~ block
This EMT is similar in operation to the previous EMT:
it too is used to
request that file blocks be locked. The difference is that if the requested
block is already locked by another user the previous EMT suspends the requesting program whereas this EMT does not suspend the program but rather returns an
error code. As above, a request to lock block #-1 is treated as a request to
lock the entire file. If the block is available it is locked for the requesting user and no error is reported. The form of this EMT is:
EMT

375

with RO pointing to the following argument area:
• BYTE
• WORD

chan,103
block

where "chan" is the number of the I/O channel associated wi th the file and
"block" is the number of the block which is to be locked.

-156-

Shared File Record Locking
Errors:
Code

Meaning
Channel is not open to a shared file.
Request to lock too many blocks in file.
Requested block is locked by another user.

1
2
3

Example:
.TITLE
.ENABL

LOCK
LC

Tnls program cooperates Wlt:n the example program (LOCiCw) in the
previous section to demonstrate shared file record locking •
• MCALL

.PRINT,.EXIT,.WRITW,.TWAIT,.LOOKUP,.CLOSE

ERRBYT = 52

jError byte address

START:

.LOOKUP #AREA,#O,#SHRI
BCC
1$
• PRINT #LKPERR
.EXIT

;Try to open SHRl.DAT
;Branch if OK
;Say we couldn't open

1$:

MOV

IfsHRFIL, RO

EHT

.J/.J

BCC
MOVB
DEC
ASL
• PRINT
• CLOSE

3$
@ilERRBYT,RO
RO
RO
SHRERR(RO)
#0

;Point to EMT arg block to
jDeclare shared &.:,;Branch if OK
;Get error type
;Convert to zero index
; Make into word offset
;Display the error type
;Release the channel
;And give lln
-I:'

2$:

'liE::

.EXIT

3$:

4$:

5$:
6$:

MOV
EMT
BCC
CMPB
BLO
BEQ
• PRINT
.TWAIT
BR
.PRINT
BR
. PRINT
BR
.WRITW
MOV

IfLOCK,RO

375
6$
@IfERRBYT , 112
4$
5$
IfWAITNG
#AREA, IfTIME
3$
IfNOPNSF

2$
I,fXSLK.BL

J..l..l.1:

; Point to EMT arg block to
;Try to unlock block 0
;Branch if OK
;Which error was it
;Wasn't open to share file?
;Request to open too many blocks in file?
jBlock locked by another user
jWait 3 seconds
jAnd try again
;Not open to shared file
;Give up
;Too many blocks locked in file
;Give up

If AREA, If 0, If BUFFER, IfBUFSIZ, #0 ;Rewrite block 0
#UNLALL,RO
;Point to EMT arg block to

-157-

Shared File Record Locking
EMT
• PRINT
BR
.NLIST
AREA:
.BLKW
.RAD50
SHRl:
SHRFIL: • BYTE
• WORD
LOCK:
• BYTE
• WORD
UNLALL: • BYTE

375

;Release all blocks locked by this program
;Message: done, go back to original line
;Done

IIGOBACK

2$
BEX
10
/DK SHRI
0,125
3
0,103
0
0,101

DAT/

;EMT arg block
;Name of shared file
;EMT arg block to share file on chan
;Access Protected, Update
;EMT arg block to lock block on chan
;number of block to be locked
;EMT arg block to unlock all blocks on chan
; (Only applies to blocks locked by this job)
;3.sec * 60.tics/sec
;File sharing EMT error table

°
°

0,3.*60.
TIME:
.WORD
SHRERR: .WORD
SFCNOP
XSSFCN
• WORD
• WORD
XSSFOP
AXSCON
• WORD
SFCNOP: .ASCIZ /Channel not open to file/<7)
XSSFCN: .ASCIZ /Too many channels open to shared files/<7)
XSSFOP: .ASCIZ /Too many shared files open/<7)
AXSCON: .ASCIZ /Shared file access conflict/<7)
LKPERR: .ASCIZ /Couldn't open SHRl.DAT/<7)
WAITNG: .ASCII /Requested block not available for locking/<15)<12)
.ASCIZ tWill try again in 3 seconds/
GOBACK: .ASCIZ /Oone, log off and go back to original line/
NOPNSF: .ASCIZ /Channel not open to shared file/<7)
XSLKBL: •ASC IZ /Attempt to lock too many blocks in file/<7>
.EVEN
BUFFER: .ASCII /(SHRl)This line was written by the program LOCK./
.ASCIZ /
/<15><12>
BUFSIZ = <.-BUFFER+l)/2
jNumber of words to write
• BYTE
0,0
;Safety bumper
.END

START

9.5 Unlocking ~ specific block
The following EMT is used to unlock a specific block in a file.
the EMT is:
EMT

The form of

375

with RO pointing to the following argument block:
• BYTE
• WORD

chan,113
block-number

where "chan" is the number of the I/O channel opened to the shared file and
"block-number" is the number of the block to be unlocked.
-158-

Shared File Record Locking
Errors:
Code
1

Meaning
Specified channel not opened to a shared file

Example:
See the example program LOCKW in
block.

the section on waiting for a locked

9.6 Unlocking all locked blocks in a file
The following EMT is used to unlock all blocks held locked in a file.
of the EMT is:
EMT

The form

375

with RO pointing to the following argument area:
• BYTE

chan,lOl

where "chan" is the I/O channel number open to the shared file. When this EMT
is executed all blocks previously locked by the user on the shared file are
unlocked.
Blocks locked by the user on other files are not released nor are
blocks of the same file that are locked by other users.
Errors:
Code
1

Meaning
Channel is not open to a shared file.

Example:
See the example program LOCK in the section on trying to lock a block.
9.7 Checking for writes to a shared file
The following EMT can be used to determine if any other user has written to a
shared file. The form of the EMT is:
EMT

375

with RO pointing to the following argument block:
• BYTE

chan,121

where "chan" is the I/O channel number opened to the shared file. If no other
user has written to the file since the file was opened by the user issuing this
EMT or since that last time this EMT was issued for the file, the carry-flag is
clear on return from the EMT.

-159-

Shared File Record Locking
Errors:
Code
2

Meaning
Some other job has written to file since last check

This EMT is useful when data from a shared file is being held in a program
buffer.
If no other user has written to the file, then the data is still
valid.
However, if the data in the file has been re-written then it must be
re-read. The usual sequence of operations in this situation is to first lock
the block whose data is in the program's buffer, then do the EMT to see if the
file has been written to. If the file has not been modified the data in memory
is valid and can be used, otherwise the block must be re-read from the file.
Example:
See the example program LOCKW in the section on waiting for a locked block.
9.8 Data caching
Data caching is a technique provided by TSX-Plus to speed access to files.
When TSX-Plus is generated a certain number of 512-byte buffer areas may be set
aside for data caching.
These buffer areas are part of the resident system
data area and are not associated with any particular job. There are two kinds
of data caching: generalized data caching; and shared-file data caching. Both
kinds may used automatically with minimal intervention on. the part of the
programmer or operator.
Generalized data caching applies to all files on
MOUNTed devices, while shared-file data caching applies only to files which
have been declared as shared files.
Generally, only one of these types is
selected during generation of a TSX-Plus system.
The following discussion
applies to shared-file data caching. See the TSX-Plus System Manager's Guide
for more information on data caching.
Each time a request is issued to read a shared file, a check is made to see if
the blocks being read are currently stored in the data cache. If so, the data
is moved from the cache buffer to the program buffer and no disk I/O operations
are performed. When data in the cache buffers is accessed, a use count is
incremented. Periodically, the use counts for all buffers is divided by two.
If the data blocks being read are not currently in the cache, the data is read
from the disk into the program buffer and then it is moved into the cache
buffers with the lowest use count.
When a write operation is done to a f!le that is being cached, a check is made
to see if the data being written is currently stored in the cache. If so, the
cache buffers are updated. In any case the data is written to the disk. In
other words, this is a "wri te-through" cache; the disk file is always updated
and caching does not improve the performance of "writes".
All data files that are declared to TSX-Plus for shared access (using EMT 375
with function code 125) are eligible for data block caching regardless of their
access protection type.
Data caching on a shared file may be disabled by
-160-

Shared File Record Locking
setting bi t 8 (octal 400) in the access-code word of the EMT argument block
when the file is declared for shared access.
Data caching is particularly
effective for COBOL-Plus ISAM files.

-161-

-162-

10. MESSAGE COMMUNICATIONS FACILITIES
TSX-Plus provides an optional facility that allows running programs to send
messages to each other. This message communication facility allows programs to
send messages through named channels, check to see if messages are pending, and
suspend execution until a message is received. TSX-Plus provides EMTs for each
of these operations which are described below.
10.1 Message channels
Messages are transferred to and from programs by using TSX-Plus "Message
Channels". A message channel accepts a message from a sending program, stores
the message in a queue associated with the channel and delivers the message to
a receiving program when requested. Message channels are totally separate from
I/O channels.
Each message channel is ~aentified to the sending and rece~vlng programs by a
one to six character name.
The total number of message channels is defined
when TSX-Plus is generated. The names associated with the channels are defined
dynamically by the running programs. A message channel is said to be "active"
if any messages are being held in the queue associated with the channel or if
any program is waiting for a message from the channel. When message channels
become inactive they are released and may be reused.
Once a message is queued on a channel, that message will remain in the queue
until some program receives it or the TSX-Plus system is halted. A program may
exit after queuing a message without affecting the queued message. This allows
one program to leave a message for another program that will run later.
10.2 Sending ~ message
The following EM"T is used to queue a message on a named channel. If other
messages are already pending on the channel, the new message is added to the
end of the list of waiting messages. The sending program continues execution
after the EMT and does not wait for the message to be accepted by a receiving
program. During processing of the EMT the message is copied to an internal
buffer, and the sending program is free to destroy its message on return from
the EMT. The form of the EMT is:

EMT

375

with RO pointing to the following argument area:
• BYTE
• WORD
• WORD
•WORD

0,104
chadr
msadr
mssiz

where "chadr" is the address of a six byte field containing the name of the
message channel (ASCII with trailing blanks if the name is less than six
characters), "msadr" is the address of the beginning of the message text, and
"mssiz" is the message length in bytes.

-163-

Message Channels
Errors:
Code
1
2
4

Meaning
All message channels are busy.
Maximum allowed number of messages already in message queues.
The transmitted message is too long. The message is truncated
to maximum allowed length.

The system manager may alter parameters during TSX-Plus generation to aIle'
these error conditions.
Example:
.TITLE SNDMSG
.ENABL LC
Demonstrates use of the TSX-Plus EMT to queue a message to the interprocE
message communication facility •
• MCALL

.EXIT,.PRINT,.GTLIN

ERRBYT = 52
START:
1$:

.GTLIN
MOV
TSTB
BNE
SUB
MOV
.GTLIN
MOV
EMT
BCC
MOVB
DEC
ASL
• PRINT
• EXIT

9$:

CLRB
• PRINT
• PRINT
• EXIT

.NLIST
MSGBLK: • BYTE
•WORD
•WORD
MSGLEN: • WORD

;EMT error byte
IIMSGB UF , IIMSG PR T ;Get the message to be queued
jPoint to beginning of buffer
IIMSGBUF ,R1

(R1)+
1$
II<MSGBUF+1),R1

;Find end of message

;Determine message length
;accounting for post-increment
R1,MSGLEN
;Set message length in EMT arg block
IICNLBUF,IICNLPRT jGet the six character channel name
IIMSGBLK, RO
;Point to EMT arg block to
;Send message on named channel
375
;Branch if no error
9$
@IIERRBYT ,RO
;Which error?
;Zero offset
RO
;Convert to word index
RO
;Display
the appropriate message
ERRTBL(RO)
CNLBUF+6
IIDONEOK

IlcNLBUF
BEX
0,104
CNLBUF
MSGBUF
0

;Make channel name ASCIZ
;Inform user message queued
jon channel CNLBUF

;EMT block: send message on named channel
;Address of channel name
;Address of message
;Char length of message
-164-

Message Channels
ERRTBL: .WORD
.. WORD
• WORD
• WORD
BSYERR: .ASCIZ
FULERR: • ASC IZ
OHOH:
• ASCIZ
TRNERR: • ASC IZ
MSGPRT: .ASCIZ
CNLPRT: .ASCII
DOt--l'"EOK: .ASCII
• EVEN
CNLB UF: • BLKB
MSGBUF: .BLKB
.END

;Table of send error messages
BSYERR
FULERR
OHOH
;Error code 3 not used
TRNERR
/?SNDMSG-F-Maximum number of messages have been queued./
/?SNDMSG-F-All message channels are busy./
/?SNDMSG-F-This is a non-existent error./
/?SNDMSG-W-Message was too long, truncated./
/Message to be queued: /
<15><12>/Channel Name (six characters max): /<200>
/Message queued on channel /<200>
80.
80.

;First 6 chars to contain file name
;Message buffer.

START

10.3 Checking for pending messages
The following EMT is used to receive a message from a named channel if a
message is pending on the channel. If no message is pending, an error code (3)
is returned, and the program is allowed to continue execution. The form of the
EMT is:
EMT

375

with RO pointing to the following argument area:
• BYTE
•WORD
•WORD
•WORD

0,105
chadr
msadr
mssiz

where "chadr" points to a field wi th a six character channel name, "msadr"
points to the buffer in which the message is to be placed, and "mssiz" is the
size of the message buffer (bytes).
If a message is received, its length (bytes) is placed in RO on return from the
EMT. If the message is longer than the message buffer (mssiz), only the first
part of the message will be received.
Errors:
Code
3
4

Meaning
No message was queued on the named channel.
Message was longer than the receiving buffer.

-165-

Message Channels
Example:
.TITLE GETMSG
Demonstrates use of the TSX-Plus EMT to check for pending messages in the
interprocess message communication facility •
•MCALL

.EXIT,.PRINT,.GTLIN

ERRBYT = 52
START:

2$:
5$:

.GTLIN
MOV
EMT
BCC
CMPB
BEQ
• PRINT
.EXIT
• PRINT
• PRINT
.PRINT
.EXIT

MSGBLK: .BYTE
• WORD
• WORD
• WORD
.NLIST
CNLBUF: • BLKB
MSGBUF: .BLKB
•WORD
CNLPRT: .ASCII
NOMERR: .ASCIZ
TRNERR: .ASCIZ
PNDMSG: .ASCIZ
.END

;EMT error byte
IICNLBUF,IICNLPRT
IIMSGBLK,RO
375
5$
@IIERRBYT, 114
2$
IINOMERR

;Get the channel name
;Put EMT argument block address in RO
;EMT to check channel for message
;Error?
;Only two errors possible
;Overflow message buffer?
;No message

IfTRNERR
IlpNDMSG
IIMSGBUF

;Print truncation warning
;Print message preamble
;Print actual message

0,105
CNLBUF
MSGBUF
81 •
BEX
80.
80.

;GETMSG EMT block
;Channel name buffer address
;Buffer address to receive message
;Buffer length

;First 6 chars are channel name
;Message buffer
o
;Insure ASCIZ
/Channel Name (6 chars): /<200>
/?GETMSG-F-No messages pending in named channel./
/?GETMSG-W-Message truncated/<7>
/Message pending in named queue is:/

START

10.4 Waiting for ~ message
The following EMT is used to suspend execution of a program until a message
becomes available on a named channel. The form of the EMT is:

-166-

Message Channels

EMT

375

with RO pointing to the following argument area:

0,106
chadr
msadr
mssiz

• BYTE
•WORD
• WORD
•WORD

where "chadr" points to a six byte field containing the channel name, "msadr"
points to the buffer where the message is to be placed, and "mssiz" is the size
of the message buffer (bytes).
The length of the received message (bytes) is placed in RO on return from the
EMT.
Errors:
Code
1
4

Meaning
All message channels are busy.
Message was longer than the receiving buffer.

Example:
.TITLE

WATMSG

.ENABL

Demonstrate TSX-Plus EMT to wait for a queued message from the
interprocess message communication facility •
•MCALL
ERRBYT

= 52

START:

.GTLIN
• PRINT
MOV
EMT

2$:
5$ :

BCC
CMPB
BHI
• PRINT
.EXIT
• PRINT
• PRINT
.PRI~"T

.EXIT,.PRINT,.GTLIN
jEMT error byte
IICNLB UF , IlcNLPRT
IIWAITNG
IIMSGBLK,RO
375
5$
@I!ERRBYT, 111
2$
II NOMERR

;Get the channel name
;Explain waiting
;Put EMT argument block address in RO
;EMT to check channel for message
;Check for error
;Error?
;Message truncated
JAIl channels busy

IITRNERR
IIRCVMSG
ffMSGBUF

;Print truncation warning
;Print message preamble
;Print actual message

0,106
CNLBUF

;WATMSG EMT block
jChannel name buffer address

.EXIT
MSGBLK: .BYTE
• WORD

-167-

Message Channels

CNLBUF:
MSGBUF:
CNLPRT:
WAITNG:
NOMERR:
TRNERR:
RCVMSG:

•WORD
• WORD
.BLKB
.BLKB
•WORD
.NLIST
.ASCII
.ASCII
.ASCIZ
.ASCIZ
.ASCIZ
.ASCIZ

MSGBUF
B1 •

.END

START

BO.
BO.

;Buffer address to receive message
;Buffer length
;Channel name first 6 chars
;Message buffer
;Insure ASCIZ

BEX

/Channel Name (6 chars): /<200>
/Waiting for a message • • • /<15><12>
/Go to another line and send me something./
/?WATMSG-F-All message channels are busy./
/?WATMSG-W-Message truncated./<7)
/Message received in named queue is:/

-16B-

11. REAL-TIME PROGRAM SUPPORT
TSX-Plus provides a real-time program support facility that allows multiple
real-time programs to run concurrently with normal time-sharing operations.
The basic functions provided by this facility are summarized below.
1.

The ability to map the I/O page into the user's virtual memory region
so that device status and control registers may be directly accessed
by the program.

The ability to connect device interrupt vectors to program interrupt
service routines running at fork level or to program completion
routines running at user-selectable priority levels with full job
context.

The ability for a program to lock itself in memory so that rapid
interrupt response can be assured=

The ability for a program to suspend its execution until an interrupt
occurs.

The ability to set execution priorities for tasks.

The ability to convert a virtual address within the job's region to a
physical address for DMA I/O control.

The abili ty to map a virtual address region to a physical address
region.

The ability for a program to declare a list of addresses of device
control registers to be reset when the program exits or aborts
(=DEVICE EMT) ..

Real-time support features are only available if the real-time support facility
is included in TSX-Plus when the system is generated.
A program must have operator privilege to use any of the real-time features
described in this chapter.
The real-time facilities are available to both
normal jobs controlled by time-sharing lines and to detached jobs. Note that
detached jobs that are specified during system generation for automatic startup
run with operator privilege; detached jobs started by time-sharing users have
operator privilege only if the user starting them does.
11.1 Accessing the I/O page
A basic facility required by most real-time programs is the ability to access
the PDP-II I/O page (160000-177777) which contains the device control and
status registers. Under TSX-Plus, addresses in this range are normally mapped
to a simulated RMON or may be used as normal program space. This is done since
many old programs require direct access to certain system values at fixed
offsets into RMON, although recent programs should access these values with the
.GVAL and .PVAL EMTs. TSX-Plus provides several EMTs to deal with mapping of
the I/O page and accessing locations within it.
These are discussed below.
See Chapter 8 for a discussion of various mapping techniques which may be used
under TSX-Plus.
-169-

Real-Time Programs
A TSX-Plus real-time program can access the I/O page in one of two ways: It
can cause the program's virtual address region in the range 160000 to 177777 to
be mapped directly to the I/O page so that it can directly access device
registers; or it can leave the virtual address range mapped to the simulated
RMON and use a set of EMTs to peek, poke, bit-set and bit-clear registers in
the I/O page. It is much more efficient to directly access the device control
registers by mapping the I/O page into the program's virtual address region
than to use EMTs to perform each access. However, this technique will not work
if the program must also directly access offsets inside RMON. The correct way
for a program to access RMON offsets is to use the .GVAL EMT which will work
even if the I/O page is mapped into the program region.
11.1.1 EMT to map the I/O page into the program space.
The following EMT can be used to cause the program's virtual address region in
the range 160000 to 177777 to be mapped to the I/O page.
The form of the EMT is:
EMT

375

with RO pointing to the following argument area:
• BYTE

5,140

The I/O page mapping set up by this EMT remains in effect until the program
exits, chains, or the EMT described in the next section is used to remap to
RMON. Note that completion routines and interrupt service routines run with
the same memory mapping as the main-line code of the job.
The .GVAL EMT wi th offset value -8. may be used to determine if PAR 7 is
currently mapped to the I/O page or to the simulated RMON. See the description
in Chapter 7 of the special use of .GVAL for further information.
Example:
.TITLE
.ENABL

MAPIOP
LC

;Demonstrate TSX-Plus EMTs to map to the I/O page and back to RMON
RMONST = 54
CONFIG = 300
176540
RCSR
RBUF
= RCSR+2
CTRLC = 3

START:

jSYSCOM location holding base of RMON
;Fixed offset into RMON of CONFIG word
;Serial line RCSR address
;Line input buffer address
jControl-C

• MCALL
.GLOBL

.PRINT,.EXIT,.TTYOUT,.GVAL
PRTOCT

CALL

SHOMAP

;Display current PAR 7 mapping
-170-

Real-Time Programs
CALL

1$:

2$:

3$:

SHODAT

jDemonstrate "RMON" mapping

.. PRINT IIIOPMSG
llMAPIOP ,RO
MOV
375
EMT
BCC
1$
• PRINT IINOPRIV
• EXIT
SHOMAP
CALL
• PRINT IITYPE
MOV
@IIRCSR,CSRSAV
@#RCSR
CLR
@IIRCSR
TSTB
BPL
2$
MOVB
@IIRBUF ,RO
RO,IICTRLC
CMPB
BEQ
3$
.TTYOUT
BR
2$

;Say we are switching to I/O page mapping
;Point to EMT arg block to
jMap to I/O page
;Branch if OK to map
jYou aren't allowed to do that

CSRSAV, @IIRCSR
IIGOBACK
IlMAPMON,RO
375
SHOMAP
SHODAT

jRestore original CSR
jSay we are returning to original mapping
jPoint to EMT arg block to
;Map back to simulated RMON
jDisplay current PAR 7 mapping
jAnd prove we are back

llMAPMSG
IIAREA, 11-8.

jCurrent mapping preface
jWhat is our current PAR 7 mapping?
jConvert to word offset
jShow which one it is

MOV
• PRINT
MOV
EMT
CALL
CALL
• EXIT

SHOMAP: • PRINT
.GVAL
ASL
• PRINT

RO
CURMAP(RO)

jDisplay current PAR 7 mapping
jPrompt for input from I/O page
;Save a copy of current CSR
jDisable interrupts on serial line
;Is anything available from the line
jNo, keep checking
;Get the new character
jShould we quit?
jQuit on . . C
jDisplay the character
jAnd repeat

RETtJRN

SHODAT: .. PRINT
MOV
MOV
CALL
RETURN
MAPIOP:
MAPMON:
AREA:
CSRSAV:
CURMAP:

.BYTE
• BYTE
•WORD
• WORD
•WORD
• WORD
.NLIST
TORMON: .ASCIZ
TOIOPG: .ASCIZ
MAPMSG: .ASCII

IICNFGIS

@IIRMONST,RO
CONFIG(RO) ,RO
PRTOCT
5,140
6,140
10

;Preface config value
jPick up pointer to RMON base
;Get the current CONFIG value
jDisplay it
jEMT arg block to map to I/O page
jEMT arg block to map to "RMON"
jEMT arg block
jSave CSR for restoration on exit
jCurrent mapping message table

TORMON
TOIOPG
BEX
/simulated RMON./
"I/O page.
/PAR 7 is currently mapped to /<200>
-171-

Real-Time Programs
CNFGIS:
TYPE:
IOPMSG:
GOBACK:
NOPRIV:

.ASCII
.ASCIZ
.ASCIZ
.ASCIZ
.ASCII
.ASCIZ
.END

/Current value of CONFIG word in simulated RMON is /<200>
/Characters entered on serial line will be displayed here:/
<12)"Now switching PAR 7 mapping to the I/O page."
<15><12>/Returning PAR 7 mapping to simulated RMON./
/Real-time support not specified during TSGEN or /
/user not privileged./
START

11.1.2 EMT to remap the program region ~ the simulated RMON.
The following EMT can be used to cause the virtual address mapping region of
the job in the range 160000 to 177777 to be returned to normal mapping if it
had previously been mapped to the I/O page. The form of the EMT is:
EMT

375

with RO pointing to the following argument area:

• BYTE

6,140

Example:
See the example program MAPIOP in the section on mapping the I/O page into the
program space.
11.1.3 EMT to peek at the I/O page.
The following EMT can-beused to access a word in the I/O page wi thout
requiring the job's virtual address region to be mapped to the I/O page. (Note
that the .PEEK and .POKE EMTs can also be used to access parts of the I/O page.
See Chapter 14 for more information on the effects of the .PEEK and .POKE EMTs
with TSX-Plus.) The form of this EMT is:
EMT

375

with RO pointing to the following argument area:
• BYTE
• WORD

1,140
address

where "address" is the address of the word in the I/O page to be accessed. The
contents of the specified word in the I/O page are returned in RO.
The
carry-flag is set on return if real-time support was not included in the
generation of TSX-Plus or the job does not have operator privilege. Note that
wi th this and other EMTs that access the I/O page, if an invalid address is
specified, an error will result with the message:
?MON-F-Kernel mode trap within TSX-Plus

-172-

Real-Time Programs
Example:
.TITLE
.ENABL

PEEKIO
LC

jDemonstrate TSX-Plus EMTs to peek and poke into the I/O page
3
CTRLC
54
RMONST
CONFIG = 300
RCSR
176540
= RCSR+2
RBUF

START:

1$:

• MCALL
.GLOBL

.PRINT,.EXIT,.TTYOUT,.GVAL
PRTOCT

CALL
CALL

SHOMAP
SHOCON

;Display current PAR 7 mapping
jDemonstrate "RMON" mapping

MOV
EMT
BCC
• PRINT
.EXIT
MOV

IIPEEKIO,RO
375
1$
IINOPRIV

;Point to EMT arg block to
;Peek into the I/O page
;Branch if OK
;You aren't allowed to do that

RO,CSRSAV

;Save a copy of current CSR

CLR

POKVAL
/lPOKE 10, RO
375

;Want to disable interrupts
jPoint to EMT arg block to
jPoke a value into the I/O page
jShouldn't be error if peek worked
;Prompt for input from I/O page
;Point to EMT arg block to
;Check the RCSR
;Is anything available from the line
;No, keep checking

Mf\U
j.-~V.

EMT
2$:

• PRINT
MOV
EMT

TSTB
BPL

3$:

;Control-C
;Pointer in SYSCOM area to start of "RMON"
;Fixed offset into "RMON" of config word
;Serial line RCSR address
;Line input buffer address

IITYPE
IIPEEKIO,RO
375
RO
2$

112, PEKADD
ADD
IlpEEKIO,RO
MOV
375
EMT
CMPB
RO,lIcTRLC
BEQ
3$
• TTYOUT
112,PEKADD
SUB
BR
2$

;Point to the receiver buffer
;Point to EMT arg block to
;Get the input character
;Should we quit?
;Quit on . . C
;Display the character
;Point back to the RCSR
;And repeat

MOV
MOV
EMT

;Want to restore the original CSR status
;Point to EMT arg block to
;Restore the CSR

CSRSAV,POKVAL
IlpOKEIO, RO
375

.EXIT
-173-

Real-Time Programs
SHOMAP: • PRINT
• GVAL
ASL
• PRINT
RETURN

RO
CURMAP(RO)

;Current mapping preface
;What is our current PAR 7 mapping?
;Convert to word offset
;Show which one it is

SHOCON: .PRINT
MOV
MOV
CALL
RETURN

IICNFGIS
@IIRMONST,RO
CONFIG(RO) ,RO
PRTOCT

;Preface config value
;Pick up pointer to RMON base
;Get the current CONFIG value
;Display it

PEEKIO:
PEKADD:
POKEIO:
POKADD:
POKVAL:
AREA:
CSRSAV:
CURMAP:

1,140
;EMT arg block to peek into the I/O page
RCSR
;Address to be read
2,140
;EMT arg block to poke into the I/O page
RCSR
;Address to be modified
0
;Word to be moved to POKADD
10
;EMT arg block
0
;Save CSR for restoration on exit
;Current mapping message table
TORMON
TOIOPG
BEX
/simulated RMON./
"I/O page."
/PAR 7 is currently mapped to /<200)
/Current value of CONFIG word in simulated RMON is /<200)
/Characters entered on serial line will be displayed here:/
/Real-time support not specified during TSGEN or /
/user not privi1eged./
START

TORMON:
TOIOPG:
MAPMSG:
CNFGIS:
TYPE:
NOPRIV:

• BYTE
• WORD
• BYTE
• WORD
• WORD
•WORD
• WORD
• WORD
•WORD
.NLIST
.ASCIZ
.ASCIZ
.ASCII
.ASCII
.ASCIZ
.ASCII
.ASCIZ
.END

IlMAPMSG
IIAREA,II-8.

11.1.4 EMT to poke into the I/O page.
The following EMT
be'used to store a value into a cell in the I/O page
without requiring the job's virtual address region to be mapped to the I/O
page. The form of the EMT is:

can-

EMT

375

with RO pointing to the following argument area:
• BYTE
• WORD
• WORD

2,140
address
value

where "address" is the address of the cell in the I/O page and "value" is the
value to be stored. The carry-flag is set on return if real-time support was
not included in the TSX-Plus generation or the job does not have operator
privilege.
-174-

Real-Time Programs
Example:
See the example program PEEKIO in the section on peeking into the I/O page.
11.1.5 EMT to bit-set ~ value into the I/O page.
The following EMT can be used to perform a bit-set (BIS) operation into a cell
in the I/O page without requiring the job's virtual address region to be mapped
to the I/O page. The form of the EMT is:
EMT

375

with RO pointing to the following argument area:
• BYTE
• WORD
• WORD

3,140
address
value

where "address" is the address of the cell in the Iio page and "value" is the
value that will be bit-set into the cell. An error will cause the carry-flag
to be set on return, indicating that either real-time support was not included
in the TSX-Plus generation or the job does not have operator privilege.
Example:

.TITLE
.ENABL

BISIO
LC

jDemonstrate TSX-Plus EMTs to bit-set and bit-clear into the I/O page
CTRLC
RMONST

;Control-C
;Pointer in SYSCOM area to start of "RMON"
;RCSR interrupt enable bit
jFixed offset into "RMON" of config word
;Serial line RCSR address
jLine input buffer address

3
54
100
INTNBL
CONFIG = 300
RCSR
176540
= RCSR+2
RBUF

START:

• MCALL

.PRINT,.EXIT,.TTYOUT,.GVAL

CALL
CALL

SHOMAP
SHOCON

MOV

IIBICIO,RO
375

jDisplay current PAR 7 mapping
jDemonstrate "RMON" mapping

BCC
• PRINT
• EXIT

1$
IINOPRIV

jWant to clear input interrupts
jPoint to EMT arg block to
jClear a bit in the I/O page
;Branch if OK
;You aren't allowed to do that

• PRINT

IITYPE

jOK, interrupts should be disabled
jPrompt for input from liD page

EMT

1$:

-175-

Real-Time Programs
2$:

TSTB
BPL

/lPEEKIO,RO
375
RO
2$

jPoint to EMT arg block to
;Check the RCSR
;Is anything available from the line
jNo, keep checking

ADD

112,PEKADD

MOV
EMT

/lPEEKIO,RO
375

;Point to the receiver buffer
;Point to EMT arg block to
;Get the input character
;Value from peek is returned in RO
; Should we qui t ?
;Quit on . . C
jDisplay the character
jPoint back to the RCSR
jAnd repeat

MOV
EM!

CMPB
RO,IICTRLC
3$
BEQ
.TTYOUT
SUB
112,PEKADD
BR
2$
3$:
MOV
EMT

IIBISIO,RO
375

;Want to set input interrupts
jPoint to EMT arg block to
;Set a bit in the I/O page

• EXIT

RO
CURMAP(RO)

;Current mapping preface
;What is our current PAR 7 mapping?
;Convert to word offset
jShow which one it is

SHOCON: .PRINT
MOV
MOV
CALL
RETURN

IICNFGIS
@IIRMONST,RO
CONFIG(RO) ,RO
PRTOCT

;Preface config value
;Pick up pointer to RMON base
jGet the current CONFIG value
jDisplay it

PRTOCT: MOV
MOV
MOV
MOV
MOV
1$:
MOV
BIC

Rl,-(SP)
R2,-(SP)
R3,-(SP)
IIEOW,R2

;Save rl-r3 on the stack
;RO contains word of interest

SHOMAP: .PRINT
•GVAL
ASL
• PRINT
RETURN

ADD

MOVB
CLC
ROR
ASH
SOB
• PRINT
MOV
MOV
MOV

IIMAPMSG
IIAREA, 11-8.

116,R3

RO,Rl
11177770,Rl
/I . . O,Rl

Rl,-(R2)

;Point to end of 6 char output buffer
jSet up counter for 6 chars
jSet up mask for low 3 bits (Is digit)
;Get low 3 bits
jConvert to ascii
;Fill octal digits in from end

RO
11-2,RO

R3,1$
IICHARS

(SP)+,R3
(SP)+,R2
(SP)+,Rl

jShift out bits just converted
jRepeat for 6 chars
jDisplay result at console
;Restore registers rl-r3

-176-

Real-Time Programs

RETURN
PEEKIO: .BYTE
PEKADD: .WORD
BICIO: • BYTE
• WORD
• WORD
BISIO: • BYTE
•WORD
• WORD
AREA:
.BLKW
CSRSAV: • WORD
CHARS: .BLKB
EOW:
• WORD
CURMAP: • WORD
• WORD
.NLIST
TORMON: .ASCIZ
TOIOPG: .ASCIZ

MAPMSG: .ASCII
CNFGIS: .ASCII
TYPE:
.ASCIZ
NOPRIV: .ASCII
.ASCIZ
• END

1,140
RCSR
4,140
RCSR
INTNBL
3,140
RCSR
INTNBL
10

o
6

jEMT arg block to peek into the I/O page
jAddress to be read
;EMT arg block to clear a bit in the I/O page
;Input status register
;Interrupt enable mask
;EMT arg block to set a bit in the I/O page
jlnput status register
jlnterrupt enable mask
jEMT arg block
jSave CSR for restoration on exit
j6 char output buffer
jTerminator for .PRINT
jCurrent mapping message table

TORMON
TOIOPG
BEX
/simulated RMON./
"rio page."
/PAR 7 is currently mapped to /<200)
/Current value of CONFIG word in simulated RMON is /<200)
/Characters entered on serial line will be displayed here:/
/Real-time support not specified during TSGEN or /
/user not privileged./
START

11.1.6 EMT to do a bit-clear into the 1/0 page.
The following --m.tT" can be used toperform a bit-clear (BIC) operation into a
cell in the I/O page without requiring the job's virtual address region to be
mapped to the I/O page. The form of the EMT is:

EM!

375

with RO pointing to the following argument area:
• BYTE
• WORD
• WORD

4,140
address
value

where "address" is the address of the cell in the I/O page and "value" is the
value to be bi t-C.leared into the specified cell. An error will cause the
carry-flag to be set on return, indicating that either real-time support was
not included in the TSX-Plus generation or the job does not have operator
privilege.
Example:
See the example program BISIO in the section on doing a bit-set into the I/O
page.
-177-

Real-Time Programs
11.2 Mapping to ~ physical memory region
In certain circumstances, it is desirable to map a portion of virtual memory to
a specific area in physical memory which is not in the I/O page. Possible
examples would be ROM memory or an array processor. This mapping is done by
altering one or more of the Page Address Registers (PARs) for the job. Each
PAR maps 8192 bytes of memory from the virtual job space into physical memory.
There are 8 PAR's (8*8192=64Kb). The region of memory mapped through each PAR
is shown by the table below:
PAR

Virtual Region

--------------0
1
2
3
4
5
6
7

000000 - 017777
020000 - 037777
040000 - 057777
060000 - 077777
100000 - 117777
120000 - 137777
140000 - 157777
160000 - 177777

The form of this EMT is:
EMT

375

with RO pointing to the following argument area:
• BYTE
• WORD
• WORD
.l-lORD

• WORD

17,140
par-number
phys-address
size
access

"par-number" is the number of the Page Address Register (PAR) that
corresponds to the beginning of the program virtual address region that is
to be mapped.
"phys-address" is the physical address to which the virtual address is to
be mapped. The physical address is specified as an address divided by 64
(decimal) • Tha t is, the physical address represents the 64-byte block
number of the start of the physical region.
Note that the physical
address of any 64-byte block within a 22-bit physical address space can be
represented in 16 bits.
"size" is the number of 64-byte blocks of memory to be mapped through the
virtual region. Each PAR can map up to 128 64-byte blocks of memory. If
more than 128 blocks are ma.ppeQ., successively higher PARs are set up to
map the remainder of the region.

-178-

Real-Time Programs
"access" indicates if the mapped region is to be allowed read-only access
or both read and write access: 0 = read-only; 1 = read/write.
This EMT may be used to map any of the PARs to any physical address regions
desired (even to map PAR 7 to the I/O page). The use of this EMT does not
affect mapping set up previously for other PARs. If the "size" parameter is 0
(zero), all PAR mapping is reset and the normal virtual address mapping for the
job is restored.
An error on return indicates either that real-time support was not included in
the TSX-Plus generation process or that the job does not have operator
privilege.
Note that this EMT is not equivalent to the extended memory EMTs used with PLAS
(Program . . s Logical Address Space) requests and virtual overlays and virtual
arrays. See Chapter 8 for a discussion of job environment and the appropriate
RT-11 manuals for a more complete discussion of PLAS features.
Example:
.TITLE
.ENABL

HAPPHY
LC

Demonstrate TSX-Plus EMT to map to any physical address
CTRLC

INTNBL
RCSR
RBUF

START:

1$:
2$:

;Control-C
;Interrupt enable bit
;Serial line RCSR address
;Line input buffer address

3
100
176540
RCSR+2

•MCALL

.PRINT,.EXIT,.TTYOUT,.GVAL

• PRINT

tlMAPMSG

MOV
EMT
BCC
• PRINT
.EXIT
• PRINT
BIC
TSTB
BPL
MOVB
CMPB
BEQ

tIMAPPHY,RO
375

1$
#NOPRIV
IITYPE
IIINTNBL, @IIRCSR

;Prompt for input from I/O page
jDisable interrupts on serial line
;Is anything available from the line
;No, keep checking
;Get the new character
;Should we quit?
;Quit on .... c
jDisplay the character
;And repeat

CLR
MOV

SIZE
IIMAPPHY , RO

;If .size is 0, original mapping is restored
;Point to EMT arg block to

@tIRCSR

2$
@IIRBUF ,RO
RO,IICTRLC
3$

• TTYOL"T

3$ :

;Say we are switching to physical mapping
;Point to EMT arg block to
;Map to physical memory
;Branch if OK to map
;You aren . . t allowed to do that

-179-

Real-Time Programs
EMT

375

;Revoke mapping to physical address

17,140

;EMT arg block to map to physical memory
;remap PAR 7
;17760000/64. address to map into PAR 7
;size of region to be mapped - full 8kb
;access O=read-only, l=read/write

.EXIT
MAPPHY: • BYTE
• WORD
•WORD
• WORD
SIZE:
.WORD
.NLIST
MAPMSG: .ASCIZ
.ASCIZ
TYPE:
NOPRIV: .ASCII
.ASCIZ
.END

177600
20000
1

BEX
/PAR 7 mapping is now directed to top of physical memory./
/Characters entered on serial line will be displayed here:/
/Real-time support not specified during TSGEN or /
/user not privileged./
START

11.3 Requesting exclusive system control
The following EMT allows real-time jobs to gain exclusive access to the system
while they perform time-critical tasks. The form of the EMT is:
EMT

375

with RO pointing to the following argument block:
• BYTE

14,140

The effect of this EMT is to cause the TSX-Plus job scheduler to ignore all
other jobs, even higher priori ty jobs - including fixed-high-priori ty jobs,
until the real-time job relinquishes exclusive access control. Note that this
is different (and more powerful) than giving the real-time job a higher
execution priority because all other jobs are completely prevented from
executing even if the real-time job goes into a wait state causing the CPU to
become idle.
The form of the EMT used to relinquish exclusive system access is:
EMT

375

with RO pointing to the following argument block:
• BYTE

15,140

In order to use either of these EMTs, the real-time option must be included
when the TSX-Plus system is generated and the executing job must have operator
command privilege.
The following restrictions apply to a job that has issued an exclusive access
EMT:
-180-

Real-Time PrJgrams
1.

The job is automatically locked in memory during the time it has
exclusive access to the system. If you wish to use the TSX-Plus EMT
that locks a job in the lowest portion of memory~ that EMT must be
executed before calling this EMT to gain exclusive access to the
system.

The size of the job may not be changed while it has exclusive access
to the system.

Exclusive access is automatically relinquished if the job exits or traps but is
retained if the job chains to another job.
Example:
.TITLE
.ENABL

STEALS
LC

Demonstrate TSX-Plus EMT to obtain exclusive system control
LEAD IN

JSW
TTSPC
NOWAIT

44
10000
100

START:

;TSX-Plus program controlled terminal
;option lead-in character.
;Job status word address
;TT special mode bit in JSW
;TT nowait bit in JSW

• MCALL

.PRINT,.TTYOUT,.TTYIN,.EXIT

MOV

#TTSPC!NOWAIT,@#JSW

.TTYOUT #LEADIN
.TTYOUT #'S
.TTYOUT i/LEADIN
.TTYOUT II'u
• PRINT
MOV
EMT

IIMSG
IlsTEALS, RO
375

.TTYIN
MOV
EMT
.EXIT

IILETGO,RO
375

.NLIST
STEALS: • BYTE
LETGO: • BYTE
.ASCII
MSG:
.END

;Set TT special mode and nowait
;bits in the JSW
;And make TSX-Plus understand both

;Prompt for input
;Point to EMT arg block to
;Steal exclusive system control
;Time critical processing goes here
;Simulated here with terminal input
;Point to EMT arg block to
;Relinquish exclusive system control

BEX
14,140
;EMT arg block for exclusive system control
15,140
;EMT arg block to relinquish exclusive control
IOther users are locked out until you press a key: 1<200)
START
-181-

Real-Time Programs
11.4 Locking ~ job in memory
In time-critical real-time applications where a program must respond to an
interrupt with minimum delay, it may be necessary for the job to lock itself in
memory to avoid program swapping. This facility should be used wi th caution
since if a number of large programs are locked in memory there may not be
enough space left to run other programs.
TSX-Plus provides two program locking facilities. The first moves the program
to the low end of memory before locking it; this is done to avoid fragmenting
available free memory.
This type of lock should be done if the program is
going to remain locked in memory for a long period of time. However, this form
of locking is relatively slow since it may involve program swapping. The
second locking facility simply locks the program into the memory space it is
occupying when the EMT is executed without doing any repositioning. This EMT
has the advantage that it is extremely fast but free memory space may be
non-contiguous.
The form of the EMT used to lock a program in low memory (re-positioning if
necessary) is:
EMT

375

with RO pointing to the following argument area:

• BYTE

7,140

An error will cause the carry-flag to be set on return, indicating that either
real-time support was not included in the TSX-Plus generation or the job does
not have operator privilege.

The form of the EMT used to lock a job in memory without repositioning it is:
EMT

375

with RO pointing to the following argument area:

• BYTE

13,140

An error will cause the carry-flag to be set on return, indicating that either
real-time support was not included in the TSX-Plus generation or the job does
not have operator privilege.
Example:
See the example program ATTVEC in
interrupt to a completion routine.

the

-182-

sec tion on connec ting a real-time

Real-Time Programs
11.5 Unlocking ~ job from memory
When a job locks itself in memory, it remains locked until the job exits or the
following EMT is executed.
The form of the EMT used to unlock a job from
memory is:

EMT

375

with RO pointing to the following argument area:
• BYTE

10,140

An error w~ll cause the carry=flag to be set on return, indicating that either
real-time support was not included in the TSX-Plus generation or the job does
not have operator privilege.
Example:
See the example program ATTVEC in
interrupt to a completion routine.

the

section on connecting a real-time

11.6 Suspending/Resuming program execution
The RT-11 standard .SPND and .RSUM EMTs are used by TSX-Plus real-time jobs to
suspend and resume their execution. Frequently, a real-time job will begin its
execution by connecting interrupts to completion routines and doing other
initialization and then will susPend its eXecution while waiting for a device
interrupt to occur.
The .SPND EMT causes the main-line code in the job to be suspended. Completion
routines are not affected and execute when interrupts occur. If a completion
routine executes a .RSUM EMT, the main-line code will continue execution at the
point following the • SPND when the completion routine exits.
Refer to the
RT-11 Programmer's Reference Manual for further information about the use of
.SPND and .RSUM.
Example:
See the example program ATTVEC in
interrupt to a completion routine.

the

-183-

section on connecting a

real-time

Real-Time Programs
11.7 Converting ~ virtual address ~ ~ physical address
When controlling devices that do direct memory access (DMA) , it is necessary to
be able to obtain the physical memory address (22-bit) that corresponds to a
virtual address in the job.
Note that a job should lock itself in memory
before performing this EMT. The form of the EMT is:
EMT

375

with RO pointing to the following argument area:
• BYTE
•WORD
• WORD

0,140
virtual-address
result-buffer

where "virtual-address" is the virtual address that is to be converted to a
physical address and "resul t-buffer" is the address of a two word area that is
to receive the physical address. The low-order 16 bits of the physical address
are stored in the first word of the result buffer and the high-order 6 bits of
the physical address are stored in bit positions 4-9 of the second word of the
result buffer.
An error will cause the carry-flag to be set on return, indicating that either
real-time support was not included in the TSX-Plus generation or the job does
not have operator privilege.

Example:
.TITLE
.ENABL

PHYADD
LC

Demonstrate TSX-Plus EMT to convert a virtual to a physical address

START:

1$:
2$:

•MCALL

• PRINT, • EXIT

MOV
EMT
BeC
• PRINT
BR
• PRINT
MOV
CALL
.EXIT

IILOKJOB,RO
375
1$
IINOPRIV
2$
IISTRADD
IISTART,RO
PRTADD

;Point to EMT arg block to
;Lock job in memory
;Continue if OK
;Explain the problem
;and quit
;Say where this program was loaded
;Get the virtual address
;and display it to the terminal

RO,VIRADD
IlpHYADD, RO
375
BUFFER,R1
<BUFFER+2),R2

;Put the virtual address into the arg block
;Point to EMT arg block to
;Convert virtual to physical address
;Retrieve the low address
;And the high address

PRTADD: MOV
MOV
EMT
MOV
MOV

-184-

Real-Time Programs

1$:

2$:

3$:

BIC
MOV
ASR
SOB
MOV
MOV
MOV
BIC
ADD
MOVB
MOV
ASR
ROR
SOB
SOB
• PRINT
RETURN

LOKJOB: .BYTE
PHYADD: .BYTE
VlRADD: .WORD
• WORD
BUFFER: .WORD
.BLKB
CHREND: .WORD
.NLIST
NOPRIV: .ASCII
.ASCIZ
STRADD: .ASCII
.END

fl C17 60, R2
A

114~R3

;Use only bits 4-9
;Throw away bits 0-3

R2
R3,1$
IICHREND, R4

118. ,R3
R1,RO
II C7 ,RO
11'0 ,RO
RO,-(R4)
113,R5
R2
R1
R5,3$
R3,2$
R4
A

13,140
0,140

BUFFER
0,0
10.

;Point to end of character output buffer
;Need to convert 8 digits
;Get a copy of low bits into RO
;Mask out all but low digit
;Convert to ASCII
;Put low digit in output buffer
;Shift over 3 bits to next digit
;Low bit of high address
;into high bit of low address
;Do all 8 digits
;Print out the result

;EMT arg block to lock job in memory
;EMT arg block to determine physical address
;Virtual address to be located
;Location of 2 word result buffer
;Will hold low and high physical address
;Buffer to hold ASCII value of address
;End of ASCII buffer

BEX
IReal-time not included in TSGEN or user 1
/not privileged./
IThis program is loaded at START = 1<200)
START

11.8 Specifying ~ program-abort device reset list
The standard RT-11 .DEVICE EMT is used by TSX-Plus real-time jobs to specify a
list of device control registers to be loaded wi th specified values when the
job terminates.
This feature is useful in allowing real-time devices to be
turned-off if the real-time control program aborts. The TSX-Plus .DEVICE EMT
has the same form and options as the standard RT-11 .DEVICE EMT. See the RT-11
Programmer's Reference Manual for further information.
The connection between interrupt vectors and interrupt service routines or
interrupt completion routines is automatically dropped when a job terminates.

-185-

Real-Time Programs
11.9 Setting processor priority level
The following EMT allows a program to set the processor priority level. This
can be useful in a situation where it is necessary for a real-time job to block
interrupts for a short period of time while it is performing some critical
operation. On return from this EMT, the job is executing in user mode with the
specified processor priority level. The form of the EMT is:
EMT

375

with RO pointing to the following EMT argument block:
• BYTE

•WORD

16,140
prio-level

where "prio-level" should be 7 to cause interrupts to be disabled or 0 to
reenable interrupts.
Interrupts should not be disabled for a long period of
time or clock interrupts and terminal I/O interrupts will be lost.
Note that it is not possible to raise the processor priority level by storing
directly into the processor status word from a real-time program because the
PDP-11 hardware disallows modification of the PSW by a user mode program even
if the program has access to the I/O page.
Example:
See the example program ATTVEC in
interrupt to a completion routine.

the

sec tion on connec ting a real-time

11.10 Setting Job Execution Priority
Jobs may be assigned priority values in the range 0 to 127 to control their
execution scheduling relative to other jobs. The priority values are arranged
in three groups: the fixed-low-priority group consists of priority values from
o up to the value specified by the PRILOW sysgen parameter; the fixed-highpriority group ranges from the value specified for the PRIHI sysgen parameter
up to 127; the middle priority group ranges from (PRILOW+1) to (PRIHI-1). The
current values for PRIHI and PRILOW may be determined with the SHOW PRIORITY
command, or from within a program with a .GVAL request. The following diagram
illustrates the priority groups:

-186-

Real-Time Programs
127

+------------+

-->1

Fixed
I
high
1 priorities

PRIHI

1
1

I
1

-->1

+------------+

Normal
1
PRIDEF -->1
job
I
I priorities I
1

+------------+

PRILOW -->1

Fixed
low
I priorities

-->1
+------------+

to other jobs"

A job with a fixed priority is allowed to

execute as long as it wishes until a higher priority job becomes active.
The fixed-high-priority group is intended for use by real-time programs. The
fixed-low-priority group is intended for use by very low priori ty background
tasks. Normal time-sharing jobs should not be assigned priorities in either of
the fixed priority groups.
The middle group of priorities from (PRILOW+1) to (PRIHI-1) are intended to be
used by normal, interactive, time-sharing jobs.
Jobs with these assigned
priorities are scheduled in a more sophisticated manner than the fixed-priority
jobs. In addition to the assigned priority, external events such as terminal
input completion, I/O completion, and timer quantum expiration play a role in
determining the effective scheduling priority.
When a job with a normal priority switches to a virtual line, the priority of
the disconnected job is reduced by the amount specified by the PRIVIR sysgen
parameter. This causes jobs that are not connected to terminals to execute at
a lower priority than jobs that are. This priority reduction does not apply to
jobs with priorities in the fixed-high-priority group or the fixed-low-priority
group. The priority reduction is also constrained so that the priority or jobs
in the normal job priority range will never be reduced below the value of
(PRILOW+1) •

-187-

Real-Time Programs
The following EMT can be used to set the job priority from within a program.
Unlike the other real-time EMT's in this chapter, this EMT does not require
operator privilege. The maximum priority which may be used by a job is set by
the system manager. The job priority can also be set from the keyboard with
the SET PRIORITY command. The current job priority, maximum allowed priority,
and fixed-high- and fixed-low-priority boundaries may be determined with the
.GVAL request. See the TSX-Plus System Manager's Guide for more information on
the significance of priority in job scheduling. The form of this EMT is:
EMT 375
with RO pointing to the following EMT argument block:
• BYTE
• WORD

0,150
value

where "value" is the priority value for the job. The valid range of priorities
is 0 to 127 (decimal). The maximum job priority may be restricted through the
logon mechanism.
If a job attempts to set its priority above its maximum
allowed priority, its priority will be set to the maximum allowed. This EMT
does not return any errors.
Example:
See Chapter 7 for an example of the use of this EMT.
11.11 Connecting interrupts to real-time jobs
One of the most important uses for real-time jobs is to service interrupts for
non-standard devices.
TSX-Plus provides three mechanisms for connecting
user-written real-time programs to interrupts:
device handlers, interrupt
service routines, and interrupt completion routines.
Interrupt service
routines and interrupt completion routines permit jobs to process interrupts
without the necessity of writing a special device handler. However, there are
restrictions on the use of these two methods which must be considered when
deciding the appropriate method for handling special device interrupts.
The fastest method of handling interrupts is to write a device handler
(driver).
Device handlers execute in kernel mode and provide the fastest
possible response to interrupts.
A device handler is the best choice when
interrupts occur at a rate which significantly loads the system.
Device
handlers written for use with TSX-Plus should conform to the rules for writing
device handlers for RT-11XM.
The second method for processing real-time interrupts is to connect the
interrupt to a real-time interrupt service routine.
The interrupt service
routine is written as a subroutine in a real-time job; it is not necessary to
write a separate device handler. Interrupt service routines are connected with
minimal system overhead and can service interrupts quite rapidly (approximately
2000 per second on an 11/44). Interrupt service routines are called in user

-188-

Real-Time Programs
mode but can only execute a limited set of system service calls (EMT . . s).
Interrupt service routines can trigger the execution of interrupt completion
routines to perform additional processing.
The third method for processing real-time interrupts is to connect the
interrupt to an interrupt completion routine.
Real-time interrupt completion
routines have access to the full job context and can use most system service
calls (EMT's), but have more overhead and should not be used for interrupts
that occur more frequently than 200 times per second.
The following diagram illustrates the different levels of interrupt

-189-

processing~

Real-Time Programs
Interrupt Processing

+--------------------------------------------------------------------+

Level 2

Level 1

Level 3

Hardware interrupt

I
I
I
I
I
I
I
I
I

v
• INTEN

I
V

.FORK

>-----------------+
1

1<--------------+

+-----------+

1 Interrupt 1

Service
Routine

I
I

1
1
+-----------+

1
1

+--------------+
I

More
Fork
Requests

I
1

I
(yes)

1
1
1
1

1-------+

+--------------+

(no) 1

1<-------------------------------+ I
v i i
+--------------+
+------------+ 1 I
1 Any Pending

1 I 1
1 1 1
1------->1 Routine 1--+ 1
?
1
1
1
1
1
+------------+
I
+--------------+
Completion
1 Routines
I

(no)

1
I

(yes)

Interrupt

1 Completion

+---------------------+

I
I

1
1
1

Return from interrupt

+--------------------------------------------------------------------+

-190-

Real-Time Programs
This diagram shows that there are three "levels" of interrupt processing.
Level 1 is entered when a hardware interrupt occurs.
In this level the
processor (hardware) priority is set to 7 which causes other interrupt requests
to be temporarily blocked. After some brief interrupt entry processing, the
system performs a .FORK operation which queues a request for processing at fork
level and then drops the processor priority to O.
At this time another
hardware interrupt can occur, in which case the cycle will be repea ted and
another request for fork level processing will be placed on the queue. Note
that if .FORK requests are issued at a sustained high rate, such that numerous
prior requests cannot be serviced, a system error may eventually occur.
Level 2 processing is also known as "fork level" processing. This level of
interrupt processing services requests that were placed on a queue by the .FORK
operation. Hardware interrupts are enabled during this processing and if any
other interrupts occur their .FORK requests are placed at the end of the queue.
Interrupt service requests are processed serially in the order that the
interrupts occurred. Only two system service calls may be used from service
routines running at fork level: a request to queue a user completion routine
for subsequent processing; and the .Rsufi EMT.
Level 3 processing occurs in "job state". That is, the TSX-Plus job execution
scheduler selects the highest priority job or completion routine and passes
execution to it. Completion routines run with full job context and may issue
system service calls (except USR calls) as needed.
Completion routines are
serialized for each job.
That is, all other completion routines (including
higher priority interrupt completion routines) which are scheduled for the same
job are queued for execution and will not be entered until the current
completion routine exi ts.
During level 3 processing, interrupts are enabled
and job execution may be interrupted to process fork level interrupt service
routines or by higher priority completion routines for other jobs.
11.11.1 Interrupt service routines.
Interrupt service routines execute in user mode but require a minimal a~ount of
system overhead. When an interrupt is received through a vector which has been
connected to an interrupt service routine, TSX-Plus executes a .INTEN and a
• FORK, sets up memory management for the appropriate job, saves the status of
the floating point unit (FPU) if it is in use, and passes control to the
interrupt service routine. Using this approach, interrupts may be serviced at
about 2000 per second on a PDP-I1/44. Lower rates should be expected on slower
processors.
Several restrictions apply to this method of interrupt processing:
a)

The job must be locked in memory betore connecting to the interrupt
vector and must remain locked in memory as long as the interrupt
connection is in effect.

The processing done by the interrupt service routine should be brief
since other interrupts that do • FORKs will be queued until the
interrupt service routine exits.
-191-

Real-Time Programs
c)

Only two system service calls (EMTs) are valid within a interrupt
service routine:
1)

A .RSUM EMT may be issued to cause the job's main-line code to
continue processing if it has done a .SPND.

The TSX-Plus
routine.

EMT

which

schedules

execution

of a completion

Access to the I/O page is possible if the main-line code sets up such mapping
prior to the interrupt.
Registers are undefined on entry to an interrupt
service routine, and do not have to be preserved by the interrupt service
routine.
An interrupt service routine must exit with a RETURN instruction (RTS PC), not
an RTI. Since interrupt service routines execute at fork level, job scheduling
is not relevant for them. All fork level processing, whether queued for system
processing or for an interrupt service routine, is executed in the order in
which the interrupts were received and execute before any completion routines,
fixed-priority jobs or normal interactive time-sharing jobs.

The form of the request to connect an interrupt service routine to a vector is:
EMT 375
with RO pOinting to the following argument block:
• BYTE
•WORD
• WORD
. WORD

20,140
vector-address
service-routine

where "vector-address" is the address of the interrupt vector to which the
service routine is to be connected, and "service-routine" is the address of the
entry point of the interrupt service routine.
The total number of vectors that can be connected either to interrupt service
routines or interrupt completion routines is determined by the RTVECT parameter
during TSX-Plus system generation.
Error:
Code

o
1
2
3

Meaning
Real time not included or job not privileged
There are no free interrupt control blocks
Some other job is already connected to that vector
Job is not locked in memory

The association between an interrupt service routine and an interrupt vector
may be released by the same EMT as used to disconnect an interrupt completion
-192-

Real-Time Programs
routine.
chapterQ

See the section on releasing an interrupt connection later in this

Example:
.TITLE
.ENABL

INTSVC
LC

Demonstrate EMT to implement an interrupt service routine
Simple file capture program. Steal a time-sharing line
and put everything that comes in on it into a file •

•MeALL
•MCALL
VECTOR
RCSR
RBUF
BUFSIZ
INTNBL
CTRLC
CTRLD

330
176530
RCSR+2
256.
= 100
3
4

START:

• GVAL
TST

•TTYIN,.TTYOUT,.EXIT,.PEEK,.POKE,.GVAL,.SCCA
.ENTER,.LOOKUP,.CSISPC,.WRITE,.PURGE,.CLOSE,.DEVICE
;Serial line vector
jSerial line RCSR address
;Serial input buffer address
;Size of buffer in words
jInterrupt enable bit in RCSR
;ASCII control-C
jASCII control-D

IIAREA, 11-6.
RO

DL\{

DUA

ATTT""
\{U.l.l.

MOV
EMT
MOV
EMT

IILOKJOB,RO
375
IlMAPIO,RO
375

jSee if job is privileged
j1 if priv, 0 if not
;Immediate exit if not priv
jPoint to EMT arg block to
;Lock job in memory
jPoint to EMT arg block to
jMap PAR7 into the I/O page

SP, SPSAVE
;Save SP prior to CSI call
GETFIL: MOV
.CSISPC #OUTSPC,#DEFEXT,#O ;Get file specification
.Lv,
BCS
1$
jRepeat until valid command line
MOV
SPSAVE,SP
;Restore SP, no valid switches
• ENTER #AREA,#O,#INSPC,#-l jOpen largest possible output file
1$
jOn error, ask for new file
BCS
MOV
#BUFF1,BUFPTR
jlnitialize buffer pointer
BLOCK
jlnitialize output file block count
CLR
,

(:0 •

Set up to accept terminal commands
ctrl-c, ctrl-c to abort; ctrl-d to end transmission
.SCCA
IIAREA,IITTSTAT
jDisable control-c abort
MOV
#ACTCTD,RO
;Point to EMT arg block to
EMT
375
jActivate input on AD
Since we are going to borrow a current time-sharing line, we need
to save its vector pointers for later restoration
MOV
@#RCSR,CSRSAV
jSave old status bits, esp. int. enable
.DEVICE #AREA,#DEVLST
jForce restoration of RCSR on exit
-193-

Real-Time Programs
BIC
• PEEK
MOV
• PEEK
MOV

IIINTNBL,@IIRCSR
IIAREA,IIVECTOR
RO,VECSAV
IIAREA,IIVECTOR+2
RO,VECSV2

;Disable interrupts until ready
;Get normal vector pointer
;And save it for later restoration
;Get normal priority
;And save it for later restoration

Now attach interrupt service routine to input vector
IIINTSVC,RO
MOV
;Point to EMT arg block to
375
;Schedule interrupt service routine
EMT
GO:
IIINTNBL, @IIRCSR ;Enable interrupts and wait for input
BIS
;Wait for terminal command during transfer
.TTYIN INBUF
Resume here when transfer is complete, or want to abort
IIINTNBL, @IIRCSR ;Disable interrupts (data lost if mistake)
WHOA:
BIC
CMPB
INBUF , IlcTRLC
;Was it a control-c?
BNE
;Branch if not
5$
• PURGE I/O
;If CTRL-C, throwaway input
TTSTAT
;Did we get double control-c's?
TST
GETFIL
;If not, get another file name
SEQ
;If double control-c, then abort
BR
QUIT
INBUF,IICTRLD
;Is the transmission done?
5$:
CMPB
GO
;Branch if not
BNE
FINISH
CALL
;Write out remainder o~ current buffer
• CLOSE 110
;If done, close out file
; Done or abort, restore time-sharing line conditions
MOV
IIRELVEC,RO
;Point to EMT arg block to
QUIT:
EMT
375
;Release interrupt connection
.POKE
IIAREA,#VECTOR+2,VECSV2 ;Restore old priority
.POKE
IIAREA,lIvECTOR,VECSAV
;And old vector pointer
• EXIT
; And done!
Interrupt service routine, executes at .FORK level
ISR:

BHI
BLO
MOV
BR
CMP
BLO
MOV
MOV

@IIRBUF ,@BUFPTR
BUFPTR
SUFPTR,IIBUFF2
1$
9$
IIBUFFl, WRTPTR
2$
BUFPTR,#BUFEND
9$
IIBUFF 1, BUFPTR
IIBUFF2, WRTPTR

;Put char in buffer
;And point to next location
;Which buffer in use?
;Branch if already in second
;Return if first not full
;Exact end of buffer 1, point to it
;Schedule write
;Second buffer full yet?
;Not yet, return
;Second buffer full, reset pointer
;Point to second buffer for write

MOV
EMT

IlsCHWR T, RO
375

;Point to EMT arg block to
;Schedule completion routine
ito write buffer to file

MOVB
INC
CMP

1$:

2$:

-194-

Real-Time Programs
9$:
10$:

TST
BEQ
BIC
RETURN

TTSTAT
10$
IIINTNBL,@IIRCSR

jDoes mainline want to quit? (ACAC)
;Branch if not
;If so, disable interrupts
;Wait for another char
;Note RTS PC, not RTI !

j Completion routine to save buffer to file
CMPRTN: .WRITE
BCC
MOVB
MOV
JMP

1$:

INC
RETURN

#AREA,#0,R1,1I256.,BLOCK jWrite buffer to file
1$
jBr if no error
CTRLC,INBUF
jOn error, set abort flags
#-l,TTSTAT
jSkip .TTYIN, and abort
WHOA
jPoint to next output block
BLOCK

Routine to complete write of last block
FINISH: MOV
MOV
CMP
BLO
ADD
CLRB
1$:
CMP
BLO
SUB
CALL
RETURN

BUFPTR,RO
IIBUFF2,R1
RO,R1
1$
112*BUFS IZ, R1
(RO)+
RO,R1

jGet current buffer pointer
;Point to end of first buffer
jSee which buffer in use
;Skip if in first
;If in second, point to end
;Zero out buffer
jALI the way to the end

112*BUFSIZ ,R1
CMPRTN

;Now point back to buffer beginning
jCall write routine (NOT AS COMPLETION)

'J..;;"~

EMT arg block areas
AREA:

,,,
.LV

jGeneral EMT arg block

LOKJOB: • BYTE

13,140

;EMT arg block to lock job in mem

MAPIO:

.BYTE

5,140

;EMT arg block to map I/O page to PAR 7

ACTCTD: • BYTE

0,152

;EMT arg block to
;Set activation character
jControl-D

• BLl{Tvl

• WORD

CTRLD

INTSVC: • BYTE
• WORD
•WORD

20,140
VECTOR
ISR

;EMT arg block to set up interrupt svc routine
;Vector to attach
jAddress of Interrupt Service Routine
; Requ!.red

21,140
CMPRTN
7

jEMT arg block to sched compl routine
jWrite buffer contents to file
jReal-time priority (adds to PRIHI)

• WORD

SCHWRT: • BYTE
• WORD
•WORD

-195-

Real-Time Programs
WRTPTR: • WORD
• WORD
RELVEC: • BYTE
• WORD

°°
12,140
VECTOR

;Passed in Rl to compl routine (buffer addr)
;Required
;EMT arg block to release interrupt connection
;Vector to be released

General storage
OUTSPC:
INSPC:
DEFEXT:
SPSAVE:
BLOCK:
TTSTAT:
VECSAV:
VECSV2 :
DEVLST:
CSRSAV:

.BLKW
.BLKW
• WORD
• WORD
•WORD
• WORD
•WORD
• WORD
• WORD
• WORD
• WORD
BUFPTR: • WORD
INBUF : • BYTE
BUFFI : .BLKW
BUFF2: .BLKW
BUFEND:
.END

15.
24.
0,0,0,0

°
°
°
°

°RCSR
°
°
°0,0,0,0
BUFSIZ
BUFSIZ

JCSI output file specs
;CSI input file specs
;No default file specs
;Save stack pointer during CSI call
;Output file block counter
;SCCA terminal status word
;Save original vector contents
; and priority
;.DEVICE restoration list
;To hold original value of RCSR
;End of list
;Current input char pointer
;Terminal command buffer
;1 block input buffer
;Second buffer

START

Interrupf-cilmpletlOn routines-~
The TSX-Plus real-time support facility allows a program to connect a real-time
interrupt to a completion routine.
If this is done, TSX-Plus schedules the
completion routine to be executed each time the specified interrupt occurs.

tl~ lr~Z

Interrupt completion routines have much greater flexibility than interrupt
service routines, but require more overhead and are capable of servicing
interrupts only at a lower rate. Interrupt completion routines run with full
job context. This allows them to use all system service calls (except to the
USR). Registers will be preserved between calls to the completion routine.
Real-time completion routines can service interrupts at rates up to about 200
interrupts per second.
Devices which interrupt at a faster rate should be
connected through an interrupt service routine or through a special device
handler.
The total number of interrupt vectors that can be connected either to interrupt
completion routines or interrupt service routines is determined by the RTVECT
parameter during TSX-Plus system generation.
It is possible for several
interrupts to be connected to the same completion routine in a job but it is
illegal for more than one job to try to connect to the same interrupt. When an
interrupt completion routine is entered, RO contains the address of the
interrupt vector that caused the completion routine to be executed.

-196-

Real-Time Programs
Real-time completion routines, whether direc tly connec ted to an interrupt or
scheduled with the EMT for that purpose, have an associated job priority.
These are software priorities, not hardware priorities; all completion routines
are synchronized with the job and execute at hardware priority level O.
Completion routine priorities 1 and larger are classified as "real-time"
priorities and are added to the system parameter PRIHI to yield the job
execution priority, unless the resultant priority would exceed 127 in which
case the priority will be 127.
These completion routines will then be
scheduled for execution whenever there are no executable jobs with a higher
priority.
A real-time completion routine for one job will be suspended if an interrupt
occurs which causes a higher priority completion routine to be queued for
another job. However, a real-time completion routine for one job will never be
interrupted by a completion routine for that same job regardless of the
subsequent completion routine's priority. If additional requests are made to
trigger the same or different completion routines while a completion routine is
executing, the requests are queued for the job and are serviced in order based
on their priority and the order in which they were queued.
A real-time completion routine is allowed to run continuously until one of the
following events occurs:
1) the completion routine finishes execution and
returns; 2) a higher-priority completion routine from another job interrupts
its execution -- it is re-entered when the higher-priority routine exits; or 3)
the completion routine enters a system wai t state such as waiting for an I/O
operation to complete or waiting for a timed interval.
If a real-time
completion routine enters a wait state, it returns to the same real-time
priority when the wait condition completes.
Real-time completion routines with a priority of 0 are treated slightly
differently than those with priorities greater than zero.
The action taken
depends on the priority of the main-line job when the completion routine is
scheduled.
If the base priority is equal to or greater than PRIHI, then the
completion routine is treated just as those with real-time priorities greater
than zero.
That is, the completion routine is assigned a priori ty of PRIHI
(PRIHI + the real-time priority of 0).
On the other hand, if the base job
priority is less than PRIHI, then the job is scheduled as a very high priority
normal (non-interactive) job~ The effect of this is that completion routines
with a real-time priority of 0 and a base job priority less than PRIHI will
interrupt normal time-sharing jobs, but are time-sliced in the normal fashion
and lose their high priority if they execute longer than the system parameter
QUAN1A.
Jobs that have real-time, interrupt completion routines need not necessarily be
locked in memory.
If an interrupt occurs while the job is swapped out of
memory, it is scheduled for execution like any other job and swapped in before
the completion routine is executed. Note, however, that this condition is not
optimal for timely servicing of interrupts.

-197-

Real-Time Programs
When a real-time interrupt occurs, a request is placed in a queue to execute
the appropriate completion routine. If the interrupt occurs again before the
completion routine is entered, another request is placed in the queue so the
completion routine will be invoked twice. A TSX-Plus fatal system error occurs
if an interrupt occurs and there are no free completion routine request queue
entries.
When a real-time completion routine completes its execution, it must exit by
use of a RETURN instruction (RTS PC), not ~ RTI.
The form of the EMT used to connect an interrupt to a real-time completion
routine is:

EMT

375

with RO pointing to the following argument area:

11,140
interrupt-vector
completion-routine
priority

• BYTE
• WORD
• WORD
•WORD

where "interrupt-vector" is the address of the interrupt vector, "completionroutine" is the address of the completion routine, and "priority" is the
execution priority for the completion routine.
Er:rol:':

Code

o
1

Meaning
Real-time support not included or job not privileged
Maximum number of vectors already in use
Some other job is already connected to that vector

Example:
.TITLE
.ENABL

ATTVEC
LC

Demonstrate TSX-Plus EMTs to attach a completion routine to an interrupt
CTRLC = 3
ERRBYT = 52
RCSR
176540
= RCSR+2
RBUF

START:

;Control-C
;Serial line RCSR address
;Line input buffer address

• MCALL

.PRINT,.EXIT,.TTYOUT,.SPND,.RSUM

MOV

EMT

#MAPIOP,RO
375

BCC

;Point to EMT arg block to
;Map to I/O page
;Branch if OK to map

-198-

Real-Time Programs
.PRINT
.EXIT

IINOPRIV

jYou aren't allowed to do that

;+
;If this job were to be resident for a long time, it would be better
;to lock into low memory to avoid memory fragmentation by job swapping.
; However , since this job may have to be swapped now to get into low
; memory , locking into low memory takes longer to execute.
;

; 1$:

MOV

IILOKLOW,RO

;Point to EMT arg block to lock into low mem.

MOV
EMT

IILOKJOB ,RO
375

;Point to EMT arg block to
;Lock the job in memory

MOV
EMT
BCC
• PRINT
MOVB
ASL
• PRINT
BR

IIATTVEC ,RO
375
2$
IIBADATT
@IIERRBYT , RO
RO
ATTERR(RO)
3$

;Point to EMT arg block to
jAttach to an interrupt vector
;Continue if OK
;Notify can't attach to interrupt
;Find out which error
; Convert to word offset
;And explain reason for error
;Go on to unlock and exit

• PRINT
.SPND

I!TYPE

;Prompt for input from interrupting device
;Now wait for an interrupt

1$:

2$:

,. .

MOV
EMT

IIREL VEC ,RO

375

;Resume here on exit from completion
; Point to EMT arg block to
;Release an interrupt vector

__ ..3_
~uut::

;+
; NOTE: Any interrupts through this vector after it has been released
will cause a TSX-Plus fatal system error - Unexpected Interrupt.
;3$ :

MOV

tlUNLOKJ ,RO

EMT

375

;Point to EMT arg block to
;Unlock this job from memory

.EXIT

;+
; The following code will be executed as a completion routine
; when the device attached to the vector interrupts.
;-

@IIRBUF ,RO
CMPRTN: MOVB
RO,IICTRLC
CMPB
BEQ
1$
.TTYOUT
HSETPRI,RO
MOV
375
EMT

CLR

PRILEV

;Enter here when new character is available
;Get the new character
;Should we quit?
;Quit on ... c
;Display the character
jPoint to ~IT arg block to
;Set processor priority (block interrupts)
;Time critical processing goes here
jSet priority back down
=199=

Real-Time Programs

1$:
2$:
MAPIOP:
LOKLOW:
LOKJOB:
UNLOKJ:
ATTVEC:

RELVEC:
SETPRI:
PRILEV:
ATTERR:

TYPE:
BADATT:
NOPRIV:
NAXINT:
INUSE:

MOV
EMT
BR
.RSUM
RETURN

IISETPRI,RO
375
2$

.BYTE
.BYTE
.BYTE
.BYTE
.BYTE
• WORD
•WORD
. WORD
.BYTE
• WORD
.BYTE
.WORD
.WORD
• WORD
•WORD
.NLIST
.ASCIZ
.ASCIZ
.ASCII
.ASCIZ
.ASCIZ
.ASCIZ
.END

5,140
7,140
13,140
10,140
11,140
340
CMPRTN

;Point to EMT arg block to
;Set processor priority (reenable interrupts)
;Return to main-line code
;Wait for next interrupt (NOTE: Not RTI)

12,140
340
16,140
7

;EMT arg block to map to I/O page
;EMT arg block to lock job into low mem.
;EMT arg block to lock job in place
;EMT arg block to unlock job from memory
;EMT arg block to attach to interrupt
;Interrupt vector
;Address of completion routine
;Real-time priority (NOT processor priority!)
;EMT arg block to release interrupt vector
;Interrupt vector
;EMT arg block to set processor priority
;Desired priority level (modifiable)
;Attach to interrupt error table

NOPRIV
MAXINT
INUSE
BEX
/Characters entered on serial line will be displayed here:/
/?ATTVEC-F-Cannot attach to interrupt./<7>
/Real-time support not specified during TSGEN or /
/user not privileged./
/Maximum number of interrupts already in use./
/Another job already connected to interrupt./
START

11.12 Releasing ~ interrupt connection
A connection between an interrupt vector and an interrupt service routine or an
interrupt completion routine remains in effect until the job exits or the
following EMT is executed to release the connection.
Warning: An interrupt through a vector which has been released with this EMT or
which was connected to a job that has terminated will cause a fatal system
error: DEI-Interrupt occurred at unexpected location.
The form of the EMT is:
EMT

375

with RO pointing to the following argument area:
• BYTE
• WORD

12,140
interrupt-vector
-200-

Real-Time Programs
where "interrupt-vector" is the address of the interrupt vector whose connection is to be released.
An error will cause the carry-flag to be set on
return, indicating that either real-time support was not included in the
TSX-Plus generation or the job does not have operator privilege.
Example:
See the example program ATTVEC in
interrupt to a completion routine.

the

section on connecting

real-time

11.13 Scheduling ~ completion routine
Real-time programs may schedule a completion routine for execution with a
special EMT provided for that purpose.
This is particularly valuable from
within interrupt service routines which do not have access to system service
calls other than this EMT and the .RSUM request.
While any program with
real-time (operator) privilege may issue this request, its primary intent was
to provide a mechanism for access to system service calls from interrupt
service routines. The form of this EMT is:

EMT

375

with RO pointing to the following argument block:
• BYTE
• WORD

•WORD
• WORD
• WORD

21,140
completion-routine
priority
R1-value

where "completion-routine" is the address of the entry point of the completion
routine that is being started, "priority" is the real-time priori ty level for
the completion routine being started, and "R1-value" is a value to be placed in
R1 on entry to the completion routine.
Completion routines scheduled in this manner follow the same rules as for
interrupt completion routines described above, except that they are scheduled
as a result of the EMT call rather than in response to an interrupt.
Example:
See the example program INTSVC in the section on connecting interrupts to
real-time jobs/ interrupt service routines.

-201-

Real-Time Programs
11.14 Adapting real-time programs ~ TSX-Plus
The following points should be kept in mind when converting an RT-ll real-time
program for use under TSX-Plus.
1.

The I/O page (160000-177777) is not directly accessible to the program
unless the program executes the TSX-Plus real-time EMT that maps the job's
virtual region to the I/O page.

If the program's virtual region 160000 to 177777 is mapped to the I/O
page, the program must use .GVAL to access offsets in the simulated RMON.

Real-time interrupts are connected to interrupt service routines and
interrupt completion routines by use of the TSX-Plus real-time EMT for
that purpose. The program should not try to connect interrupts by storing
into the interrupt vector cells.

The. PROTECT EMT is a no-op under TSX-Plus and always returns wi th the
carry-flag cleared.

Interrupt service routines and completion routines connected to real-time
interrupts should exit by use of a RTS PC instruction rather than RTI.

Programs that require very rapid response to interrupts should use the
interrupt service routine method and must lock themselves in memory.

7•

Real~time inter-ruptsmust no-tGc-eur unl-e-s-s an--inter-rup-t -se-rv-i-ce routine- or
completion routine is connected to the interrupt.
If a real-time
interrupt occurs with no associated interrupt service or, completion
routine, a fatal TSX-Plus system error (UEI) occurs and the "argument
value" displays the address of the vector of the interrupt.

A higher priority real-time completion routine for one job will interrupt
a lower priority completion routine being executed by another job but will
not interrupt a lower priority completion routine being executed by the
same job.

A real-time completion routine running at priority 1 or above is not
time-sliced and will lock out all lower priority jobs until it completes
its processing or enters a wait state.

-202-

12. SHARED RUN-TIME SYSTEM SUPPORT
TSX-Plus provides a facility that allows one or more shared run-time systems or
data areas to be mapped into the address space of multiple TSX-Plus timesharing jobs. There are two primary uses of this facility:
1.

Memory space can be saved by having multiple jobs that use the same
run-time system access a common copy rather than having to allocate
space within each job for a copy.

Programs can communicate with each other through the use of a common
shared memory region to which all of the communicating jobs have
direct access.

To use this facility, information about all of the shared run-time systems must
be declared when the TSX-Plus system is generated.

During system initializ-

ation the shared run-time system files are opened and read into memory. These
shared run-time systems remain in memory as long as the system is running and
are never swapped out of memory even if there are no jobs actively using them.
The EMTs described below can be used to associate one or more shared run-time
systems with a job.
virtual memory space is mapped to allow access to part or all of one or more
run-time systems.
12.1 Associating ~ run-time system with ~ job
The following EMT is used to associate a shared run-time system with a job.
The form of the emt is:
EMT

375

with RO pointing to the following argument area:
• BYTE

• WORD

0,143
name-pointer

where "name-pointer" is the address of a two-word cell containing the six
character name of the shared run-time system in RAD50 form.
This name
corresponds to the file name which was specified for the run-time system when
TSX-Plus was generated. If the name pointer value is zero, the effect of the
EMT is to disassociate all shared run-time systems from the job and to
re-establish normal memory mapping for the job.
If the run-time system whose name is specified with this EMT is not recognized,
the carry-flag is set on return with an error code of 1.
The effect of this EMT is to associate a particular shared run-time system with
the job. However, this EMT does not affect the memory mapping for the job or
make the run-time system visible to the job; that is done by the EMT described
below. If some other run-time system has been previously mapped into the job's
region, that mapping is unaffected by this EMT. Thus it is possible to have
multiple run-time systems mapped into the job's region by associating and
-203-

Shared Run-times
mapping them one at a time into different regions of the job's virtual memory
space.
Example:
.TITLE USERTS
.ENABL LC
Demonstration of TSX-Plus EMT to map to a shared run-time region
•MCALL .PRINT,.EXIT
PARI
= 20000
;Base address of PAR 1 window
IIUSERTS,RO
;Point to EMT arg block to
START: MOV
375
EMT
;Associate a shared run-time region
BCC
;Error?
1$
• PRINT IINOSHRT
;Can't find named shared run-time
.EXIT
MOV
IIMAPRTS ,RO
1$:
;Point to EMT arg block to
375
EMT
;Map to shared run-time system
@11<PARl+200)
2$:
CALL
;JSR to entry point in shared region
;which prints some data from there.
CLR
SHRNAM
;Undeclare any shared run-times
<SHRNAM+2)
CLR
MOV
IIUSERTS,RO
;Point to EMT arg block to
375
;Dissociate all shared regions
EMT
,
;Go on with other processing
.EXIT
USERTS: .BYTE
0,143
;EMT arg block to associate
;Pointer to file name
•WORD
SHRNAM
SHRNAM: • RAD50 IRTCOM 1
;Shared region file name
1,143
MAPRTS: • BYTE
;EMT arg block to map shared region
•WORD
1
;Map PAR 1
o
jOffset into region
• WORD
•WORD
1000/64.
;Size of region (64. byte blocks)
.NLIST BEX
NOSHRT: .ASCIZ ICan't find the shared run-time system.I<7)
.END
START

The example program RTCOM declared in the above program was defined during
TSX-Plus system generation with the RTDEF macro as follows:
RTDEF <SY RTCOM SAV),RW,1
and the shared program itself was:
.TITLE RTCOM
.ENABL LC
Demonstration shared run-time file
(Position Independent Code.)
• MCALL • PRINT
.NLIST BEX
.PSECT RTCOM,I
;RTDEF in TSGEN specifies
-204-

Shared Run-times
;skip 1 block so default start address of 1000 is OK
.ASCII /This data was produced by the /
.ASCIZ /RTCOM shared run-time region./
START + 200
;Entry point for shared code
PC,RO
;Find out where we are
ENTRY:: MOV
#(.-START),RO
;Point back to data area
SUB
.PRINT RO
;Display what is there
RETURN
;And go back .to MAIN
.END
ENTRY
START:

12.2 Mapping a run-time system into ~ job's region
Once a shared run-time system has been associated with a job by use of the
previous EMT, the run-time system (or a portion thereof) can be made visible to
the job by mapping it into the job's virtual address region. The form of the
EMT to do this is:
EMT

375

with RO pointing to the following argument area:
• BYTE
• WORD
• WORD
•WORD

1,143
par-region
run-time-offset
mapped-size

The "par-region" parameter is a number in the range 0 to 7 that indicates the
Page Address Register (PAR) that is to be used to access the run-time system.
The PAR number selects the region of virtual memory in the job that will be
mapped to the run-time system. The following correspondence exists between PAR
numbers and virtual address regions within the job:
PAR

Address Range

--------------0
1

2
3
4
5
6
7

000000 020000 040000 060000 100000 120000 140000 160000 -

017777
037777
057777
077777
117777
137777
157777
177777

The "run-time-offset" parameter specifies which portion of the run-time system
is to be mapped into the PAR region.
The "run-time-offset" specifies the
number of the 64-byte block within the run-time system where the mapping is to
begin.
This makes it possible to access different sections of a run-time
system at different times or through different regions.

-205-

Shared Run-times
The "mapped-size" parameter specifies the number of 64-byte blocks to be
mapped.
If this value is larger than can be contained within a single PAR
region, multiple PAR regions are automatically mapped as necessary to contain
the entire specified section of the run-time.
If an error is detected during execution of the EMT, the carry-flag is set on
return with an error code of I to indicate that there is no run-time system
associated with the job.
This EMT only affects the mapping of the PAR region specified in the argument
block (and following PAR's if the size so requires). It does not affect the
mapping of any other PAR regions that may previously have been mapped to a
run-time system. Thus a job may have different PAR regions mapped to different
sections of the same run-time system or to different run-times.
Real-time
programs may map PAR 7 to the I/O page and also map other PAR regions to shared
run-time systems.
The memory size of a job is not affected by the use of the shared run-time
control EMTs. That is, mapping a portion of a job's virtual address space to a
shared run-time system neither increases nor decreases the size of memory
occupied by the job.
If a job's size is such that a portion of its normal
memory is under a PAR region that is mapped to a run-time system, that section
of its normal memory becomes inaccessible to the job as long as the run-time
system mapping is in effect, but the memory contents are not lost and may be
re-accessed by disassociating all run-time systems from the job.
Note that any of the PAR regions may be mapped to a run-time system including
PAR 7 (160000-177777).
Example:
See the example program USERTS in the section on associating a run-time system
with a job.

-206-

13. TSX-Plus PERFORY~NCE MONITOR FEATURE
TSX-Plus includes a performance analysis facility that can be used to monitor
the execution of a program and determine what percentage of the run time is
spent at various locations wi thin the program. During performance analysis,
TSX-Plus examines the program being monitored when each clock tick occurs (50
or 60 times per second) and notes at what location in the program execution is
taking place.
Once the analysis is completed the TSX-Plus performance
reporting program (TSXPM) can be used to produce a histogram showing the
percentage of time spent at various locations during the monitored run.
There are
program:
1.
2~

three steps

involved

in performing a

performance analysis on a

Use the MONITOR command to begin the analysis.
Run the program to be monitored.
Run the TSXPM program to print a histogram of the result.

13.1 Starting ~ performance analysis
The first step in doing a performance analysis is to use the MONITOR kevboard
command to tell TSX-Plus that a performance analysis is to be done on the
program that will be run next. The form of the MONITOR command is:
MONITOR base-address,top-address[,cell-size]/switches
where "base-address" is the lowest address in the region to be monitored,
"top-addres s" is the highes t address in the region to be moni tored, and
"cell-size" is an optional parameter that specifies the number of bytes of
address in the region being monitored to be grouped together into each
histogram cell.
If the "cell-size" parameter is not specified, TSX-Plus
calculates the cell size by dividing the number of bytes in the region being
monitored (base-address to top-address) by the total number of histogram cells
available (specified when TSX-Plus is generated).
This gives the finest
resolution possible. The only available switch is "/1" which causes I/O wait
time to be included in the analysis. If this switch is not specified, only CPU
execution time is included in the analysis. A link map of the program should
be available to determine the addresses in the program that are appropriate to
monitor.
Exa,mples:
.MONITOR 1000,13000/1
.MONITOR 20000,40000,10
.MONITOR 2000,6000
The effect of the MONITOR command is to set up parameters within TSX-Plus which
will be used to monitor the next program run. It does not actually begin the
analysis, so there is no rush in running the program to be monitored. Once the
MONITOR command has been issued) the program to be moni tored is run by using
-207-

Performance Honitoring
the standard "RUN" or "R" commands. If a program being monitored does a .CHAIN
to another program, the analysis continues and the times reported will be the
composite of the programs run.
Only one user may be doing a performance analysis at a time. This is because
the performance analysis histogram buffer is a common memory area that may not
be in use by more than one user at a time. An analysis is in effect for a user
between the time the MONITOR command is issued and the TSXPM program is run to
display the results of the analysis. Running the TSXPM program terminates the
performance analysis and allows other users to perform analyses.
Note that
space for the performance analysis data buffer must be reserved when TSX-Plus
is generated.
If the program to be monitored is overlayed and the region to be monitored is
in the overlay area, the analysis technique is more complex. In this situa tion, the EMTs described below must be used to control the performance
analysis as overlay segments are run in the segment being monitored.
13.2 Displaying the results of the analysis
After the program being monitored has exited and returned control to the
keyboard monitor, the TSXPM performance reporting program is used to generate a
histogram of the time spent in the region being monitored. The TSXPM program
is started by typing "R TSXPM"; it responds by printing an asterisk ("*"). In
response to the asterisk, enter the file specification for the device/file
where the histogram is to be written. An optional switch of the form "/M:nnn"
may be specified following the file specification.
This swi tch is used to
specify the minimum percentage of the total run-time that a histogram cell must
contain in order to be included in the dis play.
If this swi tch is not
specified, the default cut-off percentage is 1%.
After receiving the file specification, TSXPM prompts for a title line. Enter
a line of text which will be printed as a page title in the histogram file.
Press RETURN if you wish no title.
The next item of information requested by TSXPM is a set of base offset values.
The base offset values are optional. Base offsets are useful in the situation
where you have several modules making up a program being monitored and you want
the addresses displayed on the performance analysis histogram to be relative to
the base of each module. You may specify up to 10 offset values. Each offset
value is specified as an offset module number (in the range 0 to 9) followed by
If offset
a comma and the base address of the module (see example below).
values are specified, TSXPM determines in which module each cell of the
histogram falls and displays the address as a module number and offset within
the module. After you enter all desired module offsets, enter RETURN without a
value.
After the base offset values are entered, the histogram will be produced and
written to the specified device and file. After the histogram is generated,
TSXPM prints the asterisk prompt again, at which point you may enter the name

-208-

Performance Monitoring
of another device/file and produce the histogram
control-C to return to the keyboard monitor.

again

you

may

type

Example use of TSXPM:
.R TSXPM
*LP:/M: 5
Title':PERFORMANCE ANALYSIS OF EIGENVALUE CALCULATION
Base offsets:
)1,1000
)2,2134
)3,5212

(Histogram is produced at this point)
*(CTRL-C)
The histogram produced by TSXPM consists of one line per histogram cell. Each
line contains the following information: 1) the base module offset number (if
ottsets were specified);

2) the address range coverea oy the n1stogram celL

(relative to the module base if base offsets were used); 3) the percentage of
the total execution time spent at the address range covered by the histogram
cell; 4) a line of stars presenting a graphic representation of the histogram.
13.3 Performance monitor control EMT's
For most applications the method described above can be uSed to do a performance analysis. However, in special cases (such as analyzing the performance of
an overlayed program) it is necessary to have more explicit control over the
performance analysis feature as a program is running.
The following set of
EMTs may be used to control a performance analysis.
13.3.1 Initializing ~ performance analysis.
This EMT is used to set up parameters that will control a performance analysis.
It does not actually begin the analysis. The form of the EMT is:
EMT

375

with RO pointing to the following argument block:
.BYTF

• WORD
• WORD
• WORD
• WORD

0,136
base-address
top-address
cell-size
flags

where "base-address" is the address of the base of the region to be =onitored)
"top-address" is the address of the top of the region to be monitored, and
"cell-size" is the number of bytes to group in each histogram cell.
If 0
(zero) is specified ~s the cell size, TSX-Plus calculates the cell size to use
by dividing the number of bytes in the region being monitored (top-address
-209-

Performance Monitoring
minus base-address) by the number of cells available in the histogram data area
(specified when TSX-Plus is generated).
The "flags" parameter is used to
control whether or not I/O wait time is to be included in the analysis. If a
value of 1 is specified as the "flags" parameter, I/O wait time is included in
the analysis; if a value of a (zero) is specified, I/O wait time is not
included in the analysis.
Errors:
Code

Meaning

Performance analysis being done by some other user.
Performance analysis feature not included in TSX-Plus generation.

1
Example:

.TITLE DEMOPA
.ENABL LC
Demonstrate use of TSX-Plus EMT's to initialize, start, stop, and
terminate a performance analysis
• MCALL
.GLOBL

.EXIT,.PRINT,.LOOKUP,.READW,.CLOSE,.TTYOUT
PRTOCT
jDisplay an octal word in RO
jEMT error byte
jASCII 'space'
;ASCII 'asterisk'

ERRBYT
SPACE
STAR

52
40
52

START:

MOV
EMT
BCC
MOVB
ASL
• PRINT
• EXIT

IIINITPA,RO
375
5$
@IIERRBYT,RO
RO
INIERR(RO)

;Point to EMT arg block to
jlnitialize the performance analysis
;No error
;Which erro~?
;Convert to word offset
jPrint the error message
jAnd depart this world of woe •

5$:

MOV
EMT
BCC
• PRINT
• EXIT

IISTRTPA,RO
375
10$
IISTRERR

;Point to EMT arg block to
jStart the performance analysis
;No error
jStart error
;and depart •

10$:
; Dummy section of code to do some I/O and computation for analysis
BEGIN: .LOOKUP IIAREA,IIO,IIFILNAM
MOV
1110,R1
; Disk I/O
1$:
.READW IIAREA,#0,IIBUFFER,1I256.,1I0
SOB
R1,1$
• CLOSE #0
-210-

Perform.ance Monitoring
Terminal I/O
• PRINT IIBUFFER
Compute bound
11123456,R3
MOV
1112345,RO
2$:
MOV
Rl
CLR
DIV
11345,RO
SOB
R3,2$
ENDB:
NCELLS = «ENDB-BEGIN)/2)
#STOBLK,RO
375
15$
lIs TOERR

;Point to EMT arg block to
;Stop the performance analysis
;Check for error return
;Only one error - PA not initialized
;and leave •

MOV

IIHALBLK, RO

EMT

J/J

BCC
MOVB
ASL
• PRINT
• EXIT
TST

20$
@IIERRBYT , RO
RO
HLTERR(RO)

BPL

?r;c::
...
.,y

• PRINT

II 0 VRWRN
III ,HALFLG
30$
IIIOWNOT

;Put HALTPA block address in RO
;Terminate the performance analysis
;Check for errors
jGet error type
;Convert to word offset
;Print out proper error message
;And depart •
;Check HALTPA return flag
;No cell overflow?
;Issue overflow warning
;1/0 time included?
;Skip message if not
;Print I/O wait time included msg

MOV
EMT
BCC
• PRINT
• EXIT
15$ :

20$:

25$:

;Number of cells in histogram

BIT
BEQ
• PRINT

')"'7~

HALFLG

; Print a histogram of the performance analysis
CLR
R3
;Set histogram cell counter
CMP
HSTTBL(R3),#64.
;Normalize the table for 64. longest
35$:
BHI
40$
;Too many counts?
ADD
#2,R3
;Point to next cell
CMP
R3,#<2*NCELLS>
;End of table?
;No, repeat
BLE
35$
;All cells less than 64. counts now
BR
50$
;Re-init. histogram cell counter
CLR
R3
40$:
;Divide each cell count by 2
CLC
45$:
ROR
HSTTBL(R3)
;Point to next cell
112 ,R3
ADD
jEnd of table?
R3,#<2*NCELLS>
CMP
jNo, repeat
BLE
45$
;Go check all cells again
BR
30$
• PRINT IIHSTMSG
;Caption histogram
50$:
;Set first analyzed address
#BEGIN,R2
MOV
jInit. cell counter
R3
CLR
;Get ready to print it out
MOV
R2,RO
55$:

30$:

-211-

Performance Monitoring

60$:
65$:

CALL
PRTOCT
.TTYOUT tis PACE
MOV
HSTTBL(R3),Rl
65$
BEQ
.TTYOUT tlSTAR
SOB
Rl,60$
• PRINT tlCRLF
CMP
(R2 )+, (R3 )+
CMP
R3, 11<2 *NCELLS>
BLE
55$
• EXIT

INITPA: • BYTE
•WORD
• WORD
•WORD
•WORD
STRTPA: .BYTE
STOBLK: • BYTE
HALBLK: .BYTE
• WORD
•WORD
• WORD
PRMBUF: .BLKW
HALFLG: • WORD
HSTTBL: .BLKW
HSTEND:
AREA:
.BLKW
BUFFER: .BLKW
• WORD
FILNAM: .RAD50
INIERR: .WORD
• WORD
HLTERR: .WORD
• WORD
.NLIST
INPRG: .ASCIZ
NOGEN: .ASCIZ
NOPA:
.ASCIZ
TOSMAL: .ASCIZ
STRERR: .ASCIZ
STOERR: .ASCIZ
OVRWRN: .ASCIZ
IOWNOT: .ASCIZ
OKDONE: .ASCIZ
HSTMSG: .ASCIZ
CRLF:
.ASCIZ
.END

0,136
BEGIN
ENDB-2
2
1

1,136
2,136
3,136
PRMBUF
HSTTBL
<HSTEND-HSTTBL>
3

o
<2*NCELLS>+2
10
256.

;Display analyzed address
;For formatting
;Get address use counter
;No stars on 0 count
;Print a '*' for each count
;Go to next line
;Point to next address and count
;End of histogram?
;No, display next cell
;Else done •
;EMT arg block for perform. analysis
;Start analysis address
;End analysis address
jCount 1 address in each cell
;Include 10 wait time.
;Start Performance Analysis EMT block
jEMT arg block to stop perf. analysis
jEMT arg block to release analysis
;PA parameter buffer address
;Histogram Table buffer address
;Histogram Table buffer length
;PA four word parameter buffer
j PA return flags
;Histogram table
;EMT arg block area
;Data input buffer
;Make sure buffer is ASCIZ
;Read this file
jInitialize PA error table

/DK DEMOPAMAC/
I NPRG
NOGEN
NOPA
;HALTPA Error message table
TOSMAL
SEX
/?INITPA-F-Performance analysis being done by another user./
/?INITPA-F-Performance analysis feature not genned./
/?HALTPA-F-This job is not doing a performance analysis./
/?HALTPA-F-Area provided for histogram table too small./
/?INITPA-F-Performance analysis not initialized yet./
/?STOPPA-F-Performance Analysis has not been initialized./
/?HALTPA-W-Some histogram cell(s) overflowed during analysis./
I HALTPA-I-I/O wait time included in performance analysis. I
/ STOPPA-S-Performance Analysis stopped./
/Address
Frequency/
<15><12><200>
START

-212-

Performance Monitoring
13.3.2 Starting ~ performance analysis.
This EMT is used to begin the actual collection of performance analysis data.
The previous EMT must have been executed to set up parameters about the
performance analysis before this EMT is called. The form of the EMT is:
EMT

375

with RO pointing to the following argument block:
• BYTE

1,136

The carry-flag will be set on return from this EMT if performance analysis has
not been initialized yet.
Example:
See the example program DEMOPA in the section on initializing a performance
analysis.
13.3.3 Stopping ~ performance analysis.
The following EMT can be used to suspend the data collection for a performance
analysis. The data collection can be restarted by using the start-analysis EMT
described above. This EMT could, for example, be used to suspend the analysis
when an overlay module is loaded that is not to be monitored.
The startanalysis EMT would then be used to re-enable the data collection when the
overlay of interest is re-loaded. The form of this EMT is:
EMT

375

with RO pointing to the following argument block:
• BYTE

2,136

The carry flag will be set on return from this EMT if performance analysis has
not been initialized yet.
Example:
See the example program DEMOPA in the section on initializing a performance
analysis.
13.3.4 Terminating ~ performance analysis.
This EMT is used to conclude a performance analysis.
It has the effect of
returning into a user supplied buffer the results of the analysis and releasing
the performance analysis feature for other users. The form of this EMT is:

-213-

Performance Monitoring

EMT

375

with RO pointing to the following argument block:
• BYTE
• WORD
•WORD
.WORD

3,136
parameter-buffer
histogram-buffer
buffer-size

where "parameter-buffer" is the address of a 4 word buffer into which will be
stored some parameter values describing the analysis that was being performed,
"histogram-buffer" is the address of the buffer that will receive the histogram
count values, and "buffer-size" is the size (in bytes) of the histogram buffer
area.
The values returned in the parameter buffer consist of the following 4 words:
1) base address of the monitored region; 2) top address of the monitored
region; 3) number of bytes per histogram cell; 4) control and status flags.
The control and status flags are a set of bits that provide the following
information:
Flag

Meaning
1

100000

I/O wait time was included in the analysis.
Some histogram cell overflowed during the analysis.

The data returned in the histogram buffer consists of a vector of 16-bit binary
values, one value for each cell in the histogram. The first value corresponds
to the histogram cell that starts with the base address of the region that was
being monitored.
Errors:
Code

o
1

Meaning
This job is not doing a performance analysis.
Area provided for histogram count vector is too small.

Example:
See the example program DEMOPA in the section on initializing a performance
analysis.

-214-

14. TSX-Plus RESTRICTIONS

14.1 System service call (EMT) differences between RT-11 and TSX-Plus
The following list describes the differences in the way TSX-Plus implements
some RT-11 system service calls (EMTs). If an EMT is not listed, it provides
the same functions as described in the RT-11 Programmer's Reference Manual •
• ABTIO

Action depends on setting of IOABT system parameter. If IOABT is set
to 1 then .ABTIO operates the same as RT-11 and calls handler abort
entry points. If IOABT is set to 0 then .ABTIO does not call handler
entry points, but instead does a .WAIT on all channels. The default
method of handling I/O abort requests is chosen during TSX-Plus
system generation with the IOABT parameter. The I/O abort handling
method may also be changed while TSX-Plus is running with the SET 10

[NO]ABORT keyboard command •
• CDFN

User jobs may not define more than 16 channels. If a .CDFN EMT is
done, all channels are purged if a .CHAIN is done.
If .CDFN is not
done, channels are not purged across a chain •

• CHCOPY

Not implemented •

• CNTXSW

Not implemented •

• DEVICE

Operator privilege is required to use this EMT.

.FETCH

Returns in RO the address specified for the handler load area. All
TSX-Plus device handlers are resident, hence the ~FETCH EMT performs
no operation. If the device handler specified was not loaded during
TSX-Plus initialization, then an error code of 0 is returned.

• FORK

May be used in device handlers but not in user jobs •

.GTJB

The job number returned in word 1 of the result area is two times the
TSX-Plus line number~
That is) the first line specified in the
system generation will be number 2, the second 4, etc. Words 8
through 12 of the result area are not altered by this EMT •

• HRESET

Action depends on setting of IOABT system generation parameter. If
lOABT is set to 1 then .HRESET calls handler abort entry points. If
IOABT is set to 0 then .HRESET does not call handler entry points but
instead does a •WAIT on all channels.
Messages queued on named
message channels are not canceled. Otherwise, this EMT operates the
same as under RT-11 •

• INTEN

May be used in device handlers but not in user jobs •

• LOCK

The TSX-Plus file management module

(USR)

is always "resident" and

the .LOCK EMT is ignored •
• MTxxxx

Multi-terminal control EMT's (.MTIN,
supported.

-215-

• MTOUT ,

.MTPRNT, etc.) are not

Restrictions
.MTPS

The processor priority level may not be changed from user mode, hence
this macro performs no operation.
TSX-Plus provides a special
real-time EMT to set the processor priority.

• MWAIT

Not supported •
communication.

• PEEK

Non-privileged jobs may use .PEEK to access cells within the
simulated RMON (addresses 160000 to 160626) although the .GVAL EMT is
a recommended alternative.
Jobs with operator privilege may use
• PEEK to access the I/O page or low memory cells in kernel space.
References to addresses in the virtual address range of the simulated
RMON (160000 to 160626) are always directed to RMON rather than the
I/O page.

• POKE

Non-privileged jobs may use .POKE to access cells within the
simulated RMON (addresses 160000 to 160626) although the .PVAL EMT is
a recommended alternative.
Jobs with operator privilege may use
.POKE to access the I/O page or low memory cells in kernel space.
References to addresses in the virtual address range of the simulated
RMON (160000 to 160626) are always directed to RMON rather than the
I/O page •

See the chapter that describes

inter-job message

• PROTECT Not supported.
See the chapter on real-time programming
information about how to connect an interrupt to a TSX-Plus job.

for

.QSET

TSX-Plus uses an internal pool of I/O queue elements for all jobs
hence it is not necessary to define additional I/O queue elements in
order to perform overlapped I/O. The .QSET EMT is ignored.

• RCVD

Not supported •
communication •

• RELEAS

This EMT is ignored.

• SETTOP

Returns the job limit in RO but does not actually expand or contract
the allocated job region. The job region allocation can be changed
by use of the MEMORY keyboard command or the TSX-Plus specific EMT
for this purpose •

• SDAT

Not supported.
communication.

.SFPA

This EMT functions the same as RT-11.
going to use the floating-point unit.

• SDTTM

Operator privilege is required to use this EMT •

.SRESET

Messages queued on named message channels are
Otherwise, this EMT operates the same as under RT-11.

See the chapter that describes

See

inter-job message

Refer to .FETCH •

the

chapter

-216-

that describes

inter-job message

It must be used if a job is

not

canceled.

Restrictions
• SYNCH

May be used in handlers but not in user jobs.
When used in a
handler the number of the TSX-Plus job that is being synchronized
with must be stored in word 2 of the SYNCH block •
j

• TLOCK

This EMT is ignored •

• TTlNR

Only honors bit 6 in the Job Status Word (TCBlT$) if a SET TT NOWAlT
command

has

been issued,

or the running program has send the

"u"

program controlled terminal option to the system, or the program was
R[UN] with the /SlNGLECHAR switch •
• UNLOCK

This EMT is ignored •

• UNPROT

Not supported.
See the chapter on real-time programming
information about how to connect an interrupt to a TSX-Plus job.

for

A full list of RT-11 compatible and TSX-Plus specific EMTs is included in
Appendix D. The list indicates the level of support TSX-Plus provides for each
RT-ll compatible EMT.
14.2 Programs Not Supported by TSX-Plus
Mos t programs which run under RT-11 will run under TSX-P Ius wi thout change.
However, a modified version of ODT ("TSODT"--supplied with TSX-Plus) must be
used to debug programs under TSX-Plus.
The FORMAT program may not be used under TSX-Plus.
The BATCH RT-11 facility is not supported by TSX-Plus.
The logical subset disk feature is provided internally
therefore does not use the LD pseudo-device handler.

TSX-Plus

and

The single line editor feature is provided as an optional system overlay region
with TSX-Plus and does not use the SL pseudo-device handler.
The VM handler supplied with TSX-Plus was written specially for use with
TSX-Plus and is not the same as the DEC VM handler.
The QUEUE package (QUEUE and QUEMAN) is not supported by TSX-Plus.
The RESORC utility is not supported.

-217-

-218-

Appendix ~== SETSIZ PROGRAM
The SETSIZ program can be used to store into a SAV file information about how
much memory space should be allocated for the program when it is executed.
SETSIZ can also be used to set the "virtual job" flag in the job status word
(JSW) for a programe
There are three ways
controlled:

that

the amount of memory allocated to a job can be

1. The TSX-Plus EMT with function code 141 (described in Chapter 7) may be
used by a running program to dynamically set the job's size.
2. If a size is specified in a SAV file (by use of the SETSIZ program) the
specified amount of memory is allocated for the program when it is
started.
3. If no size is specified in the SAV file, the size specified by the last
MEMORY keyboard command is used.
Note that the .SETTOP EMT does not alter the amount of memory space allocated
to a job but can be used by a running program to determine the amount of memory
allocated.
The effect of the SETSIZ program is to store into location 56 of block 0 of the
SAV file the number of K-words of memory to allocate for the program when it is
run (the LINK "/K:n" switch can also be used to do this). This value has no
effect when the SAV file is run under RT-11 but causes TSX-Plus to allocate the
specified amount of memory when starting the program.
If a size value is specified in a SAV file, it takes precedence over the size
specified by the last }lliMORY keyboard command. The TSX-Plus EMT with function
code 141 may still be used to dynamically alter the memory allocation while the
program is running.
Most programs allocate memory in two ways: 1) a static region that includes
the program. code and data areas of fixed size; 2) a dynamic region that is
allocated above the static region -- usually the • SETTOP EMT is used to
determine how much dynamic space is available to the program. The size of the
static region for a program is fixed at link time. If the program is overlayed
the static region includes space for the largest overlay segment as well as the
program root. Location 50 in block 0 of the SAV file is set by the linker to
contain the address of the highest word in the static region of the program.
The amount of memory space to allocate for a SAV file can be specified to the
SETSIZ program in either of two ways: 1) as the total amount of memory for the
program which includes space for the static plus dynamic regions; or 2) as the
amount of memory for the dynamic region only, in which case SETSIZ automatically adds the size of the static region.

-219-

SETSIZ
A.l Running the SETSIZ program
The SETSIZ program is started by use of the command
.R SETSIZ
it responds by printing an asterisk to prompt for a command line.
the command line is:

The form of

*filespec/switch:value
Where "filespec" is a file specification of the standard form dev:name.ext with
the default device being "DK"and the default extension being "SAV".
If a file specification is entered wi thout a swi tch, the effect is to cause
SETSIZ to display information about the size of the SAV file; the SAV file is
not altered.
SETSIZ also displays the following status message if the SAV file is flagged as
being a virtual image.
Virtual-image flag is set
The virtual message is displayed if either of the following two conditions
exist for the SAV file:
1.

Bit 10 (mask 2000) is set in the job status word (locatio,n 44) of the
SAV file.

Location 0 of the SAV file contains the RAD50 value for "VIR".

These are the same two conditions that cause TSX-Plus to recognize the SAV file
as being a virtual image when it is started.
Examples:
.R SETSIZ
*TSTPRG
Base size of program is 22Kb
Size of allocation space is 28Kb
*SY: PIP
Base size of program is 10Kb
Size of allocation space is 22Kb
*PROGI
Base size of program is 31Kb
No allocation size specified in SAV file
Virtual-image flag is set

-220-

SETSIZ
A.2 Setting total allocation for ~ SAV file
The "/T" swi tch is used to specify the total amount of memory space to be
allocated for a program when it is run.
The form of the /T switch is
"/T:value."
where "value" is the number of K-bytes of memory to allocate.
Note that a decimal point must be specified with the value if it is entered as
a decimal value.
If the "/T" switch is used without a value, the effect is to clear the TSX-Plus
size allocation information in the SAV file.
Examples:
.R SETS1Z
*SY:P1P/T:18.
*TSTPRG/T:32.
*PROGl!T
A.3 Setting amount of dynamic memory space
The "/D" switch is used to specify the amount of dynamic memory space to be
reserved for a program.
The SETS1Z program calculates the total amount of
space to allocate for the program by adding the static size (stored in location
50 of the SAV file by LINK) to the specified dynamic size. The form of the /D
switch is "/D:value." where "value" is the number of K-bytes of dynamic memory
space to reserve. If a program does not use any dynamic memory space, the ID
switch may be used without an argument value to cause the total memory space
allocation to be set equal to the static size of the program. FORTRAN programs
use dynamic space for I/O buffers and the exact amount required depends on the
number of I/O channels used. However, 4Kb of dynamic memory space seems to be
adequate for most FORTRAN programs.
Examples;
.R SETS1Z
*SY:PIP/D:ll.
*TSTPRG/D:4.
*PROGI/D
A.4 Setting virtual-image flag in SAV file
The "/V" swi tch is used to cause SETS 1Z to set the virtual-image flag in the
SAV file. This flag is bit 10 (mask 2000) in the job status word (location 44)
of the SAV file.
Setting this

flag

indicates

that

the program will not directly access R..'10N,

although it may do so indirectly by use of the .GVAL and .PVAL EMT's. The
significance with regard to TSX-Plus is that it allows the program to use more
than 56Kb (if that much memory is also allowed by use of a MEMORY command).
The virtual-image flag should not be set unless you are sure the job does not
need direct access to the RMON area.
-221-

-222-

Appendix ~

== DIBOL TSX-Plus SUPPORT SUBROUTINES

A set of subroutines is provided with TSX-Plus to perform DIBOL record locking
and message transmission functions.
DIBOL IS1\.'1 files are not supported by
TSX-Plus. These subroutines may not be used with DBL, which provides most of
their functionality separately. Note that if these TSX-Plus features are to be
used, they must be enabled when the TSX-Plus system is generated.
B.1 Record locking subroutines
The record locking subroutines coordinate access to a common file being shared
and updated by several TSX-Plus users.
The five subroutines parallel the
operation of the DIBOL statements: OPEN, CLOSE, READ, WRITE and UNLOCK. The
normal DIBOL I/O statements cannot be used to perform record locking under
TSX-Plus.
Opening the file
The first subroutine is used to open a shared file in update mode.
the call is:

The form of

XCALL FOPEN(chan,devlbl,errflg)
where
chan

A decimal expression that evaluates to a number in the range
1-15. This is the channel number used in associated calls to FREAD,
FWRIT, FUNLK and FCLOS subroutines.

devlbl = The name of an alphanumeric literal, field
contains the file specification in the general form:

or record that
dev:filnam.ext

The file size must not be specified with the file name. An optional
"/W" swi tch may be appended to the file name to cause the "WAITING
FOR dev:file" message to be printed.
errflg = A aumeric variable capable of holding at least two digits into
which is stored an indication of the result of the FOPEN call. The
following values are returned:
Value

o
17
18
72
73

Meaning
No error. File is open and ready for access.
File name specification is invalid.
File does not exist or channel is already open.
Too many channels are open to shared files.
Re-gen TSX-Plus and increase the value of MAXSFC parameter.
Too many shared files are open.
Re-gen TSX-Plus and increase the value of MAXSF parameter.

The FOPEN subroutine should only be used to open files that will be updated by
several users.
The normal DIBOL OPEN READ/WRITE sequence should be used for
other files.
Several files may be opened for update by calling FOPEN with
different channel numbers. The ONERROR DIBOL statement does not apply to these
record locking subroutines. Instead the "err fIg" argument is used to indicate
the outcome of the operation.
-223-

DIBOL Subroutines
Locking and reading a record
The FREAD subroutine is used to lock and read a record.
is:

The form of the call

XCALL FREAD(chan,record,rec #,'T' or 'W',errflg)
where
chan

Decimal expression in the range 1-15 that identifies a channel
previously opened by FOPEN.

record = Name of the record or alphanumeric field in which the record
read is to be placed.
rec # = Decimal expression that specifies the sequence number of the
record to be read. This value must be between 1 and the total number
of records in the file.
'T'/'W' = If 'T' is specified as the fourth parameter, FREAD will return a
value of 40 in err fIg if the requested record is locked by some other
user.
If 'w' is specified, FREAD will wait until the record is
unlocked by all other users and will never return the record-locked
error code.
errflg = Decimal
values:
Value

o
1
22
28
40
71
72

variable

into

which is stored one of the following

Meaning
No error. Record has been locked and read.
End-of-file record has oeen read.
I/O error occurred on read or channel is not open.
Invalid record number (possibly beyond end of file).
Record locked by another user.
(Only returned if 'T' is specified as fourth argument.)
Channel was not opened by calling FOPEN.
Request to lock too many blocks in file.
Re-gen TSX-Plus and increase value of MXLBLK parameter.

The FREAD subroutine functions like the DIBOL READ statement. However, whereas
the DIBOL READ statement always returns an error code (40) if the requeRted
record is locked, FREAD offers the user a choice: If 'T' is specified as the
fourth argument to FREAD, a code of 40 will be returned in errflg if the record
is already locked. If 'w' is specified as the fourth argument and the record
is locked, FREAD does not return an error code, but rather waits until the
requested record is unlocked. It is much more efficient to wait for a locked
record by using the 'w' option rather than re-executing the FREAD with the 'T'
option. It may be desirable to perform the first FREAD using the 'T' option.
If the record is locked a "WAITING FOR RECORD ••• " message can be displayed on
the user's console and another FREAD can be issued with the 'w' option to wait
for the record. On return from this FREAD the "WAITING" message can be erased.
-224-

DIBOL Subroutines
Note that although record locking is requested on a record-by-record basis, the
actual locking is done on a block-wi thin-file basis e
(A block contains 512
characters).
The result of this is that a record is locked if any record
contained in the same block(s) as the desired record is locked.
Once a record is locked and read using FREAD, the record remains locked until
the program performs one of the following operations:

1.
2.
3.
4.

Issues an FWRIT to the channel from which the record was read.
Issues another FREAD to the channel.
Issues an FUNLK to the channel.
Issues an FCLOS to the channel.
5.
Terminates execution by use of the STOP statement or because of an
error.
The same set of rules that apply to the DIBOL READ statement apply to FREAD.
Writing ~ record
The FWRIT subroutine is called to write a record to a shared file.
the call is:

The form of

XCALL FWRIT(chan,record,rec #,errflg)
where
chan =

Channel number associated with the file.

record
Name of the record or alphanumeric field
record to be written.

that

contains the

rec /I = Decimal expression that specifies the sequence number of the
record to be written.
errflg:=

Decimal

variable

into

which

stored

one

the following

values.
Value

Meaning

o No error.
22 110 error occurred during write or channel is not open.
28 Bad record number specified.
The FWRIT subroutine writes the indicated record to the file then unlocks any
blocks that were locked by the program. FWRIT appends a <CR><LF> to the end of
the written record as does the DIBOL WRITE statement. The rules for the DIBOL
WRITE statement also apply to FWRIT.

-225-

DIBOL Subroutines
Unlocking records
The FUNLK subroutine is used to unlock records that were locked by calling
FREAD. The form of the call is:
XCALL FUNLK(chan)
chan =

Channel number.

Closing ~ shared file
The FCLOS subroutine is called to close a channel that was previously opened to
a shared file by calling FOPEN. The form of the call is:
XCALL FCLOS(chan)
chan =

Channel number.

FCLOS unlocks any locked records and closes the file. Other users accessing
the file are unaffected. After calling FCLOS, the channel may be reopened to
some other file.
Record Locking Example
In the following example a program performs the following functions:
1. Opens a shared file named "INV.DAT" on channel 2.
2. Reads a record whose record number is stored in RECN into the field
named ITEM and waits if the record is locked by another user.
3. Updates the information in the record.
4. Rewrites the record to the same position in the file.
5. Closes the shared file.
XCALL FOPEN(2,'INV.DAT',ERRFL)
XCALL FREAD(2,ITEM,RECN,'W',ERRFL)
;<update record>
XCALL FWRIT(2,ITEM,RECN,ERRFL)
XCALL FCLOS(2)
Modifying programs for TSX-Plus
It is a straightforward process to modify DIBOL programs to use the TSX-Plus
record locking subroutines. OPEN, CLOSE, READ, WRITE, and UNLOCK statements
that apply to shared files must be replaced by the appropriate subroutine
calls.
Error conditions must be tested by IF statements following the
subroutine calls rather than by using the ONERROR statement.
B.2 Message communication subroutines
Three subroutines are included in the DIBOL support package to allow programs
to transfer messages to each other.
When running under TSX-Plus these
subroutines must be used instead of the DIBOL SEND and RECV statements.

-226-

DIBOL Subroutines
Message Channels
t1essages are transferred to and from programs by using TSX-Plus "Message
Channels"~
A message channel accepts a message from a sending program, stores
the message in a queue associated with the channel and delivers the message to
a receiving program that requests a message from the channel. Message channels
are totally separate from I/O channels.
Each active message channel has associated with it a one to six character name
that is used by the sending and receiving programs to identify the channel.
The total number of message channels is defined when TSX-Plus is generated.
The names associated with the channels are defined dynamically by the running
programs. A message channel is said to be "ac ti ve if any messages are being
held in the queue associated with the channel or if any program is waiting for
a message from the channel. When message channels become inac ti ve they are
returned to a free pool and may be reused by another program.
II

The DIBOL SEND command directs a message to a program by using the name of the
recelvlng program. Under TSX-Plus a sending program transmits a message using
an arbitrary channel name. Any program may receive the message by using the
same channel name when it requests a message.
j

Sending ~ Message
The MSEND subroutine is called to queue a message on a named channel. If other
messages are already pending on the channel the new message is added to the end
of the list of waiting messages. The form of the call is:
XCALL MSEND(chan,message,errflg)
where
chan =

alphanumeric literal or
channel name (1 to 6 characters).

variable

that

contains

the

message

aLpnanumeric or decimal literal, field or record that contains
the message to be sent.

err fIg

Decimal variable into which will be stored one of the following
values:
Value

o
1
2

Meaning
No error. Message has been sent.
All message channels are busy.
(Re-gen TSX-Plus and
increase the value of MAXMC parameter).
Maximum allowed number of messages are being held in
message queues. (Re-gen TSX-Plus and increase the value
of HAXHSG parameter).

Note that the maximum message length that may be transferred is defined during
system generation by the MSCHRS parameter. If a message longer than this is
sent, only the first part of the message will be delivered.

-227-

DIBOL Subroutines
Checking for Pending Messages
The MSGCK subroutine may be called to determine if any messages are pending on
a named channel. The form of the call is:
XCALL MSGCK(chan,message,errflg)
where
chan = alphanumeric literal or variable that contains the name of the
channel (1 to 6 characters).
message

alphanumeric or decimal
message is to be placed.

errflg

decimal variable into which will be stored one of the following
values:
Value

o
3

field

record

where

the

received

Meaning
No error. A message has been received.
No message was queued on the named channel.

If a received message is shorter than the receiving message field the remainder
of the field is filled with blanks. If the message is longer than the field,
only the first part of the message is received.
Waiting for a Message
The MSGWTs~broutine is used by a receiving program to suspend its execution
until a message is available on a named channel. It is much more efficient for
a program to wait for a message by calling MSGWT rather than repeatedly calling
MSGCK. The form of the call is:
XCALL MSGWT(chan,message,errflg)
where the arguments have the same meaning as for MSGCK,
values may be returned in errflg.
Value

a
1

Meaning
No error. A message has been received.
All message channels are busy.

-228-

and the following

DIBOL Subroutines
Message Examples
In the following example a program sends a message to another program by using
a message channel named "SORT" and then waits for a reply to come back through
a message channel named "REPLY".
XCALL HSEND( 'SORT' ,'DK: PAYROL. DAT' ,ERRFL)
IF(ERRFL.NE.O)GO TO ERROR
XCALL MSGWT('REPLY',MSGBF,ERRFL)
IF(ERRFL.NE.O)GO TO ERROR
B.3 Using the subroutines
The subroutines described above are part of the ~lliCRO program called
"DTSUB.MAC".
Once assembled, the object file for DTSUB (DTSUB.OBJ) may be
linked wi th DIBOL programs that use the record locking or message facilities.
An example of a LINK command is shown below •
•R LINK
B.4 Miscellaneous functions
Determining the TSX-Plus line number
The TSLIN subroutine can be called to determine the number of the TSX-Plus
timesharing line from which the program is being run. Real lines are numbered
consecutively starting at 1 in the same order they are specified when TSX-Plus
is generated.
Detached job lines occur next and virtual lines are numbered
last.
The form of the call of TSLIN is:
XCALL TSLIN(lnum)
where "Inurn" is a numeric variable capable of holding at least two digits into
which is stored the TSX-Plus line number value.

-229-

-230-

Appendix ~

== FILTIM PROGRAM

In addition to the date of creation of a file, TSX-Plus also stores file
creation times in device directories.
At the time a file is closed, the
current time of day is automatically stored in the sixth word of the directory
entry for that file. Under RT-11, this word is unused for permanent files and
contains the job and channel number for tentative file entries. In order to
represent the time as a positive 16-bit value, the time is converted to an
integer representing the number of 3 second intervals since midnight.
For
example, if a file were closed at 11:13:22, then the sixth word of the
permanent directory entry for that file would contain 13467 (32233 octal).
11 hr * 60 min/hr * 60 sec/min / 3 sec/interval
13 min
* 60 sec/min / 3 sec/interval
22 sec
/ 3 sec/interval

13200
260
7

13467
An EMT to obtain file directory information, including file creation times is
provided by TSX-Plus. An EMT is' also provided to set the file creation time
value into file directory entries.
See Chapter 7 for information on use of
these EMTs.
The DIR utility provided wi th RT=ll does not interpret file creation time
information as set by TSX-Plus, so a utility program (FILTIM) is provided with
TSX-Plus to obtain this information. The FILTIM program should be copied from
the distribution medium to the system device (SY:). It may then be run either
explicitly (R FILTIM) or implicitly as a system program (FILTIM).
Although
FILTIM does not accept wildcard file specifications, it will accept up to 6
file specifications.

The defaul t

device is "DK" and the default extension is

"MAC".
A device specification also applies to subsequent file sp~cifications
which do not explicitly include a device. Files created under RT-ll or before
this feature was implemented in TSX-Plus will have a creation time of 00:00:00.
Example:
.FILTL~ CKACT,TPR~~\N.TXT,¥~~J:CH13.DPS,APPCwDPS,RKO:FILTIM

DK:CKACT.MAC
DK:TPRMAN.TXT
MAN:CH13.DPS
MAN:APPC.DPS
RKO:FILTIM.MAC

3P
835
35
5
23

31-May-83
17-Jul-83
18-Jul-83
18-Jul-83
18-Jul-83

00:00:00
22:15:33
08:31:42
15:54:48
11:24:57

184
14226
3570
3605
4240

Note that the default device "DK" is used for CKACT and is carried over to the
next file specification, and that the default file type is "MAC". The logical
device "MAN" is used for the next two file specifications until the device
specification, "RKO".
And again, the default extension for RKO:FILTIM is
"MAC" •

Warning: Due to the method used by PIP for copy operat!ons, file creation times
are not preserved during copy operations, although the date is handled
correctly. When copying a file with PIP, the destination file will acquire the
time the copy is made as its creation time.
The EMT to set file times,
described in Chapter 7, may be used to set the correct time in the new file.
-231-

-232-

Appendix!?.

RT-11 ~ TSX-Plus EMT CODES

D.1 TSX-Plus RT-11 Compatible EMTs
EMT Code Chan Name

Description

--------------340 341
342
343 344
345
346 0
347 0
350
351
352 353 0
354 355
357 374
374
374
374
374
374
374

1
2
3
4
5
6

'l"'7t

"'7

,;)1'+

1"\

• TTINR
.TTYOUT
.DSTATUS
.FETCH/.RELEAS
.CSIGEN
.CSISPC/.GTLIN
.LOCK
• UNLOCK
.EXIT
• PRINT
.SRESET
.QSET
.SETTOP
• RCTRLO
.HRESET
.WAIT
.. SPND
.RSUM
• PURGE
.SERR
•HERR
• CLOSE
""T I"'\."T7

• 1. LVvL'\.

10
374
374 * 11
374
12
374 - 13
0
375
375
1

• CHAIN
.MWAIT
• DATE
.AETIO
• DELETE
• LOOKUP

'l"'7J:'

• ENTER

';)/J

£.

375
3
375
4
375
5
375
6
375
7
10
375
11
375
12
375
375 * 13
375
14
375 - 15
375 - 20

.TRPSET
• RENAME
• SAVE STATUS
• REOPEN
.CLOSE
.READ [C] IW]
.WRIT[C] [E] [W]
.WAIT
.CHCOPY
.DEVICE
.CDFN
.GTJB

Get character from terminal
Send character to terminal
Get device information
Load/Unload device handlers
Call command string interpreter
Get command line
Lock USR in memory
Allow USR to swap
Return to monitor
Display string at terminal
Software reset
Increase I/O queue size
Set program upper limit
Reset CTRL-O
Stop I/O then .SRESET
Wait for I/O completion
Suspend mainline program
Resume mainline program
Free a channel
Inhibit abort on error
Enable abort on error
Close channel
Try to lock USR
Pass control to another program
Wait for message
Get current date
Abort I/O in progress
Delete a file
Open existing file
Create file
Intercept traps to 4 and 10
Rename a file
Save channel information
Restore channel information
Close channel
Read from channel to memory
Write from memory to channel
Wait for I/O completion
Open channel to file in use
Load device registers on exit
Define extra I/O channels
Get job information

-233-

EMT Codes
EMT Code Chan Name

Description

375
21
375
22
375
23
375
24
375 * 25
375 * 26
375
27
375
30
375 0 31
375 0 31
375
32
375 * 33
375
34
375 - 34
375
34
37'5 - 34
375
35
375
36
375
36
375
36
375
36
375
36
375
36
375
36
375 * 37
375 * 37
375 * 37
375 * 37
375 * 37
375 * 37
375 * 37
375 * 37
375 * 37
375
40
375
41
375
42
375
43

Get time of day
Schedule completion routine
Cancel mark time
Timed wait
Send data to another job
Receive data from another job
Return channel information
Trap floating point errors
Control interrupt vector
Release interrupt vector
Special device functions
Context switch
Get monitor offset value
Get low memory value
Change monitor offset value
Change low memory value
Inhibit CTRL-C abort
Create an extended memory region
Eliminate an extended memory region
Create a virtual address window
Eliminate a virtual address window
Map virtual window to XM region
Get window mapping status
Obtain window status
Set terminal status
Get terminal status
Get character from terminal
Send character to terminal
Reset CTRL-O
Lock terminal to job
Release terminal from job
Display string at terminal
Get system status
Set date and time
Change mainline control flow
Change file date
Change file protection

.GTIM
.MRKT
.CMKT
• TWAIT
.SDAT[C] [W]
.RCVD[C][W]
.CSTAT
.SFPA
o .PROTECT
1 .UNPROTECT
.SPFUN
.CNTXSW
o .GVAL
1 .PEEK
2 .PVAL
3 .POKE
.SCCA
o .CRRG
1 .ELRG
2 .CRAW
3 .ELAW
4 .MAP
5 .UNMAP
6 .GMCX
o .MTSET
1 .MTGET
2 .MTIN
3 .MTOUT
4 .MTRCTO
5 .MTATCH
6 .MTDTCH
7 .MTPRNT
10 .NTSTAT
.SDTTM
.SPCPS
.SFDAT
.FPROT

Notes:

Not supported, will cause error.
Treated as NOP.
Minor differences, see Chapter 14.

-234-

EMT Codes
D.2 TSX-Plus Specific EMTs
EMT Code Chan Name

Description

375
375
375
375
375
375
375
375
375
375
375
375
375
375
375
375
375
375
375
375
375
375
375
375
375
375
375
375

Unlock all blocks
Wait for locked block
Try to lock a block
Send message on named channel
Get message from named channel
Wait for message on named channel
Get number of free spool blocks
Get line number
Resetiset ODT activation mode
Unlock a block
Send block of text to terminal
Get block of test from terminal
Check for terminal input errors
Set terminal read time-out
Reset/set high-efficiency mode
Check for writes to shared file
Save shared file information
Check for activation characters
Declare file for shared access
Send message to another line
Start a detached job
Check detached job status
Abort a detached job
Establish break sentinel control
Mount a directory structure
Dismount a directory structure
Initiate performance analysis
Start monitoring performance
Stop monitoring performance
Terminate performance analysis
Get terminal type
Convert virtual to physical address
Peek into the I/O page
Poke into the I/O page
Bit-set into the I/O page
Bit-clear into the I/O page
Map PAR7 to the I/O page
Map PAR7 to simulated RMON
Lock job into lowest memory
Unlock job from memory
Attach to interrupt vector
Release interrupt vector
Lock job without re-positioning
Get exclusive system access

101
102
103
104
105
106
107
110
111
113
114
115
116
117
120
121
122
123
125
127
132
132
132
133
134
135
136
136

UNLALL
LOCKW
TLOCK
SNDMSG
GETMSG
WATMSG
0 SPLFRE
0 TSXLN
0/1 ACTODT
UNLOCK
0 TTOBLK
0 TTIBLK
0 CKTTIE
0 SETTTO
Oil HIEFF
CKWSHR
SAVSHR
0 CKACT
SHRFIL
0 SEND
0 STRTDJ
1 STATDJ
2 ABRTDJ
0 DCLBRK
0 MOUNT
0 DISMNT
0 INITPA
1 STRTPA

375

1':36

2 STOPPA

375
375
375
375
375
375
375
375
375
375
375
375
375
375
375

136
137
140
140
140
140
140
140
140
140
140
140
140
140
140

3 HALTPA
0 TTYPE
0 PHYADD
1 PEEKIO
2 POKEIO
3 BISIO
4 BICIO
5 MAPIOP
6 MAPMON
7 LOKLOW
10 UNLOKJ
11 ATTVEC
12 REL\~C
13 LOKJOB
14 STEALS

-235-

EMT Codes
EMT Code Chan Name

Description

---------------- ----------------------------------375
375
375
375
375
375
375
375
375
375
375
375
375
375
375
375

140
140
140
140
140
141
143
143
144
145
146
147
150
151
152
153

15 RTURNS
16 SETPRI
17 MAPPHY
20 ATTSVC
21 SCHCMP
o MEMTOP
o USERTS
1 MAPRTS
o JSTAT
FILINF
SFTIM
0/1 GSUNAM
o SETPRI
SPHOLD
o SELOPT
o NONINT

Relinquish exclusive system access
Set user mode priority level
Map to physical memory
Attach interrupt service routine
Schedule completion routine
Control size of job
Associate with run-time system
Map run-time system into job
Get job status information
Get file directory information
Set file creation time
Get/set user name
Set job execution priority
Set spooler HOLD/NOHOLD
Select terminal option
Set [non]interactive job status

-236-

Appendix ~

SUBROUTINES USED IN EXAMPLE PROGRAMS

E.l PRTOCT - Print an octal value
The following subroutine accepts a value in RO and prints the 6 digit octal
representation of that value at the terminal •
• TITLE PRTOCT
.ENABLE LC
Print octal value of the word in RO
•MCALL
.GLOBL
PRTOCT: MOV
MOV
MOV
MOV
MOV
1$:
MOV
BIC
ADD
MOVB
CLC
ROR
ASH
SOB
• PRINT
MOV

MOV
CHARS:
EOW:

MOV
RETURN
.BLKB
.. ASCII

• PRINT
PRTOCT

Rl,-(SP)
R2,-(SP)
R3,-(SP)
IfEOW,R2
116,R3
RO,Rl
.It,

..,..,..,..,n . . . ,

7r 1. I I I I V , 1\.1.

lI'O,Rl
Rl,-(R2)
RO
11-2,RO
R3,1$
flcF....l\RS
(SP)+,R3
(SP)+,R2
(SP)+,Rl
6

(200)

jSave RI-R3 on the stack
;Point to end of 6 char output buffer
;Set up counter for 6 chars
jSet up mask for low 3 bits (Is digit)
jGet low 3 bits
jConvert to ASCII
;Fill octal digits in from end
;Shift out bits just converted
jRepeat for 6 chars
;Display result at console
jRestore registers Rl-R3

;6 char output buffer
;No CR terminator for .PRINT

.. EVEN

.END
E.2 PRTDEC - Print a decimal value
The following subroutine accepts a value in RO and prints the decimal representation of that value at the terminal with no leading zeroes •
• TITLE
.ENABL

PRTDEC
LC

Print the decimal value of the word in RO
•MCALL
.GLOBL
PRTDEC: MOV

• PRINT
PRTDEC'
Rl,-(SP)

;Save Rl and R2
-237-

Subroutines for Examples
MOV
MOV
MOV
CLR
1$:
DIV
ADD
MOVB
MOV
BNE
• PRINT
MOV
MOV
RETURN
.BLKB
BUFEND: • BYTE
.EVEN
.END
E.3 PRTDE2

R2,-(SP)
IIBUFEND,R2
RO,R1
RO
1110. ,RO
lI'O,R1
R1,-(R2)
RO,R1
1$
R2
(SP)+,R2
(SP)+,R1

;Point to end of output buffer
;Set up for DIV
;C1ear high word for DIV
;Get least significant digit
;Make remainder into ASCII
;Save digit in output buffer
;Set up for next DIV
;Unti1 nothing left
;Display number at the terminal
;Restore R1 and R2

5
200

;5 char output buffer
;No CR terminator for • PRINT

=Print

~~ digit

decimal value

The following subroutine accepts a value in RO and prints the decimal representation of it at the terminal. The value must be in the range of
to 99 •

• TITLE PRTDE2
.ENABLE LC
Print a 2-digit decimal value from RO
•MCALL
.GLOBL
PRTDE2: MOV
MOV
MOV
MOV
MOV
MOVB
MOV
CLR
2$:
DIV
ADD
MOVB
MOV
SOB
• PRINT
MOV
MOV
MOV
RETURN

• PRINT
PRTDE2
R1,-(SP)
R2,-(SP)
R3,-(SP)
RO,R1
II<BUFFER+2),R2
11200, (R2)
112,R3
RO
1110. , RO
lI'O,R1
R1,-(R2)
RO,R1
R3,2$
UBUFFER
(SP)+,R3
(SP)+,R2
(SP)+,R1

;Get copy of char in R1
;Point to buffer.
;Set end for .PRINT
;C1ear high word for DIV
;Get low digit
;Convert low digit to ASCII
;Put digit in char buffer
;Ro11 quotient for next DIV
;Two digits only
;Disp1ay the result

-238-

Subroutines for Examples
BUFFER: .BLKB

.EVEN

.. END
E.4 PRTR50 - Print a RAD50 word at the terminal
The following subroutine accepts a one word RAD50 value in RO and prints its
ASCII representation at the terminal.
Example:
.TITLE
.ENABL

PRTR50
LC

Display the RAD50 value of a word passed in RO
•MCALL .TTYOUT
.GLOBL PRTR50
PRTR50: MOV
R1,-(SP)
;Need place to store last char
;Need R4 and R5 for DIV
R4,-(SP)
MOV
R5,-(SP)
MOV
;Get copy of rO into dividend
RO,R5
MOV
jZero high word for DIV
R4
CLR
;Extract last char
1150,R4
DIV
;Save last char (remainder)
R5,Rl
MOV
MOV
;Move quotient for next DIV
R4,R5
;Zero high word for second DIV
R4
CLR
DIV
1150,R4
;Get first and second chars
;Display first char (quotient)
.TTYOUT R50TBL(R4)
; and second char (remainder)
.TTYOUT R50TBL(R5)
; and last char
.TTYOUT R50TBL(R1)
MOV
(SP)+,R5
jRestore registers
(SP)+,R4
MOV
(SP)+,Rl
MOV
RETURN
.NLIST BEX
R50TBL: .ASCII / ABCDEFGHIJKLMNOPQRSTUVWXYZ$. 0123456789/
• EVEN
.END
E.5 DSPDAT - Print !. date value at the terminal
The following subroutine accepts
representation at the terminal.

a date value in RO and prints the date

-239-

Subroutines for Examples
.TITLE
.ENABL

DSPDAT
LC

Print a date value from RO
• MCALL
.GLOBL
MONMSK
DAYMSK
YRMSK

=
=
=

• PRINT
DSPDAT,PRTDEC

036000
001740
000037

DSPDAT: MOV
MOV
BIC
ASH
CALL
MOV
BIC
ASH
ADD
• PRINT
MOV
BIC
ADD
CALL
MOV
RETURN
.NLIST
MONTBL: .ASCII
.ASCII
.ASCII
.ASCII
.ASCII
.ASCII
.ASCII
.ASCII
.ASCII
.ASCII
.ASCII
.ASCII
.ASCII
• EVEN
.END

R1,-(SP)
RO,R1
""CDAYMSK,RO
11-5,RO

PRTDEC
R1,RO
II"CMONMSK, RO
11-7,RO

IIMONTBL, RO
RO
R1,RO
II"CYRMSK,RO
1172. ,RO
PRTDEC
(SP)+,R1

;Get copy of date in R1
;Mask in only day bits (5-9)
;Shift down
;Print it out
;Get fresh copy of date
;Use only month bits (10-13)
;Shift down to index into month table
;Point into table
;Display the month
;Fresh copy again
;Use only year bits
;Year since 1972
;Dis'play the year

BEX
/-NON-/<200><0><0>
/-Jan-/<200><0><0>
/-Feb-/<200><0><0>
/-Mar-/<200><0><0>
/-Apr-/<200><0><0>
/-May-/<200><0><0>
/-Jun-/<200><0><0>
/-Jul-/<200><0><0>
/-Aug-/<200><0><0>
/-Sep-/<200><0><0>
/-Oct-/<200><0><0>
/-Nov-/<200><0><0)
/-Dec-/<200><0><0>

-240-

Subroutines for Examples
E.6 DSPTI3

=Display 3-second format time value
~

The following subroutine accepts a special 3-second time value in RO and prints
the time value at the termina' •
• TITLE

DSPTI3

.ENABL

Display special 3-sec format time value from RO
•MCALL
.GLOBL
DSPTI3: MOV
MOV
CLR
DIV
MOV
" ('IT
ft&:>l.i

• TTYOUT
DSPTI3,PRTDE2
Rl,-(SP)
RO,Rl
RO
1120. ,RO
Rl,-(SP)
n'

~.L

ADD
MOV
CLR
DIV
MOV
CALL

Rl,(SP)
RO,Rl
RO
1160. ,RO
Rl,-(SP)
PRTDE2
"TTYOUT II' :
MOV
(SP)+,RO
/"1.0\ T T

vn. ........

PRTDE2

• TTYOUT II' :
MOV
(SP)+,RO
PRTDE2
CALL
MOV
(SP)+,Rl
RETURN
• END
E.7 ACRTI3

;Set up for divide
;Get II of 3-SEC'S since midnight
jPut on stack
;2X 3-SEC'S
;Plus IX gives 3X = seconds
jGet rest of time
jSet up for next divide
jGet number of minutes
jAnd save on stack
;What's left is hours, display
;Recover minutes
jDisplay minutes
;Recover seconds

=Convert time value to special 3-second format
~

The following subroutine accepts a time value from the terminal and converts it
to a special 3-second internal format. The value is returned in RO •
•TITLE
.ENABL

ACRTI3
LC

Accept a time from the keyboard and return it in
a special 3-second format in RO
.GLOBL
ACRTI3: MOV

ACRTI3
Rl,~(SP)

-241-

Subroutines for Examples

1$:

MOV
MOV
CLR
CLR
CALL
BCS
MUL
MOV
TST
BNE
CALL
BCS
MUL
MOV
TST
BNE
CALL
BCS
CLR
DIV

R2,-(SP)
R3,-(SP)
HOURS
MINITS
GETNUM
2$
(1<60. *20. >,R3
R3,HOURS
NUMERR
1$
GETNUM
2$
1120. ,R3
R3,MINITS
NUMERR
1$
GETNUM
2$
R2

ADD

MINITS,R2
HOURS,R2
R2,RO

ADD
MOV
CLC
BR
SEC
2$:
MOV
3$:
MOV
MOV
RETURN
GETNUM: CLR
CLR
1$:
MOVB
CMPB
BLT
CMPB
BGT
MUL

2$:

3$:

113,R2

;Accrue decimal hours
;Return with error
;Convert hours to 3-sec periods
;Save hours in 3-sec units
;Did we hit end of input?
;Yes, return value
;Accrue decimal minutes
;Return with error
;Convert minutes to 3-sec periods
;Save minutes in 3-sec units
;End of input?
jYes, return value
jAccrue decimal seconds
;Return with error
;Convert seconds into 3-sec periods
;Quotient stays in R2
;Add in 3-secs from minutes
;Add in 3-secs from hours
;Return it in RC
;Say no error
;Return
;Say there was an error

(SP)+,R3
(SP)+,R2
(SP)+,Rl
NUMERR
R3
(RO)+,Rl
Rl,II . . O

2$
Rl,II .... 9

2$
1110. ,R3

SUB

lI'O,Rl

ADD

Rl,R3
1$
Rl, I":
3$

BR
CMPB
BEQ
INC
TSTB
BEQ
SEC
RETURN
CLC
RETURN

;Make sure it's reentrant

NUMERR

Rl
3$

;Say no error yet
;Initialize number
;Get next digit into Rl
;Less than 'O?
;Not a digit
;Greater than '9?
;Not a digit
;Shift previous digits
;Convert current digit to binary
;And include in number
;Get digits til next separator
;Is it a legal separator?
;Yes, return
;Say it may be end
;Was it a nul (end of input string)?
;Yes, return
;No, say invalid input
;Error return
;No error

-242-

Subroutines for Examples

HOUKS: .WORD
MINITS: *WORD
NUMERR: .WORD
.END

0
0
0

-243-

-244-

Appendix!

== TSX-Plus USER ERROR MESSAGES

Several different categories of errors can generate messages, ranging from
errors which are fatal to the operating system to something as simple as an
incorrect file specificatione Errors are identified by the name of the program
which recognized the error and one or more lines of descriptive information.
Errors identified by utility programs are identified by the name of the utility
(e.g., ?PIP-F, ?DUP-F, ?KED-F) and mayor may not abort the program. For more
information about utility program error messages, consult the appropriate RT-11
manual (RT-11 System Message Manual, RT-11 System Utilities Manual, RT-ll
Keypad Editor User's Guide, etc.). Errors which are fatal to the TSX-Plus
operating system (identified as ?TSX-F) report error conditions for which
time-sharing users are not usually responsible and usually cannot correct. TSX
fatal errors should be reported to the system manager who should consult the
TSX-Plus System Manager's Guide for more information. Errors which are not
fatal to the operating system but which indicate a user mode error are reported
as monitor errors.
This Appendix describes TSX-Plus specific monitor error
messages.
All user mode fatal monitor error messages have the syntax:
?KMON-F-"

message

or
?MON-F-"

message

where the "?KMON-F" form is used if the error occurs while using the keyboard
monitor and the "?MON-F" form is used for errors which occur within a user
program.
In some cases, the message is only informational rather than
indicating an error. In these cases, the message is of the form:
?KMON-I-" message

Error messages are consistent with RT-11 usage insofar as possible.
error messages

unique

TSX-Plus

are

described

below.

Consult

Monitor

the

RT-ll

System Message Manual for monitor errors not described here.
Ambiguous option
Not enough characters were specified to distinguish between options.
ASSIGN table full
Maximum number of logical assignments (15 per user)
ASSIGNS and DEASSIGN unnecessary logical assignments.

exceeded.

SHOW

Attempt to increase MAXPRIORITY above current value
Maximum job priority may be restricted by the system manager. It may be
reduced, but it may not be increased during a time-sharing session.
Cannot find SY:TSODT.REL file
The relocatable copy of the T5X-Plus ODT debugging program was not found
on the system device.
Copy the file "TSODT • RELit from the distribution
medium to SY.

-245-

Error Messages
Cannot file SY:TSXUCL.SAV
A command was attempted to be interpreted as a user-defined command, but
the TSXUCL program could not be found. Copy TSXUCL.SAV from the distribution to SY.
Cannot open alignment file
The alignment file specified in a SPOOL align command cannot be opened.
Cannot open logoff command file
A logoff command file which was specified during job start-up could not be
found while logging the job off.
Cannot open spool device
The spooler cannot access the spool device. Verify the device name used
in the SPOOL macro during TSX-Plus generation and check for correct device
assignments.
Can't open system accounting file
The file SY:ACCESS.TSX cannot be found during logon or logoff.
is created by the system manager.

This file

Closing log file
If a-device on which a terminal output log file is open is initialized or
squeezed, the log file is first closed.
Command file nesting too deep
Maximum depth of command file nesting exceeded. The depth of command file
nesting allowed depends on the number and length of parameter strings.
Three levels are possible even with long strings and as many as seven
levels are possible with no parameters.
See Chapter 3 for more information on command files.
Command file not found
--------The specified command file was not found.

See Chapter 2 for an explanation of command interpretation including default devices, and Chapter 3
for more information on command files.

Command file parameter string too long
Total number of characters in parameter string exceeds the maximum allowed
length of 60 characters. See Chapter 3.
Command string too complicated
The commarur-string expansion is too large for the internal CCL buffer.
Reduce the complexity of the command string. The SET CCL TEST command may
be used to examine the expanded command string generated by high level
commands.

-246-

Error Messages
Device is mounted by another user
-The INITIALIZE and SQUEEZE commands are invalid if the device is MOUNTed
by any other user.
This minimizes the opportunity for data corruption
when other users may be wr i ting to a device.
See the INITIALIZE and
SQUEEZE commands for motivation.
Device is still mounted by other users
This informational message is displayed when a DISMOUNT request is issued
for a device which is also MOUNTed by other users. See the INITIALIZE and
SQUEEZE commands for motivation.
Device or file is access restricted
----User does not have access privilege to requested device or file.

The
system manager may restrict user access to individual devices and files.

Directory I/O error
A device directory failed internal consistency checks. Devices must have
valid RT-ll format directories for use with TSX-Plus~ This error may also
occur when attempting to use 22-bit addressing with DMA devices when the
handler or hardware does not support 22-bit addressing.
Handler active -- Can't update running copy
An attempt-;as made to perform a SET command on a device handler which was
in use. If the handler is idle when the SET is issued, the change will be
made, otherwise, the running copy of the handIer is not altered. Reissue
the command when the handler is not active.
Illegal use of wildcards
Wildcards may not be specified for (part of) this command.
IND already active
The IND program cannot be run from within a command file which is being
executed under control of the IND program.
IND is not available
---rhe-IND.SAV program was not on the system disk during TSX-Plus start-up.
IND is provided with RT-ll version 5 and later.
Invalid logical disk name
Logical subset disks must be mounted as LDO through LD7.
Invalid multiple value on option
More than one parameter was specified for an option which only accepts
one.

-247-

Error Messages
Invalid or uninitialized directory
A disk device must contain a valid RT-ll format directory to be accessed
by any operation other than INITIALIZE.
Logical subset disks must be
initialized before first use. This error may also occur when attempting
to use 22-bit addressing with a DMA device and either the device handler
or hardware does not support 22-bit addressing.
Invalid SAV file
A file specified wi th an R or RUN command failed internal consistency
checks.
The file may be damaged. An incorrect file type may have been
specified - the default type is "SAV".
Invalid address as EMT argument
An address specified in a monitor call was odd or was not within the job's
address space. The value returned as the abort location is the address of
the instruction or the EMT that caused the error.
Invalid file name
An invalid file name was specified. Check for typing errors, names too
long, and correct file specification format.
Invalid line number
An invalid line number was specified for a KILL or DETACH command.
Invalid start address for program
The start addressfor the program was outside of the program's memory
bounds or on an odd address.
A MACRO program may have an incorrect
starting address specified wi th the .END directive.
The file may be
damaged. An incorrect file type may have been specified - the default is
"SAV".
Kernel mode trap within TSX-Plus
A kernel mode trap error usually indicates the operating system image has
been corrupted due to hardware or software failure. Record the full error
message and report the error to the system manager. This error can also
be generated by attempting to access a non-existent memory address with
the real-time EMT's to access the I/O page.
Line is gagged
Messages cannot be sent to lines which have SET TT GAG unless those lines
are waiting in TSKMON for a command.
Line too long
- - The expanded CCL command vvdS too long.
Commands are expanded into the
chain data area, locations 500 - 777. See the SET CCL TEST command.

-248-

Error Messages
Log file overflow
----xn-error was reported while writing to the terminal output log file. This
is most commonly an attempt to write past end-of-file. Make more room on
the output device, specify a file size with the SET LOG command, or use
the SET LOG NOWRITE option to reduce the volume of log file output.
Logical Disk support was not generated into system
Attempts to MOUNT a logical subset disk are not valid unless support for
logical subset disks was selected when generating TSX-Plus.
Logical disks must be nested in order of increasing unit #
Whenafile residing within a logical subset disk- is to be mounted as
another logical subset disk, it must be assigned a higher number than the
outer level logical subset disk.
For example, the following command is
invalid:
MOUNT L01 L03:MYOISK; whereas the following is acceptable:
MOUNT L03 LD1:MYDISK.
Max allowed number of devices already mounted
The number of device directories which may be cached is defined during
system generation. DISMOUNT devices on which caching is no longer needed
or consult the system manager.
Memory size change not allowed in non-swapping TSX system
Jobs may not change size dynamically unless job-swapping was
during system generation. Consult the system manager.

enabled

Missing equal sign
The equal sign was missing on a SET device command.
No defined operator's console
No operator console was defined during system generation.
Form mount
requests and messages using the OPERATOR command are sent to the operator
console.
No free detached job lines
- ----nle maximum number of detached job lines is specified during system
generation.
Either wait for a job to terminate, stop one by use of the
DETACH/KILL command, or ask the system manager to increase the number of
detached lines.
Not enough memory to run program
A file was too large (or the size specified in the SAY image was too
large) to fit in the space allocated to the job. See Appendix A for more
information on program size specifications. Use overlay segments or chain
requests to reduce the program size. Use the MEMORY command to request
more memory for your job. Note that you cannot use the MEMORY command in
a non-swapping environment; see the system manager.

-249-

Error Messages
Performance monitor is in use by user number nn
The performance monitor facility is already in use.
it at a time.

Only one job may use

Priority value must be in the range
Job priority may not be set less than 0, nor higher than the maximum
allowed priority.
Prompt string too long
Prompt strings may not be longer than 8 characters.
Save file I/O error
---- An I~rror occurred while reading the SAV file. Check that the disk is
still on line. It is also possible that the SAV file or the directory is
damaged.
SL was not included at system generation
The SET SL ON command may not be issued unless support for the single line
editor was selected when generating TSX-Plus.
System was not generated to support performance monitoring
Performance monitoring is an optional feature that must be included during
system generation. See the system manager.
Terminal type must be set to VT100 'or VT52
The SET SL ONcommandmay only be issued if the current terminal type is
VT100 or VT52. Other terminal types are not supported by the single line
editor.
Table overflow
Too many devices/files have been specified in the ACCESS command.
system manager.

See the

This command only legal in startup command file
- - - The ACCESS and SETLOGOFF commands are only valid in startup command
files.
This operation not legal with SY (system) device
The device which was booted when starting TSX-Plus may not be initialized
or squeezed while running TSX-Plus. If it is necessary to initialize or
squeeze this device, do so while running RT-11.
Too many completion routines
- - You have attempted to connect too many completion routines to interrupt
vectors.
The number of interrupt vectors that can be connected to
completion routines is determined during system generation.
See the
system manager.

-250-

Error Messages
Too many files
The command interpreter uses standard command string format:
up to 6
input files and 3 output files. Reduce the number of file specifications
accordingly.
Too many parameters to command file
TSX-Plus command files accept a maximum of six parameters.
Trap to 14
Abort location = nnnnnn
Invalid breakpoint trap executed.
The abort
address of the instruction following the trap.
Trap to 20
Abort location = nnnnnn
The abort
Invalid lOT instruction executed.
address of the instruction following the trap.

See Cnapter 3.

location provided is the

Trap to 34
~t:rocation = nnnnnn
Invalid TRAP instruction executed.
The abort location provided is the
address of the instruction following the trap.
TSGEN was modified without relinking TSKMON
Whenever a new TSX-Plus system generation is done, both TSX and TSKMON
must be relinked. See the system manager.
Unable to allocate memory for virtual overlays
The system failed toSuccessfully allocate extended memory regions when
trying to run a program with virtual overlays. Unlock jobs from memory or
increase the PLAS region swap file size.
Unable to open log file
The system reported an error when attempting to create a file for terminal
output logging. Check the file specification, verify that there is room
and that the output device is not write protected.
User command interface program not available
The system could not locate the file specified
SET KMON UCl[=filnam]. Check the file specification.
SY:UKMON.SAV.

with the command:
The default file is

USR called from completion routine
You cannot call system service routines that use TSUSR from a completion
routine.
This includes:
• LOOKUP , .ENTER, • RENAME , .DELETE, .CLOSE,
. DSTATUS, .SFDAT, and . FPROT.

-251-

Error Messages
USR err tin
--- AII-of the following USR errors result from consistency checks performed
in closing a tentative file (creating a permanent file).
These are
usually indicative of a strange hardware condition, such as exchanging or
squeezing a disk while a file is open.
USR err /I 1
--- TSUSR-can't find tentative file entry for specified file on close.
USR err /I 2
- -File
- - -length in channel block is not equal to length in file entry.
USR err /I 3
- - Highest block number written is greater than file length.
USR err /I 4
- - Empty-file entry doesn't follow tentative file entry.
USR err 11 5
Tentative file entry status was lost during close operation.
This is
usually an indication of hardware failure.
Unrecognizable command
TSX-Plus could not find a system command, a user-defined command, or a
command file with that name.
See Chapter 2 for more information on
command interpretation.
Value required for option
A command was issued that required a value for an option, but no value was
specified. Reissue the command correctly.
You are not authorized to write to that device or file
- - The-;Ystem manager may restrict access to individual devices or files.
See the system manager.
You're not privileged for that command
The command is a privileged command.
use of privileged commands.

The system manager may restrict the

?CCL-W-This command may interfere with other users
This warning is issued by CCL on INITIALIZE and SQUEEZE commands to warn
you that other users using that device might be dismayed by what you are
about to do. See the warning with the SQUEEZE command.

-252-

Appendix Q:= LOGICAL SUBSET DISKS
Logical subset disks provide a method of logically partitioning a large disk
into smaller units which can themselves be treated as directory structured
devices.
This is done by creating a (relatively large) file on a physical
device and then creating a device directory and files within that file. The
resulting pseudo device which is created within the file on the mother device
is called a logical subset disk.
Logical subset disks may also be nested.
That is, one logical subset disk may be contained within another logical subset
disk. This nesting may continue up to seven levels of logical subset disks
within other logical subset disks.
Logical subset disks may be initialized,
squeezed, and have files created, opened, closed and deleted. They may also be
assigned logical device names (e.g.
OUT:, DK:, ABC:).
Several keyboard
commands are used to manipulate logical subset disks: DISMOUNT, MOUNT, SET LD
and SHOW SUBSETS.
Support for logical subset disks is built into the kernel of TSX-Plus.
Therefore, it is not necessary to use the LD device handler and logical subset
disks may be used under TSX-Plus with either version 4 or version 5 RT-11
utilities.
Each user may

use all eight 199ical subset disks at any time.
That is, if one user has
mounted LDO then any other user may also use LDO simultaneously and they need
not (and usually will not) refer to the same file containing the logical subset
disk.
If logical subset disks are nested, then the device numbers must
increase with the level of nesting. For example, LDO may contain a file to be
mounted as LD1. However, a file contained within LD1 may never be mounted as
LDO.

The typical sequence of operations when using logical subset disks is to: 1)
create a file on a physical disk device; 2) mount that file as a logical subset
disk; 3) initialize the new logical subset disk; 4) and then proceed to use it
as any other disk device (except that it cannot be physically handled independently of the surrounding real disk). Subsequent uses of the logical disk only
require that the disk be re-mounted. The file need not be re-created, nor the
logical subset disk re-initialized.

The following example shows a typical sequence of commands which might be used
to initiate use of a new logical subset disk •
• CREATE DL1:MYDISK.DSK/ALLOCATE:500 •
• MOUNT LDO: DL1:MYDISK
.INITIALIZE/NOQUERY LDO:

.DISMOUNT LDO:
In order to use this new logical disk at a later time, it would only be
necessary to issue the MOUNT command:
.MOUNT LDO: DL1:MYDISK DK:

-253-

LOGICAL SUBSET DISKS
The default (and recommended) file type for files intended to contain logical
subset disks is .DSK.
When logical subset disks are mounted, information about them can be obtained
with the SHOW SUBSETS command. For example:
• SHOW SUBSETS
DLl:MYDISK.DSK[500]

L~->

To remove a logical subset disk from use,
example:

use

the dismount command.

For

.ASSIGN DL1 DK
.DISMOUNT LDO:
Note that the disk files containing logical subset disks are automatically
marked as protected files.
In order to delete them, they must first be
unprotected.
It is possible with logical subset disks to create some unusual situations and
conflicts. For example, it is possible to mount a logical subset disk and then
unprotect and delete the file which contained it. This condition would be
marked with an asterisk (*) with the SHOW SUBSETS command. In addi tion, the
SET LD CLEAN command can be used to force the system to compare, verify and
correct the information in its internal logical subset disk tables if possible.
Obviously, the system will not go back and recreate deleted files. An implicit
SET LD CLEAN is done each time the DUP utility is called (e.g. with the DELETE
and SQUEEZE commands).
For more information on the details of the commands used with logical subset
disks, see the descriptions in Chapter 2 of the following commands: DISMOUNT,
MOUNT, SET LD CLEAN and SHOW SUBSETS.

-254-

JOB EXECUTION PRIORITIES

Appendix~:=

TSX-Plus jobs may be assigned execution priorities to control their scheduling
relative to other jobs. The priority values range from 0 to 127. The maximum
execution priority that may be assigned to a job can be controlled by the
system manager by use of the TSAUTH account authorization program or the SET
MAXPRIORITY command (see the TSX-Plus System Manager's Guide).
The priority assigned to a job is set by use of the SET PRIORITY keyboard
command or the TSX-Plus EMT described in Chapter 7~ The current priority for a
job and the maximum authorized priority can be displayed by use of the SHOW
PRIORITY keyboard command, and may be obtained from within programs with the
.GVAL request.
The priority values are arranged in three groups:

the fixed-low-priority group

consists of priority values from 0 Up to the value specified by the PRILOW

sysgen parameter; the fixed-high-priority group ranges from the value specified
for the PRIHI sysgen parameter up to 127; the middle priority group ranges from
(PRILOW+1) to (PRIHI-l).
The following diagram illustrates the priority
groups:
127

+------------+

-->1

I Fixed
high
I
I priorities

PRIHI

-->1

+------------+
I

Normal
PRIDEF ~->I
job
1 priorities

PRILOW -->1

1
I

+------------+

I Fixed
I
I
low
I
I priorities I
-->1
1

+------------+

Job scheduling is performed differently for jobs in the fixed-high-priority and
fixed-low-priority groups than for jobs with normal interactive priorities.
Jobs wi th priorities in the fixed-low-priority group (0 to PRILOW) and the
fixed-high-priority group (PRIHI to 127) execute at fixed priority values.
That is, the priority absolutely controls the scheduling of the job for
execution relative to other jobs.
The job state does not influence the
execution scheduling except as to whether the job is in a ready-to-run state or
a wait state. A job with a fixed priority is allowed to execute as long as it
wishes until a higher priority job becomes active.
The fixed-high-priority group is intended for use by real-time programs. The
fixed-low-priori ty group is intended for use by very low priori ty background
-255-

Job Execution Priorities
tasks. Normal time-sharing jobs should not be assigned priorities in either of
the fixed priority groups.
The middle group of priorities from (PRILOW+l) to (PRIHI-l) are intended to be
used by normal, interactive, time-sharing jobs.
Jobs with these assigned
priorities are scheduled in a more sophisticated manner than the fixed-priority
jobs. In addition to the assigned priority, external events such as terminal
input completion, I/O completion, and timer quantum expiration play a role in
determining the effective scheduling priority. For these jobs the job state is
the primary factor in determining execution scheduling and the user-assigned
job priority only influences the scheduling of jobs in the same state. See
Chapter 5 of the TSX-Plus System Manager's Guide for further information about
job scheduling.
When a job with a normal priority switches to a virtual line, the priority of
the disconnected job is reduced by the amount specified by the PRIVIR sysgen
parameter. This causes jobs that are not connected to terminals to execute at
a lower priority than jobs that are. This priority reduction does not apply to
jobs with priorities in the fixed-high-priority group or the fixed-low-priority
group.
The priority reduction is also constrained so that the priority of
normal jobs will never be reduced below the value of (PRILOW+l).

-256-

Index
.ABTIO, 215
.CDFN, 215
• CHAIN, 215
.. CHCOPY, 215
.CNTXSW, 215
.CSIGEN EMT, 78
.CSISPC EMT, 78
.DEVICE, 215
.DEVICE EMT, 185
.FETCH, 215
.FORK, 215
.GTJB, 215
.GTLIN EMT, 78
.GVAL EMT
Checking I/O page mapping, 170
Special TSX-Plus use, 112
.HRESET, 215
.INTEN, 215
.LOCK, 215
.MTPS, 216
.MWAIT, 216
• PE EK , 172, 216
.POKE, 172, 216
• PROTECT, 202, 216
• PURGE
Shared files and, 151
~QSET, 216
• RCVD , 216
.RELEAS, 216
• RSUM , 183
• SAVESTATUS
Shared files and, 151
"SDAT, 216
.SDTTM, 216
.SETTOP, 111, 216, 219
.SFPA, 216
.SPND, 183
.SRESET, 216
.SYNCH, 217
.TLOCK, 217
.TTINR, 217
.TTYIN EMT
Command file input, 78
Non-wait input, 59, 105
Time-out value, 124
• UNLOCK, 217
.UNPROTECT, 217
ABORT command, 73
Aborting jobs
Detached jobs, 85
Normal jobs, 36

ACCESS command, 28
ACRTI3, 241
Activation characters, 97
Checking for, 128
Defining, 103
Field width, 104
ODT activation mode, 135
Resetting, 104
Time-out activation, 124
Adapting RT-11 Real-time programs,
202
Administrative control, 3
Alignment of forms, 96
ASSIGN command, 28
Assigns
Displaying those in effect, 62
B(ASE) command, 73
Backing up in a spool file, 92
BACKUP command, 29
Basic
BATCH facility, 217
Block locking
See Shared files
BOOT command, 29, 73
Booting the system, 73
Break sentinel control, 125
BYE command, 29
CACHE
SHO\.J command, 63
CACHE parameter
Selecting appropriate size, 46
Caching
Data, 160
Directories, 38
Carriage-return
Automatic line-feed, 106
Cataloged procedures
See Command files
Chapter summaries, 4
Character echoing, 57, 103
CLOSE command, 73
COBOL command, 29
Command file control, 75
Command files, 75
Comments within, 77
Control characters within, 78
Controlling input, 78, 104
Controlling listing, 58, 77, 78
Displaying messages, 79
Invoking, 17, 18, 76
Nesting of, 77
-257-

Parameter strings, 76
PAUSE command, 41
Pausing execution, 79
Setting error abort level, 48
Command interpreter, 17
Commands
Defining, 20
Listing user-defined, 63
Common data areas, 203
COMPILE command, 30
Completion routine
Connecting to an interrupt, 196
Scheduling, 201
Configuration
SHOW command, 63
Configuration requirements, 1
Control characters, 11
Ctrl-C, 11, 103
Ctrl-O, 11
Ctrl-Q, 11, 58, 59, 106
Ctrl-R, 11
Ctrl-S, 11, 58, 59, 106
Ctrl-U, 11
Ctrl-W, 11, 81
Ctrl-Z, 11
Within command files, 78
Control files
See Command files
Cooperative file access
See Shared files
COpy command, 30
CORTIM
SHOW command, 63
CORTIM parameter
Setting value, 47
CREATE command, 30
CRT terminal support, 58
D(EPOSIT) command, 73
Data caching, 160
Enabling use of, 148
Setting number of cache buffers,
53
Suppression of, 160
DATE command, 31
DBL default compiler, 50
DEASSIGN command, 31
Debugging programs, 42
Deferred character echoing, 57

DELETE command, 31
DELETE key
Rubout filler character, 102
DETACH command, 31, 83, 84, 85
Detached jobs, 81, 82
Aborting, 32, 85, 87
Checking status, 32
Checking status of, 84, 88
Comparison with virtual lines,
83
Control EMTs for, 85
Keyboard control commands, 31
Starting, 31, 83, 85
Device spooling
See Spooling
DIBOL command, 32, 73
DIBOL default compiler, 50
DIBOL record locking procedures,
147
DIBOL support subroutines, 223
DIFFERENCES command, 32
Directory caching, 38
Dismounting a file structure,
123
Displaying mounted devices, 65
Mounting a file structure, 122
SQUEEZE command effect, 69
DIRECTORY command, 32
Directory information
EMT to obtain, 136
DISMOUNT command, 33, 253
Dismounting a file structure, 123
DISPLAY command, 34, 79
DL-11, 1
DSPDAT, 239
DSPTI3, 241
DUMP command, 34
DZ-11, 1
E(XAMINE) command, 73
Echo control, 57, 103
EDIT, 47
EDIT command, 34
Editor
Selecting default, 47
Single line, 12
EMT codes
table, 233
EMT differences, 215
EMT tracing, 47
EMT's
TSX-Plus specific, 107
-258-

Index
Error messages, 245
Escape character
Within command files, 78
Escape sequence processing, 102
Exclusive access to a file, 147
Exclusive system control, 180
releasing, 180
EXECUTE command, 34
Execution priority, 255
Virtual lines, 81, 82
Extended memory regions, 143
Field width activation, 104
Field width limit for TT input,
106
File
Block locking, 147
Data caching, 160
Exclusive access, 147
Opening for shared access, l.'H
Protection modes, 147
Shared access, 147
File creation time, 138
File directory information, 136
Fixed-high-priority
Determining, 112
Fixed-low-priority
Determining, 112
Floating point, 216
Foreground programs
See Real-time support
Form alignment procedure, 96
FORM command, 34, 95
Form feed control, 57
Form names, 90, 95
FORMAT program, 217
FORTRAN command, 35
FRUN command, 73
Generalized data cache
Selecting appr,opriate size, 46
GET command, 73
Global data areas, 203
GT ON/OFF command, 73
Hardware requirements, 1
Hazeltine terminal support, 58
HELP command, 35
High-efficiency terminal mode, 42,
100, 101, 104, 132
HIPRCT
SHOW command, 64
'1

"'7

HIPRCT parameter
Setting value, 48
I/O page
Accessing, 145, 169

IND
Command file aborting, 48, 49
Command file processing, 49
Control of command files, 75
INITIALIZE command, 35
INSTALL command, 73
Interactive jobs
Selecting dynamically, 120
Interprogram communication, 163
Checking for messages, 165
Common memory areas, 203
Message channels, 163
Sending a message, 163
Waiting for a message, 166
Interrupt completion routine, 196
Interrupt processing
(Diagram), 190
Interrupts
Connecting to real-time jobs,
188
INTIOC
SHOW command, 65
INTIOC parameter, 49
Introduction, 1
10 abort handling, 49
Job number
Determining, 112
Job priority
Determining, 112
Maximum, 52
Setting, 53, 117, 186
SHOW command, 66
Job scheduling, 2
Job status information, 114
Job status word
Non-wait TT input, 59, 105
Setting virtual flag with SETSIZ,
221
Virtual-image flag, 143
K52, 47
Virtual lines, 82
KED, 47
Virtual lines, 82
Keyboard commands, 17, 28
Abbreviation of, 17

-259-

Index
Keyboard monitor
Prompt character, 54
KILL command, 36
KJOB command, 36
LA120 terminal support, 58
LA36 terminal support, 58
LD
Handler, 217
LD handler, 253
Lead-in character, 99, 101
Determining, 112
LIBRARY command, 36
Line number
Determining, 108
Determining primary, 112
Line-feed
Echoing of, 106
Ignored with tape mode, 59, 106
LINK command, 36
/XM switch, 143
LOAD command, 73
Locking a form on a spooled device,
90
Locking a job in memory, 182
Log off command files, 52
Logging off, 10, 40
Logging on, 9
Password, 9
Project programmer number, 9
User name, 9
Virtual lines, 81
Logging terminal output, 51
Logical device names, 28
Assigning, 62
Logical subset disks
Dismounting, 33
Mounting, 39
Nesting, 253
Using, 253
Verifying, 51
Lower-case character input, 58,
103
MACRO command, 37
MAKE command, 37
Mapping virtual region, 178
Maximum priority
Determining, 112
Setting, 52

Memory
Using as pseudo-disk, 145
Memory allocation
EMT to control, III
MEMORY command, 37
Setting size in SAV file, 219
MEMORY command, 37, 112, 219
Memory mapping, 141
Memory space
Displaying value, 65
Message channels, 163
Message communication
See Interprogram communication
Messages
error, 245
Inhibiting, 57
Sending to another line, 121
Modification of shared files
Checking for, 159
MONITOR command, 38, 207
MOUNT command, 38, 122, 253
Mounting a file structure, 38, 122
Multi-terminal EMTs, 215
MUNG command, 40
Non-interactive jobs
Selecting dynamically, 120
Non-wait TT input, 59, 105
Normal programs, 143
NUMDC parameter
Setting value, 53
SHOW command, 66
Obtaining TSX-Plus system values,
112
ODT activation mode, 135
ODT debugger, 217
OFF command, 40, 82
Opening. shared files, 147
OPERATOR command, 40
Operator communication, 40
Operator privilege
Determining, 112
Real-time jobs, 169
Optimization
SET SIGNAL, 54
Page length control, 58
Paint character
See Rubout filler character
Paper tape mode
See Tape mode
PAR 7 mapping
Determining, 112
-260-

Index
Parameter strings for command files,
76
Password
Changing, 9
Logging on, 9
PAUSE command, 41, 79
Performance monitor, 207
Control EMT's, 209
Displaying results, 208
MONITOR command, 38, 207
Starting, 207, 209
Physical address calculation, 184
Physical address space, 141
Physical memory access, 178
PLAS support, 143
Poke EMT, 174
Primary line
Determining, 112
PRINT command, 41
Printer form names, 90
Priorities, 255
Priority
Maximum, 52
PRIORITY
SHOW command, 66
Priority level
Setting, 53, 117
setting, 186
PRIORITY parameter
Setting value, 53
PRIVIR parameter, 118, 187, 256
Program controlled terminal options
See Terminal control
Programmed Logical Address Space
See PLAS support
Programmer number
Determining, 112
Project number
Determining, 112
PROTECT command, 41
Protected access to a file, 147
PRTDE2, 238
PRTDEC, 237
PRTOCT, 237
PRTR50, 239
Pseudo-disk in memory, 145
QUAN values
Selecting, 54
QUANxx parameters
Setting value, 54

SHOW command, 66
QUEMAN, 217
QUEUE, 217
R command, 41
/DEBUG switch, 42, 112
/HIGH switch, 42
fLOCK switch, 42
/NONINTERACTlVE switch, 43
/SINGLECHAR switch, 43, 105
Implicit, 18
Read time-out value for TT inputs,
124
Real-time completion routine, 196
Real-time jobs
Operator privilege, 169
Real-time priority, 197
Real-time support, 169
Accessing the I/O page, 169, 172,
177
Adapting RT-l1 programs~ 202
Device reset on exit, 185
Interrupt connections, 188
Locking a job in memory, 182
Mapping to physical addresses,
178
Physical address calculation,
184
Poke EMT, 174
Suspending/resuming execution,
183
Rebooting the system, 73
Record locking, 147
See Shared files
REENTER command, 73
Reentrant run-times
See Shared run-time systems.
Regions in extended memory, 143
Releasing exclusive system control,
180
REMOVE command, 73
RENAME command, 44
Requesting exclusive system control,
180
RESET command, 44, 70, 73
Resident run-times
See Shared run-time systems.
RESORC, 217
Restrictions
Keyboard commands, 73
Programs not supported, 217
-261-

Index
RESUME command, 73
RMON
Real-time support consideration,
170
Simulated, 143
SYSGEN options word, 107
RT-11
Returning control to, 72, 73
Rubout filler character, 102
RUN command, 44
/DEBUG switch, 42, 112
/HIGH switch, 42
fLOCK switch, 42
/NONINTERACTIVE switch, 43, 120
/SINGLECHAR switch, 43, 105
Run-time systems
See Shared run-time systems.
Running programs, 41, 44
SAVE command, 73
Scheduling a completion routine,
201
Scheduling of jobs, 2
Scope type terminal support, 58
SEND command, 44
Sending messages, 121
SET command, 45, 73
CACHE, 46
CCL, 46
CORTIM, 47
EDIT, 47
EMT, 47
ERROR, 48
Handler options, 45
HIPRCT, 48
IND, 49
INTIOC, 49
10, 49
KMON, 24, 49
LANGUAGE, 50
LD, 51, 253
LOG, 51
LOGOFF, 52
MAXPRIORITY, 52
NUMDC, 53
PRIORITY, 53
PROMPT, 54
QUANxx, 54
SIGNAL, 54
SL, 55
TERMINAL, 56

TT, 56
TT ADM3A, 57
TT DECWRITER, 57
TT DEFER, 57
TT DIABLO, 57
TT ECHO, 57
TT FORM, 57
TT FORMO, 57
TT GAG, 57
TT HAZELTINE, 58
TT LA120, 58
TT LA36, 58
TT LC, 58
TT PAGE, 58
TT QUIET, 58, 77
TT QUME, 58
TT SCOPE, 58
TT SINGLE, 58
TT TAB, 59
TT TAPE, 59, 106
TT terminal-type, 109
TT VT100, 59
TT VT50, 59
TT VT52, 59
TT WAIT, 59
UCI, 24
UCI=filnam, 24
UCL, 21, 60
UCL FIRST, 21, 60
UCL LAST, 21, 60
UCL MIDDLE, 21, 60
UCL NONE, 21, 60
VM, 61
WILDCARDS, 61
SET UCL command
FIRST, 17
LAST, 18
MIDDLE, 17
NONE, 19
SETSIZ program, 112, 219
Setting processor priority level,
186
Shared access to a file, 147
Shared files, 147
Checking for modification of,
159
Opening, 147
Protection modes, 148
Saving channel status, 151
Testing for locked blocks, 156
-262-

Index
Unlocking a block, 158
Unlocking all locked blocks, 159
Waiting for locked block, 154
Shared run-time systems, 203
Associating with job, 203
Displaying run-times available,
67

Mapping into job region, 144,
205
SHOW command, 62
ALL, 62
ASSIGNS, 62
CACHE, 63
COMMANDS, 63
CONFIGURATION, 63
CORTD1, 63
DEVICES, 64
HIPRCT, 64
INTIOC, 65
JOBS, 65
MEMORY, 65
MOUNTS, 65
NUMDC, 66
PRIORITY, 66
QUANxx, 66
QtJEUE, 67

RUN-TIMES, 67
SUBSETS, 67, 253
TERMINALS, 68
USE, 68
SHUTDOWN command, 73
Signaling
System tuning parameters, 54
Simulated RMON
Access through page 7, 143
Real-time support consideration,
170
Single character activation, 43,
58, 97, 105
Single line editoT, 1Z
SET options, 55
Skipping forward in a spool file,
91
SL, 12
Handler, 217
SET command, 55
Special Chain Exit, 24
SPOOL command, 69, 90
Aligning a form, 91
Backing up in a sponl file, 92

Checking device status, 92
Deleting queue entries, 91
HOLD & NOHOLD options, 93
SING & MULT options, 92
Skipping forward in a file, 91
Specifying a form name, 90
Spooling, 89
Aligning a form, 91
Backing up in a file, 92
Checking device status, 92
Concept of, 89
Deleting queue entries, 91
Directing output to, 89
Displaying requests in queue,
67
Form names, 95
Holding output, 93
Number of free spool blocks, 134
Single and multifile processing,
92
Skipping forward in a file, 91
Specifying a form name, 90
Specifying default form name,
34
SPOOL command, 69
Spooling, Operation of, 89
SQUEEZE command, 69
SRUN command, 73
START command, 73
Start-up command file, 9
Starting detached jobs, 83
STOP command, 72
Stopping the system, 72, 73
Summaries of chapters, 4
SUSPEND command, 73
SYSGEN options word, 107
SYSTAT command, 70
System configuration
Showing, 63
System device
Determining, 112
System resource management, 2
System tuning
SET SIGNAL, 54
System values
Obtaining, 112
Tab character support, 59
Tape mode, 59, 106
TECO, 47
MAKE command, 37
-263-

Index
Use within command files, 78
TECO command, 71
Terminal control, 97
Break sentinel, 125
Character echoing, 103
Checking for activation, 128
Checking for input errors, 127
Command file input, 104
Defining activation characters,
103
Disabling virtual line use, 103
Echo control, 103
Field width activation, 104
Field width limit, 106
High-efficiency mode, 104, 132
Line-feed echoing, 106
Lower-case character input, 103
Non-wait TT input, 105
ODT activation mode, 135
Read time-out value, 124
Resetting activation characters,
104
Rubout filler character, 102
Single character activation, +05
Tape mode, 106
Transparency mode output, 104
VT52 & VT100 escape sequences,
102
Terminal handler, 97
Terminal logging, 51
Terminal options
Setting, 132
Terminal type
Determining, 109
TIME command, 72
Time-out value for TT reads, 124
Transparency mode output, 104
TSODT debugging program, 42
TSX-Plus
Determining if under, 107
TSX-Plus license number
Determining, 112
TSXPM program, 207, 208
TSXUCL file
Size, 112

TSXUCL program, 23
Tuning parameters
Selecting, 54
TYPE command, 72
UCL, 20
UCL command, 72
UNLOAD command, 73
Unlocking a job from memory, 183
UNPROTECT command, 72
Unrecognizable command, 18
USE command, 72
User Command Interface, 17, 24
User Command Language, 20
User name
changing, 110
determining, 110
Logging on, 9
User-defined commands, 20
Order of interpretation, 17, 18,
19
SHOW command, 63
Utilities
Unsupported, 217
Virtual lines, 81
Comparison with detached jobs,
83
Disabling use of, 103
Execution priority of, 81
KED and K52, 82
Switching to, 11
Virtual memory, 141
Virtual programs, 143
Setting flag with SETSIZ, 221
Virtual region mapping, 178
Virtual to physical address, 141,
184
Virtual windows, 144
VM

Handler, 145, 217
Initializing, 145
SET BASE command, 145
VT100 support, 59, 102
VT52 support, 59, 102
WHO command, 72
X-off
See Control characters, Ctrl-S.
X-on
See Control characters, Ctrl-Q.

-264-