TSX Plus_5.0_Reference_Manual_Feb84 Plus 5.0 Reference Manual Feb84
TSX-Plus_5.0_Reference_Manual_Feb84 manual pdf -FilePursuit
TSX-Plus_5.0_Reference_Manual_Feb84 TSX-Plus_5.0_Reference_Manual_Feb84
User Manual: TSX-Plus_5.0_Reference_Manual_Feb84
Open the PDF directly: View PDF 
.
Page Count: 277
| Download | |
| Open PDF In Browser | View PDF |
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 • . • • • • • •
75
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
88
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
PRTOCT
PRTDEC
PRTDE2
PRTR50
DSPDAT
DSPTI3
ACRTI3
USED IN EXAMPLE PROGRAMS •
- Print an octal value •
- Print a decimal value
- Print a 2 digit decimal value
- Print a RAD50 word at the terminal
- Print a date value at the terminal
- Display a 3-second format time value
- 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
ix
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.
2.
TSX-Plus supports most RT-11 system service calls (EMTs).
3.
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.
4.
TSX-Plus uses RT-11 XM version device handlers.
5.
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
recent portion of the current
released to the printer as data
is closed. The spooling system
from the output queue, and reprint the most
file.
Files sent to a spooled device may be
becomes available or held until the output file
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
to
terminate
("log off")
a
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"
I Left arrow I Move cursor to left end of line
I Right arrow Move cursor to right end of line
!
I
I
I
I
I
I
I
I
BACK SPACE
DELETE
LINE FEED
RETURN
PF 1
PF2
PF3
PF4
Ctrl-U
for recall later
Exchange char under cursor with char to left
Retrieve last deleted character
Retrieve last deleted word
Truncate from cursor to end of line and execute
Ignored
Not implemented
VT52: Retrieve last deleted line
VT100: Retrieve last deleted line
Retrieve last deleted line
I
!
I
I
I
I
I
I
I
I
I
I
+-------------+-----------------------------------------------------+
-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.
2)
The SET SL LEARN mode is not implemented.
3)
The SET SL ASK option is ignored.
type information is used.)
4)
The SET SL SYSGEN option is ignored.
5)
The maximum width of a command line or input field that is accepted
is 80 characters. The SET SL WIDTH=n option is ignored.
6)
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.
7)
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.
8)
Using the single line editor with .TTYIN input does not force a new
line.
9)
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.
2.
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.
5.
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.
7.
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.
8.
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.
9.
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.
a
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
3.
DUMP
Run a program named "PAYROL" on device "DX1:" •
• RDN DX1: PAYROL
4.
List all files on "RK1:"
.DIR RK1:
5.
Start a command file "SY:LOADIT.COM" and pass it the parameter string
"PROG2" •
• LOADIT PROG2
6.
Execute the program
"A. TMP=B. TMP" •
"SY:PIP.SAV"
• PIP A.TMP=B.TMP
-19-
and
pass
it
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
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 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
44
BEL
BS
7
.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
;ASCII
;ASCII
;ASCII
;ASCII
;ASCII
10
12
14
15
33
LF
FF
CR
ESC
START:
•DSABL GBL
.SCCA
IIAREA,IITTSTAT
@/IMONPTR,RO
MOV
TST
SYSGEN(RO)
QUIT
BPL
MOV
IITTYPE,RO
375
EMT
RO
ASL
CMP
RO,1I4
lC
BLOS
....
CLR
RO
RO,Rl
MOV
• PRINT CLRSCR(Rl)
• PRINT {IMENU
{/SETRUB ,RO
MOV
375
EMT
• PRINT CENTER(Rl)
.GTLIN IIBUFFER, {IPROMPT
CALL
MATCH
BCS
2$
{11000, SP
MOV
CALL
MOVCMD
ftSPXIT$, @f.fJSW
BIS
RO
CLR
.EXIT
bell
backspace
line feed
form feed
carriage return
escape
;Disable undefined globals
;Inhibit control-C abort
;Get pointer to base of R}10N
;Are we running under TSX?
;Normal exit if not
;Point to EMT arg block to
;Get TSX-Plus terminal type
;Convert to word offset
;Legal types are unknown, VT52 and VT100
~
1$:
2$:
QUIT:
;If not VT52 or VT100, make unknown
;Save terminal type
;Clear the screen
;Display simple menu
;Point to EMT arg block to
;Set rubout filler character
;Move to screen center and clear the line
;Accept input line
;See if it's legal
;Repeat if illegal command
;Ensure stack pointer safe
;Move command from buffer to chain data area
;Set special chain exit bit ~n JSW
;Required for special chain exit
;And pass command to KMON
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
10
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
/[H//[J/<200> jVTI00 clear screen sequence
o
I
/Y% 1
/KI
1
1<200>
/[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:
1 [2KI <200) ;Erase entire line
!
Simple Menu
*****
/Command:
*****1<200)
1
------------------------------
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.
It
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.
2.
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.
3.
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
mounted by other users. If it is necessary
which is mounted by other users, then they
Remember that it is possible for a job which
access that device.
be performed on a device which is
to INITIALIZE or SQUEEZE a device
must first DISMOUNT that device.
has not mounted a device to still
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
defined
must be
and the
subset disks may be "nested", allowing one or more subsets to be
within other subsets. However, if this is done, the MOUNT commands
executed sequentially from outer-most to inner-most logical subset disk
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
/HIGH
/LOCK
/NONINTERACTIVE
/SINGLECHAR
------
Run program under control of debugger
Run program in high efficiency TTY mode
Lock program to line
Run program in non-interactive mode
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
2.
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
4.
Start the execution of BASIC and force logoff on exit •
• R/LOCK BASIC
---
5.
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 "R" command for
information about available switches.
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
2.
~
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
000000
000610
000000
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.
ON
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
SET
SET
SET
UCL
UCL
UCL
UCL
FIRST
MIDDLE
LAST
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
--)
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
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
------cmd
cmd
cmd
cmd
cmd
cmd
cmd
cmd
cmd
cmd
TEST. FOR
TEST.*
TEST
TEST.
*.FOR
.FOR
*.*
*
.*
IMPLICIT
-------cmd
cmd
cmd
cmd
cmd
cmd
cmd
cmd
cmd
cmd
TEST. FOR
TEST.*
TEST.*
TEST.
*.FOR
*.FOR
*.*
*.*
*.*
*.*
file specifications when
EXPLICIT
-------cmd
cmd
cmd
cmd
cmd
cmd
cmd
cmd
cmd
cmd
TEST.FOR
TEST.*
TEST
TEST.
*.FOR
.FOR
*.*
*
.*
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.
a
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
MT
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
8
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
DL
DL
DZ-O
DZ-l
DZ-3
060
310
320
300
300
300
177560
176510
176520
160040
160040
160040
VT100
VT100
LA120
VT100
VT100
VT52
Active
User
------ ------------
-------- -------- ------ --------N/A
N/A
N/A
9600
9600
1200
Yes
No
Yes
Yes
No
No
SYSMGR
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
.. 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 "/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/<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
;Check status
;If still on,
;Else, say it
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
arg block to
of a detached job
kill it
isn't active
.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
with the FORM or LOCK functions. The FORM command is used by
to specify the default form name to be used for subsequent
SPOOL FORM/LOCK commands are used by the TSX-Plus operator to
system which form is currently mounted.
The ALIGN
The ALIGN
The name
command.
the SPOOL command
the TSX-Plus user
spool files. The
tell the spooling
Function
function is used to print a form alignment file on a spooled device.
of the alignment file is specified in the "parameter" field of the
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
o
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
o
1
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
a
form-mount
request
message
and
suspends
the
2.
The operator mounts the desired form and issues one or more SPOOLALIGN commands to verify its positioning.
3.
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.
4.
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
F
H
I
J
K
L
M
N
o
P
Q
R
s
T
U
V
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
1$
• 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.
e
-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
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
C
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
to
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
LC
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
44
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
IILINMSG
LINE,RO
PRTDEC
• PRINT
MOV
EMT
liT RMMS G
IITTYPE,RO
375
ASL
• PRINT
.EXIT
RO
TYPE(RO)
NOTTSX: .PRINT
• EXIT
LINE:
TERM:
TSXLN:
TTYPE:
NOTTSX
RO,LINE
BCS
MOV
• HERR
• PRINT
MOV
CALL
• WORD
eWORD
• BYTE
• BYTE
jIf error, not under TSX-Plus
;Save it
;Enable error aborts
jDisplay line number message
;Recall line number
;Display line number
;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
IITSXERR
;Say we are not under TSX-Plus
o
jStorage for TSX line number
;Storage for TSX term type code
;TSX line number EMT parameters
;TSX term type EMT parameters
o
0,110
0,137
; 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
in
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
9$
;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.
------ -that indicate the status of the jobe The
000001
000002
000100
000200
This is
This is
Job has
Job has
The value returned contains bit flags
following bit flags are defined:
a virtual line.
a detached job line.
locked itself in memory.
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
BR
CHECK
SLEEP:
• TWAIT
BR
ERRTYP: CMPB
BLT
BEQ
MOVB
DECB
BR
2$ :
.EXIT
MEMTOP:
e
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
2
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:
o
PRGNAt\f
BUFADD
2
30.
0,127
o
o
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
0
-->1
1
Fixed
1
I
low
1
I
1 priorities 1
-->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 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
AREA:
.BLKW
SETPRI: • BYTE
NEWPRI: • WORD
CURlS:
MAXIS:
NEWIS:
PRTDEC
10
0,150
50.
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
o
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
1$
;Else echo it back (we have to echo
; when in single char mode)
;And repeat
,
.TTYOUT
BR
2$:
3$:
4$:
MOV
MOV
EMT
• PRINT
.TTYIN
CMPB
BEQ
• TTYOUT
BR
111, SELECT
#N()NTN'T' RO
11 ..... ,...., ................... ,
... , , _
375
IIFAST
RO,IICTRLZ
4$
3$
..... .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
• EXIT
SINGLE: • BYTE
• WORD
•WORD
NONINT: .BYTE
SELECT: .WORD
•WORD
.NLIST
SLOW:
.ASCII
.ASCII
.ASCII
.ASCIZ
FAST:
.ASCIZ
.END
0,152
'S
°0,153
°BEX
°
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
o
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~
LC
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:
:/<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
o
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
BS
.GLOBL
10
•MCALL
IRAD50
=
;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:
:/<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
'Q
.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
o
• WORD
o
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
;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
since the line logged on or since the last time a
errors.
The two types of errors that a:re monitored
reported errors (parity, silo-overflow, etc.) and
TSX-Plus input buffer overflow.
input error has occurred
check was made for input
by this EMT are hardware
characters
lost
due
Example:
.. TITLE CKTTIE
~ENABL
LC
;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-
to
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
IIYESERR
HADERR: • PRINT
CMP
jNote that last
;for activation
BLE
• PRINT
.EXIT
TOOMNY: • PRINT
• EXIT
;Error message
;Did we fill the buffer?
two chars of input buffer are reserved
chars. Any excess input is discarded.
TOOMNY
;Yes, buffer overflow
;No, hardware error message
tlHDWERR
SETTTO: • BYTE
• WORD
• WORD
CKTTIE: • BYTE
.NLIST
YESERR: .ASCIZ
OVFERR: .ASCIZ
HDWERR: • ASCIZ
NOERR: .ASCIZ
PROMPT: .ASCIZ
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 • • • /
.END
R1,113
IloVFERR
;Buffer overflow message
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
;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
;from a terminal •
• MCALL
.EXIT,.PRINT,.TTYIN
II PROMPT
#TTIBLK,RO
375
EMT
MOV
RO,Rl
;Char count includes activation
BCC
1$
• PRINT IloVFLOW
1$:
ADD
#BUFFER,Rl
CLRB
(Rl)
• PRINT IIBUFFER
• EXIT
START:
• PRINT
MOV
TTIBLK: .BYTE
• WORD
• WORD
charact~rs
;Request input
;Point to EMT arg block to
;Accept a block of chars from the terminal
;Save input character count
char (and LF after CR)
;Buffer overflow on input?
;Yes, warn user
jPoint past last char in buffer
;Make the input ASCIZ
;Reproduce the input
0,115
;EMT arg block to accept block from terminal
BUFFER
;Start of input buffer
(RO) jReplace the activation char with
#12,BUFFER(RO) jCarriage return, line feed
RO
jCount LF for output
RO i
;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
6
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
not in use, "dblk" is the address
specification (device, file name,
7-word block that will receive the
returned in "rblk" is:
Word
Word
Word
Word
Word
Word
Word
Errors:
Code
0
1
2
1:
2:
3:
4:
5:
6:
7:
in the range 0-16 (octal) that is currently
of a 4-word block containing the RAD50 file
extension), and "rblk" is the address of a
information about the file. The information
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
=
START:
.CSISPC
MOV
EMT
BCC
MOVB
ASL
wPRINT
• EXIT
#ODTSPC,#DEFLT, #0, #BUFFER
jGet file name
;Point to EMT arg block to
#FILINF,RO
375
;Get information about a file
5$
;Nc error?
@#ERRBYT,R1
jWhat error
R1
;Convert to word index
5$:
10$:
MOV
TSTB
BNE
MOVB
• PRINT
.TTYOUT
MOV
CALL
TST
#BUFFER,RO
(RO)+
10$
#200,-(RO)
{IBUFFER
15$:
;EMT error code location
52
11'[
FILSIZ,RO
PRTDEC
PRTCTD
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
.NLIST
FILINF: .BYTE
• WORD
•WORD
FILS IZ: • WORD
PRTCTD: .WORD
;Find the end of the file spec.
;End?
;No, keep looking
jNo CR,LF at end
;File name
BEX
0,145
INSPC
FILSIZ
o
o
;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
;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
°°
°0,0
15.
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
13 min
*
*
60 sec/min = 39600
780
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
o
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
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
;EMT error code location
;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
2$
-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.
2)
The amount of memory specified with the MEMORY keyboard command
(initialized by the DFLMEM system generation parameter).
3)
The memory limit reserved
program (see Appendix A).
4)
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.
2)
Simulated RMON.
This is the virtual address region from 160000 to
177777 that is mapped to a simulated RMON (RT-11 resident monitor).
3)
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.
4)
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.
5)
System I/O page.
TSX-Plus real-time programs may map the system I/O
page into their virtual address space.
These categories
sections.
of
space which
virtual
address
is
job can be divided into five cate-
used
space
-142-
by
are
instructions
discussed
in
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.
2)
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.
3)
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
BCC
• PR INT
• EXIT
MOV
MOV
#AREA,#O,#SHRI
1$
EHT
375
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
IILKPERR
jOpen SHRl.DAT
jBranch if OK
;Lookup error message
#EXUP, ;Set Exclusive, Update access
#SHRFIL,RO
;Point to EMT arg block to
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, ;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
ERRBYT
BUFSIZ
.LOOKUP,.PRINT,.EXIT,.READW
.CLOSE,.TWAIT
jEMT error byte
;Size of disk file block
52
256.
START:
.LOOKUP
BCC
• PRINT
BR
#AREA,#0,#SHR1
1$
#LKPERR
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
BCC
• PRINT
BR
IIAREA,1I0,#SHR2
4$
#LKPER2
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
4$
-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
10
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
• END
BUFSIZ
;Input read buffer
START
-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
4$
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
BR
2$
• 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
2$
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
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
.NLIST
AREA:
.BLKW
.RAD50
SHRl:
SHRFIL: • BYTE
• WORD
LOCK:
• BYTE
• WORD
UNLALL: • BYTE
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
9.5 Unlocking
START
~
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
ERRBYT
START:
1$:
= 52
.GTLIN
MOV
TSTB
BNE
SUB
MOV
.GTLIN
MOV
EMT
BCC
MOVB
DEC
ASL
• PRINT
• EXIT
9$:
.EXIT,.PRINT,.GTLIN
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<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
10.4 Waiting for
;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
~
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
Meaning
1
4
All message channels are busy.
Message was longer than the receiving buffer.
Example:
.TITLE
WATMSG
.ENABL
LC
Demonstrate TSX-Plus EMT to wait for a queued message from the
interprocess message communication facility •
•MCALL
ERRBYT
=
START:
.GTLIN
• PRINT
MOV
jEMT error byte
52
EMT
2$:
5$ :
.EXIT,.PRINT,.GTLIN
BCC
CMPB
BHI
• PRINT
.EXIT
• PRINT
• PRINT
.PRI~"T
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.
a
;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.
2.
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.
3.
The ability for a program to lock itself in memory so that rapid
interrupt response can be assured=
4.
The ability for a program to suspend its execution until an interrupt
occurs.
5.
The ability to set execution priorities for tasks.
6.
The ability to convert a virtual address within the job's region to a
physical address for DMA I/O control.
7.
The abili ty to map a virtual address region to a physical address
region.
8.
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
CONFIG
RCSR
RBUF
CTRLC
START:
= 54
= 300
jSYSCOM location holding base of RMON
;Fixed offset into RMON of CONFIG word
;Serial line RCSR address
;Line input buffer address
jControl-C
176540
= RCSR+2
=3
• MCALL
.GLOBL
.PRINT,.EXIT,.TTYOUT,.GVAL
PRTOCT
CALL
SHOMAP
;Display current PAR 7 mapping
-170-
Real-Time Programs
CALL
1$:
2$:
3$:
.. PRINT
MOV
EMT
BCC
• PRINT
• EXIT
CALL
• PRINT
MOV
CLR
TSTB
BPL
MOVB
CMPB
BEQ
.TTYOUT
BR
MOV
• PRINT
MOV
EMT
CALL
CALL
• EXIT
SHOMAP: • PRINT
.GVAL
ASL
• PRINT
SHODAT
jDemonstrate "RMON" mapping
IIIOPMSG
;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
llMAPIOP ,RO
375
1$
IINOPRIV
SHOMAP
IITYPE
@IIRCSR,CSRSAV
@#RCSR
2$
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
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
@IIRCSR
2$
@IIRBUF ,RO
RO,IICTRLC
3$
RO
CURMAP(RO)
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
o
;Preface
jPick up
;Get the
jDisplay
config value
pointer to RMON base
current CONFIG value
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$
ADD
MOV
EMT
CMPB
BEQ
• TTYOUT
SUB
BR
112, PEKADD
IlpEEKIO,RO
375
RO,lIcTRLC
3$
112,PEKADD
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
CSRSAV,POKVAL
IlpOKEIO, RO
375
;Want to restore the original CSR status
;Point to EMT arg block to
;Restore the CSR
.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
;Pick up
;Get the
;Display
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.
config value
pointer to RMON base
current CONFIG value
it
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
MOV
EM!
ADD
112,PEKADD
MOV
EMT
/lPEEKIO,RO
375
CMPB
BEQ
.TTYOUT
SUB
BR
RO,IICTRLC
2$
;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
EMT
IIBISIO,RO
375
;Want to set input interrupts
jPoint to EMT arg block to
;Set a bit in the I/O page
3$
112,PEKADD
3$:
• 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
;Pick up
jGet the
jDisplay
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)
config value
pointer to RMON base
current CONFIG value
it
;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
o
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
020000
040000
060000
100000
120000
140000
160000
-
017777
037777
057777
077777
117777
137777
157777
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
BR
2$
;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
7
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.
2.
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
35
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
.TTYOUT
.TTYOUT
.TTYOUT
#LEADIN
#'S
i/LEADIN
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
1
1
I
1
PRIHI
PRIDEF
1
Fixed
high
priorities
-->1
1
I
1
I
+------------+
1
1
1
I
Normal
1
job
I
priorities I
1
1
-->1
+------------+
PRILOW
-->1
1
1
I
o
Fixed
low
priorities
-->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"
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
interrupt to an interrupt completion routine.
Real-time
routines have access to the full job context and can use
calls (EMT's), but have more overhead and should not be
that occur more frequently than 200 times per second.
is to connect the
interrupt completion
most system service
used for interrupts
The following diagram illustrates the different levels of interrupt
-189-
processing~
Real-Time Programs
Interrupt Processing
+--------------------------------------------------------------------+
1
Level 2
Level 1
Level 3
I
1
I
Hardware interrupt
1
I
I
I
I
I
I
I
I
I
I
v
• INTEN
I
V
.FORK
>-----------------+
1
1<--------------+
V
1
+-----------+
1
1 Interrupt 1
1
Service
Routine
I
1
I
I
I
1
1
+-----------+
1
1
1
1
1
V
1
I
+--------------+
I
I
1
1
More
Fork
Requests
?
1
1
I
I
1
I
1
I
(yes)
1
1
1
1
1
1-------+
I
+--------------+
I
(no) 1
1
1<-------------------------------+ I
v i i
+--------------+
+------------+ 1 I
1 Any
1
I
I
1 I
1 1
1------->1
1--+
?
1
1
1
1
+------------+
+--------------+
Pending
Completion
1 Routines
(no)
I
(yes)
1
Interrupt
Completion
Routine
1
1
1
1
I
1
1
1
+---------------------+
I
I
1
1
v
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.
b)
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.
2)
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
o
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
(:0 •
;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
GETFIL: MOV
.CSISPC
.Lv,
BCS
MOV
• ENTER
BCS
MOV
CLR
,
•TTYIN,.TTYOUT,.EXIT,.PEEK,.POKE,.GVAL,.SCCA
.ENTER,.LOOKUP,.CSISPC,.WRITE,.PURGE,.CLOSE,.DEVICE
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
#OUTSPC,#DEFEXT,#O ;Get file specification
1$
jRepeat until valid command line
SPSAVE,SP
;Restore SP, no valid switches
#AREA,#O,#INSPC,#-l jOpen largest possible output file
1$
jOn error, ask for new file
#BUFF1,BUFPTR
jlnitialize buffer pointer
BLOCK
jlnitialize output file block count
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:
• BLl{Tvl
,,,
.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
• WORD
• WORD
INTSVC: • BYTE
• WORD
•WORD
• WORD
SCHWRT: • BYTE
• WORD
•WORD
D
CTRLD
20,140
VECTOR
ISR
a
;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)
-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
2
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
1$
;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
0-
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.
;-
CMPRTN: MOVB
CMPB
BEQ
.TTYOUT
MOV
EMT
,.
CLR
@IIRBUF ,RO
RO,IICTRLC
1$
HSETPRI,RO
375
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
11.12 Releasing
;Point to EMT arg block to
;Set processor priority (reenable interrupts)
;Return to main-line code
;Wait for next interrupt (NOTE: Not RTI)
7
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
~
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.
11.13 Scheduling
~
the
section on connecting
a
real-time
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
o
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.
2.
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.
3.
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.
4.
The. PROTECT EMT is a no-op under TSX-Plus and always returns wi th the
carry-flag cleared.
5.
Interrupt service routines and completion routines connected to real-time
interrupts should exit by use of a RTS PC instruction rather than RTI.
6.
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
completion routine is connected to the interrupt.
If a
interrupt occurs with no associated interrupt service or,
routine, a fatal TSX-Plus system error (UEI) occurs and the
value" displays the address of the vector of the interrupt.
8.
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.
9.
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-
routine- or
real-time
completion
"argument
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.
2.
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
.ENABL
Demonstration
•MCALL
PARI
= 20000
START: MOV
EMT
BCC
• PRINT
.EXIT
MOV
1$:
EMT
2$:
CALL
,.
CLR
CLR
MOV
EMT
.EXIT
USERTS: .BYTE
•WORD
SHRNAM: • RAD50
MAPRTS: • BYTE
•WORD
• WORD
•WORD
.NLIST
NOSHRT: .ASCIZ
.END
USERTS
LC
of TSX-Plus EMT to map to a shared run-time region
.PRINT,.EXIT
;Base address of PAR 1 window
IIUSERTS,RO
;Point to EMT arg block to
375
;Associate a shared run-time region
;Error?
1$
IINOSHRT
;Can't find named shared run-time
IIMAPRTS ,RO
375
@11
(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
o
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
.TTYOUT
MOV
BEQ
.TTYOUT
SOB
• PRINT
CMP
CMP
BLE
• 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
PRTOCT
tis PACE
HSTTBL(R3),Rl
65$
tlSTAR
Rl,60$
tlCRLF
(R2 )+, (R3 )+
R3, 11<2 *NCELLS>
55$
0,136
BEGIN
ENDB-2
2
1
1,136
2,136
3,136
PRMBUF
HSTTBL
3
o
<2*NCELLS>+2
10
256.
o
;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.
to
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.
2.
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.
rec /I
that
contains the
=
Decimal expression that specifies the sequence number of the
record to be written.
errflg:=
Decimal
variable
into
which
is
stored
one
of
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 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)
;
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
or
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
timesharing line from which the program is being run. Real lines are
consecutively starting at 1 in the same order they are specified when
is generated.
Detached job lines occur next and virtual lines are
last.
TSX-Plus
numbered
TSX-Plus
numbered
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
13 min
*
*
60 sec/min / 3 sec/interval
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
347
350
351
352
353
354
355
357
374
374
374
374
374
374
374
'l"'7t
0
0
0
0
1
2
3
4
5
6
1"\
"'7
374
374 *
374
374 375
375
10
11
12
13
0
1
,;)1'+
'l"'7J:'
';)/J
V
1
"I
£.
375
3
375
4
375
5
375
6
375
7
10
375
11
375
12
375
375 * 13
375
14
375 - 15
375 - 20
• 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'\.
• CHAIN
.MWAIT
• DATE
.AETIO
• DELETE
• LOOKUP
• ENTER
.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
375
375
375
375
375
375
375
375
375
375
375
375
375
375
37'5
375
375
375
375
375
375
375
375
375
375
375
375
375
375
375
375
375
375
375
375
375
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
*
*
0
0
*
-
*
*
*
*
*
*
*
*
*
21
22
23
24
25
26
27
30
31
31
32
33
34
34
34
34
35
36
36
36
36
36
36
36
37
37
37
37
37
37
37
37
37
40
41
42
43
o
1
o
1
2
3
o
1
.GTIM
.MRKT
.CMKT
• TWAIT
.SDAT[C] [W]
.RCVD[C][W]
.CSTAT
.SFPA
.PROTECT
.UNPROTECT
.SPFUN
.CNTXSW
.GVAL
.PEEK
.PVAL
.POKE
.SCCA
.CRRG
.ELRG
.CRAW
.ELAW
2
3
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:
*
o
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
375
1':36
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
0
0
0/1
0
0
0
0
Oil
0
0
0
1
2
0
0
0
0
1
UNLALL
LOCKW
TLOCK
SNDMSG
GETMSG
WATMSG
SPLFRE
TSXLN
ACTODT
UNLOCK
TTOBLK
TTIBLK
CKTTIE
SETTTO
HIEFF
CKWSHR
SAVSHR
CKACT
SHRFIL
SEND
STRTDJ
STATDJ
ABRTDJ
DCLBRK
MOUNT
DISMNT
INITPA
STRTPA
2 STOPPA
3
0
0
1
2
3
4
5
6
7
10
11
12
13
14
HALTPA
TTYPE
PHYADD
PEEKIO
POKEIO
BISIO
BICIO
MAPIOP
MAPMON
LOKLOW
UNLOKJ
ATTVEC
REL\~C
LOKJOB
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
16
17
20
21
RTURNS
SETPRI
MAPPHY
ATTSVC
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<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
LC
Display special 3-sec format time value from RO
•MCALL
.GLOBL
DSPTI3: MOV
MOV
CLR
DIV
MOV
" ('IT
ft&:>l.i
ADD
MOV
CLR
DIV
MOV
CALL
"TTYOUT
MOV
• TTYOUT
DSPTI3,PRTDE2
Rl,-(SP)
RO,Rl
RO
1120. ,RO
Rl,-(SP)
n'
~.L
Rl,(SP)
RO,Rl
RO
1160. ,RO
Rl,-(SP)
PRTDE2
II' :
(SP)+,RO
/"1.0\ T T
vn. ........
PRTDE2
• TTYOUT
MOV
CALL
MOV
RETURN
• END
II' :
(SP)+,RO
PRTDE2
(SP)+,Rl
E.7 ACRTI3
=Convert
~
;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
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
3$
;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
It
Error messages are consistent with RT-11 usage insofar as possible.
error messages
unique
to
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
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
I
Normal
PRIDEF ~->I
job
1 priorities
I
I
I
-->1
I
1
PRILOW
o
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
I
"'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-
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.3 Linearized : No XMP Toolkit : Adobe XMP Core 4.2.1-c043 52.372728, 2009/01/18-15:56:37 Create Date : 2012:07:12 17:22:19-08:00 Modify Date : 2012:07:12 17:26:57-07:00 Metadata Date : 2012:07:12 17:26:57-07:00 Producer : Adobe Acrobat 9.51 Paper Capture Plug-in Format : application/pdf Document ID : uuid:465517f6-35d4-4e6d-9bda-f1fbefd84f31 Instance ID : uuid:c62e719a-1d64-4f1d-acf9-909bbc94d951 Page Layout : SinglePage Page Mode : UseNone Page Count : 277EXIF Metadata provided by EXIF.tools