Digital PDFs

AA-EZ09A-TC

June 1987

732 pages

Original

27MB

Document:	RSTS/E Programming Manual
Order Number:	AA-EZ09A-TC
Revision:	0
Pages:	732
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsts_e/V09/6_System_Programming/AA-EZ09A-TC_Prog_RSTS_E_V9.4_Programming_Manual_Jun87.pdf

OCR Text

RSTS/E
Programming Manual
Order No. AA-EZ09A-TC
Including AD-EZ09A-T1 ,T2

June 1987
This manual describes RSTS/E special programming techniques. It contains
information on device-dependent features and the use of system function
calls.

OPERATING SYSTEM AND VERSION:

RSTS/E

V9.4

SOFTWARE VERSION:

RSTS/E

V9.4

digital equipment corporation, maynard, massachusetts

The information in this document is subject to change without notice and
should not be construed as a comm:itment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors
that may appear in this document.
The software described in this document is furnished under a license and
may be used or copied only in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on eqUipment that is not supplied by DIGITAL or its affiliated companies.

The postage-paid READER'S COM:MENTS form on the last page of this
document requests your critical evaluation to assist us in preparing future
documentation.

The follOWing are trademarks of DiHital EqUipment Corporation:

mD~DDmDTM
DATATRIEVE
DEC
DECmail
DECmate
DECnet
DECsystem-10
DECSYSTEM-20
DECtape

DEC US
DECwriter
DIBOL
FMS-11
LA
MASS BUS
PDP
P/OS
Professional
Q-bus

Rainbow
ReGIS
RSTS
RSX
RT
UNIBUS
VAX
VMS
VT
Work Processor
WPS-PLUS

CONTENTS
PREFACE

SUMMARY OF TECHNICAL CHANGES

xix

PART I

Devices

CHAPTER 1

System Structure and Disk Operations
System Accounts
. . . .
System Library Account [1,2] .
System Account [0,1] . . . . .
. .
Allocating Disk Storage Space
Bad Block File . . . .
System Overlay File
. .
DECtape Directory File . .
. . . .
Monitor Save Image Library File
.
Error Messages File
..... .
Saving Information After a Crash . .
Run-Time System Files
System Program Resident Library
. . . .
Initialization Code
...... .
Swapping Storage . . . . . . . .
.
System Account [0,1] on Nonsystem Disks
Storage of Accounting Data . . . . . . .
Accounting Data on the System Device .
Accounting Data on Nonsystem Disks . .
privileges . . . . . . . . .
. ....
Multiple privileges
..... .
Classes of System Functions
Account Management Activities
File Access Activities . .
Multiple privilege Masks . . .
Multiple Privileges and Jobs
Job Creation .
Log i n . . . . . . . . .
Logout . .
. . . .
Spawned Jobs .
. . . . . . . . . .
Writing Applications Using Multiple privileges
Writing Programs Protected <124> and <104>
writing Programs Protected <232> . .
Program Access and Privilege Checks
Program Exit.
. ..... .
Multiple privilege System Function Calls
Non-File-Structured Disk Operation . . .
Opening a Disk for Non-File-Structured
Processing . . . . . . . .
Accessing Device Clusters
..... .
iii

.
.

1-1
. 1-2
. 1-2
1-3
1-6
. 1-6
1-6
. 1-7
1-7
1-7
1-8
1-8
1-8

. . 1- 9
1-11
1-12
1-12
1-14
1-14
1-14
1-17

1-17
1-18

1-20
1-21
1-21
1-21
1-22
1-22
1-23
1-23
1-24
1-25
1-26
1-26
1-27

1-27
1-28

Non-Pile-Structured Block Access: MODE 128%
1-31
Access to Bad Block Information: MODE 512%
1-31
Privilege and Access . . . . . . . . .
1-31
Allocating a Disk Unit . . . . .
1-32
Pile-Structured Disk Operation . .
1-32
Reading and Writing Disk Files: MODE 0%
1-34
Updating Disk Files: MODE 1%, MODE 4%+1% .
1-34
RSTS/E File Updating Capabilities
1-·34
F i 1 e Upda te: MODE: 1 % ~ . . . . .
1-·35
Guarded File Update: MODE 4%+1%
1-·36
Appending Data to Disk Files: MODE 2%
. . . . 1-·37
Special Mode for Extending Files: MODE 8%
1-38
Creating a Contiguous File: MODE 16% .
1-·38
Creating a Tentative File: MODE 32%
. . . . . 1-·39
Creating a Contiguous File Conditionally: MODE
64%
. . . . . . . . .
1-·39
..... .
No Supersede: MODE 128%
1-·40
Data Caching: MODES 256%, 2048%
1-·40
Cache Size . . . . . . . . . .
1--41
Caching Control
. . . . . . . . . . .
1-41
Random Mode Data Caching: MODE 256%
1-- 4 2
Sequential Mode Data Caching: MODE 2048% . .
1-- 42
Creating and Placing a File at the End of the
Directory: MODE 1024%
. . ..
. . . . . . 1--43
Creating and Placing a File at the Beginning of
the Directory: MODE 1536%
. . . . 1-- 44
Reading a File During Processing: MODE 4096% .
1-44
Read-Only Access to a File: MODE 8192% . .
1-- 4 5
write Access to a Directory: MODE 16384% .
1--45
Simultaneous Disk Access . . . . . . . . .
1-- 4 5
Disk Optimization
... .
1-- 46
Partial Block Operations on Disk .
1-- 4 7
The Virtual Disk - DVO:
....
1--48
Asynchronous I/O Requests
. . . .
1-- 4 9
Disk Special Function: SPEC%
.....
1-49
RX01/02 Flexible Diskettes
1-- 51
Block Mode: MODE 0%
1-·52
Sector Mode: MODE 16384% .
1--54
Flexible Diskette RECORD Modifiers .
1-55
Deleted Data Marks . . . . . . . . . . . . . .
1-56
Partial Block Operations on Flexible Diskettes 1-56
Flexible Diskette Special Function: SPEC%
1··57
The Null Device - NL:
............ .
1·-59
CHAPTER 2

Magnetic Tape
Overview of Tape Operations
.. . . . . .
File-Structured and Non-File-Structured
Processing . . . . . . . . . .
Magnetic Tape Labels . . . . . . . . . .

. 2-1

•

• .2-2
• 2- 4

Data and Label Handling in File-Structured
Processing. . . . . . . . . . . . .
. 2-4
The File-Structured Magnetic Tape OPEN FOR INPUT . 2-6
Searching for a Label on INPUT . . . . . .
. 2-8
Rewinding the Tape: MODES 2%, 32%, 64% . . . . . 2-8
Example of OPEN FOR INPUT Statement
. 2-9
Reading Data . . . . . . . . . . . . . . . . . . 2-9
The File-Structured Magnetic Tape OPEN FOR OUTPUT 2-10
Searching for a Label on OUTPUT
. . . .
2-11
Writing a Label: MODES 16%, 512% . .
2-12
Extending a File: MODE 128%
... .
2-13
DOS and ANSI Format Labels: MODES 16384%,
24576% . . . . . . . . . . . . . . . .
2-13
Processing DOS Magnetic Tape Files .
2-13
processing ANSI Magnetic Tape Files
2-14
Processing Multivolume ANSI Magnetic Tape Files 2-17
Example of OPEN FOR OUTPUT Statement
2-18
Writing Data and Processing End-of-Tape
2-18
The File-Structured Magnetic Tape OPEN . . .
2-20
The File-Structured Magnetic Tape CLOSE
2-20
The Non-File-Structured Magnetic Tape OPEN .
2-21
The Non-File-Structured Magnetic Tape CLOSE
2-22
The MODE Specification in Non-File-Structured
Processing . . . . . . . . . . . . . . . . .
2-22
2-24
The MAGTAPE Function . . . . . . . . . . .
Off-line (Rewind and Off-line) Function
2-26
2-26
Wri te Tape Mark Function .
.....
Rewind Function
. . . . . . . . .
2-26
Skip Record Function .
2-27
2-27
Backspace Function . .
Set Density and parity Function
2-28
2-29
Tape Status Function . . . . . . .
2-32
Return File Characteristics Function .
2-34
Rewind on CLOSE Function . . . . . . . .
Write End-of-Volume Labels on CLOSE Function.
2-35
Error Condition Acknowledged . . . . . . . . .
2-35
Extended Set Density Function
. . . .
2-36
2-37
Asynchronous I/O Requests
. . . . . . . .
Magnetic Tape Special Function: SPEC%
2-37
Magnetic Tape Error Handling
2-38
Parity (Bad Tape) Error
2-39
Record Length Error
2-39
Offline Error
2-39
Write Lock Error . . . .
. ...... .
2-40
Writing Beyond EOT Error
. . ~ .
2-40
Magnetic Tape Programming Examples . .
2-40
Writing a Magnetic 'Tape File . .
2-40
Reading a Magnetic Tape File . . .
2-41
Reading a Magnetic Tape Non-File-Structured
2-42

CHAPTER 3

Line Printer
Special Character Handling . . . . . . . . . . . . 3-1
Line Printer Control with the MODE Option
. 3-2
Line Printer Control with the FILESIZE Statement. 3-3
Change ESC to $: MODE 16%
.... ..
. . . 3-4
Set NOWRAP for Excess Lines: MODE 32%
3~4
Software Formatting: MODE 512%+N%
. . . 3-5
Enable Hardware Form Feed: MODE 4096%
. . . 3-6
Translate Numeric a to Letter 0: MODE 128% . . . 3-7
Truncate Long Lines: MODE 256% . . . .
. . . 3-7
Translate Lowercase to Uppercase: MODE 1024% . . 3-7
Skip Lines at Perforation: MODE 2048%
. . . 3-8
Suppress Form Feed on CLOSE: MODE 8192%
. . 3-8
Line Printer Control with the RECORD Option
. . . 3-8
Print Over Perforations: RECORD 2% . . . . . . . 3-9
Delay Return Until Output Complete: RECORD 4%
3-10
Clear Buffers Before Returning Control: RECORD
8% • • • • • • • • • • • • • • • _
3--10
Truncate Long Lines: RECORD 32%
3--11
Binary Output: RECORD 4096%
3--11
No Stall Option: RECORD 8192%
3--11
Line Printer Special Function: SPEC% .
3--12
Error Handling . . . . . . . . . . . .
3-·13

CHAPTER 4

Terminals
Conditional Input from a Terminal: RECORD 8192%
. 4-1
No stall Option on Terminal Output: RECORD 8192% . 4-2
Force Interactive Input: RECORD 256% . . . . . . . 4-3
Multiterminal Service on One I/O Channel: RECORD
32767%+1%
... . . . . . . ..
. . . . . . . 4-3
Multiterminal Service Output . . . . . . . . . . 4-4
Multiterminal Service Input
. . . .
. . . 4-5
Terminal Control with the MODE Option
. . . 4-7
Binary Data Output and Input: RECORD 4096% and
MODE 1%
. . . . . . . . . . . . . . . . . . . . 4-7
Suppress Automatic Carriage Return/Line Feed:
MODE 4%
.................. .
4 --10
Echo Control: MODE 8%
........... .
4--11
Prevent CTRL/C Interruption and Hibernation:
MODE 16% . . .
. . . . . . . . . . . . .
4·- 20
Enable Incoming XON/XOFF Processing: MODE 32%
4·-21
Special Use of RUBOUT: MODE 128%
4·- 21
Escape Sequence Mode: MODE 256%
4·-22
Escape Sequences . . . . . . . .
4·-23
VT100- and VT200-Family Escape Sequences .
4·-24
Programming Example
. . . .
4 ·-28
Output Escape Sequences
4·- 29
Input Escape Sequences .
4-29

Transparent Control Character Output: RECORD
16384% and MODE 16384% . . . . . . . . . .
Private Delimiters . . . . . . . . . . .
Characteristics of Private Delimiters
Usage Notes for Private Delimiters
Terminal Special Function: SPEC% . .
Pseudo Keyboa rds . . . . . . . .
Accessing the Pseudo Keyboard
Creating the Controlled Job . . . . .
Pseudo Keyboard I/O
Pseudo Keyboard Input
Pseudo Keyboard Output
Pseudo Keyboard Escape Sequence processing
Programming Example
. . . . . . . . . .
Pseudo Keyboard Special Function: SPEC%
CHAPTER 5

DECtape, Paper Tape, and Card Reader
File-Structured DECtape: Tu56
Non-File-Structured DECtape: TU56
Pape r Tape . . . . . . . . . . . .
Punching with Parity on Paper Tape . .
Parity Checking on Paper Tape
Card Reader
. . . . . . . .
ASCII Mode: MODE 0%
.....
Packed Hollerith Mode: MODE 1% .
Binary Mode: MODE 2% . .
....
Setting Read Modes . . . . . . . . . .

CHAPTER 6

4-33
4-34
4-35
4-36
4-37
4-37
4-40
4-40
4-41
4-41
4-41
4-45
4-45
4-47

.
.

·
·
·
. .
· .
. .
·
· .

5-1
5-2
5-4
5-4
5-4
5-5
5-5
5-6
5-7
5-8

DMC11/DMR11 Interprocessor Link
Using the DMC11/DMRll Interprocessor
Point-to-Point Configurations
. . .
The OPEN Sta tement . .
. . . .
MODE Value . . .
.....
CLUSTERSIZE Value
FILESIZE Value .
RECORDSIZE Value .
Errors . . . . . . . . . .
The GET Statement and RECORD Options
Count and Status Information .
The PUT Statement
.........
The CLOSE Statement
. . . .
Hardware Errors

vii

Link in
. . . . .
. .
.

. 6-1
6-1
6-2

• 6- 2

·
.
.

. 6-2
6-3
· . 6-3
6-3
6-4
6-7
· . 6-8
. 6-8

PART II

System Function Calls and Programming Hints

CHAPTER 7

SYS System Function Calls
SYS System Function Calls
... . . . . .
• • 7- 2
SYS System Function Formats and Codes
. . 7-2
Cancel CTRL/O Effect on Terminal
....
7--18
Enter Tape Mode on Terminal
7--19
Enable Echoing on Terminal
. . . . 7 -- 2 0
Disable Echoing on Terminal
. . . . .
7--21
Enable OOT Submode on Terminal
...... .
7--22
Exi t wi th No Prompt Message
. . . .
7--24
FIP Function Call
. . . . . . . . .
7-25
Get Core Common String
7-26
Put Core Common String
. . . . . 7·-27
Exit and Clear Program
7·-28
Cancel All Type Ahead
7·-30
Return Information on Last Opened File
7-31
Execute eeL Command
7·-34
SYS System Function Calls to FIP (F=6)
7·-36
Building a Parameter String . . . . .
7-37
Unpacking the Returned Data
. . . . .
7·-38
Notation and References Used in SYS Call
Descriptions . . . . . . . . .
7-40
Project-Programmer Number
. . . . . . . . .
7-41
Integer (2-Byte) Numbers . . . . . . . . . .
7-41
Unsigned Integer (2-Byte) Numbers
7-42
Negative Byte Values . . . . . .
7-43
File Name String Scan Format . . . .
7-43
MACRO Mnemonic Cross-References
7-44
Organization of This Section .
7-44
File Name String Scan
. . . . .
7-45
Get Monitor Tables - Part III
7-58
Spooling
..... .
7-61
Snap Shot Dump
7-66
File Utility Functions
7-67
Manipulate File, Pack, and Account Attributes
7-74
Read File Attributes
7-75
write File Attributes
7-77
Read Pack Attributes
7-79
Read Account Attributes
. . . .
7-81
write Account Attributes
7-85
Delete Account Attributes
7-87
Add/Delete CCL Command
7-89
Set Special Run Priority
....... .
7-92
Drop/Regain Temporary Privileges
7-93
Lock/Unlock Job in Memory
7-96
Set Logins
.............. .
7-98
Manipulate Run-Time System, Resident Library,
Dynamic Region . . . . . . . . . . . . . . . . 7-100
viii

Add a Run-Time System
7-100
Remove a Run-Time System
7-104
Unload a Run-Time System
7-106
Add a Resident Library
7-108
Remove a Resident Library . . . .
· 7-112
Unload a Resident Library
. . . .
7-113
Create Dynamic Region
7-114
Associate a Run-Time System with a File
· . . 7-117
Shut Down System
. . . .
· 7-119
Accounting Dump
7-120
Change Date and Time
· 7-122
Change Priority, Run Burst, and Maximum Size
7-124
Get Monitor Tables - Part II
· 7-127
Change File Statistics
· . . 7-129
Hang Up a Dataset
. . .
· 7-132
Get Open Channel Statistics
· 7-134
Enable CTRL/C Trap
7-137
Poke Memory
· 7-140
Broadcast to a Terminal
7-141
Force Input to a Terminal
· . 7-143
Get Monitor Tables - Part I
· . . 7-144
Disable Further Logins
7-147
Enable Further Logins
7-148
Create User Account
· . 7-149
Create User Account (New Format) .
· . 7-149
Create User Account (Old Format)
· 7-154
Delete User Account
7-158
Disk Pack Status .
· . 7-160
Login/Verify Password
7-166
Logout
7-170
At tach . .
· . 7-173
Attach
..
7-174
Reattach
· 7-176
Swap Console
....
· . 7-178
Detach
. .
· 7-180
Change Quota, Password, Expiration Date
7-183
Change Quota (New Format)/Expiration
7-183
Date/Password (Old Format)
Change Quota (Old Format)/Expiration
Date/Password (Old Format) .
. . 7-187
Set Password (New Format)
. 7-189
Kill Job
....
. 7-191
Disable Terminal
7-193
Return Error Message
7-195
Allocate Device/Assign User Logical
. . 7-197
Allocate/Reallocate Device
7-197
Assign User Logical
. .
7-201
Deallocate a Device or Deassign User Logical
7-203
Deallocate All Devices
. . . 7-205
Zero a Device
. . . . . . . . . . . . .
7-206
Read/Read and Reset Accounting Data
. . . 7-210
Directory Lookup . . . . . . . . . . . . . . . 7-217
•

•

• •

•

• • • •

•

' 0

•

• •

•

• • • • •

• •

•

Directory Lookup on Index
. 7-220
Special Magnetic Tape Directory Lookup
. 7-222
Disk Directory Lookup by File Name
. 7-225
Disk Wildcard Directory Lookup
. 7-227
Set Terminal Characteristics . . .
. 7-229
Set Terminal Characteristics - Part I
. 7-230
Set Terminal Characteristics - Part I I .
. 7-242
Enable and Disable Disk Caching
. 7-249
Date and Time Conversion
. 7-253
System Logical Names
. 7-255
Add New Logical Names
. 7-257
Remove Logical Names
. 7-260
Change Disk Logical Name
. 7-262
List Logical Names . . .
. 7-264
Add, Remove, and List System Files
. 7-267
Add System Files
. 7-268
Remove System Files
. 7-271
List System File
. 7-273
Create a Job
. 7-275
Wildcard PPN Lookup
. 7-283
Return Job Status
. . . . .
. 7-285
Set, Clear, or Read Current privileges.
. 7-290
Set/Clear/Read Current Privileges
. 7-290
S tall /U n s tall S y s t E~ m
. . . .
. . 7- 29 2
Third Party Privilege Check
. . . .
. 7-294
Check Access Function
. 7-296
Check File Access Rights . .
. 7-296
Convert Privilege Name to Mask
. 7-298
Convert Privilege Mask to Name .
. 7-300
Open Next Disk File
. 7-302
Set Device Characteristics and System Defaults 7-305
Set Device Characteristics . . . .
. 7-305
Set Line Printer Characteristics . .
. 7-309
Set System Defaults
. 7-312
Load Monitor Overlay Code and Return
Status/Remove Monitor Overlay Code .
· 7-315
The PEEK Function
. . . ..
....
· 7-319
Fixed Locations in Monitor .
· 7-320
Finding the Current PPN
· 7-321
CHAPTER 8

System Calls for Local Interjob Communication
Local Interjob Communication .
Format of the Send/Receive SYS Calls .
Privileges Required for Send/Receive . .
Declare Receiver
Send Local Data Message
Send Local Data Message With Privilege Mask
Receive
....
Remove Receiver
Local Send/Receive Examples

·
·
·
·

.
.
.
.

8-1
8- 2
8-3
8-4
8-13
8-18
8-21
8-31
8-33

Declare Receiver Example .
Send Local Data Examples .
Receive Examples . .
Summary of Data Values . .
CHAPTER 9

System Call for Print/Batch Services
Sending a User Request Packet
Confirming a User Request
Send Use r Reque s t Packe t . . .

CHAPTER 10

8-33
8-34
8-35
8-38

. 9-1
. 9-1
9-2

System programming Hints
Designing a Program to Run by a CCL Command
System Processing of CCL Commands
CCL Precedence Rules
Effect of CCLs on Your Job Area
CCL Syntax and Switches
CCL Command Line Parsing . . " . .
BASIC-PLUS Action
. . . .
Conventions Used in BASIC-PLUS Programs
SLEEP and Conditional SLEEP Statements.

CHAPTER 11

10-1
10-1
10-2
10-3
10-3
10-4
10-6
10-8
10-8

Ethernet Operations
Ethernet Concepts
The Conversation Analogy .
Ethernet and DECnet/E
Ethernet Terms . . . .
Physical Layer . . . .
Channel, Controller, and Data Link Layer.
Protocol Type and Portal .
Counters .
....
Physical Addressing
DECnet/E on Ethernet .
Multicast Addressing .
Ethernet Addresses . .
Commands for Ethernet
OPEN .
Padded and Unpadded Protocols
System Receive Buffers .
CLOSE
GET
PUT
Special Ethernet Functions .
Set New Physical Address .
Enable Multicast Addresses .
Get Circuit Counters and Get Line Counters

·
·
·
·
·
·
·
·
·

11-1
11-2
11-2
11-3
11-3
11-4
11-4
11-4
11-5
11-5
11-5
11-6
11-7
11-8
11-10
11-10
11-11
11-11
11-13
11-15
11-15
11-16
11-16

Transfer Circuit Counters and Transfer Line
Counters

APPENDIX A

Magnetic Tape Label Formats
DOS Magnetic Tape Format
. . . .
DOS Label s
. . . . . . • • • • • •
ANSI Magnetic Tape Format
. . • . . • • •
ANSI Labels
. . . .
• • • • • .
Volume Label
....
• • •
Header 1 Label (HDRl)
. .
Header 2 Label (HDR2)
End-of-File or Volume 1 Label (EOFI or
End-of-File or Volume 2 Label (EOF2 or
Initializing Magnetic Tapes

APPENDIX B

Card Codes

APPENDIX C

Error Messages

. A-I
•

•

• A- 2
• A- 4

•
•

•
.

• A- 5
• A- 6

•

• A-7

EOVl)
EOV2)

. A-8
A-9
A·-ll
A·-12

User Recoverable Errors
. . .
Nonrecoverable Errors
. . . . . . .
BASIC-PLUS-2 Errors
• • • • • • • •
The ? ?Program Lost-Sorry Error
. . . . . .
Checksum Error on a .SAC File
Unrecoverable Disk Error Reading a .BAC File
Incor rect . SAC Fi Ie Size
Unmatched Version Numbers
Software Performance Report Guidelines
APPENDIX D

11-,16

. . c- 5
C-·15
•

C - 21

C-· 23
C-24
C-·25
C-25
C--25
C--25

Radix-50 and ASCII Character Sets
Radix-50 Character Set
ASCII Character Codes

APPENDIX E

Device Handler Index

APPENDIX F

Monitor Directives

APPENDIX G

EMT Logger Send/Receive Calls
EMT Logging and Send/Receive .
Declaring an EMT Logger
. . . .
Receiving an EMT Logger Message
Message Format . . . . . . . .
xii

. 0-1

. 0-4

•

G- 2

•

• G- 2

G-4
. G-6

EMT Root and FIRQB Fields
Message from SHUTUP

. . G-8
. . G-9

INDEX
FIGURES
4-1
4-2
4-3
5-1
5-2
5-3
7-1
7-2
7-1
8-1
A-I
A-2
A-3
A-4
G-1

Input Escape Sequence Processing . . . . . . . .
4-30
Pseudo Keyboard Operations . . . . . . . .. . . .
4-39
PUT statement Actions for Pseudo Keyboard Output 4-43
TU56 DECtape Format
. . . . . . . .
5-3
Packed Hollerith Read Mode . . . . . . . . . . . . 5-7
Binary Read Mode . . . . . . . . . . . . . . . . . 5-8
Integer Representation of Changed Characters
7-39
Reversal of Bytes by SWAP%() Function
7-40
High-Order Bits of CPU Time and KCTs .
. . . 7-216
Summary of Send/Receive Data . . . . .
8-39
DOS-Labeled Magnetic Tape File . . . .
. . . A-2
DOS Magnetic Tape Consisting of 3 Files of 10 Data
Recor.ds Apiece . . . . . . . . . . . . . •
. . A-2
ANSI-Labeled Magnetic Tape File . . . .
. . A-4
ANSI Magnetic Tape Consisting of 3 Files of 10
Data Records Apiece
....
. . . . A-5
EMT Data Packet Layout . . . . . . . . .
. . G-7

TABLES
1-1
1-2
1-3
1-4
1-5
1-6
1-7
1-8
1-9
1-10
2-1

Valid Cluster Size Ranges
. . . . . . . . . . . . 1-4
Swap Times . . . . . . . . . . . . . . . . . .
1-10
Account Information Stored on the System Device
1-13
RSTS/E Privileges
. . ..
1-15
Account Management privileges
. . . .
1-18
RSTS/E File Protection Codes .
1-19
File Access Privileges . . . . .
1-20
Non-File-Structured Disk Default Characteristics 1-28
MODE Specifications for Disk Files . . . .
1-33
1-52
MODE Specifications for Flexible Diskette
Statements and Functions for Accessing Magnetic
Tapes
. . . . . . .
2-2
System Density Values for Magnetic Tape
. . . 2-3
Magnetic Tape OPEN FOR INPUT MODE Values .
. . 2-7
Magnetic Tape OPEN FOR OUTPUT MODE Values
2-11
ANSI Magnetic Tape CLUSTERSIZE Values
2-15
MAGTAPE Function Summary . . .
2-25
Magnetic Tape Status Word
.
2-30
Magnetic Tape File Characteristics Word for ANSI
Format .
2-33
LP11 Characters
. . . . .
3-1
Line Printer OPEN MODE Values
. . . . . . . . 3-3
Additional OPEN MODES with FILESIZE 32767%+1%
. . 3-4
Line Printer RECORD Values . . . . . o .
• • • 3-9
Multiple Terminal RECORD Values for S% . . . . . . 4-6
0

2-2
2-3
2-4
2-5
2-6
2-7
2-8

3-1
3-2
3-3
3~4

4-1

•

• •

•

• • • • •

•

xiii

•

• •

•

4-2
4-3
4-4
4-5
5-1
7-1
7-2
7-3
7-4
7-5
7-6
7-1
7-2
7-9
8-1
8-2
9-1
10-1
A-I
A-2
A-3
A-4
A-5
A-6
B-1
C-1
C-2
C-3
C-4
C-5
C-6
D-1
D-2
E-1
F-1

Summary of MODE Values for Terminals . .
· . 4-7
4-13
Echo Control Mode Character Set
....
ANSI-Compatible Escape Sequences: VT100- and
4-25
VT200-Family Terminals . . . . . . . .
Escape Sequence Terminators
. . . . .
4-32
Specifying Read Modes on Card Reader . .
· 5-9
SYS System Function Calls (by Function Code)
· 7-4
SYS System Function Calls (by Function Name) . • • 7 - 5
FIP SYS Calls (by Subfunction Code)
....
· 7-6
FIP SYS Calls (by Function Name) . .
7-12
File Name String Scan Flag Word 1
.....
7-49
File Name String Scan Flag Word 2
7-51
SYS 14 Legal Byte Value Combinations . .
· 7-215
Internal Speed Values for Terminal Interface
. . 7-234
Lines
. . . . . . . . . .
Monitor Fixed Locations
. . . . . 7-320
RSTS/E Reserved Names
8-10
Sender Selection Summary .
8-30
User Request Data Fields
9-10
STATUS Variable After CCL Entry
. . . .
10-7
. . • • . A- 3
DOS Label Record Bytes .
Volume Label Format
. A-6
Header 1 Label Format
. A-7
Header 2 Label Format
· . A-8
End-of-File or Volume (EOF or EOV) 1 Record
Format . . . . . . . . . . . . . . . . . . . . . A-IO
End-of-File or Volume (EOF or EOV) 2 Record
Format .
. . . .
A-II
Card Reader Codes
. . . . . . . . . . . . .
B-1
Severity Standard in Error Messages
. . . ..
C-3
Special Abbreviations for Error Descriptions
. C-3
Nontrappable Errors in Recoverable Class
C-4
User Recoverable Errors
. . . ..
. . . . . . C-5
Nonrecoverable Errors
. . . . . . . .
C-15
BASIC-PLUS-2 Errors
.. . . . .
C-21
Radix-50 Character positions .
. D-2
ASCII Character Codes
. . . .
. D-4
Handler Index
. . . . . . .
. E-1
Monitor Directives . .
F-l

xiv

Preface
Objectives
This manual describes RSTS/E programming techniques.

It:

Explains how to optimize the use of devices on RSTS/E

Describes system function calls to the RSTS/E monitor

Provides general information and programming hints for the
system programmer

Audience
This manual is for BASIC-PLUS, BASIC-PLUS-2, and MACRO programmers.
It assumes that you know how to program in one of these languages and
are familiar with RSTS/E system concepts and features.
If you program in BASIC-PLUS or BASIC-PLUS-2, this manual contains all
the information you need to use device-dependent features and system
function calls.
If you program in MACRO, however, you will need to
use this manual as a companion to the RSTS/E System Directives Manual.
Document structure
Part I, Devices, contains six chapters.
Each chapter describes
programming techniques for a different type of device:
Chapter I

Describes file-structured and non-file-structured disk
and flexible diskette operations.
It also describes
RSTS/E system files and privileges.

Chapter 2

Describes file-structured and non-file-structured
magnetic tape operations and explains how to process DOSand ANSI-labeled tapes.

Chapter 3

Describes system features for controlling line printers.

Chapter 4

Describes system features for controlling terminals, such
as echo control and multiterminal service.
It also
describes pseudo keyboards.

Chapter 5

Describes DECtape, paper tape, and card readers.

Chapter 6

Describes the DMClI/DMRll interprocessor link.

?art II, System Function Calls and Programming Hints, contains four
~hapters:

:hapter 7

Describes system function calls available to BASIC-PLUS
and BASIC-PLUS-2 programmers. These calls let you
communicate with the RSTS/E monitor, perform special I/O
functions, and set terminal and job characteristics.
Although the call descriptions are tailored for BASIC
programmers, MACRO programmers can consult this chapter
for a detailed description of the corresponding monitor
directives.

:hapter 8

Describes system function calls for local message
send/receive operations. As in Chapter 7, the call
descriptions are tailored for BASIC programmers but are
intended for use by MACRO programmers as well.

:hapter 9

Describes the system function call for a Print/Batch
Services (PBS) request.

:hapter 10

Contains system programming hints. It describes the CCL
facility and explains how the monitor handles the SLEEP
and conditional SLEEP statements.

:hapter 11

Describes Ethernet and the commands for using it.

rhis manual also has seven appendixes:
~ppendix

Describes magnetic tape label formats for DOS and ANSI
tapes and explains how RSTS/E initializes the two types
of tapes.

~ppendix

Lists card codes.

~ppendix

Lists RSTS/E and BASIC-PLUS error messages.

~ppendix

Summarizes the Radix-50 and ASCII character sets.

~ppendix

Lists device handler indexes.

~ppendix

Lists the monitor directives that correspond to the
BASIC-PLUS system function calls.

~ppendix

Describes the use of parameters and other features of the
send/receive calls that are specific to an EMT logging
program.

June 1987

xvi

Related Documents
The RSTS/E System User's Guide describes RSTS/E system concepts, and
explains how to work with files and devices.
The RSTS/E utilities Reference Manual describes the use of RSTS/E
system programs.
The BASIC-PLUS

l~anguage

Manual describes how to program in BASIC-PLUS.

The RSTS/E SystE~m Directives Manual describes monitor directives
available to MACRO programmers.
See the RSTS/E Documentation Directory for more information on RSTS/E
manuals.
Conventions
This manual uses the following conventions:

< >

Angle brackets enclose essential elements of the item being
described.
For example, you must supply an expression in
the statement:
SLEEP <expression>

[ 1

Square brackets indicate an optional element or a choice of
one element among two or more optional elements.
For
example, the CCL DETACH switch has the form:
[<space>l/DET[A[C[Hlll
The required part of the switch is /DET.

CTRL/x

This symbol indicates a control key combination, such as
CTRL/U or CTRL/O.
To enter a control key combination, hold
the CTRL key down while you press the indicated key.

All examples in this manual are written to execute in BASIC-PLUS
EXTEND mode unless otherwise noted.
If you enter them at your
tE~rminal, remember to press the RETURN or LINE FEED key after each
command, statement, or program line.

xvii

Summary of Technical Changes for RSTS/E V9.0
Version 9.0 is a major release of the RSTS/E operating system.
manual contains support for the following new features:

This

Multiple privileges:
to system functions.

A set of privileges now control access

Print/Batch Services (PBS): A new spobling package provides
improved print and batch capability. V9.0 still supports thE
OPSER-based spooling package.

Quota specification: You can specify logged-in, logged-out,
and detached account quotas.
In addition, the system now
performs logged-in quota checking. V9.0 still supports the
old quota format.

Long passwords: You can specify an account password as 14
ASCII characters. V9.0 still supports the old format
password.

Expiration date:

8-bit character support: The system provides transparent
handling of 8-bit characters.

Virtual disk: A logical device that supports the storage of
temporary data within system memory.

Nine character logical names.

New terminal features.

You can specify an account expiration date

RSTS/E V9.0 supports the following new hardware:
PDP-ll/73 and
PDP-ll/84 systems, DHUll/DHVll multiplexer, VT220/240 and LA200
terminals, RD52 disk, RC25 disk, TK25 tape, LN03 laser printer, and
LQP03 printer.
See the RSTS/E v9.0 Release Notes for a complete list
of supported hardware.
RSTS/E V9.0 no longer supports the following hardware: RFll disks,
RS03/RS04 disks, RK05 as a system disk, VT05 and VT50 terminals, TU58
DECtape-II.
See the RSTS/E V9.0 Release Notes for a complete list of
unsupported hardware.

xix

System Function Call Changes
v9.0 has five new SYS system function calls.

expanded functions.

Many existing calls have
The following is a summary:

New System Function Calls
Set/Clear/Read Current Privileges (SYS 28)
This call reads the current privilege mask and selectively sets
and/or clears bits in it.
Third Party Privilege Check (SYS 31)
Server programs such as spoolers use this call to perform
privilege checks on users who request the service.
Check Access Function (SYS 32)
This call performs a variety of privilege checking functions.
It
checks file access rights, converts a privilege mask to names,
and converts privilege names to mask.
Open Next Disk File (SYS 33)
This call opens a disk file or a series of disk files matching a
wildcard specification.
Set Device Characteristics/Set System Defaults (SYS 34)
This call se~s certain device characteristics, line printer
characteristics, and the following system defaults: date, time,
magnetic tape labeling, and magnetic tape density. The call also
loads and removes certain monitor overlay codes.
New Subfunctions of Existing System Function Calls
Send Print/Batch Services Request (Message Send/Receive, SYS 22)
This call allows an application program to issue a request for
print/batch services. It has the same range of capabilities as
the DCL PRINT or SUBMIT commands.
Send Local Data Messages with Privileges (Message Send/Receive,
SYS 22)
This subfunction provides a method for a program to tell another
program about a job's current privileges.
Change Quota/Expiration Date/Password (SYS 8)
This call is restructured to accomodate qu~ta checking and
password changing in both the new and old format.
It also lets
you specify an account expiration date.
Read Pack Attributes, Read/Write/Delete Account Attributes (SYS -25)
These subfunctions expand your ability to manipulate accounting
information.

List Logical Names (SYS 21)
In addition to the new List subfunction, this call now supports
nine-character logical names.
Set Terminal Characteristics - Part II (SYS 16)
This subfunction expands the range of settable terminal
characteristics. The call now supports terminal settings for
S-bit characters, auto-baud, CTRL/C and CTRL/X, terminal
capability flags, separate control characters, and terminal type.
Create Dynamic Region (SYS -IS)
This subfunction creates both named and unnamed dynamic regions
of memory.
Verify Password (SYS 4)
This addition to the Login call allows an application to verify c
password without having to first logout.
Return Job status (SYS 26)
A new subfunction returns information on I&D space as well as the
current privilege mask.
Deleted System Function Calls
Clean a Disk (SYS 2)
The DCL MOUNT command now performs this function.
Declare Default Keyboard Monitor (subfunction of SYS -IS)
In V9.0, DCL is always the system default keyboard monitor.
other System Function Call Changes
All SYS calls that handle quota, password, or privilege checking now
support the V9.0 format. Among the calls affected are SYS calls 0, 5
6, 14, and 24.
There are also minor changes to SYS calls -29, -2S, -26, la, 15, and
17 .

xxi

other Technical Changes
For line printers, new MODE values let you specify a form length up to
255 lines, disable escape sequences, and set NOWRAP. For individual
output steps, new RECORD modifiers let you truncate long lines and
enable binary output. Two new SPEC% functions return page counter and
line position information.
For magnetic tape, a new MAGTAPE function lets you write an
end-of-volume (EOV) tape mark, providing support for multivolume ANSI
tape processing. Another new MAGTAPE function provides support for
error handling in asynchronous I/O requests.
For terminals, you can now use a new MODE value and RECORD modifier to
correctly handle a 256-character set.
In addition, a new RECORD
modifier lets you force program input from a terminal even when the
program is running under the control of a DCL command file.
For pseudo keyboards, a new SPEC% function returns the exit status of
a controlled job.
Summary of Technical Changes for RSTS/E V9.1
Version 9.1 is a mini-release of the RSTS/E V9.0 operating system.
This manual contains support for the following new features:
All references to the primary run-time' system have been changed to the
default keyboard monitor. Specifically, pages 1-3, and 1-8.
TMPPRV privilege description has been added to Table 1-4.
Default Characteristics for the RD53 disk have been added to Table
1 -8 .

System Density Values for the TK50 magnetic tape drive have been added
to Table 2-2.
A new subfunction code has been added to the MAGTAPE and SPEC% calls.
This function can be used to set the density of a tape drive, or to
return density information about a drive. See pages 2-24, 2-25, and
2-36.
Two new subfunction codes have been added to the Disk Pack status SYS
call (FO=3). These functions can be used to load the storage
Allocation Table (SAT) of a disk into memory or unload a SAT from
memory. See pages 7-160 to 7-164.
The data passed and returned for the Set System Defaults Function of
the Set Device Characteristics and System Defaults SYS call (FO=34)
have been changed. See page 7-311.

xxii

october 1985

Summary of Technical Changes for V9.4
Significant changes to the RSTS/E Programming Manual for V9.4 are:
Ethernet has been added.
See Chapter 11 for an overview of Ethernet
and a description of how to use its local area networking features on
RSTS/E.

June 1987

xxiii

PART I
Devices

Chapter 1
System structure and Disk Operations

Disks are file-structured, random access devices.
They are the
fastest, most reliable, and most durable type of peripheral device.
RSTS/E is a disk-based system. During timesharing, some parts of the
monitor and run-time system code are always in memory; other parts are
on the system disk and are loaded into memory only when needed.
The
system disk also stores system programs and user files.
Because the RSTS/E system is built around disks and their
characteristics, this chapter differs from other chapters on
peripheral devices in this manual. Besides describing both
file-structured and non-file-structured disk operations, it also
describe's how RSTS/E system accounts are set up and how RSTS/E handles
privileges.
This chapter also describes flexible diskettes and the
"null device," a software structure available on all RSTS/E systems
for debugging and for creating a buffer without tying up a physical
device.

System Accounts
RSTS/E systems have two accounts that are essential to system
operation: the system library account and the system account. The
system library account, [1,2], stores a library of system programs and
message and control files.
This account must be present on the system
disk.
The system account, [0,1], contains RSTS/E monitor files and
routines that are critical to system operation.
The following sections explain these two accounts in detail.

1-1

System Structure and Disk Operations
System Library Account [1,2]
During system installation, the initialization procedure creates the
system library account [1,2] on the system disk.
The system program
installation procedure populates the account with system programs.
This section briefly describes the contents of account [1,2].
See the
RSTS/E System Installation and Update Guide for a directory listing of
the account.
The system library stores many of the system programs that are
available to general and privileged users.
It also contains text
files used by system programs.
During normal system start-up or automatic crash recovery, the START
option accesses the system library automatically. The console
keyboard is logged in automatically under account [1,2]. Then the
system invokes the START.COM file in account [0,1] as a DCL command
file.
One of the steps in the system start-up procedure runs the
ERRCPY program. Depending on the contents of the start-up command
file, other programs may be started up in account [1,2] as well, or
the system manager may elect to run any of these programs in some
other account.

System Account [0,1]
During system installation, the initialization procedure creates the
system account [0,1] on the system disk. The procedure creates two
files required for all RSTS/E disks and stores them in [0,1]:
the
storage allocation file SATT.SYS and the bad block file BADB.SYS.

1-2

System Structure and Disk Operations
Account [0,1] on the system disk also contains files used for system
operation.
During system installation, the system copies the
necessary files into [0,1].
See the RSTS/E System Installation and
Update Guide for a directory listing of the account.
Some of the most
important files are:
o

INIT.SYS,

the system initialization code

SWAP.SYS, the primary swapping file

CRASH.SYS, the crash dump data file

A file with the file type .SIL, the monitor code

DCL.RTS, the system default keyboard monitor

RTll.RTS, a required auxiliary run-time system

ERR. ERR, the error message text

CSPLIB.LIB,

th~

system program resident library

The following sections describe the RSTS/E system files.

Allocating Disk storage Space
RSTS/E uses the SATT.SYS file to control the allocation and
deallocation of storage space for a disk.
The file maps the entire
space on the disk in a bit map called a Storage Allocation Table
(SAT).
Each bit in a SAT represents either allocated or unallocated
space.
The system sets a bit in the SAT to 1 when that space is
allocated for any purpose.
The system allocates storage space in terms of pack clusters.
Each
bit in the SAT represents one cluster of disk space.
A cluster is a
fixed number of contiguous 512-byte blocks of storage on the disk.
The clustet size defines how many contiguous 512-byte blocks are
contained in the cluster.
RSTS/E defines cluster sizes for disks,
directories, and files.

October 1985

1-3

System Structure and Disk Operations

Table 1-1 presents the types of clusters and related information.
Table 1-1:

Valid Cluster Size Ranges

+ - - - - - - - - - - - + - - - - - - - - - - - - - - + - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - .- - - - +
Cluster
:
I Maximum i
Size
I Minimum Size I
Size
I
When Defined
+- - - - - - - - - - -+- - - - - - - - - - - - - -+- - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

Pack (for
any disk)

Device
Cluster Size
(see Table
1 -8 )

At initialization time with
DSKINT option, or on line
with the DCL INITIALIZE
command.

Directory

Pack Cluster
Size

At creation of the directory
with either the DSKINT
initialization option,
CREATE/ACCOUNT command, or
SYS system function.

File

Pack Cluster
Size

256

At creation of the file with
either an OPEN or OPEN FOR
OUTPUT statement, or the DCL
CREATE or COpy command.
Specify cluster size with the
CLUSTERSIZE option. Note that
when you specify a negative
cluster size, the system uses
either the absolute value of
the argument specified or the
pack cluster size, whichever
is greater.

+ - - - - - - - - - - - + - - - - - - - - - - - - - - + - - - - - - - - - + - - - - - - -:' - - - - - - - - - - - - - - - - - - - - - - - •. +

The system manager specifies the disk cluster size either during di~k
initialization (DSKINT) or on line with a qualifier to the DeL
INITIALIZE command. The pack cluster size defines the minimum number
of contiguous 512-byte blocks that a cluster comprises on a specific
disk; thus, the extent of contiguous space each bit represents in the
SAT. A pack cluster size of 1 means that one 512-byte block of
storage is allocated for each bit set to 1. A pack cluster size of 2
means that two contiguous 512-byte blocks are allocated for each bit
set to 1. The minimum value for a pack cluster size is the device
cluster size for the disk type. Allowable pack cluster sizes are 1,
2, 4, 8, or 16, as long as the pack cluster size is equal to or
greater than the device cluster size of the disk. See table 1-8 for a
list of disk device cluster sizes.
The pack cluster size affects the efficiency of storage space
allocation. A large size improves access time to programs and files
1 -4

System Structure and Disk Operations
but may waste disk space. For example, if the pack cluster size is
16, the system allocates one cluster of 16 contiguous blocks to a
one-block file: fifteen blocks are wasted. A IS-block file also
requires one cluster but only one block is wasted. Thus, the system
manager must choose the pack cluster size that best fits the type of
processing and the access requirements of the local installation.
One processing consideration is the use of data caching on the system
(see the section "Caching Control"). While the pack cluster size is
set during disk initialization and the cache cluster size can be set
and changed during timesharing, the relationship between the two
affects the optimal use of the cache. For example, if the pack
cluster size and file cluster size are both 4 and you specify a cache
cluster size of 8 (see the SET CACHE command in the RSTS/E System
Manager's Guide, or SYS Call 19, Enabling and Disabling Disk Caching),
4 blocks in the cache contain your file's data and 4 may contain
unrelated data. Therefore, if you plan to use data caching on your
system, the pack cluster size that the system manager specifies during
disk initializatiori should be equal to or greater than any cache
cluster size you specify during timesharing.
The User File Directory (UFO) has a defined directory cluster size.
Its minimum value is the pack cluster size. The system manager
specifies the cluster size during account creation. A directory
cluster size must be a power of 2 up to a maximum of 16 and must be
greater than or equal to the pack cluster size. Thus, for a pack
cluster size of 2, the directory cluster size on that device can be 2,
4, 8, or 16.
For a pack cluster size of 8, a directory cluster size
on that device can be 8 or 16.
The directory cluster size limits the size to which a directory can
expand. A directory expands to catalog files and can occupy a maximum
of seven clusters.
The directory cluster size determines how many files a user can create
under one account. The following formula gives the number of user
files (UF) for each allowable directory cluster size (UC). (The
formula assumes that all files are a minimum size between 1 and 7
clusters and have no attributes.)
( 21 7

JC:

UC) .. 1

- - - - - - - - - - - ~ - -

The minimum number of user files is 72 for a UFD cluster size of 1 and
the maximum UF is 1157 for a UFD cluster size of 16. Note that system
performance is maximized when the UFO contains fewer files.

1-5

System structure and Disk Operations
Bad Block File
The bad block file BADB.SYS is the mechanism which the system manager
uses to remove unreliable storage blocks on system and nonsystem disks
from use.
The DSKINT option or the DeL INITIALIZE command creates
BADB.SYS in account [0,1]. DSKINT can thoroughly check each block on
a disk for reliability.
If any block on a disk pack or cartridge is
faulty, DSKINT allocates the pack cluster in which the bad block
resides to the file BADB.SYS.
The bad block file, therefore, contains
no data but merely removes from use those clusters found to contain
unreliable blocks.
As a disk is exercised during time-sharing operations, more unreliable
portions of a disk may be uncovered.
By checking the data errors
recorded in the system error log, the system manager can isoYate these
bad blocks.
Through the REFRESH initialization option (see the RSTS/E
Installation and Update Guide), the m.anager can add newly discovered
bad blocks to BADB.SYS. Once the system allocates a bad block to
BADB.SYS, it cannot be deallocated.
Note that MSCP disk controllers provide their own built-in handling of
bad disk blocks.
This is transparent to the system; the disk always
appears to have the full number of good data blocks.
This applies to
RA80, RA8l, RA60, RC25, RD5l, and RD52 disks.

System Overlay File
The OVR.SYS file contains certain monitor code that resides on disk,
not in memory.
The system loads this code into memory on demand and
overlays a certain part of the monitor.
The monitor Save Image
Library (SIL) normally contains the overlay code.
The system achieves
optimum efficiency when this code resides on the center of a
fast-access disk.
If the system disk is not a fast-access disk, the system manager can
use the DCL INSTALL/OVERLAY FILE commi~nd to create a separate,
contiguous file that contains the ovelrlay code.
The manager can
optimally position this file on a fast disk. At the start of
time-sharing operations, the system manager can add the overlay file
to the system. Thereafter, the system accesses the copy of the
overlay code in the optimally positioned file rather than in the
original code in the SIL.

DECtape Directory File
The BUFF.SYS file is used in DECtape processing. When you open a file
on DECtape, the system writes the directory of the DECtape to the file
BUFF.SYS.
The BUFF.SYS file requires three 5l2-byte blocks for each
1-6

System Structure and Disk Operations
DECtape drive on the system.
Any updates to the DEC tape directory
during processing cause the system to manipulate the copy in BUFF.SYS.
This technique eliminates the need for continuous winding and
rewinding of DECtape.
The copy'of the DECtape directory in BUFF.SYS
is written back to the DEC tape when the last file open on the DECtape
unit is closed or any output file is closed.
During system installation, the system automatically creates the
BUFF.SYS file if it is needed.

Monitor Save Image Library File
All monitor code, whether permanently resident in memory or loadable
as overlays, resides in account [0,1] on the system disk.
This file
is structured in Save Image Library format and must have a file type
of .SIL.
Multiple monitor files can reside on the system disk but the
system only installs one such file at a time.
The system marks the
installed monitor file as nondeletable and loads the file from disk tc
memory when time-sharing operations begin.

Error Messages File
The ERR. ERR file contains the system error messages.
DIGITAL
distributes ERR. ERR with each RSTS/E system.
ERR.ERR must exist in
account [0,1] on the system disk.
The DCL INSTALL/ERROR FILE command allows the system manager to create
a separate contiguous-file and position it on any disk~
The standard
name for this file is ERR.SYS.
The system achieves optimum efficiencl
when this code resides on a fast-access disk.
Ai the start of
time-sharing operations, the system manager can add this separate file
to the error message file on the system.
The monitor copies the
contents of the established default error me~sage file to this
optimally positioned file.
Thereafter, the system accesses the copy
in the optimally positioned file instead of the established default
file.

Saving Information After a Crash
The system uses the file CRASH.SYS to save a dump of the read/write
area of the monitor and the extended buffer pool (XBUF) at the time of
a system crash.
INIT.SYS automatically creates the CRASH.SYS file on the system disk
during system start-up.
If INIT.SYS cannot find sufficient contiguou~

1-7

System Structure and Disk Operations
disk space to create CRASH.SYS,
starting the system.

it prints a warning message before

The size of CRASH.SYS depends on the size of the monitor read/write
area and XBUF.
The monitor read/write area size varies according to
the hardware and software configuration but is between 48 and 96
blocks.
To estimate the number of blocks needed for XBUF, use the
formula:
Size of XBUF in K words

* 4

Run-Time System Files
The account [0,1] on the system disk must contain at least one file
with a file type of .RTS.
This file is the default keyboard monitor
and is automatically loaded into memory by the monitor at the start of
timesharing.
The default keyboard monitor must reside on the system
disk because that disk is the only one logically mounted at system
start-up time.
DCL.RTS is the system default keyboard monitor.
In addition, RTll.RTS
is also required on the system.
The system manager can add auxiliary
run-time systems (other files with .RTS file types in account [0,1]).
All run-time system files (as well as resident library files) must
occupy contiguous space on disk.
This condition allows a run-time
system (or resident library) to be loaded into memory as fast as
possible.

System Program Resident Library
Account [0,1] on the system disk contains the resident library
CSP~IB.LIB.
Because nearly all system programs use CSPLIB.LIB, this
resident library is required on the system.
CSPLIB.LIB is
automatically installed during system start up.
CSPLIB.LIB is a floating resident library.
See the system function
call, Manipulate Run-Time System, Resident Library, Dynamic Region
(SYS -18), for more information about floating libraries.

Initialization Code
The INIT.SYS file contains the system initialization code.
INIT.SYS
resides in account [0,1] on the system disk.
When the system disk is

1-8

October 1985

System Structure and Disk Operations
bootstrapped, a secondary bootstrap loads the main part of the
initialization code into memory.
The initialization code is a large,
stand-alone program that performs consistency checks on system
software and hardware.
It allows the system manager to:
o

Initialize and format disks

Install patches

Enable and disable device controllers and units

Manipulate files in account [0,1] on both system and nonsystem disks

Change some default timesharing characteristics

An important feature of the initialization code is that it allows bad
blocks to be added to the bad block file BADB.SYS in account [0,1].
At the start of timesharing, the RSTS/E monitor code replaces the
initialization code in memory.

Swapping Storage
Nonresident jobs on RSTS/E are kept in predefined areas on disk called
swap files.
RSrrS/E provides four distinct swap files:
SWAP. SYS,
Swap file number 2, named SWAP.SYS,
SWAPO.SY'S, SWAP1.SYS, SWAP3.SYS.
is required on all systems; the other files are optional. SWAP.SYS
must reside on the system disk.
During system installation, INIT.SYS automatically creates the
SWAP.SYS file in account [0,1] at a size large enough for 1 job.
Later on in the system installation, the system manager can create a
SWAPl.SY'S file at a size large enough to hold the rest of the jobs on
the system. Or, the system manager can later create multiple swap
files (up to a total of 4) to provide swap space for all jobs. The
system manager can locate some or all of these files on disks other
than the! system disk, preferably on high speed disks that do not
contain frequently accessed files.
See the RSTS/E System Installation
and Updatte Guide for details.
RSTS/E uses swap files in a predefined way.
For example, the system
stores at highly interactive job that must be removed from memory in
the lowest numbered file available. The system searches for an empty
space starting at the lowest numbered active file.
On the other hand,
a job with infrequent activity is stored in the highest numbered file
available.
Such relatively inactive jobs are those that sleep until
an event occurs. The system error logging program ERRCPY is an
example of a relatively inactive job.

1-9

System Structure and Disk Operations
A swap file can be either a file or an entire device, for example, a
high speed disk.
The best device to use for swap files on a system
depends on the types of devices available and the amount of data
swapped.
Table 1-2 shows the approximate amount of time (in seconds) needed to
transfer different size job images for various types of disks. Actual
times will be longer if the disk is accessed in other ways, for
example to read user file data.
Table 1-2:

Swap Times

+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Job Size ( i:n words)
Disk
+- - - - - - - - - - - - - -+- - - - - - -+- - - - - - -+- - - - - - -+- - - - - - -+- - - - - --+
32K
64K
2SK
SK
16K
I
I
+- - - - - - - - - - - - - -+- - - - - - -+- - - - - - -+- - - - - - -+- - - - - - -+- - - - - --+

I
I RL01/02
I
I RK05
I

I
I
I
I

.19

.32

.43

.78

.15

.17

.29

.16

.24

.27

.50

.06

.08

.11

.12

.20

RPOS/06

.06

.08

.11

.12

.20

RM02

.06

.08

.11

.12

.20

RM03/0S

.05

.06

.08

.09

.14

RM80

.05

.06

.08

.09

.14

RA60

.06

.07

.08

.11

RA80

.05

.06

.08

.09

.14

RA81

.04

.05

.06

.07

.10

RC25

.04

.06

.07

.08

.13

RDS1

.11

.14

.17

.19

.29

.10

.13

.1S

.16

.25

.38

RK06/07

.08

.11

RP02/03

.10

RP04

.14
.15
.26
.08
.10
RD52
+- - - - - - - - - - - - - -+- - - - - - -+- - - - - - -+- - - - - - -+- - - - - - -+- - - - - --+

1-10

System Structure and Disk Operations
Calculate the swap times for each disk by using the formula:
Job size
Swap time

* 2

= Avg access time + -------------Transfer speed

where:
Average access time

measured in seconds, is defined as the sum of
the average seek time and the average latency
time.

Transf:er speed

is measured in kilo-bytes per second (KB/S).

Job size

is measured in kilo-words (KW).

See the appropriate Peripherals Handbook for the average access time
and transfer speed of each disk.
When a file is used as a swap file, the system manager can further
reduce the swap time by using the /POSITION switch on the file
specification to position the file in the middle of the disk.
This
minimiz€!s the time required for positioning the read/write heads.
On
systems with multiple disks, the system manager can position two files
on separate drives to take advantage of overlapped seeks.
A swap f:ile other than file 2 (SWAP.SYS) is dynamic.
The system
manager adds files at the start of timesharing to allow the maximum
number of jobs to run.
During timesharing, a swap file can be removed
and added again as another device or file.
Dynamic addition and
removal of swap files allows timesharing to continue when hardware
problems; on a device being used for swapping would normally require
discontinuing system operation.

System Account [0,1] on Nonsystem Disks
The system account [0,1] on a nonsystem disk initially contains two
required files:
SATT.SYS and BADB.SYS.
The DSKINT initialization
option or the DCL INSTALL FILE command similarly creates these files
for nonsystem disks as for the system disk. Account [0,1] on a
nonsyst€'m disk, either public or private, can contain other optional
system files.
The REFRESH initialization option manipulates system files in account
[0,1] on a nonsystem disk as well as on the system disk.
The
following DCL commands perform the same operations:
the /ERROR FILE,
/SWAP_FILE, and /OVERLAY_FILE qualifiers of the INSTALL and REMOVE
commands; the SET FILE/[NO]DELETABLE command.
See the RST5/E System
Managers Guide for more information about these commands.

1-11

System Structure and Disk Operations
Both the REFRESH option and OCL commands can create and position
contiguous files (such as a swap file or the overlay file) on a
nonsystem disk. They can also mark files in account [0,1] as
nondeletable. Note that only REFRESH can add blocks to the BAOB.SYS
file.
Nonsystem disks can also contain auxiliary run-time system
files.

storage of Accounting Data
This section describes how accounting data is stored on system and
nonsystem disks.
It describes:
o

Accounting data on the system device.

Accounting data on nonsystem disks.

Accounting Data on the System Device
Project-programmer numbers (PPN) and passwords control access to the
RSTS/E system. The system manager, or anyone who has sufficient
privilege (GACNT for group, WACNT for all), creates a new account by
using the CREATE/ACCOUNT command (see the RSTS/E System Manager's
Guide).
The manager enters the PPN and password for the new account,
along with other information, to allow a user access to system
facilities.
The new account information is stored on the system device. Ouring
account creation, the system manager has the option to preextend and
position the UFO (see SYS Call 0, Crec~te User Account). By default,
the system preallocates one cluster for the UFO. The UFO is related
directly to the user's account and contains information about the
files created under that account number.
The system disk structure contains in:Eormation about all UFOs
(accounts) on the system. When a user tries to gain access to the
RSTS/E system by giving an account and password, the system program
LOGIN checks whether the PPN and pass~~ord given match one stored on
disk.
If so, the system allows access.
Besides the LOGIN program, other systf~m commands and programs also
access the account information.
For f~xample, the SHOW ACCOUNT command
references the accumulated system accounting information. The system
manager uses the SET/ACCOUNT command to reset this accounting data or
change certain parameters such as disk quota. The LOGOUT system
program references the disk quota information.

1-12

System Structure and Disk Operations
Table 1-3 lists the account information that the system keeps for each
account.
Table 1·3:

Account Information Stored on the System Device

+ ~ - - - - - - - - - - - - - ., - - - _ .... - - - - - - - - - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - • • - - - - • - - +

I
....

Type
g

•

Description
-

Identification

Accumulated Usage

Disk Storage and
System Resource
Usage

....

I
Explanation
I
+ - - - - - - - - - - - - •• - - - - - - - - - - - - - +

Project-programmer I The PPN has the format
number (account)
I [n,m] where nand m are
I decimal numbers that
identify the user.
Password

6 letters and/or digits
(old format).
14 ASCII characters (new
format) .

Central Processor
Unit (CPU) time
(Run Time)

Processor time the
account has used to date,
in tenths of a second.

Connect Time
(log-in time)

Number of minutes the
user has been connected
to the system through a
terminal or remote line.

Kilo-core-ticks
(KCTs)

Memory usage factor. One
KCT is the usage of lK
words of memory for one
tenth of a second.

Device time

Number of minutes of
peripheral device time
the account has used.

Quota

Number of 512-byte blocks
the user is allowed to
retain. Types of quotas
include logged-out,
logged- in, job,
detached-job, message,
and RIB.

I
I

I
I
I

+g - - - - - - - - - - - - - ~ - _. -+- - - - - - - - - - - - - - - ~ - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - --+

Using SYS system function calls, users who have GACNT or WACNT
privilege can write programs that access the accounting information.
See the description of the system function calls in Chapter 7.

1-13

System structure and Disk Operations
Accounting Data on Nonsystem Disks
The system disk exists in what is called the public structure. The
system manager can add additional disks to the public structure or add
them as private disks. Disks other than the system disk are called
nonsystem disks. Each disk added to the system also contains its own
directory structure, which is created when the system manager
initializes the disk. A nonsystem disk initially contains UFD
information for account [0,1] as well as storage information.
Accounts on public disks are treated differently from accounts on
private disks. RSTS/E allocates space for a user's file in the public
structure on the disk that has the most free space. If the user's
account does not yet exist on the disk with the most free space, the
account number is added dynamically to that disk and a UFD is created
for the user on that disk. A user cannot create a file on a private
disk unless the account number already exists on that disk. The
system manager or a sufficiently priv:Lleged user grants access to a
private disk by entering the account information on the desired disk
with the CREATE/ACCOUNT command.

Privileges
The system manager must have a way to prevent general access to
activities that can damage the system.. In previous releases, RSTS/E
allowed the system manager to divide llsers into privileged and
nonprivileged groups. Nonprivileged llsers were restricted to
activities that could cause no system damage. Privileged users had
access to all activities.
The V9.0 multiple privileges feature qives the system manager finer
control over access to activities. Now the system manager can limit
the user's access to just those activities suitable to the user's job.
Multiple privileges gives the system manager a tool to enhance system
performance, security, and more easily delegate certain operations.

Multiple Privileges
The multiple privilege feature groups similar system functions into
sets and defines a privilege to control access to each set of
functions. A group of 34 privileges qovern the entire set of RSTS/E
system functions. The privileges givE!n to an account determine the
range of functions available to the user. Some privileges apply to
very specific functions; others control functions within broader
classes of system use.

1-14

System Structure and Disk Operations
Table 1-4 summarizes the RSTS/E privileges.
Table 1-4:

RSTS/E Privileges

+- - - - - - .. - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
i Privilege i
Description
+- - - - - _ .. - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

DATES

Change system date/time and file dates.

DEVICE

Access restricted devices.

EXQTA

Exceed quotas or memory maximum. (Not usually given to
users; used by privileged programs.)

GACNT

Perform accounting operations on accounts in the
user's group.

GREAD

Read or execute any file in the user's group,
regardless of protection code.

GWRITE

Write, delete, create, or rename any file in the
user's group, regardless of protection code.

HWCFG

Set hardware configuration parameters; for example,
set terminal characteristics.

HWCTL

Control devices; for example, disable a device or hang
up a dial-up line.

INSTAL

Install run-time systems, swap files,
libraries.

JOBCTL

Manipulate other jobs; for example, detach or kill a
job.

MOUNT

Mount or dismount disks other than NOSHARE.

PBSCTL

control Print/Batch Services (PBS); for example, turn
servers on or off, and change printer forms.

RDMEM

PEEK at memory. (Not usually given to users; used by
privileged programs.)

RDNFS

Read a disk non-file-structured.

SEND

Broadcast to terminals and send messages to restricted
receivers.

SETPAS

Change your own password.

1-15

and resident

System structure and Disk Operations
Table 1·4:

RSTS/E Privileges (Cont.)

+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - _ .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I Privilege

Description

+ - - - - - - - - - - -+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+
I

SHUTUP

Shut down the system.

SWCFG

Set software configuration parameters; for example,
installation name.

SWCTL

Control software components; for example, turn DECnet
on and off.

SYSIO

Perform restricted I/O operations; fOI example, gain
write access to files in account [0,*], or set the
privilege bit on executable files.

SYSMOD

Perform functions that could easily modify the system;
for example, poke memory.

TMPPRV

Set privilege bit (128) in the protection code of an
executable program.

TUNE

Control system tuning parameters; for example, caching
or job priority.

USERl-8

Available for customer applications. Not used by
RSTS/E.

WACNT

Perform accounting operations on any account.

WREAD

Read or execute any file regardless of protection
code.

WRTNFS

Read/write a disk non-file-structured.

WWRITE

Write, delete, create, or rename any file regardless
of protection code. (For [0,*] accounts, SYSIO is
required in addition to WWRITE.)
+ - - - - - - - - - - -+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+

1-16

October 1985

System Structure and Disk Operations
Classes of System Functions
Most system activities fall into two general classes:
o

Account Management Activities

File Access Activities

The next two sections describe these two classes of system activities
and discuss the privileges that control them.

Account Management Activities
user accesses a computer through an account.
The individual account
is a member of the "group," which contains all accounts with the same
project number.
The group, in turn, is a subset of the "world," which
contains all accounts on the system. Account management activities
include creating and deleting accounts, as well as changing passwords,
disk quotas, and expiration dates.

The following privileges control account management:
GACNT

Group Account Management -- Grants account management
privileges within the user's group.

WACNT

World Account Management -- Grants account management
privileges for all accounts.

SETPAS

Set Password -- Allows changing one's own password.

Table 1-5 outlines the account management activities and the
privileges required to perform them.

1-17

System Structure and Disk Operations
Table 1-5:

Account Management Privileges

+ - - - - - - - - - - - - - - - - - - + - - - - - - - - - - - • • • • - - - + - - - - - - - - - ••••' • • • - + - - - - - - - - - - - - +
I
Activity
I
Self
I
Group
I
World
I
+- - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - -+- - - - - - - ~ - - - - .. - - - -+- - - - - - - - - - --+

Create/delete
account

GACNT or WACNT
(for nonsystem
disks *)

GACNT or WACNT

WACNT

set account
parameters

GACNT or WACNT

WACNT

set password

SETPAS or
GACNT or WACNT

GACNT or WACNT

WACNT

Read account
data/parameters

Always allowed,
except password

GACNT or WACNT

WACNT

Read/reset
account data

GACNT or WACNT

WACNT

+ - - - - - - - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - .' + - - - - - - - - - - - - - - - - - + - - - - - - - - - - - - +
I * Create does not apply to the system disk; you cannot delete
I
your own account.
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - .' - - - - - - - - - - - - - • - - • - - - - - - - - - - - - - - +

File Access Activities
Users routinely access files.
The USE!r creates some files, which
reside in the individual's account. Other files reSide in the
accounts of other users or in system accounts.
File access activities
include:
creating, deleting, renamin9, reading, writing, and
executing files.
Both the protection code of the file clnd the privileges granted to the
user can affect whether the system grclnts or denies file access.
On a system with equal privileges granted to all us~rs, protection
codes control the operations that a user can perform on a file.
The
SET PROTECTION command (or the /PROTECTION switch in the RSTS/E file
specification) passes a value to the s;ystem that sets bits in the
protection code byte. When a bit is set, the the system prohibits
activity named by that bit.

1-18

System Structure and Disk Operations
Table 1-6 shows the value and meaning of each protection code bit.
Table 1-6:

RSTS/E File Protection Codes

If Executable Bit Not Set

128

Priv

:e:xe (0)

Write
World

Read
World

Write
Group

Read
Group

Write
Owner

Reaa
Owne

Exe
World

Read,
Write
Group

Exe
Group

Read,
Write
Owner

If Executable Bit Set

128
I
I

Priv

64
I

:e:xe

(1)

Read,
Write
World

certain privileges also govern file access activities.
Some
privileges override protection codes completely.
The following
privileges grant a user the right to perform certain file access
activities, regardless of protection codes:
GREAD

Group Read -- Read the data in any file within the group.
Also, execute a program, if the executable bit is set.

WREAD

World Read -- Read the data in any file in on the system.
Also, execute a program, if the executable bit is set.

GWRITE

Group Write -- Modify, extend, or delete the data in any
file within the group.

WWRITE

World Write -- Modify, extend, or delete the data in any
file on the system.

1-19

Exe
Owne

System Structure and Disk Operations
Table 1-7 summarizes the file access activities and the rules that
govern file access.
Table 1-7:

File Access Privileges

+- - - - - - - - - - - - - - -+- - - - - - _. - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - .. +

Function

Self

Group

World

+- - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - .. +

Read

Yes, if protection
code permits, or
GREAD or WREAD

GREAD or WREAD
or protection
code permit

WREAD or
protection code
permit

Write/Delete

Yes, if protection
code permits, or
GWRITE or WWRITE

GWRITE or WWRITE
or protection
code permit

WWRITE or
protection code
permit (and
SYSIO if account
[0,*])

Execute

Yes, if protection
code permits, or
GREAD or WREAD

GREAD or WREAD
or protection
code permit

WREAD or
protection code
permit

Create/Rename
/Zero

Yes

GWRITE or WWRITE

WWRITE (and
SYSIO if account
[0,*])

+- - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - -+- -~ - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - .. +

Multiple Privilege Masks
The system manager assigns a certain set of privileges to each
account.
The system stores this set of privileges in privilege masks.
A privilege mask is a set of flag bits with one bit corresponding to
each pr i vi lege. When a flag bi t i s scet:, the use r acqui res the
corresponding privilege.
For each active job, RSTS/E keeps three masks:
o

Authorized mask -- The se~ of privileges that the system
manager gives to the account.
You can use the SHOW
ACCOUNT/FULL command to list the set of privileges available
to your account.

Current mask -- The set of privileges now in effect for the
job.
The system always references this ma~k when it performs
a privilege check.
You can raise or lower your privileges
(up to your authorized limit) with the Set/Clear/Read Current
privileges SYS Call (SYS 28), or the DCL

1-20

System Structure and Disk Operations
SET JOB/PRIVILEGE command.
You can list your current set of
privileges with the SHOW JOB/PRIVILEGE command.
o

Saved mask -- The saved record of the current privileges when
a job gains temporary privileges (see the section "Temporary
Privileges").

When a user attempts to perform an activity that is restricted by one
or more privileges, the system performs a privilege check. This check
examines the current mask to determine if the requesting job has all
the privileges required to perform the activity.
If the requesting
job has insufficient privilege to perform the activity, the system
returns one of the following errors:
?Protection violation (ERR=lO)
?Illegal SYS() usage (ERR=18)

Multiple Privileges and Jobs
The following sections describe how the monitor handles privilege
information during the life of a job. They describe:
o

Job creation

Logout

Spawned jobs

Job Crealtion
At job creation, the monitor initializes both the current mask and the
authorized mask, giving them all privileges except SYSMOD. This
applies to all newly created jobs with the exception of those created
by SYS 24, Create a Job (see Chapter 7).

Login
When a job logs in, the Login SYS call (SYS 4) looks up the authorized
mask in the account attributes.
It copies this mask into the saved
and authorized masks, ORs it into the current mask, and sets the job
status to indicate the job has temporary privileges in effect.

1-21

System Structure and Disk Operations
If a program logs in, it now has all the privileges it originally had,
plus possibly some new ones. When a program exits, the user has all
authorized privileges enabled.
A user who logs in may not want all hi.s authorized privileges to be
active at login. In that case the user can employ ~ LOGIN.COM file to
initially drop some privileges.

Logout
When a job logs out, the monitor clears the group-related privileges
GACNT, GREAD, and GWRITE in all three privilege masks. This is done
because the job is currently running with PPN = 0, effectively putting
it in group zero. The monitor drops 9rouP privileges because the
intent of these privileges is to allow access to the user's group, not
group zero.
Apart from losing group privileges, a job neither gains nor loses any
privileges as a result of logging out. Note that the Logout SYS call
(SYS 5) performs a self-kill except when the job cutrently has WACNT
privilege.

Spawned Jobs
The Create A Job SYS call (SYS 24) creates a spawned job. For jobs
spawned logged-in, the monitor usually gives the spawned job the same
set of authorized and current privileges as the account it logs in to.
This is done before the program, if any, is run. If the program is a
privileged program, the usual additional privilege processing takes
place (see the section "Running a Privileged Program").
As an option, the caller of the Create a Job SYS call can specify that
the created job have fewer privileges.
Jobs spawned logged-out are given the same privileges as the job
issuing the spawn function.
Spawning a job logged-in to an account other than the caller's
requires accounting (GACNT/WACNT) privilege. Logged-out spawn
requi res WACNT privilege. Spawn there,fore allows users wi th
accounting privilege to create jobs that have some other account's
privileges, possibly more than their own.

1-22

System Structure and Disk Operations
Writing Applications Using Multiple Privileges
When you write applications in RSTS/E V9.0, you must correctly use the
multiple privileges features. The following sections explain how to
best use multiple privileges within your program. They describe:
o

Writing programs protected <124> and <104>

Writing programs protected <232> (privileged programs)

Performing access and privilege checks

Program exit

Multiple privilege system function calls

Writing Programs Protected <124> and <104>
Before V9.0, only a "privileged" user could run an executable program
residing in a [1,*] account with a protection code of <124> (60+64).
These programs could safely assume that anyone able to run the program
had all the privileges required to perform all of the program's steps
(an exception to this was POKE, which required the program to be run
from account [1,1]).
In V9.0, the concept of "privileged" user is no longer all inclusive.
If you have WREAD (world read) privilege, you can execute any program
protected <124> on the system, even though you may not have all the
privileges required for the program to work properly.
It may be acceptable to simply leave programs protected <124> as is.
These programs will succeed or fail depending on the privileges of the
user who executes them. However, some <124> programs may require the
user to have several different privileges in order to succeed. If a
user has some but not all of the privileges required, the program may
partly succeed; it can complete some of its tasks but may fail at
others. This may be undesirable, especially where failing part way
through a multistep operation could leave a file or other data
corrupted.
The solution to this problem is for such programs to do a privilege
check at the beginning of the program, to ensure that the user has all
the required privileges before proceeding. You can use the Check
Access Function SYS call (SYS 32) to determine if a user has a
particular privilege. See Chapter 7 for a complete description of
this call.
Once you add a privilege check to <124> programs, you can safely lower
the program's protection code to <104> (40+64). Protection code <104>
1-23

System Structure and Disk Operations
allows any user on the system to run the program.
The up-front
privilege check terminates the program if its user does not have the
proper privileges.
For example, suppose a program requirE!S HWCFG, SWCFG, and TUNE
privilege in order to work properly.
The program should initially
perform a check to ensure that any USE!r running the program has all
three privileges before continuing.
If the user has HWCFG and SWCFG
privilege, but lacks TUNE privilege, then the program issues an error
message and terminates.
If you still want program privacy, you can leave the program's
protection code <124>, allowing only users with WREAD (or GREAD if the
program resides in the same group as the user) to access the program
or display it in a DIRECTORY listing.

Writing Programs Protected <232>
In some cases, you may not want to require users to have all the
privileges that a program needs to work properly.
In such cases, you
can give a program temporary privilege by setting the privilege bit
(128) in its protection code. When a privileged program is executed,
it receives all privileges except SYSMOD.
Any program with a protection code of <192> or higher is privileged.
The normal protection code associated with privileged executable
programs is <232>, granting execute a~cess to all, but restricting
read/write access to the owner.
For security purposes, the system places two restrictions on
privileged programs:
o

You needs SYSIO privilege to designate a program as
privileged.

A privileged program that resides on a disk mounted /NOSHARE
will not have temporary privileges when run.
This
restriction prevents an outsider from acquiring privileges by
bringing in a privileged program on a private pack.
To be
able to mount a disk /SHARE, you need MOUNT privilege.

Privileged programs may be available to all users (for example,
SYSTAT), or they may be restricted by including a check for some
privilege at the beginning. Using the previous example, if you make a
<104> program privileged (protection code <232», it can check at the
beginning for only TUNE privilege.
The program proceeds for those
users with TUNE privilege, even though the program itself requires
HWCFG and SWCFG privilege as well.
Be sure to drop temporary
privilege before doing the privilege check, so that the user's
1-24

System Structure and Disk Operations

privileges are checked, not the program's (see the next section).
SHUTUP :is an example of such a privileged program.
It requires a
variety of privileges to remove jobs, remove runtime systems, dismount
disks, and issue the Shut Down System SYS call (SYS -16). Instead of
requiring a user to have all of these privileges, SHUTUP is installed
as a privileged program (protection code <232» and only requires the
user to have SHUTUP privilege in order to perform all of its steps.
SHUTUP lceturns the error message ?SHUTUP privilege required if a user
without SHUTUP privilege attempts to run it.
Whenever such a program drops temporary privilege, the program's
privileqes are saved and the user's own privileges are re-enabled.
When temporary privileges are regained, the two sets of privileges are
exchanged again.
If temporary privileges are permanently dropped,
then the user's privileges are re-enabled and the program's temporary
privileqes are lost.
You should be careful when you create privileged programs.- In
general" a privileged program should execute most of its functions
with temporary privileges dropped, raising them just before executing
a privileged operation and then dropping them immediately following
the operation.
Pay special attention to BASIC-PLUS error handling under such
conditions.
If a privileged operation causes an error, control may be
passed to an error handler with temporary privileges still enabled.
Be sure that there are no paths in the program where temporary
privileqes may be accidentally left enabled.

Program Access and Privilege Checks

When designing programs, avoid duplicating the monitor's access and
privilege checks in your program. When performing an operation that
depends on the user's privileges and/or a file'S protection code, a
program should simply perform the operation (with temporary privileges
disabled if a privileged program), and let the monitor enforce its
access and privilege rules. Duplicating such checks in the program
itself is inefficient and may lead to incompatibility in the future.
For example, suppose you want to design a privileged program that
creates a file in a user-specified location (device and account).
Rather than having the program determine if the user is authorized to
create the file in the location specified, simply drop temporary
privileges and create the file.
If the user lacks the required
privileges, the monitor blocks the file's creation and returns an
error.
The program can then report the error and reprompt the user
for a new file location. Note that this program will continue to
function properly, even if nSTS/E access and privilege rules change in
the future.
1-25

System Structure and Disk Operations

Several system function calls allow programs to more easily establish
access rights and privileges. DIGITAL recommends you use these calls
where possible. See the section "Multiple Privilege System Function
Calls" for a summary of the calls.

Program Exit

Whenever a program exits or chains to another progiam, the monitor
performs the following privilege-related cleanup:
o

If temporary privileges are in effect, the monitor cancels
them.

The monitor cancels any third-party privilege check currently
in effect.
(See the Third-Party Privilege Check SYS call,
SYS 31)

If the job is currently logged-out and does not have WACNT
privilege, and the program exits, the monitor kills the job.
Chaining among programs is possible without restriction when
logged out, but other operations that exit the current
program result in a self-kill. Note that the Logout SYS call
(SYS 5) performs a self-kill immediately unless the caller
has the WACNT privilege.

If the program being exited is a privileged program, the
monitor clears the job's memory and sets the job size to the
minimum size for the job's default keyboard monitor.

All open files are closed.

Multiple Privilege System Function Calls

Five SYS calls control multiple privileges:
o

Drop/Regain Temporary Privileges (SYS -21) -- This call
allows a program to selectively use temporary privileges.

Set/Clear/Read Current Privileges (SYS 28); - - This call reads
the current mask and selectively sets and/or clears bits in
it. The SET JOB/PRIVILEGE and SHOW JOB/PRIVILEGE commands
use this call.

Third-Party Privilege Check (SYS 31) -- This call enables or
disables third-party privilege checking. Server programs
such as spoolers use this call to perform privilege checks
for users who request the service.
1-26

October 1985

System Structure and Disk Operations
o

Check Access Function (SYS 32) -- This call performs a
variety of privilege checking functions.
It checks file
access rights, converts a privilege mask to names, and
converts privilege names to mask.

Send Privileges (SYS 22)
This new subfunction of the
Send/Receive call permits a program to pass a job's current
privileges to another program.

See Chapter 7 for a detailed description of each SYS call.

Non-File-Structured Disk Operation
Non-file-structured disk operation lets sufficiently privileged users
(RDNFS, WRTNFS privileges) access specific blocks on a disk.
You can process non-RSTS/E file-structured disks under RSTSjE and use
an entire disk as a single file.
Non-file-structured processing also
allows system pr6grams, such as SAVE/RESTORE (see the RSTS/E System
Manager's Guide), to optimally process file-structured disks.

Note
The data you look at when reading a disk as a
non-file-structured device is internal to RSTSjE and
is subject to change at any time.

Opening a Disk for Non-File-Structured processing
If you have RDNFS privilege, you can open a disk in
non-file-structured mode.
To access a disk for non-file-s~ructured
processing, specify only a device designator in the OPEN statement.
Only the OPEN and OPEN FOR INPUT statements are valid.
The following
two sample statements are equivalent:
100 OPEN "DLl::" FOR INPUT AS FILE 1%
100 OPEN

"DLl~"

AS FILE 1%

Both allow reading and writing of physical blocks on RL unit 1.
An
OPEN FOR OUTPUT statement results in the error ?Disk pack is not
mounted (ERR=21).
For example:
100 OPEN "DL1:" FOR OUTPUT AS FILE 1%

1-27

System Structure and Disk Operations

You need RDNFS privilege to read a disk that is open in
non-file-structured mode. You need WRTNFS privilege to write to the
disk.
To prevent other programs from accessing a non-file-structured
disk, a job with HWCTL privilege can assign the device.

Accessing Device Clusters

Before writing a program that accesses a disk as a non-file-structured
device, you need to understand the terms logical block, device
cluster, device cluster size, device cluster number, and default
buffer size:
o

A logical block is 512 bytes of disk data.

Logical blocks

are numbered starting at O.
a

A group of contiguous logical blocks forms a device cluster.

The device cluster size is the number of logical blocks in
the group.
The device cluster size is fixed for each type of
disk; it can be 1, 2, 4, 8, or 16. The device cluster size
represents the minimum amount of information (the minimum
number of logical blocks) that can be retrieved or written in
one non-file-structured I/O operation. Device clusters are
numbered from 0 to the maximum shown in Table 1-8.
a

The default buffer size for all disk units when open in
non-file-structured cluster mode is the device cluster size
multiplied by 512 bytes.

Table 1-8 lists the default disk characteristics.
Table 1-8:

Non-File-Structured Disk DejEault Characteristics

+ - - - - - - - - - + - - - - - - - - - + - - - - - - - - - + - - - - - - .. - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - +

Minimum
Device
Cluster
Size

Default
Buffer
Size
(Bytes)

512

800

799

512

4800

4799

512

4800 per unit;
2 units/drive

4799 per unit;
2 units/drive

Maximum Device

Total Size

I
Device
Cluster Number
(in Blocks)
+ - - - - - - - - - + - - - - - - - - - + - - - - - - - - - + - - - - - - ., - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - +

I Rx50
I
I RK05

RK05F

RL01

512

10220

10219

RL02

512

20460

20459

1-28

October 1985

System Structure and Disk Operations
Table 1-18:

Non-File-Structured Disk Default Characteristics (Cont.)

+- - - - - - - - -+- _ .. - - - - - -+- - - - - - - - -+- - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - --+

Device

Minimum I Default
I Device I Buffer
I Cluster I
Size
i
Size
(Bytes)

I
I
i

Total Size
(in Blocks)

Maximum Device
Cluster Number

+- - - '. - - - - -+- _ .. - - - - - -+- - - - - - - - -+- - - - - - - - - - - - - - - - - -+- - - - - _ .. - - - - - - - - - --+

RD51

I
I

RD52
RC25

512

21600

21599

512

60480

60479

I
I

512

50902 per unit
2 units/spindle

50901 per unit
2 units/spindle

I
I

RK06

512

27104

27103

RK07

I
I

512

53768

53767

RP02

I
I

1024

40000

19999

1024

80000

39999

2048

138668

34666

Rf102/0 3 I

2048

131648

32911

RP04/05

I
I

2048

171796

42948

RM80

I
I

2048

242575

60643

RM05

I
I

4096

500352

62543

RP06

4096

340664

42582

RA60

4096

400175

50021

RA80

2048 .

237208

59301

RA81

8192

891056

55697

Virtual
disk *

512

4 * #K words
allocated

Varies with size

I
RP03
RD53

I
. I
I
I

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

I
The virtual disk is
created from
+I ___ device
.. __________
u

not a physical device. It is a logical
memory.

________________________________________

••

___________

After you open a disk for non-file-structured processing, use the
RECORD or BLOCK option in GET and PUT statements to read and write a
october 1985

1-29

System Structure and Disk Operations
specific cluster on the disk.
The number you specify designates a
device cluster number.
Thus, on an RK05, BLOCK 4100 refers to device
cluster number 4100 on the disk, because the device cluster size for
an RK05 is 1.
On an RP03, BLOCK 4100 refers to device cluster number
4100, which contains logical blocks 8200 and 8201 because its device
cluster size is 2.
In this case, the program accesses both logical
blocks.
The following example reads the last two blocks of an RP03:
100 OPEN "DP1:" AS FILE 1%,
\ GET #1%, BLOCK 39999.
After the program opens the disk, the GET statement reads device
cluster 39999, which contains the last two blocks of the disk.
The system can access device cluster 0 only immediately after an OPEN
statement.
The GET or PUT statement that accesses device cluster 0
must either specify BLOCK 0 or omit the BLOCK option.
Once the disk
has been accessed, omitting the BLOCK option or specifying BLOCK 0 in
a GET or PUT statement accesses the next sequential device cluster.
Note that you can use COUNT to read a partial block (see the section
"Partial Block Operations on Disk"), however the system positions
itself at the start of the next cluster following the operation.
After you perform I/O to the disk, the only way you can access device
cluster 0 is by closing the disk and reopening it for
non-file-structured access.
This statement reads the first block of
an RK05:
100 OPEN "DKl:" AS FILE 1%
\ GET #1%, BLOCK O.
caution
On a RSTS/E file-structured disk, logical block 0
contains the bootstrap.
The remaining blocks, if any,
in device cluster 0 contain no data.
Writing to
device cluster 0 on a RSTS/E file-structured disk
destroys the bootstrap.
If the program attempts to read or write beyond the end of the disk,
the ?End of file on device (ERR=ll) error occurs.
You can improve total throughput by specifying a large buffer size.
This permits a single disk transfer to read a large quantity of data.
To change the buffer size, include the RECORDSIZE option in the OPEN
statement.
The RECORDSIZE specified should be an integral multiple of 512 times
,the device cluster size.
For example, the following statement opens

1-30

System Structure and Disk Operations

the RK05 disk on unit 1 for non-file-structured processing and sets
the buffer size to 2048 bytes:
100 OPEN

"DKl~"

AS FILE 1%, RECORDSIZE 2048%

See the BASIC-Pl~US Language Manual for a description of the RECORDSIZE
option in OPEN statements.

Non-File-Structured Block Access: MODE 128%

Specify MODE 128% in a non-file-structured OPEN statement to access
logical disk blocks instead of device clusters. MODE 128% lets you
perform read/write operations on individual disk blocks.
To access blocks on the disk, specify MODE 128% in the OPEN statement
and use the BLOCK option in the GET or PUT statement. The BLOCK
option accepts a floating-point argument that represents the desired
block (where block 1 is the first block on the disk, the pack label).
See the BASIC-PLUS Language Manual for a description of the BLOCK
option in GET and PUT statements.

Access to Bad Block Information: MODE 512%

MODE 512% in a non-file-structured OPEN statement allows a program to
read beyond the last writable portion of a disk. The DCL INITIALIZE
command uses this mode to read the factory bad block file, which is
located beyond the last writable portion of the disk.
MODE 512% also suppresses errors normally logged by the system error
logger.
The system sends these errors to your program if you declare
the program as a local receiver with object type code 64% (see Chapter
8).

Note that this mode is reserved for use by the disk initialization
program and is not intended for general use.

Privilege and Access

You do not need to logically mount a disk that is being processed in
non-file-structured mode. After you insert the disk into its drive,
you can read or write to it if you have the appropriate privilege
(RDNFS,1WRTNFS).
If you only have RDNFS privilege, you can read the
disk regardless of the number of users accessing it, but if you
attempt to write on the disk while another user is accessing it, a
?Protection violation error occurs.

1-31

System Structure and Disk Operations
If the disk is logically mounted, you have only read access while
doing non-file-structured processing, unless you have both WRTNFS and
SYSMOD privilege.
By testing bits 9 and 10 of the BASIC-PLUS variable STATUS, the user
program can determine what accesses it has.
See the BASIC-PLUS
Language Manual for a description of the STATUS variable.

Allocating a Disk Unit
You can allocate a dismounted disk unit to your current job if you
have the HWCTL privilege. This action prevents access by other users
to the drive when you perform non-file-structured operations on a
volume mounted in the drive.
When a.dismounted disk is allocated, the system limits access to the
drive. The drive cannot be logically mounted.
If the job to which
the drive is allocated has the necessary privileges, it has both read
and write access to the disk. Other users who have the RDNFS or
WRTNFS privilege can read the disk in non-file-structured mode but
cannot write on the disk.
Allocating the disk unit can be useful when performing I/O.
If you
need to CLOSE and reopen and GET or PUT block 0, you do not lose
ownership of the disk while it is closed.
The output of the SHOW DISK command shows an allocated drive as
non-file-structured (NFS) and private (Pri). For example, the
following portion of a SHOW DISK command output shows that disk DMl is
assigned.
Disk Structure:
Dsk Open
Size
DMl
1
DRI
45 131648
DR2
0 242576
DR3
8 500352
DR4
0 242572
DR5
0 500352

Free
30052
33040
56296
17528
76152

22%
13%
11%
7%
15%

Clu
1
4
8
8
4
8

Err
0
0
0
0
0
0

Name

Level

A
R
W
M
H

1 .2
1 .1
1.2
1.1
1 .1

Comments
Pri, R-O,
Pub, DLW,
Pri, R-O,
Pri, DLW,
Pri, DLW,
Pri, R-O,

NF'S
LDX
DLW
LOX
LOX
DLW

File-structured Disk Operation
In file-struct~red disk operation, data is organized in files.
The
system manager uses the DSKINT option during system, initialization or
the DCL INITIALIZE command to set up a skeletal file structure on a
RSTS/E disk.
During timesharing, you can create files with the CREATE
command, a text editor such as EDT, or the OPEN and OPEN FOR OUTPUT

1-32

October

198~

System Structure and Disk Operations

statements.
See the BASIC-PLUS Language Manual for a complete
discussion of BASIC-PLUS I/O methods.
You can open disk files in one of several modes. The following
sections describe these modes; Table 1-9 summarizes them.

Table 1-9:

MODE Specifications for Disk Files

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

MODE

Meaning

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

I
I

I
Normal read/write

I
I

UPDATE mode

APPEND to file

Guarded UPDATE (4%+1%)

Special extend

16%

Creat.e contiguous file

32%

Creat.e tentative file

64%

Create contiguous file conditionally

128%

No supersede

256%

Random data caching (requires TUNE privilege)

I
I

I
I
I
I
I
I

II
I
I

I
I
I
I
I
I
I
I
I

512%

Creat.e file -- Place at beginning of directory (with
1024%)

1024%

Create file -- place at end of directory

I
I

2048%

Sequential data caching (wit.h 256%)

I
I

4096%

Read normally regardless

8192%

OPEN file read only

16384%

Write UFD (requires WRTNFS privilege)

I
I
I
I

+- - - - - - - -+- - - - - - - - - - ~ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

The general form of the OPEN statement with the MODE option is:
100 OPEN "FILE.DAT" AS FILE N%, MODE M%

1-33

System structure and Disk Operations

where N% is the internal I/O channel number and M% is the mode in
which the file FILE."DAT is to be opened.
Note that if a nonprivileged job attempts to open a file in a mode
that requires privilege, the system ignores that particular mode
value. Table 1-9 lists the disk file MODE specifications.

Reading and Writing Disk Files: MODE 0%

Specify MODE 0% or omit the MODE option to open a disk file for normal
reading and writing (the system default).
In default mode, an OPEN
FOR INPUT statement opens an existing file for read and write access
(if the protection code of the file permits it). OPEN FOR OUTPUT
deletes an existing file and creates a new file with the same name.
An OPEN statement without an INPUT or OUTPUT specification attempts to
perform an OPEN FOR INPUT operation.
If this fails, the system
creates a new file.
OPEN, OPEN FOR INPUT, and OPEN FOR OUTPUT statements control only the
actions the system performs when it opens the disk file.
See the
BASIC-PLUS Language Manual for a description of these statements.

Updating Disk Files: MODE 1'%, MODE 4%+1%

In certain applications (for example, inventory updating) several
users may need read and write access to a single master file.
In such
cases, it is time consuming to continually close and reopen the file
to obtain and relinquish write access.
For this reason, RSTS/E
provides an update option that gives several users write access to a
file while guarding against simultaneous writing of the same data.
The following sections describe the capabilities RSTS/E provides and
those that are available through BASIC-PLUS.

RSTS/E File Updating Capabilities

In file updating operations, RSTS/E allows locks to be applied on
blocks in a file. A single lock can apply to a single block or to a
range of blocks.
The blocks within the range of a single lock must be
logically sequential; they need not be physically clustered. Because
RSTS/E permits multiple locks at the same time on the same file,
logically nonsequential blocks within a file can be updated in the
same time period.

1-34

System Structure and Disk Operations
The general form of the OPEN statement with the MODE option is:
100 OPEN "FILE.DAT" AS FILE N%, MODE M%
where N% is the internal I/O channel number and M% is the mode in
which the file FILE.DAT is to be opened.
Note that if a nonprivileged job attempts to open a file in a mode
that requires privilege, the system ignores that particular mode
value.
Table 1-9 lists the disk file MODE specifications.
Table 1-9:

MODE Specifications for Disk Files

+- - - - - - - -+- - - '. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
MODE
Meaning
+- - - - - _.' -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Normal read/write
UPDATE mode
APPEND to file
55.5

Guarded UPDATE (4%+1%)

8 c!,.10

Special extend

16 ~5

Create contiguous file
Create tentative file
Create contiguous file conditionally
No supersede
Random data caching (requires TUNE privilege)
Create file -- Place at beginning of directory (with
1024%)

1024~%

Create file -- Place at end of directory

2048%

Sequential data caching (with 256%)

4096%

Read normally regardless

8192%

OPEN file read only

16384%

write UFn (requires WRTNFS privilege)

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

1-33

System structure and Disk Operations
Reading and Writing Disk Files: MODE 0%
Specify MODE 0% or omit the MODE option to open a disk file for normal
reading and writing (the system default).
In default mode, an OPEN
FOR INPUT statement opens an existing file for read and write access
(if the protection code of the file permits it). OPEN FOR OUTPUT
deletes an existing file and creates a new file witn the same name.
An OPEN statement without an INPUT or OUTPUT specification attempts to
perform an OPEN FOR INPUT operation.
If this fails:, the system
creates a new file.
OPEN, OPEN FOR INPUT, and OPEN FOR OUTPUT statements control only the
actions the system performs when it opens the disk file.
See the
BASIC-PLUS Language Manual for a description of these statements.

Updating Disk Files: MODE 1%, MODE 4%+1%
In certain applications (for example, inventory updating) several
users may need read and write access to a single master file.
In such
cases, it is time consuming to continually close and reopen the file
to obtain and relinquish write access.
For this reason, RSTS/E
provides an update option that gives several users Write access to a
file while guarding against simultaneous writing of the same data.
The following sections describe the capabilities RSTS/E provides and
those that are available through BASIC-PLUS.

RSTS/E File Updating Capabilities
In file updating operations, RSTS/E allows locks to be applied on
blocks in a file. A single lock can apply to a sin~le block or to a
range of blocks.
The blocks within the range of a single lock must be
logically sequential; they need not be physically clustered.
Because
RSTS/E permits multiple locks at the same time on the same file,
logically nonsequential blocks within a file can be updated in the
same time period.

1-34

System Structure and Disk Operations
File update: MODE 1%
Use MODE: 1% in the OPEN statement to open a file for update.
example:

For

100 OPEN 'MASTER.DAT' AS FILE 1%, MODE 1%
This statement opens MASTER. OAT for update on channel 1 and creates a
5l2-byte buffer in your job space.
After a program opens a file for update, the system allows the program
to access data simultaneously with other programs but enforces certain
safeguards. When a program performs any read operation on the file,
RSTS/E puts the block accessed in a locked state. An attempt by
another program to access any data in that locked block results in the
error ?Disk block is interlocked (ERR=19). This error signals that
the data required is being accessed on another channel in the current
program or by another program and is perhaps being updated.
The proqram accessing the data makes the data available to another
program by unlocking the block. Several ways exist for a program to
unlock a locked block. The program can:.
o

Perform any write operation on the file.

Execute the UNLOCK statement on the channel where the file is
open.
The UNLOCK statement has the form:
UNLOCK <expression>
where expression is the internal channel number of the file
that is opened for update.

Read another block.
retrieved block.)

(However, this action locks the newly

Execute a CLOSE statement on the file.
(Executing an END or
CHAIN statement or executing the last statement of the
program implicitly closes all files.)

Additionally, the system unlocks a block when the program encounters
an error while accessing the file.
You cannot open a file simultaneously in both normal and update mode.
An attempt to perform an open in one mode when the file is currently
open in the other mode generates the error ?Protection violation
(ERR=lO).
The same error occurs if the protection code of the file
prohibits read and write access.
Even if a file is open in update mode, a program can still gain read
1-35

System Structure and Disk Operations
access to the file.
It can open the j:ile with MODE 4096% (see the
section "Reading a File During Processing: MODE 4096%"). This mode
allows normal read access but not write access, regardless of whether
the file is open for update.
BASIC-PLUS allows a program to lock sE~veral logically consecutive
blocks during a GET operation.
The number of blocks is established by
the RECORDSIZE option.
For example:
100 OPEN 'MASTER.DAT' AS FILE 1%, RECORDSIZE 1024%, MODE 1%
The RECORDSIZE 1024% option causes BASIC-PLUS to create a 1024-byte
buffer.
Therefore, a GET operation on channell retrieves 2 blocks
and puts both blocks together in the locked state.
RSTS/E allows up
to 31 blocks in the buffer to be locked in this manner and allows up
to seven locks on the file (see the section "Disk Special Function:
SPEC%"). Note that the same rules for a single locked block apply for
the range of locked blocks.
You can open a file in UPDATE mode (1% or 5%) and extend it beyond the
current end-of-file (EOF).
To extend the file, follow these steps:
1.

OPEN the file in UPDATE mode.

GET block 1 (the first block of the file).

Use the SPEC% function (see the section "Disk Special
Function: SPEC%") to place an explicit lock on block 1.

Extend the file to the desired length beyond the current EOF
with PUT statements.

Unlock block 1 (see the section "Disk Special Function:
SPEC%").

The extended blocks are now available to users of the file.

Guarded File update: MODE 4%+1%
Guarded file update in the OPEN statement provides the same update
processing as MODE 1% with one more processing feature.
The program
can write a block or range of blocks only after it has read and locked
the data.
If your program attempts to write data that is not
currently locked, the result is a ?Protection violation error
(ERR=10).
This feature prevents a program from updating data that it
has not accessed.
Note that you must use MODE 4% and 1% to gain
special update; MODE 4% alone is equivalent to MODE 0%.

1-36

System Structure and Disk Operations

You can open a file in UPDATE mode and extend it beyond the current
EOF.
See the previous section for a description of the extend
procedure.

Appendin.g Data to Disk Files: MODE 2%

Use MODE 2% in the OPEN statement to write data to a new block
following the current EOF in a disk file.
Do not use the OPEN FOR
OUTPUT statement, because it deletes the existing file.
Specify MODE
2% only with block I/O files.
For example:
100 OPEN "DATA.DAT" FOR INPUT AS FILE 1%, MODE 2%
The system opens the file DATA.DAT under the current account on the
system disk. The next output operation creates a new block and
appends it to the last block in the file that contains data. Any fill
charactE~rs in the previous last block of the file remain when the
system appends the new last block. A PUT statement that the system
later e~=ecutes on the file need not specify a BLOCK number. When the
PUT statement does not include the BLOCK option, the system writes the
next sequential block.
The following sample program illustrates append mode by showing its
use in a classroom environment. Each student enters experimental data
into a class data file.
The complete class data file can then be
input t() another program to produce a class curve for the experiment.
100

400
500
600
700
800

DIM X(10%), X$(10%)
\OPEN "SCIENC.EXP" AS FILE 1%, MODE 2%
\IF (STATUS AND 1024%) THEN
PRINT "WRITE ACCESS NOT GRANTED."
\PRINT "TRY AGAIN IN A FEW MINUTES."
\GOTO 800
FIELD #1%, 8%*1% AS B$, 8% AS X$(I%)
FOR 1%=1% TO 10%
PRINT "YOUR VALUES FOR X ARE";
\MAT INPUT X
LSET X$(I%)=CVTF$(X(I%))
FOR 1%=1% TO 10%
PUT #1%
\PRINT "THANK YOU"
CLOSE 1%
\END

Note that in certain applications, you may want to append records to a
file on one channel and read the appended records on another channel.
The most current file size information is available to all channels on
which a file is open.

1-37

System Structure and Disk Operations
Special Mode for EKtending Files: MODE 8%
Use MODE 8% in the OPEN, OPEN FOR INPUT, or OPEN FOR OUTPUT statement
to force RSTS/E to update a file's size data and retrieval pointers on
the disk during extend operations.
In normal processing, RSTS/E
maintains a file's size data in memory.
RSTS/E does not update this
size on disk until it allocates a new cluster to the file.
By
specifying MODE 8%, you force RSTS/E to update the on-disk file size
as well as the retrieval pointers for each allocated cluster for every
block added to the file.
For example:
10 OPEN 'DATA.DAT' AS FILE 1%, MODE 8% + N%
where the value N% can be any other disk MODE option.
creates the file if it does not exist.

The system

Extending a disk file using MODE 8% increases the processing overhead
because the system must access the disk more times for every block
added.
The extra overhead is warranted for applications where the
system must correctly preserve a file's size in the event of a system
crash or power failure.

Creating a Contiguous File: MODE 16%
Use MODE 16% with the FILESIZE option in the OPEN FOR OUTPUT statement
to create a contiguous file on disk.
Contiguous means that the
clusters allocated to the file are physically adjacent.
For example:
10 OPEN 'DATA.l' FOR OUTPUT AS FILE 1%, FILESIZE 12%, MODE 16%
You can use other options with MODE 16% to specify the buffer size
(RECORDSIZE) and the file cluster size (CLUSTERSIZE).
You must use the FILESIZE option with MODE 16%.
It preextends the
to its maximum length, thereby telling the system how much
contiguous space is required.
If sufficient contig~ous space is not
available, the system generates the error ?No room for user on device
(ERR=4). Note that you can specify MODE 64% (see the section
"Creating a Contiguous File Conditionally: MODE 64%°) to create a
contiguous file conditionally. The file is made contiguous if
possible; otherwise, it is made noncontiguous and no error is
returned.

~ile

processing a contiguous file greatly reduces overhead because it
minimizes di rectory accesses and movement of read/wri te heads.
Fil,es
for run-time systems and swapping must be contiguous because the
monitor accesses these files independe~ntly of the normal file
processor. However, you cannot extend a contiguous file. An attempt
to extend a contiguous file generates the error ?Protection violation
(ERR=lO).
1-38

System Structure and Disk Operations
Creating a Tentative File: MODE 32%
Use MODE: 32% in the OPEN FOR OUTPUT statement to create a file that
does not. become permanent until it is closed with the CLOSE statement.
If a file of the same name currently exists, the system does not
supersede it until you close the tentative file.
When you create a tentative file, the system searches for an existing
file of the same name.
If you do not specify an explicit disk name,
the system searches the public structure.
If the system finds a file
of the same name, and its protection code does not allow deletion, you
receive the error ?Protection violation (ERR=lO).
If the system finds
a file of the same name, and it can be deleted, it is left intact (not
deleted) until a CLOSE on the tentative file is executed.
A successful OPEN st.atement causes an entry for the tentative file to
be made in the directory.
The entry marks the tentative file for
deletion.
If the system crashes or the job resets the channel (with a
negative~ channel number in the CLOSE statement) before closing the
file, the tentative file is deleted.
Note that tentative file
directory entries appear only on a directory listing that contains
files marked for deletion.
When you close a tentative file, the system again searches for a file
of the same name.
If such a file is found and it can be deleted, the
system deletes it and makes the tent.ative file permanent.
If a file
of the same name is found and its protection code does not allow
deletion, the error ?Protection violation (ERR=lO) occurs. However,
the system closes the tentative file and renames it to:
TM?nnn.TMP
where:
?

is an alphabetic indication of the file's channel (A=O, B=l,
C=2, and so on).

nnn

is the job number.

Note that this operation can cause multiple copies of this name to
exist in a directory.

Creating a Contiguous File Conditionally: MODE 64%
Use MODE 64% in the OPEN FOR OUTPUT statement to create a
conditionally contiguous file.
MODE 64% causes the monitor to create
a contiguous file based on the following conditions:
o

If there is enough contiguous space available on the disk to
contain the file, the monitor creates a contiguous file.
1-39

System Structure and Disk Operations
o

If there is not enough contiguous space on the disk to
contain the file, the monitor creates a noncontiguous file.
If the monitor can create the file, it does not return an
error.

Note that the monitor ignores MODE 64% if MODE 16% is also set for the
file (see the section "Creating a Contiguous File: MODE 16%").

No Supersede: MODE 128%
Use MODE 128% in the OPEN FOR OUTPUT statement to create a file that
will not supersede an existing file of the same name. MODE 128%
notifies the monitor that, if a file of the same name currently
exists, the existing file should not be deleted.
Instead, the system
returns the error ?Name or account now exists (ERR=16).

Data Caching: MODES 256%, 2048%
When your job executes a read request, the monitor performs a disk
access and transfers the requested data from the disk to the your
job's I/O buffer. On systems with many jobs that use large amounts of
data, the resulting large number of disk accesses can slow response
time.
You can reduce the number of data transfers from disk through
data caching.
When you enable caching, the monitor stores the most recently read
(accessed) data blocks in an area of memory called the cache, which is
part of XBUF.
If your job requests a data block that is present in
the cache, the monitor copies the requested data directly from the
cache into the job's I/O buffer and thus avoids a physical disk
access.
Data caching is most useful for read operations because it can
minimize disk transfers.
In a write operation that modifies existing
data, the data is updated on disk and in the cache, but no new data is
installed in the cache.
The system manager installs caching on the system and optionally sets
its parameters during system start-up" When cachin9 is enabled, the
monitor examines the cache for all data transfer requests that are
directed to the disk driver.
If the requested data is in the cache, a
read operation occurs without placing a load on the disk driver.
The monitor constantly updates the cache so that it contains the most
recently requested data by adding data clusters or replacing data
clusters (if the cache is full).
The monitor schedules a job's data
transfers into the cache based on the time since last access.

1-40

System Structure and Disk Operations
A data cluster currently in the cache is eligible for replacement if
it:
o

Is the data with the longest time since last access

Has been in the cache for more than the minimum residency
established by the system manager (the cache replacement
timer, set with the SET CACHE command).

Cache Size
The amount of data that can be in the cache at any given time depends
on the cache cluster size, which can be 1, 2, 4, or 8 blocks.
In many
cases, the cache cluster size determines the number of read requests
that can be resolved in the cache before a disk access is required.
For example, when the cache cluster size is 8 blocks, a read operation
that installs data in the cache causes the installation of 8
physically contiguous blocks (including the requested blocks).
The system manager sets the cache cluster size during system start-up
or with the Enable Disk Caching SYS call (SYS 19).
For optimum
performance, the cache cluster size should equal the pack cluster size
set during disk initialization.
If that is not possible, then the
cache cluster size should be smaller than the pack cluster size.
The
monitor allocates cache space from XBUF (see the section
"Enable/Disable Disk Caching," in Chapter 7).

Caching Control
If you have the TUNE privilege, you can enable or disable caching and
determine the size of the cache by using the Enable Disk Cache SYS
call (SYS 19) or the SET CACHE command (see the RSTS/E System
Manager's Guide).
In addition, if you have TUNE privilege, you can
specify caching for a file on a system where caching is enabled.
You can cache a file in either random or sequential mode.
Random mode
is the default; DIGITAL recommends it for files that are accessed
randomly, such as RMS indexed files.
Sequential mode caching is
designed for files that are accessed sequentially.
If you are not
sure in advance how a file will be accessed, you should specify random
mode caching ..

1-41

System Structure and Disk Operations
To specify caching for a file, you can either:
o

Mark its UFD entry with the File utility Functions SYS call
(SYS -26) or the SET FILE command

Specify MODE 256% or MODE 2048% in the OPEN statement

Both methods let you specify either random or sequential mode caching.
The best way to specify caching for a file depends on its use.
If you
are creating a file for use in a specific program, use the following
MODE values to specify caching when you open the file.
However, if
you are creating a file for general use, it is better to mark the
file's UFD entry with the File utility Functions SYS call (SYS -26) or
the SET FILE command.
The use of caching MODE values requires TUNE
privilege.
However, a file whose UFD is marked for caching is cached
on OPEN, regardless of the user's privilege, as long as caching is
enabled on the system.

Random Mode Data Caching: MODE 256%
Use MODE 256% in the OPEN statement to cache data transfers to and
from a file in random mode.
MODE 256~~ has effect only if data caching
is enabled on the system (see the section "Enable/Disable Disk
Caching", in Chapter 7).
When a read on a randomly cached file occurs, the monitor examines the
cache to determine if the requested data item is present.
If the data
is in the cache, the monitor copies the data from the cache buffer
that contains it to the program's I/O buffer.
The monitor then links
the cache buffer to the beginning of the list of cache buffers and
clears its time of residency since last access.
The monitor maintains
the list of cache buffers in order of increasing time since last
access.
If the requested data item is not in the cache, the monitor examines
the list of cache buffers to determinE~ the time of last access for the
oldest cluster in the cache.
If the time is less than the minimum
residency, the requested data cannot be installed in the cache, so the
monitor automatically performs a normal disk read.
If the time is
greater than the minimum residency, the monitor replaces the current
data in the cache buffer with the new data and then transfers it to
the program's I/O buffer.

Sequential Mode Data Caching: MODE 2048%
Use MODE 2048% in the OPEN statement to cache data transfers to and
from a file in sequential mode.
MODE 2048% has effect only if the
1-42

System Structure and Disk Operations
file is being cached~
That is, either MODE 256% is set, the file's
UFO entry is marked for caching (see the section File Utility
Functions, in Chapter 7), or caching is set for all data on the system
(see the section "Enable/Disable Disk Caching", in Chapter 7) .. Note
that sequential mode caching has no effect for a cache cluster size
equal to 1, although no error is returned if the cluster size is 1.
Sequenti4al mode works like random mode caching except for the way the
monitor handles:
o

A read on the last block of a cache cluster

A read on more than one cache cluster

In sequential mode caching, a read on the last block of a cluster
makes the cluster eligible for replacement, regardless of the amount
of time it has been in the cache.
This speeds the replacement process
in the cache and minimizes the space that the cache requires.
The
monitor handles a read on any other block in the cache cluster the
same as in random mode caching: the cluster becomes eligible for
replacement only when its minimum residency time in the cache expires.
In a read on more than one cache cluster, the monitor transfers all
the requested data blocks to the program's I/O buffer but only
installs the last cache cluster in the cache.
Furthermore, if the
last data block read is the last block in a cache cluster, the monitor
does not install any data in the cache.
Thus, if you define the cache
cluster size as 1 and specify sequential mode, no data blocks are
installed in the cache because every data block is the last block in a
cache cluster.

Creating and Placing a File at the End of the Directory: MODE 1024%
Use MODE 1024% to override the pack default and specifically place a
file at the end of the current account's directory.
This file
placement is useful for files that are infrequently accessed or are
not time critical.
Because the monitor always searches for files
starting at the beginning of the directory, placing noncritical files
at the end speeds access to the first part of the directory.
Use MODE 1024% only in the OPEN FOR OUTPUT statement to create a new
file.
If you do not specify MODE 1024%, the monitor places the file
in the directory as directed by the pack defa~lt.
This default
depends on the system manager's response to the New files first?
DSKINT question.
For example, if you create the file on OBI: and do
not specify MODE 1024%, the monitor uses the OBI: default to place the
file.
If the device is part of the multidisk public structure (SY:),
the monitor selects the disk pack with the most free space and uses
that pack's default.

1-43

System Structure and Disk Operations
Creating and Placing a File at the Beginning of the Directory: MODE
1536%
Specify MODE 1536% (MODE 1024% + 512%) in the OPEN FOR OUTPUT
statement to cause the monitor to override the pack default and place
a file at the beginning of the current account's directory.
If you do
not specify MODE 1536%, the monitor places the file in the directory
as directed by the pack default.
This default depends on the system
manager's response to the New files first? DSKINT question.
For
example, if you create the file on DBl: and do not specify MODE 1536%,
the monitor uses the DBl: default to place the file.
If the device is
part of the multidisk public structure (SY:), the monitor selects the
disk pack with the most free space and uses that pack's default.
Use MODE 1536% for files that are frequently accessed.
For example,
if a program is used very heavily, you can place it at the start of
the directory.
For example, the $PIP program is heavily used on many
RSTS/E systems.
In this case, placing $PIP at the start of the [1,2]
directory may improve system performance.

Reading a File During Processing: MODE 4096%
In certain applications, you may need to read a data file regardless
of what other processing is in progress.
Under normal circumstances,
the system prohibits opening a file while the file is currently open
for update (MODE 1% or MODE 4%+1%).
However, with MODE 4096% you can
open a file for read access regardless of whether the file is being
updated. When a file is opened using MODE 4096%, other users can open
the file in update mode.
For example:
10 OPEN 'DATA.2' FOR INPUT AS FILE 1%, RECORDSIZE R%, MODE 4096%
You cannot perform write operations.
If you attempt a write
operation, the system generates the error ?Protection violation
(ERR=lO).
If the file is simultaneously open for update, the system
does not generate the normal error ?Disk block is interlocked (ERR=19)
when the program reads a block being updated (although that block may
contain inconsistent data).
Note
Use MODE 4096% with care because of the danger
involved in reading data that is subject to change.

1-44

System Structure and Disk Operations
Read~nly

Access to a File: MODE 8192%

Certain applications require simple read access to a data file and do
not want to preclude write access by other applications. Under normal
circumstances, an OPEN FOR INPUT statement for a disk file possibly
gains write access on the I/O channel involved.
To gain read access
to a data file when you do not want write access, use MODE 8192% in
the OPEN FOR INPUT statement.
The system never grants write access to
a file opened with MODE 8192%.
You can use MODE 8192% on files that are opened normally (MODE 0%).
However, you cannot use MODE 8192% to open a file that is currently
opened for update (MODE 1%).
If a file is currently opened for
update, you must specify MODE 8192%+1% in order to open the file
read-only.
If the file is not yet opened and you specify MODE
8192%+1%, subsequent opens on that file must be made with MODE 1%.
For example:
10 OPEN

'DATA~3'

FOR INPUT AS FILE 1%, RECORDSIZE R%, MODE 8192%

,After execution of this statement, the program has only read access to
the file DATA.3.
If the file is currently open for update, however,
the system generates the normal error ?Protection violation (ERR=10).

write Access to a Directory: MODE 16384%
If you have the WRTNFS privilege, you can write into a directory by
specifying MODE 16384% in the OPEN statement.
For example, the
following statement allows you to read and write into the UFD of
account [5,10]:
199 OPEN "DK1:[5,10]" AS FILE 2%, MODE 16384%
An OPEN FOR OUTPUT statement is invalid for a UFD. Without MODE
16384%, the system allows only read access if you have the appropriate
READ privilege (GREAD for group, WREAD for all).

Simultaneous Disk Access
RSTS/E permits several users to read from the same file
simultaneously, but only one user can write to a file (unless the file
is open in update mode). Without this limitation, two users could try
to write the same record of the file simultaneously, resulting in a
loss of data.
~ro avoid this conflict, the system permits only one
user at a time to have write access to any file.
If a second user
attempts to write into the file, the error ?Protection violation
(ERR=10) results.
Thus, users may fail to obtain write access to a
file that is not write-protected against them.
If this failure
1-45

System Structure and Disk Operations
occurs, the second user must close thE! file and reopen it after the
first user has closed it.
The system does not permit a file to be open simultaneously in update
mode and in normal mode. If your pr09ram attempts to do so, it
results in the error ?Protection violation (ERR=lO). However, a file
can be open simultaneously in update mode and read during processing
mode (see the section "Reading a File During Processing: MODE 4096%").
In addition, a file can be open in update mode by multiple users.
By checking bits 9 and 10 of the STATUS variable immediately after the
OPEN statement, a program can ascertain whether the: current job has
read and write access to a file. The example in the section
"Appending Data to Disk Files: MODE 2%", performs this check. See
the BASIC-PLUS Language Manual for a description of the STATUS
variable.

Disk Optimization
Whenever you open a file on the public structure, the system searches
the directories of all public disks t() determine whether the file
exists. To avoid the overhead of searching multiple directories, you
can put the file on a private disk.
When you dedicate a private disk to a large production file, it
minimizes overhead to access data and ensures an efficient directory
organization. If you find this impractical and must store more than
one such file on one private disk, dedicate an entire account to each
file. This arrangement reduces directory search overhead.
However, if you must save more than one file under an account, create
the more frequently acce~sed ones first or use MODE 1536% (see the
section "Creating and Placing a File at the Beginning of a Directory:
MODE 1536%") to ensure better directory organizatiori.
If you cannot do this, the system manager can optimally reorder the
file directory with the REORDR system utility (see the RSTS/E System
Manager's Guide). With REORDR, you can order files on an account in
either forward or reverse direction, by either date and time of
creation or date of last access.
When you create a large file, specify a large file cluster size to
increase efficiency. A large cluster size reduces the number of UFD
blocks required to describe the file. Performance improves'because
the system can read or write multiple blocks in a single transfer. In
addition, you can preextend a disk file to its maxi~um length when you
create it and can specify that contiguous space be used. Preextension
reduces directory fragmentation. Contiguous space reduces window
turning, which is the process of following UFD retrieval pointers to
locate a specific block within a file.
1-46

System Structure and Disk Operations
If you have the appropriate accounting privilege (GACNT for group,
WACNT fOlC all), you can use the Create User Account SYS call (SYS 0)
to optimally preextend and place directories.
By doing this, you may
improve system performance.
If you preextend a disk file with the FILESIZE modifier on the OPEN
statement and you do not specify the cluster size with the CLUSTERSIZE
modifier, the monitor computes the clustersize that is optimal for
fast aCCE~SS.
The monitor uses the formula FILESIZE/7, rounded up to
the nearest cluster size.
For example:
100 OPEN "MYFILE.DAT" FOR OUTPUT AS FILE 1%, FILESIZE 100%
This OPEN statement preextends the file MYFILE.DAT to a size of 100
blocks.
The monitor automatically computes a cluster size of 16
(100/7, rounded up).
Note that the largest possible cluster size is
256 blocks.
If a program requires simultaneous access to more than one data file,
it is best to place each file on a different private disk. Overhead
increases if the files reside on the same disk because the disk head
must move whenever the program accesses a different file.
Thus, a
large percentage of execution time is spent in moving the disk head
back and forth.
Use diff«~rent accounts to store different kinds of files.
To minimize
the numb«~r of poorly ordered accounts, dedicate certain accounts to
files that are created once and remain fairly static, and reserve
other accounts for transient files.
To further optimize the
structure, minimize the number of files in one account.
For example,
it is better to have 30 files each in 10 accounts than to have 300
files in one accounto

Partial Block Operations on Disk
In general, the buffer you use for disk I/O should be a multiple of
512 bytes in length.
Specify the buffer size by using the RECORDSIZE
option in the OPEN statement.
By default, GET and PUT statements transfer the entire buffer.
If you
want to transfer less data, use the COUNT option.
The COUNT option
used in a GET statement specifies the maximum number of characters to
be read in the current record regardless of the buffer size.
In the
following example the file is opened with RECORDSIZE 1024% and you
want to read only 520 bytes:
100 OPEN "MYFILE.DAT" AS FILE 1%, RECORDSIZE 1024%
110 GET 1%, COUNT 520%
This GET operation on channel 1% fills the buffer to the requested
1-47

System structure and Disk Operations
number of bytes.
The disk software then skips the rest of the last
disk block read and positions itself to access the next block. To
satisfy the COUNT of 520, the software reads the current block (for
512 bytes), reads 8 bytes of the next block, and positions itself to
access the following block.
For GET or PUT operations, you can use any value for RECORD or BLOCK.
For example, with a COUNT of 520 bytes, BLOCK 1 accesses the first
block and 8 bytes of the second block.
BLOCK 2 in the GET statement
retrieves the entire contents of the second block plus 8 bytes of the
third block.
The file is then positioned to access· the block
following the last one accessed (block 4 in the previous example).
For PUT operations, the COUNT must be a multiple of 512 bytes (or
exactly 512 bytes when writing a UFO).
For GET operations, COUNT must
be even (a multiple of 4 on RP02/03 disks).
In all cases, the COUNT
value must not be greater than the buffer size (RECORDSIZE option of
the OPEN).
See the BASIC-PLUS Language Manual for more information.

The Virtual Disk - DVO:
The virtual disk lets you store temporary data within the system's
memory.
The virtual disk is not a physical hardware device, but it
contains the same structures as a physical disk device.
You can use
the virtual disk for file-structured or non-file-st'ructured I/O in the
same way you use any other disk device, with one exception: all data
written to the virtual disk is lost when the RSTS/E system shuts down
or crashes.
DVO: is the device designator for the virtual disk.
The system manager allocates memory to the virtual disk with the
INIT.SYS DEFAULT option. Use the SHO'W DISK command to find out if the
virtual disk is enabled on your system.
You can use the virtual disk to store temporary files or any file that
has a very short lifespan.
Examples of temporary files are work files
created by an application program like SORT/MERGE that are later
deleted; virtual arrays created by BASIC-PLUS that are no longer
needed once the program exits; or temporary files used for entering
data in applications that give users a chance to edit data before
updating a permanent file.
You can also place copies of read-only files that never change and are
frequently accessed on the virtual disk.
For example, place in
virtual memory a copy of an index file that is used; to access other
files.
Or, place heavily overlaid programs (like TKB) in virtual
memory to improve performance.

1-48

System Structure and Disk Operations
The virtual disk is especially useful on large memory systems.
Because the virtual disk never requires physical I/O, it is the
fastest disk on your system.
It is even faster than data caching for
these reasons:
o

A file placed on the virtual disk always remains in memory.
On the other hand, a cached file remains in memory based on
frequency of access.

When you write to a file on the virtual disk, no physical I/O
takes place. When you write to a cached file, physical I/O
takes place.
The file processor first performs a physical
write, then it updates memory.

The virtual disk takes memory away from user space. On a small memory
system, this may detract from overall performance.
In addition, you
cannot use the virtual disk for any permanent files because all data
is lost when the system shuts down or crashes.

Asynchronous I/O Requests
An asynchronous read or write request performs the same basic function
as the synchronous read or write request:
it moves data between a
device and a program.
The difference lies in the completion of the
request. While a synchronous request stalls the job's execution until
the request is complete, an asynchronous request does not stall the
program.
The program continues to run regardless of the state of the
I/O request. When the I/O request completes, the RSTS/E monitor
executes an asynchronous completion routine (AST) in the user program.
This routine notifies the user job of the I/O completion.
The AST is a section of code within the user job that executes when an
I/O request completes.
The AST is the only section of code in the
program that can check for any device dependent errors.
BASIC-PLUS programmers cannot use asynchronous I/O.
BASIC-PLUS-2
programmers can use this feature, but must write a MACRO subroutine.
See the RSTS/E System Directives Manual for details.

Disk Special Function: SPEC%
The SPEC% function performs special operations on disks, flexible
diskettes, magnE~tic tapes (see Chapter 2), line printers (see Chapter
3), terminals (see Chapter 4), and pseudo keyboards (see Chapter 4).
On disks, the SPEC% function allows you io explicitly lock a maximum
of seven disk block ranges on a file that is open for update (MODE 1%
or MODE 1%+4%, see the section Updating Disk Files). A locked range
1-49

System Structure and Disk Operations
(from 1 to 31 blocks) is one that cannot be accessed by another user
or from another channel.
Thus, SPEC% extends the use of guarded
update, which locks the last block or blocks read on a file.
SPEC% also allows you to release explicit or implicit locks. Note
that when you close a file, all explicit and implicit locks are
released for that file.
The SPEC% function for disk files has the format:
VALUE%=SPEC%(FUNCTION%, BLOCK, CHANNEL%, 0%)
where:
VALUE%

depends on the particular function code you specify in
FUNCTION%.
In most cases, VALUE% is equal to the BLOCK
parameter.

FUNCTION%

is a function code that specifies the desired operation.
During normal I/O operations, a block, or range of
blocks, is implicitly locked when you read the file with
a BASIC-PLUS GET statement.
The SPEC% function allows
you to convert implicit locks to explicit locks and to
release selected locked blocks.
The code specified in
FUNCTION% determines the use of SPEC%.
The codes are:
FUNCTION%=O%

releases all locked blocks.

FUNCTION%=l%

releases the current implicit lock.

FUNCTION%=2%

converts the current implicit lock to
an explicit lock.

FUNCTION%=3%

releases the explicitly locked block
specified in the BLOCK parameter.
If
BLOC~ is 0, all explicitly locked
blocks are released.
However,
implicitly locked blocks remain
locked.

FUNCTION%=4%

converts an implicit lock to an
explicit lock and release the
implicit lock.

BLOCK

specifies the starting block number for releasing an
explicit lock.
Note that BLOCK must be a floating-point
number.

CHANNEL%

is the I/O channel on which the operation is to be
performed.

is the handler index for disk devices.
1-50

System Structure and Disk Operations
If you open a file with a RECORDSIZE greater than 512, SPEC% allows
you to lock more than one block when you read a range of blocks into
the buffer with the GET statement.
For example, if you open the file
with RECORDSIZE 1024%, each GET operation reads (and implicitly locks)
two blocks.
For example, suppose you explicitly lock blocks 2 and 3:
100

GET #1%, RECORD 2%
\ VALUE%==SPEC%(2%,0,1%,0%)

You can then read blocks 3 and 4 (GET RECORD 3%) and cause implicit
locks on these blocks. Note that if you attempt to lock a range of
blocks that overlap an already explicitly locked range, the monitor
returns the error ?Disk block is interlocked (ERR=19).
In addition,
if a range of blocks is locked, an explicit release of those blocks
must refer to the first block in the range.
The following errors are possible during a SPEC% operation:
Meaning

ERR Value

?NO ROOM FOR USER ON DEVICE
There are too many locks pending on this channel.
You can lock a maximum of seven ranges of blocks on
a file.

?CAN'T FIND FILE OR ACCOUNT
You specified function code 3 for FUNCTION% and
attempted to unlock a block that was not locked.

?PROTECTION VIOLATION
You clttempted to explicitly lock a block that had
not been implicitly locked. An attempt to lock a
block after a PUT or UNLOCK can cause this error.

?DISK BLOCK IS INTERLOCKED
You attempted to explicitly lock a range of blocks
that overlaps an already explicitly locked range of
blocks.

RX01/02 Flexible Diskettes
The RSTS/E monitor handles the RXll/RXOl and RX21l/RX02 flexible
diskettes (sometimes called floppy disks) as non-file-structured
devices.
The device name for the flexible diskette is DX.
Note
The RX50 flexible disk is not in this category.
It is
treated as a file-structured disk with the device name
DU.
1-51

System Structure and Disk Operations
BASIC-PLUS, which uses the standard monitor I/O services for flexible
diskettes, lets you store only one file on a disket~e.
For example:
SAVE DXl:
This command stores one .BAS file on a diskette.
from the diskette or to run it, use:

To read the file

OLD DXl:
RUN DXl:
Two system utility programs, FIT and FLINT, let you store more than
one file on a flexible diskette.
These programs tr~nsfer specially
formatted data between a flexible diskette and the RSTS/E environment.
See the RSTS/E utilities Reference Manual for more information.
A flexible diskette is divided into 77 tracks (numbered 0 through 76),
each of which consists of 26 sectors (numbered 1 through 26).
Thus,
there are 2002 records (numbered 0 through 2001).
Each record is 128
bytes for RXOI and single-density RX02, or 256 bytes for
double-density RX02 on each diskette.
Table 1-10 shows that you can open and access a flexible diskette in
either of two modes.
Table 1-10:

MODE Specifications for Flexible Diskette

+- - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - -" - - - - - - - - - - - - _ .. _+

MODE

Meaning

+- - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - _ .. - - - - - - - - - - - - - .. -+

0%
16384%

Read and write in block mode (default)
Read and write in sector mode

+- - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - _ .. - - - - - - - - - - - - -;.-+

The following sections describe the MODE specifications.

Block Mode: MODE 0%
In block mode, the buffer size is 512 bytes, equivalent to four
128-byte records.
The four sectors are interleaved according to the
following algorithm, where N is the value specified'in RECORD:
TEMPI

= INT(N/26)

TEMP2

= N - INT(N/26)*26

TEMP2 = TEMP2 * 2
1-52

System Structure and Disk Operations
TEMP2 = TEMP2+1 IF TEMP2 >=26
TEMP2 = TEMP2 + 6*TEMPI
TRACK = TEMPI + 1
SECTOR = TEMP2 - INT(TEMP2/26)*26 + 1
This interleaving algorithm is standard in other PDP-II operating
systems for the flexible diskette (for example, RSX-IIM, RT-ll).
Note
that track 0 is unavailable; its use is reserved for IBM-compatible
labels.
The following statement opens the diskette on unit 3 in block mode on
I/O chan.nel 1:
10 OPE:N "DX3: WI AS FILE 1%
A GET statement reads a 512-byte block from the diskette.
The RECORD
option, if present, defines a specified sector starting point for the
read.
If you omit the RECORD option or include RECORD 0%, the next
sequential block is read.
For example:
100 GET #1%, RECORD N%
where N% is the number of the sector at which the block begins.
It
can be any number from 1 through 493.
(Only the first GET statement
after the device is opened can access the first block on the
di sket te') .
A PUT statement writes a 512-byte block on the diskette:
200 PUT #1%, RECORD N%, COUNT C%
where:
N%

is the number of the sector at which the block begins.
The
RECORD option can also include 16384% to write a Deleted Data
Mark with each of the sectors (see the section "Deleted Data
Marks") .

must be a positive nonzero number.

You can perform block mode operations in sector mode.
example opens an RXOI diskette with this statement:

The following

20 OPEN "DX3:" AS FILE 1%, RECORDSIZE 512%, MODE 16384%

1-53

System structure and Disk Operations
Then use the GET (or PUT) statement:
30 GET #1%, RECORD N%*4% + 32767% + 1%
where:
32767%+1%

specifies sector interleaving

N%*4%

defines 5l2-byte blocks at 4-sector intervals.

Sector Mode: MODE 16384%
In sector mode, the buffer size is 120 bytes for RXOI and 256 bytes
for RX02.
Open the diskette on unit 3 in sector mOQe with the
following statement:
10 OPEN "Dx3:" AS FILE 1%, MODE 16384%
When you use GET and PUT statements, you can calculate track and
sector numbers from the RECORD number.,
If you specify the desired
record number as N (any number from 0 through 2001), you can specify
the track and sector to access as:
TRACK

= INT (N/26)

SECTOR

= N - INT(N/26)*26 + 1

A GET statement reads a 128-byte single-density or a 256-byte

double-density record from the diskette.
The RECORD option, if
present, defines a specific record on the diskette.
If you omit the
RECORD option or include RECORD 0%, the next sequential record is
read.
For example:
100 GET #1%, RECORD N%
where N% is the record number and can be any number from 1 through
2001.
(Only the first GET statement after the file has been opened
can access record 0.)
If you include -32768% (formed by 32767% + 1%) in the RECORD option
(for example, RECORD N%+32767%+1%), sectors are interleaved according
to the algorithm discussed in the section Block Mode - MODE 0%.

1-54

System Structure and Disk Operations
A PUT statement writes a 128-byte single density or a 256-byte double
density record on the diskette.
For example:

200 PUT #1%, RECORD N%, COUNT C%
where:
N%

is the record number.
The RECORD option can also include
-32768% for interleaving (see the section Block Mode - MODE 0%)
and 16384% to write a Deleted Data Mark (see the section
"Deleted Data Marks") with each of the records.

must be a positive nonzero number.
Note
If you insert a single-density diskette into an Rx02
drive, the buffer size on a sector mode open is 256
bytes (the length of two sectors).
Thus, the
statement GET RECORD N% reads record N% and record
N%+I%~
To make sure that you read only one record,
include COUNT 128% in the GET statement.

Flexible Diskette RECORD Modifiers
When you perform I/O operations on flexible diskettes, you can include
three special RECORD values in GET and PUT statements to modify the
actions of the diskette drive:
RECORD a:192%

Allows you to access logical record zero on the
flexible diskette.
Under normal operation, the
system does not allow access to logical record
zero after the first I/O operation is performed.
However, the following statement accesses logical
record zero:
GET #N%, RECORD 8192%

RECORD 16384%

Writes a Deleted Data Mark to the diskette when
used in the PUT statement (see the following
section "Deleted Data Marks").

RECORD 32767%+1%

Causes the specified I/O operation to be performed
in block mode.
That is, when you want block mode
on a diskette that is open in sector mode (MODE
16384%), you can specify RECORD 32767%+1% in the
GET or PUT statement. With RECORD 32767%+1%, the
I/O operation you perform is done in block mode.

1-55

System Structure and Disk Operations
Deleted Data Marks
Each sector of a flexible diskette contains a bit called the Deleted
Data Mark in addition to its data. When an INPUT or GET operation
from the diskette encounters a Deleted Data Mark, the error ?Data
format error (ERR=50) occurs.
In a GET operation, the contents of the buffer are valid even if this
error occurs.
So it is possible to examine the contents of the record
containing the Deleted Data Mark. WhE~n the record Size specified is
larger than one sector, the last sector read into t~e buffer is the
data that had the Deleted Data Mark.
The RECOUNT variable reflects the amount of data read up to and
including this mark.
To write a Deleted Data Mark to a diskette,
include RECORD 16384% in the PUT statement.

Partial Block Operations on Flexible Diskettes
Use the RECORD5IZE option in the OPEN statement on a flexible diskette
to specify a value that is not a multiple of the de~ault buffer size
(512 bytes in block mode; 128 bytes or 256 bytes in:sector mode).
Be
careful, however, in using the GET and PUT statements.
For GET operations with a nondefault buffer size (or a multiple of the
default), the software retrieves the required number of bytes and
positions itself to the next boundary.
In block moqe, this boundary
is the next block (sector number times 4 for RXOI, ~imes 2 for RX02);
in sector mode, this boundary is the next sector.
Thus, for a buffer
size of 520 bytes, a GET statement in block mode returns in the buffer
the current sector, the next three sec:tors, and the first eight bytes
of the fourth sector.
The software then skips the ~est of the fourth
sector and all of the fifth, sixth, and seventh sectors to position
itself at the beginning of the next block boundary ~or the next GET
operation. A GET statement in sector mode returns the required number
of bytes and skips the rest of the par'tial sector to position itself
at the beginning of the next sector boundary.
You can use any legal value in the RECORD option with the GET
statement.
Thus, with a buffer size grreater than 512 bytes, you can
overlap record values to recover skipped data.
Note
When you use the COUNT option in a GET statement, the
COUNT argument must be a positive even numb~r.
If an
odd number (or 0) appears in the COUNT, the 'error
?Illegal byte count for I/O (ERR=3l) is returned.
For a PUT operation with a nondefault buffer size (or a multiple of
1-56

System Structure and Disk Operations
the default), the software performs the same skipping and positioning
The software writes null bytes in the
skipped data.
If you include the COUNT option in the PUT statement,
the software writes the specified number of bytes from the buffer and
writes null bytes for the rest of the buffer and for the skipped data.

as with the GET statement.

Flexible Diskette Special Function: SPEC%
The SPEC% function performs special operations on flexible diskettes,
disks, magnetic tape (see Chapter 2), line printers (see Chapter 3),
terminals (see Chapter 4), and pseudo keyboards (see Chapter 4).
For flexible diskettes, the SPEC% function lets you:
o

Find out the density (single or double) of the current
diskette

Mount a new diskette and recompute the density

Reformat an RX02 diskette for a desired density

Because the RX02 flexible diskette drive supports single- and
double-density diskettes, the SPEC% function is useful for programmed
diskette~ operations.
For example, SPEC% allows you to mount a series
of single- and double-density diskettes without having to close and
reopen the device for each mount.
Normally the driver computes
density once, during the initial open.
If you insert a second
diskettE! that is incompatible with the initially computed density,
read or write operations fail.
SPEC% pE!rmits you to include an instruction in your program that
causes the driver to recompute the density.
In addition, for RX02
flexiblE! diskette drives, SPEC% lets you specify a density reformat
operation.
The SPEC% function for flexible diskettes has the format:
VALUE~)=SPEC% (FUNCTION%, PARAMETER, CHANNEL%, 18%)

where:
VALUE~i

depends on the function code you specify in FUNCTION%.

FUNCTION%

is a function code that specifies the desired operation.
The codes are:
FUNCTION%=O% returns the density of the currently
mounted diskette in the form:
DENSITY%=VALUE% AND 255%.
1-57

System Structure and Disk Operations
If DENSITY%=l%, the diskette is
single-density; if DENSltY%=2%, the
diskette is double-density.
Note that
PARAMETER must also be O.
FUNCTION%=l% causes the diskette driver to recompute
density.
If the diskette has been changed
in the drive without closing and reopening
the I/O channel, issue this code prior to
any I/O operation on the diskette.
This
function also returns the computed density
as described in FUNCTION%=O%.
Note that
PARAMETER must be O.
FUNCTION%=2% reformats the current diskette to the
density in PARAMETER.
PARAMETER equals 1
for single-density and 2 for
double-density.
Note that this operation
is allowed only on RX02 drives and that any
data on the diskette prior to the operation
is lost.
PARAMETER

see the description of FUNCTION%.

CHANNEL%

is the I/O channel on which the operation is to be
performed.

18%

is the handler index for flexible diskettes.

SPEC% can take up to 20 seconds to reformat the density of an RX02
diskette and cannot be interrupted with CTRL/C.
If the operation is
interrupted by power failure or catastrophic error, the diskette will
contain both single- and double-density and cannot be used.
To
recover, you must reformat the diskette.
The following errors are possible during a SPEC% operation:
ERR Value

Meaning
?DEVICE HUNG OR WRITE LOCKED
A hardware error occurred.
This can often be a
transient condition.
Retry the operation.

?MISSING SPECIAL FEATURE
An attempt was made to reformat on an RXOl flexible
diskette drive.
The use of SPEC% to reformat
diskette density is allowed only on RX02 drives.

SPEC% is useful in flexible diskette programming to make sure that
sector opens are correctly handled.
You can resolve the conflict
between 128-byte single-density buffer sizes and 256-byte
double-density buffer sizes by using the following procedure:
1-58

System Structure and Disk Operations
To field the buffer:
FIELD #channel number, l28%*DENSITY% AS BUFFER.RX02$
To write the buffer:
PUT #channel number, COUNT l28%*DENSITY%
DENSITY% is defined as:
DENSITY%=SPEC%(O%, 0, CHANNEL%, 18%) AND 255%

The Null Device· NL:
The null device exists as a debugging aid on all RSTS/E systems.
It
provides a means for a program to check out all I/O routines without
reference to an actual device. A read access for the null device
returns the error ?End of file on device (ERR=ll) and a write access
simply returns control to your program.
You can use the null device to dynamically allocate buffer space in
memory.
It has a default buffer size of 2 bytes, which is adequate
for performing alternate buffer I/O operations with data on another
channel.
To specify a different buffer size, use the RECORDSIZE
option in the OPEN statement.
The null device can use any even buffer
size.
For example, the following statement allocates 132 bytes of
buffer space:
100 OPEN 'NL:' AS FILE 12%, RECORDSIZE 132%
Opening the null device is also a convenient way to set up a buffer
for message send/receive operations. Use the RECORDSIZE option in the
OPEN statement to specify the buffer size.
See Chapter 8 for more
information on message send/receive operations.
The null device is shareable by all users on the system: no user can
assign it.

1-59

Chapter 2
Magnetic Tape

Magnetic tape is a compact, relatively inexpensive medium that can
provide large amounts of off-line data storage. One reel of magnetic
tape can store many files. In addition, through multivolume ANSI
processing of the PIP system program, you can store one or more large
files on several reels of tape.
Unlike disks, which can be accessed randomly or sequentially, magnetic
tape is a sequential access device. In most applications, a magnetic
tape file is read or written from beginning to end, and each record in
the file is processed in order.
Magnetic: tape is used for backing up disks on many RSTS/E systems.
The RSTS/E BACKUP and SAVE/RESTORE programs (see the RSTS/E System
Manager's Guide), the PIP program (see the RSTS/E utilities Reference
Manual), and the DCL COpy command (see the RSTS/E System User's Guide)
can all perform this function. In addition, the RMSBCK and RMSRST
utility programs (see the RMS-ll User's Guide) can back up and restore
RMS-ll files between disk and magnetic tape.
Other uses for magnetic tape include journaling and data interchange.
Some applications track transactions as they are processed by
journaling each operation to a magnetic tape as well as to a disk.
Magnetic: tape is also useful for transferring data between different
computer' systems. Finally, you may want to use magnetic tape instead
of disk for applications that require infrequent processing
(particularly batch processing) and use large amounts of data.

Overview of Tape Operations
RSTS/E olffers a variety of utility programs and software features for
processing magnetic tapes. The utility programs can fill most general
needs.

2-1

Magnetic Tape
This chapter discusses the software fE~atures, which provide extra
flexibility and control for special applications.
These features
include:
o

MODE values for use in file-structured and
non-file-structured processing

FILESIZE, CLUSTERSIZE, and POSITION values for ANSI tapes

MAGTAPE and SPEC% functions

File-structured and Non-File-Structured processing
RSTS/E can process magnetic tape as either a file-structured or a
non-file-structured device.
File-structured processing lets you take
advantage of built-in system file handling functions; thus, it is
easier to program than non-file-structured processing.
On the other
hand, non-file-structured processing 9ives you more control over tape
operations.
(For example, you may need to process a tape written in a
non-standard format by another system or recover a file from a
corrupted tape in non-file-structured mode.)
Table 2-1 summarizes the BASIC-PLUS statements used to access magnetic
tape on RSTS/E.
These are the same statements used to access disks.
See the BASIC-PLUS Language Manual fOl: complete descriptions of the
statements.
Table 2-1:

statements and Functions for Accessing Magnetic Tapes

+- - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - -+ .. - - - - - - - - - - - - - .. - - - - - --+
I
Block I/O
I
Stream ASCII
(File- or
I
Function
(File-Structured)
Non-Fi1e-Structured)
+- - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - -+ .. - - - - - - - - - - - - - ~ - - - - - --+

Open

OPEN

Access Buffer

FIELD

Read

INPUT
INPUT LINE

GET

Write

PUT

Special

MAGTAPE, SPEC%

Close
CLOSE
CLOSE
+- - - - - - - - _ .. - - - - -+- - - - - - - - - - - - - - - - - - -+ .. - - - - - - - - - - - - - - - - - - - --+
2-2

Magnetic Tape

The KILL and NAME AS statements (see the BASIC-PLUS Language Manual)
apply only to disk and DECtape files; you cannot use them with
magnetic tape files.
RSTS/E provides several MODE values for use with the OPEN statement to
control file-structured and non-file-structured tape operations. The
MODE values differ for file-structured and non-file-structured
processing.
The MAGTAPE and SPEC% functions, used mostly in
non-file-structured processing, give you still more control over
magnetic tape operations.
In addition, the Special Magnetic Tape
Directory Lookup SYS call (SYS 15) is available to look up directories
on magnetic tape (see Chapter 7).
RSTS/E writes tape records of 512 bytes by default. Table 2-2 lists
standard system defaults for magnetic tape density and parity. Note
that all tape drives except for the TK25 use 9-track magnetic tape.
The Set System Defaults SYS call (SYS 34) changes the system tape
density default.
See Chapter 7 for details.
Table 2·2:

System Density Values for Magnetic Tape

+- - - - - _ .. - - -+- - - - - - - - - - - - - - - - - --+

Tape
Drive

Density

+- - - - - _ .. - - -+- - - - - - - - - - - - - - - - - --+
I

BOO bpi only

TEIO
TUIO

IrS03
+- - - - _ .... - - -+- - - - - - - - - - - - - - - - - --+

BOO bpi
1600 bpi

TE16
TU16
TU4S
TU77

+- - - - - - .. - - -+- - - - - - - - - - - - - - - - - --+

TSIJ.
TSV05
TUBO

1600 bpi only

+ - - - - - - - - - -+ - - - - - - - - - - - - - - - - - - -+
I

TK2S

Special format

IrK 5 0
I
+ - - - - - - - - - -+ - - - - - - - - - - - - - - - - - - -+

You can override the system defaults by using the MOUNT command.
In
addition, you can override both system and assigned defaults in a
program by using the MODE option (in non-file-structured processing)
and the MAGTAPE and SPEC% functions (in both file-structured and
non-file-structured processing).
October 1985

2-3

Magnetic Tape
Magnetic Tape Labels
RSTS/E supports two types of magnetic tape file labels in
file-structured processing:
ANSI (American National Standards
Institute) and DOS (Disk Operating System).
These labels contain
information about data on the tape, but they have different formats.
The ANSI label has a more complex format and contains more information
than the DOS label. A specific tape must contain only one type of
label.
Note
Where ANSI is used in RSTS/E documentation, it refers
to the RSTS/E implementation of American National
Standard X3.27-l978 - magnetic tape labels and file
structure for information exchange.
RSTS/E implements
a subset of this standard.
In addition, RSTS/E uses U (undefined) record format,
which is not defined in ANSI standard X3.27-l978.
The system manager sets the default label format wi,th the DCL SET
If you
SYSTEM command or with the Set System Defaults SYScall (34).
want to use a different label, you can either select a label format
for your current job with the MOUNT command or spedify a label in a
program by use of MODE values in the OPEN statement.
The MOUNT
command overrides the system default; the MODE values override both
the system default and the job default.

Data and Label Handling in File-Structured Processing
File-structured magnetic tape processing involves two types of
operations:
o

Data handling

Label handling

Data handling, which is done by your program, is no different from
data handling on any other device:
the operations you perform depend
on the I/O method you use.
In BASIC-PLUS, you can use either stream
(formatted) ASCII or block I/O.
Stream ASCII I/O limits you to stream
ASCII records, but BASIC-PLUS takes care of record blocking and
deblocking, buffer management, and conversion between ASCII and
numeric data types.
Block I/O lets you read or write any type of data
record, but your program must do its own blocking and deblocking,
buffer management, and data conversion.
Note that you may be able to
use PIP instead of writing your own program (see the RSTS/E utilities
Reference Manual). Or, you may be able to use the ,DCL COpy command
(see the RSTS/E System User's Guide).
2-4

Magnetic Tape
Label handling, on the other hand, is done by the system.
(Your
program needs to read and write magnetic tape labels only when you
process tapes in non-file-structured mode.) The system needs
information from you to write a tape label; you supply this
information when you open the file.
The way you supply information
and the amount you supply depends on whether you are writing a DOS or
ANSI tape.
In general, the system requires no special information from your
program to write a DOS tape.
You can use standard BASIC-PLUS
programming techniques (such as the RECORDSIZE option in the OPEN
statement to specify a buffer size other than the default).
However,
when you write an ANSI tape, you need to supply some special
information, which you place in the CLUSTERSIZE and FILESIZE options
and the POSITION switch when you open the file.
CLUSTERSIZE,
FILESIZE, and POSITION for ANSI tapes have different meanings than
they do for disk files.
These parameters:
o

Specify information about record format and length to be
written at certain positions in the tape label

Determine the I/O buffer size

Specify a section number for a multivolume file; that is, a
file too large to fit on one tape

See the section "processing ANSI Magnetic Tape Files" for more
information.
Note that although the system writes the label based on information
you specify, it does not check this information when you write data
records to the tape.
Instead, your program must ensure that the label
information and the data format agree.
Reading a magnetic tape also differs depending on whether it has DOS
or ANSI labels. When you open a DOS tape for input, the system
creates a 512-byte I/O buffer unless you specify a different buffer
size in the RECORDSIZE option.
However, when you open an ANSI tape
for input, the system determines the I/O buffer size from information
in the label. Do not use the RECORDSIZE option when opening an ANSI
tape.
The rest of this chapter describes magnetic tape operation in detail:
o

File-structured processing

Non-file-structured processing

Multivolume ANSI processing

MAGTAPE and SPEC% functions

2-5

Magnetic Tape
o

Asynchronous I/O processing

Error Handling

programming Examples

Note that Appendix A of this manual describes DOS and ANSI label
formats and explains how RSTS/E initicllizes the two types of tapes.
This information is useful for readin9 a tape from another operating
system or writing a tape for use on another operating system.

The File-Structured Magnetic Tape OPEN FOR INPUT
To open a magnetic tape file for file··structured processing, specify
the device name and file name in the OPEN statement.
For example:
100 OPEN "MTO:ABC" FOR INPUT AS FILE N%, MODE M%
The OPEN FOR INPUT statement searches for the specified file on a
designated tape unit.
Use OPEN FOR INPUT when you want to read a
magnetic tape.
Unlike disk operation" OPEN FOR INPUT on magnetic tape
permits read access only. An attempt to write to the file generates
the error ?Protection violation (ERR=10).
If the system detects a
logical end-of-tape before finding a jEile, the error ?Can't find file
or account (ERR=5) occurs.
In the previous example,
channel designated by N%
account according to the
that a~count numbers are

the system associates tape unit 0 with the
and searches for file ABC under the current
value of M% :Ln the MODE specification. Note
ignored on ANSI-labeled tapes.

Table 2-3 shows the MODE values that you can use in an OPEN FOR INPUT
statement.
The MODE value can be the sum of any combination of these
single values, as long as they do not represent conflicting
operations.

2-6

Magnetic Tape
Table 2·3:
+~

Magnetic Tape OPEN FOR INPUT MODE Values

- - - - - - -+- - - - _ .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - _. - - - - - - - - - - - - - - - - - --+

MODE

Meaning

+ .. - - - - - - -+- - - - - ~ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

Read file label record at current tape position.

Do not rewind tape when searching for specified file.

32%

Rewind tape before searching for specified file.

64%

Rewind tape upon executing a CLOSE.

I
I

Search for a DOS-formatted file label.

I
I

16384%

I
I
I

I
I

24576%
Search for an ANSI-formatted file label.
I
+- - - - - - - -+- - - - _ .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
If the system finds the file, it opens the file for read access only.
If you later execute a GET statement on channel N%, it makes a block
of the file available to the program in the channel's buffer.
For ANSI-labeled tapes, the system reads the block length from the
header 2 label (HDR2) when it opens the file.
The system creates the
buffer at the size given by the block length.
However, if the block
length is odd, the system rounds the value down to make the buffer
size an even number of bytes.
(To avoid loss of data when a magnetic
tape file is read, make sure the block length is an even value when
you write the file.)

Under DOS file-structured operations, a GET statement reads magnetic
tape records into a 5l2-byte buffer.
However, in certain cases you
may need to process records larger than 512 bytes. Use the RECORDSIZE
option to allocate more buffer space than the default provides.
The
form of the statement is:
100 OPEN "MTO:FIDO" FOR INPUT AS FILE N%, MODE M%, RECORDSIZE R%
where:
N%

is the internal I/O channel on which the file is open,

is the MODE value

is the desired record length.
even number if R% is odd.

The system rounds R% down to an

This statement opens the file FIDO under the current account on tape
unit 0 for input and allocates R% bytes of buffer space for data
transfer operations.

2-7

Magnetic Tape
To open a file stored on a DOS file-structured magnetic tape under an
account other than the current account, supply the project-programmer
number in the OPEN statement.
For example:
100 OPEN "[3,2l4]MTO:ABC" FOR INPUT AS FILE N%, MODE M%
In this example, the system associates tape unit 0 with the channel
designated by N% and searches for filf~ ABC under account [3,214]
according to the value of M% in the MODE specification.

Searching for a Label on INPUT
Omitting the MODE specification or using a MODE 0% specification reads
the record at the current position of the tape.
The system expects
the label format to be the system-widl~ default unless you changed the
format when the unit was allocated to the job with the MOUNT command.
If the label format differs or the tape is not properly positioned,
the system generates the error ?Bad directory for device (ERR=l).
No
match causes the system to rewind the tape and check successive label
records until the label record for thc~ desired file is found or the
logical end-of-tape is detected.
The system does not rewind the tape
when the program executes a CLOSE statement on channel N%.

Rewinding the Tape: MODES 2%, 32%, 64%
As mentioned before, MODE 0% reads thf~ tape from its current position~
If the file name specified in the OPEN statement does not match the
label record, the system automatically rewinds the tape to the first
file label record and begins reading labels file by file.
To override this automatic rewind feature, include MODE 2% in the OPEN
statement.
In this case, the system reads the tape from its current
position and, if no match occurs, continues reading file label records
from that position forward until it either finds the file or detects
the logical end-of-tape.
The system does not rewind the tape when it
performs a CLOSE operation.
MODE 32% rewinds the tape to the first label record before reading any
label.
Once again, no match causes the system to check successive
label records until it finds the file or detects the logical
end-of-tape.
The system does not rewind the tape when it performs the
CLOSE operation on channel N%.
Including MODE value 64% with any of the above modes rewinds the tape
when you issue a CLOSE statement on channel N%.

2-8

Magnetic Tape
Example of OPEN FOR INPUT statement
You can use the MODE values in any combination as long as they do not
represent conflicting operations.
(For example, MODE 16384%+24576%
causes illogical results because DOS and ANSI formats are mutually
exclusive.)
Consider the following:
10 OPEN "MTl:NATHAN" FOR INPUT AS FILE 3%, MODE (32%+64%+24576%)
This staltement opens the file MARKlE on tape unit 1 and associates it
with channel 3%.
You can also specify MODE 24772%, the sum of the
three modes.
When the system executes this statement, it rewinds the tape to the
first label record (MODE 32%) and begins to read successive file label
records until it either finds the file or detects the logical
end-af-tape.
reached.
The search is successful only if the system
finds the file label MARKlE, written in ANSI format (MODE 24576%).
When thE! search is successful, the file MARKlE is available for input
by means of GET, INPUT, or INPUT LINE statements.
Remember, since the
file is open for input only, attempting to execute PUT or PRINT
statements results in the error ?Protection violation (ERR=10).
The next CLOSE statement rewinds the tape (MODE 64%).

Reading Data
Three types of statements read magnetic tape data:
and GET statements.

INPUT, INPUT LINE,

If a tape contains stream ASCII data, you can read it with INPUT or
INPUT LINE statements.
These statements work the same way they do for
disks.
To read other types of data, use the GET statement.
GET reads a
single block of data into the I/O buffer from a magnetic tape file
that is open for input.
Do not use both GET and INPUT statements to
read the same file.
The GET statement for magnetic tape has the form:
100 GET iN%
where N~; is the channel on which the device is open.
This statement
reads the next sequential block in the file.
For DOS format tapes,
the buffer is 512 bytes long unless you specify a larger buffer with
the RECORDSIZE option when you open the file.
For ANSI-labeled tapes,
2-9

Magnetic Tape
the buffer size is the block length read from the header 2 label
(HDR2).
Magnetic tape hardware allows only sequential access.
Therefore, you
cannot use the RECORD option in the GgT statement. After the GET, the
number of bytes read is available in the RECOUNT variable.
To
associate string variables with all or part of the data in the I/O
buffer, use a FIELD statement, (see the BASIC-PLUS Language Manual).
Attempting to read beyond the end of the file results in the error
?End of file on device (ERR=ll).
If the system reads a block that is larger than the buffer, it
transfers the amount of data that fits, skips the excess data, and
returns the error ?Magtape record length error (ERR=40).
The next GET
statement then reads the next block.
The GET statement does not perform any data conversions or record
blocking and deblocking.
Your program must interpret the data
retrieved.

The File-Structured Magnetic Tape OPEN FOR OUTPUT
The OPEN FOR OUTPUT statement searches for a specified file on a
designated tape unit.
Use OPEN FOR OUTPUT when you want to write a
magnetic tape.
(Unlike disk operations, OPEN FOR OUTPUT on magnetic
tape allows write access only.) For example:
10 OPEN "MTO:ABC" FOR OUTPUT AS FILE N%, MODE M%
The system associates tape unit 0 with the internal channel designated
by N% and searches for the file ABC in the current account according
to the value M% in the MODE specification.
Note that the system
ignores account numbers on ANSI-labeled tapes.
If it does not find the file, the system writes a magnetic tape label
record for the file at the logical end-of-tape and leaves the unit
open with write access only. A PUT or PRINT statem~nt subsequently
executed on channel N% writes the channel's buffer to the tape.
Since
the file is open solely for output, a GET, INPUT, or INPUT LINE
statement executed on channel N% generates the error ?Protection
violation (ERR=lO).
The search is successful when the system locates th~ specified file.
The value of M% in the MODE specification determines how the system
searches for and acts on the file when it is found.
Table 2-4 shows the MODE values that can be used in an OPEN FOR OUTPUT
statement.
The MODE value can be the sum of any co.bination of these
single values, as long as they do not represent conflicting
operations.
2-10

Magnetic Tape
Table 2·4:

Magnetic Tape OPEN FOR OUTPUT MODE Values

+- - - .. - - - -+_. - - _ .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

MODE

Meaning

+- - _ .. - - - -+- - - - - ~ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I

I Read file label record at current tape position.

I
I

Do not rewind tape when system searches for the file.

16% I Write over existing file.
I currently on the tape.)
32%

(Destroy any

I
I Rewind tape before searching for
I

subsequent

files

the file.

64%

I Rewind tape upon executing the CLOSE statement.

128%

I Open for append.

512%.

I
I

Write new file label record without searching.

16384%. I Search for a DOS-formatted file label.
24576%;

I
I

Search for an ANSI-formatted file label.

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

Searching for a Label on OUTPUT
Omitting[ the MODE specification or using a MODE 0% specification reads
the tape~ at its current position.
The system expects the label format
to be the system default unless you changed the format when the unit
was allocated to the job using the MOUNT command.
If the label format differs or the tape is not correctly positioned,
the system generates the error ?Bad directory for device (ERR=l).
If the system finds a file label record, and its file name (and
account for DOS tapes) matches that of the file specified in the OPEN
statement, the system generates the error ?Name or account now exists
(ERR=16).
No match causes the system to rewind the tape and to check successive
file label records until it either finds a match or detects the
logical end-of-tape.
If the system detects the logical end-of-tape,
the search is unsuccessful. As a result, the system backspaces over
the logical end-of-tape, writes a file label record for the file, and
allows ~Trite access to the file.
The system does not rewind the tape
when the program executes a CLOSE statement on channel N%.

2-11

Magnetic Tape
Writing a Label: MODES 16%, 512%

As mentioned before, a search is successful when the system finds the
specified file on the magnetic· tape. The error ?Name or account now
exists occurs when this happens. This is a precaution to prevent you
from unintentionally writing a file at this point.
(Doing so will
write over the current file and destroy all later files on the tape.)
Include a value of 16% in the MODE specification to suppress this
error message and cause the system to write over an existing file on
magnetic tape.
Note

Writing over a file causes any files after the
overwritten file to be lost.
When 16% appears alone in the MODE specification, the system first
reads the tape at its current position. If the system finds a file
label record and the file specification in th~ labei record matches
the file specification in the OPEN FOFt OUTPUT statement, it backspaces
over the file label record, writes a new label record over the
existing label, and allows the program write access to the file.
If
the logical end-of-tape is at the current position, the system
backspaces one record, writes a new file label record, and allows
write access to the file. No match causes the system to rewind the
tape and to check label records until it either locates the file or
detects the logical end-of-tape. Detecting the logical end-of-tape
before locating the file causes the system to backspace one record,
write a tape label for the file, and allow write access to the file.
When you include 512% in the value for the MODE option, the system
writes a file label record at the current tape position. No label
record reading occurs. The system simply writes a new file label
record, destroying all subsequent files on the tape., Only the value
32%, which causes the tape to rewind (see the section "Rewinding the
Tape"), takes precedence over 512%. Therefore, when you use 512% with
any combination of values, not including 32%, the s~stem writes a file
record label at the current tape position.
Note

Any MODE value that includes 512% causes the files
after an overwritten file to be lost. The overwritten
file is always the one at which the tape is currently
positioned, except when you also include 32% in the
MODE value.

2-12

Magnetic Tape
Extending a File: MODE 128%
When you include 128% in the value for the MODE option, the system
attempts to open an existing file and position the tape so you can
append information to it.
The file must already exist; if it does not
exist, the error ?Can't find file or account (ERR=5) occurs.
The file
must also be the last file on the tape before the logical end-of-tape.
If it is not the last file on the tape, the system cannot locate the
trailin9 EOF tape marks and the error ?Protection violation (ERR=10)
occurs. As for all other MODE values, you can use 128% alone or with
any combination of values.

DOS and ANSI Format Labels: MODES 16384%, 24576%
By default, the system assumes that label records on a tape (either
DOS or ]\NSI) are in the system default format or the format you select
for your job with the MOUNT command.
The MODE values 16384% and
24576% override any current defaults for labeling.
MODE 16384% in the OPEN FOR OUTPUT statement causes the system to
search for a specified magnetic tape file.
The search succeeds only
if the file is written in DOS format (that is, preceded by a DOS
label).
MODE 24S76% in the OPEN FOR OUTPUT statement causes the system to
search for a specified magnetic tape file.
In this case, the search
succeeds only if the file label is written in ANSI format.
If the tape
search, the
1).
If the
account now

format (either ANSI or DOS) differs from that used in the
system generates the error ?Bad directory for device (ERR=
system finds the file, it returns the error ?Name or
exists (ERR=16).

The system reads the tape from its current position.
If it does not
find the file, the system rewinds the tape and reads file labels one
by one until it finds the correct file.
If the system detects the
logical end-of-tape, it automatically backspaces over the logical
end-of-tape, writes a DOS or ANSI label record for the file, and
allows write access to the file.

Processing DOS Magnetic Tape Files
If the tape being processed is in DOS format, use the RECORDSIZE
option in the OPEN FOR OUTPUT statement to designate the block length.
Omittin9 the RECORDSIZE option from the OPEN FOR OUTPUT statement is
the saml~ as specifying RECORDSIZE 00
BASIC-PLUS creates a 5l2-byte
buffer, the default for DOS magnetic tape processing.
PUT statements
write blocks on tape equal to the buffer size (512 bytes).
2-13

Magnetic Tape
To write blocks larger than 512 bytes" specify an even value equal to
or greater than 512 in the RECORDSIZE option.
If t~e value is odd,
BASIC-PLUS rounds the buffer size down to make it even.
To write blocks smaller than 512 bytes, create a buffer smaller than
512 bytes.
Specify 32767%+1% plus an even value equal to or greater
than 14 in the RECORDSIZE option.
ThE~ minimum bloc~ for DOS format
tapes is 14 bytes.
For example:
100 OPEN 'MTl.ABC' FOR OUTPUT AS FILE 1%, RECORDSIZE 32767%+1%+130%
In this example, the 32767%+1% value sets the sign bit and tells
BASIC-PLUS to use the value specified (130 in this Case) instead of
the default value of 512.
If the sign bit is not set, the system
creates a 512-byte buffer.
If the value given is odd (and the sign
bit is set), BASIC-PLUS rounds the buffer size down to make it even.
PUT statements write blocks on tape equal to the buffer size. You can
use the COUNT option to write tape blocks smaller than the buffer size
but not less than the minimum of 14 bytes.

Processing ANSI Magnetic Tape Files
If the system is processing a tape with ANSI labels, use the
CLUSTERSIZE and FILESIZE options in the OPEN FOR OUTPUT statement to
designate the record format and length, file characteristics, and
block length.
Use the /POSITION switch to specify a section number of
a multivolume file.
The system uses these values to create the corresponding fields in the
file label and to set the I/O buffer size.
The FIL~SIZE and
CLUSTERSIZE options and the /POSITION switch have e£fect only when the
tape being processed has ANSI labels.
The general form of the
statement with options is:
10 OPEN 'MTO:ABC/PO[SITION]:n' FOR OUTPUT AS FILE ~N%,
CLUSTERSIZE Q%, FILESIZE P%, MODE 24576% + M%
You must specify the options in the exact order shown; otherwise, the
system gene~ates the error ?Modifier €!rror.
To apply the system
default for lany option, omit that specification from its place in the
statement.
In the previous example, the system associates tape :unit 0 with the
channel designated by N%.
The system searches for file ABC according
to the value specified by M% in the MODE option.
The value 24576% in
the MODE option ensures that ANSI label processing is done because any
system or device defaults are overridden by the value in the MODE
option.
For the search to succeed, the file name ABC must match the
file identifier in the file label on the tape.
2-14

Magnetic Tape
The value n in the /POSITION switch designates the section number of a
multivolume file.
If you do not specify the /POSITION switch, the
default section number is 1. See the following section "Processing
Multivolume ANSI Magnetic Tape Files."
The value Q% in the CLUSTERSIZE option designates the record length,
record format, and characteristics of the file created. The value
given causes the system to write the appropriate data in the label
fields of the header and end-of-file records on tape.
Table 2··5 shows the label data for values of Q%.
The value specified
with CLUSTERSIZE is the sum of values chosen from Table 2-5.
Table 2-5:

ANSI Magnetic Tape CLUSTERSIZE Values

+ - - - - - - .' - - - - - - - - - - - + - - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
I
I CLUSTERSIZE I
I
Value
I
Label Result
I
I Label Field Name I
+ - - - - - - ., - - - - - - - - - - - + - - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
I

Record Format

0%
I
16384%
I
I 32767%+1%
I -16384%
I
Record Length
I Between 0%
(in bytes)
I and 4095%
I
I
I
I
I
0%
System Dependent I
4096%
(File
I
8192%
Characteristics) I
I
I
I

u = Undefined*
F = Fixed length
D = Variable length
S = Spanned**
For U, always 0%
For F, value gives fixed record
length.
For D, value gives maximum record
length.
For S, value is unused.**
M = carriage control embedded
A = FORTRAN carriage control.
(space) = Implied carriage
control (when printed, line feed
precedes and carriage return
follows each record).

+- - - - - _ .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I * RS~rS/E undefined record format tapes cannot be processed
directly by most other operating systems.
I
I ** RSTS/E does not support ANSI format S records.

I
I
I

+- - - - - - ,. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -- - -- - - - - - - - - - - --+

If you omit the CLUSTERSIZE option from the OPEN FOR OUTPUT statement,
the system applies CLUSTERSIZE 0%.
The system creates a file with
undefin4~d (U) record format and embedded carriage control with record
length 0%.
(Use the default CLUSTERSIZE if you plan to use PRINT to
write a stream ASCII tape.)
2-15

Magnetic Tape
Note
U format records do not conform to ANSI standard
X3.27-l978.
Non-RSTS/E operating systems may not be
able to read tapes with undefined format.
The record length that the CLUSTERSIZE: option specifies is the value
that the system writes in character positions 11 th~ough 15 of the
header 2 (HDR2) label record.
For fixed-length recdrds, this value
should equal the number of bytes you use in the FIELD statement to
subdivide the I/O buffer.
The subdivisions created;to load records
into the I/O buffer then equal the record length on ,the tape label.
For variable-length records, this value should be the maximum length
of a record.
The value P% in the FILESIZE option designates the block length for
the file.
The system writes this value in character positions 6
through 10 of the header 2 (HDR2) label when it opeQs the file.
If
you omit the FILESIZE option (the same as specifying FILESIZE 0%) from
the OPEN FOR OUTPUT statement, the system sets the block length to 512
bytes.
In the FILESIZE option, you must specify a value between 18
(the minimum allowed on ANSI-labeled tape) and 4095.
Because a record
cannot span blocks, the FILESIZE value for fixed-length records must
be a multiple of the CLUSTERSIZE value, and greater 'than the
CLUSTERSIZE value for variable-length records.
In ANSI label processing, the system uses the block length from the
HDR2 label to create the magnetic tape I/O buffer.
This action allows
the program to write blocks of data on tape equal in size to the I/O
buffer.
The block length in the FILESIZE option shquld correspond to
the total size of the I/O buffer defined by the FIELD statement.
You can use the FILESIZE option in ANSI label processing to create an
I/O buffer other than 512 bytes.
The specified block length is
written in the HDR2 label.
The block length on the tape should be an
even number.
If the block length is odd, the system rounds it down
one byte to make the I/O buffer an even number of bytes.
Note that the action of the FILESIZE option in ANSI label processing
is similar to the action of the RECORDSIZE option in DOS label
processing.
However, if you use the RECORDSIZE opti;on in ANSI label
processing, and the value you specify is larger than the block length
in the HDR2 label, the system establishes the I/O buffer at the size
given in the RECORDSIZE option. No advantage is gairied from using a
buffer size larger than the block length.
Thus, DIGITAL recommends
that you do not use the RECORDSIZE option in ANSI l~bel processing.
Data to be written to ANSI-labeled tape is not automatically converted
by RSTS/E to the appropriate ANSI record format.
Your program must
format the data in the I/O buffer before writing the buffer to the
tape.
In addition, data read from an ANSI-labeled tape must be
2-16

Magnetic Tape
interpreted in the appropriate ANSI record format by the program.
It
is not in the scope of this manual to fully describe ANSI record
format; refer to ANSI standard X3.27 - 1978. However, the PIP utility
can create and read ANSI format records (see the RSTS/E utilities
Reference Manual).

Processing Multivolume ANSI Magnetic Tape Files
If you are processing large ANSI magnetic tape files, you can use the
/POSITION switch in the file specification to label files that reside
on more than one volume.
The general form of the statement is:
10 OPEN "MTO:ABC/POSITION:n" [FOR OUTPUT/INPUT] AS FILE N%, MODE M%
where n indicates the volume number of the file.
are:

Legal values for n

OPEN FOR OUTPUT

writes volume number 1 mark on the file

1-9999

Writes the volume number specified on the file.
If you specify a value other than 0 or 1, the file must be
the first data on the tape to ensure sequential processing.

OPEN FOR INPUT

Searches for the first file that matches the filename.ext

1-9999

Searches for the first file that matches both the file name,
file type, and the volume number specified.
If the file is
found but the volume numbers do not match, the error ?Pack
IDs don't match (ERR=20) is returned.

When you are at the the end of a tape and, you know that there is more
data for another tape, issue MAGTAPE function 10 (End-of-Volume Mark
on CLOSE:) before the CLOSE statement. When you issue the CLOSE
statement, this MAGTAPE function writes an ANSI EOV label on the tape
instead of the EOF label.
See the section "The MAGTAPE Function" for
more information on writing an EOV mark.
Multivolume magnetic tape processing works only on ANSI-labeled files.

2-17

Magnetic Tape
Example of OPEN FOR OUTPUT Statement
You can use the MODE values available with OPEN FORi OUTPUT in any
combination as long as they do not spE!cify conflicting operations.
For example:
10 OPEN "MTO:LLL317" FOR OUTPUT AS FILE 2%, MODE 16466%
This statement opens the file LLL317 on tape unit 0 and associates it
with channel 2%. MODE 16466% is the sum of MODE 2% + 16% + 64% +
16384%.
When the system executes line 10, it determines whether the current
label record is in DOS format (MODE 16384%).
If th~ file is not
found, the system does not rewind the tape (MODE 2%); instead it
continues to search for labels in DOS format from the next record on.
If the correct label record is found (that is, LLL317 exists), the
system backspaces one record and writE~s the new label over the
existing label (MODE 16%).
If the 109ical end-of-t~pe is found first,
the system backspaces one EOF record and writes the'new label,
allowing write access to the new file~
Once the new label record is written, the file LLL317 is available for
output.
Since the file is open for output only, attempting to execute
GET or INPUT statements results in thE! error ?Protection violation
(ERR=10)8
The next CLOSE statement rewinds the tape (MODE 64%].

Writing Data and processing

End~f~ape

You can write data to a magnetic tape file with either PUT or PRINT
statements. Do not use both statements to write the same file.
The PUT statement writes the contents of the I/O buffer for the
specified I/O channel to the next sequential record of the file.
general form of the statement is:

The

100 PUT #N%
where N% specifies the internal channe'l on which th~ file is open.
PUT writes a single record to a magnetic tape file. '
The PRINT statement writes stream ASCII data to a magnetic tape file.
Use PRINT only if you plan to use the tape on a RSTS/E system. Other
operating systems may not be able to read BASIC-PLUS stream ASCII
data.

2-18

Magnetic Tape
If RSTS/E finds the physical end-of-tape marker while writing to tape
using a PUT statement, the system writes the entire record and returns
the error ?No room for user on device (ERR=4).
However, if RSTS/E finds the physical end-of-tape marker while writing
to tape using a PRINT statement, the system may not write the last
item printed.
The system returns the error ?No room for user on
device (ERR=4).
The error condition does not harm the data.
GET statements (when the
file is later opened for input) access data at and beyond the marker
without error.
If you see this error, use one of these recovery
procedures:
o

Close the file as soon as the error occurs, and then create
another file on another tape for the remainder of the data.

If the tape is ANSI format and you want to use multivolume
processing, follow these steps:

Issue the SPEC% or MAGTAPE function to write an
end-of-volume mark on the tape.

Close the tape.

Open the next volume of the file as the first file on
another tape. Use the same name, but include the
/POSITION switch to specify the next higher section
number of the file.

Continue writing the file on the next volume.
If the
error ?No room for user on device (ERR=4) occurs again,
go to step 1.

If the file is DOS format or if the file is ANSI format and
you do not want to use multivolume ANSI processing, include a
subroutine that writes a logical end-of-tape mark at the end
of the previous fil~ in the program.
You can then write the
file that generated the error condition to another tape.
Follow these steps:
1.

Backspace with the MAGTAPE function using the maximum
parameter,32767% (see the section "Backspace Function").
Repeat this procedure until the status function (see the
section "Tape Status Function") indicates the tape is at
beginning-of-tape (BOT) or that it detects a tape mark
(end-o£-file [EOF]).

2-19

Magnetic Tape
2.

If no error occurs during the backspac" check the tape
status function (see the section "TapeiStatus Function")
to see whether the tape is at BOT or EOF.
If any error
occurs, the data may be corrupt.

If the tape is at BOT, the file will not fit on the tape.
Write three tape marks (see the sectio$ "Write Tape Mark
Function") to zero the tape, then t r y . longer tape.
Finding BOT should occur only on DOS tapes. ANSI tape
files contain a tape mark between the label records;
thus, the system should find a tape mark before finding
BOT.

If the tape is at a tape mark and is im DOS format, write
three tape marks.
On an ANSI-labeled tape, backspace to
the next tape mark, and then write thr*e tape marks.

The File-Structured Magnetic Tape OPEN
The OPEN statement performs an OPEN FOR INPUT operation for a
designated file on a specific tape unit.
For example:
10 OJ?EN "MTO :ABC" AS FILE N%, MODE 1"1%
The system associates tape unit 0 with the internal channel designated
by N% and searches for the file ABC as if you specify an OPEN FOR
INPUT statement with M% in the MODE specification. An OPEN statement
without a MODE specification is treated the same as ;MODE 0%.
If the
OPEN FOR INPUT operation succeeds, the program has read access to the
file on the channel's buffer.
If the system cannot ;open the file for
input, it performs an OPEN FOR OUTPUT operation using the MODE M%
specification.
Use OPEN FOR INPUT or OPEN FOR OUTPUT instead of OPEN with magnetic
tape.
OPEN FOR INPUT and OPEN FOR OUTPUT allow the ,system to
immediately determine which operation is needed.

The File-Structured Magnetic Tape CLOSE
The CLOSE statement terminates processing of a magnetic tape file.
If
the file is open for input, the system skips to EOF !or EOV (if it is
not already there) and frees~the buffer space for other use within the
program.
If the file is open for output and the file label is in ANSI
format, the system writes a trailer label group (se~ Appendix A).
The
system writes three EOF records to mark the logical iend-of-tape,
regardless of the file label format.
It then backs~aces the tape over
2-20

Magnetic Tape
two of the EOF records to position the tape for later output and frees
the buffer space for other use within the program.
If you issue the WriteEOV Mark on CLOSE MAGTAPE function (code 10)
prior to the CLOSE, the system writes EOV labels instead of EOF
labels.
In addition, the system rewinds the tape if you include the value 64%
in the MODE specification when you open the tape.
Otherwise, the
system does not rewind the tape.

The

Non~ile·Structured

Magnetic Tape OPEN

In non-file-structured processing, the system does no label
processing.
Essentially, the system passes all data directly between
the magnetic tape and the user program.
You can read or write tapes
of any :format with non-file-structured magnetic tape operations, as
long as the program is set up to handle the actual tape format
correctly. You can only write records of 14 bytes or longer.
However, other operating systems may not be able to process records of
less than 18 bytes, which is the minimum record length allowed by ANSI
standard X3.27-l978. Attempting to write a shorter record results in
the error ?Illegal byte count for I/O (ERR=31).
To indicate non-file-structured processing, specify' only the tape unit
in the OPEN statement.
Do not include a file name.
There are three
types of OPEN statements.
The first two are:
100 OPEN "MTO:" FOR INPUT AS FILE 1%
100 OPEN "MTO:" AS FILE 1%
The OPEN FOR INPUT and simple OPEN statements are equivalent. No tape
movement occurs; the system permits both reading and writing of
records.
The third form of the OPEN statement is slightly different:
100 OPEN "MTO:" FOR OUTPUT AS FILE 1%
In this example, the OPEN FOR OUTPUT statement permits writing only.
The next section discusses this method of opening a tape for writing
and the actions that occur on CLOSE~

2-21

Magnetic Tape
The

Non~ile-Structured

Magnetic Tape CLOSE

CLOSE has no special action on non-file-structured tapes unless you
used an OPEN FOR OUTPUT statement. On a magnetic t~pe that is open
for output, the CLOSE statement causes three traili~g tape marks to be
written, followed by backspacing over two of these tape marks, which
positions the tape correctly for later output operations.
In any case, if the tape is open for non-file-structured processing,
it is not rewound on CLOSE.

The MODE Specification in Non~ile-Structured Processing
The MODE specification in non-file-structured magnetic tape processing
can be used with some 9-track devices to indicate pqrity.
For 800 bpi
tape density, the standard parity is odd.
DIGITAL 40es not recommend
using the MODE specification to specify even parity~ DIGITAL
recommends the use of odd parity.
Even parity, although available,
cannot be used to write binary data.
In addition, few other operating
systems (or tape drives) support the use of even parity.
For 1600 bpi tape densities, parity is odd and nons~lectable.
system ignores any attempt to specify even parity in the MODE
specification.

The

See Table 2-2 for information on the density of 9-track devices.
MODE in the OPEN statement is evaluated by the following algorithm:
D+P+S
where:
D (density) is:
12 = 800 BPI
256 = 1600 BPI
P (parity) is:

o = odd parity
1

= even parity

S (stay) is:

o = MODE value does not stay after CLOSE
8192

MODE value stays after CLOSE

Magnetic Tape
If you do not specify a MODE value in the OPEN statement, the system
processes the tape using the system density default and odd parity.
If you add 8192% to the MODE value, the associated parity and density
settings remain in effect for the job if the tape unit was allocated
to the job, even after the channel has been closed.
To allow read and write access to a tape, use the OPEN or OPEN FOR
INPUT statement.
For example:
100 OPEN "MTO:" AS FILE 1%, MODE 12%
100 OPEN "MTO:" FOR INPUT AS FILE 1%, MODE 12%
Either statement makes the tape on the 9-track drive unit 0 available
for execution of GET and PUT statements on channel 1%.
The system
accesses tape with a density of 800 bpi and odd parity.
The system
does not perform tape positioning or status checking.
You must
perform such operations using the MAGTAPE function described in the
next section.
To allovv only write access to a tape, use the OPEN FOR OUTPUT
statement.
For example:
OPEN "MTl:" FOR OUTPUT AS FILE 1%, MODE 12%
If the unit is write-locked (that is, the write-enable ring on the
reel is removed), the system generates the error ?Device hung or write
locked (ERR=14) and does not open the device.
Otherwise, the
statement makes the tape on unit 1 available for execution of PUT
statements on channel 1%.
Since the device is open solely for write
access, an attempt to execute a GET statement on the channel causes
the error ?Protection violation (ERR=lO).
The system writes records
in odd parity at a density of 800 bpi.
Your program must check the
status of the device and control the device by use of the MAGTAPE
function described in the next section.
To read and write records larger than 512 bytes, include the
RECORDSIZE option in the OPEN statement.
For example:
100 OPEN "MTO:" AS FILE 1 9,.o ,

RECORDSIZE 1000%, MODE 12%

This statement associates the tape on unit 0 with channel 1%.
The
RECORDSIZE option creates a buffer of 1000 bytes.
If insufficient
memory is available, you see the error ?Maximum memory exceeded.
You
must then either reduce the size of the program or increase the
maximum size to which the job can grow.
The buffer length must be an
even number greater than 512.
If the number given is odd, the system
rounds it down one byte to make it even.
If the number is less than
512, the system uses the default buffer length of 512.

2-23

Magnetic Tape
Subsequent GET and PUT operations on channel 1% read and write records
1000 bytes long. Attempting to read a record longer than the buffer
generates the error ?Magtape record length (ERR=40). The RECOUNT
variable contains the number of bytes read.
To write records smaller than the buffer size, open the device
normally and specify the COUNT option in the PUT statement. For
example:
205 PUT #1%, COUNT 76%
This statement writes a 76-byte record.
If you do not use COUNT, PUT
writes an entire buffer, regardless of whether the buffer contains
meaningful data. A record must be at least 14 bytes: (18 bytes to
conform to the ANSI standard), and no larger than the I/O buffer.
If a record smaller than the buffer size is read, the BASIC-PLUS
RECOUNT variable contains the number of bytes read. Every input
operation on any channel (including channel 0) sets RECOUNT. Thus,
you should test or save RECOUNT immediately after each GET statement.

The MAGTAPE Function
The MAGTAPE function gives a program control over all magnetic tape
operations. You can use MAGTAPE in either file-structured or
non-file-structured processing, although it is mainly used in
non-file-structured processing.
The general form of the MAGTAPE function is:
I% = MAGTAPE (F%,P%,U%)
where:
F%

is the function code (1 to 12).

is an integer parameter.

is the internal channel number on which the selected tape is
open.

is the value returned by the function.

F% determines the effect of the MAGTAPE function. The following
sections describe these functions, beginning with f~nction code 1. In
all examples in these sections, assume that tape unit 1 is open on
channel 2.

2-24

October 1985

Magnetic Tape

Table 2-6 summarizes the MAGTAPE function codes and includes the
designations IMMEDIATE and WAIT.
IMMEDIATE means that the monitor
starts the action and returns control to your program immediately;
WAIT means that the monitor returns control to your program only after
the operation is complete.
Table 2-6:

MAGTAPE Function Summary

+- - _ .. - - - - - - - _ .. _ .. - - - - - - - -+- - - -+- - - - - - - - - -+- - - - - - - - - - - - - - -+- - - - - - - - - - --+

Action

I
I
I
ICodel Parameter I

Value
Returned

I wait or
I Immediate

+- - _ .. - - - - - - - _ .. - - - - - - - - - -+- - - -+- - - - - - - - - -+- - - - - - - - - - - - - - -+- - - - - - - - - - --+
I
I

Rewind and offline

Write tape mark

1 IUnused
I

2 IUnused

Rewind

3 IUnused

Skip record

4 IRecords to Records not
skipped
skip

Backspace over record
Set density and parity

iWait
I

I Immediate
I

Records to Records not
backspace backspaced

I Immediate
I

D+P+S

IWait
I
I

Iwait
I
I

I Immediate

Tape status function

Unused

File characteristics

Unused

Rewind on CLOSE

9 IUnused

End-of-volume (EOV)
labels on CLOSE

10 jUnused
I

Error condition
acknowledged
(only meaningful for
asynchronous I/O)

11 IUnused

Extended
set density

12 IDensity tolActual Density IImmediate
Iset/check Iset/checked
I

IStatus

I Immediate

IFile
I Immediate
Icharacteristicsl

I
I
I
I

I
I
I

0
0
0

I Immediate

I Immediate
I

IWait

I
I
I
I

+- - _. - - - - - - - _ .. - ,. - - - - - - - -+- - - -+- - - - - - - - - -+- - - - - - - - - - - - - - -+- - - - - - - - - - --+

October 1985

2-25

Magnetic Tape
Off-line (Rewind and Off-line) Function
Function code
Parameter
Value returned

1
unused

The OFF-LINE function causes the specified magnetic tape to be rewound
and set to OFF-LINE.
For example:

200 I%

= MAGTAPE(1%,0%,2%)

This statement rewinds and sets the
channel 2 to OFF-LINE.

ma~gnetic

tape open on internal

Write Tape Mark Function
Function code
Parameter
Value returned

unused

The Write Tape Mark function writes one tape mark record at the
current position of the magnetic tape.
For example;

200 I%

= MAGTAPE(2%,0%,2%)

This statement writes a tape mark on the magnetic tape that is open on
internal channel 2.

Rewind Function
Function code
Parameter
Value returned

3
unused

The Rewind function rewinds the selected magnetic tape.

200 I%

For example:

= MAGTAPE(3%,0%,2%)

This statement rewinds the magnetic tape open on internal channel 2.
(This function does not cause the tape to be set to; OFF-LINE.)
i

2-26

Magnetic Tape
Skip Record Function
Function code
Parameter
Value returned

number of records to skip (1 to 32767)
number of records not skipped (0 unless the system
finds a tape mark)

The Skip Record function advances the tape.
The tape continues to
advance until either the specified number of records is skipped, in
which case the value returned by the function is 0, or a tape mark is
encountered, in which case the value returned is the specified number
of records to skip minus the number actually skipped.
(The system
counts the tape mark as a record skipped.) For example, to skip from
the current tape position to just past the next tape mark, use the
function:
200 1%

= MAGTAPE(4%,32767%,2%)

This statement assumes there are fewer than 32767 records before the
next tape mark.
In the section, "Tape Status Function," a more
complex example using the MAGTAPE function shows how to skip an entire
file regardless of the number of records.

Backspace Function
Function code
Parameter
Value returned

5
number of records to backspace (1 to 32767)
number of records not backspaced (0 unless the
system finds a tape mark or BOT)

The Backspace function is similar to the Skip function, except that
tape motion is in the opposite direction.
The beginning-of-tape (BOT
or Load Point) as well as tape marks can cause premature termination
of the Backspace operation, in which case the value returned is the
specified number of records to backspace minus the number actually
backspaced.
(The system counts the tape mark as a record actually
backspaced.) The BOT is neither skipped nor counted as a skipped
record.
For example:
200 1% = MAGTAPE(5%,1%,2%)
This statement backspaces one record on the magnetic tape opened on
internal channel 2, unless the tape was already at BOT.

2-27

Magnetic Tape
Set Density and Parity Function
Note
This function does not support the TK25, or TK50
magnetic tape drives. It is provided only for
compatibility with existing software. DIGITAL
recommends that the Extended Set Density Function
(code 12) be used in future program development.
Function code
Parameter
Value returned

D+P+S

where:
D (density) is:
12
256

800 bpi
1600 bpi

P (parity) is:

o = odd parity
1

even parity (not recommended; see the section "The
MODE Specification in Non-File-Structured Processing")

S (stay) is:

o
8192

MODE value does not stay after CLOSE
MODE value stays after CLOSE

A tape drive is set to the system default for density and odd parity
unless you change the default when you allocate theiunit (with a MOUNT
command) or when you open the unit. If the tape dr~ve has more than
one density and/or parity option available, this fu6ction changes the
density and/or parity according to the value given as the parameter.
See Table 2-2 for information about 9··track tape drive densities, and
the section "The MODE Specification in Non-File-Structured Processing"
for information on parity settings.
The system interprets the parameter exactly as it d~es the MODE value
in a non-file-structured OPEN statement. For example:
10

OPEN "MMO:" AS FILE 2 ~5

1% = MAGTAPE(6%, 256%, 2%)

These statements set the density and parity of the 9-track tape drive
open on channel 2 to 1600 bpi, odd parity. The density and parity
2-28

October 1985

Magnetic Tape
that you specify in the parameter are in effect until channel 2 is
closed.
The system sets I% to 0 to indicate successful completion.
If you execute this function on a tape open in file-structured mode,
the system ignores the request and returns the same value as the one
passed.
If the unit is allocated, adding 8192% to the parameter value (making
it 8192%+256%) keeps the new density/parity setting in effect even
after the associated channel is closed.
The next OPEN statement
without a MODE option, associating any channel number with tape unit
0, automatically opens it with that new density/parity setting.
A
DISMOUNT command for a previously allocated unit returns the
density/parity setting for the tape unit to the system default value.
Specifying another parameter value also changes the density and parity
setting.
The setting remains if ownership of the unit is passed to
another job.
The following immediate mode routine sets tape unit 2 to 800 bpi, odd
parity, using DOS labels.
In this example, once channel 3 is closed,
the new density/parity setting is now in effect and remains in effect
until a DISMOUNT operation- is executed on tape unit 2.
ASSIGN MM2:.DOS
OPEN "MM2:" AS FILE 3%
1% = MAGTAPE(6%, 8192%+12%, 3%)
CLOSE 3%

Tape status Function
Function code
Parameter
Value returned

unused
status

The Tape Status function returns the status of the specified magnetic
tape as a 16-bit integer, with certain bits set, depending on the
current status.
Table 2-7 shows the status word format.

2-29

Magnetic Tape
Table 2-7:

Magnetic Tape status Word

+ - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - + - - - - - ., - - - - - - - - - - - - - .. - - - - - - - - - - - - - - - - - +

Bit

Test

Meaning

+ - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - + - - - - - ., - - - - - - - - - - - - - ~ - - - - - - - - - - - - - - - - - +

ILast command caused:an
11% < 0%
1
1
14-13 1 ( 1% AND 24576%)/8192% I If bit 3 = o, density:
1
I
1
I
1
I
1
I
1 , densiti:y:
I If bit 3
1
I
I
15

12
11
10
9
8
7
6

5
4
3

error.
0
1
2
3

reserved
reserved
reserved
800 bpi

0
1
2 =
3

1600 bpi
reserved
reserved
reserved

I
1
I ( 1% AND 4096%) = 0%
I ( 1% AND 4096%) <> 0%
I
I ( 1% AND 2048%) = 0%
I ( 1% AND 2048%) <> 0%
I
I ( 1% AND 1024%) <> 0%
I
I ( 1% AND 512%) <> 0%
I
I ( 1% AND 256%) <> 0%
1
I ( 1% AND 128%) <> 0%
I
I
1(1% AND 64%) <> 0%
I
I
I
I
I ( 1% AND 32%) <> 0%
I
1(1% AND 16%) = 0%
1%
I ( 1% AND 16%)
I
I ( 1% AND 8%) = 0%
1%
1(1% AND 8%)

1
I
19-track tape.
IReserved.
I
IOdd parity.
IEven parity.
I
ITape is physically write-locked.
I
ITape is beyond physical EOT marker.
I
ITape is at BOT (load point) .
I
ILast command detected a tape mark
I (EOF marker).
I
IThe last command was READ and the
Irecord read was longer than the I/O
Ibuffer size (that is, part of the
Irecord was lost) .
I
IUnit is nonselectable (OFF-LINE).
I
IUnit does not accept 1600 bpi.
IUnit accepts 1600 bpi.
I
ISee values for bits 14-13.
ISee values for bits 14-13.

2-30

Magnetic Tape

Table 2-7 (cont.)
+ - - - - - - -+ - - - - - - - - - - - - - - - - - - - - - -+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+
Bit
Test
Meaning
I
+. - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
I
I
IIndicates last command issued:
2-0
1(1% AND 7%)
OFF-LINE
I a
I
1
READ
I
I
2
WRITE
I
I
WRITE TAPE MARK
3
I
I
4
REWIND
I
I
SKIP RECORD
5
I
I
BACKSPACE
RECORD
6
I
I
+. - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +

Note
Bits 3, 4, and 11 to 14 are maintained only for
backwards compatibilty.
DIGITAL recommends that you
use the Extended Set Density Function (code 12) for
all future software development.
The following example obtains the status of the magnetic tape opened
on internal channel number 2:
200 1%

= MAGTAPE(7%,0%,2%)

When the value of 1% returned is 24,848 decimal (or 60420 octal), the
magnetic tape is 800 bpi, 9-track, odd parity, and the last command
issued was OFF-LINE.
You can determine this information by testing
the value of 1%, bit by bit, against Table 2-7.
For example:
1%

24,848 (decimal)

a 4 2 a (octal)

110 000 100 010 000 (binary)
The test for density uses bits 14 and 13:
(1% AND 24576%)/8192%
The following diagram shows the result:
1% 110 000 100 010 000
AND 24576% 110 000 000 000 000
Result 110 000 000 000 000

October 1985

2-31

Magnetic Tape
If you divide the result of (1% AND 24576%), which in this example is
24576%, by 8192%, the quotient can equal 0, 1, 2, ot 3. In this case,
24576/8192 = 3, indicating that the tape density is 800 bpi.
The results of bit 12 (1% AND 4096%) and bit 11 (1% AND 2048%) are
both zero, indicating a 9-track tape with odd parity.
!

Bit 8 (1% AND 256%) and bit 4 (1% AND 16%) both ret~rn a value of 1,
indicating that the tape is at the load point and that the unit
accepts 1600 bpi.
Bit 2-0 (1% AND 7%) returns a value of 0, indicating the last command
issued was OFF-LINE.
Use the Skip Record function to advance to the next tape mark (that
is, skip over the current file). You can use one Skip Record function
unless the file is longer than 32,767 records (in which case the
system must execute several skip record functions) or the system
detects a physical EDT within a file.
The following statements
execute a Skip Record function until the next tape mark is found:
20 1%

= MAGTAPE(4%,32767%,2%)
!Do some skips &
\GOTO 20 UNLESS (MAGTAPE(7%,0%,2%) AND 128%),Do more unless &
!tape mark found

Return File Characteristics Function
Function code
Parameter
Value returned

= unused
file characteristics

This function r~turns the status of the specified file-structured
magnetic tape file as a 16-bit integer, with certain bits set
depending on the current file characteristics. Nonzero integers are
returned for ANSI files; zero is always returned fo~ DOS files.
Table 2-8 shows file characteristics vlord for ANSI format.

2-32

Magnetic Tape
Table 2·8:

Magnetic Tape File Characteristics Word for ANSI Format

+ - - - - - _.f- - - - - - - - - - - - - - - - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
1 Bit 1
Test
Meaning
+ - - - - - _.f- - - - - - - - - - - - - - - - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
1

,ANSI format:
U (undefined)*
I
0
1
F (fixed-length)
I
2
D (variable-length)
3
S (spanned)**

15-141 (SWAP%(I%) AND 192%)/64%
1

1 3 - 12 1 ( I % AND 12288 %) /4096 %
1

IFormat U operation:
1
0 (default)

IFormat D, Sand F operation:
1
0 (embedded carriage control)
1 (FORTRAN carriage control)
2 (implied LF/CR)

1
1
1

11 - 0 1I % AND 4 09 5 ~i

Format U operation:
o = (default)

Format F operation:
Record length

Format D operation:
Maximum record length

Format S operation:
unused**

+- - - - - _ .. - - - - - - - - - - - - - - - - - - - - - - - - - -

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

* ANSI format U does not conform to ANSI standard X3.27-l978
I ** RSTS/E does not support ANSI format S

+- - - - - _ .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

The following example obtains the characteristics of a file on a
magnetic tape opened on channel 2:
400 I%

= MAGTAPE(8%,0%,2%)

When the value of I% returned is 16464 (16384% + 64% + 16%) decimal
(40120 octal), the magnetic tape file is in ANSI format F, carriage
control is embedded "M", and the record length is 80 bytes.
You can
determine this information by testi'ng the value of I%, bit by bit,
against Table 2-8.
For example:
I%

16464 (decimal)
o 4 0 1 2 0 (octal)
o 100 000 001 010 000 (binary)

2-33

Magnetic Tape
The test for ANSI format type is (SWAP%(I%) AND 192%)/64%, where 192%
128% + 64%.
SWAP%(I%)

a 101 000 001 000 000

AND 192%

11 000 000

Result

1 000 000

Dividing the result of SWAP%(I%) AND 192% (which in this case is 64%)
by 64%, the quotient equals 64%/64% = 1, indicating that the tape file
is in ANSI format F.
The result of (1% AND 12288%)/4096% is a in this example, indicating
that the carriage control is embedded "M".
Finally, the result of (1% AND 4095%) yields 80 in this case, so the
record length is 80 bytes.

Rewind on CLOSE Function
Function code
Parameter
Value returned

9
unused

The Rewind on CLOSE function causes the selected magnetic tape to be
rewound when the CLOSE statement is executed.
For ~xample:
1%

MAGTAPE(9%,0%,2%)

This statement rewinds the tape open on internal channel 2 when you
issue CLOSE from a program or in immediate mode.
You must use the Rewind on CLOSE function after the OPEN statement and
before the CLOSE statement.
This function overrides all MODE
specifications that, in the OPEN statement, instruc~ the system not to
rewind on closing the file.
Once the system executes the Rewind on
CLOSE function, it cannot be cancelled.

2-34

Magnetic Tape

write End-of-Volume Labels on CLOSE Function
Function code
Parameter
Value returned

10
unused

This function writes end-of-volume (EOV) labels on the selected ANSI
magnetic tape when the close statement is executed.
This function is
mainly for multivolume ANSI processing.
For example:
1%

MAGTAPE(lO%,O%,2%)

This statement causes EOV labels to be written to the file on
execution of the CLOSE statement.
Normally, end-of-file (EOF) labels
are written.
You must use the write End-of-Volume Labels function
after the OPEN statement and before the CLOSE statement.
This function works only on ANSI labeled magnetic tapes.
An attempt
to write end-of-volume labels on DOS-labeled or non-file-structured
tapes results in the error ?Illegal MAGTAPE () usage (ERR=65).

Error Condition Acknowledged
Function code
Parameter
Value returned

11
unused

This function acknowledges an error condition that has occurred during
an asynchronous I/O operation.
When an error occurs while performing
asynchronous I/O, the tape driver does not execute any more requests
until this function has been issued.
This is because asynchronous I/O
allows multiple requests to be outstanding, but they may be invalid if
the user knows of the error condition that occurred.
All requests
between the original errored request and the error condition
acknowledged function call return the error ?Device hung or write
locked (ERR=4).
Once the error condition acknowledged function has
been issued, the driver resumes normal processing, on the assumption
that the user is aware of the error and is taking whatever steps are
appropriate to correct it.
For example:
1% = MAGTAPE(11%,O%,2%)
This statement acknowledges the error condition that occurred from the
asynchronous I/O operation on the magnetic tape open on internal
channel 2.
The Error Condition Acknowledged function returns no errors and will
never fail when issued.
If not required, it is simply ignored.

2-35

Magnetic Tape
Extended Set Density Function
Function code
Parameter
Value returned

12
Density to set/check
Actual density

You can use this function to set the density of a t$pe drive, or get
density information about a drive. The action that: RSTS/E takes
depends on the value of the parameter.
If the parameter value is zero, RSTS/E returns the ~urrent density of
the tape drive.
If bit 15 is set, RSTS/E attempts to set the density
of the tape drive to the value in bits 14-0 as folllPws:
Value

Meaning

32767

Sets the density to the highest legal density allowed
for that tape drive. The value ret~rned is the
density set. No error is returned.

Sets the density to the lowest legal density allowed
for that tape drive. The value returned is the
density set. No error is returned.

Attempts to set the density to the value specified.
If the value is not legal for that tape drive, RSTS/E
returns an ?Illegal number error me$sage (ERR=52) and
leaves the density of the drive unc~anged.

If bit 15 is clear, RSTS/E does not change the drive's density but
only tests the value passed in bits 14-0 as follows~
Value

Meaning

32767

Returns the highest legal density for this drive

Returns the lowest legal density for this drive

Returns the nearest legal density for this drive that
is not greater than the parameter v~lue.
If the
parameter value is less than the drive's lowest legal
density, RSTS/E returns the lowest possible density.

Any density changes made by this call" remain in effect until either a
new density is set or a magnetic tape is read that has a density
different than the one formerly set. This action i~ equivalent to the
STAY value 8192% in the Set Density and Parity Function (function code
6)•

2-36

October 1985

Magnetic Tape
Note
For MT, MM, and MU tape drives, a tape must be
mounted and be at beginning-of-tape (BOT) to set the
drive density.
If this condition is not met and an
attempt is made to change the drive's density, RSTS/E
returns an ?Illegal MAGTAPE ( ) usage error message
(ERR=65).
A tape does not have to be mounted on the
drive to check legal densities or return the current
density of a drive.

Asynchronous I/O Requests
An asynchronous read or write request performs the same basic function
as the traditional synchronous read or write request: it moves data
between a device and a program.
The difference lies in the completion
of the request.
While a synchronous request stalls the job's
execution until the request is complete, an asynchronous request does
not stall the program.
The program continues to run while the I/O
request completes in the background.
When the asynchronous I/O request completes, the system informs the
program that issued the request of the completion and status of the
request.
The system notifies the program by forcing it to run an
asynchronous completion routine to notify the user job of the I/O
completion.
The asynchronous completion routine is a section of code
within the user job that executes when an I/O request completes.
When
the asynchronous completion routine is entered, it can check for any
device dependent errors.
Asynchronous I/O is only meaningful on MS: tapes (TS11, TK25, TSV05,
TUBO).
Other tape drives accept asynchronous I/O requests and emulate
asynchronous behavior, but the job stalls and few advantages are
gained from its use.
BASIC-PLUS programmers cannot use asynch~onous I/O.
BASIC-PLUS-2
programmers can use this feature, but must do so using a MACRO
subroutine.
See the RSTS/E System Directives Manual for details.

Magnetic Tape Special Function: SPEC%
The SPEC% function performs special operations on magnetic tape, disks
(see Chapter 1), flexible diskettes (see Chapter 1), line printers
(see Chapter 3), terminals (see Chapter 4), and pseudo keyboards (see
Chapter 4).

October 1985

2-37

Magnetic Tape

The SPEC% function for magnetic tape performs the same operations as
the MAGTAPE function.
It allows you to rewind the tape, skip records
on the tape, and set tape density and parity.
See the section "The
MAGTAPE Function" for details.
The SPEC% function for magnetic tape has the format~
VALUE%=SPEC%(FUNCTION%,PARAMETER,CH1~NNEL%,14%)

where:
VALUE%

depends on the function code specified in FUNCTION%.

FUNCTION%

is the function code.

PARAMETER

depends on the function code specified in FUNCTION%.

CHANNEL%

is the I/O channel on which the operation is to be
performed.

14%

is the handler index for magnetic tape.

The code you specify in FUNCTION% determines the op~ration performed.
These operations duplicate those performed by the MAGTAPE function
codes (see Table 2-6).
The following MAGTAPE and SfEC% functions are
equivalent:
1% = MAGTAPE(F%,P%,U%)
1% = SPEC%(FUNCTION%-1%,PARAMETER,CHANNEL%,14%)

Magnetic Tape Error Handling
RSTS/E recognizes the following magnetic tape error conditions:
o

Parity error

Record length error

Offline (not ready) error

Write lock error

Write beyond EDT error

For other error conditions that can occur with magn~tic tape (Illegal
byte count, File exists, Protection violation), see: Appendix C.

2-38

Magnetic Tape
Parity (Bad Tape) Error
If the system detects a parity error on a read attempt, it tries to
reread the record up to 15 times.
If the error condition persists,
the error ?Data error on device {ERR=13) occurs.
In this case, the
read has been completed, but the data in the I/O buffer cannot be
considered correct.
On an output operation, if the first attempt to write a record fails,
the system tries to rewrite the record up to 15 times using write with
Extended Inter"record Gap to space past a possible bad spot on the
tape.
If the error condition persists, the error ?Data error on
device (ERR=13) occurs.
In both cases, the tape is positioned just
past the record on which the error occurred.
If you have error logging on your system, a magnetic tape error is
logged for each parity error that occurs.
Consult the ERRDIS full
error report to see if the problem is due to a malfunctioning or
poorly aligned magnetic tape drive.

Record Length Error
The record length error can occur only during a read operation when
the record on the tape is longer than the I/O buffer size, as
determined by the OPEN statement.
The extra bytes in the record are
not read into memory but are checked for possible parity errors.
If a
parity error occurs, the error ?Data error on device (ERR=13) is
returned to your program, and bit 6 of the tape status word is set.
Therefore, if you are reading records of unknown length from magnetic
tape, you must check for possible record length errors after every
read operation.
Use a statement of this form:
200 PRINT "RECORD TOO LONG" IF MAG/rAPE (7%,0%,2%) AND 64%
Note that if bit 6 is set in the tape status word, the IF condition in
this example tests as TRUE.
The error ?Magtape record length error
(ERR=40) occurs when the tape block is too long, in either
file-structured or non-file-structured magnetic tape.

Offline Error
The system determines the status of the tape unit by testing bit 5 of
the returned value of the tape status function shown in Table 2-7.
If
bit 5 is set, the tape unit is offline.
The error ?Magtape select
error (ERR=39) occurs if you attempt to access an offline drive.

2-39

Magnetic Tape
write Lock Error
Attempting any write operation on a magnetic tape that is physically
write-locked (that is, a tape that does not have the write-enable ring
inserted) results in the error ?Device hung or write locked (ERR=14).

Writing Beyond EOT Error
Attempting to write a record beyond the end-of-tape reflective marker
writes the entire record but returns the error ?No room for user on
device (ERR=4).
This error condition is a warning to the user
program; it does not harm the data.
The program cah recover in one of
two way S i S e e the sec t ion "w r i tin g Da t a and Pro c e s s :i n g End - 0 f - Tap e . "

Magnetic Tape Programming Examples
The following examples show how to read and write a magnetic tape
file.

Writing a Magnetic Tape File
The following BASIC-PLUS program opens an existing magnetic tape file
for output and appends data to the file:
100

M%=16384%+128%+64%+32%
\OPEN "MMO:RECORD.FIL" FOR OUTPUT AS FILE 1%1, MODE M%
\FIELD #1%, 2% AS S$, 8% AS M$, 2% AS Y$, 8%! AS C$, 2% AS D$
\INPUT "HOW MANY RECORDS TO ENTER"iA%
400
FOR 1%=1% TO A%
\INPUT "RECORD";S%
\INPUT K$
\INPUT Y%
\INPUT L$
\INPUT D%
500 LSET S$=CVT%$(S%)
\LSET Y$=CVT%$(Y%)
\LSET D$=CVT%$(D%)
\LSET M$=K$
\LSET C$=L$
\PUT 1%, COUNT 22%
\NEXT 1%
\CLOSE 1%
3000 END

The program opens the file RECORD.FIL, which is on a DOS tape (MODE
16384%), for append (MODE 128%).
The system rewind~ the tape before
2-40

Magnetic Tape
it searches for the file (MODE 32%) and when it executes a CLOSE
statement on the file (MODE 64%).
After the user types in each
record, the program converts the data, builds a record, and writes the
record to the file.
Finally, after all records have been written, the
program closes the file and ends.

Reading a Magnetic Tape File
The following BASIC-PLUS program opens a magnetic tape file for input
and reads records from the file.
It assumes a file in which records
are identifiable by an integer key.
For example:
150

M%=16384%+64%+32%
\OPEN "MMO:RECORD.FIL" FOR INPUT AS FILE 1%, MODE M%
200
INPUT "HOW MANY RECORDS"; F%
210
FOR 1%=:1 % TO F%
\N%=O%
\INPUT "RECORD TO FIND";J%
300 GET #1%
\FIELD #1%, 2% AS S$, 8% AS M$, 2% AS Y$, 8% AS C$, 2% AS D$
500 N%=N%+I%
\S %=CV'!l$ %( S$ )
\GOTO 300 IF J%<>S%
625 Y%=CVT$%(Y$)
\D%=CV'!l$ %(D$ )
750
PRINT S%
\PRINT M$
\PRINT Y%
\PRINT C$
\PRINT D%
\T%=MAGTAPE(5%,N%,1%)
\NEXT 1%
\CLOSE 1%
2000 END
The program opens the magnetic tape file RECORD.FIL on I/O channel 1
with read access only.
The tape is in DOS format and is rewound both
before the system searches for the file and when the system closes the
file (MODE 16384% + 32% +64%).
The program searches for the record
the user specifies and converts the data in the record to a
recognizable form before printing it.
Because magnetic tape is a sequential access device, the program uses
the MAGTAPE function to backspace the tape to the beginning of the
file follo~ing each record retrieval.
This allows the user to request
records in any order.
Finally, the program closes the file and ends.

2-41

Magnetic Tape
Reading a Magnetic Tape Non-File-Structured
The following program reads a DOS magnetic tape label record.
Appendix A for a description of the DOS label forma~.

See

100
110

DEF FNZ$(Z$)=RAD$(SWAP%(CVT$%(Z$)))
INPUT "WHICH DRIVE"iM$
\OPEN M$ AS FILE 1%
200
FIELD #1%, 2% AS F$, 2% AS N$, 2% AS X$, 1% AS p$, 1% AS J$,
1% AS C$, 1% AS uS, 2% AS D$, 2% AS Ul$
\GET #1%
250
Fl$=FNZ$(F$)+FNZ$(N$)+"."+FNZ$(X$)
300 P%=ASCII(P$)
\J%=ASCII(J$)
\C%=ASCII(C$)
400 D%=SWAP%(CVT$%(D$))
\Y$=DATE$(D%)
500 PRINT Fl$,P%,J%,C%,Y$
600 CLOSE 1%
32767 END

The program opens the tape for non-file-structured :processing on I/O
channell.
No MODE specification is necessary beca~se the tape is
9-track, 800 bpi, odd parity.
After reading the l4!-byte label record,
the program converts the file name (bytes 0-5) from Radix-50 notation
to the ASCII character string Fl$.
The program then converts the
project-programmer number (PPN) and protection code: (p$, J~, and C$)
to integer format.
It next changes the creation da:te of the file (D$)
to PDP-II internal form and uses the DATE$ function: to obtain the
creation date in DD-MMM-YY format.
Finally, the program prints all
the .label informa ti on and ends.

2-42

Chapter 3
Line Printer

RSTS/E provides several MODE and RECORD options as well as one SPEC%
function for controlling line printer output.
It also provides a
FILESIZE modifier to enable extended software formatting.
This
chapter describes these options.
In addition, it describes special
character handling for line printers.

Special Character Handling
Certain nonprinting characters have special significance on line
printer output.
Table 3-1 summarizes LPll operation under RSTS/E for
each of these special characters.
Table 3-1:

LP11 Characters

+- - - - - - - - - - -+- _ .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Character
LPll Action
+I ___
.' _____ • _+I __ fi. __ . ______ . __ . __ . _. _______
. _. ________________ . _______ +I

I
I CHR$(8)

I
I BS . Backspace. This action depends on the /BACKSPACE
I

I
I
I
I

CHR$(9)

qualifier of the SET PRINTER command.
1. Prints line
2. Returns carriage
3. Spaces to position immediately before previous
position on line

I
I Tab - Horizontal Tab. This action depends on the /TAB
I qualifier of the SET PRINTER command.
1. Spaces over to next tab position (columns 1, 9,
I
I

CHR$(10)

LF' .
1.
I
2.
I
3.
I
I

17, 25, and so on)

Line Feed
Prints line
Returns carriage
Advances paper one line
3-1

Line Printer
Table 3-1:

LP11 Characters (Cont.)

+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ~ - - - - - - - - - - - - - - - --+

I Character I

LP11 Action
I
+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

CHR$(ll)

VT - Vertical Tab
1. Advances paper one line and resets line counter

CHR$(12)

FF 1.
2.
3.

CHR$(13)

CR 1.
2.
3.

Form Feed
Prints line
Returns carriage
Advances paper to the top of the next form (see
the section, Line Printer Control with the MODE
Option)
Carriage Return
Prints line
Returns carriage
No line feed (may be used for overprint)

I
I

I
I
I
I
I
I

I
I
I
I
I

I
I

CHR$(96)
Lowercase printing characters, converted to uppercase
I
to
except on an uppercase/lowercase printer.
I
CHR$(126)
I
+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - _ .. - - - - - - - - - - - - - .. - - - - - - - - - - - - - - - --+

Line Printer Control with the MODE Option
The MODE specification in the OPEN statement allows you to control
line printer operations.
For example~
OPEN "LP:" AS FILE N%, MODE M%
The system associates line printer unit 0 with channel N%.
The value
of M% in the MODE specification determines the actions the system
performs at the line printer.
Table 3-2 shows the line printer MODE values.

3-2

Line Printer
Table 3·2:

Line Printer OPEN MODE Values

+ - - • - - - - - - - - -+ - . - - - - - .. - - - - - - - - - - - - - - - - - - - - - . - - - - - - - - - - - - - - - - - - - - - - --+
I MODE Value I
Line Printer Action
+- - - - - - - - - - - -+- - - - - - - - _. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - _. - - - - - - - - --+

0% to 127%

Defines form length in number of lines per page. 0%
indicates the default form length. You set the
default form length with the SET PRINTER command.
Also included when specifying nonstandard form length
with software formatting (512%) and/or automatic page
skip (2048%). This feature is maintained for backward
compatibility only. Use the FILESIZE form (see the
next section) in all new program development.

128%

Changes the character 0 (zero) to the letter 0
("oh").

256%

Truncates lines that are longer than the form width.
If MODE 256% is not set, then lines longer than the
form width are wrapped onto the next line.

512%

Enables software formatting. Allows special
characters to position paper at a specific line.

1024%

Translates lowercase characters to uppercase
characters.

2048%

Skips six lines (that is, skips over perforation) at
the bottom of each form.

4096%

Enables hardware form feed.

Suppresses form feed on CLOSE. Normally, two form
feeds are generated whenever the line printer is
closed.
+- - - - - _ .. - - - - -+- - - - - - - - - - - - - - - - - - - - - - - _. _. - - - _ ..•• - - - - - - _ •. - - - - - _ ••• --+
0192%

Line Printer Control with the FILESIZE statement
The FILgSIZE specification in the OPEN statement allows you to use
extended software formatting.
This feature handles a line printer
form length specification of up to 255 lines.
It also enables two
additional mode values:
Change <ESC> to $ - MODE 16%, and Set NOWRAP
- MODE 32%.
You enable extended software formatting with a FILESIZE 32767%+1%
modifier in the OPEN statement.
For example:
10 OPEN "LP:" AS FILE 1%, FILESIZE 32767%+1%+N%, MODE M%
3-3

Line Printer
The system associates line printer unit 0 with chanoel 1. The value
N% specifies the form length and can be any value from 0-255. A value
of 0 indicates the default form length. The FILESI~E value 32767%+1%
sets the FILESIZE sign bit, thereby enabling extended use of the MODE
values. M% specifies the MODE value.
Table 3-3 lists the MODE values available for use with the FILESIZE
32767%+1% modifier.
Table 3-3:

Addi tiona1 OPEN MODES wi th FILESIZE 327617%+1%
;

+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - ,. - - - - - - - - - - - - - ~ - - - - - - - - - - - - - - - --+
I MODE Value I
Line Printer Action,
+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - ,. - - - - - - - - - - - - - .. - - - - - - - - - - - - - - - --+

16%
32%

I
I

Changes ESC to $. This mode disables escape sequences I
in data output to the device.
I

I Sets NOWRAP mode for lines that are longer than the
I
I
I printer's form width. Excess charact~rs continue to
I be output to the device. Mode 256% o~errides this
I
I mode.
' I

+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - _ .. - - - - - - - - - - - - - ~ - - - - - - - - - - - - - - - --+

The following sections describe the vclrious uses of the MODE option.

Change ESC to $: MODE 16%
You can use MODE value 16% only when you include the FILESIZE
32767%+1% modifier in the OPEN statement. This mod~ value instructs
the line printer driver to change any ESC character to a dollar sign
($) character.
For example:
10 OPEN "LP:" AS FILE 1%, FILESIZE 32767%+1%+60%, MODE 16%
i

This statement enables extended softwclre formatting and sets the page
length to 60 lines per page. MODE 16~; disables esc~pe sequences in
all data output to the device.

Set NOWRAP for Excess Lines: MODE 32%
I

You can use MODE value 32% only when you include th~ FILESIZE
32767%+1% modifier in the OPEN statement. This mode value instructs
the line printer driver to continue to output exces. characters to the
device.
For example:
10 OPEN "LP:" AS FILE 1%, FILESIZE 32767%+1%+60%, MODE 32%
3-4

Line Printer
This statement enables extended software formatting and sets the page
length to 60 lines per page.
The driver continues to output excess
characters to the device.
Normally, the driver inserts a line feed character in lines that
exceed the printer's form width, causing the line to be wrapped onto
the next line. With MODE 32% enabled, the driver passes excess
characters to the device without inserting a line feed character.
the
hardware characteristics of the device itself determine the actual
display of excess characters. Note that the driver's horizontal
position counter remains at the rightmost position of the form width,
even though characfers that exceed the line width are being sent to
the device.
Note that MODE 256%, Truncate Long Lines, always takes precedence over
MODE 32%.

Software Formatting: MODE 512%+N%
The MODE value 512% allows you to pass special control characters to
position the paper on a specified line number.
Note that if your
system manager specifies 8 bit capabilities for a line printer (which
allows SI bit characters to be sent to the printer) you cannot perform
software formatting to that printer.
If you attempt to do so, the
system generates the error ?Missing special feature (ERR=66).
For example:
100 OPEN "LPO:" AS FILE 1%, MODE 512%+30%
This statement enables software formatting and sets the form length to
30 lines per page.
If you do not specify the form length, the system
uses thE~ default defined with the SET PRINTER command.
Lines are
numbered from zero to one less than the length specified. Thus, in
the previous example, lines are numbered from 0 to 29.
After enabling software formatting with MODE 512%, you specify the
line number on which to position the printer paper by sending a
special character to the line printer in PUT or PRINT statements.
The
system skips to this line by sending the proper number of line feed
characters to the printer.
The special character is of the form CHR$(128%+L%), where L% is the
line number to advance to.
For example:
200 PRINT #1%, CHR$(l28%+19%);
This statement causes the system to advance the paper to line 19.
If
the line value L% is greater than the page length, the system ignores
it.
If the line value L% is greater than the current line number, the
3-5

Line Printer
printer skips to that line number on the current page.
If the line
value L% is less than or equal to the number of the, current line, the
system moves the paper to the top of the next page and then skips to
the appropriate line.
Note
To enable the program to properly perform software
formatting of print lines using special characters,
load the paper in the line printer with the top of
form aligned properly and with the tractors set at
their top-of-form position.
The system treats characters whose values lie between 0 and 127 as the
standard ASCII equivalents as shown in Appendix D. ,If you do not
specify MODE 512% in the OPEN statement, and, if yo~ do not specify 8
bit capabilities for the line printer l characters w~ose values lie in
the range 128% to 255% are treated as (value - 128%).

Enable Hardware Form Feed: MODE 4096%
The form feed (FF) character advances the paper to the top of the next
page. When you use the default form length, the FF character is sent
directly to the device.
If you use a form length other than the
default, the system translates FF to the proper number of line feed
(LF) characters to advance to the next page.
MODE 4096% causes the system to alway£; send a FF to;the device,
regardless of the form length.
This mode disables tF-to-LF
translation.
MODE 4096% is useful for devices that:can be set to
variable page lengths.
Note
;

If you include both 4096% and 512% values in the MODE
option, a FF character sent to the line pri~ter
remains untranslated.
The form feed positi~ns the
paper at the top of hardware form.
This action
results in unpredictable output because the:line
counting done by the MODE 512% processing dqes not
take into account the movement of the paper to the top
of hardware form.

3-6

Line Printer
Translate Numeric 0 to Letter 0: MODE 128%
A value of 128% in the MODE specification causes the system to print
all 0 (zero) characters as 0 (uppercase "oh") characters.
This
feature is often used in commercial applications where there can be no
possibility for confusion.
For example:

10 OPEN "LPO:" AS FILE 1%, MODE 128%+60%
This statement indicates that the line printer should translate 0 to 0
(128%) on line printer unit 0 with a form length of 60.

Truncate Long Lines: MODE 256%
To truncate lines greater than the width of the line printer, include
256% in the MODE value.
For example:

10 OPEN "LPO:" AS FILE

1 ~o ,

MODE 256%+128%+22%

The statement sets the MODE value 128% on line printer unit 0; it also
discards excess characters from each line printed (MODE 256%).
The
form length is 22 lines. When you do not use 256% in the MODE value,
the system prints excess characters on a second physical line (unless
you use MODE 32%).

Translate Lowercase to Uppercase: MODE 1024%
To translate lowercase characters to uppercase characters, include
1024% in the MODE value.
For example:

10 OPEN "LPO:" AS FILE 1%, MODE 1024%+256%+128%
This statement sets the MODE values 128% and 256%.
The default form
length is used.
In addition, it causes the system to translate all
characters with representations between CHR$(96%) and CHR$(122%) to
their equivalents between CHR$(65%) and CHR$(90%).
The system also
translates characters with representations between CHR$(224%) and
CHR$(254%) to their equivalents between CHR$(192%) and CHR$(222%).
This feature is always set for an uppercase-only printer.

3-7

Line Printer
Skip Lines at Perforation: MODE 2048%
To skip six lines at the bottom of each form, include 2048% in the
MODE value.
For example:

10 OPEN "LPO:" AS FILE 1%, MODE 2048%+1024%+256%+128%+60%
The statement sets the MODE values 128%, 256%, and +024%, and also
skips six lines at the bottom of each to page.
Note that form length
is specified by 60%. With MODE 2048% in effect, th~ system does not
print on the last six lines of each form.
This feature is useful when
you are printing continuous listings to be placed im horizontal
binders.
If you load the line printer so that the top of form is the
third physical line on the page, the system leaves three blank lines
at the bottom and top of each page. vvhen the listings are placed in
binders, printed material is located three lines frQm the perforations
of the page for easy reading.

Suppress Form Feed on CLOSE: MODE 8192%
For certain applications, it is neces~;ary to maintain the current
print position on the line printer during a CLOSE operation.
Normally, the system automatically generates two form feeds (FF) on
either an implicit CLOSE (for example,< a CHAIN operation) or an
explicit CLOSE.
By specifying MODE 8192% in the OP$N statement, the
program tells the system not to generate any form f~ed when it
performs the CLOSE operation on the channel open fot the line printer~
For example:

10 OPEN "LPO:" AS FILE 1%, MODE 8192% + N%
The value N% can be any other combination of MODE v4lues valid for
line printer operation.

Line Printer Control with the RECORD Option
The RECORD option in a PUT or PRINT statement modif~es the operation
of the line printer and enables discre!te control of 'individual output
steps.
Table 3-4 lists the values allowed in the RECORD

3-8

op~ion.

Line Printer
Table 3-4:

Line Printer RECORD Values

+- - - - - - -+- - - _ .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I Value I
Meaning
I
+- - - - - - -+- - - - - - - - - - - _. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I

Print over perforation (disables MODE 2048% for this
output step).

I
I

I
I
I

Do not return control to the program until output is
complete or until the system encounters an error.

I
I
I

Clear pending output buffers before buffering characters
for the request.

32%

Truncate long lines (enables MODE 256% for this output
step) .

I 4096%

Enable binary output, pass all characters to the device
"as is."

I
I

I
I
I
I
I

Return control to the program if an output stall is to
occur on the device.
I
+- - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
8192%

The general format of the RECORD option for line printer operation is
either one of these two forms:
10 PUT #N%, RECORD R%, COUNT C%
10 PRINT #N%, RECORD R%, A$
The following sections describe the RECORD values.

Print Over Perforations: RECORD 2%

By specifying RECORD 2% in the PUT or PRINT statement, you can
temporarily override the effect of MODE 2048% on an output form.
For
example, an application program that usually skips six lines at the
bottom of forms might need to print an identification or special page
requiring all lines on the page.
RECORD 2% allows the program to
print in the lines normally skipped.

3-9

Line Printer
Delay Return Until Output Complete: RECORD 4%
For line printer output, the system transfers data ~rom program
buffers to the device by using intermediate storage i areas called
system buffers. This intermediate buffering allows the faster
computational process to continue unhindered by the slower output
action of the line printer. For each output reques~, the system
transfers the data to system buffers. At the same time, at its own
speed, the line printer driver extracts the data from the system
buffers and outputs it to the d~vice.
Normally, completion of an output request occurs when the data is
buffered. After buffering the data, the system returns control t~ the
program at the next statement. If the program finishes its output
routine but an error occurs at the device before the data is actually
printed, recovery can be di fficul t under programmed, control.
The RECORD 4% option in an output request tells the system not to
return control until the data is actually printed. This mechanism
allows a program greater control over error recover~ -- although at
the cost of increased execution time. To use this mechanism, print a
NUL character with the RECORD 4% option. For example:
!

10 PRINT #1%, RECORD 4%, CHR$(O%);
The output operation has no effect on the line printer because the
system discards all NUL characters. 'The program maintains control of
the output operation because the system does not complete the request
until it prints all previously buffer'ed characters.! If an error
occurs, the program can take recovery action and resume at this
operation. When control passes to the next statement, the output
operation is complete.

Clear Buffers Before Returning Control: RECORD 8%
Sometimes it is advantageous for a program to stop printing characters
already buffered for output. Because characters to, be printed on a
line printer are kept in intermediate buffers, inte~rupting the output
routine only prevents additional chariacters from being buffered.
Normally, characters already buffered for output by' the system
continue printing until the buffers are clear or until an error
occurs.
The RECORD 8% option in an output request tells the system to
terminate the print operation and clear all pending output buffers
before buffering the characters in the request. For example:
10 PRINT #1%, RECORD 8%, CHR$(13%);
The system clears all pending output buffers and then sends the
3-10

Line Printer
carriage return (CR) character to the printer.
The CR character
flushes out any characters in the printer hardware buffers by forcing
them to print. After. the successful completion of this statement, the
printer 4and its buffers are clear, the vertical position counter is
reset to top of form y and the horizontal position counter is reset to
the left margin.
(Although the driver's internal vertical form
position counter is reset to top of form, you may need to align the
form itself to its top-of-form position.)

Truncate Long Lines: RECORD 32%
RECORD 32% enables MODE 256% for one output step.
RECORD 32% causes
the driver to truncate lines greater than the width of the line
printer.

Binary Output: RECORD 4096%
RECORD 4096% disables all formatting of characters sent to the line
printer for one output step.
The driver outputs all characters to the
device "as is." Note that the driver does not update the vertical and
horizontal position counters and the page counter when this modifier
is in effect.
Note that you cannot output null characters to the printer when using
binary output.

No Stall Option: RECORD 8192%
RECORD 8192% provides a "no stall" option for line printer output.
RECORD 8192% causes the monitor to return control to your program if
an output stall is to occur on the device.
You can determine the
number of bytes still to be written by checking the contents of the
XRB+XRBC.
The XRB is accessible only through MACRO; see the RSTS/E
System Directives Manual.
RECORD 8192% is useful for programs that must perform several
different functions with optimal performance (such as a line printer
spooler that per.forms message send/receive and prints files at the
same time). When an output stall does occur, the program can perform
other processing before trying to write the remaining bytes to the
line printer or terminal.
When you use the "no stall" option, you can perform a special test to
see if the line printer is busy without causing your program to stall.
To perform the test, print a single null character and specify RECORD
(8192%+4%). When you specify both values, the system returns control

3-11

Line Printer
to your program instead of stalling it.
If the system returns 0 at
XRB+XRBC, the line printer buffers are empty, which means there are no
characters still to print. A nonzero value at XRB+XRBC means that the
line printer buffer still contains one or more characters to print,.
In this case, repeat the test until the system returns 0 at XRB+XRBC.
Note that BASIC-PLUS programmers cannot use this R~CORD modifier.
BASIC-PLUS-2 programmers can use this modifier, but must ~se a MACRO
subroutine to check the XRB.
See the RSTS/E System Directives Manual
for details.

Line Printer Special Function: SPEC%
The SPEC% function performs special operations on line printers,
terminals, disks, flexible diskettes, magnetic tap~s, and pseudo
keyboards.
For line printers, the SPEC% function lets you:
o

Read the current value of the page counter:.

Read the current vertical and horizontal line positions.

The SPEC% function for line printers has the

forma~:

VALUE% = SPEC%(FUNCTION%,PARAMETER%,CHANNEL%,6%) ,
where:
VALUE%

depends on the function code specified, in FUNCTION%.

FUNCTION%

is the function code.
The SPEC% functiion performs
various functions on line printers as determined by the
function code . . These codes are:
FUNCTION%=O
FUNCTION%=l

returns current value of, page counter.
returns current vertical and horizontal
line positions.

PARAMETER% is unused.
CHANNEL%

specifies the I/O channel for the line: printer.

is the handler index for line printers,.

SPEC% subfunction 0 returns the current value of th~ page counter as a
16-bit value.
SPEC% subfunction 1 returns a 16-biti value with the
current vertical line position in the low byte and ~he horizontal
position in the high byte.

3-12

Line Printer
Error Handling
An error condition at the line printer causes the system to interrupt
the transfer of data from the buffers to the device, but not from the
program to the buffers.
Since any number of unpredictable events such
as a ribbon jam or a paper tear can cause an error condition, the
system retains the unprinted data in the buffers until either the
error is cleared (the unit becomes ready again) or the user program
executes a CLOSE operation.
The system checks the status of the line printer every ten seconds
and, upon detecting the ready condition, continues output from the
small buffers without loss of data.
If a program closes the line
printer while the error is still pending, the system returns the small
buffers to the pool without printing their contents. The data
transferred from the program, but not yet printed, is lost.
If the program disregards the error condition and continues
processing, the system does not transfer more data to additional small
buffers. No output occurs at the line printer while the error
condition remains in effect.
To prevent loss of data, your program must properly detect a line
printer error condition and perform appropriate error handling.
The
system indicates a line printer error by generating the error ?Device
hung or write locked (ERR=14).
The first time the system returns this
error after an output request (for example, PUT), the data is fully
buffered by the monitor. No data is lost, but the buffered data
cannot be sent to the printer because of the error condition.
Because all of the data is buffered, you should not write
exceptionally large buffers to the line printer. The monitor checks
the printer's status every 10 seconds.
It resumes printing when the
error condition is removed.
To prevent filling up monitor buffer
space, subsequent output requests return immediately with the error
?Device hung or write locked (ERR=14). No data is buffered while the
error condition persists. When an output request returns without
error, the printer error is cleared. However, it is good programming
practice to force the monitor to wait until line printer output is
complete before printing any more data.

3-13

Line Printer
The following sample program demonstrates code that:
o

Opens the line printer, inputs a line from the disk file, and
performs output to the line printer

Performs efficient error handling as described in this
section

10
20

100
110
120
130
140
150

160

200
210

300
310
32767

HOUSEKEEPING
OPEN "DATA.DAT" FOR INPUT AS FILE 1%
\OPEN "LPO:" AS FILE 2%, RECORDSIZE BUFSIZ(l%)
\FIELD 1%, BUFSIZ(l%) AS 1$
\FIELD 2%, BUFSIZ(2%) AS 0$
\FIELD 2%, 1% AS 01$
\E% = 0%
\ON ERROR GOTO 200
COpy LOOP
GET #1%
\C% = RECOUNT
\LSET 0$ = 1$
PUT #2%, COUNT C%
\GOTO 100
LINE PRINTER OUTPUT ERROR - DATA PUT
AT LINE 120 IS BUFFERED
LSET 01$ = CHR$ (n%)
PUT 2%, RECORD 4%, COUNT 1%
\E% = 0%
\PRINT IF POS (0%)
\GOTO 100
PUT A NULL (LGNORED BY MONITOR)
AND WAIT FOR PRINTER READY
IF IT MAKES, PRINTER IS OK, SO GO
BACK TO COPY LOOP
PRINT 'PRINTER HUNG - PLEASE FIX IT';
UNLESS E%
\PRINT CHR$ (7%);
\E% = -1%
\SLEEP 10%
\GOTO 150
ASK FOR REPAIRS ONCE, DING EACH
TIME, SLEEP AND RETRY
ERROR HANDLING
RESUME 300
IF ERR = 11% AND ERL = 110%
\RESUME 130
IF ERR = 14% AND ERL = 120%
IF ERR = 14% AND ERL = 150%
\RESUME 160
\ON ERROR GOTO 0
DONE
CLOSE 1%, 2%
END

3-14

Chapter 4
Terminals

RSTS/E provides several features for use in interactive terminal
applicat.ions.
You access most of these features through the MODE
option in the OPEN statement and the RECORD option in GET and PUT (or
PRINT) statements.
For example, by using various MODE and RECORD
options you can:
o

Display and process screen forms using echo control

Perform I/O to several terminals using one I/O channel

This chapter describes these and other terminal features.
describes:
o

Escape sequences

Private delimiters

Pseudo keyboards

It also

Except for the section on escape sequences, which contains information
about the VT100- and VT200-family terminals, this chapter describes
only the general-purpose software features that the RSTS/E operating
system provides.
See the user's guide for your terminal for
hardware-specific information.

Conditional Input from a Terminal: RECORD 8192%
Sometime!s a program must execute an input request from a terminal
without waiting for data to be available.
For example, the terminal
may be opened on a specific I/O channel or may be one of many
terminals opened on one I/O channel (see the section "Multiterminal
Service on One I/O Channel").
Normally, the system stalls a program
that is executing an input request until data is available in the
keyboard input buffer (that is, until a user types a line terminator
4-1

Terminals
at the keyboard).
To avoid waiting fDr data, use RECORD 8192% in the
GET statement.
For example:
GET #1%, RECORD 8192%
If data is available from the terminal open on channell, the system
transfers it to the program's channell buffer.
Th. number of bytes
read from the terminal input buffer is given by the RECOUNT variable.
If no data is available, the system generates the error ?Data error on
device (ERR=13).
In both cases, the system reports the results
immediately.
.
You can use RECORD 8192% with the SLEEP statement to wait for input.
When you type a delimiter at a terminal or when a receiving job has
received a message, the system cancels the sleep operation.
This
feature is useful for determining whether the sleep operation was
canceled by terminal input or the expiration of a r~ceive call's wait
time (see the section "Receive" in Chapter 8).
The following sample
routine shows the procedure for cancellation on terminal input:
100
110

200
300

OPEN "KB:" AS FILE #1%
ON ERROR GOTO 200
\GET #1, RECORD 8192%
\GOTO 1000
!GOT DATA, GO PROCESS IT
IF ERR=13 AND ERL=110 THEN RESUME 300
ELSE ON ERROR GOTO 0
SLEEP 5%
\GOTO 110

If data is not available at the terminal, a message is pending.
data is available, the program can process it.

No Stall Option on Terminal Output: RECORD 8192%
When performing output to a terminal, you can also nclude the value
8192% in the RECORD option. Note that RECORD 8192% works differently
for terminal input and output. When used on output RECORD 8192%
causes the monitor to return control to your program if an output
stall occurs on the device.
If an output stall does occur, the
program can perform other processing before trying to write the
remaining bytes to the terminal.
This modifier performs a similar
function to the "no stall" option for line printer Qutput (see the
section "No Stall Option" in Chapter 3).

4-2

Terminals
Force Interactive Input: RECORD 256%
You can use the RECORD 256% modifier on a GET statement to force the
program to always take input from the terminal, even if a command file
is in effect.
Normally, if you read from a terminal and there is a
DCL command file active, then the program takes input from the command
file.
See the RSTS/E Guide to Writing Command Procedures for more
information on DCL command files.
For example:
GET #1%, RECORD 256%
This modifier is useful in programs that need to ask questions of a
user, even when running under the control of a command file.
The DCL
command $INQUIRE uses this modifier.

Multiterminal Service on One I/O Channel: RECORD 32767%+1%
The multiterminal feature allows one program to interact with several
terminals on one I/O channel instead of opening each terminal for
input or output.
This feature is useful in applications such as order
entry, inventory control, and query-response where the same function
is performed on several terminals but a separate job for each terminal
is undesirable or inefficient.
To control several terminals, you must first establish a master
terminal by opening a keyboard on a nonzero channel.
Two forms of the
OPEN statement are possible:
10

OPl~N

"KB:" AS FILE N%

10 OPEN "KB4:" AS FILE N%
The first form associates channel N% with the job console keyboard and
defines it as the master terminal.
The second form associates channel
N% with keyboard number 4 and defines it as the master terminal.
You can then control additional, or slave, terminals through special
forms of the block I/O GET and PUT statements.
The program must
allocatE~ the terminal to the job but must not open it.
You can
establish the terminals as slave terminals with the ALLOCATE command
before you run the program.
You can also allocate these terminals by
executing the Allocate/Reallocate Device SYS call (SYS 10). Your
program can control any number of terminals up to the maximum number
of terminals on the system.
When a program intc~acts with several terminals on one I/O channel,
the system services the terminals in round-robin fashion, determined
by the numeric sequence of the terminals.

4-3

Terminals
To perform input and output, use GET (or INPUT) and'PUT (or PRINT and
PRINT-USING) statements in a special manner, as theifollowing sections
describe.
Note that the RECORD option specifies a ~articular action
and keyboard number.

Multiterminal Service Output
Use a PUT statement of the following form to perform output to a
keyboard, either master or slave:
10 PUT #1%, RECORD 32767%+1%+K%, COUNT N%
where:
K%

is a variable in the RECORD modifier that specifies the unit
number of the keyboard to which output is directed.

is a variable in the COUNT modifier that specifies the number of
characters to transfer from the buffer on channel 1 to the
designated keyboard.

The only special error that can occur is ?Not a valid device (ERR=6),
indicating that the terminal addressed is neither the master keyboard
nor a slave keyboard reserved by the program. Other possible errors,
such as ?I/O channel not open (ERR=9), work in the standard way.
You can use the RECORD option with thE~ PRINT or PRINT-USING statement
as well as with the PUT statement.
Fe)r example, the following
statements output the string Z$ to the unit designated by K%:
20

PRINT #1%, RECORD 32767%+1%+K%, Z$;

PRINT #1%, RECORD 32767%+1%+K%, USING

" ., ., ..
, , " , Z$;

When you use PRINT or PRINT-USING, you do not need to use ,FIELD, LSET,
and RSET statements to move data to an output buffer.
It is also
easier to format the data with PRINT or PRINT-USING than with block
I/O statements.
You can output binary data using multi terminal service by including
the value 4096% in the RECORD option.
For example:
100 PUT #N%, RECORD 32767%+1%+4096%+K%, COUNT M%
This statement outputs the number of bytes of binary data specified by
M% to the keyboard whose unit number is the variable K%.
Note that when you use multiterminal service, the system keeps track
of the current position (using the CPOS() function) of the output line
of the master keyboard but does not kE!ep track of the current position
4-4

Terminals
of the output line of the slave keyboards.
Thus, you should keep a
count of characters printed to the slave keyboards if you need to know
exactly what the current position is on the line.

Multiterminal Service Input
In multiterminal service, you can request:
o

Input from a specific keyboard

Input from any of the multiple terminals

You specify each type of input request by including certain values in
the GET statement RECORD option.
The rest of this section describes
the two types of input requests in detail.
Use a GET statement of the following form to request input from a
specific keyboard, either master or slave:
10 GET #1%, RECORD 32767%+1%+K%
where the variable K% in the RECORD modifier specifies the keyboard
number ()f the terminal from which input is requested.
The GET
statement transfers the data from the terminal's input buffer to the
I/O buffer for the designated channel.
The first character in the
buffer contains the number of the keyboard from which the input came.
The total number of characters transferred, including the keyboard
number, is available in the RECOUNT variable.
You can access the data
with a standard FIELD statement.
Because the first character of the
I/O buffer is the keyboard number, the length of the data input is
equal t() RECOUNT-l%.
If no input is available from the designated terminal, the error ?Data
error on device (ERR=13) results.
Because this error is recoverable,
your pr()gram can execute an appropriate ON ERROR GOTO routine.
The
system does not allow a stall on input from a specific keyboard in
multiple terminal arrangements.
The following GET statement requests input from anyone of the
multiple terminals:
10 GET #1%, RECORD 32767%+1%+16384%+5%
If input is pending from any terminal, the system transfers the
contents of that terminal's buffer to the buffer for the designated
channel..
The first character in the buffer is the keyboard number of
the terminal from which input came. As with input from a specific
keyboard, you can use FIELD to access the sending keyboard number and
the data sent.
The variable 5% tells the system how long to stall the
program to wait for input.
Table 4-1 lists the values 5% can have.
4-5

Terminals
If no input is pending from any terminal, the program stalls as
described for 5%=0% in Table 4-1.

Table 4-1:

Multiple Terminal RECORD Values for S%

+ - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - '. - - - - - - - - - - - - - .. - - - .. - - - - - - - - - - - - .. +
Value
Meaning
+ - - .. .. - - - - - - - - + - - - - - - - - - - - - - - - .. - - - - - - .. '. - - - - - - - - - - - - - ~ - - .. - - - - - - - - - - - - - - +

5% = 0%

GET statement waits until input is available from any
one of the terminals. The system waits indefinitely
if no input is pending. When input is available, the
system transfers the data and the program accesses
the data as described in the previous section. The
error ?Data error on device (ERR=13), may occur due to
a race condition with CTRL/C. No dat~ is lost; simply
reissue the GET statement to continu~ operation.
A race condition can occur when two jobs are
accessing the same data. That is, on~ job attempts to
access data while another job is in the act of
changing that data. The system canno~ resolve these
two conditions.

1%<5%<255%

GET statement wai ts up to 5% seconds: for input from
any terminal. If no input is available from any
terminal in 5% seconds, the error ?Data error on
device (ERR=l3) occurs.

5% = 8192%

If no input is pending from any of th. terminals, the
error ?Data error on device (ERR=13): occurs
immediately.
+ - - - - - - - - - - .. - + - - - - .. - - - .. - - - - - .. - - - - - .. - - - - - - - - - - - - - - - - ,- • - - - - - - - - - .. - - - - - - +
In multiterminal service, the system handles CTRL/C differently for
slave and master terminals. A CTRL/C entered at anyone of the slave
terminals passes a CHR$(3) character to the program but does not
terminate the program. The RECOUNT variable contains the value 2%,
representing the keyboard number and the CTRL/C cha~acter. The
program can process the CTRL/C character as a special character.
If
CTRL/C is entered at the master terminal, the syste~ terminates the
program in the standard fashion.,
A CTRL/Z entered at either a master or slave terminal produces the
error ?End of file on device (ERR=1l). The system returns the unit
number of the keyboard causing the error as the first character in the
channel buffer.

4-6

Terminals
Terminal Control with the MODE Option
You can control a terminal in several ways with the MODE option in the
OPEN statement.
Table 4-2 summarizes the MODE values you can use for
terminals.

Table 4-:2:

Summary of MODE Values for Terminals

+- - - - - _ .. -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I MODE
Meaning
I
+- - - - - _ .. -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ~ - - - - - - - - - - - - - - - - - - - - - - - --+
1%

Enable binary input from a terminal

Reserved for TECO

4~s

Suppress automatic carriage return/line feed at right
margin
Enable echo control (turns off other modes and
automatically enables MODE 4%)

16 ~5

Guard program against CTRL/C interruption and dial-up
line hibernation

32 ~5

Enable incoming XON/XOFF processing
Reserved

l28~5

Enable special scope RUB OUT
Set escape sequence mode

Enable transparent control character output
+- - - - - _ .. -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
The following sections describe the various MODE options.

Binary Data Output and Input: RECORD 4096% and MODE 1%
To perform binary data output to a terminal, either opened on its own
I/O channel or opened as one of many terminals on one I/O channel, use
a statement of the following form:
PUT iN%, RECORD 4096%, COUNT M%
This statement transfers the number of bytes specified by M% to the
output buffer of the terminal open on channel N%. You do not need any
4-7

Terminals
special form of the OPEN FOR OUTPUT statement.
Specifying RECORD
4096% in the PUT statement disables all output formatting on the
terminal for that output operation.
You can obtain binary input from a keyboard by including MODE 1% in
the OPEN statement.
For example:
10 OPEN "KB6:" AS FILE N%, MODE 1%
This statement associates channel N% 'Nith keyboard number 6 in binary
input mode. As a result, characters received are nbt echoed by the
system and are not altered in any way.
A program can read binary data from:
o

A terminal paper tape reader

The terminal itself

Any device connected to the system through a keyboard
interface.

To start a transfer of data, use the GET statement.

For example:

GET #N%
The system transfers some number of characters from: the keyboard open
on channel N% to the buffer for that channel.
If no data is
available, the system stalls the program until data is received from
the keyboard. When data is received, the system makes the program
eligible to run and transfers the data to the program's I/O buffer.
The program must execute GET statements often enougn to avoid losing
data from the transmitting device.
The number of characters received is ialways at least one and never
more than the channel buffer size.
The default buffer size for
keyboards is 128 characters.
You can override the default buffer size
by using the RECORDSIZE option in the OPEN statement.
However,
becaus~ the system must first buffer the characters! before they can be
transferred to the program's buffer, changing the RECORDSIZE may not
help increase the number of characters read by each, read operation.
(The system limit is approximately 180, but will va~y depending on
other system activity.) The RECOUNT variable contains the actual
number of characters received.
Normally, the system terminates a read after every character typed at
a terminal open for binary input.
However, if you ~et one or more
private delimiters for that terminal, the system terminates a read
only when you type a private delimiter.

4-8

Terminals
The system accepts and does not alter any characters received from a
terminal open for binary input.
Thus, entering CTRL/C has no effect.
For this. reason, the system disables binary input mode under any of
the following conditions:
o

The period for a WAIT statement expires.
(The error
?Keyboard wait exhausted (ERR=lS) occurs.)

You execute any input or output statement on channel zero
when the user's keyboard is open for binary input.

You execute an OPEN statement in normal mode on the device
but on a different channel.

You execute a CLOSE statement on any channel associated with
a keyboard open for binary input.

under condition 1, the system disables binary input mode if time for a
WAIT is exhausted.
For example:
10 WAIT 10%
20 GE'I~ #1%
If the system does not detect data within 10 seconds on channell,
which is open for binary input, it disables binary mode in addition to
generating the error ?Keyboard wait exhausted (ERR=lS).
The keyboard
stays open for normal ASCII data transfers.
Under condition 2, the system disables binary input mode when the
program performs I/O on channel 0 and the user's keyboard is open for
binary input on a nonzero channel.
For example:
10 OPEN "KB:" AS FILE 1%, MODE 1%
20 GEr.I? #1%

40 PRINT "MESSAGE";
The statement at line 10 opens the user's keyboard for binary input on
a nonzero channel (channell). The statement at line 20 performs
binary input from the keyboard. However, at line 40 the system
executes a PRINT statement on channel 0, which disables binary input
mode. ,The user's terminal remains open on channell for normal ASCII
data transfers. Note that a PRINT or PUT statement on channell does
not turn off binary input mode.

4-9

Terminals
Under condition 3, the system disables binary input on a channel if
the program executes a normal OPEN on the same device but on a
different channel.
For example:
10 OPEN "KB6:" AS FILE 1%, MODE 1%

100 OPEN "KB6:" AS FILE 2%
When the system executes line 100, it disables binary input on
keyboard 6.
If line 100 contained MODE 1%, the system would open
keyboard 6 for binary input on channel 2.
Therefore, keyboard 6 would
be open for binary input on both channels.
Under condition 4, the system disables binary input if the program
executes a CLOSE statement on any channel associated with a keyboard
open for binary input.
For example:
10
20

OPEN "KB6:" AS FILE 1%, MODE 1%
OPEN "KB6:" AS FILE 2%, MODE 1%

100

CLOSE 2%

The CLOSE statement at line 100 disassociates channel 2 from keyboard
6 but also disables binary input on channell. Keyboard 6 remains
open in normal mode on channell. DIGITAL recommends using binary
input mode by opening a device other than the user's terminal for
binary input on any nonzero channel. Your program can interact
normally with the user's terminal by executing standard INPUT and
PRINT statements and can gather data from the binary device on the
nonzero channel by executing GET statements.
Because binary input disables all special character handling, the
system cannot detect an end-of-file on a terminal transmitting binary
data.

Suppress Automatic Carriage Return/Line Feed: MODE 4%
RSTS/E normally performs a carriage return/line feed (CR/LF) operation
when the right margin of a terminal is to be exceeded.
(The SET
TERMINAL command sets the right margin by means of the width
characteristic.) You can suppress this automatic operation by opening
the terminal with the MODE 4% option.
For example:
OPEN "KB13:" AS FILE 1%, MODE 4%
The system opens keyboard number 13 on channel 1 in suppress CR/LF
4-10

Terminals
mode.
The system places all terminals allocated by the job but not
opened in the same mode.
(This action follows the multi terminal
service rules; see the section, "Multiterminal Service on One I/O
Channel.") Thus u all slave terminals have the same control
characteristics as the master terminal.
MODE 4% stays in effect until the terminal is either closed or opened
again without MODE 4%. All slave terminals stay in this mode until
the master terminal is either closed or opened again without MODE 4%.
MODE 4% is normally used for echo control and is automatically enabled
with the MODE 8% option, which the next section describes.

Echo Control: MODE 8%
RSTS/E normally echoes characters on your terminal ,as you type them.
When you enter a BASIC-PLUS or DCL command, for example, the system
displays the command on the screen. You can also "type ahead" on
RSTSjEi that is, enter input faster than the system can process it.
Besides storing your input in a type-ahead buffer to wait for
processing, the system also echoes each character you type at the
current cursor position on your screen.
While normal terminal echo is useful in many applications, it may be
inconvenient in applications that display prompts or forms on the
screen.
For these applications, you can use echo control.
Echo control is designed for use on video terminals, but you can also
use it on hard-copy terminals.
It is often used with cursor control
in forms-oriented data entry applications. Note that echo control is
an optional feature of the RSTS/E monitor and may not be available on
all systems.
Echo control modifies the way the system handles terminal echo.
Instead of echoing characters' as you type them, the system echoes
characters only within a field that your program declares.
If no
field is currently active, the system stores typed characters and
echoes them when your program declares a field.
Echo control mode also provides other features for screen
applications:
o

Automatic display of a "paint" character -- When you declare
a field on the screen, you can define a special paint
character for character deletion in the field.
When you
delete characters from the field, the system refreshes the
paint character on the screen to maintain the appearance of
the field.

4-11

Terminals
The system maintains the declared paint character
automatically; your program can display prompts or forms on
the screen, accept input from one field at a time, and format
the data for processing.
o

Other special character handling -- For example, if you type
too many characters in a field, the system can echo them as
BEL characters or store them as input for the next field.
You specify which type of processing you want when you
declare the field.

To enable echo control, use the MODE 8% option in the OPEN statement:
OPEN "KBn:" AS FILE 1%, MODE 8%
where n designates the keyboard to be opened on channel 1 in echo
control mode. A nonzero channel is required.
The system also places
all terminals allocated by the job but not opened in echo control
mode.
(This action follows the multiterminal service rules; see the
section, "Multiterminal Service on One I/O Channel~" Thus, all slave
terminals are in the same mode as the master terminal.)
MODE 8% turns off other MODE options in effect (except MODE 16% and
MODE 128%) and turns on MODE 4%.
Echo control remains in effect until one of the following conditions
is met:
a

A CLOSE is performed on the channel

The terminal is opened again without MODE 8%

Any input or output is performed on channel 0 (the job's
console terminal)

In echo control mode, the system strips the parity bit from all
characters. All characters returned to the user have ASCII values in
the rarige 1 to 127. The system does not pass synchronization and
editing characters to the program.
The system passes delimiters to
the program but they are never echoed.
Table 4-3 summarizes how the system t.reats these characters in echo
control mode.

4-12

Terminals
Table 4-3:

Echo Control Mode Character Set

+- - - - - _.' - - - - _ .. _.... - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I
I Code Returned I
I ASCIl: Code I
to User
I
Comments
+- - - - - _.' - - - - _ .. _.... - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

Ignored Characters
+- - - - - _.' - - - - - - -+- - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I
I

Used as filler for timing.

+- - - - - _. - - - - - - -+- - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

Delimiter Characters

+- - - - - _.' - - - - _ .. -+- - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

Pri.vate

Private delimiter.

AC (CTRL/C combination).

AD (CTRL/D combination).

Line feed.

Form feed.

13,10

Carriage return (with line feed
appended) .

I
I
I
I
I
I
I
I
I
I
I

I
I
I
I
I

AZ (CTRL/Z combination); generates
ERR=ll.

If you use the SET
I
TERMINAL/NOES CAPE SEQUENCE command
I
and output an escape character, the I
system returns 27 to the user and
I
treats it as a delimiter.
I

If you use the SET
TERMINAL/ESCAPE_SEQUENCE command,
the escape character triggers an
escape sequence. The system returns
an escape sequence to the user and
considers the whole sequence as the
delimiter.
125

27 or 125

I
I
I

I
I
I
I
I
I

If you use the SET TERMINAL/ALTMODE I
command, 125 is translated to
I
escape (27).
I
If you use the SET
TERMINAL/NOALTMODE command, 125 is
data.

4-13

I
I
I
I

Terminals
Table 4·3:

Echo Control Mode Character Set (Cont.)

+- - - - - - - - - - - - - -+- - - - - - - - - _. - - - -+- - - _ .. - - - - - - - - - - - - -. - - - - - - - - - - - - - - - --+

ASCII Code

I Code Returned I
I
to User
I

Comments

I
I

+- - - - - - - - - - - - - -+- - - - - - - - - -. - - - -+- - _. _. - - - - - - - - - - - - -. - - - - - - - - - - - - - -. --+

Delimiter Characters

+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - -+- - - - _. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

126

27 or 126

If you use the SET TERMINAL/ALTMODE I
command, 126 is translated to
I
I escape (27).
I

I
I

If you use the SET
I TERMINAL/NOALTMODE command, 126 is
I data.

I
I

+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - -+- - - - _ .. - - - - - - - - - - - - _. - - - - - - - - - - - - - - - --+

Editing Characters
+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - -+- - - - _ .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

127

Rubout (DEL character); on video
terminals, generates a backspace
followed by the paint character and
another backspace; on hard-copy
terminals, echoes deleted
characters between backslashes.

AU (CTRL/U combination); repeatedly
simulates RUB OUT until no
characters remain in field.

+ - - - - - - - - - - - - - - + - - - - - - - - - - - - - - - + - - - - - .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +

Data Characters

+- - - - - - - - - - - - - -+- - - - - _. - - - - - - - -+- - - - _. - - - - - - - - - - - - -. - - - - - - - - - - - - - - - --+

32-95

Normal 64-character graphic set.

96-126

64-94

If you use the SET
TERMINAL/UPPERCASE=INPUT command,
lowercase letters are translated to
uppercase.

96-126

If you use the SET
TERMINAL/LOWERCASE#INPUT command,
lowercase letters are returned to
the user.

192-254

192-221

If you use the SET
TERMINAL/UPPERCASE=INPUT command,
lowercase letters are translated to
uppercase.
4-14

Terminals
Table 4-3:

Echo Control Mode Character Set (Cont.)

+- - - - - -.' - - - - - - -,+- - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I
I Code Returned I
I
I ASCll: Code I
to User
I
Comments
I
+ - - - - - - .' - - - - - - - + - - - - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
I
Data Characters
+ - - - - - - .' - - - - - - -,+ - - - - - - - - - - - - - - -+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+

I
I
I

192-254

I
I

I
I
I
I
I
I

223-254

I
I If you use the SET
I TERMINAL/LOWERCASE=INPUT command,
I lowercase letters are returned to
I the user.
I

+- - - - - _.' - - - - - - -+- - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I
Synchronization Characters
+ - - - - - - ., - - - - - - - + - - - - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +

XON (CTRL/Q combination); resumes
suspended output (if you use the
SET TERMINAL/TTSYNC command).

XOFF (CTRL/S combination); suspends
output (if you use the SET
TERMINAL/TTSYNC command).

+- - - - - _ .. - - - - - - -+- - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - _ .. - --+
I
Other Characters
+- - - - - _ .. - - - - - - -+- - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

1,2,S-9,11,
14-16,18,20
22-2S,28-31

Echoed as BEL (code 7); otherwise,
ignored.

17,19

If you use the SET
TERMINAL/NOTTSYNC command,
synchronization characters are
treated as other (echoed as BEL;
otherwise, ignored).
+- - - - - _ .. - - - - - - -+- - _.' - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
When you open the terminal in echo control mode, the terminal does no
echoing until a field is declared on the channel.
Declaring a field:
o

Establishes field size, which is the maximum number of
characters the field can hold.

4-15

Terminals
o

Specifies how overflow characters are handled.
are available:

Two methods

Normal. A field is terminated by receiving a delimiter.
Any characters received in excess of the field size are
treated as other (see Table 4-3) and echoed as BEL
characters.
Keypunch. A field is terminated either by receiving a
delimiter or by entering the nth character in an
n-character field.
If the field is terminated by size
(receiving the maximum number of characters allowed)
rather than by a delimiter, a form feed (code 12) is
appended to the field. The terminal does not echo any
excess characters but retains them as input for the next
field.
o

Defines a special character to be echoed for character
deletion sequences. The default is the space character,
which actually erases a visible character on a video screen.
However, you can use a character like underscore (_) to
indicate, or paint, the field. An editing character (CTRL/U
or DELETE) causes the defined paint character to be echoed in
place of the default space character. This action maintains
the visual indicator of the field during any character
deletion sequence.

To declare a field, execute a special form of the PUT or PRINT
statement on the channel where the teJ~minal is open with MODE 8%. Use
the RECORD 256% and COUNT N% options in the PUT statement to declare
the field:
PUT #C%, RECORD 256%, COUNT N%
where the value N% must be in the range of 1% to the size of the
buffer declared on channel C% and indicates how many bytes in that
buffer represent the field declaration. Define the field as follows:
N% = 1%

The byte contains the field size and overflow handling
information. The field size must be in the range of 1
to 127. If you attempt to declare a size of 0, the
system returns the error ?Illegal byte count for I/O
(ERR=31).
If you add 128 to the field size, it indicates that
keypunch overflow handling is to be used instead of
normal overflow handling.

The first byte contains the field size declaration as
described in N% = 1%.

4-16

Terminals
The second byte contains the ASCII value of the paint
character.
If this byte is 0 or N% = 1%, then a space
is the paint character by default.
N%

> 2%

The first N minus 2 bytes contain a prompt that is to
print on the terminal before the field.
Byte N minus 1 is the field size declaration as
described for N% = 1%.
The last byte is the paint
character as described for N% = 2%.

For example:
COUNT 1%

Specifies that the first byte in the buffer declares the
field size.
Space becomes the paint character by
default.

COUNT 2%

Specifies that the first byte in the buffer declares the
field size.
The second byte in the buffer declares the
paint character.
If you want to use a space as the
paint character, specify 0% or the ASCII value for space
in this byte.

COUNT 20%

Specifies that the first 18 bytes in the buffer contain
the prompt.
The prompt is a string of ASCII characters.
Byte 19 in the buffer contains the field size.
Byte 20
in the buffer contains the paint character.

You can also use the PRINT statement to declare a field, using a
method similar to that of the PUT statement.
The PRINT statement must
include a RECORD 256% modifier to indicate the field declaration and
string specifications (in place of the COUNT option) to declare field
parameters.
For example:
10
10
10

PRINT #C%, RECORD 256%g CHR$(M%+S%);
PRINT #C%, RECORD 256%g CHR$(M%+S%)+'P';
PRINT #C%, RECORD 256%, A$+CHR$(M%+S%)+CHR$(P%);

where:
C%

is the nonzero channel open with MODE 8%.

is the overflow handling code:
M%
128% for keypunch.
M% = 0% for. normal.

is the field size in the range of 1 to 127.

concatenates the field declarations.

'P'

is the ASCII paint character.

4-17

Terminals
A$

is the prompt.

is the decimal code for the paint character;
for example, underline is CHR$(95%).
terminates the string (suppresses CR/LF).

When you use the PRINT statement instead of the PUT statement to
declare a field, it saves space in your program because it eliminates
the need for the statements to define and load a buffer.
Note that
you should output all necessary bytes as one string, as in the
previous examples.
Do not use multiple elements separated by
semicolons (;).
After you declare the field, the system enables echoing.
The
declaration makes the field active.
The terminal then echoes
characters until the field is filled.
The terminal handles subsequent
characters according to the overflow mode in effect for the field.
When the terminal receives a delimite·r (or the nth character for an
n-character keypunch field), it deactivates the field and disables
echoing.
The terminal retains characters typed after the field is
deactivated until the next field is declared.
Attem~ting

to declare a field when one is currently active and the
system has input characters for your program generates the error
?Account or device in use (ERR=3).
The SYS call to cancel type ahead
deactivates an active field.
You can combine 256% with other values in the RECORD option of the PUT
or PRINT statement for multi terminal service operations.
Combining
RECORD values lets you declare a field for either the master or a
slave terminal.
You need not declare fields on all terminals, only on
those terminals from which input is solicited.
If your program tries
to input data without declaring a field on any terminal, the system
returns the error ?Data error on device (ERR=13).

DIGITAL recommends the following sequence when interacting with a
video terminal in echo control mode:
1.

Open any terminal on a nonzero channel with MODE 8%.

Execute the Cancel All Type Ahead SYS call (SYS 11), to
cancel type ahead.
This action discards any unsolicited
input that would be echoed automatically after a field is
declared.

Position the cursor to top of screen and clear the screen.

Print any prompting text and display paint characters in all
fields.
(The program must initially display the paint
characters that will be maintained by terminal service during
any deletion sequences.)
4-18

Terminals
5.

Position the cursor to the beginning of the first field (by
direct cursor addressing).

Declare the field with the desired size and prompt and a
paint character that matches the one displayed.

Execute the GET statement to retrieve input.
The INPUT,
INPUT LINE and MAT INPUT statements recognize only-the
standard BASIC-PLUS delimiters (carriage return, line feed
and form feed) and should not be used for input operations.
With the GET statement, you can use a private delimiter.

Extract data from the buffer and store it for processing.

Continue positioning the cursor, declaring fields, retrieving
input, and extracting data as required.

For hard-copy terminals, the sequence is slightly different:
1.

Open the terminal on a nonzero channel with MODE 8%.

Execute the Cancel All Type Ahead SYS call (SYS 11).

Position the paper at top of form.
(If the terminal has
hardware top of form, print a form feed; otherwise, print
several line feeds.)

Print any prompting text for the first field.

If the terminal can backspace and has the underline
character, paint the field with underlines and print the
appropriate number of backspaces to fix the printing positior
at the start of the field.

Declare the field with the desired size, overflow handling
mode, and prompt.
Do not declare a paint character because
it has no effect on a hard-copy terminal.

Execute the GET statement to retrieve input.
INPUT, INPUT LINE, or MAT INPUT statements.

Extract data from the buffer and store it for processing.

Position the paper and printing mechanism for the next field
by printing carriage return, line feeds, and spaces as
required. Use only one field for each line because
characters removed during a deletion sequence are echoed,
which can cause the next intended field to be used.

10.

Repeat the sequence from step 4 until all fields are
satisfied.

4-19

Do not use

Terminals
It is possible to use ODT submode (see SYS call 4, Enable ODT Submode)
with echo control.
Combining these features allows a program to
examine every input character while ensuring that type ahead stays
within the bounds of a field.
However, some special processing is
required for the program to work correctly.
Completion of an ODT submode input request does not necessarily
terminate an echo control field.
Therefore, if the program tries to
declare the next field while the previous field is still active, one
of two conditions occurs:
o

If there is no pending input for the program, the system
cancels the existing field and defines the new one.

If there is pending input for the program, the system
notifies the program by returning the error ?Account or
device in use (ERR=3), and the field declaration fails.

To handle the second condition, you can trap the error and have the
program read the rest of the characters in the field.
DIGITAL recommends using private delimiters instead of ODT submode
(see the section, "Private Delimiters").

Prevent CTRL/C Interruption and Hibernation: MODE 16%
MODE 16% protects a program from:
o

Aborting when CTRL/C is entered at the terminal.

Hibernating when it becomes detached and attempts terminal
I/O on a nonzero channel. A job becomes detached when it
executes the detach system function call or when it is
running over a dial-up line that gets hung up.

Entering CTRL/C at a terminal that is open with MODE 16% cancels any
pending output to the terminal, sets CTRL/O, and is interpreted as an
ASCII 3.
The program can recover and continue output.
Hanging up a dial-up line (without using MODE 16%) causes a job to be
detached and to enter the hibernation state as soon as it does
terminal I/O.
The job must wait until it is attached, through some
external process, before it can recover. With MODE 16%, an immediate
exit to the error ?I/O to detached keyboard (ERR=27) occurs when
terminal I/O is attempted, which allows the program :to recover.
To
take advantage of MODE 16%, your program must trap this error.
Otherwise, the job goes into hibernation because BAS:IC-PLUS uses
channel zero to display the error message on the terminal.

4-20

Terminals
MODE 16% remains in effect until one of the following conditions is
met:
o

A CLOSE is performed on the channel

The terminal is opened again, without MODE 16%

Any I/O is performed on channel 0 (the job's console
terminal)

Enable Incoming XON/XOFF Processing: MODE 32%
When an OPEN statement includes MODE 32%, an incoming XOFF character
(ASCII 19) suspends output to the terminal; an incoming XON character
(ASCII 17) resumes output to the terminal.
When the OPEN statement also includes MODE 1% (for binary input), the
terminal processes all other incoming characters as for MODE 1%.
However, the terminal ignores all other incoming characters when the
OPEN statement does not also include MODE 1%.
MODE 32% remains in effect until one of the following conditions is
met:
o

A CLOSE is performed on the channel

The terminal is opened again without MODE 32%

Any I/O is performed on channel 0 (the job's console)

An input timeout occurs, producing the error ?Keyboard wait
exhausted (ERR=15)

Special Use of RUBOUT: MODE 128%
MODE 128% allows video terminals to use RUBOUT as a delimiter.
RUBOUT's use as a delimiter is subject to these conditions:
o

If a typed character is the object of a RUBOUT operation and
is a printing character (CHR$(32) to CHR$(126} or CHR$(160}
to CHR$(254}}, the terminal deletes the character.

If there is no typed character or if the character is
nonpr.inting (CHR$(O) to CHR$(31} and CHR$(127}}, the terminal
does not delete a character. The terminal buffers RUBOUT as
a delimiter and marks the job as eligible to run.
4-21

Terminals
The ability of MODE 128% to buffer RUBOUT as a delimiter is
particularly useful to screen-oriented editors.
Note
MODE 128% is reserved for use with DIGITAL-supplied
software and it is subject to change in future
releases.

Escape Sequence Mode: MODE 256%
When a terminal is in escape sequence mode, RSTS/E interprets the ESC
character (CHR$(27%)) as the start of an. escape sequence instead of as
a delimiter.
You can set escape sequence mode either by opening the
terminal with MODE 256% or by setting the terminal's escape sequence
characteristic with the SET TERMINAL/E:SCAPE SEQUENCE command. MODE
256%, the method DIGITAL recommends, sets escape sequence mode even if
the terminal is set to /NOESCAPE_SEQUENCE.
DIGITAL recommends MODE 256% because, in addition to setting escape
sequence mode, it modifies the way the~ system handles escape sequences
that end with P. When you use MODE 2S6%, the system recognizes P as
an escape sequence terminator.
On the~ other hand, when you set the
terminal's escape sequence characteristic, the system requires another
character after P to terminate an escClpe sequence.
See the section
"Input Escape Sequences" for more information about escape sequence
terminators.
Note
As an alternative to MODE 256%;, an optional patch is
available to cause the system to recognize P as an
escape sequence terminator.
Unlike MODE 256%, this
patch affects all terminals on the system.
See the
RSTS/E Maintenance Notebook for details.
Because the system recognizes P as an escape sequence terminator with
MODE 256%, you can use the same code to read incoming escape sequences
from all keys on VT52-, VT100-, and VT200-family terminals in ANSI
mode.
On the other hand, when you set escape sequence mode through
the terminal's escape sequence characteristic, you cannot use the same
code to read incoming escape sequences from the VT100- or VT200-family
PF1 key and the VT52 blue key, which are in the same place on the
keypad.
Both keys send escape sequences that end with P.
See the
section "Escape Sequences" for a complete description of escape
sequences.

4-22

Terminals
The following statement opens keyboard unit 46 in escape sequence mode
on I/O channel 2:
100

OPEN "KB46:" AS FILE #2%, MODE 256%

This mode follows multi terminal service rules, which means that all
terminals allocated but not opened by the job are also placed in
escape sequence mode.
See the section "Multiterminal Service on One
I/O Channel" for more information about multiterminal service.
MODE 256% remains in effect until either:
o

A CLOSE is performed on the channel

The terminal is opened again without MODE 256%

If the terminal's escape sequence characteristic is set, escape
sequence mode stays in effect when you cancel MODE 256%.

Escape Sequences
An escape sequence is a series of characters that performs a control
function on the terminal, such as moving the cursor forward or
backward or erasing part of the screen.
The first character of an
escape sequence is an ESC.
The ESC character is a prefix that causes
the terminal to treat subsequent characters as a command instead of
echoing them on the screen.
One common use of escape sequences is cursor control.
Cursor control
is a feature of many video terminals, including the VT100-family and
VT200-family terminals. As its name suggests, cursor control allows a
program to manipulate the screen cursor.
Cursor control is often used
with the RSTS/E echo control feature in data entry applications.
This section:
o

Summarizes commonly-used escape sequences for the
VT100-family and VT200-family terminals.

Shows how to use ANSI-compatible escape sequences to control
the cursor and use two graphics features: reverse video and
double-height characters.
(The example is intended to show
the technique, not to be a practical application.)

Explains how the system handles input and output escape
sequences for all types of terminals.

4-23

Terminals
VT100- and VT200-Family Escape Sequences
VT100- and VT200-family terminals can operate in either
ANSI-compatible mode or VT52-compatibJLe mode. Each mode has a
different set of escape sequences.
In VT52-compatible mode, the VT100- and VT200-family terminal responds
to escape sequences like a VT52 terminal. VT52-compatible escape
sequences let you execute programs on the VT100- and VT200-family
terminals that are written for the VTS2 terminal but do not let you
take advantage of advanced features, such as reverse video. In
addition, VT52-compatible escape sequences are not ANSI-standard.
If you write programs for both the VT52 and the VT100- and
VT200-family terminals or if you are converting from the VT52 to a
more advanced terminal, be aware of differences between the terminals.
For example:
o

The "home" cursor position differs for the VT100- and
VT200-family terminals and the VT52. Home, which is the top
left corner of the screen, is:
(1,1) for the VT100- and VT200-family terminals in
ANSI-compatible mode
(32,32) for the VT52 and the VT100- and VT200-family in
VT52-compatible mode

When you use cursor control functions on the VT52 or the
VT100- and VT200-family terminal in VT52-compatible mode, you
must output the line and column positions as one-byte ASCII
values.
(You can use the CHR$ function to perform the
necessary conversion.)
On the other hand, when you use cursor control functions on
the VT100- and VT200-family terminals in ANSI-compatible
mode, you output line and column positions as string data.
No conversion is necessary.

See the appropriate hardware manuals for a complete discussion of
terminal hardware and software. The rest of this se;ction describes
VT100-family and VT200-family ANSI-compatible escape sequences.
Table 4-4 summarizes the VT100- and VT200-family ANSI-compatible
escape sequences that move the cursor, erase all or part of the
screen, and control line size and VT100- and VT200-family character
attributes (bold, underscore, blink, and reverse video). The table
uses the symbols PI, Pc, and Pn:
PI

means line number.
4-24

Terminals
Pc

means column number.

is a decimal parameter expressed as a string of ASCII digits.
The parameter's meaning for each escape sequence is explained
in Table 4-4.
Separate multiple parameters with a semicolon
(;).
If you omit a parameter or specify 0, the terminal uses
the default parameter value for that escape sequence.

Be sure to include the left square bracket ([) in the escape sequence
prefix \~here Table 4-4 indicates. Note that escape sequences cannot
contain embedded spaces.
See the VT100 User Guide for a complete
description of VT100 escape sequences. See the VT220 User Guide,
VT240 User Guide, or VT241 User Guide, for a complete description of
VT200-family escape sequences.

Table 4-4:

A~lSI-Compatible

Escape Sequences:

VT100- and VT200-Family

Terminals
+ __________________

Escape Sequence

_+ _____________ .. ___ .. ___________________________ -_+

Description

+- - - - - - - - - - - - - - - - - - ,. -+- - - _ .. - - - - - - - _ .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
... ___ .. _ .... _ .... ___ .. ____ ,. _+ ____ .. _Cursor
.. __ .. ___ Movement
n

I
I ESC[PnA

I
I
I
I ESC[PnB
I
I
I
I
I ESC[PnC
I
I
I
I
I ESC[PnD
I
I
I
I

I ESC[Pl;PCH
I
I
I
I

......

___

_____________________

___

Moves the cursor up n lines without affecting
the column position. The parameter Pn
specifies the number of lines. The default
value is one line.
Moves the cursor down n lines without
affecting the column position. The parameter
Pn specifies the number of lines. The default
value is one line.
Moves the cursor forward (right) n columns
without affecting the line position. The
parameter Pn specifies the number of columns.
The default value is one column.
Moves the cursor backward (left) n columns
without affecting the line position. The
parameter Pn specifies the number of columns.
The default value is one column.
Direct cursor address. Moves the cursor to
the specified line and column position. If
you do not specify a line or column position,
the cursor moves to the home position, which
is the top left corner of the screen.

4-25

Terminals
Table 4-4: ANSI-Compatible Escape Seq:uences: VT100- and VT200-Family
Terminals (Cont.)
+- - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - _. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Escape Sequence
I
Description
I
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Cursor Movement
I
+- - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

ESCD

Index. Moves the cursor to the current column I
position on the next line.
I

ESCM

Reverse index. Moves the cursor to the
current column position on the preceding
line.

ESCE

I
I
I

I
I
Moves the cursor to the first column position I
on the next line.

I
+ - - - - - - - - - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - -. - - - - - - - - - - - - - - - .. - - +
Erasing
I
+ - - - - - - - - - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ,. - - +

ESC[K or ESC[OK
ESC[IK

I
I
I
I
Erases from the beginning of the current line I
to the cursor.
I
Erases from the current cursor position to
the end of the line.

ESC[2K

Erases the entire line containing the cursor.

ESC[J or ESC[OJ

Erases from the current cursor position to
the end of the screen.

ESC[IJ
ESC[2J

Erases from the beginning of the screen to
the current cursor position.
Erases the entire screen.

I
I
I

+- - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Line Size (Double Height and Double Width)
+- - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

ESC#3

Changes the current line to the top half of a
double-height, double-width line.

ESC#4

Changes the current line to the bottom half
of a double-height, double-width line.

ESC#5

Changes the current line to a single-width,
single-height line.

4-26

Terminals
Table 4-,4: ANSI-Compatible Escape Sequences: VT100- and VT200-Family
Terminals (Cont.)
+ - - - - - - ., - - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +

Escape Sequence

Description

+- - - - - _ .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

Line Size (Double Height and Double Width)

+- - - - - _ .. - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

ESC#6

I
I Changes the current line to a double-width,
I single-height line.

To display double-height characters, use the ESC#3 and ESC#4
sequences as a pair on adjacent lines and send the same characters
to both lines. The use of double-width characters reduces the
number of characters on each line by half.
+- - - - - _ .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

Chnracter Attributes (Require Advanced Video Option on VT100)
+- - - - - - ,. - - - - - - - - - - - -. -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

ESC[Pn;Pn;Pn; ... ;m

Turns bold, underscore, blink, and reverse
video attributes ON and OFF. Pn can have the
following values:
0 or none
I
4

5
7

All attributes OFF
Bold ON
Underscore ON
Blink ON
Reverse video ON

The terminal executes the parameters in order
and ignores any other parameter values.
Unlike line size commands, which affect only
the current line, the character attributes
affect the entire screen. Remember to turn
them OFF before ending your program.
+- - - - - - '. - - - - - - - - - - - ~ -+- - - - - - - - - - - - - ~ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

4-27

Terminals
Programming Example
The following example shows how to use VT100- and VT200-family
ANSI-compatible escape sequences in BASIC-PLUS. The program uses
PRINT statements to send the escape sequences to the terminal and uses
the special value CHR$(155%) for the ESC character.
(See the section
"Output Escape Sequences.") Each PRINT statement ends with a semicolon
to prevent BASIC-PLUS from printing a carriage retu~n/line feed
(CR/LF) as the last step in the PRINT statement. Ybu need separate
PRINT statements to print each half of the double height line.
10 EXTEND
100 ESC$ = CHR$(155%)
!Set up variables
120 PREFIX$ = ESC$ + '['
!for ESC and ESC[ prefix
125 CLEAR$ = PREFIX$ + '2J'
land to clear the screen
130
132 ! Escape sequences to move cursor and erase screen.
133
135 PRINT CLEAR$;
!Clear screen
140 PRINT PREFIX$ + '16;4H';
!Move cursor to 16,4
160 PRINT 'Move the cursor to line 16, column 4 and pridt this text.'
170 SLEEP 3%
180 PRINT PREFIX$ + 'lK';
!Erase text
186 PRINT PREFIX$ + '16;4H';
!Move cursor back to 16,4
200 PRINT PREFIX$ + 'SA';
!Move cursor up 5 lines
220 PRINT 'Then move the cursor up 5 lines';
225 SLEEP 3%
230 PRINT CLEAR$;
!Clear screen
250 PRINT PREFIX$ + '10C';
!Move cursor forward 10 spaces
270 PRINT 'and forward 10 spaces';
280 SLEEP 3%
290 PRINT CLEAR$;
!Clear screen
300 PRINT PREFIX$ + 'H';
!Back to home positiqn
310
320 ! Escape sequences for line size control and reverse video
350
!Turn on reverse video
370 PRINT PREFIX$ + '7m';
390 PRINT PREFIX$ + '16H' + ESC$ + '#3';
395 !Change line 16 to double-height top half
400 PRINT 'Double height line in reverse video';
410 !Change line 17 to double-height bottom half
420 PRINT PREFIX$ + '17H' + ESC$ + '#4';
430 PRINT 'Double height line in reverse video';
450 SLEEP 3%
460 PRINT PREFIX$ + 'm';
!Turn off reverse video
470 PRINT CLEAR$
!Clear screen
32767 END

4-28

Terminals
output Escape Sequences
When you send an escape sequence to a terminal, use the value
CHR$(155%) for the escape character if the terminal is in normal
output mode.
Do not use CHR$(27%), which is the ASCII decimal code
for the ESC character, unless you are using transparent control
character mode.
The system translates CHR$(27%) to CHR$(36%), the
dollar sign ($) character.
CHR$(155%), an ESC with the high order bit
set, is a special value that prevents the system from translating the
ESC character to a $ character. When you use CHR$(155%), it causes
the real CHR$(27%) to be sent, allowing the terminal to interpret the
transmitted escape sequence.
See the section, "Transparent Control
Character Output: RECORD 16384% and MODE 16384%" for more information.
In processing output escape sequences, the system counts the escape
characters along with the other characters to be output.
This causes
lines to wrap prematurely on video terminals.
To avoid this line
wrap, open the terminal in MODE 4% (suppress automatic CR/LF).

Input Escape Sequences
Under RSTS/E, terminals can operate in either escape sequence mode or
no escape sequence mode.
DIGITAL recommends that you set escape
sequence mode by using MODE 256% in the OPEN statement (see the
section "Escape Sequence Mode:
MODE 256%").
For compatibility with
existin9 applications, you can set either mode with the Set Terminal
Charact~eristics SYS call (SYS 16), or the SET TERMINAL command (see
the RSTS/E System User's Guide).
New applications should use MODE
256%.
When a terminal is in normal mode, the system recognizes an incoming
ESC character, CHR$(27%), as a delimiter and echoes a CHR$(36%), the $
character. When a terminal is in escape sequence mode, however, the
system does special processing of input escape sequences.
This
special processing is useful for applications such as reading input
from keypad function keys.
Note
To cause a terminal to send escape sequences instead
of numbers when keypad keys are pressed, you must send
an escape sequence to the terminal.
For the VT100 in
ANSI-compatible mode, this escape sequence is "ESC=".
See the appropriate hardware manual for details.
When a terminal is in escape sequence mode, the system processes input
escape sequences so that:
o

The characters in the escape sequence do not echo on the
terminal
4-29

Terminals
o

A BASIC-PLUS program can read and test escape sequences

Input escape sequences are processed after CTRL/S and CTRL/Q (if the
TTSYNC characteristic is set) but before private delimiters and all
other characters.
In brief, the system moves the ESC character from
the beginning to the end of the escape sequence so that BASIC-PLUS can
recognize the ESC character as a delimiter.
The program receives the
escape sequence as follows:
1.

A CHR$(128%) value

The characters in the ESC sequence (minus the ESC character
that started the sequence) without normal data conversions

A CHR$(155%) value, which signals the end of the escape
sequence

Figure 4-1 shows an example of this conversion process.

CHR$(27%) + 'OP'

Terminal

Figure 4-1:

CHR$(128%) +'OP' +CHR$(155%)

)10-

""'---------'
User Program

System

MK-00697-00

Input Escape Sequence Processing

Use GET statements to read incoming escape sequences, not INPUT or
INPUT LINE statements.
Unlike INPUT and INPUT LINE, GET does not
strip the high order bit or discard nulls.
It is also a good idea to cancel type ahead right after you change a
terminal's escape sequence characteristic or open a terminal in escape
sequence mode (see SYS call 11, Cancel All Type Ahead).
Canceling
type ahead makes sure that the terminal's type ahead buffer does not
contain a mixture of data processed in normal and escape sequence
modes.
VT52 and VT100 ANSI-compatible escape sequences are defined so that
matching keys on each terminal send escape sequences that end with the
same character.
Thus, you can use the same code to read incoming
escape sequences from both terminals, regardless of whether the VT100s
are in ANSI- or VT52-compatible mode.
For example, the up arrow key on a VT52 terminal (and a VT100 terminal
in VT52-compatible mode) sends the sequence ESC+"A".
Your program
receives this sequence as CHR$(128%)+"A"+CHR$(155%).
The up arrow key

4-30

Terminals
on a VT100 terminal in ANSI mode sends the sequence ESC+"[A"; your
program receives this sequence as CHR$(128%)+"[A"+CHR$(155%). By
checking for an "A", your program can recognize the up arrow key from
both terminals.
Incoming escape sequences for other keys follow the
same pattern. When you use this technique:
o

Use MODE 256% to set escape sequence mode instead of setting
the terminal's escape sequence characteristic. The system
handles escape sequences that end with P differently for each
method.
See the section "Escape Sequence Mode: MODE 256%"
for more information.

Remember that it works only for reading incoming escape
sequences; on output, your program must distinguish between a
VT100 and a VT52.
See the section "VT100- and VT200-Family
Escape Sequences" for more information.

The rest of this section provides more detailed information on how the
system processes escape sequences in escape sequence mode.
In escape sequence mode, an incoming ESC character CHR$(27%) sets a
flag indicating that an escape sequence follows.
The system does not
echo the ESC character as a $ character and does not echo other
characters in the sequence except for certain control characters. The
terminal handles the characters in the escape sequence as follows:
1.

The ASCII control characters (CHR$(O%) through CHR$(31%) and
CHR$(127%»
are processed first.
Except for DELETE
(CHR$(l27%»
and CTRL/U (CHR$(2l%», their functions do not
change.
The terminal discards DELETE and CTRL/U and does not
passed them to the user.
The control character CHR$(27%)
(escape) starts a new escape sequence.
Note that control characters in escape sequences violate the
ANSI standard and should not be used.

Normal data conversion, such as translating lowercase letters
to uppercase letters, is not done for characters inside an
escape sequence.

The system resumes normal data conversions after it
terminates the escape sequence.

Table 4-5 describes how the system terminates the escape sequence when
it receives one of the escape sequence terminators.

4-31

Terminals
Table 4-5:

Escape Sequence Terminators

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

Sequence

Examples

Comments

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

Y<2 characters>

I
<ESC>Y<linei><coli>IThe VT52 terminal uses this
lescape sequence for direct
Icursor addressing.

O<modifier>
?<modifie'r>

<ESC>OP
<ESC>?M

IThe modifier can be any
Icharacter except a control
Icharacter. VT52 and VT100
Iterminals transmit escape
Isequences of this type when
Ithe terminal is in keypad
lapplication mode and a
Ikeypad key is pressed.
I

P<modifier>

I
P

<ESC>P
<ESC>OP

[<n fillers><terminator>

<ESC>[5A
<ESC>[lOi15H

4-32

IThe modifier can be any
Icharacter except a control
Icharacter. The system
I recognizes this sequence as
Ian escape sequence
I terminator when you set the
Iterminal's ESC SEQUENCE
Icharacteristic but not when
IYou open the terminal with
IMODE 256%. See the section,
IEscape Sequence Mode: MODE
1256%.*
I
IThe system recognizes P as
Ian escape sequence
I terminator when you open
Ithe terminal with MODE 256%
Ibut not when you set the
Iterminal's ESC SEQUENCE
Icharacteristic. See the
Isection, Escape Sequence
IMode: MODE 256%.*
I
IThe filler characters must
Ibe in the range CHR$(32%)
Ithrough CHR$(63%). The
Iterminator character must
Ibe in the range CHR$(64%)
I through CHR$(128%). These
lare ANSI-compatible escape
I sequences.

Terminals
~able

4-5:

Escape Sequence Terminators (Cont.)

+---------------~----~-----+-------------------+----------------------------+

Sequence

Examples

Comments

+ - - - - - - - - - - - - - - - .. - - - - • - - - - - +-------------------+-------------------'- --------+

I
I <n fillers><te:cminator>
I
I
,
,
I
I
I
I
I
I
I

I
I<ESC>*4
I<ESC>I<ESC>O
I
I
I
I
I
I
I
I
I

I
I
IThe filler characters must
Ibe in the range CHR$(32%)
I through CHR$(47%). The
Iterminator character must
Ibe in the range CHR$(48%)
Ithrough CHR$(l26%). These
lare ANSI-compatible escape
I sequences. Some VT52 escape
I sequences, such as <ESC>O
I(red key), are also
Irec09nized by this rule.
I

+- - - - - _ .. - - - - - - - - - - - - _.. - - - - -+- ---------_. -------+- ---------------------------+

, * As ~ln alternative to MODE 256%, an optional patch is available that
I
I
I

causes the system to recognize UP" as an escape sequence terminator.
Unlike MODE 256%, this patch affects all terminals on the system. See
the RSTS/E Maintenance Notebook for details.

I
I
,
I

+ - - - - - - .. - - - - - - - - - - - - - .. - - - - - - - - - - - - - - - - - .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+

The system starts another escape sequence whenever it receives another
ESC character.
If the ESC character precedes or is embedded in one of
the character sequences in Table 4-5, the system does not append the
CHR$(155%) value to the escape sequence it was processing before it
starts processing the next one.

Transparent Control Character Output: RECORD 16384% and MODE 16384%
until recently, most terminals had a character set of 128 characters.
The characters were stored as 8 bits of data and were usually
transmitted that way as well.
The top bit (sign bit) of the 8-bit
byte was always zero.
Now, many terminals support the international character set of 256
characters.
For these terminals, all 8 data bits are significant.
You can set thE~ terminal to correctly handle the 256-character set
using the lEIGHT_BIT qualifier of the SET TERMINAL command.
See the
RSTSIE System Manager's Guide for details.
RSTS/E terminal output processing normally modifies control character~
in a variety of ways.
For example, the terminal prints many
characters with up-arrows, and converts ESC to $. To suppress these
conversions, programs can add 128 to the value of the character to be
printed. However, this is often inconvenient, especially in programs

4-33

Terminals
that must also run on other operating systems.
additional problems on 8-bit terminals.

It also causes

On 8-bit terminals, the characters in the range 128-159 are called "C1
control characters" and have a different meaning from the
corresponding characters with the sign bit cleared.
Since RSTS/E
normally assumes that characters in the range 128-159 are used to
represent "real" control characters in the range 0-31, the new CI
control characters are not normally available.
Transparent control character output solves these problems.
You
specify it by using MODE 16384% in the~ OPEN statement, or by using the
RECORD 16384% mpdifier in the PRINT or' PUT statements.
For example:
PUT #1%, RECORD 16384%
Transparent control character output is, in a sense, an intermediate
form between "normal" and "binary" out.put.
It processes the
backspace, tab, line feed, vertical tab, form feed, and carriage
return control characters in the usual way (for example, if the No Tab
characteristic is set, tab expansion is performed).
It transmits all
other control characters unchanged, including the Cl control
characters.
Character codes 27 (ESC) and 155 (CSI) reset the position
counter (CCPOS function value) to zero.
Other control characters do
not affect the position counter at all. Graphic (printable)
characters are output in the same way as normal output.

Private Delimiters
A "private delimiter" is a character used as a delimiter within a
program.
You can define any printing or nonprinting character to be a
private delimiter.
For example:

A letter

A function key, such as DELETE

A control character, such as CTRL/Z

standard delimiter, such as LINE FEED

A private delimiter is useful on a data entry terminal with a
specialized keyboard.
You can use a large or conveniently located key
as the delimiter key.
Private delimiters are also ~seful in keypad
applications.

You can declare one character as a private delimiter on any RSTS/E
system.
Use the Set Terminal Characteristics SYS call (SYS 16), or
the .SPEC directive (see the RSTS/E System Directives Manual).

4-34

Terminals
Some RS~~S/E systems allow the use of multiple private delimiters.
If
your system has this feature, you can declare up to 256 private
delimitE~rs with the .SPEC directive, available through MACRO.
Multiple private delimiters let you do special character processing
without using single character I/O.
For example, by combining escape
sequencE~s with private delimiters, you can define your own function
keys in keypad applications.
The .SPEC directive lets you set, read, and clear multiple private
delimitE~rs.
You cannot set or read multiple private delimiters in
BASIC-PLUS.
For more information about the .SPEC directive, see the
RSTS/E System Directives Manual.
The rest of this section provides
general information about private delimiters for both BASIC-PLUS and
MACRO programmers.

Characteristics of Private Delimiters
When you declare a character as a private delimiter with either the
Set Terminal Characteristics SYS call (SYS 16) or the .SPEC directive,
it overlrides the existing ASCII code for the character.
Thus, unlike
a standard delimiter such as RETURN or LINE FEED, a private delimiter
does not echo at the te~minal.
In addition, a special character no
longer performs its normal function.
For example, when the DELETE key
is a privai~ delimiter, it does not erase the last character typed.
A private delimiter has basically the same characteristics as a
standard delimiter.
Like a standard delimiter, it:
o

Terminates a read operation.

Cannot be deleted (except with CTRL/X).
The DELETE key and
CTRL/U do not affect private delimiters in the type ahead
buffer.

Causes the system to awaken a sleeping job when typed at a
terminal that the job has open or assigned.
If the job
cannot be awakened, the system stores the private delimiter
character.

Once set, a private delimiter remains in effect for a terminal until
either:
o

The program clears it.

The job releases the terminal by deassigning it or by closing
the I/O channel where the terminal is open.

In addition, the system clears private delimiters when a dial-up line
is hung up or the job controlling the terminal is killed.

4-35

Terminals
Private delimiters change the way characters are prpcessed in binary
mode (MODE 1%). When a terminal is open in binary mode and no private
delimiter is in use, the system terminates a read after every
character.
However, if one or more private delimit~rs are in use, the
system terminates a read only when a private delimiter is typed.
The system processes private delimiters after processing CTRL/S and
CTRL/Q (if the TTSYNC characteristic is set) and escape sequences (if
the terminal is in escape sequence mode).
This feature prevents a
terminal from becoming permanently stalled, and it also lets you use
private delimiters and escape sequences in the same program.
The system processes private delimitelrs before all other characters,
including control characters (for example, CTRL/C).
Thus, when you
use a standard delimiter character as a private delimiter, it does not
echo on the terminal.

usage Notes for Private Delimiters
Follow these guidelines when using private delimiters:
o

In a BASIC-PLUS program that uses a private delimiter, you
must read input from the terminal with GET statements.
Private delimiters do not work with INPUT, INPUT LINE, or MAT
INPUT statements.

By combining escape sequences with private delimiters, you
can define your own function keys without using single
character I/O.
Follow these steps:
1.

Make sure the keypad is in the right mode for your
application.

Define each function as the PF1 key followed by a
character.

Define each character as a private delimiter so it does
not echo on the terminal.

For example, you might define PFI + A as one function and PFI
+ M as another function.
o

To return a private delimiter character to its normal
function, execute the Set Terminal Characteristics SYS call
(SYS 16) or the .SPEC directive again~
Note that while you
can set and read multiple private de1imite(s only with the
.SPEC directive, you can clear multiple private delimiters
with either the .SPEC directive or the BASIC-PLUS SPEC%
function (see the section "Private Delimiters").

4-36

Terminals
Terminal Special Function: SPEC%
The SPEC% function performs special operations on terminals, pseudo
keyboards (see Chapter 4), disks (see Chapter 1), flexible diskettes
(see Chapter 1), magnetic tapes (see Chapter 2), and line printers
(see Chapter 3).
For terminals, the SPEC% function allows you to cancel CTRL/O, set
modes for tape, echo, and ODT, cancel type ahead, and clear private
delimitE~rs.
The SPEC% function for terminals has the format:
VALUE~~=SPEC% ( FUNCTION%, PARAMETER, CHANNEL%, 2 %)

where:
depends on the function code specified in FUNCTION%.
FUNCTION%

is the function code.
The SPEC% function performs
various operations on terminals as determined by the
FUNCTION% code.
These codes are:
FUNCTION%=O
FUNCTION%=l
FUNCTION%=2
FUNCTION%=3
FUNCTION%=4
FUNCTION%=7
FUNCTION%=9

Cancel CTRL/O.
Set tape mode.
Enable echo and clear tape mode.
Disable echo.
Set ODT mode.
Cancel all type ahead.
Clear all private delimiters.

PARAME:TER

specifies the terminal on which the operation is to
take place.
If PARAMETER is 0, the system performs
the operation on the currently open terminal.
If you
specify a keyboard number in PARAMETER, the system
performs the operation on that terminal.
Note that
you must allocate the keyboard to the calling job but
you must not open it.

CHANNE:L%

specifies the I/O channel for the terminal in
PARAMETER.

is the handler index for terminals.

Pseudo

]~eyboards

A pseudo keyboard is a logical device that has the characteristics of
a terminal but has no terminal associated with it.
Like a terminal, a
pseudo keyboard has an input buffer and an output buffer, both of
which come from the small buffer pool.
User programs can send input
to and get output from these buffers.

4-37

Terminals
Using a pseudo keyboard lets one job control other jobs on the system.
Pseudo keyboards are especially useful for batch operations because
they let you do terminal I/O without tying up a terminal.
The system manager sets the number of pseudo keyboards on the system
during system installation.
The systE~m assigns a device name of PKn:
to each pseudo keyboard and associates each one with a keyboard unit
number KBn: but not with a physical terminal.
For example, the system
may associate PK5: with KB8: even though no physical keyboard 8
exists.
Using a pseudo keyboard involves a controlling job and a controlled
job.
The controlling job (your program) creates the controlled job
and then does I/O to it through the pseudo keyboard, PKn:.
You can
run LOGIN and use both system and pro9ram commands to control the job.
The controlling job uses the pseudo keyboard to perform input to and
extract output from the controlled job (which runs on KBm: associated
with PKn:).
However, the controlled :job qoes not know it is working
with a pseudo keyboard.
Instead, it does input and output on its own
keyboard, KB:.
Figure 4-2 shows the interaction between the controlled and
controlling jobs.

4-38

Terminals

IL_

CONTROLLING
JOB

GET,
INPUT,
INPUT LINE

PKm:
KBn:

PUT,
PRINT
lit

OUTPUT
BUFFER
FOR

INPUT
BUFFER
FOR

CONTROLLED
JOB

CONTROLLED
JOB
GET,
INPUT,
1
INPUT LINE

PUT,
PRINT

[

Controlling job
does I/O to PKm:

Controlled job
does I/O to KBn:

CONTROLLED
JOB
------'

Figure 4·2:

MK-00696-00

Pseudo Keyboard Operations

The system transfers data to a pseudo keyboard in full duplex mode.
This means that strings sent by PUT or PRINT statements are echoed in
the output buffer of the associated keyboard unit.
Your program can
read this echo with GET, INPUT, or INPUT LINE statements.
In
addition, when you send a carriage return character (CHR$(l3%)) to the
controlled job's input buffer, the system automatically appends a line
feed cha.racter.
The rest of this section contains the following pseudo keyboard
information:
o

How to access a pseudo keyboard, create a controlled job, and
perform pseudo keyboard I/O

A sample program

The SPEC% function for pseudo keyboards

4-39

Terminals
Accessing the Pseudo Keyboard
Use the OPEN statement to access a pseudo keyboard.

For example:

10 OPEN "PKO:" AS FILE #1%
This OPEN statement associates pseudo keyboard unit 0 with I/O channel
1 and sets up its input and output buffers. Use this simple form of
the OPEN statement; the system ignores the optional phrases FOR INPUT
and FOR OUTPUT when opening pseudo keyboards.
Two MODE values are available for pseudo keyboards. MODE 0%, the
default, causes the system to kill the controlled job when you close
the pseudo keyboard. MODE 1% requires EXQTA privilege and causes the
system to detach the controlled job when you close the pseudo
keyboard.
For example:
100 OPEN "PK3:" AS FILE #1%, MODE 0%
200 OPEN "PKS:" AS FILE #2%, MODE 1%

300 CLOSE #1%, #2%
When these statements execute, the system kills the job running on
PK3: and detaches the job running on PKS:.
When the PK side of a pseudo keyboard is open, its KB side functions
like a real keyboard.
It can be opened, closed, assigned, and
deassigned.
You can broadcast data to it and force input to it.
However, when the PK side of a pseudo keyboard is not open, its KB
side functions like a disabled terminal.
The system do~s not process
input from it or send output to it.
See the Disable Terminal SYS call
(SYS 8) for more information about disabled terminals.
Two errors can occur when you open a pseudo keyboard:
o

If the device you specify do(~s not exist on the system, the
error ?Not a valid device (ERR=6) occurs.

If another job has the device assigned or opened, the error
?Device not available (ERR=8) occurs.

Creating the Controlled Job
After you open a pseudo keyboard, you must start the controlled job.
The normal way to create the controlled job is with the Create A Job
SYS call, (SYS 24).
In some cases, you could force the LOGIN dialogue
instead, but that requires you know the account password-.
4-40

Terminals
After the controlled job is running, you can send system commands,
program commands, and program responses to the PK device by using PUT
or PRIN1 statements with various RECORD options. Use GET statements
to obtain output from the controlled job. The next section explains
pseudo keyboard I/O in detail.
1

Pseudo Keyboard I/O
Reading from a pseudo keyboard is the same as reading from the
controlled job's screen; writing to a pseudo keyboard is the same as
typing alt the controlled job's terminal or forcing input to the
controlled job's keyboard.

Pseudo Keyboard Input
To obtain output from the controlled job, execute a GET statement on
the I/O channel where the pseudo keyboard is open.
For example, the
following statement transfers data from the controlled job's output
buffer to your program's channell buffer:

100 GET #1%
The system never stalls the controlling program to wait for data.
Instead, it immediately returns the contents of the controlled job's
output buffer to the controlling job.
The buffer contents may be a
single message, several messages, or a message fragment.
If no input
is available, the error ?End of file on device (ERR=ll) occurs.
If the controlled job performs output faster than the controlling job
can execute GET statements, the keyboard output buffer fills. As a
result, the controlled job enters an output wait state (TT) as if it
were waiting for a real terminal. When the stall occurs, the system
makes the controlling job eligible to run (if it was in the SLEEP
state) so that it can execute GET statements and receive the
controlled job's output.

Pseudo Keyboard Output
To perform output to a pseudo keyboard, execute a PRINT or PUT
statement with a coded value in the RECORD option.
For example:

100 PUT #N%, RECORD R%, COUNT C%
where:
N%

is the I/O channel where the PK device is open

4-41

Terminals
C%

is the number of bytes to send from the I/O buffer to the
controlled job's input buffer.
If you omit the COUNT option, the PUT statement sends either
128 bytes (the pseudo keyboard's default buffer size) or the
number of bytes specified in the RECORDSIZE option of the OPEN
statement.

determines the actions the system performs for a specific PRINT
or PUT statement.
R% is an integer whose va~ue the system
interprets on a bit-by-bit basis.
The system tests the low
order four bits in R% (the bits numbered 0 through 3 from right
to left) and executes the PRIN~~ or PUT statement depending on
whether certain bits are on or off.
Figure 4-3 explains the bit tests.

4-42

Terminals

CtN=1

ERR=5
>--.---11P1 (JOB IS NOT
LOGGED IN)

ERR=3
>-_.---11P1 (DEVICE IN
USE)

ERR=28
(JOB IN KB
WAIT BUT NOT
CTRlIC STATE

DO NOT
SEND ANY
DATA

SEND
CHARACTERS
TOKB

OFF=O

>-----~

WAIT UNTIL
ROOM IS
AVAILABLE

ERR=4
(NO ROOM FOR ~-------------------~---11P1
INPUT ON KB)

RETURN
CONTROL
TO USER

EXIT)

YES

MK-00031-01

Figure 4-3:

PUT Statement Actions for Pseudo Keyboard Output
4-43

Terminals
Figure 4-3 shows the actions the syste!m performs by testing the bits
in R%.
In summary:
Bit 0 (value

= 1)

If set, the system does not check job status
before sending data to the pseudo keyboard.

Bit 1 (value

= 2)

If set, the system tests whether the pseudo
keyboard is waiting for a system command (AC
state) or is waiting for program input (KB wait
state).

Bit 2 (value

= 4)

If set, the system does not send data to the
pseudo keyboard but instead returns control to the
controlling program.

Bit 3 (value

= 8)

If set, and there are no small buffers for
keyboard input, the system waits until small
buffers are available. However~ your program
receives an error if the output buffer chain is
full.

The data you send to a pseudo keyboard must have the same format as
data typed at a keyboard.
For examplE~, if you send a line that would
normally end with the RETURN key, you must end the line with a
carriage return character (CHR$(13%»u
In addition, the value you
specify in the COUNT option must include the carria~e return
character. Do not end the line with a carriage return/line feed
sequence; the system automatically appends a line feed character to a
line that ends with a carriage return character (just as it does when
you enter a line at a terminal with the RETURN key).
Your program should send only one line at a time and retrieve each
program or system response separately"
Sending multiple lines fills
up small buffers.
For the same reason, the user should not type
ahead.
In addition, do not send a line unless the PK device is
waiting for input. Always check PK dE~vice status before sending data.
Use the RECORD 6% option (values 2 and 4) in a PUT or PRINT statement
to ensure that the controlled job is at command level.
If the job is
waiting for keyboard input but is not at command level, the error
?Programmable AC trap (ERR=28) occurs,. You must force a CTRL/C to the
controlled job; otherwise, control returns to your program, which can
then send a system command.
'
To run a program under the controlled job:
1.

Use a PUT or PRINT statement with the RECOlD 6% option to
make sure that the controlled job is at co~mand level.

Send the RUN command followed by the program name to the PK
device.
4-44

Terminals
The RECORD 16% option lets you kill any job currently running on the
pseudo keyboard.
In the PUT statement, specify the I/O channel where
the pseudo keyboard is open.
For example:
100 PUT

#8%~

RECORD 16%

This statement kills the job currently running on the PK:
on channel 8.

unit open

Pseudo Keyboard Escape Sequence Processing
When you output escape sequences on a pseudo keyboard, the terminal
driver translates CHR$(155%) to an escape ESC character (ASCII 27).
The translation is necessary to properly handle eight bit terminal
input. ATPK takes that pseudo keyboard output and displays it on your
terminal.
However the terminal driver now translates the ESC
character to a $ character.
To make pseudo keyboard processing work correctly when using escape
sequences, use either binary MODE (1%), or transparent control
character output MODE (16384%) as an open mode, or use the RECORD
4096% modifier.
This allows the terminal driver to correctly read
escape characters back from the pseudo keyboard (without translation).
See the seGtions "Binary Data output and Input: RECORD 4096% and MODE
1%" and "Transparent Control Character Output: RECORD 16384% and MODE
16384%" for more information.

Programm.ing Example
The following sample program uses a pseudo keyboard to process a
command file:
10
100
110
120
130
140
150
160
170
180
190
200
210
220
230
240

EX.TEND
OPEN "PK8:" AS FILE #1%
PRINT "What command file do you want to use";
INPUT LINE FILENAME$
OPEN FILENAME$ FOR INPUT AS FILE #2%
PRINT "What is the account to log into";
INPUT LINE PPN$
PPN$ = CVT$$(PPN$,4%)
INPUT "What is the password"; PW$
PRINT #1%, RECORD 1%, "HELLO "; PPN$; CHR$(13%);
PRINT #1%, RECORD 1%, PW$ + CHR$(13%);
ON ERROR GOTO 19000
SLEEP 1%
GET #1%
FIELD #1%, RECOUNT AS A$
PRINT A$;
4-45

Terminals
250 GOTO 220
260 PRINT #1%, RECORD 4%
270 INPUT LINE #2%, B$
280 B$ = CVT$$(B$,4%)
290 PRINT #1%, B$; CHR$(13%);
300 GOTO 220
19000 IF ERR = 11% AND ERL = 220% THEN RESUME 260 &
ELSE IF ERR = 3% AND ERL = 260% THEN RESUME 210 &
ELSE IF ERR = 11% AND ERL = 270% THEN RESUME 19100 &
ELSE ON ERROR GOTO 0
19100 CLOSE #1%, #2%
32767 END
Line 100 opens the pseudo keyboard on I/O channell.
Lines 110
through 170 ask the user (the controlling job) for a command file name
and accounting information for the controlled job.
Lines 180 and 190
create the controlled job by sending :LOGIN input to the pseudo
keyboard.
Both PRINT statements use RECORD 1% to tell the system not
to check job status before sending data.
The next section of the program consists of two loops:
o

The first loop (lines 220 through 250) repeatedly gets data
from the controlled job's output buffer and prints it on the
controlling job's terminal. When there is no more data in
the buffer, control goes to the error handling routine at
line 19000.

The second loop (lines 260 through 300) first uses a PRINT
statement with RECORD 4% to see if the controlled job is
waiting for keyboard input.
Lf it is, the program reads a
line from the command file and sends it to the controlled
job's input buffer.
Control then goes back to the first
loop.
If the controlled job is not waiting for keyboard input,
control goes to error handling routine.

The error handling routine (lines 19000 through 19100) processes two
errors:
o

?End of file on device (ERR=ll).
This error can occur for
two different reasons in this program:
The controlled job's output buffer is empty.
There are no more commands in the command file.
If the output buffer is empty, control goes to the loop that
reads the next command from the command file.
If there are
no more commands in the command file, the program closes I/O
channels and ends.
4-46

Terminals
o

?Account or device in use (ERR=3).
This error occurs if the
controlled job is busy (that is, not waiting for keyboard
input) when the program checks to see if it is ready for
another command.
The error handling routine transfers
control to the SLEEP statement at line 210, which suspends
program execution for one second before starting to execute
the first loop again.
The program works without the SLEEP
statement but makes less efficient use of system resources.

Pseudo Keyboard Special Function: SPEC%
The SPEC% function performs special operations on pseudo keyboards,
terminals (see Chapter 4), disks (see Chapter 1), flexible diskettes
(see Chapter 1), magnetic tapes (see Chapter 2), and line printers
(see Chapter 3)0
For pseudo keyboards, the SPEC% function lets you:
o

Disable and enable echo at the controlled job's keyboard
(that is, the KB side of the pseudo keyboard)

Read a flag word that tells you whether echo is ON or OFF at
the controlled job's keyboard

Read the current exit status of the job you are controlling.

pseudo keyboard receives two kinds of output from a controlled job:
character echo, which is done by the RSTS/E monitor, and program
output, which occurs when a program writes to the controlled job's
keyboard.
The SPEC% function affects only character echo, not program
output.

Character echo is enabled by default.
However, in some pseudo
keyboard applications it is more convenient to disable character echo.
For example, in a pseudo keyboard application that uses both a
terminal and a pseudo keyboard, you get character echo from the
terminal; you also get character echo and program output from the
pseudo keyboard.
You can use this function to disable character echo
at the pseudo keyboard.
The SPEC% function for pseudo keyboards has the format:
VALUE% = SPEC%(FUNCTION%, PARAMETER%, CHANNEL%, 16%)

4-47

Terminals
whe rOe:
VALUE%

depends on the function code you specify in FUNCTION%.
FUNCTION%=O%

a flag word that contains information
about the controlled job's keyboard.
By
testing bit 5 in VALUE%, you can
determine whether keyboard echo is
enabled or disabled.
The tests are:
VALUE% AND 32% <> 0%
Keyboard echo is disabled.
VALUE% AND 32% = 0%
Keyboard echo is enabled.

FUNCTION%=l%

returns the current exit status and the
worst exit status for the job you are
controlling:
VALUE% AND 7%
The current exit status, from the list
below.
(VALUE%/16%) AND 7%
The worst exit status the job has had,
from the list below.
Value
0%
1%
2%
4%

PARAMETER%

status
warning
Success
Error
Severe error

depends on the function code you specify in FUNCTION%.
FUNCTION%=O%

FUNCTION%=l%

specifies the operation to perform:
Value

Operation

0%
255%
-1%

Read the flag word
Enable echo
Disable echo

unused

CHANNEL%

specifies the I/O channel where the pseudo keyboard is
open.

16%

is the device handler index for pseudo keyboards.

4-4E1

Chapter 5
DECtape, Paper Tape, and Card Reader

This chapter describes how to process TU56 DEC tape as a
file-structured and a non-file-structured device. This chapter also
describes the use of paper tape and card readers on RSTS/E.

Fil~structured

DECtape: TU56

To indicate file-structured process1ng on TU56 DECtape, include a file
name with the device specification in the OPEN statement. Up to 15
files can be open for read access simultaneously on a TU56 DECtape
drive.
However, only one file can be open for write access. An
attempt to open a second file for write access while one is currently
open generates the error ?Too many files open on unit (ERR=17).
When a file is opened on Tu56 DECtape, RSTS/E implicitly allocates the
unit to the job performing the OPEN operation. Another job attempting
to access the DECtape receives the error ?Device not available
(ERR=8).
For the job performing the OPEN operation, BASIC-PLUS
creates a 510 byte buffer. Only 510 bytes are usable in a
file-structured TU56 DECtape block because the system treats the
remaining two bytes as a pointer to the next block in the file.
(See
Figure S-l.) GET and PUT statements read and write successive blocks
on the tape.
You cannot use the RECORD option to access blocks in the
file in a random manner.
u

If you specify the RECORDSIZE option in the OPEN statement, the system
creates a buffer of the value given in the option. For a buffer size
less than 510 bytes, a GET statement returns that many bytes from the
first part of 510-byte block. A P~T statement writes one block and
fills the remainder of the 510 bytes with NUL characters.
For a
buffer size greater than 510 bytes, a GET statement reads one block of
510 bytes and a PUT statement generates the error ?Illegal byte count
for I/O (ERR=31).

5-1

DEctape, Paper Tape, and Card Reader
Non-File-structured DECtape: TU56
In non-file-structured processing of 'TU56 DECtapes, you can access
specific physical blocks on the DECtape.
To start non-file-structured
processing, specify only a device designator in the OPEN statement.
Only OPEN FOR INPUT and OPEN are valid.
The following two statements
are equivalent because both reading and writing of physical blocks on
the device are permitted:
100 OPEN "DT1:" FOR INPUT AS FILE 1%
100 OPEN "DT1:" AS FILE 1%
BASIC-PLUS creates a 512-byte buffer.
The following statement is
invalid because it attempts to create a file:
100 OPEN "DT1:" FOR OUTPUT AS FILE 3%
After opening a TU56 DECtape device for non-file-structured
processing, you can use the RECORD option in GET and PUT statements to
retrieve and write specific physical blocks on the device.
The record
number you specify is interpreted as a block number. When the RECORD
option specifies a negative block number, the designated block is
accessed backwards.
(Block a cannot be accessed backwards.) For
example, the following statement reads block 4 of the file opened on
channel 1% backwards:
200 GET #1%, RECORD -4%
The maximum block number is 577.
In writing non-file-structured TU56 DEC tape files, you can specify how
blocks should be accessed. Whenever possible, the system writes a
file on a file-structured DECtape on every fourth block (that is,
block N, N+4, N+8, and so on) of the DECtape.
This procedure
optimizes DECtape access time. When the system reaches the last block
of the tape, it begins to write blocks backwards in intervals of four.
It then repeats the entire process to fill in the available blocks on
the TU56 DECtape.
Because the blocks are not physically contiguous in file-structured
mode, the first word of each block of a file is a pointer to the next
logical block of the file.
These blocks are linkedi by these pointers.
The TU56 DEC tape format diagram (see Figure 5-1) shOWS how
non-file-structured DEC tape access time can be minimized.
The link pointer is either positive or negative. A negative pointer
indicates the block was written in the reverse direction. A positive
pointer indicates the block was written in the 'forward direction. Use
a negative value in the RECORD option to access a block written
backwards.

5-2

DECtape, Paper Tape, and Card Reader
Figure 5-1 shows the Tu56 DECtape format.

~ l~lVED FOR BOOTSTRAg
1

A DEC tape has 576 blocks of 256 words each.
The first word in every block of a linked file is a pointer to the next
logical block of that file.
(The pointer contains the physical block #
of the next logical block; it is positive for forward tape motion and
negative for backward tape motion.)

LINKED FILES

~~~~~~====~~
LINKED FILES

The remaining 255 words are data.
DEC tape directory structure can catalog and map a maximum of 56 files.

FILE BI'r MAPS FOR FILES 1-7

FILE BU MAPS FOR FILES 8-14

FILE BIT MAPS FOR FILES 15-21

FILE BIT MAPS FOR FILES 22-28

FILE BIT MAPS FOR FILES 29-35

FILE BIT MAPS FOR FILES 36-42

FILE BIT MAPS FOR FILES 43-49

FILE BIT MAPS FOR FILES

FILE BIT MAP (36 WORDS) FILE 22

Each File Bit Map has 36
words (=576 bits)

FILE BIT MAP (36 WORDS) FILE 23
FILE BIT MAP (36 WORDS) FILE 24

5~-56

MFD BLOCK #1
19i1
1~2

MFD BLOCK #2

-------------------UFO BLOCK #1

1~3

UFO BLOCK #2

1~4

MASTEH/PERMANENT BIT MAP

1~5

LINKED FILES

1~77

[

F'ILE BIT MAP (36 WORDS) FILE 25

256

""""" "",~1

FILE BIT MAP (36 WORDS) FILE 26
FILE BIT MAP (36 WORDS) FILE 27
FILE BIT MAP (36 WORDS) FILE 28

LINKED FILES

Each File Bit Map maps
the entire DECtape.

(4 WORDS UNUSED)

~ {~;~ :~~::

-~J

Each bit maps 1 block
of the DECtape. (A set
bit means an allocated
block; a clear bit means
a free block.)

1~18

(link to MFD block #2)
(interleave factor)
(pointer to 1st Master Bit Map)
4th word: 1~48 (pointer to non-existant 2nd
Master Bit Map)
252 words unused

256
words

1st word:

1~48

(link to non-existant MFD block #3)
UIC
POINTER TO UFO
START BLOCK (l~28)

256
up to 63 4-word entries
each with format shown

OF WORDS PER
UFO ENTRY (=9)
{6

remainder unused.
MFD BLOCK #2

1st word: 1{638 (link to next UFO block) or {6 (end of
chain)

RSTS does not read or check
DEC tape UIC's.

FILENAME (PART 1) RAD5~

When zeroing a DEC tape RSTS
enters a UIC of [1,1].

FILENAME (PART 2) RAD5{6

28 file entries (max)
9 words each with this
format:

UFO BLOCKS
RSTS ignores - LOCK Bits, USAGE COUNT,
and END BLOCK entries in the UFO.
RSTS checks the "TYPE" bit (bit 15)
and will allow a "CONTIGUOUS" file
to be OPENed.

256

EXTENSION RAD5~

t = File Type
{6 = Linked
1 = Contiguous

CREATION DATE
LOCK

-i- I

USAGE
COUNT

START BLOCK #
LENGTH

When creating a DEC tape file, RSTS
writes a protection code of 2338 (for
DOS-11 compatibility). But RSTS does
not read or check DEC tape protection
codes.

END BLOCK #
3 words unused

I~ROTECTION
CODE

4 word header
256
words

{

36 word bit map of entire DEC tape (a logical
OHing of all File Bit Maps)

MK-00032-00

Figure 5-1:

TU56 DECtape Format
5-3

DECtape, Paper Tape, and Card Reader
Paper Tape
The paper tape reader and punch output data onto unoiled paper tape.
In a punch operation, characters are read from the l/O buffer and
translated into perforations on the tape.
In a read operation, the
tape perforations are translated back into charactets and written to
your I/O buffer.
You can specify two modes to set even or odd parity
for the characters punched on the tape! and to check the parity of the
characters read from the tape.

Punching with Parity on Paper Tape
Use the MODE option in an OPEN statement to control the parity of data
punched on the paper tape.
Bit 1 of the mode word (value 2) enables the punching of paper tape
with a generated parity.
If this bit is not set, the paper tape punch
(PP:) driver passes eight-bit characte~rs from the buffer to the tape
without a parity bit.
If bit 1 is set, the PP: driver generates the
parity bit for each character from the buffer and passes the parity
and character to the tape.
Bit 0 of ~the mode word (value 1) specifies the parity that is to be
passed with ea6h character.
If bit 0 is not set, characters are
passed to the tape with even parity.
If bit 0 is set, characters are
passed to the tape with odd parity. PLS each character is punched, the
high-order bit is removed and the appropriate parity bit is added to
the character.
Note that bit 0 is ignored if bit 1 is not set.
Valid MODE values are:
MODE 0%
MODE 2%
MODE 3%

No parity punched
Even parity
Odd parity

Parity Checking on Paper Tape
You can also use the MODE option in an OPEN statement to check the
parity of paper tape data.
Bit 1 of the mode word (value 2) enables parity checking.
If this bit
is not set, the paper tape reader (PR:) passes eight-bit characters
from the tape to the buffer without checking parity.
If bit 1 is set,
the PR: driver performs parity checking on the characters that it
reads.

5-4

DEctape, Paper Tape, and Card Reader
Bit 0 of the mode word (value 1) specifies the expected parity of the
data on the tape.
If bit 0 is not set, the driver checks the tape for
even parity.
If bit 0 is set, the driver checks for odd parity. As
the PR: driver reads the tape, it checks the parity of each character.
If th( parity is as specified, the driver removes the high-order bit
(the parity bit) and writes a seven-bit character to your buffer.
If
the parity does not match the specification, the driver writes a
seven-bit character with the high-order bit set. After the tape is
read, any characters in the buffer with bad parity return the error
?Data error on device (ERR=13).
Note that bit 0 is ignored if bit 1 is not set.
Valid MODE values are:
MODE 0%
MODE 2%
MODE 3%

No parity check
Check for even parity
Check for· odd parity

Note that the RECOUNT variable (see the BASIC-PLUS Language Manual)
contains the number of characters read after every input operation.
with this information, your program can scan the buffer for any
characters with a bad parity flag.

Card Reader
The card. reader reads data from standard (80-column) punched cards.
Data is read from the card one column at a time in one of three modes:
ASCII, packed Hollerith, or binary.
One card can be read (and the
data on it stored) in any mode.

ASCII Mode: MODE 0%
The card. reader reads cards punched with the standard ASCII codes, as
shown in Appendix B. One of four sets of codes can be used: ANSI,
029, 026, or 1401. The code set for the system is specified during
system installation.
Cards punched in other formats are not
acceptable to RSTS/E in ASCII mode.
The end-of-file card for RSTS/E
contains a 12~11-0-1 or a 12-11-0-1-6-7-8-9 punch in card column 1.
Reading an end-af-file card causes the error ?End of file on device
(ERR=ll), which can be trapped with an ON ERROR GOTO statement.
The RECOUNT variable (see the BASIC-PLUS Language Manual) contains the
number of characters read following every input operation.
In the
ASCII read mode, trailing spaces are ignored and carriage return and
line feed characters are appended, making the value of the RECOUNT
variable' two more than the number of punched columns per card.
Consequently, the RECOUNT variable can have a value between 2 (for a
5-5

DECtape, Paper Tape, and Card Reader
blank card) and 82 (for 80 columns of data).
card punched as follows:

For example, consider a

ABCDEFGHIJKLMNOPQRSTUVWXYZ
Columns 1 to 26 are punched and 27 through 80 are blank.
following program executes as shown:

The

100

OPEN nCR:" AS FILE 1%
\INPUT LINE #1%, A$
\PRINT LEN(A$)
\PRINT ">" iA$i "<"
32767 END

RUNNH
28
>ABCDEFGHIJKLMNOPQRSTUVWXYZ

<
In this example, the trailing spaces in card columns 27 through 80 are
deleted, and the two characters, carriage return ana line feed, are
added, making a total of 28 characters in the string A$.
You can read cards with INPUT, INPUT LINE, or GET statements.
If a
card is misread or contains any illegal punches, the error ?Data error
on device (ERR=13) occurs. With INPu~r or INPUT LINE statements, any
columns containing illegal punches arE~ stored as BA~KSLASH (ASCII 92)
codes.
If you read the card with a block I/O GET statement, the
buffer contains data for each column punched, and any columns that
contain illegal punches are stored as ASCII 220 code (BACKSLASH with
the high order bit set). By checking the characters for code 220,
your program can determine in which c()lumn(s) the error(s) occurred.

Packed Hollerith Mode: MODE 1%
In packed Hollerith read mode, the value of the RECOUNT variable is
always 80, because each of the 80 card columns corresponds to a single
data byte and trailing spaces are not ignored. The value of each byte
is the sum of the punched row positions.

5-6

DEctape, Paper Tape, and Card Reader
Figure S-2 shows the packed Hollerith read mode values
Associated Values of Rows
#1:2
#1"

ROWS

-_
- -_
__
1_
264
8
_-_
_ _ _ _ _ _ 32

# ()
# "
# :2

______ 1
______ 2

#:3

______ 4

------3

# 4
# !5
# 13
# l
# B
# !~

______ 5

------6
______ 7
-------8
_ _ _ _ _ _ _ 16
COLUMNS

BIT
ROW

VALUE

128

Figure 5-2:

1-7
4

MK-00033-01

Packed Hollerith Read Mode

Note that the associated values of rows 1 through 7 are simply 1
through 7, respectively.
Only one of these seven rows can be punched
per column.
If none of these seven rows is punched, the value of the
byte is O.

Binary Mode: MODE 2%
The binalry read mode associates two data bytes with each card column.
Therefore, the value of the RECOUNT variable is always 160. Once
again, the value of each byte is the sum of the values of the punched
row positions.

5-7

DEctape, Paper Tape, and Card Reader
Figure 5-3 shows the binary read modes.

--,--

#12
#11

ROWS

# 0
# 1
# 2
# 3
# 4
# 5
# 6
# 7
# 8
# 9

Associated Values of Rows

______ 8

______ 4
______ 2
______ 1

---f-

SECOND BYTE

_ _ _ _ _ _ 128
_ _ _ _ _ _ 64
_ _ _ _ _ _ 32

_ _ _ _ _ _ 16
______ 8
_ _____ 4

FIRST BYTE

___ 1__

2
1

COLUMNS

BIT

ROW

7
2

I I I II

FIRST BYTE

SECOND BYTE

MK-00034-01

Figure 5-3:

Binary Read Mode

Setting Read Modes
You can specify a read mode in an OPEN statement (with the MODE
option) or a GET statement (with the RECORD option).
Table 5-1 shows
the MODE and RECORD values that correspond to each read mode.
The
default mode is 0 (ASCII).
As shown in Table 5-1, you must specify an explicit value when you use
the MODE or RECORD option; failure to do so results in an error
message.

5-8

DEctape, Paper Tape, and Card Reader
Table 5-1:

Specifying Read Modes on Card Reader

+- - - - - _ .. - - - -+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - --+
I Statement I
Option
I Specified Read Mode I
+- - - - - _ .. - - - -+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - --+

MODE 0
MODE 1.
MODE 2

OPEN

ASCII
Packed Hollerith
Binary

RECORD 256
ASCII
RECORD 257
Packed Hollerith
RECORD 258
Binary
+- - - - - _ .. - - - -+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - --+
GET

For example:
60 OPEN "CR:" FOR INPUT AS FILE 2%, MODE 1%
110 GET #2%, RECORD 258%
Line 60 of the example specifies packed Hollerith read mode.
specifies binary read mode for the first card.

Line 110

A read mode specified in an OPEN statement supersedes previous read
mode specifications. A read mode specified in a GET statement,
however overrides previous read mode specifications in the program
for one card only.
Consider the following sample program segment:
j,

Specified Read Mode
at This Point
100

OPEN "CR:" FOR INPUT AS FILE 1%, MODE 1%
\GET #1%, RECORD 256%
\GET #1%
350
CLOSE 1%
400
OPEN "CR:" FOR INPUT AS FILE 6%, MODE 0%
\GET #6%
\GET #6%, RECORD 258%
\CLOSE 6%
32767 END

Hollerith
ASCII
Hollerith
ASCII
ASCII
Binary

Line 100 of the sample program sets the read mode to Hollerith and
then overrides it, setting the read mode to ASCII temporarily. When
the last statement on the line is executed without a RECORD option,
however, the read mode reverts to the OPEN mode -- in this case,
Hollerith.
The next OPEN statement (line 400) supersedes the previous
one, setting the read mode to ASCII.
However, a RECORD 258% option
changes the mode to binary.
Closing a file cancels the card reader's
read mode. When a file has been closed, executing an OPEN statement
is the only way to reestablish a read mode.

5-9

Chapter 6
DMCll/DMRll Interprocessor Link

This chapter describes how to use the DMCll and DMRll devices in a
program to set up a communication link to another processor. Although
the DMRll differs in some details from the DMCll, they appear
identical to your program.

Using the DMCll/DMRll Interprocessor Link in Point-to-Point
Configurations
The DMC11/DMRl1 Network Link (device XM: on RSTS/E) provides high
speed local or remote interconnection of computers over a serial
synchronous link.
It uses the Digital Data Communications Protocol
(DDCMP) to provide data transmission and uses Non-Processor Request
(NPR) data transfers to and from memory to provide high throughput and
minimize processor overhead.
Normally, the DMC11/DMR11 is used by the DECnet/E package, which
supports multiple node networks, user data security, multiple logical
links over a single physical link, and other network features. When
in use by DECnet/E, the DMC1l/DMR11 is not available to you except
through DECnet/E. However, in point-to-point configurations, DECnet/E
may not be needed.
In these cases, you can access the XM: device
directly from a program to obtain a communication link with another
processor.
DECnet/E need not even be configured into the RSTS/E
system.

The OPEN statement
The DMC11/DMRl1 is not a file-structured device. However, you must
specify certain parameters at open time to establish the device's
operating mode.
In addition, when you execute an OPEN statement on a
DMC/DMR with an autoanswer/autodial phone connection, the Data
Terminal Ready (DTR) modem control signal is automatically raised to
enable data transmission.
6-1

DMCll/DMRll Interprocessor Link
MODE Value
The MODE value used when opening a DMC11/DMR11 indicates whether the
unit is to be run in full-duplex or half-duplex mode.
These modes are
described in the Terminals and Communications Handbook.
To cause the
DMC11/DMR11 to hang up a phone connection when it receives a DDCMP
restart, add 512 to the specified MOD]~ value.
To specify full duplex,
omit the MODE option in the OPEN statf~ment, or specify a MODE value of
zero.
To specify half duplex, use a J~ODE value of 1024.

CLUSTERSIZE Value
To ensure that messages from the remote processor to the local RSTS/E
system are received without need for retransmission, the DMC1l/DMRll
allocates one or more receive buffers to the unit when it is opened.
Whenever a message is received over the link, it is placed in one of
the allocated buffers.
That buffer is then placed on a queue of
received messages, called the receive complete queue. When you issue
a GET statement on the open channel o:E the DMCll/DMRll, the message is
copied from the system buffer to your I/O buffer, and the system
buffer is released.
Because a buffer on the receive complete queue is no longer available
for use by the DMCll/DMRII, the driver tries to replace it with
another buffer from the monitor's extended buffer pool or from the
small buffer pool.
The number of buffers that the ~river attempts to
keep allocated to the DMCll/DMRll receiver side is called the buffer
quota for the unit.
You specify it at open time as the CLUSTERSIZE
value. Any number from 1 to 127 is valid as a buffer quota, but
values above 4 are not recommended except when a very large volume of
traffic on a high speed (higher than S6K baud) line is expected;
allocating too many buffers to the DMCll/DMRll needlessly ties up
system resources.
However, if the bu:Efer quota is too low, overrun
errors occur on the unit.
These do nc)t cause any loss of data, but do
result in reduced performance due to retransmission~.

FILESIZE Value
The value used in the FILESIZE option at open time specifies the size
of the buffers allocated to the DMCll/DMRll receiver.
This value
limits the length of a received message and must be between 1 and 632
inclusive.
If the remote processor sends a message larger than the
receiver buffer size, the message is lost and the DMCll/DMRll halts
operation.
Note that the 632-byte limit on receive buffer size does
not limit the length of transmitted messages.
The DMC/DMR driver
limits transmitted message lengths to a maximum of 8000 bytes.
However, to avoid message truncation, you must be careful to stay
within the remote system's receive buffer size.
For example, if the
6-2

DMCll/DMRll Interprocessor Link
remote system is also RSTS/E, the length of transmitted messages is
limited to 632 bytes maximum or a smaller value that is equal to the
receive buffer size, as established by the FILESIZE value (specified
in the OPEN statement for the remote DMCll/DMRll).

RECORDSIZE Value
The RECORDSIZE value establishes the I/O buffer size for the
DMCll/DMRll.
The default buffer size is 512 bytes. While you can
specify any even buffer size, it is good practice to make the I/O
buffer the same size or larger than the device's receive buffer (see
the section, "The GET Statement and RECORD Options").

Errors
Only two errors specific to the DMCll/DMRll can occur at open time.
The error ?Device hung or write locked (ERR=14) occurs if the driver
cannot initialize the device.
The error ?No buffer space available
(ERR=32) occurs if the driver cannot obtain a 264-byte buffer to use
as the hardware base table.

The GET statement and RECORD Options
The GET statement copies the next message from the DMCll/DMRll queue
of received messages into your program's I/O buffer.
If the received
message is longer than your buffer, the monitor truncateS it with no
warning.
Therefore, it is good practice to specify a RECORDSIZE in
the OPEN statement that is greater than or equal to the FILESIZE value
(see the section, "FILESIZE Value").
The value in the RECORD option of GET statements determines how the
program treats message unavailability.
If no message is available and
the DMCll/DMRll is still running (that is, the physical link is
intact), you can cause your job to get an error indication immediately
or to sleep until a message is received. A RECORD value of 0 (or
omitting the RECORD option) tells the monitor to generate the error
?Can't find file or account (ERR=5) immediately. A RECORD value of
8192% tells the monitor to stall the job until either:
o

message is available from the remote processor, in which
case the message is returned in the user's buffer as usual

.A DMCll/DMRll error occurs,

the

e~ror

in which case the program receives
?Device hung or write locked (ERR=14)

A RECORD value of 16384%+n%, where n% is a number between 0 and 255,
6-3

DMCll/DMRll Interprocessor Link
causes the monitor to put the job to sleep.
the following conditions:

It is awakened by any of

A ~essage is received on the DMCll/DMRll.

An error occurs on the DMCll/DMRll.

A message is received through the local send/receive
mechanism.

A delimiter is typed on one of the job's keyboards.

The number of logins is set to 1.

N seconds have expired and n is not O.

If the job is awakened because a message is received, the monitor
copies the message to its buffer, just as if the GET had succeeded
without sleeping.
If it is awakened because an error occurred, it
receives the error ?Device hung or write locked (ER~=14).
If it is
awakened for any other reason, it receives the error ?Can't find file
or account (ERR=5).
When the DMCll/DMRll driver detects a failure in the physical link, it
shuts down the uni t. An'y messages received before the hardware
failure are returned to the job as it executes GET statements. No
error indication appears until the receive complete queue is empty.
At that point, the job receives the error ?Device hung or write loc~ed
(ERR=14).
The only recourse is to close the channel on whi~h the unit
is open.

Count and status Information
If the 4096% bit is on in the RECORD value in a GET, statement, the
driver does not return a message from the DMCll/DMRll.
Instead, it
returns count and status information to the user. Twenty-six bytes of
information are returned in the following format:
Bytes

Meaning

Number of transmit buffers actually being processed by the
DMCll/DMRll hardware.

Total number of transmi t buffers wai ting to' be sent, including
those given to the hardware (that is, number of uncompleted
PUT statements).

Number of messages on the receive queue waiting to be given to
the job.

6-4

DMCll/DMRll Interprocessor Link

Reserved.

Number of receive buffers actually given to the DMCl1/DMRll
hardware.

Total number of buffers allocated to the DMCll/DMRll receiver,
including those given to the hardware.

7-8

Length of the first message on the receive queue (0 if byte 3
is 0).

If the DMCll/DMRll is not running (see byte 10), this is a
code indicating the type of error:

o
1
2
3
4
5
6
7
8
9
10
11
12
255
10

Hardware error (see control-out information in bytes 19Unknown control-out operation.
Illegal input interrupt.
Illegal output interrupt.
Unsolicited input interrupt.
Unexpected output interrupt.
DDCMP maintenance mode/message received.
Lost data error.
Reserved.
Disconnect code.
DDCMP start received.
UNIBUS address timeout on DMC/DMR access.
Procedure error.
Timeout error.

Status flags, encoded as a combination of bits:
4
64
128

The first transmit since the DMCll/DMRll was opened is
complete, indicating that a link has been established
and that further transmits will be timed out.
The driver is waiting for buffers to satisfy receive
buffer quota.
Unit is running.
If this bit is off, the DMCll/DMRll
was halted for the reason given in byte 9.

All other bits are reserved.
11-12

Receive buffer size (from the FILESIZE value when the
DMCll/DMRll was opened).

13-14

Operational mode (from the MODE value when the DMCll/DMRll was
opened)~

15-16

Reserved.

Receive buffer quota (from the CLUSTERSIZE value when the
DMCll/DMRll was opened).

6-5

DMCll/DMRll Interprocessor Link

Reserved.

19-20

Value of SEL6 hardware register at most recent control-out
interrupt.
If the DMCll/DMRll was halted dUe to a hardware
error, the specific error (or errors) can be found here.
For
the format of this word, see the description of the DMCII and
DMRll in the DMRll Synchronous Controller Users's Guide.

21-22

Data check count.
A data check error occurs when the
DMCll/DMRll has tried seven retransmissions of a message
without success.
This indicates that the physical channel is
defective or that the remote processor does not have a buffer
to receive the message.
The DMCll/DMRll continues to retry
the transmission and reports a data check error every seven
retries.
The total number of data check errors that have
occurred since the DMCll/DMRll unit was opened is returned in
this word.

23-24

Timeout count.
A timeout error occurs when the DMCll/DMRll
has received no response from the remote end of the link for
21 seconds.
This indicates a broken communications channel or
a failure at the other end of the link.
Th~ number of timeout
errors since the OPEN is returned in this word.

25-26

Overrun count (the number of overrun errors since the OPEN).
An overrun error indicates that a message w~s received but no
buffer was available.
This is nonfatal because the remote
system retransmits the message (and possibl~ logs data check
errors).
You can reduce overrun errors by increasing the
buffer quota for the unit (see CLUSTERSIZE in OPEN).
Overrun
errors can also occur when the driver is not able to obtain a
buffer allowed by the buffer quota value.
To reduce this type
of overrun error, increase the size of XBUF at the start of
the next time-sharing session.

Three errors (data check, timeout, and overrun) that are detected by
the DMCll/DMRll are only warnings.
These are nonfatal and do not
cause the unit to halt.
Your program is not informed when they occur.
However, if any of them occurs frequently, it indicates that the
program has set the wrong CLUSTERSIZE value or that: there is trouble
on the physical line between the two processors.
The driver count~
the number of times each error occurs and returns those counts as part
of the status information.
Your program never stalls when it issues a count and status request.
Furthermore, this request is legal wh,ether or not the unit is running.
Thus, you can use it to d~termine the specific DMCll/DMRll problem
after the program receives an ERR 14.

6-6

DMCll/DMRll Interprocessor Link
The PUT Statement
The PUT statement copies data from your program's I/O buffer to a
system buffer and queues the buffer for transmission.
The number of
bytes to transmit is specified in the COUNT option and can be from 1
to 8000. A COUNT value outside that range generates the error
?Illegal byte count for I/O (ERR=3l).
If the monitor cannot obtain a
buffer big enough to hold the message, it returns the error ?No buffer
space available (ERR=32).
The program can sleep for a while and retry
the PUT, waiting for adequate buffer space to become available. Note
that on a given configuration it may be impossible to obtain a buffer
of the proper size.
It is good practice to limit the retry operations
to a small number after receiving ERR=32.
If the physical link has gone down, the driver immediately returns the
error ?Device hung or write locked (ERR=14). As with the GET
statement, the only recourse is to close the channel.
The PUT statement queues messages to the DMCll/DMRll to be sent as
soon as possible.
Your program is not normally notified when the
actual message transmission is done, nor whether it is ever done (in
case of a physical link failure).
You can modify this action by using
the RECORD option of the PUT statement. A RECORD value of a (or
omitting the RECORD option) tells the monitor to queue the data for
transmission, and the program immediately continues processing.
RECORD 8192% tells the monitor to stall the job until all pending
transmissions have completed successfully (in which case the program
continues processing normally) or until a DMCll/DMRll error occurs (in
which case the program receives error 14). RECORD l6384%+n%, where n%
is a number between a and 255, causes the monitor to put the job to
sleep.
It is awakened by any of the following conditions:
o

All pending transmissions have completed successfully.

An error occurs on the DMCll/DMRll.

A message is received through the local send/receive
mechanism.

A delimiter is typed on one of the job's keyboards.

The number of logins is set to 1.

N seconds have expired and n is not O.

If the j~~b is awakened for the second reason, it receives the error
?Device hung or write locked (ERR=14).
If it is awakened for any
other reason, it receives no error and continues processing normally.
To find the number of transmissions still outstanding, use a GET with
RECORD 4096% and examine the value in byte 2.

6-7

DMCll/DMRll Interprocessor Link
Adding the value 4096% to any of the clbove RECORD values tells the
monitor not to transmit any data, but to do the WAIT operation
specified.

The CLOSE Statement
If a DMCll/DMRll unit is open by a user on more tha~ one channel, no
CLOSE except the last has any effect. When the last CLOSE is issued,
the unit is halted, any received messages not given to the user are
discarded, any messages queued for transmission butinot transmitted
are discarded, and all buffers are returned to the monitor.
It is
normally good practice to issue a PUT statement with RECORD
4096%+8192% to wait for all transmissjLons to complete before executing
a CLOSE statement.
The CLOSE call cannot fail.
When the CLOSE
statement is executed on a DMC/DMR with an autoansw$r/autodial phone
connection, the DTR (Data Terminal Ready) modem control signal is
automatically dropped to disable data transmission.

Hardware Errors
Any fatal error detected by the DMCll/DMRll (that is, any error not
listed as nonfatal in the count and status description) causes the
monitor to shut down the link.
The monitor reports the error ?Device
hung or write locked (ERR =14) to your job on all subsequent PUT
operations and on any GET operations after all queued messages have
been received.
(GET operations with RECORD 4096% are always legal,
whether or not the unit is running.)

6-8

PART II
System Function Calls

Chapter 7
SYS System Function Calls

This chapter describes the system function calls, also known as SYS
calls.
System function calls let you perform many special functions,
such as:
o

Establish special characteristics for a job

Perform special I/O functions

Set terminal characteristics

Modify account characteristics

Manipulate account privilege information

The SYS call whose function code is 6 is a specialized case of the
general system function call.
SYS call 6 contains a subfunction code
called the FIP code.
The FIP code causes a dispatch call to be made
to special resident or nonresident code that performs file processing.
The subfunctions of SYS call 6 are called FIP calls. Because
programmers generally use FIP calls more frequently than the SYS
calls, the FIP calls are also commonly referred to as SYS calls. This
chapter also uses SYS call as the preferred term.
The calls described in this Chapter are organized as follows:

SYS system function calls (F=O to F=14). The calls are
arranged in ascending numerical order.
Tables 7-1 and 7-2
summarize these calls.

SYS system function calls to FIP (FO=-29 to FO=34). With two
exceptions, the calls are arranged in ascending numerical
order. Tables 7-3 and 7-4 summarize these calls.

The PEEK function.
This function lets a user who has RDMEM
privilege examine any word location in the monitor part of
memory.

7-1

SYS System Function Calls
SYS System Function Calls
I

SYS system function calls let you perform special 110 functions,
establish special characteristics for a job, set te~minal
characteristics, and cause the moni tor to execute sI!>ecial ope.rations.
I

The SYS call format is used for two reasons.
First, th~ calls are
unique to the RSTS/E implementation of the BASIC-PL~S language. As
such, the calls are system-dependent clnd have calli~g formats
different from any BASIC-PLUS language call.
Second, the SYS format
allows the use of a variable number of parameters.
Some SYS calls provide one set of func:tions to a nooprivileged user,
while providing the privileged user wi.th a more powJrful set.
To find
out what privileges are associated with each call, $ee Tables 7-1
through 7-4, as well as the individual description 6f each SYS call.
If you are not sure what privileges your account has, use the SHOW
JOB/PRIVILEGES command to list them.
If you have more privileges than
you need to use a certain call and want to temporar~ly disable them,
use the SET JOB/PRIVILEGES command.
1~he DCL commanqs associated with
privileges are described in the RSTS/E System User'~ Guide.
i

The first part of Chapter 7 describes all system fuqction calls with
function codes other than 6.
The second part of Ch~pter 7 describes
system function calls to the file proc:essor (FIP ca~ls).
These calls
are associated with system function call 6.

SYS System Function Formats and Codes
The general format of the SYS call is:
V$ = SYS(CHR$(F%) + 0$)
where:
V$

is the data (target) string returned by the call.

is the SYS system function code.

is the optional (by function code) parameter string passed by
the call.

F% in the general format denotes function codes tha~ range from 0
through 14, inclusive.
SYS calls that specify a coqe outside of this
range or that pass a zero length string generate th~ error ?Illegal
SYS() usage (ERR=18).
Table 7-1, organized by code [number, summarizes
the codes and their functions.
Table 7-2, organizeq alphabetically by
function name, provides the same information.

7-2

SYS System Function Calls
The SYS call whose function code is 6 is a more specialized case of
the general system function call.
It is specialized by a subfunction
code called the file processor (FIP) code.
The FIP code causes a
dispatch call to be made to special resident or nonresident code that
performs file processing.
The format of the call is:
V$ = SYS(CHR$(6%) + CHR$(FO%) + 0$)
where:
V$

is the data (target) string returned by the call.

FO%

is the FIP subfunction code.

is the optional (by function code) parameter string passed by
the call.

The section "SYS System Function Calls to FIP" describes the purpose,
calling format, and use of each FIP system function call (F=6).
It
also describes how to build the parameter string to pass to the
monitor and how to extract data from the returned string.
Table 7-3 in this section is a quick reference index of the FIP
functions in order of FIP code (FO).
Table 7-4 provides the same
information, but is arranged alphabetically by function name.
For
detailed information on each of the functions, refer to the page shown
beside the name in the table.
In Tables 7-1 through 7-4, the Relevant Privileges column lists the
associated with each SYS call. A user who attempts to call
a SYS function without sufficient privilege receives the error
?Illegal SYS() usage (ERR=18) or the error ?Protection violation
(ERR=lO).
To avoid repetition, this chapter describes error 18 for
calls only if it has a meaning different from nonprivileged attempts
to use the call.
privilegl~s

7-3

SYS System Function Calls
Table 7-1:

SYS System Function Calls (by Function ~ode)

+ _ _ _ _ _ _ _ _ _ _+ _ _ _ _ _ _ _ _ _ _ _ _ _ _ • _ _ • _ _ • • _ _ • _ _ _ _ . _ • • • _ _ _ _ • • _+ _ _ _,_ _ • _ _ _ _ _ _ _ _ _ _+ _ _ _ _ _ _

I Function I
I Code(F) I

-Relevant
Function Name
Privileges
Page
+- - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - _. - - - - - - - - - - -+- - - - - - - - - - - - - - - -+- - - - - - --

I
I 7-18
I
I 7-19
I
I 7-20
I
I 7-21
I
I 7-22
I
I 7-24

Cancel CTRL/O effect on terminal

None

Enter tape mode on terminal

Nope

Enable echoing on terminal

None

Disable echoing on terminal

None

Enable ODT submode on terminal

None

Exit with no prompt message

None

SYS call to the file processor

See individual
FIP call

7-25

Get core common string

None

7-26

Put core common string

None

7-27

Exit and clear program

None

7-28

Reserved for special implementations

Cancel all type ahead

Nope

7-30

Return information on last opened file

Nope

7-31

Reserved for special implementations

Execute eCL command

access
7-34
toi file
+ •.. - - - • - - - +. - • - I- - - - - - - - - • - • - - - - - - - - - - - - - .. - - - - - - - - - - - + - - - - - - - - - - - - '. - - • + - - - - - - - Ex~cute

7-4

Chapter 7
SYS System Function Calls

This chapter describes the system function calls, also known as SYS
calls.
System function calls let you perform many special functions,
such as:
o

Establish special characteristics for a job

Perform special I/O functions

Set terminal characteristics

Modify account characteristics

Manipulate account privilege information

The SYS call whose function code is 6 is a specialized case of the
general system function call.
SYS call 6 contains a subfunction code
called the FIP code.
The FIP code causes a dispatch call to be made
to special resident or nonresident code that performs file processing.
The subfunctions of SYS call 6 are called FIP calls.
Because
programmers generally use FIP calls more frequently than the SYS
calls, the FIP calls are also commonly referred to as SYS calls.
This
chapter also uses SYS call as the preferred term.
The calls described in this Chapter are organized as follows:
o

SYS system function calls (F=O to F=14).
The calls are
arranged in ascending numerical order.
Tables 7-1 and 7-2
summarize these calls.

SYS system function calls to FIP (FO=-29 to FO=34). With two
exceptions, the calls are arranged in ascending numerical
order.
Tables 7-3 and 7-4 summarize these calls.

The PEEK function.
This function lets a user who has RDMEM
privilege examine any word location in the monitor part of
memory_

7-1

SYS System Function Calls
SYS System Function Calls
SYS system function calls let you perform special I/O functions,
establish special characteristics for a job, set terminal
characteristics, and cause the monitor to execute special ope,rations.
The SYS call format is used for two reasons.
First, the calls are
unique to the RSTS/E implementation of the BASIC-PLUS language. As
such, the calls are system-dependent and have calling formats
different from any BASIC-PLUS language call.
Second, the SYS format
allows the use of a variable number of parameters.
Some SYS calls provide one set of functions to a nonprivileged user,
while providing the privileged user with a more powerful set.
To find
out what privileges are associated with each call, see Tables 7-1
through 7-4, as well as the individual description of each SYS call.
If you are not sure what privileges your account has, use the SHOW
JOB/PRIVILEGES command to list them.
If you have more privileges than
you need to use a certain call and want to temporarily disable them,
use the SET JOB/PRIVILEGES command.
The DCL commands associated with
privileges are described in the RSTS/E System User's Guide.
The first part of Chapter 7 describes all system function calls with
function codes other than 6.
The second part of Chapter 7 describes
system function calls to the file processor (FIP calls).
These calls
are associated with system function call 6.

SYS System Function Formats and Codes
The general format of the SYS call is:
V$ = SYS(CHR$(F%) + 0$)
where:
V$

is the data (target) string returned by the call.

is the SYS system function code.

is the optional (by function code) parameter string passed by
the call.

F% in the general format denotes function codes that range from 0
through 14, inclusive.
SYS calls that specify a code outside of this
range or that pass a zero length string generate the error ?Illegal
SYS() usage (ERR=18).
Table 7-1, organized by code number, summarizes
the codes and their functions.
Table 7-2, organized alphabetically by
function name, provides the same information.

7-2

is the data (target) string returned by the call.

FO%

is the FIP subfunction code.

is the optional (by function code) parameter string passed by
the call.

The section "SYS System Function Calls to FIP" describes the purpose,
calling format, and use of each FIP system function call (F=6).
It
also describes how to build the parameter string to pass to the
monitor and how to extract data from the returned string.
Table 7-3 in this section is a quick reference index of the FIP
functions in order of FIP code (FO).
Table 7-4 provides the same
information, but is arranged alphabetically by function name.
For
detailed information on each of the functions, refer to the page shown
beside the name in the table.
In Tables 7-1 through 7-4, the Relevant Privileges column lists the
privileges associated with each SYS call. A user who attempts to call
a SYS function without sufficient privilege receives the error
?Illegal SYS() usage (ERR=18) or the error ?Protection violation
(ERR=10).
To avoid repetition, this chapter describes error 18 for
calls only if it has a meaning different from nonprivileged attempts
to use the call.

7-3

SYS System Function Calls
Table 7-1:

SYS System Function Calls (by Function Code)

+- - - - - - - - - -+- ------------_. --_.. -_. _... --------------+- ---------------+- ------_.
I Function I
I
Relevant
I
I Code(F) I
Function Name
I
Privileges
I Page
+- - - - - - - - - -+- ---------- ------------------------------+- ---------------+- ------_.

Cancel CTRL/O effect on terminal

None

I
I 7-18

Enter tape mode on terminal

None

7-19

Enable echoing on terminal

None

7-20

Disable echoing on terminal

None

7-21

Enable ODT submode on terminal

None

7-22

Exit with no prompt message

None

7-24

SYS call to the file processor

See individual
FIP call

7-25

Get core common string

None

7-26

Put core common string

None

7-27

Exit and clear program

None

7-28

Reserved for special implementations

Cancel all type ahead

None

7-30

Return information on last opened file

None

7-31

Reserved for special implementations

Execute CCL command

Execute access
to file

7-34

+----------+-----------------------------------------+----------------+--------.

7-4

SYS System Function Calls
Table 7-2:

SYS System Function Calls (by Function Name)

+ .. - - - - - - - - - - - - -" - ~ - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - -+- - - - - - - - - - - - - - - -+- - - - - - --+
I
I
Function I
Relevant
I
I
Function Name
I
Code(F) I
Privileges
I
Page
I
I
+ .. - - - - - - - - - - - - -" - ~ - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - -+- - - - - - - - - - - - - - - -+- - - - - - --+

Cancel all type ahead

Cancel CTRL/O effect on terminal

Disable echoing on terminal

Enable echoing on terminal

Enable ODT submode on terminal

Enter tape mode on terminal

Execute CCL command

Exit and clear program

Exit with no prompt message

Get core common string

Put core common string

Reserved for special implementations

Return information on last opened file

I
I 7-30
I
None
I 7-18
I
None
I 7-21
I
None
I 7-20
I
None
I 7-22
I
None
I 7-19
I
Execute access I 7-34
to file
I
I
None
I 7-28
I
None
I 7-24
I
None
I 7-26
I
None
I 7-27
I
I
I
I
I
None
I 7-31
None

SYS call to the file processor
+,. - - - - - - - - - - - - - - -

See individual I 7-25
FIP call
I
-+- - - - - - - - - -+- - - - - - - - - - - - - - - -+- - - - - - --+
6

7-5

SYS System Function Calls
Table 7-3:

FIP SYS Calls (by Subfunction Code)

+- - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - -+- - - - - - --+
I Function I
I
Relevant
I
I
Function Name
I
Privileges
I Page I
I Code(FO) I
+- - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - -+- - - - - - --+
-29
-28

- 27
-26

I
I Get monitor tables - part III
I
I Spooling (Obsolete, use PBS request)
I
I

I
I None
I
I Read access to
I file
I Wri te access

I to file
I

I
I Snap shot dump
I
i File utility functions

I SYSIO
I

I
I 7-58
I
I 7-61
I
I
7 - 66

Read access to
file
write access
to file
DATES
TUNE
SYSIO

7-67

-25

Read/write file attributes

Read access to
file
Write access
to file

7-75

-25

Read pack attributes

DEVICE

7-79

-25

Read/write account attributes

GACNT
WACNT

7-81

-25

Delete account attributes

GACNT
WACNT

7-87

-24

Add/delete CCL command

INSTAL

7-89

-23

Terminating file name string scan

None

7-45

-22

Set special run priority

TUNE

7-92

-21

Drop/regain (temporary) privileges

None

7-93

-20

Lock/unlock job in memory

TUNE

7-96

-19

Set number of logins

SWCTL

7-98

-18

Add run-time system

INSTAL

7-100

-18

Remove run-time system

INSTAL

7-104

7-6

SYS System 'Function Calls
Table 7·3:

FIP SYS Calls (by Subfunction Code) (Cont.)

+-.------ .. + ..... -.-.--- ... ---.- ..
I
I

Function
Code(FO)

--~-

.. ----.-.--.-.-+ ....•... -------.+ . . . . . . . . ~

Function Name

+_ •• _ •••••• + .....

•••

___

•

_______

•

••

•••••

Relevant
Privileges

I
I

Page

+. _ ..... ___ ..... _+ ......

·18

Unload run-time system

INSTAL

7·106

·18

Add resident library

INSTAL

7·108

·18

Remove resident library

INSTAL

7·112

·18

Unload resident library

INSTAL

7-113

·18

create dynamic region

INSTAL

7·114

·17

Name run-time system

write access
to file

7·117

·16

Shut down system

SHUTUP

7-119

·15

Accountin'g dump

GACNT
WACNT

7-120

·14

Change system date/time

DATES

7-122

·13

Change priority/run burst/job size

TUNE

7·124

-12

Get monitor tables - part II

None

7·127

·11

Change file backup statistics

DATES

7·129

·10

File name string scan

None

7-45

-9

Hang up a dataset

HWCTL

7·132

·8

Get open channel statistics

None

7·134

-7

Enable CTRL/C trap

None

7-137

·6

Poke memory

SYSMOD

7-140

·5

Broadcast to terminal

SEND

7·141

·4

Force input to terminal

SYSIO

7-143

-3

Get monitor tables - part I

None

7·144

-2

Disable llogins

SWCTL

7-147

-1

Enable 10lgins

SWCTL

7·148

7-7

I
_.~

SYS System Function Calls
Table 7-3:

FIP SYS Calls (by Subfunction Code) (Cont.)

+- - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - -+- - - - - - --+
I Function I
I
Relevant
I
I
I Code(FO) I
Function Name
I
Privileges
I Page I
+ - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -.- - - - - - + - - - - - - - - - - - - - - - - + - - - - - - - - +
0

Create user account (new format)

GACNT
WACNT

7-149

Create user account (old format)

GACNT
WACNT

7-154

Delete user account

GACNT
WACNT

7-158

Reserved

Disk pack status

MOUNT
HWCFG

7-160

None

7-165

verify password

DEVICE
GACNT
WACNT

7-165

Logout

EXQTA
WACNT

7-169

Attach

GACNT
WACNT

7-173

Reattach

DEVICE

7-175

Swap Console

None

7-177

Detach

JOBCTL

7-179

Change quota (old format)/expiration
date/password (old format)

GACNT
WACNT

7-182

Change quota (new format)/expiration
date/password (old format)

GACNT
WACNT

7-186

Set password (new format)

GACNT
WACNT

7 -.1 88

Kill job

JOBCTL

7-190

Disable terminal

HWCTL

7-192

7-8

SYS System Function Calls
Table 7-3:

FIP SYS Calls (by Subfunction Code) (Cont.)

+- - - - - - _ .. - -+- - - - - - - - - - ,. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - -+- - - - - - --+
Function
Relevant
Code(FO)
Function Name
Privileges
Page
+ - - - - - - - .. - - + - - - - - - - - - - ,. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + - - - - - - - - - - - - - - - - + - - - - - - - - +
I

I
I

I
I
I
I
I
I

I
I Return error messages

None

7-194

DEVICE
HWCTL

7-196

None

7-200

None

7-202

None

7-204

DEVICE
Create/rename
access to
account

7-205

10
10
11
12

I Allocate/reallocate device
I
I
I Assign user logical
I
I Deallocate a device or deassign user
I logical
I
I Deallocate all devices
I
I Zero a device
I
I

Read/read and reset accounting data

GACNT
WACNT

7-209

Directory lookup on index

DEVICE
Read or
execute access
to file

7-219

Special magnetic tape directory lookup

DEVICE

7-221

Set terminal characteristics - part I

HWCFG

7-229

Set terminal characteristics - part II

HWCFG

7-241

Disk directory lookup on file name

DEVICE
Read or
execute access
to file

7-224

Disk wildcard directory lookup

DEVICE
Read or
execute access
to file

7-226

Obsolete (use function code 22)

Enable/disable disk caching

TUNE

7-248

7-9

I
I

SYS System Function Calls
Table 7-3:

FIP SYS Calls (by Subfunction Code) (Cont.)

+- - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - -+- - - - - - --+
I Function I
Relevant
I
I
I Code(FO) I
Function Name
Privileges
I Page I
+- - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - -+- - - - - - --+
20

Convert date and time

None

7-252

Add new logical names

INSTAL

7-256

Remove logical names

INSTAL

7-259

Change disk logical name

INSTAL

7-261

List logical names

None

7-263

Message send/receive

JOBCTL
SEND
SWCFG
SWCTL
SYSIO

Ch. 8

Send local data message with privileges

SEND

Ch. 8

Send Print/Batch Services request

None

Ch. 9

Add system files

write access
to file
INSTAL

7-267

Remove system files

write access
to file
INSTAL

7-270

List system files

None

7-272

Create a job

Execute access
to file

7-274

EXQ~TA

JOBCTL
TUNE
WACNT
25

Wildcard PPN lookup

DEVICE

7-282

Return job status

JOBCTL
TUNE

7-284

Reserved

Set/clear current privileges

None

7-289

7-10

SYS System Function Calls
Table 7-3:

FIP SYS Calls (by Subfunction Code)

(Cont.)

+- - - - - - - - - -+- - - - - - - - - - ~ - - - - - - - - - - - - - - - - _. - _. _. _. - _. - -+- - - _.••.• _ •. - - - -+- - - - - - --+
Function
Relevant
Code(FO)
Function Name
Privileges
Page
+ - - - - - - - . - - + - - - - - - - - - - ,. - - - - - - - - - - . - - - - - - .. - - . - - - - - - - - - + - - - - - - - - - - - - - - - - + - - - - - - - - +
I

I
I
I
I

Read current privileges

None

7-289

Stall/Unstall system

HWCTL

7-291

Reserved

I
I

Third party privilege check

None

7-293

I
I
I

Check file access rights

None

7-295

Convert privilege name to mask

None

7-297

I
I

Convert privilege mask to name

None

7-299

Open next disk file

DEVICE
Read access to
file
Write access
to file
DATES

7-301

Set device characteristics

HWCFG
HWCTL

7-304

Set line printer characteristics

HWCFG

7-307

Set system defaults

HWCFG
SWCFG

7-310

Load monitor overlay code and return
status/remove monitor overlay code

SWCFG

7-313

I
I
I
I
I

I
I

7-317
RDMEM
SYSMOD
+ - - - - - - - .. - - + - - - - - - - - - - . - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + - - - - - - - - - - - -'- - - - + - - - - - - - - +

PEEK fun'ction

7-11

SYS System Function Calls
Table 7-4:

FIP SYS Calls (by Function Name)

+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - -+- - - - - - - - - - - - - - - -+- - - - - - --+
I
I Function I
Relevant
I
I
I
Function Name
I Code(FO) I
Privileges
I Page I
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - -+- - - - - - - - - - - - - - - -+- - - - - - --+

Accounting dump

-15

GACNT
WACNT

7-120

Add/delete CCL command

-24

INSTAL

7-89

Add new logical names

INSTAL

7-256

Add system files

Write access
to file
INSTAL

7-267

Add resident library

-18

INSTAL

7-108

Add run-time system

-18

INSTAL

7-100

Allocate/reallocate device

DEVICE
HWCTL

7-196

Assign user logical

None

7-200

Attach

GACNT
WACNT

7-173

-5

SEND

7-141

Change disk logical name

INSTAL

7-261

Change file backup statistics

-11

DATES

7-129

Change quota/expiration date/password

GACNT
WACNT

7-182

Change priority/run burst/job size

-13

TUNE

7-124

Change system date/time

-14

DATES

7-122

Check file access rights

None

7-295

Convert date and time

None

7-252

Convert privilege mask to name

None

7-299

Convert privilege name to mask

None

7-297

Broadcast to

t~rminal

7-12

SYS System Function Calls
Table 7-4:

FIP SYS Calls (by Function Name) (Cont.)

+- - - - - - - - - - - - - - - ~ - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - -+- - - - - - - - - - - - - - - -+- - - - - - --,
I
I Function I
Relevant
Code(FO) +I ________________
privileges
page
+I _______________Function Name
+I __________
+ ________
m

_________________________

I
I Create a job
I
I
I
I

Execute access
to file
EXQTA
JOBCTL
TUNE
WACNT

7-274

Create dynamic region

-18

INSTAL

7-114

Create user account (new format)

GACNT
WACNT

7-149

Create user account (old format)

GACNT
WACNT

7-154

Deallocate all devices

None

7-204

Deallocate a device or deassign user
logical

None

7-202

Delete account attributes

-25

GACNT
WACNT

7-87

Delete user account

GACNT
WACNT

7-158

Detach

JOBCTL

7-179

Directory lookup on index

DEVICE
Read or
execute access
to file

7-219

Disable logins

-2

SWCTL

7-147

Disable terminal

HWCTL

7-192

Disk directory lookup on file name

DEVICE
Read or
execute access
to file

7-224

MOUNT
HWCFG

7-160

Disk pack status

7-13

SYS System Function Calls
Table 7-4:

FIP SYS Calls (by Function Name) (Cont.)

+ _________________________________________ + __________ + ________________ + _____

I Function I
Relevant
Function Name
Code(FO) +I ________________
P~ivileges
Page
+ _________________________________________
+I __________
+ _____
u

Disk wildcard directory lookup

DEVICE
Read or
execute access
to file

7-226

Drop/regain (temporary) privileges

-21

None

7-93

Enable CTRL/C trap

-7

None

7-137

Enable logins

-1

SWCTL

7-148

Enable/disable disk caching

TUNE

7-248

File name string scan

-10

None

7-45

File utility functions

-26

Read access to
file
write access
to file
DATES
TUNE
SYSIO

7-67

Force input to terminal

-4

SYSIO

7-143

-3

None

7-144

Get monitor tables - part II

-12

None

7-127

- part III

-29

None

7-58

Get open channel statistics

-8

None

7-134

Hang up a dataset

-9

HWCTL

7-132

Kill job

JOBCTL

7-190

List logical names

None

7-263

List system files

None

7-272

Load monitor overlay code and return
status

SWCFG

7-313

Lock/unlock job in memory

-20

TUNE

7-96

Get monitor tables

- part I

7-14

+
+

SYS System Function Calls
Table 7-4:

FIP SYS Calls (by Function Name)

+ .. _____________

_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _•

________

(Cont.)

+ __________ + ________________ + ________ +

Function
Relevant
Function Name
Code(FO)
Privileges
Page
+ .. - - - - - - - - - - - - - - _ .. - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - -+- - - - - - - - - - - - - - - -+- - - - - - --+
I

None

7-165

Logout

EXQTA
WACNT

7-169

Message send/receive

JOBCTL
SEND
SWCFG
SWCTL
SYSIO

Ch. 8

Name run-time system

-17

write access
to file

7-117

Open next disk file

DEVICE
Read access to
file
write access
to file
DATES

7-301

RDMEM
SYSMOD

7-317

PEEK function
Poke memory

-6

SYSMOD

7-140

Read current privileges

None

7-289

Read pack attributes

-25

DEVICE

7-79

Read/read and reset accounting data

GACNT
WACNT

7-209

Read/write account attributes

-25

GACNT
WACNT

7-81

Read/write file attributes

-25

Read access to
file
write access
to file

7-75

Reattach

DEVICE

7-175

INSTAL

7-259

Remove logical names

7-15

SYS System Function Calls
Table 7-4:

FIP SYS Calls (by Function Name) (Cont.)

+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - -+- - - - - - - - - - - - - - - -+- - - - - - --+
Function
Relevant
Function Name
Code(FO)
Privileges
Page
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - -+- - - - - - - - - - - - - - - -+- - - - - - --+
I

Remove monitor overlay code

SWCFG

7-313

Remove resident library

-18

INSTAL

7-112

Remove run-time system

-18

INSTAL

7-104

Remove system files

Write access
to file
INSTAL

7-270

None

7-194

Return error messages

Return job status

JOBCTL
TUNE

7-284

Send local data message with privileges

SEND

Ch. 8

Send Print/Batch Services request

None

Ch. 9

Set/clear current privileges

None

7-289

Set device characteristics

HWCFG
HWCTL

7-304

Set line printer characteristics

HWCFG

7-307

Set system defaults

HWCFG
SWCFG

7-310

Set number of logins

-19

SWCTL

7-98

Set password

GACNT
WACNT

7-188

Set special run priority

-22

TUNE

7-92

Set terminal characteristics - part I

HWCFG

7-229

Set terminal characteristics - part II

HWCFG

7-241

Shut down system

-16

SHUTUP

7-119

Snap shot dump

-27

SYSIO

7-66

Special magnetic tape directory lookup

DEVICE

7-221

7-16

SYS System Function Calls
Table 7-4:

FIP SYS Calls (by Function Name)

(Cont.)

+- - - _ •. - - - - - - - - - - - - - - - - - - _. - - - - _. - - .. - - - - -+- - - - - - - _. -+- - - - - - - - - - - - - - - -+- _. - - - --+
I
I Function I
Relevant
I
Function Name
I Code(FO) I
Privileges
Page
+- _. - - _. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - -+- - - - - - - - - - - - - - - -+- - - - - - --+

Spooling (obsolete: use PBS request)

-28

Read access to
file
Write access
to file

7-61

Stall/Unstall system

HWCTL

7-291

Swap Console

None

7-177

Terminating file name string scan

-23

None

7-45

Third party privilege check

None

7-293

Unload resident library

-18

INSTAL

7-113

Unload run-time system

-18

INSTAL

7-106

Verify password

DEVICE
GACNT
WACNT

7-165

Wildcard PPN lookup

DEVICE

7-282

Zero a device

DEVICE
7-205
Create/rename
access to
account
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - -+- - - - - - - - - - - - - - - -+- - - - - - --+

7-17

Cancel CTRL/O Effect on Terminal

F=O
Cancel CTRL/O Effect on Terminal
Data Passed
Meaning

Bytes
1

CHR$(O%), the cancel CTRL/O code.

CHR$(N%), where N% is the number (between 0 and 12) of the
channel on which the system executes the call.
If you do
not specify this byte, the call uses channel O.

CHR$(K%), where K% is the number (between 0 and 127) of the
keyboard assigned but not open by the job. This follows the
multiterminal service rule.
The keyboard is the slave
terminal under control of a master terminal open on the
channel you specify in byte 2.
If you do not specify this byte, the keyboard affected is
the one open on the channel you specify in byte 2.

Data Returned
The target string is equivalent to the passed string.
Privileges Required
None.
Discussion
This call cancels the effect of a CTRL/O typed at the specified
terminal.
The call selects the terminal open on the channel number
you pass in byte 2.
(The terminal must be open on that channel.) If
you use a slave terminal, byte 2 must be a nonzero channel number on
which the master terminal is open; byte 3 must contain the keyboard
number of the slave terminal.
See the RSTS/E System User's Guide for
a description of CTRL/O.

7-18

Enter Tape Mode on Terminal
F=l
Enter Tape Mode on Terminal
Data Passed
Bytes

Meaning

CHR$(l%), the enter tape mode code.

CHR$(N%), where N% is_the number (between 0 and 12) of the
channel on which the system executes the call.
If you do
not specify this byte, the call uses channel Os

CHR$(K%), where K% is the number (between 0 and 127) of the
keyboard assigned but not open by the job.
This follows the
multiterminal service rule.
The keyboard is the slave
terminal under control of a master terminal open on the
channel you specify in byte 2.
If you do not specify this byte, the keyboard affected is
the one open on the channel you specify in byte 2.

Data Returned
The target string is equivalent to the passed string.
Privileges Required
None.
Discussion
This call is specifically for use with ASR33 terminals that have a
low-speed paper tape reader.
The call disables echoing on the
terminal' and places the terminal in tape mode so that a program can be
read into the system from the low-speed reader.
The action of this call is the same as that of the TAPE command (see
the BASIC-PLUS Language Manual).
The call selects the terminal open
on the channel number you pass in byte 2.
(The terminal must be open
on that channel.) If you use a slave terminal, byte 2 must be a
nonzero channel number on which the master terminal is open; byte 3
must contain the keyboard number of the slave terminal.
Note that CTRL/C cancels tape mode.

7-19

Enable Echoing on Terminal
F=2

Enable Echoing on Terminal
Data Passed
Meaning

Bytes
1

CHR$(2%), the enable echoing code.

CHR$(N%), where N% is the number (between 0 and 12) of the
channel on which the system executes the call.
If you do
not specify this byte, the call uses channel O.

Data Returned
The target string is equivalent to the passed string.
Privileges Required
None.
Discussion
This code cancels the effect of SYS calls with codes 1 and 3. The
call selects the terminal open on the channel number you pass in byte
2.
(The terminal must be open on that channel.) If you use a slave
terminal, byte 2 must be a nonzero channel number on which the master
terminal is open; byte 3 must contain the keyboard number of the slave
terminal.

7-20

Disable Echoing on Terminal
F=3
Disable Echoing on Terminal
Data Passed
Bytes

Meaning

CHR$(3%), the disable echoing code.

CHR$(N%), where N% is the number (between 0 and 12) of the
channel on which the system executes the call.
If you do
not specify this byte, the call uses channel O.

CHR$(K%), where K% is the number (between 0 and 127) of the
keyboard assigned but not open by the job.
This follows the
multiterminal service rule.
The keyboard is the slave
terminal under control of a master terminal open on the
channel you specify in byte 2.
If you do not specify this byte, the keyboard affected is
the one open on the channel you specify in byte 2.

Data Returned
The target string is equivalent to the passed string.
Privileges Required
None.
Discussion
This call prevents the system from echoing information typed at the
terminal. As a result, information such as a password is kept secret
but accepted as valid input by the system.
The call selects the
terminal open on the! channel number you pass in byte 2.
(The terminal
must be open on that channel.) If you use a slave terminal, byte 2
must be a nonzero channel number on which the master terminal is open;
byte 3 must contain the keyboard number of the slave terminal.
Note that CTRL/C reenables terminal echo.

7-21

Enable ODT Submode on Terminal
F=4
Enable ODT Submode on Terminal
Data Passed
Meaning

Bytes
1

CHR$(4%), the enable ODT submode code.

CHR$(N%), where N% is the number (between 0 and 12) of the
channel on which the system executes the call.
If you do
not specify this byte, the call uses channel O.

CHR$(K%), where K% is the number (between 0 and 127) of the
keyboard assigned but not open by the job.
This follows the
multi terminal service rule.
The keyboard is the slave
terminal under control of a master terminal open on the
channel you specify in byte 2.
If you do not specify this byte, the keyboard affected is
the one open on the channel you specify in byte 2.

Data Returned
The target string is equivalent to the passed string.
Privileges Required
None.
Discussion
ODT submode allows the system to accept less than a full line as input
from the terminal.
Normally, the system waits to accept terminal
input until it receives a line terminated by a delimiting character:
carriage return, line feed, form feed, escape character, or CTRL/D
~ombination.
However, in ODT submode the system does not wait for a
delimiting character.
Instead, one or more characters typed at the
terminal are passed immediately to the program by the next keyboard
input request statement.
This input mode is called ODT submode
because it is used in the system program ODT.BAS and the debugging
routine ODT.OBJ.
You must enable this function before every input request statement
that immediately passes characters to the program.
You must use a GET
statement as the input request statement.
(You must not use INPUT or
INPUT LINE statements, because they cause repeated generation of the
input request until a line terminator is detected.)
7-22

Enable ODT Submode on Terminal
F=4
If a program performs other lengthy operations before it executes
either another SYS call and GET statement or other input/output
operation at the terminal, it allows time for the user to type more
than one character.
To provide for such a possibility, the program
should e~xamine the system variable RECOUNT after executing each GET
statement.
This procedure determines how many characters the user
typed be~tween keyboard input operations and enables the program to
process all the characters without losing any.
The call selects the terminal open on the channel number you pass in
byte 2.
(The terminal must be open on that channel.) If you use a
slave te~rminal, byte 2 must be a nonzero channel number on which the
master terminal is open; byte 3 must contain the keyboard number of
the slave terminal.

7-23

Exit with No Prompt Message
F=5

Exit with No Prompt Message
Data Passed
Meaning

Byte

CHR$(S%), the exit with no prompt code.

Data Returned
None.
Privileges Required
None.
Discussion
This type of exit does not clear the program from memory, and thus
allows you to continue running the program. The specific effects are:
o

Keeps the files open.

Saves the current program state, which allows you to
execution.

Drops temporary privilege.

Does not generate a prompting message.

Has the BASIC-PLUS keyboard monitor wait for a command.

7-24

continue~

FIP Function Call
F=6

FIP Function Call
The SYS call whose function code is 6 is a specialized case of the
general system function call. SYS call 6 contains a subfunction code
called the FIP code~
The FIP code causes a dispatch call to be made
to special resident or nonresident code that performs file processing.
The entire class of subfunctions of SYS call 6 are called FIP calls.
See the section "SYS System Function Calls to FIP" for a description
of SYS calls to the file processor.

7-25

Get Core Common String
F=7

Get Core Common String
Data Passed
Byte
1

Meaning
CHR${7%), the get a string from core common code.

Data Returned
The target string is the contents of the job core common area.

Privileges Required
None.

Discussion
This call allows a program to extract a single string from a data area
loaded by another program previously run by the same job. The data
area is called core common and is from 0 to 127 bytes long.
This call
does not alter the contents of the core common area.
See SYS call 8,
Put Core Common String.

7-26

Put Core Common String
F=8
Put Core Common String
Data Passed
Bytes
1

2-128

Meaning
CHR$(8%), the put string into core common code.
The string to put in core common.

Data Returned
The target string is the passed string.
Privileges Required
None.
Discussion
This call allows a program to load a single string into a common data
area called core common. Another program running under the same job
and called by the CHAIN statement can extract this string later.
The
string can be from 0 to 127 bytes long.
If the string to be put into
the core common area is longer than 127 bytes, the system sets the
length of the core common string to O.
This function provides a way to pass a limited amount of information
when a program executes a CHAIN statement.
If you want to pass a
larger amount of information, it must be written to a disk file and
read back by the later program.

7-27

Exit and Clear Program
F=9

Exit and Clear Program
Data Passed
Meaning

Bytes
1

CHR$(9%), the exit and set up NONAME code.

2-3

The first three characters of the run-time system name, in
Radix-50 format, to which control is to pass. If bytes 2-5
are zero, the call selects your job keyboard monitor.

4-5

The last three characters of the run-time system name, in
Radix-50 format, to which control is to pass.

If you do not specify this byte, the call establishes the
r_un-time system you name in bytes 4··5 as the job keyboard
monitor.
otherwise, CHR$(N%); the following values of N% determine
the action performed:
Value
255%
0%

Action
Establish the run-time system as the job keyboard
monitor.
Enter the specified run-time system without
establishing it as the job keyboard monitor.

Data Returned
None.
privileges Required
None.
Discussion
This call clears the current program from memory and returns control
to your job keyboard monitor or the run-time system you specify in
bytes 2-5. It also closes all channels without cleaning up partial
buffers.
(That is, any I/O in progress is not completed). This is
the proper way of stopping a program that is not to be rerun. Such
programs are those that terminate on an error and have the privileged

7-28

Exit and Clear Program
F=9

bit set in the protection code.
performs the same action.

The BASIC-PLUS command NEW NONAME

If bytes 2 through 5 specify a run-time system, the call transfers
control to that run-time system and establishes it as the job keyboard
monitor.
If you do not specify bytes 2 through 5, the call transfers
control to the job keyboard monitor.
If you specify byte 6 with a
value of 0, it causes a temporary switch to the run-time system named
in bytes 2-5.
The run-time system to which control is returned prints its prompting
message.
For the BASIC-PLUS run-time system, two prompts are
possiblc~.
If the job is logged in to the system, BASIC-PLUS prints
carriage return, line feed, and Ready prompt followed by one carriage
return and two line feeds.
If the job is not logged in, BASIC-PLUS
prints carriage return, line feed and Bye followed by one carriage
return and two line feeds.

7-29

Cancel All Type Ahead
F=ll
Cancel All Type Ahead
Data Passed
Bytes

Meaning

CHR$(ll%), the cancel type ahead code.

CHR$(N%), where N% is the number (between 0 and 12) of the
channel on which the system executes the call.
If you do
not specify this byte, the call uses channel O.

Data Returned
The target string is equivalent to the passed string.
Privileges Required
None.
Discussion
This call clears all unread, pending input from a terminal's buffers,
which cancels any input typed before a program requests it.
This call
is mainly intended for echo control operations, where echoing of
unsolicited input ruins the appearance of painted fields.
See the
section "Echo Control: MODE 8%" in Chapter 4 for the discussion of
controlling echo and declaring a field on a screen to have a special
paint character.
The call selects the terminal open on the channel number you pass in
byte 2.
(The terminal must be open on that channel.) If you use a
slave terminal, byte 2 must be a nonzero channel number on which the
master terminal is open; byte 3 must contain the keyboard number of
the slave terminal.

7-30

Return Information on Last Opened File
F=12
Return Information on Last Opened File
Data Passed
Meaning

Byte
1

CHR$(12%), the return information about the last opened file
code.

Data Returned
Meaning

Bytes
1

The current job number times 2.

Internal coding.

The channel number (times two) on which the file was opened.

The most significant bits of the file size (MSB size).
If
the call returns a nonzero number, it indicates a file whose
size is greater than 65535 blocks.

5-6+

project-programmer number.

7-10+

File name in Radix-50 format.

11-12+

File type in Radix-50 format.

13-14+

The least significant bits (LSB) of the file size (in
blocks).

15-16+

The default buffer size (in bytes).

17-18+

The OPEN MODE value.

19-20

status (the same information returned by the BASIC-PLUS
STATUS variable).

21+

File cluster size (MOD 256).

22+

Protection code of the file opened.

23-24+

The physical device name, in ASCII format.

7-31

Return Information on Last Opened File

F=12
25+

The device's unit number (a real number).

Bit flags that specify whether the
public structure.
See Discussion.

d~vice

is part of the

Internal coding.

27-30

Privileges Required
None.
Discussion
When you execute a compiled program under the BASIC-PLUS run-time
system (by a RUN command, a CHAIN statement, or a CCL command that
executes a .BAS or .BAC file), BASIC-PLUS saves several pieces of
information about the program, including its file specification and
job number.
When the file is opened, BASIC-PLUS saves the information in file name'
string scan format (identified by the + in the Data Returned).
BASIC-PLUS keeps this information until another file is opened, at
which time it updates the information.
This SYS call allows you to
obtain the information that BASIC-PLUS saves.
See the section "File
Name String Scan Format" for more information.
For a file-structured OPEN, byte 26 of the returned string contains
the following information in bits I and 0 (the other bits are
meaningless):
Bit 0

= 0

The device is in the public structure.

Bit 0

= I

The device is a private disk.

Bit I

= 0

A specific device was not specified.

Bit 1 = I

A specific device was specifiede

These bits are meaningless for a non-file-structured OPEN.

7-32

Return Information on Last Opened File
F=12
Examples
The following two e:~amples illustrate the Return Information on Last
Opened File SYS call:
o

DB3: is a public disk.
If the file SY:FOO was last opened
and the file is on DB3:, bytes 23-25 contain DB3. However,
the program can examine byte 26 (using the AND operator) to
determine that:
Byte 26 AND I

= 0

Byte 26 AND 2 = 0

The device is part of the public
structure.
The public structure was specified.

Therefore the correct device designator is SY:.
o

DB3: is the public disk. Using DB3:FOO as last opened file,
the correct device designator would be DB3: since:
Byte 26 AND 1 - 0

The device is part of the public
structure.

Byte 26 AND 2 = 2

The device has a specific unit number in byte 29.

Note that this call returns information about the file last opened, no
matter how it was opened.
For example, suppose the call is made after
you type:
OLD PROG
RUN
The last file opened is a BASIC-PLUS work file, not the program
PROG.BAS.

7-33

Execute CCL Command
F=14
Execute CCL Command
Data Passed
Meaning

Bytes
1

2-128

CHR$(14%), the execute a CCL command code.
The string to be executed.

Data Returned
The target string is equivalent to the passed string.
Privileges Required
None

The protection code grants you execute access

GREAD

Execute any program within the group

WREAD

Execute any program

Possible Errors
Meaning

ERR Value

?LINE TOO LONG
The string you passed is too long to be executed as
a CCL command. Note that the monitor expands CCL
abbreviations to their full syntax.

?ILLEGAL NUMBER
You used a nonnumeric value as an argument in one of
the ceL switches.
For example, a /SIZE:A switch
specification can cause this error.
-

?ILLEGAL SWITCH USAGE
You specified an illegal switch for the CCL command.
For example, requesting a size that is larger than
the system's SWAP MAX can cause this error.

7-34

Execute

eeL Command
F=14

Discussion
This call causes the monitor to scan the string in bytes 2-128 to
determine if it is a valid eeL command.
If the string is valid, the
call removes the current program from memory and executes the eeL
command as though it had been typed directly to a keyboard monitor.
Note that this call has the same effect on your current program as a
CHAIN statement:
both cause your current program to be terminated and
removed from memory.
If the string is not valid because of one of the previously described
error conditions, the program terminates (unless an error handling
routine is in effect).
If the string is valid but no such eeL command
is defined, the monitor returns control to the caller (with no error)
at the next program statement.
other errors can be detected after the call removes the current
program and the system attempts to execute the eeL command (see the
RSTS/E System Directives Manual).

7-35

System Function Calls to FIP
F=6
SYS System Function Calls to FIP (F=6)
The SYS call whose function code is 6 is a specialized case of the
general system function call.
SYS call 6 contains a subfunction code
called the FIP code.
The FIP code causes a dispatch call to be made
to special resident or nonresident code that performs file processing.
The entire class of subfunctions of SYS call 6 are called FIP calls.
Because programmers generally use FIP calls much more frequently than
the SYS calls, the FIP calls are also commonly referred to as SYS
calls.
This chapter also uses SYS call as the preferred term.
The format of the call is:
V$

SYS(CHR$(6%) + CHR$(FO%) + 0$)

where:
V$

is the data (target) string returned by the call.

FO%

is the FIP subfunction code.

is the optional (by function) parameter string.

The general format of the target variable (V$) is:
Bytes

Meaning

Job number times 2.

Value of internal function called (normally meaningless to
general users).

3-30

Data returned.
Note
Except for the Message Send/Receive calls (SYS 22),
the call always returns 30 bytes. Unused bytes are
not defined.
DIGITAL reserves the right to change the
values returned in these bytes at any time.

The proper use of the FIP system function call requires that you build
a parameter string to pass and that you later extract the data from
the returned string, called the target string.
Each call returns a
string of 30 bytes, each byte (or character) of which mayor may not
contain useful information.
The descriptions of the FIP codes specify
the contents of each useful byte in the string. Use these
descriptions to determine whether you need the information.

7-36

System Function Calls to FIP
F=6
Building a Parameter String
Some SYS calls require no parameters except the function and
subfunction codes; other SYS calls require either variable length
parameter strings or very simple parameter strings. For such SYS
calls, it is usually more convenient to set up and execute the
function call in a single statement. The following sample statements
show the procedure:
A$ = SYS(CHR$(6%) + CHR$(-7%))
!ENABLE CTRLC TRAP
!(NO PARAMETER STRING)
A$ = SYS(CHR$(6%) + CHR$(-lO%) + "DKO:FILE.TYP")
!FILE NAME STRING SCAN
!(VARIABLE LENGTH
!PARAMETER STRING)
A$ = SYS(CHR$(6%) + CHR$(-8%) + CHR$(I%))
!FCB/DDB INFORMATION
!FOR FILE OPEN ON
!CHANNEL 1
!(SIMPLE PARAMETER
!STRING)
\

Many SYS calls require more complex data formats. For example, the
Kill A Job SYS call, (SYS 8), requires byte 3 to be the job number to
kill, byte 27 to be 0, and byte 28 to be 255. To build the complex
parameter string to pass to' a function, DIGITAL recommends that you
dimension a 30 element integer array and set the items in the array to
values that map into those required in the parameter string format.
You can then convert the array to a character string by the CHANGE
statement before passing it as the parameter string of the SYS system
function call. The resulting character string is in the proper format
and contains the correct byte values to be placed as the parameter
string of the SYS call. For example:
ti

DIM A%(30%)
\J% == 4%
\A%(I%) = 0% FOR I%
\A%(O%) = 30%
\A%(l%) = 6%
\A%(2%) = 8%
\A%(3%) = J%
\A %( 27 %) ,- 0 %
\A %( 28%) ,= 2 55%

0% TO 30%

7-37

System Function Calls to FIP
F=6
Following the code that builds the list is the CHANGE statement and
the call itself:
100

CHANGE A% TO A$

200

= SYS(A$)

lGENERATES CHARACTER
!STRING FROM THE
!INTEGER LIST
!INVOKE SYSTEM FUNCTION CALL

In the SYS call descriptions, certain parts of parameter strings are
documented as "Reserved; should be 0." You should fill these bytes
with NUL characters (ASCII code 0).
You can use the STRING$(n,O%)
function (where n is the number of NUL characters needed) to generate
a string of proper length or place 0% in the appropriate array
elements.
By placing 0% in these bytes you will be sure that your
code is upward compatible if future releases of RSTS/E use these
currently unused bytes.
If not, your code may produce unpredictable
results with future releases of RSTS/E.

Unpacking the Returned Data
In the example shown in the previous section, the action performed
(kill a job), rather than the data returned, is the objective of the
call.
However, many SYS calls return a data string that is your
primary objective.
In such a case, you must unpack the data in the
string.
When you build the parameter string, DIGITAL recommends two ways to
unpack the returned string:
Method 1:
If you need only a few pieces of data~ it may be more convenient to
operate directly on the returned string.
For example, if you want
only the 4-byte Radix-50 representation of a 6-byte string, you can
use the File Name String Scan SYS call (SYS -10):
A$ = MID(SYS(CHR$(6%) + CHR$(-lO%) + S$), 7 S\,

I) ,

4%)

The MID function extracts bytes 7 through 10 of the returned string~
To extract numeric data, you can use the ASCII or CVT$% functions.
See the BASIC-PLUS Language Manual for more information.

7-38

System Function Calls to FIP
F=6
Itfethod 2:
If you need many pieces of the returned data, or if you need to use
the string returned by the SYS call to set up another SYS call, you
can transform the returned string to a 30-element integer array using
a CHANGE statement.
For example:
CHANGE A$ TO A%
CHANGE SYS( ... ) TO A%
When you convert the returned string in this manner, you need to do
further conversions to get numeric data into a usable form.
Consider,
for example, the data returned by a the Directory Lookup On Index call
(SYS 15).
The layout of the data returned specifies that bytes 11 and
12 are the file type encoded in Radix-50 format.
To convert those
bytes into an ASCII string (for example, to open the file), you must
convert the two bytes to a single integer and then use the BASIC-PLUS
RAD$ function.
However, the integer representation of each byte
occupies a full word; 16 bits in length.
Figure 7-1 shows array elements 11 and 12.
1..C:'I
A%(11)

[

15
A%(12)

[

Figure 7-1:

7
BYTE 11

BYTE 12
MK-00035-01

Integer Representation of Changed Characters

A%(ll) contains the low byte portion of the Radix-50 word; A%(12)
contains the high byte portion of the Radix-50 word.
You must combine
the two bytes into a single word and convert them to the proper
character string representation:
S$ = RAD$(A%(11) + SWAP%(A%(12»)

7-39

System Function Calls to FIP
F=6
Figure 7-2 shows that the SWAP% function reverses the bytes (the low
byte takes the high byte position and vice versa) in an integer word.

,. .;.15_ _ _ _---.;7_ _ _ _ _0

BYTE 12

~---.....I SWAP% (A% (12»

'--- - - - - - - - - - -

Figure 7-2:

I----.r[

7
BYTE 12

0
0

---------~

MK-00036-01

Reversal of Bytes by SWAP%() Function

Thus, byte 12 takes the high byte position in the word.
The +
operator then combines the two words to form one word.
The RAD$
function performs the conversion on that one :integer word to produce
the three-character string representation of the file type. See the
BASIC-PLUS Language Manual for a more detailed description of the
SWAP% function and its use with the CVT funct:ions.
The character string is assigned to the character variable S$ and is
in ASCII format.
To convert a longer string from Radix-50 to ASCII format, you must use
this procedure on each pair of bytes in the string.
For example, SYS
call 15 returns the file name in bytes 7 through 10. To convert these
bytes to ASCII format, use the following routine:
A$= RAD$(A%(7%) + SWAP%(A%(8%»)
B$ = RAD$(A%(9%) + SWAP%(A%(lO%»)
F$ = A$ + B$
You can also use the statement:
F$

= RAD$(A%(7%) + SWAP%(A%(8%») + RAD$(A%(9%) + SWAP%(A%(lO%»)

Notation and References Used in SYS Call Descriptions
This section describes conventions used in the SYS call descriptions.
It also provides programming hints for working with SYS calls.
Because programmers commonly refer to the FIP calls as SYS calls, the
term SYS call is used in the individual description of each call.

7-40

System Function Calls to FIP
F=6
P'roject-Programnler Number
Many SYS calls require that you specify a project-programmer number
(PPN) in the calling string, and several return a PPN.
In these
cases, the PPN field is in the general form:
Bytes X and (X+I)

PPN

y;rhere:
Byte X

holds the programmer number

Byte (X+I)

holds the project number.

For example, to set up a SYS call to zero an account on a disk (SYS
13), the calling format shows:
Bytes 5-6

Project-programmer number

If the call is to beset up in a 3D-element array A%, then the format
requires that:
A%(5%)
A% ( 6 %)

programmer number

= project number

Integer (2-Byte) Numbers
Many of the SYS calls described in this chapter return or require
integer data in two consecutive bytes of the returned data string.
this case, the field in the returned string is described in th~
format:
Bytes X and (X+I)

integer value

If you are processing the returned string directly (that is, without
changing it to an integer array), then you can obtain the integer
value of the two bytes with the statement:
1% = SWAP%(CVT$%(MID(A$,X,2%»)
~~here A$ holds the returned string.
See the BASIC-PLUS Language
1'1anual for a discussion of the SWAP% function with the CVT functions.

If you convert the returned data string to an integer array A% using
the CHANGE statement, then you can obtain the integer value with the
statement:
1% = ,A%(X) + SWAP%(A%(X+I%»

7-41

System Function Calls to FIP
F=6
For example, the Get Monitor Tables - Part I SYS call (SYS -3) returns
the address of the monitor's job table in bytes 11 and 12.
If A$
holds the returned string, then either of the following two routines
puts the address of the job table into the integer variable 1%:
1%

= SWAP%(CVT$%(MID(A$,11%,2%»)

CHANGE A$ TO A%
1% = A%(ll%) + SWAP%(A%(12%»

Unsigned Integer (2-Byte) Numbers
In some integer fields in the FIP calls, the value is a full 16-bit
unsigned integer between 0 and 65535.
The sign bit indicates an extra
power of two rather than positive or negative.
Because an integer
value in BASIC-PLUS is between -32768 and +32767, any value greater
than 32767 must be stored as a floating-point value. Assume that in
some SYS call, the call returns an unsigned integer in bytes 5 and 6
and that the returned string has been changed to an array, A%. As
always, the high byte of the integer is in byte 6, the low byte in
byte 5.
The following statement places the full 16-bit value into the
floating-point variable Q:
Q = 256.*A%(6%) + A%(5%)
where Q is always positive. Note that replacing the 256.* in the
statement with SWAP%() causes the expression to be first evaluated as
a normal integer expression and then changed to a floating-point
value.
This operation is not desirable because the resulting value is
between -32768 and +32767.
The 256.* forces the expression to be
evaluated as a floating-point number.
Converting an unsigned integer to two bytes to pass to a SYS call also
requires special processing. Assume that Q holds the unsigned value
and that the value is to be placed in A%(5%) (low order) and A%(6%)
(high order).
The most direct method of transformation is:
A%(6%)
A%(5%)

= Q/256.
Q-A%(6%)*256.

On PDP-II computers without floating-point hardware (FIS or FPP),
division operations are relatively slow.
On these machines, a faster
method is the routine:

= Q - 32768.
\ Q% = Q% EQV 32767%
\ A%(5%)
\ A%(6%)

Q% AND 255%
(Q%) AND 255%

= SWAP%

7-42

System Function Calls to FIP
F=6
, However, this second method requires more code.

Negative Byte Values
Many FIP calls pass and return integer values in one byte of the data
string.
Some call descriptions refer to negative byte values.
While negative byte values are meaningful to MACRO programmers,
BASIC-PLUS treats all byte values as positive. Where the term
"negative" byte value is used, it refers to an integer value between
128% and 255%.
To obtain the actual signed value, use the following
statement:
S% = SWAP%(B%)/256%
where B% is the byte to convert.

File Name String Scan Format
The File Name String Scan SYS call (SYS -10) is useful as a
"front-end" for many SYS functions.
Most of the SYS calls that
require device or file information in their parameter strings expect
information in the format in which the SYS -10 call returns it.
For
example, SYS call 17, Disk Directory Look Up On File Name, expects its
calling string to be passed in exactly the same format as that
returned by the SYS -10 call, with a change of only four data bytes.
The following routine sets up and executes the look up calIon the
file DKO:[10,20]INVENT.DAT, using the File Name String Scan SYS call:
10

32767

DIM A%(30%)
\A$="DKO:[lO,20]INVENT.DAT"
\CHANGE SYS(CHR$(6%)+CHR$(-10%)+A$) TO A%
\A%(0%)=30%
\A%(1%)=6%
\A%(2%)=17%
\A%(3%),A%(4%)=O%
\CHANGE A% TO A$
\CHANGE SYS(A$) TO A%
END

Many calls require a file name, password, pack identification label or
other six-character string to be passed as two words in Radix-50
format.
The File Name String Scan call is the only means provided to
convert the string to the proper format.
The section "File Name
String Scan" (SYS=-lO, SYS=-23) describes how this conversion is done.

7-43

System Function Calls to FIP
F=6
Note
The SYS call descriptions that follow use a special
convention to avoid repetition. A plus sign (+)
postscript identifies fields in the calls that are
either passed or returned in the same format as that
returned by SYS call -10, File Name String Scan. See
the section "File Name String Scan" (SYS=-lO, SYS=-23)
for a detailed description of the fields returned by
File Name String Scan.
See Table 7-3 in the beginning of this chapter for a
quick reference index of the SYS functions ordered by
FIP code (FO). See Table 7-4 for a quick reference
index of the SYS functions arranged alphabetically by
function name.

MACRO Mnemonic Cross-References
The RSTS/E System Directives Manual describes monitor directives for
MACRO programmers. Many directives correspond to the SYS calls
described in the following sections. In each section that follows,
the SYS call number (FO =) appears in bold type at the top of the
page. The corresponding MACRO directive appears in parenthesis below
it. For a summary of SYS call codes and their corresponding monitor
directives, see Table F-l. For information on the use of MACRO
directives, see the RSTS/E System Directives Manual.

Organization of This Section
The system function calls to FIP are listed by number, from the most
negative to the most positive. There are three exceptions to this
sequence:
o

File Name String Scan (FO=-lO, FO=-23). Because this call is
used as a "front end" for many calls " it is described first.

Directory Lookup Calls (FO=15, FO=17). Because these calls
are related, SYS 17 is right after SYS 15.

Message Send/Receive (FO=22).
description of this call.

See Chapters 8 and 9 for a

The PEEK function is described at the end of this chapter.

7-44

File Name String Scan
FO=-10 FO=-23
(.FSS)
File Name String Scan
Data Pa!3sed
Bytes

Meaning

-1

CHR$(6%), the SYS call to FIP.

CHR$(-10), the file name string scan code.
CHR$(-23) is the same as CHR$(-10) except that the scan
terminates on certain characters. See Discussion.

3-?

Character string to scan; can be any length.

Data Returned
Sets the STATUS variable and returns the following:
Bytes

Meaning

The current job number times 2.

The Most Significant Bits (MSB) of the file size as
specified in the /FILESIZE:n (or /SIZE:n) file specification
switch.
If the call returns a nonzero number, it indicates
a file whose size is greater than 65535 blocks.

3-4

Internal coding.

5-6

project-programmer number (PPN).
0 means the current
account. See the Discussion for information about
translation of special characters.

7-10

File name in Radix-50 format.

See Discussion.

11-12

File type in Radix-50 format.

See Discussion.

13-14

The number of blocks specified in the /FILESIZE:n (or
/SIZE:n) file specification switch; for files that are
larger than 65535 blocks, the Least Significant Bits (LSB)
of the file size.

15-16

The file cluster size given in the /CLUSTERSIZE:n file
specification switch.

17-18

The value for MODE, if specified in the /MODE:n (or /RONLY)
file specification switch, with the sign bit set; 0 if /MODE
or /RONLY were not specified.

7 - 45.

File Name String Scan
FO=-10 FO=-23
19-20

The value for file position in the IPOSITION:n switch, where
n represents the device cluster number at which the first
block of the file is placed.

If no protection code is found, this byte is 0 unless a job
If a protection
default protection is currently assigned.
code is found or if no protection code is found when a job
default protection is currently setf this byte is nonzero
and byte 22 contains the protection code.

Protection code when byte 21 is nonzero.

23-24

To determine what is returned for a device, flag word 2 must
be checked.
If no colon was found in the string, these two
bytes and byte 25 and 26 are O.
If a colon was found, a
device name may or m~y not have been found.
A device name can be a physical device name or a logical
device name.
If a physical device name was found, these
bytes contain two characters in ASCII format.
(For example,
DK yields D in byte 23 and K in byte 24.) Bytes 25 and 26
contain unit number information.
If a logical name (either
job-specific or system-wide) was found and that logical name
was translatable (the name was currently assigned to a
physical device), the call translates the name and returns
the full physical device information in bytes 23 through 26.
If the logical device name was untranslatable, the call
returns the logical name in Radix-50 format in bytes 23
through 26.
For logical names longer than 6 characters, the
call returns only the first 6 characters.
The monitor does
not translate the logical device name if the name is not
currently assigned to a physical device or if the first
character of the logical name strin9 is an underscore (for
example, OPEN "_KB:It).
Note that, if a physical device name is passed to this call
and the device is not configured on the system, the name is
treated as an untranslatable logical name.

If a physical device name is returned in bytes 23 and 24,
this byte contains unit number information.
The unit number
here is real if byte 26 is 255.

If this byte is 0, no explicit unit number was found for the
device.
If this byte is 255, the value in byte 25 is the
explicitly specified device unit number.
The 255 value here
indicates that a zero in byte 25 is explicitly unit 0 of the
device.

7-46

File Name String Scan
FO=-lO FO=-23

27-28

First flag word.

See Discussion.

29-30

Second flag word.

See Discussion.

Privileges Required
None~

Possible! Errors
Meaning

ERR Value

?ILLEGAL FILE NAME
The character string scanned contains unacceptable
characters.
See the RSTS/E System User's Guide for
a description of a file specification.
If you are
using the -10 version of the call, the string may
contain other than a valid file specification
swi tc:h.

?ILLEGAL NUMBER
The argument on a file specification switch is
missing or contains an illegal character.

?ILLEGAL SWITCH USAGE
A file specification switch in the string scanned is
not the last element in the file specification, is
missing a colon, or is not a valid form of the
switch.

Discussi.on
The file name string scan function determines specific file syntax
information (for example, whether a given file name is valid) and
returns information in the format required for all other file- and
device-related SYS calls.
The call also processes the allowable
RSTS/E file specification switches.
See the RSTS/E System User's
Guide for a description of the format of these switches.
Note
This call is the only means provided to pack a string
in Radix-50 format.

7-47

File Name String Scan
FO=-lO FO=-23
The call does the following for each component of a file
specification:
o

For a device specification, the call processes physical
device names and unit number information. If you pass a
logical name, the call attempts to translate it to a physical
name. Note that if the logical name string contains an
underscore as the first character, the call does not
translate the logical name. The STATUS variable is set for
the device type found in the string scanned.

For a project-programmer specification, the call validates
the format.
If you pass a character denoting an account, the
call translates it to the proper numbers. For example, if $
is assigned to the system library account, [1,2], $ is
returned as 2 in byte 5 and 1 in byte 6. Besides the $, the
call also translates the characters 1, %, &, # and @ if they
are assigned to accounts and indicates whether the wildcard
character was found.
Note
Special PPN characters other than the dollar
sign ($) may not be available in future
releases of RSTS/E.

For a file name, the call validates the format and translates
the name into Radix-50 format. It also notes the presence of
wildcard characters.

For a file type, the call validates the format and translates
it into Radix-50 format. The call also notes the presence of
wildcard characters.

For a protection code, the call validates the format of the
numbers. If a protection code is not found, the call returns
the assigned value or, if an assignable code is not current,
returns zero.

For file specification switches, the call validates the
placement of the switches in the string and the format of
each switch found. It notes the presence of those switches
found and returns switch arguments.

The following example shows how to convert a string to Radix-50 format
with a user-defined function and the file name string scan SYS call:
10
\

DEF FNPO$(A$) = MID (SYS(CHR$(6%)+CHR$(-10%)+A$),7%,4%)&
1 PACK 6 CHARACTERS TO RADIX-50
7-48

File Name String Scan
FO=-10 FO=-23
The function FNPO$ returns a four-character string that is the
Radix-50 representation of the first six characters of A$.
(Note that
the function does not include error handling and that errors can
occur.) The File Name String Scan SYS call is the only function that
packs a string in Radix-50 format.
To pack strings longer than six
characters, you must make multiple calls to the SYS function.
You can
pack up to nine characters in a single call if a period separates the
first six characters from the last three characters (the file name and
type format).
The two words in bytes 27 and 28 and in bytes 29 and 30 hold easily
accessible flags indicating exactly what fields in the source string
were found and what kind of information they contained.
For the
purposes of the discussion, it is assumed that the returned string was
converted by a CHANGE statement to an integer array, M%(30%).
The
flag words are then created by doing the proper arithmetic operations
on the bytes, as shown:
flag word 1:
flag word 2:

SO%
Sl%

= M%(27%)+SWAP%(M%(28%»
= M%(29%)+SWAP%(M%(30%»

Once you create these two words, the information in them is accessible
by means of an AND operation between the word and the bit relating to
a particular piece of information.
Each bit of the PDP-II word holds
a YES or NO answer; see Tables 7-5 and 7-6 for details.
Flag word 1 indicates whether file specification switches were
detected in the string passed.
Flag word 2 contains information about
elements found in the file specification.
The high byte of flag word
1 is retained for compatibility with previous versions of RSTS/E.
Tables 7-5 and 7-6 assume that bytes 27 and 28 have been put into SO%
and bytes 29 and 30 have been put into Sl%, as described in the
previous example.
Table 7-5:

File Name String Scan Flag Word 1

+ .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Flag word 1: where SO% = M%(27%)+SWAP%(M%(28%»
I
+ .. - - - -+- - - - - - - - - - - - - - - - - - - - - -+- - - - - - ,. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I Bit I
Comparison
I
Meaning
I
+ .. - - - -+- - - - - - - - - - - - - - - - - - - - - -+- - - - - - ,. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I
0
(SO% AND 1%)<>0%
The /CLUSTERSIZE:n switch was
I
(50% AND 1%) = 0%
specified.
I
No /CLUSTERSIZE:n was found.

I
I

I
I
, I

(SO% AND 2%)<>0%
(SO% AND 2%) = 0%

Either the /MODE:n or /RONLY switch
was specified.
Neither /MODE:n nor /RONLY was found.

7-49

File Name String Scan
FO=-lO FO=-23

Table 7-5:

File Name String Scan Flag Word 1 (Cont.)

+- - - - -+- - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - --II Bit I
Comparison
I
Meaning
I
+- - - - -+- - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - -. - - - - - - - - - - - - - - - --+
n

= 0%

(50% AND 8%)<>0%
(50% AND 8%) = 0%

4-7

Reserved.

= 0%

(50% AND 1024%)<>0%
(50% AND 1024%)

= 0%

(50% AND 512%)<>0%
(50% AND 512%)

= 0%

(50% AND 2048%)<>0%
(50% AND 2048%) = 0%

(50% AND 4096%)<>0%
(50% AND 4096%)

(50% AND 8192%)<>0%
(50% AND 8192%)

(50% AND 256%)<>0%
(50% AND 256%)

I Either the /FILE5IZE:n or /5IZE:n
I
I switch was specified.
I
I Neither the /FILE5IZE:n nor /5IZE:n
I
I switch was found.
I
I The /P05ITION:n switch was specified.
I No /P05ITION:n switch was found.
I

(50% AND 4%)<>0%
(50% AND 4%)

A file name was found in the source
string (and is returned in Radix-50
format in bytes 7 through 10).
No file name was found.
A period (.) was found in source
string.
No period was found in source string
implying that no file type was
specified.
A project-programmer number (PPN) was
found in source string.
No PPN was found.
A left angle bracket «) or /PR was
found in source string, implying that
a protection code was found.
No left angle bracket «) or /PR was
found (no protection was specified).
A colon (but not necessarily a device
name) was found.
No colon was found, implying that no
device could have been specified.
Device name was specified and was a
logical device name.
Device name (if specified) was an
absolute (nonlogical) device name.
(If device name was not specified,
thi s i s 0.)

7-50

File Name String Scan
FO=-10 FO=-23
Table 7-5:

File Name String Scan Flag Word 1 (Cont.)

i· - - - - - + - - - - - - - - - - - - '. - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +

I Bit I

Comparison

Meaning

i· - - - - - + - - - - - - - - - - - - '. - - - - - - - - - + - - - - - .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +

15 I SO%<O%

50urce string contained wildcard
characters (either? or * or both) in
file name, file type or PPN fields.
In addition, the device name
specified, though a valid logical
device name, does not correspond to
any of the logical device assignments
currently in effect or contains an
underscore as the first character.
You must test bits of flag word 2 for
wildcard characters and device name
found.
+,- - - - -+,. - - - - - - - - - - - .. - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I
I
I
I
I
I
I
I
I
I
I

Table 7-6:

File Name String Scan Flag Word 2

+ - - - - - - ,. - - - - - - - - - - - .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
I
Flag WOI~d 2: where S1% = M% (29%) +SWAP% (M% (30%) )
+ - - - - - + ,. - - - - - - - - - - - .. - - - - - - - - - - + - - - - .' - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
I Bit I
Comparison
Meaning
+ - - - - - + .. - - - - - - - - - - - .' - - - - - - - - - - + - - - - "' - - - - - - - - - - " - - - - - - - - - - - - - - - - - - - - - - +
o
(51% AND 1%)<>0%
File name was found in the source
string.
(51% AND 1%) = 0%
No file name was found. The next two
comparisons return O.

(51% AND 2%)<>0%

(51% AND 2%)
2

(51% AND 4%)<>0%
(51% AND 4%)

= 0%

(51% AND 8%)<>0%
(51% AND 8%) = 0%

File name was an asterisk (*)
character and is returned in bytes 7
through 10 as the Radix-50
representation of the string
"??????".
File name was not an * character.
File name contained at least one
question mark (?) character.
File name did not contain any ?
characters.
A period (.) was found.
No period was found, implying that
no file type was specified. The
following three comparisons return

7-51

File Name String Scan
FO=-lO FO=-23

Table 7-6:

File Name String Scan Flag Word 2 (Cont.)

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

I Bit I

Comparison

Meaning

+- - - - -+- - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
A file type was found (that is, the
(51% AND 16%)<>0%
4
field after the period was not
null).
No file type was found. (The field
(51% AND 16%) = 0%
after the period was null -- the
next two comparisons return 0.)
5

(51% AND 32%)<>0%

(51% AND 32%) = 0%
6

(51% AND 64%)<>0%
(51% AND 64%) = 0%

File type was an * character and is
returned in bytes 11 and 12 as the
Radix-50 representation of the
string "???".
File type was not an * character.
File type contained at least one ?
character.
File type did not contain any ?
characters.

(51% AND 128%)<>0%
(51% AND 128%) = 0%

A PPN number was found.
No PPN was found. (The next two
comparisons return 0.)

(51% AND 256%)<>0%

Project number was an * character
(that is, the PPN was of the form
[*,PROG) and is returned in byte 6
as 255.
Project number was not an *
character.

(51% AND 256%) - 0%
9*

(51% AND 512%)<>0%

(51% AND 512%)

= 0%

Programmer number was an * character
(that is, the PPN was of the form
[PROJ,*)
and is returned in byte 5
as 255.
Programmer number was not an *
character.

(51% AND 1024%)<>0%
(51% AND 1024%), = 0%

A protection code was found.
No protection code was found.

(51% AND 2048%)<>0%

The protection code currently set as
default by the current job was used.
The assignable protection code was
not used.

(51% AND 2048%)

= 0%

7-52

File Name String Scan
FO=-lO FO=-23

Table 7-6:

File Name String Scan Flag Word 2 (Cont.)

- - - -+- - - - - - - - - - - ~ .. - - - - - - - - - -+- - - _ .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Comparison
Meaning
+.~ - - - -+.- - - - - - - - - - - _ .. - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
12
(81% AND 4096%)<>0%
A colon (:), but not necessarily a
device name, was found in the source
string.
(81% AND 4096%) = 0%
No colon was found (no device could
have been specified); the following
three comparisons return O.
+.~

I Bit I

(81% AND 8192%)<>0%
(81% AND 8192%) = 0%

A device name was found.
No device name was found; the
following two comparisons return O.

(81% AND 16384%)<>0

Device name specified was a logical
device name.
Device name specified was an actual
device name; the following
comparison returns O.

(81% AND 16384%)

= 0%

The logical device name specified
was invalid for one of the following
reasons:
o The device name contained an
underscore (_) but did not
correspond to any physical
device on the system.
o The device name did not contain
an underscore but could not be
translated to a physical device
name.
The logical name is returned in
bytes 23 through 26 as a Radix-50
string.
The device name specified, if any,
was either an actual device name or
a logical device name to which a
physical device has been assigned.
The physical device name is returned
in bytes 23 and 24 and the unit
information is returned in bytes 25
and 26.

51% < 0%

81% >= 0%

+- - - - - _ .. - - - - _.. - - - - - - - - - - - - ~ - - - - - - - - - - - - - - - ~ - - - - - - - - - - - - - - - - - - - - - - - - --+
I * Note that if the PPN was of the form [*,*], then both bit 8 and
I
I+ _ _ _bit
9
of
the
data
byte
returned
are
nonzero
values.
I
_ _ _ .. _ _ _ _ _ .. _ _ _ _ _ _ _ _ _ _ _ _
+
n

7-53

File Name String Scan
FO=-10 FO=-23
Since flag word 2 contains the high order byte of flag word 1 plus
some additional information, it is the more useful of the two words.
The following sample program uses this word and prints out a list of
all the bits returned in the word.
5

10
20
30
40
50
100
110
120
130
140
150
160
170

180
190
200
210
220
230
240
250
260
490
500
32767

DIM M%(30%)
! SET UP AN ARRAY TO RETURN TO
PRINT "STRING TO SCAN";
INPUT LINE S$
S$=CVT$$(S$,-l%)
! GET RID OF GARBAGE BYTES
CHANGE SYS(CHR$(6%)+CHR$(-10)+S$) TO M%
Sl%=M%(29%)+SWAP%(M%(30%»
IF Sl% AND 1%
THEN PRINT FILENAME FOUND"
IF Sl% AND 2%
THEN PRINT FILENAME WAS AN ,*,"
IF 51% AND 4%
THEN PRINT FILENAME HAD '?'S"
IF 51% AND 8%
THEN PRINT DOT (.) FOUND"
IF 51% AND 16%
THEN PRINT NON-NULL FILE TYPE FOUND"
IF Sl% AND 32%
THEN PRINT FILE TYPE WAS ,*,,,
IF Sl% AND 64%
THEN PRINT FILE TYPE HAD '?'S"
IF 51% AND 128% THEN PRINT PPN FOUND"
IF Sl% AND 256% THEN PRINT PROJECT NUMBER WAS ,*,"
IF Sl% AND 512% THEN PRINT PROGRAM.MER NUMBER WAS ' *,"
IF Sl% AND 1024%
THEN PRINT "PROTECTION CODE FOUND"
IF Sl% AND 2048%
THEN PRINT "ASSIGN'D PROTECTION USED"
IF 51% AND 4096%
THEN PRINT "COLON (:) FOUND"
IF Sl% AND 8192%
THEN PRINT "DEVICE NAME FOUND"
IF 51% AND 16384% THEN PRINT "DEVICE NAME WAS LOGICAL"
IF 51%<0% THEN PRINT "DEVICE NAME NOT ASSIGN'D OR UNDERSCORE'
IF 51% AND 4096%
THEN
IF Sl%>O% THEN PRINT "'STATUS' HAS BEEN SET"
PRINT FOR I%=I% TO 2%
GOTO 10
END

The following examples show some of the previous messages:

STRING TO SCAN? ABCDEF.TYP
FILENAME FOUND
DOT (.) FOUND
NON-NULL FILE TYPE FOUND
STRING TO SCAN? SY:FILENM.DEX
FILENAME FOUND
DOT (.) FOUND
NON-NULL FILE TYPE FOUND
COLON (:) FOUND
DEVICE NAME FOUND
'STATUS' HAS BEEN SET
STRING TO SCAN?
FILENAME FOUND
DOT (.) FOUND

SY:FILENM.TYP[1,203]

7-54

File Name String Scan
FO=-lO FO=-23

NON-NULL FILE TYPE FOUND
PPN FOUND
COLON (::) FOUND
DEVICE NAME FOUND
'STATUS' HAS BEEN SET
STRING TO SCAN? SY:FILENM.TYP[2,103]/PR:52
F'ILENAME FOUND
DOT (.) FOUND
NON-NULL FILE TYPE FOUND
PPN FOUND
PROTECTION CODE FOUND
COLON (::) FOUND
DEVICE NAME FOUND
'STATUS' HAS BEEN SET
STRING TO SCAN? SY:FILENM.TYP[,20l]
F'ILENAME FOUND
DOT (.) FOUND
NON-NULL FILE TYPE FOUND
PPN FOUND
PROJECT NUMBER WAS I'
COLON (:) FOUND
DEVICE NAME FOUND
'STATUS' HAS BEEN SET
STRING TO SCAN? SY:A.
F'ILENAME FOUND
DOT (.) FOUND
NON-NULL FILE TYPE FOUND
F'I LE TYPE WAS "
COLON (::) FOUND
DEVICE NAME FOUND
'STATUS" HAS BEEN SET
STRING TO SCAN? SY:FILE??TYP
F I L ENAMl~ FOUND
FILENAME HAD '?'S
DOT (.) FOUND
NON-NULL FILE TYPE FOUND
COLON (::) FOUND
DEVICE NAME FOUND
'STATUS v HAS BEEN SET
STRING TO SCAN?
:A
FILENAMl~ FOUND
COLON (::) FOUND
'STATUSv HAS BEEN SET

7-55

File Name String Scan
FO=-lO FO=-23

The STATUS variable is set or not set depending on the presence or
absence of a device in the string scanned.
The following three
conditions apply:
o

When no device name is found in the string; that is, no colon
is found, the STATUS is unpredictable.
This condition
applies when bit 12 of flag word 2 tests as equal to O.

When the device name is logical and untranslatable (an actual
device is not assigned or the logical name string begins with
an underscore), STATUS is unpredictable.
This condition
applies when bits 12, 13, and 14 of flag word 2 test as not
equal to 0 and bit 15 tests' as on (Sl%<O%).

When the device name is either an actual device name or is
logical and translatable, STATUS is set for the device.
This
condition applies when bit 12 tests as not equal to 0 and bit
15 tests as equal to 0 (Sl%>=O%).

Line 260 of the sample program shows the test to determine when STATUS
is set by the call.
The file name string scan call has two versions.
Both calls process
RSTS/E file specification switches.
The -10 version of the call
processes a RSTS/E file specification only.
If other than a valid
form of a file specification switch is found, it generates the error
?Illegal file name (ERR=2).
The -23 version of the call processes a
full command line, which can contain multiple file specifications and
switches other than valid forms of the file specification switches.
To process a full command line, the call terminates the scan on
certain characters.
The file name string scan using CHR$(-23%) in place of CHR$(-lO%)
terminates without error on the following characters:
=
/

Equal sign
Slash unless part of a valid file specification switch
Semicolon
Comma unless between brackets or parentheses (indicates PPN) end
of string

The scan is done from left to right.
If the scan finds a valid file
specification switch, it processed the switch and continues the scan.
If the scan finds other than a file specification switch, the scan
terminates.
The program must process the switch and also check for
remaining switches.
The scan does not process any file specification
switches following a switch that terminates the scan.

7-56

File Name String Scan
FO=-lO FO=-23

The BASIC-PLUS variable RECOUNT returns the number of unscanned
characters.
For example:
S$=SYS(CHR$(6%) + CHR$(-23%) + "SY:[l,4)ABC/PR:40")
This call returns the data as described for CHR$(-lO%) and RECOUNT
equals O.
The following call returns the data described for
CHR$(-lO%) for the string "SY:[l,4)ABC/PR:40" and RECOUNT equals 7:
S$

SYS(CHR$(6%) + CHR$(-23%) + "SY:[l,4)ABC/PR:40,DT:DEF")

The scan terminates on the comma between file specifications. Any
other characters generate an error and none of the data is returned.

7-57

Get Monitor Tables· Part III
FO=·29
(UU. TB3 )
Get Monitor Tables . Part III
Data Passed
Meaning

Bytes

CHR${6%), the SYS call to FIP.

CHR$(-29%), the get monitor tables - part III code.

3-30

Reserved; should be O.

Data Returned
Meaning

Bytes
1

The current job number times 2.

Not used.

3-4

(DDCTBL)

- The controller/device table.

5-6

(UCTTBL)

- The unit/controller table.

7-8

(SATEND)

- The disk size table.

9-10

(UNTLVL)

- The disk structure level table.

11-12

(MFDPTR)

- The MFD pointer table.

13-14

(MAGLBL)

- The magnetic tape label default table.

The number of jobs currently on the system.

16-20

Internal code.

21-22

Hardware 'configuration word.

23-24

(UNTERR)

25-26

(DEVCLU) - The low byte contains the device cluster size.
The high byte contains the CLUFAC table.

27-28

(NULRTS)

29-30

(DSTPTR) - The memory management unit (MMU) address of the
disk statistics table if this monitor is generated with the
unsupported disk statistics feature.
Otherwise, O.

See Discussion.

- The unit error table.

- The null run-time system block pointer.

7-58

Get Monitor Tables - Part III
FO=-29
privileges Required
None.
:Possible Errors
None.
Discussion
The three Get Monitor Table SYS calls to FIP return to your program
either an address or a data value.
The calls are commonly used with
the PEEK function to read various system parameters and tables that
give configuration and-run-time information.
Because it is beyond the
scope of this manual to describe the monitor, this section only
briefly describes the information returned by the monitor table
functions.
For a description of Get Monitor Tables - Part I, see SYS
call -3.
For a description of Get Monitor Tables - Part II, see SYS
call -12.
The section "The PEEK Function" describes the use of the
PEEK function for certain convenient programming operations.
In this call, a name in all uppercase letters denotes each item of
information described.
This name is the same one used to identify the
information in the RSTS/E assembly listings.
If the name is in
parentheses, the information returned is an address of the data
described.
If the name is not in parentheses, the information
returned is the actual data value.
For example, Get Monitor Tables Part I returns CNT.KB-l in byte 3.
The value returned is the number
of terminal lines minus 1 configured on the system.
However, bytes 11
and 12 return (JOBTBL), the address of the table of jobs.
Use the
PEEK function to inspect the address.
Note
All information returned by the call described in this
section is internal to RSTS/E and is subject to change
at any time"
DDCTBL and UCTTBL (bytes 3-6) are pointers to monitor tables that
allow system programs to translate communications device names from
one format to another.
For example, DECnet, which runs on many
different DIGITAL systems, uses a different format for device names
than RSTS/E.
Thus, programs that print information about
communications devices need these tables.
The SYSTAT system program
also uses this call to print its busy devices and disk status reports.
SATEND (bytes 7-9) is a pointer to a disk size table that the SYSTAT
program uses to compute sizes for its display.
UNTLVL (bytes 9-10) is
7-59

Get Monitor Tables - Part III
FO=-29

a pointer to the disk structure level table, MFDPTR (bytes 11-12) is a
pointer to the MFD pointer table, and MAGLBL is a pointer to the
magnetic tape label table. Byte 15 contains the number of entries in
the monitor's job table structure that includes jobs in any state.
The hardware configuration word (bytes 21-22) contains a bit mask
specifying configuration data.
The most useful bit flags are the
following:
Meaning

Value
32%

Q-BUS system.

If bit is OFF, UNIBUS system.

512%

FPP available.

If bit is OFF, FPP is not available.

1024%

CIS available.

If bit is OFF, CIS is not available.

8192%

System has Instruction and Data (I&D) space.
system does not have I&D space.

7-60

If bit is OFF,

FO=-28

Spooling
(UU.SPL)

Spooling
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(-28%), the spool request code.

3-4

Reserved; should be O.

5-6+

The PPN of the file to spool.
If bytes 5-6 are zero, the
call uses the current user account.
The call does not allow
wildcardso

7-10+

The file name (which can include wildcards), in Radix-50
format, of the file to spool.

11-12+

The file type (which tan include wildcards), in Radix-50
format, of the file to spool.

13-14

The two-character, ASCII spooled device name field to which
the file is sent.
If bytes 13-14 are zero, LP is used.
These bytes may affect whether requests are channeled to the
Print/Batch Services (PBS) package or the OPSER-based
spooling package.
See Discussion.

The unit number of the device name field specified in bytes
13-14.

The unit number real flag of the device specified in bytes
13-14. Specify -1 if byte 15 contains an actual unit
number.
Specify 0 if bytes 13-14 contain a generic device
name, in which case the monitor issues a request for the
default print or batch queue.
See Discussion.

17-18

Reserved, must be zero.

19-20

The flag word to specify whether to route the request to the
Print/Batch Services (PBS) or the OPSER-based (OPSER)
spooling package:
Value
0%
4096%

Meaning
The default.

See Discussion.

Network print or batch request.
PBS.
See Discussion.

7-61

Only meaningful for

Spooling
FO=-28

8192%

Always route request to the OPSER-based spooling
package

16384%

Always route request to the PBS package

You can

spec~fy

the following values for the PBS package:

Value

Meaning

Delete the file after spooling; same as DeL PRINT
command's IDELETE qualifier.

32%

No header; same as DeL PRINT command's INOFLAG PAGES
qualifier.
This value is ignored for batch re~uests.

You can specify the following values for the OPSER spooling
package:

Value

Meaning

File is spooled with FORTRAN carriage control;
equivalent to QUE ITYP:FTN option.

Restart; equivalent to QUE IRE option.

Delete the file after spoolin9; equivalent to QUE IDE
option or DeL PRINT command's IDELETE qualifier.

Binary file; equivalent to QUE /BI option.

16%

End; equivalent to QUE lEND option.

32%

No header; equivalent to QUE INH option or DeL PRINT
command's INOFLAG_PAGES qualifier.

21-22

Reserved; should be

23-24+

The device name where the file to be spooled is located.
The device must be a disk.
If bytes 23-24 are zero, SY (the
public structure) is used.

25+

The unit number of the device containing the file to be
spooled.
This byte is ignored if byte 26 is zero.

26+

The unit number real flag of the device containing the file
to be spooled. A nonzero value indicates a real unit number
in byte 25.

27-30

Reserved; should be O.

7-62

Spooling
FO=-28

D1ata Returned

No meaningful data is returned.
Privileges Required
None

Spool a file if the protection code permits access

GREAD

Spool a file /NODELETE in any account within the group

WREAD

Spool any file /NODELETE

GWRITE

Spool a file /DELETE in any account within the group

WWRITE

Spool any file /DELETE

possible Errors
Meaning

ERR value

?NO ROOM FOR USER ON DEVICE
The number of messages pending for the queue is at
its declared maximum.
This may be a transient
condition; retry the operation.

?CAN'T FIND FILE OR ACCOUNT
The account specified in bytes
the device specified, the file
specified in bytes 7-12 cannot
PBS nor QUEMAN (OPSER spooler)
message receiver.

5-6 does not exist on

name or type
be found, or neither
is installed as a

?NOT A VALID DEVICE
An attempt was made to spool a file to a spooling
device that had a unit number greater than 7, or the
file to be spooled is contained on an invalid
device.

?PROTECTION VIOLATION
An attempt was made to queue a file to which the
user did not have read access or queue a compiled
file.

?DEVICE HUNG OR WRITE LOCKED
This error is caused by a hardware condition.
For
example, the specified disk could not be accessed.

?DISK PACK IS NOT MOUNTED
The specified disk device is not mounted; logically

7-63

Spooling
FO=-28

mount the disk with the MOUNT command (requires
MOUNT privilege).
?DISK PACK IS LOCKED OUT
The disk is in a locked state.
Execute the call
under a sufficiently privileged account to override
this condition.

?DEVICE NOT FILE STRUCTURED
The device specified in bytes 23-24 of the call is
not a file-structured device.

?NO BUFFER SPACE AVAILABLE
System buffers are not currently available to store
this message. This may be a transient condition;
retry the operation.

Discussion
RSTS/E has two spooling packages:
the Print/Batch Services package
(PBS) and the OPSER-based spooling package (OPSER).
The system sends the request either to PBS or OPSER according to the
value you specify in bytes 19-20. Bits 8192% and 16384%, if set,
determine the routing.
If both bits are clear, then the next two
rules apply:
o

If the spooled device name field in bytes 13-14 is null or
LP, then the system sends the request to PBS if it is
running. Otherwise, the system sends the request to OPSER.

If the spooled device name field in bytes 13-14 is BA and the
fi1etype is .COM, then the request is routed to PBS.
Otherwise, the system sends the request to OPSER.

PBS and OPSER interpret the device name field passed in bytes 13-14
and 15 differently.
PBS requests:
Data Passed

Call Interpretation

null
LP:
LPn:
BA:
BAn:

Default print queue
Default print queue
Print queue named LPn:
Default batch queue
Batch queue named BAn:

If you specify the value 4096% in bytes 13-14, PBS sends print
requests to NET$PRINT and batch requests to NET$BATCH.
7-64

Spooling
FO=-28

OPSER requests:
Data Passed

Call Interpretation

null
LP:
LPn:
BA:
BAn:

Print
Print
Print
Batch
Batch

queue
queue
queue
queue
queue

LPO:
LP:
LPn:
BA:
BAn:

Byte 16 is the unit number real flag.
A nonzero value instructs the
monitor to issue the request for the queue with the same name as the
device name field.
For this to work properly with the PBS package,
the system manager must define queues named LPO: - LP7:, and BAO: BA7: .
When the monitor executes this call"

it performs the following checks:

Ensures that the specified file name is legally formatted.

Ensures that the specified device (the device containing the
specified file) is a mounted RSTS/E disk and that the user
has access to it.

If no wildcards are specified in bytes 7-12, ensures that the
specified j:ile exists and that the user has read access to
it.

Performs all appropriate send/receive buffer quota checks and
ensures that the spooler is available (not hibernating).

If any of these conditions are not met, the call is aborted and an
error is returned (see possible Errors).
You should use the Send User Request SYS call in future applications.
See Chapter 9, "System Call for Print/Batch Services."

7-65

Snap Shot Dump
FO=-27
(UU .DMP)
Snap Shot Dump
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(-27%), the snap shot dump

3-30

code~

Reserved; should be 0.

Data Returned
No meaningful data is returned.
Privileges Required
SYSIO
Possible Errors
Meaning
?CAN'T FIND FILE OR ACCOUNT
The call attempted to write data to the crash dump
file, but crash dump was not enabled at system
start-up time because sufficient space was not
available on the system disk.

ERR Value
5

Note that this call also returns device-dependent
errors such as ?Device hung or write locked (ERR=l4).
Discussion
This call writes the current monitor image executing in memory and the
contents of the extended buffer pool (XBUF) to the crash dump file
[O,I]CRASH.SYS. XBUF contains monitor data structures, including
DECnet/E data structures and caching information.
You can analyze the
contents of the CRASH.SYS file with the ANALYS program (see the RSTS/E
System Manager's Guide).

7-66

File utility Functions
FO=-26
(UU. FIL)
File utility Functions
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(-26%), the file utility code.

CHR$(N%), where N% is the internal channel number (in the
range 1 to 12) on which the file is open.
If N% is 0, specify the target file by PPN and file name and
type in bytes 5 through 12.

The first flag byte.
(Byte 27 is the second flag byte).
CHR$(F%), where F% specifies the file utility function.
The
function F% is one (or the sum) of the following codes:
Value

Meaning

Set or reset the file's placed bit (cannot be used
with code 8%).
See byte 15.

Modify code 16% to return 0 as the device cluster
number (DCN) if the file's placed bit is not set.

Change the file's backup statistics. Requires DATES
privilege if the date of last access is changed (bytes
17-18 are nonzero).

Change the file's run-time system name field.

16%

Return the file's retrieval information.
That is, 16%
causes the monitor to map the virtual block number
(VBN) of the file into the disk DCN. You can use this
code to obtain an existing file's DCN in order to
place a new file near it.
See Discussion.

32%

unset the file's contiguous bit.
This code allows you
to extend a contiguous file; however, the file is made
noncontiguous.

7-67

File utility Functions
FO=-26

5-6+

64%

Enable/disable sequential mode caching if the file is
cached.
You cannot use this with code 8%. Also see
bytes 13-16.
(Requires TUNE privilege.)

128%

Enable/disable data caching on the file.
You cannot
use this with code 8%.
See byte 15.
(Requires TUNE
privilege.)

If N% in byte 3 is 0, specify the PPN of the file you want
to modify.
If N% is nonzero, these bytes are ignored.

7-10+

If N% in byte 3 is 0, specify the file name (in Radix-50
format) of th~ file you want to modify.
If N% is nonzero, the call ignores these bytes.

11-12+

If N% in byte 3 is 0, specify the file type (in Radix-50
format) of the file you want to modify.
If N% is nonzero, the call ignores these bytes.

13-16

The specifications in these bytes depend on the function
code specified in byte 4:
If byte 4 AND 8%<>0%, then bytes 13 through 16 contain the
new run-time system name field in Radix-50 format.
If byte 4 AND 16%<>0%, then bytes 13 and 14 contain the low
order word of the VBN you want to locate, byte 15 contains
0% or is used by another operation, and byte 16 contains the
high order byte of the VBN you want to locate.
If byte 4 AND 1%+64%+128%, then bytes 13, 14 and 16 contain
zeros or are used by another operation, byte 15 contains
flags for the following operations:
Flag

Meaning

New value for the placed bit if byte 4 AND 1%<>0%.

New value for sequential bit if byte 4 AND 64%<>0%.

32%

New value for no delete/rename bit if byte 27 AND
1%<>0%.

128%

New value for cached bit if byte 4 AND 128%<>0%.

7-68

File utility Functions
FO=-26

17-18

If you select the change file backup statistics fundtion in
byte 4 (code 4), these bytes specify a new date of last
access for the file. If you do not want to change the date,
specify O. If you do not select the statistics function,
the call ignores these bytes.
If you select the change file backup statistics function in
byte 4 (code 4), these bytes specify a new date of creation
for the file. If ydu do not want to change the date,
specify O. If you do not select the statistics function,
the call ignores these bytes.

21-22

If you select the change file backup statistics function in
byte 4 (code 4), these bytes specify a new time of creation
for the file. If you do not want to change the time,
speci.fy O. If you do not select the statistics function,
the call ignores these bytes.

23-24+

If N% in byte 3 is 0, specify the name of the device that
contains the file you want to modify. The device must be a
disk, and a specification of 0 in bytes 23 and 24 indicates
the public disk structure.
If N% is nonzero, the call ignores these bytes.

25-26+

If N% in byte 3 is 0, specify the unit number and unit
number flag associated with the file you want to modify.
If N% is nonzero, the call ignores these bytes.

The second flag byte.
selected functions:
Value

28-30

CHR$(K%), where K% is the sum of the
Meaning

Change the value of the file's no delete/rename bit.
See byte 15. Cannot be used with byte 4, code 8%.
(Requires SYSIO privilege.)

Do not return the error ?Protection violation if the
operation will not succeed. See Discussion.

Reserved; should be O.

7-69

File utility Functions
FO=-26
Data Returned
Meaning

Bytes
1

Not used.

The file characteristics:
byte 2=2%

File is placed.

byte 2=4%

File will be cached sequentially, if at all.

byte 2=16%

File is contiguous.

byte 2=32%

File has the no delete/rename bit set.

byte 2=128%

File will be cached when open.

3-4

If the file's VBN was passed in byte 16 and file retrieval
information (code 16) was requested in byte 4 (see Data
Passed), these bytes contain the DCN of the file's VBN.
Note that these bytes return 0 if the specified VBN is
larger than the file size or if the file was not placed and
function code 2 was not passed in byte 4.

5-26

File attribute data; unused words are filled with zeros.

27-30

The file's run-time system name in Radix-50 format.

Privileges Required
None

Read or set file flags,

GREAD

Read file flags in any account within the group

WREAD

Read file flags in any account

GWRITE

Set file flags in any account within the group

WWRITE

Set file flags in any account

DATES

Change file last access date

TUNE

Set or clear file caching bits

SYSIO

Set or clear nodelete/rename bit

if the

7-70

protE~ction

code permits

File utility Functions
FO=-26

Meaning

ERR Value

?CAN'T FIND FILE OR ACCOUNT
The file or account specified in bytes 5 through 12
is not present on the disk.

?I/O CHANNEL NOT OPEN
The channel specified in byte 3 is not open.

?PROTECTION VIOLATION
The file open on the channel specified in byte 3 is
not a disk file, or the job lacks the privilege
required for the specified operation.

?ILLEGAL SYS() USAGE
The file open on the specified channel is not a disk
file or is a user file directory.

Discussion
This call supplements the functions of the Name Run-time System SYS
call (SYS -17) and the Change File Backup Statistics SYS call (SYS
-11).
This call provides support for files larger than 65535 blocks
and for file placement.
You can also use this call to obtain a file's
run-time system name and attribute data without opening the file.
The run-time system name field (see Data Passed, bytes 4 and 27
through 30) in the accounting entry of the file's User File Directory
(UFO) contains file size information for large files.
The call
decodes the two-word run-time system name field as follows:
o

If the first word is nonzero, the data in both words is the
run-time system name.
The file size is limited to 65535
blocks.

If the first word is 0, the low order byte of the second word
contains the most significant bits of the file size.
The
file size is limited to 2~23-1 blocks.
The high order byte
of the second word is reserved and must be O.

The following restrictions apply to large files:
o

Because an executable file cannot have both a run-time system
name and a most significant bit indication in the field,
large files are not executable.

-~<

7-71

File utility Functions
FO=-26
o

You cannot extend a compiled file beyond block 65535. An
attempt to extend a compiled file past block 65535 results in
the error ?Protection violation (ERR=lO).

You cannot rename a file that is larger than 65535 blocks
with the intent of assigning a compiled protection code. The
attempt is rejected with no error and the compiled bit
remains off.

When you extend a file past block 65535, it loses its
run-time system name.

You cannot change the run-time system name of a file that is
larger than 65535 blocks.
The attempt results in the error
?Protection violation (ERR=lO).

You cannot change the run-time system name of a compiled file
to two words of zeros.
The attempt results in the error
?Protection violation (ERR-IO). Note that you can perform
this operation on a noncompiled file.

You cannot change the run-time system name of any file to a
zero word followed by a non~ero word.

To place a file in a particular position on the disk, specify the
desired disk DeN (Device Cluster Number) as returned in bytes 3 and 4
of this call in the file specification /POSITION switch (see the
RST5/E System User's Guide).
The monitor attE~mpts to place the first
block of the file at or after the specified DeN.
If the file
placement is successful, the placed bit (bit 1, mask value 2) in the
file's UFD entry is set (see SYS calls -10 and -23).
If the file
placement is not successful, the first block of the file is placed at
the lowest free block on the disk, the UFD placed bit is not set, and
no error is returned.
Note that you can use either this call or SYS call -11, Change File
Statistics, to change data in a file's accounting entry. However, the
two calls work differently when you open a file, write to it, change
the date of last access in the file's accounting entry, and then close
the file.
When you use this SYS call to change the date of last access before
closing the file (by specifying 4% in byte 4 and a new date in bytes
17 and 18), the system updates the file's accounting entry to contain
the current date when it closes the file.
Use SYS call -11 if you
want the file's accounting entry to retain the date specified in the
call after the file is closed.
To change the value of the file's no delete/rename bit, pass the new
value as the value 32% in byte 15. The contents of the file's no
delete/rename bit is returned as the value 32% in byte 2. An attempt
7-72

File utility Functions
FO=-26

to reset the bit in the following files generates the error
?Protection violation: [O,l]SATT.SYS, [O,I]BADB.SYS, or
SYO:[O,l]INIT.SYS.
For more information about the no delete/rename
bit, see the REFRESH FILE suboption of INIT, in the RSTS/E System
Installation and Update Guide.
Because you can specify several functions for this call to perform at
once, you can use the value 2% in byte 27 to avoid the error
?Protection violation. This value instructs the call to disregard any
invalid requests while still processing valid ones.
In previous
versions of RSTS/E, the call returned the error if any requested
function could not be executed, even if some of the requested
functions were perfectly valid.

7-73

Manipulate File, Pack, and Account Attributes
FO=-25
(UU .ATR)
Manipulate File, Pack, and Account Attributes
This call has the following subfunctions:
o

Read File Attributes

Write File Attributes

Read Pack Attributes

Read Account Attributes

Write Account Attributes

Delete Account Attributes

certain PDP-II record organizations, such as RMS-1I, define
characteristics for files that they create.
These characteristics are
called file attributes.
File attributes are defined when the file is
created and must be retained during the existence of the file.
In
RSTS/E, file attributes are kept on disk in a UFO entry.
See the
RSTS/E System User's Guide for a description of file attributes.
Account attributes, on the other hand, are divided into "attribute
blocks." Each block is identified by a type c()de in the range 1 to 255
and contains 13 bytes of data.
The account attribute calls identify
the attribute to be accessed using the type code.
Type codes in the
range 1 to 127 are reserved for use by DIGITAL.
Type codes in the
range 128 to 255 are for customer use.
Customer applications
(typically account management related programs) can use these codes
for storing moderate amounts of account-relatE~d information.
Because
excess use of account attributes decreases the number of possible
accounts per group, applications that need to store a lot of data
should use an auxiliary file.
Currently, approximately five
additional (user-supplied) account attributes can be used per account
without affecting the 255 account per group limit.
Note that this is
subject to change because future releases of nSTS/E may use additional
account attributes.
Because these subfunctions deal with internal data structures, any
reading or writing account attributes controlled by DIGITAL may cause
problems in future releases.
If you have data that needs to be
manipulated or read by a significant number of programs, use one of
the other SYS calls provided.
The account attribute calls differ from the file attribute calls by
the negative value passed in byte 3 rather than a channel number of an
open file.

7-74

Read File Attributes
FO=-25
Read File Attributes
Data Paf;sed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(-25%), the read/write attributes code.

CHR$(N%), where N% is the channel number on which the file
is open.

CHR$(O%), to specify read.

5-30

Reserved; should be O.

Data Returned
Bytes
I

Meaning
Current job number times 2.

2-4

Not used.

5-26

File attribute data.
contain nulls*.

27-30

Name of run-time system under which file was created, in
Radix-50 format.

If file has no attributes, all bytes

* To determine the number of attributes returned, scan backwards from
byte 26 (in words) to find the first word that is not null.
Then
calculate the number of attributes returned.
If all the words are
null, no attributes were returned.
privileges Required
None.

7-75

Read File Attributes
FO=-25

Possible Errors
ERR Value

Meaning
?I/O CHANNEL NOT OPEN
Channel specified in byte 3 must have file open.

?PROTECTION VIOLATION
Job does not have read access to the file, or the
channel is open on a UFD.
(UFDs do not have
attributes.)

?DEVICE NOT FILE STRUCTURED
Device on which file is open must be disk.

?ILLEGAL I/O CHANNEL
Attributes can be accessed only on channels 1
through 15.

7-76

Write File Attributes
FO=-25

write File Attributes
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(-25%), the read/write attributes code.

CHR$(N%), where N% is the channel number on which file is
open.
(You must have write access on the open channel.)

CHR$(N%), where N% is the number of words to write
(l<=N<=ll).

5-26

The attiibute data to write, 2 bytes per attribute.

27-30

Reserved; should be O.

D1ata Returned
None.
Privileges Required
None.
PossiblE~

Errors
Meaning

ERR Value

?NO ROOM FOR USER ON DEVICE
The UFD of the account is full. Some files must be
deleted to free entries for attributes.

?I/O CHANNEL NOT OPEN
Channel specified in byte 3 must have file open.

?PROTECTION VIOLATION
Job does not have write access to the file open on
channel, or the channel is open on a UFD.
(UFDs do
not have attributes.)

?DEVICE NOT FILE STRUCTURED
Device on which file is open must be disk.

7-77

Write File Attributes
FO=-25

?ILLEGAL BYTE COUNT FOR I/O
No more than 11 can be specified in byte 4.

?ILLEGAL I/O CHANNEL
Attributes can be accessed only on channels 1
through 15.

Note
DIGITAL-supplied software depends on file attribute
data defined by the system.
User-written software
must not write attribute data that conflicts with
system-defined attribute data.

7-78

Read Pack Attributes
FO=-25

Read Pack Attributes
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(-2s%), the read/write attributes code.

CHR$(-4%), the code to read pack attributes.

4-22

Reserved; should be O.

23-26+

The name and unit number of the disk device whose attributes
are to be returned.

27-30

Reserved; should be O.

Data Returned
Bytes

Meaning

1-6

Not used.

7-8

starting device cluster number of the MFD.

9-10

Pack revision level.

Pack cluster size.

Not used.

13-14

Pack status/flags.

See the Discussion.

15-18

Pack ID, in Radix-SO format.

19-20

Size of disk in device cluster numbers.

Device cluster size.

o if disk is not system disk; 1 if disk is system disk.

23-24

UNTCNT for the disk.

7-79

Read Pack Attributes
FO=-25

25-26

Reserved for special applications.

27-28

Number of free device clusters.

29-30

Not used.

Privileges Required
DEVICE

Access a restricted disk

Possible Errors
Meaning

ERR Value

?NOT A VALID DEVICE
Device specified is not a valid device.

?DEVICE NOT FILE STRUCTURED
Device specified is not a logically mounted disk.

Discussion
This call returns information about mounted disks.
You can use it to
obtain the characteristics of a disk and the drive on which the disk
is mounted.
The following are the defined bits returned in the pack status/flags:
Bit

Value

9
11
12
14

512%
2048%
4096%
16384%

Meaning
Pack
Pack
Pack
Pack

is
is
is
is

initialized "new files first"
initialized to maintain date of last write
initialized as a read-only pack
initialized as a private/system disk

All other values are reserved.

7-80

Read Account Attributes
FO=-25

Read Account Attributes
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(-25%), the read/write attributes code.

CHR$(-l%), the read account attributes subfunction code.

CHR$(N%), where N% is the attribute type code for the
account to be accessed.
The following values are the
currently defined attribute type codes:
Value
0%
1%
2%
3%
4%
5%
6%

Meaning
Lookup by index
Quotas
Authorized privilege mask
Password
Date/time information
Name~ entry
Nondisk quotas

You may also use type codes in the customer-defined range
(128-255).
5-6

PPN of the account to be accessed.

7-8

CHR$(I%)+CHR$(SWAP%(I%)), where I% is the index number of
the account to read. Used only if byte 4 is 0; otherwise,
O. An index of 0 returns the account's accounting data.

9-22

Reserved; should be O.

23-26+

The name and unit number of the disk device where the
account resides.

27-30

Reserved; should be O.

7-81

Read Account Attributes
FO=-25

Data Returned
Meaning

Bytes
1-6

Not used.

7-20

Account attribute data.
The first byte contains the
attribute type code, as passed in byte 4_
If byte 4 is 0,
the first byte returns the type code of the attribute found.
The remaining 13 bytes contain the actual attribute data.
See the Discussion for a description of the 13 data bytes of
attribute codes 1, 2, and 4.

21-30

Not used.

Privileges Required
None

Read attributes 1, 2, and 4-191 in your own account.
That
is, you can read all DIGITAL-defined attributes except
password as well as the first 64 user-defined attributes
(128-191).

GACNT or
GREAD

Read all attributes in group accounts.

WACNT or
WREAD

Read all attributes in all accounts.

Possible Errors
The following error messages are possible with the read, write, and
delete account attributes subfunctions of this call.
Meaning

ERR Value

?CAN'T FIND FILE OR ACCOUNT
The account you specified does not exist.

?NOT A VALID DEVICE
The device you specified does not exist.

?PROTECTION VIOLATION
You do not have sufficient privilege to perform the
specified subfunction.

?DISK PACK IS NOT MOUNTED
The disk you specified is not mounted.

7-82

Read Account Attributes
FO=-25

?DEVICE NOT FILE STRUCTURED
The device on which the file is open must be a disk.

The following error message can only occur with the read account
attributes subfunction:
?END OF FILE ON DEVICE
The attribute you specified was not found.
If you
specified a lookup by index, the index is greater
than the number of attributes.

Discussi.on
This call searches for the specified attribute type and returns the
data as 7 words, beginning in byte 7.
The first byte is the type
code; the remaining 13 bytes are the actual attribute data.
You can also specify a search by index number by passing a value of 0
in byte 4.
This type of search enables programs like BACKUP to read
all the account attributes without trying each of the 255 possible
type codes.
The program can issue successive calls, incrementing the
index value by 1 each time.
The layouts of the data returned in bytes 7-20 for attribute type
codes 1, 2, 4, and 6 are listed below.
The data shown is considered
internal information and is subject to change without notice.
Type 1

Quota information
Byte
7
8

9-10
11-12
13
14
15
16
17-18
19-20

Meaning
1, the attribute type code
Detached job quota
Logged-out quota (L5B)
Logged-in quota (L5B)
Logged-in quota (MSB)
Logged-out quota (MSB)
Reserved
Current usage (MSB)
Reserved
Current usage (LSB)

7-83

Read Account Attributes
FO=-25

Type 2

Authorized privilege mask
Byte
7

8
9-16
17-20

Type 4

Meaning
2, the attribute type code
Reserved
Authorized privilege mask
Reserved

Date/time information
Byte
7
8
9-10
11-12
13-14
15-16
17-18
19-20

Meaning
4, the attribute type code
Keyboard of last login ( -1 if last login was
detached)
Date of last login, in RSTS/E internal format
Time of last login, in RSTS/E internal format
in bottom 11 bits.
Flags in high 5 bits.
Date of last password change
Time of last password change, in bottom 11
bits.
Flags in high 5 bits.
Date of account creation
Expiration date ( -1 if no expiration)

Flags in bytes 11-12 are:
2048%
Others

No password is required to log in to this account
Reserved

Flags in bytes 15-16 are:
2048%
4096%
8192%
16384%
32767%+1%
Type 6

Password cannot be looked up
No dialup logins allowed
No network logins allowed
No interactive logins allowed (spawn
and batch only)
Captive account

Nondisk quotas
Byte
7

8
9-10
11-12
13-20

Meaning
6, the attribute type code
Total job quota
RIB quota
Message quota
Reserved

7-84

write Account Attributes
FO=-25

Write Account Attributes
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(-25%), the read/write attributes code.

CHR$(-2%), the write account attributes subfunction code.

CHR$(N%), where N% is the attribute type code for the
account to be accessed. Values for attribute type codes
are:
Value
0%
1%
2%
3%
4%
5%
6%

Meaning
Accounting Data
Quotas
Authorized privilege mask
Password
Date/time information
Name entry
Nondisk quotas

You may also use type codes in the customer-defined range
(128-255).
5-6

PPN of the account to be accessed.

7-20

The new account attribute data. The first byte contains the
attribute type code. The remaining bytes contain the actual
attribute data. See the Discussion for a description of the
13 data bytes of attribute codes 1, 2, and 4.

21-22

Reserved; should be O.

23-26+

The name and unit number of the disk device where the
account resides.

27-30

Reserved; should be

Data Returned

7-85

write Account Attributes
FO=-25

Privileges Required

GACNT

write attributes for accounts in the group

WACNT

write attributes for all accounts

Possible Errors

In addition to the general error messages listed in the read account
attributes subfunction, this call returns the following errors:
ERR value

Meaning
?NO ROOM FOR USER ON DEVICE
The attribute block does not exist yet, and it
cannot be added because the directory is full.
?PROTECTION VIOLATION
You do not have sufficient privilege to perform this
subfunction, or the disk you specified is
write-locked.

Discussion

This call searches for the attribute type code you specify in byte 4.
If no match is found, it attempts to allocate a new directory entry to
hold the new attribute. Next, it writes the data passed in bytes 7-20
into the attribute block. See the Discussion in the previous
subfunction, "Read Account Attributes," for a description of the data
passed in bytes 7-20.
This call writes the data exactly as passed, with two exceptions:
o

Authorized privilege mask (attribute type 2) -- When writing
the mask, the call ignores any attempt to turn on privilege
bits if the caller does not have the corresponding privilege
currently in effect. This applies only to attempts to change
a bit from OFF to ON. Writing a bit as ON is allowed without
checking if it was ON already.

Date/time information (attribute type 4) -- The last login
fields are always left alone. This ensures that any logins
to an account leave a trace that cannot easily be altered.

7-86

Delete Account Attributes
FO=-25

Delete Account Attributes
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(-25%), the read/write attributes code.

CHR$(-3%), the delete account attributes subfunction code.

CHR$(N%), where N% is the attribute type code for the
account to be accessed. Values for attribute type codes are
limited to those in the customer defined range (128 to 255).

5-6

PPN of the account to be accessed.

7-22

Reserved; should be O.

23-26+

The name and unit number of the disk device where the
account resides.

27-30

Reserved; should be O.

Data Returned
No meaningful data is returned.
privileges Required
GACNT

Delete attributes for accounts in the group

WACNT

Delete attributes for all accounts

Possible Errors
In addition to the general error messages listed in the read account
attributes subfunction, this call returns the following errors:
ERR Value

Meaning
?PROTECTION VIOLATION
You do not have sufficient privilege to perform this
subfunction; or the disk you specified is
write-locked; or you attempted to delete attributes
in the DIGITAL reserved attribute type range.
7-87

Delete Account Attributes
FO=-25

?END OF FILE ON DEVICE
The attribute you specified was not found.

Discussion
This subfunction deletes an attribute block for a specified account.
It searches for the attribute type specified in byte 4.
If found, the
attribute block is deleted. This call applies only to attribute type
codes in the customer defined range (128 to 255).

7-88

Add/Delete CCL Command
FO=-24
(UU. eeL)
Add/Delete eCL Command
Data Passed
To add a CCL command, specify the bytes described below.
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(-24%), the code to add/delete CCL.

CHR$(O%), to add a CCL command.

CHR$(U%), where U% is the number of unique characters in the
command.
U% must be between 1 and the length of the
command.
This defines the abbreviation point.

5-6

PPN u.nder which program to run is stored.

7-10

File name/I in Radix-50 format, of the program to run.

11-12

File type)1

13-21

CCL command; from 1 to 9 ASCII characters padded with NUL
characters.

in Radix-50 format, of the program to run.

Must be CHR$(O%).

23-24

Name of device on which program to run is stored;. must be
disk.

Device unit number if byte 26 is 255.

If this byte is 255, the value specified in byte 25 is the
explicitly specified unit number.

27-28

Line numbE~r at which to start program (add 32767% + 1% to
keep privileges).

29-30

Reserved; should be O.

7-89

Add/Delete eCL Command
FO=-24

To delete a CCL command, specify the bytes described below.
Meaning

Bytes
1

CHR$(6%}, the SYS call to FIP.

CHR$(-24%}, the code to add/delete eCL.

CHR$(-2%} to delete a CCL command.

CHR$(U%}, where U% is the number of unique characters in the
command.
U% must be between 1 and the length of the command
and defines its abbreviation point.

5-12

Reserved; should be O.

13-21

CCL command to delete.

22-30

Reserved; should be O.

Data Returned
No meaningful data is returned.
Privileges Required
INSTAL
Possible Errors
Meaning

ERR Value

For the add CCL call:
?ILLEGAL FILE NAME
The CCL command being added either begins with a
number or contains an otherwise unacceptable
character.

?ACCOUNT OR DEVICE IN USE
The CCL command being added is already defined.

For the delete CCL call:
?CAN'T FIND FILE OR ACCOUNT
The CCL command specified does not exist.

7-90

Add/Delete

ceL Command
FO=-24

Discussion
This call adds and deletes CCL commands.
Chapter 10 of this manual
describes the operation and design of CCL commands.
The command can be a string from one to nine characters long.
The
a.llowed single-character commands are A through z, the at sign (@)
character, the dollar sign ($) character, and the number sign (#)
character.
For commands longer than one character, the string must
begin with a letter, and the remaining characters can be letters or
digits.
The command cannot begin with a numeric character because
BASIC-PLUS interprets digits at the beginning of a line as a line
number, not a command.
Commands have an abbreviation point after the first character.
The
abbreviation point is specified by the value in byte 4.
If you
specify an abbreviation point that equals the number of characters in
the command, the command cannot be abbreviated. An example of an
abbreviated CCL command is DIR (the abbreviation point follows the R),
which uniquely defines the CCL command DIRECTORY. Any of the
following abbreviations are also valid:
DIR, DIRE, DIREC, DIRECT,
DIRECTO, DIRECTOR, and DIRECTORY.
If the abbreviation point for
DIRECTORY follows the Y, then no abbreviation is valid.
Because of the way RSTS/E interprets CCL commands, you must make sure
that you define similar commands in the correct order.
For example,
you must define MACRO before MAC.
See the RSTS/E System Manager's
Guide for more infor.mation about defining CCL commands.

7-91

Set Special Run Priority
FO=-22
( • SET)
Set Special Run Priority
Data Passed

Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(-22%), the code to set special run priority.

3-30

Reserved; should be O.

Data Returned

No meaningful data is returned.
Privileges Required

TUNE
Possible Errors

None.
Discussion

This SYS call sets the special run priority bit in the job priority
word. This action raises the priority of the job slightly above that
of other jobs in its priority class. The priority bit is cleared
whenever the job returns to the job keyboard monitor or whenever a
program chains to another program. Thus, an appropriately privileged
job can raise its priority without protecting against a user typing
CTRL/C and retaining the higher priority.

7-92

DropjRegain Temporary Privileges
FO=-21
( • SET/. CLEAR)
Drop/Regain Temporar.y Privileges
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(-2l%), the code to drop temporary privileges.

If you do not specify a value, the call permanently drops
temporary privileges. Otherwise, CHR$(N%), where N% means
either of the following:
255% Temporarily drop temporary privileges.
0% Regain temporary privileges dropped by 255% value.

4-30

Reserved; should be O.

Data Re'turned
No meaningful data is returned.

Privileges Required
None.

Possible Errors
None.

I)iscussion
This call allows a program to selectively use temporary privileges.
(See Chapter 1 for a description of temporary privileges.)
This call allows a program to activate temporary privileges for
sections of code where they are needed, but take advantage of built in
monitor protections (such as protection code arbitration) elsewhere.
The call does not affect the permanent privileges of an account.
Good programming practice suggests two general approaches to using and
controlling temporary privilege.
If temporary privilege is required
only for some initial set-up, the program can concentrate the code
requiring privilege "up front" and then drop temporary privileges
7-93

Drop/Regain Temporary Privileges
FO=-21
permanently. The remainder of the program can then rely on the
monitor's built-in protection, appropriate to the account the program
is running in.
The following sample code illustrates this approach:
10

V$ = SYS(CHR$(6%) + CHR$(-22%))
!SET SPECIAL RUN PRIORITY - THIS REQUIRES PRIVILEGE

OPEN "$SYSTEM.FIL" FOR INPUT AS FILE 1%, MODE 8192%
!OPEN A "REFERENCE" FILE, REGARDLESS OF PROTECTION
!(USING READ-ONLY MODE, OFTEN GOOD PRACTICE, ALSO)

V$ = SYS(CHR$(6%) + CHR$(-2l%))
!HAVING DONE THE NECESSARY SET-UP, DROP TEMPORARY
!PRIVILEGES FOR THE REMAINDER OF THE PROGRAM

A different approach is appropriate when a program needs temporary
privileges at several points during execution"
In this case, good
programming practice suggests that temporary privileges be dropped
early, and then regained just long enough to be used where needed.
The following sample code illustrates this approach.
(This sample
uses line numbers appropriate for a program designed to be invoked by
CCL.
See Chapter 10 for more information on these conventions.)
1
2

30000

EXTEND
PRINT '?PLEASE USE THE "xxxxx" CCL COMMAND'
GOTO 32767 !DISALLOW SOMEONE INVOKING THE PROGRAM BY RUN

!CONVENTIONAL CCL ENTRY POINT
DROP.PRIVILEGES$ = CHR$(6%) + CHR$(-21%) + CHR$(255%)
!COMPOSE THE "DROP PRIVILEGES" CALL STRING

V$ = SYS(DROP.PRIVILEGES$)
!GO AHEAD AND DROP THEM, FIRST THING

REGAIN.PRIVILEGES$ = CHR$(6%) + CHR$(-2l%) + CHR$(O%)
!COMPOSE THE "REGAIN PRIVILEGES" CALL STRING,
!FOR LATER USE
(FOLLOWING CODE CAN NOW EXECUTE
WITHOUT PRIVILEGE)
!NOW, YOU REACH A POINT WHERE PRIVILEGE IS REQUIRED
!(OPEN A PROTECTED FILE)

7-94

Drop/Regain Temporary Privileges
FO=-21

\
\
\

V$ = SYS(REGAIN.PRIVILEGES$) !GET PRIVILEGES TEMPORARILY
OPEN "$SYSTEM.FIL" FOR INPUT AS FILE 1%, MODE 8192%
!OPEN A "REFERENCE" FILE, REGARDLESS OF PROTECTION
!(USING READ-ONLY MODE, OFTEN GOOD PRACTICE, ALSO)
V$ = SYS(DROP.PRIVILEGES$) !AND DROP PRIVILEGES AGAIN
(AND SIMILARLY FOR OTHER OPERATIONS
THROUGHOUT THE PROGRAM)

32767

END

7-95

Lock/Unlock Job in Memory
FO=-20
(.SET/.CLEAR)
Lock/Unlock Job in Memory
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(-20%), the lock/unlock a job in memory code.

CHR$(N%), where N% is 0% for lock and 255% for unlock.

4-30

Reserved; should be O.

Data Returned
No meaningful data is returned.
Privileges Required
TUNE
Possible Errors
None.
Discussion
This call prevents unnecessary swapping by forcing the job executing
the call to remain in memory.
The call performs this action without
affecting the job priority or run burst.
The call merely eliminates
the swapping time between run bursts.
You may want to use this call in a program with certain time-sensitive!
routines.
The locked time must be very short to avoid degrading
system performance. Depending on the memory configuration, a locked
job can cause fragmentation of user space and prohibit the system from
swapping any other job into memory.
If the job expands its size in
memory, the system can swap it out of memory regardless of its locked
status.

7-96

Lockjunlock Job in Memory
FO=-20
The following sample code demonstrates the lock and unlock procedure:
10

A$ - SYS(CHR$(6%) + CHR$(-20%) + CHR$(O%»
! LOCK JOB IN MEMORY

100 A$ = SYS(CHR$(6%) + CHR$(-20%) + CHR$(255%»
! UNLOCK JOB FROM MEMORY

7-97

set Logins
F 0 =-19

( UU • LOG)

set Logins
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(-19%), the set logins code.

CHR$(N%), where N% is the number of logged in jobs to allow.

4-30

Reserved; should be O.

Data Returned
Meaning

Bytes
1

The current job number times 2.

Not used.

CHR$(N%), where N% is the actual number of logins set.

4-30

Not used.

Privileges Required
SWCTL
Possible Errors
None.
Discussion
This call sets the number of allowable logins to the number specified
in byte 3. A value of 0 sets the number of allowed jobs to 1.
The
,upper limit for the number of logins is either the system JOB MAX or
the number of jobs that can currently be swapped, whichever is lower.
If you specify a larger value, the system sets the number of logins to
the upper limit.
You do not receive an error.

7-98

Set Logins
FO=-19

The number of jobs that can log in to a RSTS/E system is limited by
the swapping space available, the JOB MAX set at system start-up, and
the set maximum number of logins.
However, console terminal KBO: is a
special terminal that can log in regardless of the set login maximum,
provided that swapping space and JOB MAX permit.
The system manager
can install a patch that changes the number of the special keyboard
from KBO: to some other keyboard.

7-99

Manipulate RTS, Resident Library, Dynamic Region
FO=-18
(UU.RTS)
Manipulate Run-Time System, Resident Library, Dynamic Region
This call has the following subfunctions:
0

Add Run-Time System

Remove Run-Time System

Unload Run-Time System

Add Resident Library

Remove Resident Library

Unload Resident Library

Create Dynamic Region

Add a Run-Time System
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(-18%), the run-time system manipulation code.

CHR$(N%), where N% is:
0%

Use va1u~s for all bytes as specified in this
call.

128%

Use values defined in the .RTS file for bytes
13-14, 15-16, 19-20, and 21-22.

Reserved; should be O.

5-6+

PPN of the file to add; if none is specified, [0,1] is the
default.

7-10+

Run-time system name in Radix-50 format.

11-12

CHR$(A%)+CHR$(SWAP%(A%», where A% is the 1K-word section of
memory at which this run-time system is to be loaded.
The
numbering begins at 0 and ends at n-1 (where n is the total
number of 1K-word sections of memory on the system).
7-100

Add a Run-T ime Sys tem

FO=-18
If A% is 0% and the run-time system requires a fixed address
(read/write or /STAY run-time system), the monitor finds the
address progressing from high to low memory. Otherwise, the
monitor uses an area of memo~y calculated when the run-time
system is actually needed.
If A% is -1%, the monitor calculates a fixed address,
regardless of whether or not the run-time system requires
one.
13-14

Maximum allowed user image size, in K words (the P.SIZE
symbol).
If byte 3 is 128%, these bytes are ignored.

15-16

Minimum allowed user image size, in K words (the P.MSIZ
symbol).
If byte 3 is 128%, these bytes are ignored.

CHR$(P%), where P% is the position in the linked list of
run-time system (RTS) description blocks to place the
description block for this run-time system.
If P% is 1%,
the call places the description block immediately after that
of the primary RTS.
If P% is a nonzero value less than or
equal to the number of blocks currently in the li~t, the
call places this new block in that position following the
primary RTS block.
If P% is 0% or a value greater than the
number of blocks currently in the list, the call places this
new block at the end of the list.

CHR$(S%), where S% is the stay flag.
If S% is 128% (the
high bit is set), this RTS is kept permanently resident.
If
S% is 0%, the memory occupied by this RTS can be released as
user job space whenever the usage count of the RTS goes to

O.
19-20

CHR$(F%) + CHR$(SWAP%(F%», where F% is a flag word whose
bits define this run-time system's characteristics.
If byte
3 is 128%, these bytes are ignored.
Only the high byte is
used for flag bits.
F% is the sum of the bits set as
follows:
Value

Meaning

256%

This RTS is a keyboard monitor.

512%

This RTS handles only one user; that is, it is not
shared by multiple users.

1024%

This RTS allows read and write access to its
memory rather than read-only access~

2048%

Errors that occur under the control of this RTS
should not be recorded in the system error log.
7-101

Add a Run-T irne Sys tern
FO=-lB

4096%

This RTS should be immediately removed from memory
when its usage count goes to O.

8192%

The monitor computes the proper job image size (in
K words) for any program running under this RTS as
(file-size+3)/4.

16384%

Reserved; should be

32767%+1% This RTS emulates trap instructions by using a
special EMT prefix.
If this characteristic is
specified, the EMT prefix code is in the low byte
(0 < code < 255).
21-22

The normal executable file type, in Radix-50 format, for
this run-time system (the P.DEXT symbol).
If byte 3 is
128%, the call ignores these bytes.

23-24+

Name of the device (must be disk) on which the run-time
system file is stored.
If you do not specify a name, the
call uses SY:.

25+

unit number.

26+

unit number flag.

27-30

Reserved; should be O.

Data Returned
No meaningful data is returned.

Privileges Required
INSTAL

Possible Errors
Meaning

ERR Value

?NO ROOM FOR USER ON DEVICE
If the monitor were to load this run-time system at
the address specified in bytes 11 and 12, memory
would be fragmented and a swapping violation would
occur.
See the discussion of assigning and
allocating memory in the RSTS/E System Installation
and Update Guide for guidelines on how to avoid
fragmenting memory.

7-102

Add a Run-T ime Sys tem
FO=-18

This error can also occur when the monitor attempts
to determine the address assignment but cannot find
any valid load address due to lack of memory.
?CAN'T FIND FILE OR ACCOUNT
A file with the name specified in bytes 7 through 10
and a file type of .RTS cannot be found in the
account and device specified in this call (bytes 5-6
and bytes 23-26).

?PROTECTION VIOLATION
The file to be added as the run-time system has a
bad format.
For example, the file is not contiguous
or has illegal entries in the SIL index.

?NAME OR ACCOUNT NOW EXISTS
A run-time system with the same name currently
exists.

?ILLEGAL BYTE COUNT FOR I/O
The range of memory starting at the load address
given in bytes 11 and 12 is not available.
See the
SYSTAT memory status report to select an available
range of memory.

?NO BUFFER SPACE AVAILABLE
Adding a run-time system description block requires
a small buffer and one is not currently available.

Discussion
This SYS function adds a run-time system description block to the
linked list of blocks in the monitor. Run-time systems other than the
primary run-time system (RSX) and the default keyboard monitor (DCL)
are transient from one time-sharing session to another.
Thus, systems
that offer auxiliary run-time systems must define them for each
time-sharing session.

7-103

Remove a Run-T ime Sys tem
FO=-18

Remove a Run-Time System
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(-18%), the run-time system manipulation code.

CHR$(4%), remove run-time system.

4-6

Reserved; should be O.

7-10+

Run-time system name in Radix-50 format.

11-30

Reserved; should be O.

Data Returned
No meaningful data is returned.
Privileges Required
INSTAL
Possible Errors
Meaning

ERR Value

?ACCOUNT OR DEVICE IN USE
This run-time system is currently being loaded into
memory or is resident and in use.
It cannot be
removed until usage count is O.

?CAN'T FIND FILE OR ACCOUNT
The run-time system specified in bytes 7 through 10
is not currently defined.

?PROTECTION VIOLATION
The run-time system specified in bytes 7 through 10
is the primary RTS or the system default keyboard
monitor and cannot be removed by this call.

7-104

Remove a Run-Time System
FO=-18

Discussion

This call removes a run-time system from memory, deletes the monitor
structure that defines this run-time system, and closes the run-time
system file. The SHUTUP system program automatically performs these
actions when it terminates time-sharing operations.

7-105

Unload a Run-Time System
FO=-18

Unload a Run-T ime Sys tem
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(-18%), the run-time system manipulation code.

CHR$(6%), unload run-time system.

4-6

Reserved; should be O.

7-10+

Run-time system name in Radix-50 format.

11-30

Reserved; should be

Data Returned
No meaningful data is returned.
Privileges Required
INSTAL
Possible Errors
Meaning

ERR Value

?ACCOUNT OR DEVICE IN USE
The run-time system specified in bytes 7 through 10
is currently being loaded into memory or is resident
and in use by the job that is currently running.
It
cannot be unloaded now; a later attempt might
succeed.

?CAN'T FIND FILE OR ACCOUNT
Th~ run-time system specified in bytes 7 through 10
is not currently defined.

7-106

Unload a Run-Time System
FO=-18

Discussion
This call frees the portion of memory occupied by the run-time system.
The memory is made available as user job space. The run-time system
will be loaded again when it is needed. This function is valid for
the primary run-time system, in which case it simply causes the
run-time system to be re-read from disk. In all other cases, the
unload function also clears the "stay" flag set when the run-time
system was last added or loaded.

7-107

Add a Resident Library
FO=-18

Add a Resident Library
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(-18%), the resident library manipulation code.

CHR$(16%), add a resident library.

Reserved; should be O.

5-6+

The PPN of the file to add; if none is specified, [0,1] is
the default.

7-10+

The resident library name in Radix-50 format.

11-12

CHR$(A%)+CHR$(SWAP%(A%», where A% is the 1K-word section of
memory at which the resident library is to be loaded.
The
numbering begins at the first available 1K-word section and
ends at n-1 (where n is the total number of of 1K-word
sections of memory on the system).
If A% is 0% and the library requires a fixed address
(read/write or /STAY library), the monitor finds the address
progressing from high to low memory. Otherwise, the monitor
uses an area of memory calculated when the library is
actually needed.
See the Discussion for restrictions on
specifying A%=O%.
If A% is -1%, the monitor finds the first free space large
enough to hold the resident library, starting from the top
of memory.

13-17

Reserved; should be O.

CHR$(S%), where S% is the stay flag.
following values:
Value
0%

128%

S% can be one of the

Meaning
The memory occupied by this library can be freed
for user job space whenever the usage count of the
RTS is 0 (no active task is accessing the
library) .
The library is made permanently resident.

7-108

Add a Resident Library
FO=-lB

19-20

CHR$(F%)+CHR$(SWAP%(F%)), where F% is the flag word that
defines the characteristics of the library. Only the high
byte is used for flag bits. F% is the sum of the bits set,
as follows:
Value

Meaning

256%

Reserved; should be O.

512%

The resident library is available to only one
user. It is not shared by multiple users.

1024%

The resident library allows read/write access
to its memory, rather than read- only access.

2048%

The resident library does not record errors
in its code in the system error log.

4096%

The resident library is immediately removed
from memory when its usage count equals zero.

8192%

Reserved; should be O.

16384%

Reserved; should be O.

32767%+1%

Reserved; should be O.

21-22+

Protection code for the installed resident library. To
specify a protection code, place a nonzero value in byte 21
and the protection code in byte 22. To accept the default
protection, specify 0 in byte 218 The default protection
code is 42, which means that the monitor grants read access
to all users but denies write access.

23-24+

The name of the disk device on which the resident library is
to be stored. If no name is specified, SY: is used.

25+

unit number.

26+

unit number flag-

27-30

Reserved; should be O.

D,ata Returned
No meaningfUl data is returned.

7-109

Add a Resident Library
FO=-18

Privileges Required
INSTAL
possible Errors
Meaning

ERR Value

?NO ROOM FOR USER ON DEVICE
You specified an address in bytes 11 and 12 that
would cause the monitor to load the library so that
memory would be fragmented and a swapping violation
would occur.
See the RSTS/E System Installation and
Update Guide for guidelines on avoiding memory
fragmentation.

This error can also occur when the monitor attempts
to determine the address assignment but cannot find
any valid load address due to lack of memory.
?CAN'T FIND FILE OR ACCOUNT
You specified a file name in bytes 7 through 10 that
cannot be found in the account specified in bytes 5
and 6 on the device specified in bytes 23 through
26.
Make sure that the file name you specify has a
.LIB file type and is located in the specified
account and device.

?PROTECTION VIOLATION
The file you want to add is in improper format.
For
example, this error occurs if you specify a file
that is not contiguous or has illegal entries in the
SIL index.

?NAME OR ACCOUNT NOW EXISTS
You specified the file name of a
that already exists.

16
resid~nt

library

?ILLEGAL BYTE COUNT FOR I/O
You did not specify a load address in bytes 11 and
12 or the address you specified is not available.
Refer to the memory status report of a display
program to determine an available range of memory.

?NO BUFFER SPACE AVAILABLE
A small buffer is required for the description block
of an added resident library.
This error is
returned if a small buffer is not available.

7-110

Add a Resident Library
FO=-18

Discussion
This SYS call adds Ci specified library to the monitor's list of
resident libraries.
This call is similar to that used to add a
run-time system.
If you specify a value of -1 in bytes 11-12, the monitor automatically
decides where to load the resident library, finding the first free
space large enough to hold the library, starting from the top of
memory.
The library file does not have to reside in account [0,1];
however, the file type must be .LIB.
If you specify a value of 0 in bytes 11-12, and you add the library
neither read/write nor /STAY, the monitor calculates an address for
the library when it is actually needed.
This type of library has the
following restrictions:
o

Only 1 such resident library may be mapped by a program at
any time

A program mapping to the library must be running under the

NULL run-time system.
o

The maximum size of the library is 28K words.

The start address for mapping the library may not be any
higher than:
32K - (sizE~ of library rounded up to the next highest 4K
boundary)

See the RSTS/E Task Builder Reference Manual for more information on
creating and using resident libraries.

7-111

Remove a Resident Library
FO=-18

Remove a Resident Library
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(-18%), the resident library manipulation code.

CHR$(20%), remove a resident library.

4-6

Reserved; should be O.

7-10+

The resident library name in Radix-50 format.

11-30

Reserved; should be O.

Data Returned
No meaningful data is returned.
Privileges Required
INSTAL
Possible Errors
Meaning

ERR Value

?ACCOUNT OR DEVICE IN USE
You attempted to remove a library that is being
loaded into memory or is in use by the currently
running job. A resident library cannot be removed
while a job is still attached to it.

?CAN'T FIND FILE OR ACCOUNT
You specified a resident library name in bytes 7
through 10 that is not currently defined.

Discussion
This SYS call removes a library from physical memory, deletes the
monitor structure that defines the library, and closes the library
file.

7-112

Unload a Resident Library
FO=-l8
Unload a Resident Library
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(-18%), the resident library manipulation code.

CHR$(22%), to unload a resident library.

4-6

Reserved; should be O.

7-10+

The resident library name in Radix-50 format.

11-30

Reserved; should be O.

Data Returned
No meaningful data is returned.
Privileges Required
INSTAL
Possible Errors
Meaning

ERR Value

?ACCOUNT OR DEVICE IN USE
You attempted to unload a resident library that is
in the process of being loaded or is in use by the
currently running job. A library cannot be unloaded
while a job is still attached to it.

?CAN'T FIND FILE OR ACCOUNT
You specified an undefined resident library name in
bytes 7 through 10.

Discussion
This SYS call removes a library from memory and frees that portion of
memory for use by other jobs.
The system reloads the library when it
is needed.
If the "stay" flag has been set by a previous add or load
function, the call clears it.

7-113

create Dynamic Region
FO=-18
create Dynamic Region
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(-18%), the run-time system manipulation code.

CHR$(24%), create dynamic region.

4-6

Reserved; should be O.

7-10+

Region name in Radix-50 format.
If zero is passed, this
creates an unnamed dynamic region.
See Discussion for
information on unnamed dynamic regions.

11-12

CHR$(A%)+CHR$(SWAP%(A%)), where A% is the IK-word section of:
memory at which this dynamic region is to be loaded~
The
numbering begins at 0 and ends at n-1 (where n is the total
number of 1K-word sections of memory on the system).
If A%
is 0%, the monitor finds the first free space large enough
to hold the region, starting from the top of memory_

Size of region in K-words, between 1 and 127 K.
If you
include a value of 128%, the monitor creates the region even
if the full amount of memory requested is not available.

14-16

Reserved; should be O.

CHR$(N%), where N% can be:
0%
128%

128%

Delete region when all users detach.
Do not delete region when all users detach.

CHR$(N%)+CHR$(SWAP%(N%)), where N% can be:
0%
512%

Attach job to region.

CHR$(N%), where N% can be:
0%

19-20

Do not attach job to region.

The region can be shared.
The region cannot be shared.

Protection code flag.

If set, the protection code is real.
7-114

Create Dynamic Region
FO=-18

Protection code of region.

23-30

Reserved; should be zero.

Data Returned
Bytes

M.eaning

5-6

Region 10.

Size of the created region, in K words.

Privileges Required
INSTAL
Possible Errors
ERR Value

Meaning
?NO ROOM FOR USER ON DEVICE
If loaded at the address specified, memory would be
fragmented and a swapping violation would occur.
If
the monitor is choosing the address, there is not
enough free memory to create the region.

?NAME OR ACCOUNT NOW EXISTS
You specified a name of a dynamic region or resident
library that already exists.

?ILLEGAL BYTE COUNT ~"OR I/O
You attempted to create a region of invalid size.
Also, if the caller specified a load address, the
load address was not valid.

?NO BUFF1!:R SPACE AVAILABLE
A small buffer was not available for the region
description block. Also, if attachment was
specified, a small buffer was not available for the
window descriptor block.

7-115

Create Dynamic Region
FO=-18

Protection code of region.

23-30

Reserved; should be zero.

Data Returned
M,eaning

Bytes
5-6

Region 10.

Size of the created region, in K words.

Privileges Required
INSTAL
Possible Errors
ERR Value

?NAME OR ACCOUNT NOW EXISTS
You specified a name of a dynamic region or resident
library that already exists.

?ILLEGAL BYTE COUNT FOR I/O
You attempted to create a region of invalid size.
Also, if the caller specified a load address, the
load address was not valid.

?NO BUFFER SPACE AVAILABLE
A small buffer was not available for the region
description block. Also, if attachment was
specified, a small buffer was not available for the
window descriptor block.

7-115

Create Dynamic Region
FO=-18
Discussion
A dynamic region is a portion of memory that is used to store data.
This SYS call creates a dynamic region of memory.
You can create two
types of regions:
named and unnamed.
A named dynamic region is typically used when multiple programs desire
attachment to the region.
The name of the region must be unique.
An unnamed dynamic region is used when a program wants exclusive use
of an area of memory. When the monitor detaches from an unnamed
dynamic region, it always removes the region from memory.
In
addition, the caller is automatically attached to a dynamic region on
creation.
If you specify attachment to the region or create an unnamed region,
the region ID is returned in bytes 5-6.
This region is used in
subsequent .PLAS directives.
See the RSTS/E System:Directives Manual
for more information.
Since BASIC-PLUS does not support the .PLAS
directive, only named dynamic regions are useful to BASIC-PLUS
programs.

7-116

Associate a Run-Time System with a File
FO=-17

(UU.RAM)

Associate a Run-Time System with a File
D,ata Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(-17%), the associate run-time system code.

CHR$(N%), where N% is the channel number.

4-7

Run-time system name in Radix-50 format.

is-30

Reserved; should be O.

Data Returned
No meaningful data is returned.
privileges Required
None

Specify a file with a protection code that permits write
access

GWRITE

Specify a file in any account within the group
Specify any file

SYSIO

For files in [0,*] accounts

P()ssible Errors
Meaning

ERR Value

?I/O CHANNEL NOT OPEN
The channel specified in byte 3 of the call is not
open.

?PROTECTION VIOLATION
The file open on the channel specified in byte 3 is
not a disk file, or the job executing the call does
not have write access to the file.

7-117

Associate a Run-Time System with a File
FO=-l7

Discussion
This SYS call writes the name of the run-time system given in bytes 4
through 7 to the file open on the channel specified in byte 3.
With the exception of files that are larger than 65535 blocks (see
Discussion in the section "File utility Functions, SYS -26"), every
file on RSTS/E has an associated run-time system under which it was
created. The name of the run-time system is stored in Radix-50 format
in the file's UFD accounting entry. The monitor looks at this
run-time system name only for executable files on RUN requests. This
call is used by utility programs to allow an executable file created
by another run- time system to be run under an auxiliary run-time
system supported by RSTS/E.

7-118

Shut Down System
F 0 =-16
( UU • DIE)
Shut Down System
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(-16%), the system shut down code.
Reserved; should be O.

3-30

Data Returned
No meaningful data is returned.
Privileges Required
SHUTUP
Possible Errors
See Discussion.
Discussion
This SYS call logs out the current job (as does the FIP system
function call code 5).
In addition, this call bootstraps the
initialization code after the job is logged out.
Before this SYS call can execute properly, several system conditions
must be true:
o

Only one job can be running on the system when you invoke the
SYS call.

The number of logins allowed on the system must be 1; that
is, LOGINS DISABLED.
(See Disable Further Logins, SYS -2).

No disks except the system disk can be mounted.

No files can be open on the system disk.

If all of these conditions are met, the system shuts down.
If any are
not met, any attempt to invoke this SYS call results in the error
?Illegal SYS() usage (ERR=18).
7-119

Accounting Dump
FO=-lS
(UU .ACT)
Accounting Dump
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(-15%), the accounting dump code.

3-4

Reserved; should be O.

5-6+

PPN of the account to which the system dumps the accumulated
usage data.
See Discussion.
If both bytes are zero, the data is dumped to the current
account.

7-30

Reserved; should be O.

Data Returned
No meaningful data is returned.
privileges Required
GACNT

Access any account within the group

WACNT

Access any account

Possible Errors
Meaning
?CAN'T FIND FILE OR ACCOUNT
The account specified in bytes 5 and 6 does not
exist.

ERR value

Discussion
This call allows a program to dump accumulated accounting data to the
account specified in bytes 5 and 6. This enables user-callable
utility programs to run on an account different from the account that
called them and still charge the calling account for the time
accumulated by the utility.

7-120

Accounting Dump
FO=-lS
This call forces thE~ accumulated accounting values in memory to be
written to disk.
The values in memory are zeroed.
To charge
accounting data to another user's account, do the following:
1.

Dump accounting data to the current account.
zeros the data.

This procedure

Perform processing for the account to be charged.

Dump accounting data to the account to be charged.

This procedure makes sure that only the time expended for another
account is charged to that account.

7-121

Change Date and Time
FO=-14
(UU.DAT)
Change Date and Time
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(-14%), the change date and time code.

CHR$(D%), where D% is in the required format to generate the
date by the function DATE$(D%).
See the BASIC-PLUS Language
Manual for a description of the DATE$ function.
Note that
if D% in bytes 3 and 4 is 0%, no change is made to the
current date.

CHR$(SWAP%(D%», where D% is the same value used in byte 3.
This generates the high byte of the value used by the
DATE$(O%) function.

CHR$(T%), where T% is in the required format to generate the
time by the function TIME$(T%).
See the BASIC-PLUS Language
Manual for a description of the TIME$ function.
Note that
if T% in bytes 5 and 6 is 0%, no change is made to the
current time.

CHR$(SWAP%(T%», where T% is the same value used in byte 5.
This generates the high byte of the value used by the
TIME$(O%) function.

7-30

Reserved; should be O.

Data Returned
No meaningful data is returned.
Privileges Required
DATES
Possible Errors
None.

7-122

Change Date and Time
FO=-14

Discussion
This function changes the monitor date and time of day values that are
returned by the DATE$(O%) and TIME$(O%) functions in BASIC-PLUS.
The execution of this function causes the monitor to awaken all
sleeping jobs to inform them of the date/time change.
Note that you cannot specify a date earlier than I-Mar-85.

7-1.23

Change Priority, Run Burst, and Maximum Size
FO=-l3
(UU.PRI)
Change Priority, Run Burst, and Maximum Size
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(-13%), the change priority, run burst, and maximum size
code.

CHR$(J%), where, J% is the job number affected or is 255% to·
denote the current running job.

CHR$(A%), where A% is 0% to indicate no change to the
parameter in byte 5 or is nonzero to indicate a change to
the parameter as specified in byte 5.

CHR$(P%), where P% is the value of the running priority and
ranges from -128 to +120 in steps of 8.

CHR$(A%), where A% is 0% to indicate no change to the
parameter in byte 7 or is nonzero to indicate a change to
the parameter as specified in byte 7.
See Discussion.

CHR$(R%), where R% is the run burst. R% should be a value
from 1% to 127%. When you specify a value outside this
range, the monitor sets the run burst to 6.

CHR$(A%), where A% is 0% to indicate no change to the
parameter in byte 9 or is nonzero to indicate a change to
the parameter as specified in byte 9.

CHR$(S%), where S% is the maximum size, in 1024-word units,
to which a job can expand and is between 1 and 255.
If this
value exceeds SWAP MAX, the system uses the value of SWAP
MAX.
See Discussion.

Data Returned
No meaningful data is returned.

7-124

Change Priority, Run Burst, and Maximum Size
FO=-l3

Privileges Required
TUNE
Possibl.~

Errors
Meaning

ERR Value

?ILLEGAL SYS() USAGE
The specified job number does not exist.

Discussion
This call allows a user with TUNE privilege to give a running job an
increased or decreased chance of gaining run time in relation to other
running jobs, and to determine how much CPU time the job can have if
it is compute-bound.
The CPU time is called the job's run burst.
It
is measured by the number of clock interrupts during which the job can
run if it is compute-bound.
The initial size of a job running under the BASIC-PLUS run-time system
is set to 2K words and can grow during processing to a size limited by
the value of SWAP MAX.
The system manager determines the size of SWAP
MAX.
(See the discussion of the START and DEFAULT options in the
RSTS/E System Installation and update Guide.) The maximum size to
which a job can grow can never be greater than the currently assigned
value of SWAP MAX, which should be between lK and 64K words. A job
can expand to 64K words with user 1&0 space when SWAP MAX is 64K
words.
Note that BASIC-PLUS jobs can never grow beyond 16K regardless
of the job's maximum size.
Therefore, the appropriately privileged
user has the option of limiting the size to which a BASIC-PLUS job can
grow by specifying a value for S% between 2 and the maximum of SWAP
MAX.
You must specify values for each of the variables in the parameter
string.
In the description of the data passed, the value A% before
the related parameter variable determines whether that parameter
changes or remains unchanged.
The system does not perform error checking on the data passed by the
user.
Values are used as passed even if they produce illogical
results.
For instance, if you specify a priority that is not a
multiple of 8, its value is truncated to the next lowest multiple of
8. A priority greater than 127 is considered negative.
Setting a
priority to -128 suspends that job.
The monitor does not schedule
that job to run again until its priority is set to a value other than
-128.
Setting a job's run burst to 0 causes the monitor to set the
job's run burst to 6.
Setting a compute-bound job's run burst to some
high number tends to lock out other jobs. However, you do not
7-125

Change priority, Run Burst, and Maximum Size
FO=-13

override the system maximum by setting S% to 255% or any value greater
than SWAP MAX.
The monitor uses 256 queues to schedule jobs and polls each queue in
sequential priority order.
The monitor chooses the highest priority
runnable job as the job to be run.
Thus, a high priority
compute-bound job can monopolize system resources.
The following rules apply for a job running on a pseudo keyboard:
o

The job can never lower the priority of the controlling job
below its own priority.

The job can never raise its own priority above the priority
of the controlling job. Any attempt to do so causes the
system to set both priorities to the priority of the
controlling job.

7-126

Get Monitor Tables - Part II
FO=-12

(UU.TB2)

Get Monitor Tables - Part II
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(-12%), the get monitor tables - part II code.

3-30

Reserved; should be O.

Data Returned
Bytes

Meaning

The current job number times 2.

Not used.

3-4

(FREES) - The table of free (small and large) buffer
information.

5-6

(DEVNAM)

- The device name table.

7-8

(CSRTBL)

- The CSR table of physical device addresses.

9-10

(DEVOKB)
table.

- The number of disk devices times 2 in the DEVNAM

11-12

(TTYHCT) - The number of hung terminal errors since system
start-up.

13-14

(JOBCNT) - The count of jobs currently running (low byte)
and the number of logins currently allowed (high byte).

15-16

(RTSLST) - The root link word in the linked list of run-time
system description blocks.

17-18

(ERLCTL)

- Error logging control data.

19-20

(SNDLST)

- The list of eligible message receiving jobs.

21-22

(DSKLOG)

- The disk logical table.

23-24

(DEVSYN)

- Start of synonym names in DEVNAM.

25-26

(MEMSIZ) - The word containing the size of memory physically
present on the system.
Size is in K words times 32.

7-127

Get Monitor Tables· Part II
FO=-12

27-28

(CCLLST) - The root link word in the linked list of concise
command language (CCL) description blocks.

29-30

These bytes contain a pointer to the FCBLST table.
FCBLST
contains a word, for each generated unit, that is the root
of a linked list of file control blocks (FCBs) for open
files on that unit.

Privileges Required
None.
possible Errors
None.
Discussion
The three Get Monitor Table SYS calls return to your program either an
address or a data value.
The calls are commonly used with the PEEK
function to read various system parameters and tables that give
configuration and run-time information. Because it is beyond the
scope of this manual to describe the monitor, this section only
briefly describes the information returned by the monitor table
functions.
For a description of Get Monitor Tables - Part I, see SYS
call -3.
For a description of Get Monitor Tables - Part III, see SYS
call -29.
The section "The PEEK Function" describes the use of the
PEEK function for certain convenient programming operations.
This call denotes each item of information described by a name in all
uppercase letters. This name is the same one used to identify the
information in the RSTS/E assembly listings.
If the name is in
parentheses, the information returned is an address of the data
described.
If the name is not in parentheses the information
returned is the actual data value.
For example, the Get Monitor
Tables - Part I call returns CNT.KB-l in byte 3.
The value returned
is the number of termina~ lines minus 1 configured on the system.
However, bytes 11 and 12 return (JOBTBL), the address of the table of
jobs. Use the PEEK function to inspect the address.
g

Note
All information returned by the call described in this
section is internal to RSTS/E and is subject to change
at any time.

7-128

Change File Statistics
FO=-ll
(UU. BCK)
Change File Statistics
Data Pal;sed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(-ll%), change file statistics code.

CHR$(N%), where N% is the internal channel on which the file
is open and must be between land 12, inclusive.

4-5

Date of last access to place in the file's accounting
entry*.
Specify the date as CHR$(D%)+CHR$(SWAP%(D%», where
D% is in the form required by the BASIC-PLUS DATE$(D%)
function.
(See the sample program in the Discussion.)

6-7

Date of creation to place in the file's accounting entry.
Specify the date as CHR$(D%)+CHR$(SWAP%(D%», where D% is in
the form required by the BASIC-PLUS DATE$(D%) function.
(See the sample program in the Discussion.)

8-9

Time of creation to place in the file's accounting entry.
Specify the time as CHR$(T%)+CHR$(SWAP%(T%», where T% is in
the form required by the BASIC-PLUS TIME$(T%) function.
(See the sample program in the Discussion.)

10-30

Reserved; should be O.

*The DSKINT initialization option or the INITIALIZE command can
change the meaning of date of last access to date of last
modification for some disks.
The SHOW DISK command tells which
disks record the date of last modification.
Data Returned
No meaningful data is returned.
Privileges Required
DATES

Modify date of last access (other fields require no
privilege)

7-129

Change File Statistics
FO=-ll
Possible Errors

Meaning

ERR Value

?ILLEGAL SYS{) USAGE
The file open on the channel specified is not a disk
file or is a user file directory.

Discussion

The data passed by this call replaces the related data in the
accounting entry of the file open on the channel specified in byte 3.
No error checking is done on the date and time values passed. Because
the call does not supply default values, you must supply all three
date and time values each time the call executes.
The following is a partial directory listing of an account, showing
the file whose statistics are to be changed:
CAT
CTPBLD.BAS

30-Sep-84 30-Sep-84

03:13 PM

Ready
The following program changes the date and time of creation to 12:00
noon, 21-Jul-85, and the date of last access to 21-Jul-85, as shown in
the partial directory listing following the program:
10
20
100

200
300
400
500

D% = 15202%
!21-JUL-85 IS (202) + ({1985-1970)*1000)
T% = (24% * 60%) - (12% * 60%)
112 NOON IS 720 MINUTES BEFORE MIDNIGHT
OPEN 'CTPBLD.BAS' AS FILE #1%
\DIM M%(30%)
\M%{O%) = 30%
\M%(l%) = 6%
!OPEN FILE TO CHANGE, USE ARRAY TO SET UP CALL
M%{2%) = -11%
\M%{3%) = 1%
!SET UP FOR CHANGE STATS CALL ON CHANNEL 1
M%(4%) = D% AND 255%
\M%(5%) = SWAP%(D%) AND 255%
!SET UP THE DATE OF LAST ACCESS
M%(6%) = D% AND 255%
\M%(7%) = SWAP%(D%) AND 255%
1SET UP THE DATE OF CREATION
M%(8%) = T% AND 255%
\M%(9%) = SWAP%(T%) AND 255%
!SET TIME OF CREATION TO T%

7-130

Change File Statistics
FO=-ll

1000
2000
32767

CHANGE M% TO M$
\M$ == SYS(M$)
!SET ARRAY UP AS STRING AND DO CALL
CLOSE #1%
END

Ready
RUNNH
Ready
CAT
CTPBLD.BAS

21-Jul-85 21-Jul-85 12:00 PM

Ready
Note that you can use either this call or SYS call -26, File Utility
Functions, to change data in a file's accounting entry.
However, the
two calls work differently when you open a file, write to it, change
the date of last access in the file's accounting entry, and then close
the file.
When you use this SYS call to change the date of last access before
closing the file, the system does not update the file's accounting
entry when it closes the file.
After the file is closed, the file's
accounting entry contains the date specified in the call, not the
current date, as the date of last access. Use SYS call -26 if you
want the date of last access to be changed to the current date when
the file is closed.

7-131

Hang Up a Dataset
FO=-g

(UU. HNG)

Hang Up a Dataset
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(-9%), the hang up a dataset code.

CHR$(N%), where N% is the keyboard number of the line to
hang up.

CHR$(S%), where S% is the number of seconds to wait before
hanging up the line.
If no value is specified, the line is
hung up after 2 seconds.
See Discussion for values.

5-30

Reserved; should be O.

Data Returned
No meaningful data is returned.
privileges Required
HWCTL
Possible Errors
None.
Discussion
This SYS call allows a dial-up line to be connected or disconnected
under program control. A dial-up line can be connected but not be
performing any processing.
This condition prevents other users from
gaining access to the system.

7 -132

Hang Up a Dataset
FO.-9

Byte 4 of the data passed can contain the following values:
Value

Meaning

8%--1%

Set "Data Terminal Ready" to permit a modem connected to i
RSTS/E system to dial out. Should a connection not be
established in 127 seconds, perform an automatic hang-up
of the dataset.

8%-0%

Hang up in two seconds.

8%-1%-127%

Hang up in one to 127 seconds.

7-1.33

Get Open Channel Statistics
FO=-8

(UU. FCB)

Get Open Channel Statistics
Data passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(-8%), the get open channel statistics code.

CHR$(N%), where N% is the channel number (between 0 and 12)
of either the Device Data Block (DDB) for nondisk devices,
the Window Control Block (WCB) for the file system, or the
File Control Block (FCB).

CHR$(S%), where S% is 0% or 1%.
The value of S% determines
the information returned on the job.
See Data Returned.

5-30

Reserved; should be O.

Data Returned
If S% is

O~·
o •

Bytes

Meaning

The current job number times 2 .

Not used.

3-4

Word 1 of either the DDB or WCB.

5-6

Word 2 of either the DDB or WCB.

27-28

Word 13 of either the DDB or WCB.

29-30

Word 14 of either the DDB or WCB.

7-134

Get Open Channel Statistics
FO=-8

If S% is 1%:
Bytes

Meaning

The current job number times 2.

Not used.

The number of users who have a file open in a mode other
than read regardless.

The number of users who have a file open in read regardless
mode.

The status byte, which contains the following internal flag
information:
Bit
Value

Meaning

Reserved.

File is placed.

Some job has write access now.

File is open in update mode.

File is contiguous; no extend available.

No delete or rename allowed.

File is a UFD.

128

File is marked for deletion.

The most significant bits (MSB) of the file size.
If a
nonzero number is returned, it indicates a file whose size
is greater than 65535 blocks.

7-8

The least significant bits (LSB) of the file size (in
blocks).

9-30

Not used.

privileges Required
None.

7-1.35

Get Open Channel Statistics
FO=-8

Possible Errors
ERR Value

Meaning
?NOT A VALID DEVICE
You requested FCB information (byte 4 is 1) for a
nondisk file.

?I/O CHANNEL NOT OPEN
No file or device is open on the channel specified.

?ILLEGAL SYS() USAGE
You used a subcode other than 0 or 1 in byte 4.

?ILLEGAL I/O CHANNEL
The channel specified is outside the'range 0 to 12.

Discussion
This call returns information kept in the DDBu WCB or FCB.
Note that
these data structures are internal to RSTS/E and subject to change at
any time.
Specifying 0 in byte 4 returns information kept in the DDB or WCB data
structures.
Specifying 1 in byte 4 returns information kept in the FCB including
open counts, status byte, and current file size.
RMS uses this call
to determine file characteristics.
For an alternative to this call, see the description of the STATUS
variable in the BASIC-PLUS Language Manual.

7-136

Enable CTRL/C Trap
FO=-?

Enable CTRL/C Trap
Data Passed
Meaning

Bytes
I

CHR$(6%), the SYS call to FIP.

CHR$(-7%), the enable CTRL/C trapping code.

3-30

Reserved; should be

Data Returned
No meaningful data is returned.

Privileges Required
None.

Possible Errors
None.

Discussion
After a program executes this SYS call, the run-time system treats the
first CTRL/C typed on any terminal belonging to the job as a trappable
error (?Programmable ~C trap, ERR=28).
Upon execution of the trap,
the system passes control immediately to the numbered program
statement that has been designated as the error-handling routine by
the last execution of an ON ERROR GOTO statement. After the trap, the
system disables CTRL/C trapping.
To keep CTRL/C trapping in effect,
you must execute the SYS call again.
However, such trapping of CTRL/C guarantees only that a defined set of
statements is executed when you type a CTRL/C.
It is not always
possible to resume execution at the exact point where the CTRL/C
occurred.
The BASIC-PLUS variable LINE gives the number of the line
being executed when the CTRL/C was typed.
The variable ERL is not set
when trapping is in effect and the error ?Programmable ~C trap
(ERR=28) occurs.
The variable ERL refers to the last error trapped by
the program.

7-137

Enable CTRL/C Trap
FO=-7
The following sample routine shows the procedure:
100
200
300
400
1000
2000
32767

ON ERROR GOTO 1000
X = X/O.O
!THIS GIVES ERR 61, ERL 200
Q$ = SYS(CHR$(6%) + CHR$(-7%))
!SET CTRL/C TRAPPING
SLEEP 100%
\GOTO 400
!WAIT FOR CTRL/C TO BE TYPED
RESUME 2000 IF ERR=28
\RESUME 300 IF ERR=61
\ON ERROR GOTO 0
PRINT LINE, ERL
END

When you type CTRL/C at the terminal, the variable LINE is set to 400.
The variable ERL remains set to 200 from error number 61 at line
number 200.
Several methods are available to protect a program from CTRL/C aborts.
For example, you can:
o

Open the console terminal in binary input mode, MODE 1% (see
Chapter 4).

Detach the program.

Open the console terminal with MODE 16% (see Chapter 4).

If one of these three actions occurs, program execution under the job
is immune to any CTRL/C.
The following sample program shows the procedure:
10
30
100
110
32767

ON ERROR GOTO 100
\A$ = SYS(CHR$(6%) + CHR$(-7%))
PRINT "HI ";
\SLEEP 10%
\GOTO 30
IF ERR <> 28% THEN ON ERROR GOTO 0
ELSE RESUME 110
PRINT "CTRL/C TRAPPED"
\SLEEP 10%
\GOTO 10
END

7-138

Enable CTRL/C Trap
FO=-7

The program prints "HI" at the keyboard every ten seconds until you
type a CTRL/C.
Then it prints the "CTRL/C TRAPPED" message and
performs a sleep operation for ten seconds before reenabling the
CTRL/C trap and printing "HI." The ten-second sleep allows you to type
a second CTRL/C and actually stop the program.
Ordinarily, two CTRL/C characters typed very quickly at a terminal
stop a program even if CTRL/C trapping is enabled. However, on a
lightly loaded system, it is sometimes possible for the program to
react quickly enough to the first CTRL/C that the second one can also
be trapped.
In this situation, the only means of stopping the job is
through the Kill a Job SYS call (SYS 8), or the REMOVE/JOB command.
In this example, you can stop the program after the original trap by
typing CTRL/C within ten seconds.
DIGITAL recommends that you design
programs that trap CTRL/C characters to include a certain amount of
time after a trap in which a second CTRL/C actually stops the program.
When a CTRL/C is input from a terminal, further output is inhibited,
similar to the effect of the CTRL/O.
This is true whether the error
condition caused by CTRL/C is processed directly by BASIC-PLUS or is
handled by the user's program. When the CTRL/C error condition is
processed by BASIC-PLUS, it reenables output just prior to printing
the Ready prompt. When the CTRL/C error condition is trapped into the
user's own error handling routine, the output to the terminal is
reenabled just before executing the ON ERROR GOTO statement.

7-139

Poke Memory
FO=-6

(UU. POK)

Poke Memory
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(-6%), the poke memory code.

3-4

CHR$(A%)+CHR$(SWAP%(A%», where A% is the address to change.
The address must be an even number.

5-6

CHR$(V%)+CHR$(SWAP%(V%», where V% is the value to insert at
the address specified by bytes 3 and 4.

7-30

Reserved; should be O.

Data Returned
No meaningful data is returned.
Privileges Required
SYSMOD
Possible Errors
Meaning

ERR 'value

?PROTECTION VIOLATION
The job executing the call does not have SYSMOD
privilege, or the address specified in the call is
an odd value.

Discussion
This call changes a word in the monitor part of memory to the value
the user specifies.
This is a dangerous capability, and is therefore
heavily protected.
It requires the SYSMOD privilege.
The poke call allows only full word changes.
If you want to change a
byte, read the word using the PEEK function (see the section "The PEEK
Function" at the end of this chapter), change the desired byte, and
rewrite the entire word (using the Poke Memory call).

7-140

Broadcast to a Terminal
FO=-S
( • SPEC)
Broadcast to a Terminal
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(-5%), the broadcast to a terminal dode.

CHR$(N%), where N% is the keyboard number of the terminal to
receive the message.

4-?

M$ is the message to broadcast; LEN(M$) can be greater than
27. The string must not be null.

Data Returned
No meaningful data is returned.
Privileges Required
SEND
Possible Errors
ERR Value

Meaning
?PROTECTION VIOLATION
The job does not have sufficient privilege, or byte
3 contains an illegal KB: number.

?ILLEGAII BYTE COUNT FOR I/O
An attempt was made to broadcast a zero-length
message.

Discussj,on
The call prints the data broadcast on the destination keyboard. The
received message affects any output formatting being performed on the
destination keyboard.
If the data is broadcast to a disabled keyboard line, a hung-up modem
line, or a terminal for which broadcast is disabled (that is, SET
TERMINAL/NOBROADCAST), the call returns control to the program.

7-141

Broadcast to a Terminal
FO=-5

The call takes no action, and does not generate a system error.
In
this case, RECOUNT is equal to the length of the string that was
passed.
Because the actual number of bytes broadcast depends on the
availability of small buffer space, the destination keyboard may not
receive all of the bytes broadcast.
Therefore, the program should
test the value of the RECOUNT system variable to determine the number
of characters not broadcast.
If RECOUNT is not equal to zero, the
program should then issue another broadcast call to transmit the
remaining bytes. See the BASIC-PLUS Language Manual for information
on RECOUNT.
The following sample program segment shows how you can use this SYS
call and the RECOUNT variable to ensure transmission of complete
messages:
100
110

A$=SYS(CHR$(6%)+CHR$(-5%)+CHR$(N%)+M$)
IF RECOUNT <> 0% AND RECOUNT <> LEN(M$) THEN
M$=RIGHT(M$,LEN(M$)-RECOUNT+l%)
\SLEEP 1%
\GOTO 100

While the RECOUNT variable is nonzero, the remainder of the string M$
is rebroadcast. When the complete message is broadcast and RECOUNT is
0, the program exits from the loop.
The program also exits if RECOUNT
is equal to the length of the string, ~hich occurs if the terminal has
broadcast disabled or is a disabled terminal.

7-142

Force Input to a Terminal
FO:::-4
( • SPEC)
Force Input to a Terminal
])ata Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(-4%), the force input to a terminal code.

CHR$(N%), where N% is the keyboard number of the terminal tc
receive the forced input.

4-?

1$ is the input string to force to the terminal.
The strins
must not be null.
LEN(I$) can be greater than 27.

Data Returned
No meaningful data is returned.
Privileges Required
SYSIO
possible Errors
Meaning

ERR Value

(PROTECTION VIOLATION
The job does not have sufficient privilege, or byte
3 contains an illegal KB:
number.

l~ I LLEGAL

BYTE COUNT FOR I/O
An attempt was made to force a zero-length string.

I>iscussion
The data forced is seen as input by the system.
If the data is forced
to a disabled keyboard line or to a hung-up modem line, control is
returned to the program.
The system takes no action and does not
generate a system error.
Because the actual number of bytes forced depends on the availability
of small buffer space, the destination keyboard may not receive all of
the bytes forced.
Unlike a broadcast to the terminal, however, the
system discards characters it cannot store.
Thus, the program cannot
determine how many characters were actually forced.
7-143

Get Moni tor Tables - Part I
FO=-3
(UU. TBl )
Get Monitor Tables - Part I
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(-3%), the get monitor tables - part I code.

3-30

Reserved; should be

Data Returned
Meaning

Bytes
1

The current job number times 2.

Not used.

(CNT.KB-1) - The maximum keyboard number configured on the
system.

(MAXCNT) - The maximum job number allowed during the current
session.

time~sharing

5-6

(DEVCNT) - The table of maximum unit numbers for all devices
configured on the system.

7-8

(DEVPTR) - The table of pointers to device data blocks
(DDB) .

9-10

(MEMLST) - The root link word in the first memory control
subblock.

11-12

(JOBTBL)

13-14

(JBSTAT) - The job status table.

15-16

(JBWAIT)

- The table of job wait flags.

17-18

(UNTCLU)
disks.
(UNTOWN)

- The table of unit cluster sizes ( low byte) for

19-20

- The job table.

- The table of unit owners (high byte) for disks.

(UNTCNT) - The status table of all disk devices on the
system and the count of open files on each device.

7-144

Get Monitor Tables - Part

FO=-3

21-22

(SATCTL) - The table of free block counts for each disk
(other than swapping disks) on the system.
The table SATCTL
contains the least significant word (16 bits) of the
double-precision unsigned integer (32 bits) count of free
blocks.
Each word applies to a separate disk unit.

23-24

(JSBTBL)
index.

25-26

(SATCTM) - The table of free block counts for each disk
(other than swapping disks) on the system.
The table SATCTM
contains the most significant word (16 bits) of the
double-precision unsigned integer (32 bits) count of free
blocks.
Each word applies to a separate disk unit.

27-28

Current date in internal format.

29-30

(UNTOPT)

- The table of job status bits ordered by driver

- The table of unit options.

privileges Required
None.
Possible Errors
None.
Discussion
The three Get Monitor Table SYS calls return either an address or a
data value to your program. The calls are commonly used with the PEEK
function to read various system parameters and tables that give
configuration and run-time information.
Because it is beyond the
scope of this manual to describe the monitor, this section only
briefly describes the information returned by the monitor table
functions.
For a description of Get Monitor Tables - Part II, see SYS
call -12.
For a description of Get Monitor Tables - Part III, see SYS
call -29.
The section "The PEEK Function" describes the use of the
PEEK function for certain convenient programming operations.
In this section, a name in all uppercase letters denotes each item of
information described.
This name is the same one used to identify the
information in the RSTS/E assembly listings.
If the name is in
parentheses, the information returned is an address of the data
described.
If the name is not in parentheses, the information
returned is the actual data value.
For example, the Get Monitor
Tables .. Part I call returns CNT.KB-l in byte 3.
The value returned
is the number of terminal lines minus I configured on the system.
7-145

Get Monitor Tables - Part I
FO=-3

However, bytes 11 and 12 return (JOBTBL), the address of the table of
jobs.
Use the PEEK function to inspect the address.
Note
All information returned by the call described in this
section is internal to RSTS/E and is subject to change
at any time.

7-146

Disable Further Logins
FO=-2

(UU. NLG)

Disable Further Logins
Data Paf;sed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(-2%), the disable further logins code.
Reserved; should be O.

3-30

Data Returned
No meaningful data is returned.
Privileges Required
SWCTL
PossiblE~

Errors

No errors are possible.
Discussion
This call sets the number of logins allowed on the system to 1.
If no
jobs are active on the system, one user can successfully log in to the
system.
However, once one user is logged in, any delimiter typed at a
logged out terminal returns the NO LOGINS message.
The number of jobs that can log in to a RSTS/E system is limited by
the swapping space available, the JOB MAX set at system start-up, and
the set maximum number of 10gins. However, console terminal KBO:
is
a special terminal and can log in regardless of the set login maximum,
provided that swapping space and JOB MAX permit.
The system manager
can install a patch that changes the number of the special keyboard
from KBO: to some other terminal.

7-147

Enable Further Logins
FO=-l

(UU. YLG)

Enable Further Logins
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(-l%), the enable further logins code.

3-30

Reserved; should be O.

Data Returned
Meaning

Bytes
1

CHR$(J%), where J% is the job number times 2 of the job
executing this call.

Not used.

CHR$(N%), where N% is the number of logins allowed.

4-30

Not used.

Privileges Required
SWCTL

Possible Errors
None.

Discussion
This call sets the number of logins allowed to the maximum number
possible, given that swap file space may have been added.
The call
returns this value in byte 3.
The number of logins never exceeds that
specified at start-up time (JOB MAX).

7-148

Create User Account
FO=O
(UU.PAS)
Create User Account
This call has two subfunctions:
o

Create User Account (New Format)

Create User Account (Old Format)

Create User Account (New Format)
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(O%), the create user account code.

CHR$(N%), where N% is the number of clusters to preextend
the User File Directory (UFO).
See the Discussion for the
values you can use.

Flag byte.
format.

5-6

CHR$(N%)+CHR$(SWAP%(N%), where N% is the starting device
cluster number for UFO.
(Use -1 to place UFO at middle of

CHR$(128%) to specify disk quotas in the new

disk)~

7-8

PPN.
The project number can be between 0 and 254 with the
exception of account [0,1]; the programmer number can be
between 0 and 254.

9-12

Password in Radix-50 format.
For a long password, specify 0
in bytes 9-12.
See the Discussion for the procedures to set
a long password.

13-14

Logged-out quota (LSB).

15-16

Expiration date, in RSTS/E internal format:
(day of year) +
[(number of years since 1970) * 1000].
Specify 0 to
indicate "no expiration."

17-18

Logged-in quota (LSB).

Logged-in quota (MSB).

7-149

Create User Account (New Format)

FO=O
20

Logged-out quota (MSB).

21-22

Reserved; should be O.

23-24+

Oevice name.

25+

unit number.

26+

unit number flag.

CHR$(C%), where C% is user file directory (UFO) cluster
size; 0 means use the pack cluster size. A negative value
means use the absolute value of the number if it is larger
than the pack cluster size. Otherwise, use the pack cluster
size.

Reserved; should be

29-30

Reserved; should be O.

Data Returned
Bytes

Meaning

17-18

CVT%$(SWAP%(X%», where X% is the device cluster number for
cluster 0 of the UFO.

19-20

CVT%$(SWAP%(X%», where X% is the device cluster number for
cluster 1 of the UFO.

21-22

CVT%$(SWAP%(X%», where X% is the device cluster number for
cluster 2 of the UFO.

23-24

CVT%$(SWAP%(X%», where X% is the device cluster number for
cluster 3 of the UFO.

25-26

CVT%$(SWAP%(X%», where X% is the device cluster number for
cluster 4 of the UFO.

27-28

CVT%$(SWAP%(X%», where X% is the device cluster number for
cluster 5 of the UFD.

29-30

CVT%$(SWAP%(X%», where X% is the device cluster number for
cluster 6 of the UFD.

7-150

create User Account (New Format)

FO=O
Privileges Required
GACNT

Create an account within the group

W'ACNT

Create any account

PossiblE~

Errors
Meaning

?NO ROOM FOR USER ON DEVICE
The monitor cannot allocate one cluster for the UFD
you are creating because the disk is too full.

ERR Value
4

?PROTECTION VIOLATION
The PPN is [0,0], or either the project or
programmer number is 255.

?FATAL SYSTEM I/O FAILURE
The account has been entered and the directory has
been preextended.
However, the account has not been
given a password or quota because an internal
consistency check has failed.
Submit an SPR along
with a SAVRES of the disk if you get this error.

?NAME OR ACCOUNT NOW EXISTS
The account specified in the call currently exists
on the device specified.

?ILLEGAL CLUSTER SIZE
The cluster size specified in the call is either
greater than 16 or is nonzero and less than the pack
cluster size.
See the RSTS/E System Manager's Guide
for a discussion of valid cluster size values.

?DEVICE NOT FILE STRUCTURED
The device specified is not a disk or the disk is
open in non-file-structured mode.

?ILLEGAL BYTE COUNT FOR I/O
The number of clusters specified in byte 3 is less
than 0 or greater than 7.

Or, the position specified in bytes 5 and 6 is
beyond the end of the disk or the UFO, if placed at
the specified position, will extend beyond the end
of the disk.
See Table 1-8 for information on disk
sizes.

7-151

Create User Account (New Format)
FO=O
?MISSING SPECIAL FEATURE
You issued the new format calIon a disk with ROSl.l
or ROSO.O disk structure (pre-V9.0).
The call
returns this error if you:
o

Specify a logged-out quota of 0 or between 65536
and 16777214 (2A24-2)

Specify a logged-in quota other than 16777215
( 2A 24 - 1 )

Discussion
You can use this call to perform the following operations:
o

Create accounts on any disk that is mounted.

Preextend and position the UFO which contains the directory
entries for all of the files for the account you are
creating.
You may improve performance by preextending UFDs;
however, this takes up additional disk space if the directory
space is not used.
In general, positioning the directory at
the middle of the disk improves system performance.

Set logged-in and logged-out disk quotas for the account you
are creating.
These quotas define the amount of disk space
an account may use while logged-in and logged-out, as well as
the maximum amount of disk space a logged-in account may use.

Byte 3 specifies the number of clusters to preextend the UFO.
byte can contain the following values:
Bit

o
1-7

This

Meaning
Preextend 1 cluster.
Preextend specified number of clusters.

Create User Account (New Format)

FO=O
Set Password SYS call (SYS 8) to establish the desired password for
the account.
Bytes 13, 14, and 20 specify the logged-out quota.
Bytes 17, 18, and
19 specify the logged-in quota.
On ROSl.2 disks (V9.0 format), quota
values must be in the range 0 to 16777215 (2 24-1), with 0 meaning no
allocation allowed and 16777215 meaning unlimited, On ROS1.1 or ROSO.O
disks (pre-V9.0 disks), logged-out quotas must be in the range 1 to
65535 or 16777215 (meaning unlimited), and logged-in quotas must be
16777215.
A

The data returned in bytes 17-30 gives you the device cluster number
for each cluster of the UFO.
Check the data returned to determine if
there was enough space on the disk to completely preextend the UFO.
The monitor tries to extend the UFO contiguously, but it allocates
non-contiguously if it must.
If the monitor finds at least one
cluster, no error is returned.
You must check the data returned to
see if the number of clusters you specified were allocated (or to
determine if they were allocated contiguously).

7-153

create User Account (Old Format)

FO=O
Create User Account (Old Format)
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(O%), the create user account code.

CHR$(N%), where N% is the number of clusters to preextend
the User File Directory (UFO).
See the Discussion for the
values you can use.

Flag byte.

5-6

CHR$(N%)+CHR$(SWAP%(N%), where N% is the starting device
cluster number for UFO.
(Use -1 to place UFO at middle of
di sk ) .

7-8

PPN.
The project number can be between 0 and 254 with the
exception of account [0,1]; the programmer number can be
between 0 and 254.

9-12

Password in Radix-50 format.
For a long password, specify 0
in bytes 9-12.
See the Discussion for the procedures to set
a long password.

13-14

Disk quota as an unsigned number.
See the section "Unsigned
Integer Numbers" for a description of unsigned numbers.
Use
o for an unlimited quota.

15-16

Expiration date, in RSTS/E internal format:
(day of year) +
[(number of years since 1970) * 1000].
Specify 0 to
indicate "no expiration."

17-22

Reserved; should be O.

23-24+

Device name.

25+

Unit number.

26+

Unit number flag.

CHR$(O%) to indicate old format disk quotas.

7-154

Create User Account (Old Format)

FO=O
27

CHR$(C%), where C% is user file directory (UFO) cluster
size; 0 means use the pack cluster size. A negative value
means use the absolute value of the number if it is smaller
than the pack cluster size.
Otherwise, use the pack cluster
size.

28-30

Reserved; should be O.

Data Returned

Bytes

Meaning

17-18

CVT%$(SWAP%(X%», where X% is the device cluster number for
cluster 0 of the UFO.

19-20

CVT%$ ( SWAP %(X% ) ) , where X% is the device cluster number for
cluster 1 of the UFO.

21-22

CVT%$(SWAP%(X%», where
cluster 2 of the UFO.

X~i

is the device cluster number for

23-24

CVT%$(SWAP%(X%», where
cluster 3 of the UFO.

X~i

is the device cluster number for

25-26

CVT%$ ( SWAP %(X% ) ) , where X% is the device cluster number for
cluster 4 of the UFO.

27-28

CVT%$(SWAP%(X%», where X% is the device cluster number for
cluster 5 of the UFO.

29-30

CVT%$(SWAP%(X%», where X% is the device cluster number for
cluster 6 of the UFO.

Privileges Required

GACNT

Create an account within the group

W'ACNT

Create any account

Possible Errors

Meaning
?NO ROOM FOR USER ON OEVICE
The monitor cannot allocate one cluster for the UFO
you are creating because the disk is too full.

7-1S5

ERR Value
4

Create User Account (Old Format)

FO=O
?PROTECTION VIOLATION
The PPN is [0,0], or either the project or
programmer number is 255.

?FATAL SYSTEM I/O FAILURE
The account has been entered and the directory has
been preextended. However, the account has not been
given a password or quota because an internal
consistency check has failed.
Submit an SPR along
with a SAVRES of the disk if you get this error.

?NAME OR ACCOUNT NOW EXISTS
The account specified in the call currently exists
on the device specified.

?DEVICE NOT FILE STRUCTURED
The device specified is not a disk or the disk is
open in non-file-structured mode.

?ILLEGAL BYTE COUNT FOR I/O
The number of clusters specified in byte 3 is less
than 0 or greater than 7.

Create accounts on any disk that is mounted.

Preextend and position the UFD which contains the directory
entries for all of the files for the account you are
creating. You may improve performance by preextending UFDs;
however, this takes up additional disk space if the directory
space is not used.
In general, positioning the directory at
the middle of the disk improves system performance.

7-156

Create User Account (Old Format)

FO-O
o

Set a logged-out disk quota for the account you are creating.

Specify an expiration date for the account you are creating.

Byte 3 specifies the number of clusters to preextend the UFO.
byte can contain the following values:
Bit

This

Meaning

Preextend I cluster.
Preextend specified number of clusters.

1-7

Any other value returns the error ?Illegal byte count for I/O
(ERR=31).
Bytes 5 and 6 specify where on the disk to place the UFO. Oevice
clusters are numbered from 0 to the maximum shown in Table 1-8. Note
that you receive the error ?Illegal byte count for I/O if the device
cluster number you specify plus the number of clusters to preextend
exceeds the disk size.
Bytes 9-12 are used to specify the password. To establish a long
password, specify 0 in these bytes. The caller should then issue a
Set Password SYS call (SYS 8) to establish the desired password for
the account.
Bytes 13-14 specify the disk quota. Quota values must be in the range
o to 65535. If you issue the old format calIon an ROS1.2 disk (V9.0
format), the call sets the following quotas:
o

Sets the l()gged-out quota to the value specified in bytes
13-14. If you specify 0, it sets the logged-out quota to
16777215.

Sets the l()gged-in quota to 16777215.

The monitor tries t() extend the UFO contiguously. If the monitor
finds at least one cluster, no error is returned. You must check the
data returned to seE~ if the number of clusters you specified were
allocated (or to determine if they were allocated contiguously).

7-157

Delete User Account
FO=l
(UU.DLU)
Delete User Account
Data Passed
Meaning

Bytes
1

CHR${6%), the SYS call to FIP.

CHR${l%), the delete user account code

3-6

Reserved; should be 0.

7-8

PPN.
This call generates an error if you specify account
[0,0] or [0,1].

9-22

Reserved; should be 0.

23-24+

Device name; must be a disk.

25+

unit number.

26+

unit number flag.

27-30

Reserved; should be 0.

Data Returned
No meaningful data is returned.
Privileges Required
GACNT

Delete an account within the group

WACNT

Delete any account

Possible Errors
Meaning

ERR Value

?ACCOUNT OR DEVICE IN USE
For an account being deleted from the public
structure, a user is currently logged in to the
system under the account.

?CAN'T FIND FILE OR ACCOUNT
The specified account does not exist.

7-158

Delete User Account
FO=l

?DEVICE NOT AVAILABLE
The disk is mounted /NOSHARE by another user.

?PROTECTION VIOLATION
Account specified is either [0,0] or [0,1].

?NAME OR ACCOUNT NOW EXISTS
The account contains files (it has not been zeroed).

?DEVICE NOT FILE STRUCTURED
Device specified is not a disk or is a disk open in
non-file-structured mode.

Discussion

This call deletes a user account from a private disk or the public
structure.
If the error ?Device not available (ERR=8) occurs, you
must first delete all files in the account and release the UFD
clusters with the Zero a Device SYS call (SYS 13) or the DeL DELETE
command .

7-159

Disk Pack status
FO=3
(UU.MNT)
Disk Pack status
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(3%), the disk pack status code.

CHR$(N%); the following values of N% determine the action
performed:
Value

Action

Mount a disk pack or cartridge.

Dismount a disk pack or cartridge.

Restrict a disk pack or cartridge.

unrestrict a disk pack or cartridge.

Load SAT of a disk into memory.

10%

Unload SAT of a disk from memory.

For all values of N%:
23-24+

Device name.

25+

Unit number.

26+

Must be 255.

For Mount:
7-10+

Pack identification label in Radix-50 format.

11-12

CHR$(F%}, where F% is a flag that determines whether a
logical name is to be used.
If both bytes are 0, the call
attempts to use the pack identification. If both bytes are
255%, the call attempts to substitute the name given in
bytes 13 through 16 for the pack identification.

13-16

First six characters of the logical name for this disk, in
Radix-50 format (see bytes 19-20). If bytes 11-12 are 255%,
the logical name given here and in bytes 19-20 replaces the
7-160

october

198~

Disk Pack Status

FO=3
pack identification as the system-wide logical name.
If
bytes 11-12 are 255% and these bytes are 0, the system
places 0 in the logical name table.
17-18

Mode word.
If the sign bit is not set (bit 15 is 0), a mode
value is not used on the mount operation.
If the sign bit
is set (32767%+1% is included in the value of this word),
the following bit definitions are recognized:
Value
256%
1024%
2048%
4096%
8192%
16384%

Meaning
Mount disk /NOQUOTA.
Mount with pack identification lookup. See
Discussion.
Mount disk for one user only (/NOSHARE).
Mount disk read/write even if disk was initialized
as read-only.
Mount disk for r~ad-only access.
Mount as a private disk (/PRIVATE).

Note that you can combine the various mode bits where
appropriate.
19-20

Last three characters of the logical name for this disk, in
Radix-50 format (see bytes 13-16). When you use a logical
name of fewer than 9 characters, you must fill the extra
space with blanks.
If bytes 11-12 are 255%, the logical
name given here and in bytes 13-16 replaces the pack
identification as the system-wide logical name.
If bytes
11-12 are 255% and these bytes are 0, the system places 0 in
the logical name table.

Data Returned (Mount a disk pack or cartridge)

Bytes

fvleaning

The current job number times 2.

2-12

Not used.

13-16

First two words of the logical name used for this disk, in
Radix-50 format.

17-18

Not used.

19-20

Third word of the logical name used for this disk, in
Radix-50 format.

21-30

Not used.
7-161

Disk Pack status

FO=3
Data Returned (Load SAT into Memory)
Meaning

Bytes

The current job number times 2.

2-12

Not used.

13-14

The amount of memory used (in bytes).

17-30

Not used.
Privileges Required

HWCFG

Declare a mounted disk as restricted or unrestricted

MOUNT

Mount or dismount a disk /SHARE;
,
Dismount a disk owned (/NOSHARE) by another account;
Mount a disk /NOSHARE for a job running under another PPN;
Mount a dirty disk

SWCTL

Load SAT of a disk into memory or unload SAT of a disk from
memory

Possible Errors
Meaning

ERR Value

?ACCOUNT OR DEVICE IN USE
An attempt is made to dismount a disk that has an
open file.

?NOT A VALID DEVICE
The device specification supplied in bytes 23
through 26 is illegal because the unit or its type
is not configured on the system.

?I/O CHANNEL ALREADY OPEN
An attempt was made to load the SAT of a disk into
memory mor~ than once.

?I/O CHANNEL NOT OPEN
You tried to unload a SAT that was not loaded.

?PROTECTION VIOLATION
An attempt was made to mount a disk that does not
contain the RSTS/E file structure.
Use either the
INITIALIZE command, the online DSKINT program, or
the DSKINT initialization option to initialize the

7-162

october 1985

Disk Pack Status

FO=3
disk. Or p you do not have the required privilege
for the attempted operation.
?DEVICE HUNG OR WRITE LOCKED
An attempt was made to mount a disk read/write that
is not write enabled. Or, an attempt was made to
load'the SAT of a read-only disk.

?ILLEGAL SYS() USAGE
An attempt to mount a disk that is already mounted
or that resides in a non-dismounted drive; or disk
specified is the system disk.

?PACK IDS DON'T MATCH
An attempt is made to mount a disk with an incorrect
pack label.

?DISK PACK IS NOT MOUNTED
An attempt is made to lock, unlock, or dismount a
disk that is not mounted.
Or, an attempt is made to
load or unload the SAT of a disk that is not
mounted.

?DISK PACK NEEDS REBUILDING
The storage allocation table on the disk needs to be
restructured because the disk was not properly
dismounted when it was last used.
Before using the
disk, use the MOUNT command or the ONLCLN program to
rebuild the storage allocation table.
Note that
when this error occurs, the disk is always mounted
read-only with the "dirty" bit set.

?FATAL DISK PACK MOUNT ERROR
The disk structure is invalid.
For example, the
cluster size is larger than 16 or the storage
allocation table is unreadable.

?DEVICE NOT FILE STRUCTURED
An attempt is made to restrict, unrestrict, or
dismount a disk currently opened in
non-file-structured mode. Or, an attempt is made to
load or unload the SAT of a disk currently opened in
non-file-structured mode.

BUFFER SPACE AVAILABLE
An attempt was made to load the SAT of a disk into
memory and no memory is available.

~~NO

October 1985

7-163

Disk Pack status

FO=3
Discussion

This call lets you mount, dismount, restrict, and unrestrict a disk,
load the storage Allocation Table (SAT) of a disk into memory, or
unload the SAT of a disk from memory. For a discussion of disk
management on RSTS/E, see the RSTS/E System Manager's Guide.
The load SAT subfunction is used to load the SAT of a disk into
memory. Loading the SAT of a unit reduces the amount of disk I/O
which the file processor needs to do, thereby increasing overall
system throughput. The unload SAT subfunction frees XBUF for other
use.
The mode value in bytes 17 and 18 of the mount call modifies the mount
operation:
o

MODE values 16384% and 8192% correspond to the /PRIVATE and
/NOWRITE qualifiers of the DCL MOUNT command.

MODE value 4096% mounts packs initialized as /NOWRITE in
read/write mode (normally such packs are mounted read-only).
This mode is used by the /WRITE qualifier of the DCL MOUNT
command.

MODE value 2048% mounts the disk for a sin91e user. Only
that user can access the disk; other users receive the error
?ACCOUNT OR DEVICE IN USE (ERR = 3). In addition; mounting a
disk /NOSHARE disables any privileged programs on that disk.
The system automatically dismounts the disk when the user
logs out or the job is killed.

MODE value 1024% mounts a disk without specifying the pack
identification label. The system looks up the pack
identification label on the disk.

MODE value 256% mounts a disk /NOQUOTA. This instructs the
monitor not to perform quota checking on the unit.

The mount version of this call first mounts the disk pack or cartridge
and then determines whether a logical name should be placed in the
system logical name table.
If the mount operation fails, an error is
returned to the program. If the mount succeeds, the call checks bytes
11 and 12 of the data passed.
Null characters in bytes 11 and 12 mean that the pack identification
is to be placed in the table as the logical name for that disk unit.
The call scans the entire table.
If the name is not currently in use,
the pack identification is placed in the table and is written in bytes
13 through 16 of the data returned to the program. This action
notifies the program that a logical name is current for that disk
7-164

October 1985

Disk Pack status
FO=3

unit.
If the pack identification is currently in use as a logical
name for another device, the call writes null bytes in the table.
To
notify the program that a logical name was not placed in the table,
null characters are written in bytes 13-16 and 19-20 of the data
returned.
No error is returned to the program because the mount
operation itself succeeded.
If bytes 11 and 12 of the data passed are 255%, the call attempts to
place in the logical name table the name found in bytes 13-16 and
19-20.
If bytes 13-16 and 19-20 contain null bytes, no name is placed
in the table. When bytes 13-16 and 19-20 contain a logical name, the
call performs the same actions as previously described for the pack
identification to place the name in the table.
The program should
check the data returned to determine whether a logical name is in
effect.
If the call found the logical name currently in use, it does
not attempt to use the pack identification.

7-164.1

(UU.LIN)

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(4%), the LOGIN code.

Reserved; should be O.

CHR$(L%+P%), where:
L% indicates whether to perform a LOGIN or check a password.
L% can be one of the following values:

Value

Meaning

Perform the login function.

Check the password only.

Check the system password.

Perform the login function without checking the
password.

P% indicates the password format.
following values:

Value

See Discussion.

P% can be one of the

Meaning

The password is specified as 2 words of Radix-50
data (old format).

The password is specified as 14 bytes of ASCII
data (new format).

5-6+

PPN; must not be group [0,*].

7-20

Password of the account specified in bytes 5 and 6.
If P%
in byte 4 is 0, specify the password in bytes 7-10 in
Radix-50 format, and pad the extra bytes with nulls.
If P%
in byte 4 is 2, specify the password as 14 bytes of ASCII
data.

21-22

Reserved; should be O.

7-165

Device name; must be a disk.
You must specify the device if
you are verifying a user password (L%=l).
This field is
reserved for login (L%=O% or L%=8%) and verify system
password (L%=4%).
However, you do not need to specify the
device if you are verifying a system password (L%=4).

25+

Device unit number.

26+

unit number real flag.

27-30

Reserved; should be O.

Data Returned for Login Function
Meaning

Bytes
1

The current job number times 2.

Flag byte.

Total number of jobs logged in to the system under this
account.

4-1

Job numbers of each job running detached under this account.
A byte of CHR$(O%) signifies the end of the list.
Only the
first 26 job numbers are returned.

See Discussion.

Data Returned for Check Password Function
No meaningful data is returned.
Privileges Required
None

GACNT

For any account within the group:
without checking password

WACNT

For any account: check password, or log in without checking
password

DEVICE

Check any password on a restricted disk (required in
addition to the GACNT/WACNT privilege)

7-166

check password, or log in

Errors
Meaning

ERR Value

?BAD DIRECTORY FOR DEVICE
The account does not have all the necessary
directory structures.

?ILLEGAL FILE NAME
When verifying a password other than the system
password, the given password does not match the
account password.

('CAN'T FIND FILE OR ACCOUNT
One of the following conditions occurred:

The PPN specified in the call is [0,1] or does
not exist.

The password specified in the call does not
match the password of the account on the system.

The system password specified in the call does
not match the password block that exists in
,account [0,1].

?PROTECTION VIOLATION
You tried to verify a user password but did not
specify the device name and unit number.

?NO BUFFER SPACE AVAILABLE
No buffers are available to create the necessary
internal structures.

Discussion
This call performs three functions:
o

Logs in a job.
If the calling job is already logged in to
the system, this call does not change the job's account.
The
data returned in bytes 3 through 30 refers to the same
account under which the job is running.
The caller specifies
passwords either as two words of Radix-50 data (old format),
or as 14 bytes of ASCII data (V9.0 format).

Verifies a password while logged in.
This function allows a
program to verify a user-supplied password without having to
log out and back in.

Checks a system password.

7-167

Login/Verify Password
FO=4
Bit 2 of byte 4 is the system password flag.
If bit 2 is set, then
the system performs the check system password function.
Successful
completion of this function sets a "system password verified" flag in
the job data structure, which is checked by the Login function.
The
caller passes the system password to check in bytes 7-20. The system
follows these procedures when performing a system password check:
1.

If the caller already has the "system password verified~ flag
set, then this function completes immediately.

The system checks whether the system password applies to this
job. The system manager uses the SET SYSTEM/PASSWORD_PROMPT
command to specify which jobs require the system password.
For example, the system password may be set to apply only to
dial-up and network jobs.
In that case, local jobs do not
require a system password. The function completes
successfully, but it does not set the "system password
verified" flag.

If a system password applies to the job, the system looks for
the password block of the [0,1] account on the system disk.
If there is none, the function completes successfully.

If a password block exists in account [0,1), then the system
compares it against the specified value.
If they match, the
function completes successfully. Otherwise, it returns the
error ?Can't find file or account (ERR=5).

Byte 2 is the flag byte. On the login function, this byte reports
cases where the password and PPN are valid but the job or detached
quota for the account are exceeded. Values are:
Value

Meaning

-1

-2

o or
Positive

If the call returns a value other than -1, the job is still logged
out.

7-168

FO=5

Logout
(UU.BYE)

Logout
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(5%), the LOGOUT code.

3-4

CVT%$(SWAP%(N%+NO%)), where N% and NO% can have the
following values:
N%=O%

Close files, deassign devices, remove receivers,
and dismount disks mounted /NOSHARE.

N%=l%

Log out without closing files, deassigning
devices, removing receivers, and dismounting disks
mounted /NOSHARE.

NO%=O%

Check detached job and disk quotas on all mounted
disks before logout.

NO%=2%

Perform logout without checking quotas.

N% is forced to zero if you do not have WACNT privilege.
NO% is forced to zero if you do not have EXQTA privilege.
5-30

Reserved; should be O.

Data Returned
Bytes

Meaning

1-2

Not used.

3-4

Logout status.

The following values can be returned:

No quota is exceeded. If you have WACNT privilege,
the system returns control to your program, and you
can examine the data returned. If you do not have
WACNT privilege, the system does not return control
to your program. Instead, the system kills your job
after performing necessary clean-up functions.

7-169

Logout
FO=5
-1

Either the disk or detached job quota is exceeded;
your job is still logged in.
(Byte 13 tells you
which quota is exceeded.)

-2

A disk quota is exceeded; your job is logged out.
If
you have WACNT privilege, the system returns control
to your program.
If you do not have WACNT privilege,
the system kills your job after performing necessary
clean-up functions.

See the Discussion for an explanation of quota checking.
5-12

Not used.

If bytes 3-4 contain -1, or -2, this byte indicates which
quota is exceeded by returning one of the following values:

° = Disk quota.
1

= Detached job quota.

If a quota is exceeded, the following data is returned:
15

If byte 13 is 0, this byte returns the current disk quota
(MSB) in blocks as an unsigned integer.

If byte 13 is 0, this byte returns the current disk usage
(MSB) in blocks as an unsigned integer.

If byte 13 is 1, this byte contains the number of detached
jobs currently active in the account.

If byte 13 is 1, this byte contains the number of detached
jobs allowed on logout.
(Byte 17 minus byte 18 is the
number of detached jobs over quota.)

19-20

If byte 13 is 0, these bytes return the current disk quota
(LSB) in blocks as an unsigned integer (see the section
"Unsigned Integer Numbers").

21-22

If byte 13 is 0, these bytes return current disk usage in
blocks (LSB) as an unsigned integer (see the section
"Unsigned Integer Numbers").

23-24+

If byte 13 is 0, these bytes return the disk name as 2 ASCII
characters as an unsigned integer (see the section "Unsigned
Integer Numbers").

25+

If byte 13 is 0, this byte contains the unit number as 2
ASCII characters.

7-170

Logout
FO=5
26+

unit number

27-30

Not used.

flag~

Privileges Required
None

Log out normally

W.ACNT

Log out without self kill

EXQTA

Suppress quota checks on logout (NO%=2% in bytes 3-4)

PossiblE~

Errors

None.
Discussion
The LOGOUT and LOGIN system programs use this call.
It can close all
open channels, deassign all devices, and clear the job from the
monitor message table (depending on the values passed in bytes 3-4).
In addition, the call updates statistics on the disk and disassociates
the PPN from the job number.
The call also enforces quotas on all
disks at log-out time (all disks mounted read/write with quota
checking enabled must be under quota at log-out time).
Note that if the caller has WACNT privilege, this call does not
immediately terminate the job.
Instead, the monitor terminates a
logged-out job when the program the job is running finishes executing.
If the c:aller does not have WACNT privilege, this call terminates the
job immediately, effectively performing a self-kill.
If a quota is exceeded, byte 13 of the returned data indicates which
quota (the system only reports this information for the first
encountered quota exceeded).
If the detached job quota is exceeded,
the call does not perform the logout.
If a disk quota is exceeded and
bytes 3-4 are returned as -2, at least one other attached job is
logged in to the account, and the call performs the logout with a
quota warning_
However, if a disk quota is exceeded and bytes 3-4 are
equal to -1, the call does not perform the logout.
Note that the
calling program should examine bytes 3-4 to determine if the logout
function was performed.
For callers without sufficient privilege,
control returns to the program only if the call did not perform the
logout (bytes 3-4 are returned as -1).

7-171

Attach
FO=6

(UU.ATT)

Attach
This call has three subfunctions:
o

Attach

Reattach

Swap Console

To use this call, you need to understand the concept of terminal
ownership. A terminal is "owned" when:
o

It becomes attached to a job by logging in. When data is
entered at a free terminal, the system starts a job to handle
the input and gives the job the next available job number.
The system then starts the LOGIN program to allow the user to
log in to the system.
(See the RSTS/E System User's Guide
for the operational details.)
When a user is logged in to the system, the system associates
the activated job with both the terminal at which the user is
typing and the account number used for system identification.
The job is then considered active on the system and in
attached mode (or attached to the terminal).
The system
associates I/O channel 0 with the terminal that activated the
job.
The terminal associated with channel 0 is called the
job's console terminal or console keyboard. A job can have
only one console terminal, the keyboard to which it is
attached.

It is opened on a nonzero channel. A job can own several
terminals that are open on nonzero channels.

It is allocated for the use of a job (with the the DeL
ALLOCATE command).

7-172

Attach
FO=6
Attach
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(6%), the attach and reattach code.
The attach code is
the same as the reattach code, except that the format of the
data passed is different.
See the next section for the
format of the Reattach SYS call.

The number of the job to attach to the terminal.

CHR$(N%+P%), where N% is 0 and P% can be one of the
following values:
P%=O%

The password is specified as 2 words of Radix-50
data (old format).

P%=2%

The password is specified as 14 bytes of ASCII
data (new format).

P%=4%

Suppress the password check.

5-6+

PPN of thE~ job to attach to the terminal, or zero to specify
the same PPN as the caller.

7-20

Password of the account specified in bytes 5 and 6 (not
necessary if the PPN of the job being attached matches that
of the caller).
If PI in byte 4 is 0, specify the password
in bytes 7-10 in Radix-50 format, and pad the extra bytes
with nulls.
If P% in byte 4 is 2, specify the password as
14 bytes of ASCII data and pad the the extra bytes with
nulls.
See Discussion.

21-30

Reserved; should be O.

Data Returned
No meaningful data is returned.

7-173

Attach
FO=6
Privileges Required
None

Attach to a job running under the caller's PPN

GACNT

Attach to a job in another account within the same group

WACNT

Attach to a job in any account

Possible Errors
ERR Value

Meaning
?ILLEGAL SYS() USAGE
One of the following conditions generates the error:
o

The job executing the call has an open channel.

The job executing the call is a source (.BAS)
program rather than a compiled (.BAC) program.

The job number specified in byte 3 is not a
job.

d~tached

The account in the call does not match the PPN
of the job being attached.

The job being attached has a PPN different from
that of the caller, and the password does not
match.

The job executing the call is detached.

The caller does not have sufficient privilege to
attach to a job that is running under a
different PPN than the caller.

Discussion
The LOGIN system program executes this call.
See the description of
the ATTACH command in the RSTS/E System User's Guide for an example of
the call's use.
Note that, if byte 3 is the number of the job
executing the call, the system performs the reattach action.
See the
next section for a description of the reattach process.
If the job being attached has the same PPN as the caller, no password
is needed.
However, if the job being attached has a PPN different
from the caller, the password is required unless the suppress password
check flag is set (P%=4%).

7-174

Reattach
FO=6
Reattach
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(6%), the attach and reattach code.
The reattach code
is the same as the attach code, but the format of the data
passed is different.
See the previous section for the
attach format.

CHR$(J%), where J% is the number of the job executing the
call.

CHR$(K%), where K% is the keyboard number of the terminal to
which the calling job is to be attached.

5-30

Reserved; should be O.

Data Returned
No meaningful data is returned.
Privileges Required
DEVICE

Reattach to a terminal that is a restricted device

Possible Errors
Meaning

ERR Value

?ILLEGAL SYS() USAGE
One of the following conditions generates the error:

The job number specified in byte 3 is less than
1 or greater than the JOB MAX value on the
system.

The job executing the call is not detached.

The keyboard number in byte 4 is out of range.

7-175

Reattach
FO=6
o

The terminal specified by the keyboard number in
byte 4 is currently assigned, opened, or the
console keyboard of some job other than the
calling job.

The terminal specified is a restricted device
and you do not have the DEVICE privilege.

Discussion
This call performs differently for users with or without DEVICE
privilege.
If a job with DEVICE privilege executes the reattach call,
the call establishes the terminal specified in byte 4 as the job's
console keyboard.
In this manner, a job can reattach to a terminal
after having detached.
This call is also available to users who do not have DEVICE privilege,
with certain restrictions.
If the job issuing the reattach request
has the specified terminal assigned, the request is accepted.
If the
terminal is free (not assigned), the reattach is allowed only if the
terminal has not been marked restricted (by the SET DEVICE command).
If the terminal is marked restricted and is free, the job must have
DEVICE privilege to reattach to it.

7-176

Swap Console
FO=6
Swap Console
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(6%), the attach, reattach, and swap console code.
The
swap console code is the same as the attach and reattach
code, but the format of the data passed is different.
See
the previous two sections for the attach and reattach
formats.

CHR$(J%), where J% is the job number to swap with.
If the
calling job is attached, this job must be detached.
If the
calling job is detached, this job must be attached.
Both
the calling job and this job must be running under the same
PPN.

CHR$(S%), where S% is 1 to indicate the swap console
function.

Data Returned
No meaningful data is returned.
Privileges Required
None.
Possible Errors
Meaning

ERR Value

?ILLEGAL SYS () USAGE
One of the following conditions generates this error:
o

Both the calling job and the job specified in
byte 3 are detached, or neither job is detached.

The job specified in byte 3 has a PPN different
from the caller's.

The value in byte 4 is neither 0 nor 1.

7-177

Swap Console
FO=6

Discussion
The swap console call allows two jobs, one of which is detached, to
exchange ownership of a console terminal.
In effect, this call
combines a detach of the attached job with a reattach of the detached
job.
Its purpose is to allow detached programs to temporarily obtain
ownership of a console to perform certain functions at the request of
the program running at that terminal.
Once these functions are
performed, ownership of the console can then be returned to the
requesting program.
This call requires no privileges and can be executed by either a
detached job or an attached job.
Both jobs must be running under the
same PPN.
If the caller is detached, the job specified must be
attached.
If the caller is attached, the job specified must be
detached.
If these conditions are met, the job that was attached will
be detached from its console, and the job that was detached will be
attached to that console.
This call does not affect open files or ownership of devices with one
exception:
any channels open on KB:.
These channels are affected
because the job that was detached now has its console back, and the
job that was attached no longer has a console.
The effect is the same
as an ordinary detach (with CLOSE option specified, see SYS call 7,
Detach) or reattach operation.

7-178

FO=7

Detach
(UU.DET)

Detach
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(7%), the detach code.

CHR$(J%+C%), where:
J% is the number of the job to detach:
J%=O%

Detach the calling job (also the case if byte 3
is not specified).

J%=1%-63%

Detach another job.

C% is the CLOSE flag:
C%=O%

Do not deassign the console or close its I/O
channels (also the case if byte 3 is not
specified) .

C%=128%

Deassign the console and close all I/O channels
on which the console is open after detaching the
job.

Data Returned
No meaningful data is returned.
Privileges Required
None

Detach your own job

JOBCTL

Detach another job

EXQTA

Detach the job even if the detached job quota is exceeded

7-179

Detach

FO=7
possible Errors
Meaning

ERR Value

?NO ROOM FOR USER ON DEVICE
There are no more job slots available, or no small
buffers to create the new job.

?ILLEGAL SYS{) USAGE
The job is already detached.

?NO BUFFER SPACE AVAILABLE
No small buffers are available for a context buffer
to create the new job.

?QUOTA EXCEEDED
You exceeded the detached job quota.

Discussion
To use this call, you need to understand the concept of terminal
ownership.
See the introduction to the Attach SYS call (SYS 6) for
more information on terminal ownership.
This call disassociates the calling job or another job from its
console keyboard.
The following sample program segment prints a
message and detaches itself from the keyboard:
100
110

PRINT "DETACHING ... "
! NOTIFY THE USER
A$ = SYS(CHR$(6%) + CHR${7%))
! DO THE DETACH

It is possible for a job to be detached while still maintaining
ownership of a terminal.
By executing this call, a job can detach itself from its console
terminal, or, if it has the required privilege, detach another
attached job from its console terminal.
After a job is placed in the
detached state, it runs like any other job on the system, but it does
not have access to its console terminal (on channel 0).
The detached
state is advantageous for noninteractive jobs.
By detaching, the job
frees a terminal for other use and becomes immune from interruption by
CTRL/C.
(See Chapter 4 for a description of MODE 16%, which prevents
CTRL/C interruption and hibernation.)
The values passed in byte 3 specify the job number to detach and
determine whether I/O channels are closed.
The following paragraphs
explain how the "close flag" (bit 7, value 128%) works.
If the detached job has its console terminal open on some nonzero
7-180

Detach
FO=7
channel, and 128% is not specified in byte 3 of the data passed, the
job can perform I/O on the keyboard from which it is detached.
However, it must use a nonzero I/O channel. In addition, a terminal
that is previously assigned remains assigned. If the detached job
tries to perform I/O on channel 0, the system places the job in the
hibernate stateu (A job in the hibernate state is suspended until
some user attaches to it.) A detached job that performs I/O to the
d4~tached keyboard on a nonzero channel, however, retains control of
the terminal (I/O is performed). Thus, the terminal is not free for
other use.
Specifying 128% in byte 3 of the data passed forces the system to
disassociate the terminal from any nonzero I/O channel being used.
This value also forces deassignment of the console terminal if it was
previously assigned. The disassociation that the detach call performs
thus includes all channels on which the console terminal is open. The
keyboard from which the job is detached is explicitly forced to be
free. An attempt by the detached job to perform I/O to the terminal
on the nonzero channel causes the system to place the job in the
hibernate state (or if the terminal was opened with MODE 16%, returns
the error 11/0 to detached keyboard).
If a job running under the control of a DeL command file detaches
itself using this call, a new job is created at that terminal, logged
in to the same account, and execution of the command file continues
with the new job. The call creates a new job only if the terminal is
closed (with the close flag) or is not open on any channel. See the
RSTS/E Guide to writing Command Procedures for more information on
writing DeL command files.

7-181

Change Quota, Password, Expiration Date
FO=8
(UU.CHU)
Change Quota, Password, Expiration Date
This call has five subfunctions:
o

Change Quota (New Format)/Expiration Date/Password (Old
Format)

Change Quota (Old Format)/Expiration Date/Password (Old
Format)

Set Password (New Format)

Kill Job

Disable Terminal

Change Quota (New Format)/Expiration Date/password (Old Format)
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(8%), the change quota, password, kill job, and disable
terminal code.

Detached job quota.

Flag byte.

5-6

Reserved; should be O.

7-8

PPN.

9-12

New password in Radix-50 format (pre-V9.0 format). All
zeros means no change.
See the next section, "Set
Password," for a description of how to set passwords using
v9.0 format.

13-14

Logged-out quota (LSB).

15-16

Expiration date, in RSTS/E internal format:
(day of year) +
[(number of years since 1970) * 1000]. CHR$(O%) indicates
no change.

17-18

Logged-in quota (LSB).

See the Discussion for the values you can use.

Zero for both values means the current account.

7-182

Change Quota, Password, Expiration Date
FO=8
19

Logged-in quota (MSB).

Logged-out quota (MSB).

CHR$(255%) to change any quota (see byte 4).
CHR$(O%) to
indicate that no change is to be made to the quota.

Reserved; should be

23-24+

Device name.

25+

unit number.

26+

unit number flag.

27-28

Must be CHR$(O%).

29-30

Reserved; should be O.

If no device name is specified, SY:

is used.

Data Returned
No meaningful data is returned.
Privileges Required
GACNT

Change quota or expiration date within the group

WACNT

Change any quota or expiration date

Possible Errors
Meaning

ERR Value

?BAD DIRECTORY FOR DEVICE
The account does not have all the necessary
directory structures.

?ILLEGAL FILE NAME
You specified a password that was less than six
characters. Or, you specified a password that
contained illegal characters (such as ?).

?CAN'T FIND FILE OR ACCOUNT
The account is not present on the disk specified.

7-183

Change Quota, Password, Expiration Date
FO=8
?NOT A VALID DEVICE
The device specification supplied in bytes 23
through 26 is illegal because the unit or its type
is not configured on the system.

?ILLEGAL SYS() USAGE
The device specified is not a disk.

?MISSING SPECIAL FEATURE
You issued the new format calIon a disk with RDSl.1
or RDSO.O disk structure (pre-version 9.0).
The
call returns this error if you:

Specify a logged-out quota of 0 or between 65536
and 16777214 (2A24-2)

Specify a logged-in quota other than 16777215
( 2A 24 - 1 )

Discussion
You can use this call to perform any or all of the following
operations:
o

Change logged-in and logged-out disk quotas for the account.
These quotas define the amount of disk space an account can
use while logged-in and logged-out, as well as the maximum
amount of disk space a logged-in account can use.

Change a user's password using the old format.
To change a
password using the new 14 character ASCII format, see the
next section, "Set Password."

Byte 4 specifies the flag byte.
values:
Value

0%
1%
2%
4%
8%
16%
32%
64%
128%

This byte can contain the following

Meaning
Change disk quota using old format (see next subfunction)
Change logged-out quota (new format)
Change logged-in quota (new format)
Reserved
Change detached job quota (new format)
Reserved
Reserved
Reserved
Change disk quota using new format

7-184

Change Quota, Password, Expiration Date
FO=8
Bytes 13, 14, and 20 specify the logged-out disk quota.
Bytes 17, 18,
and 19 specify the logged-in quotas.
Quota values must be in the
range 0 to 16777215 (2 24-1).
On pre-version 9.0 disks, logged-out
quotas must be in the range 1 to 65535 or 16777215, and the call
rejects logged-in quotas other than 16777215.
A

7-185

Change Quota, Password, Expiration Date
FO=8
Change Quota (Old Format)/Expiration Date/password (Old Format)
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(8%), the change quota, password, kill job, and disable
terminal code.

Reserved; should be O.

CHR$(O%), to indicate the old format quotas.

5-6

Reserved; should be O.

7-8

PPN.

9-12

New password in Radix-50 format (pre-V9.0 format).
All
zeros means no change.
See the next section, "Set
Password," for a description of how to set passwords using
V9.0 format.

13-14

CHR$(N%)+CHR$(SWAP%(N%)), where N% is the number of blocks
for the quota.
If N% is zero, the quota is unlimited (see
byte 21).'

15-16

Expiration date, in RSTS/E internal format:
(day of year) +
[(number of years since 1970) * 1000].
CHR$(O%) to indicate
no change.

17-20

Reserved; should be O.

CHR$(255%) to change the logged-out disk quota (see bytes
13-14).
CHR$(O%) to indicate that no change is to be made
to the quota.

Reserved; should be

23-24+

Device name.

25+

Unit number.

26+

Unit number flag.

27-28

Must be CHR$(O%).

29-30

Reserved; should be

Zero for both values means the current account.

o•

If no device name is specified, SY:

o•

7-186

is used.

Change Quota, Password, Expiration Date
FO=8
Data Returned
No meaningful data is returned.
privileges Required
GACNT

Change quota or password within the group

WACNT

Change any quota or passwo'rd

Possible Errors
Meaning

ERR Value

?ILLEGAL FILE NAME
You specified a password that was less than six
characters.
Or, you specified a password that
contained illegal characters.

?CAN'T FIND FILE OR ACCOUNT
The account is not present on the disk specified.

?NOT A VALID DEVICE
The device specification supplied in bytes 23
through 26 is illegal because the unit or its type
is not configured on the system.

?ILLEGAL SYS() USAGE
The device specified is not a disk.

Discussion
You can use this call to perform any or all of the following
operations:
o

Change logged-out disk quotas for the account using the old
format.

Change a user's password using the old format.
To change a
password using the new 14 character ASCII format, see the
next section, "Set Password."

Change the expiration date for the account.

Bytes 13-14 specify the logged-out disk quota.
Quota values must be
in the range 0 to 6S535. A value of 0 means unlimited; for RDSI.I
disks, this is converted into 16777215 (2 24-1).
A

7-187

Set password (New Format)
FO=8
Set Password (New Format)
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(8%), the change quota, password, kill job, and disable
terminal code.

3-4

Reserved; should be O.

5-6+

PPN.

7-20

New password as 14 bytes of ASCII data (V9.0 format), padded
with nulls if necessary.
If the first byte is 0, the
password information is deleted, signifying an account that
cannot be logged in to in any way.
See Discussion.

21-22

Reserved; should be O.

23-24+

Device name.

25+

Unit number.

26+

unit number flag.

Must be CHR$(255%).

Must be CHR$(O%).

29-30

Reserved; should be

Zero for both values means the current account.

If no device name is specified, SY:

o•

Data Returned
No meaningful data is returned.
Privileges Required
GACNT

Change any password within the group

WACNT

Change any password

7-188

is used.

Set Password (New Format)
FO=8
possible Errors
ERR Value

Meaning
?ILLEGAL FILE NAME
You specified a password that was less than six
characters. Or, you specified a password that
contained illegal characters (such as ?).

?CAN'T FIND FILE OR ACCOUNT
The account is not present on the disk specified.

?NOT A VALID DEVICE
The device specification supplied in bytes 23
through 26 is illegal because the unit or its type
is not configured on the system.

?ILLEGAL SYS() USAGE
The device specified is not a disk.

Discussion
You can use this call to set a 14 character ASCII password for an
account~
Passwords can contain any printing character except question
mark (?), including punctuation and supplemental characters. The
system treats lower- and uppercase characters as equivalent.
If the
account is set up to have a readable password (/LOOKUP qualifier on
the SET ACCOUNT or CREATE/ACCOUNT command), then the password must be
6 characters long and can contain only letters and digits.
You specify the new password in bytes 7-20.
If the first byte is 0,
the system deletes the password information, in effect changing the
account into a no-user account.
See the RSTS/E System Manager's Guide
for more information on accounts.

7-189

Kill Job
FO=8
Kill Job
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(8%), the change password/quota, kill job, and disable
terminal code.

CHR$(N%), where N% is the number of the job to kill, or 0 to
kill the caller's job.

4-26

Reserved; should be O.

Must be CHR$(O%); this byte differentiates the kill job call
from the disable terminal call.

Must be CHR$(255%).

29-30

Reserved; should be

Data Returned
No meaningful data is returned.
privileges Required
JOBCTL
Possible Errors
Meaning

ERR Value

?ILLEGAL SYS() USAGE
The job number specified is invalid.

7-190

Kill Job
FO=8
Discussion
This call provides the normal way for a privileged job to terminate
itself under programmed control.
The job must execute the Kill a Job
SYS call with job number specified as O.
The kill does all of the
cleanup that the Logout SYS call (SYS 5) does and can be executed
under program control by any privileged program.
Note that if you do not have JOBCTL privilege, you use the Logout call
instead of this call to kill your current job.
See SYS callS,
Logout.

7-191

Disable Terminal
FO=8
Disable Terminal
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(8%), the change password/quota, kill job, and disable
terminal code.

CHR$(N%), where N% is the keyboard number of the terminal to
disable.

4-26

Reserved; should be O.

Must be CHR$(255%) to differentiate this call from the kill
job call.

Must be CHR$(255%).

29-30

Reserved; should be O.

Data Returned
No meaningful data is returned.
Privileges Required
HWCTL
Possible Errors
Meaning

ERR Value

?ILLEGAL SYS() USAGE
Keyboard number is greater than the number of
terminals on the system; keyboard number corresponds
to a line used by a pseudo keyboard; or the terminal
is currently opened or assigned by a job.

7-192

Disable Terminal
FO=8
Discussion
This SYS call disables a keyboard line. After the system executes
this function, it does not process or echo input from the disabled
keyboard. The system also ignores any output for the disabled
keyboard. Once a keyboard is disabled, it remains disabled until the
next time-sharing session is started or the line is reenabled with the
Set System Defaults SYS call (SYS 34).
This call cannot disable the system console terminal (KBO:).
Disabling KBO: is a dangerous operation because the SHUTUP system
program only runs on that terminal.
To disable a terminal (other than KBO:) for more than one time-sharing
session, use the DeL SET command (see the RSTS/E System Manager's
Guide).

7-193

Return Error Message
FO=9
(UU.ERR)
Return Error Message
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(9%), the return error message code.

CHR$(E%), where E% is the RSTS/E ERR variable number and is
between 0 and 127.

4-30

Reserved; should be O.

Data Returned
Meaning

Bytes
1

The current job number times 2.

If job is attached, current keyboard number times 2 of
terminal to which job is attached.
If job is detached, the
logical complement (NOT) of keyboard number times 2 from
which job detached.

3-30

Error message.
If message is less than 28 characters,
remainder is padded to length 28 with CHR$(O) characters.

Privileges Required
None.
Possible Errors
None.
Discussion
This call extracts error message text from the error message file
installed during the current time-sharing session or from the default
error message file if an error message file is not currently
installed.
The text is associated with the value of the ERR variable
passed as byte 3 of the call.
The number in byte 2 of the returned
string is two times the number of the keyboard on which the job is
running.
This is an exception to the conventional contents of byte 2,
7-194

Return Error Message
FO=9
which usually contains internal data. A sample use of the call is to
print the system header line containing the system name and the local
installation name.
To do this, use the character representation of
the ERR value of CHR$(O%) in the call.
The following sample program extracts and prints the message
associated with an error number that you supply:
10

INPUT "ERROR NUMBER";E%
\S$=SYS(CHR$(6%)+CHR$(9%)+CHR$(E%»
\SI$=CVT$$(RIGHT(S$,3%),4%)
\PRINT SI$
\PRINT FOR 1%=1% TO 2%
\GOTO 10
32767 END

RUNNH
ERROR NUMBER? 0
RSTS V9.0 SYSTEM #880
To extract the message text from the data returned by the SYS call,
the program executes a RIGHT() function to discard the first two
bytes.
The CVT$$() function discards any excess null characters.
The
first character of the text (except for message number 0) is the
severity indication.
See Appendix C for more information.
Error numbers used in the call can include those associated with
recoverable and nonrecoverable errors.

7-195

Allocate Device/Assign User Logical
FO=IO
(UU.ASS)
Allocate Device/Assign User Logical
This call has two subfunctions:
o

Allocate/Reallocate Device

Assign User Logical

Allocate/Reallocate Device
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(10%), the allocate/reallocate device and assign user
logical code.

3-4

Reserved; should be O.

5-6

If bytes 7 through 10 are 0, these bytes contain the
assignable PPN (@).
If bytes 7 through 10 contain a logical device name, these
bytes contain the PPN assigned to that logical device.

7-10

To allocate a device, bytes 7 through 10 must be O.
To reallocate a device, byte 7 is the job number to which
the device is reallocated.
Bytes 8 through 10 must be O.

11-12+

Either DOS or ANS (in Radix-50 format) to specify DOS or
ANSI label format for the magnetic tape drive.

13-16

Reserved; should be O.

17-18

CVT%$(SWAP%(-32767%», to allocate a device that is
currently allocated to another user.
This use requires
HWCTL privilege and requires that the target device not be
open.
If you do not want this operation, bytes 17 and IB
are o.

19-22

Reserved; should be O.

23-24+

Device name.

7-196

AllocatejReallocate Device

FO=lO
25+

unit number.

26+

unit number flag.

27-30

Reserved; should be O.

I)ata Returned
Bytes

Meaning
Not used.

1-2
3

The job number of the previous owner of the device. A value
of 0 indicates the device was not previously allocated.

4-30

Not used.

Privileges Required
DEVI"CE

Allocate a restricted device

HWCTL

Reallocate a device to a job in another account, or seize a
device

l?ossible Errors
ERR Value

Meaning
?ACCOUNT OR DEVICE IN USE
During a reallocate call, the specified device is
currently open or has an open file.

A VALID DEVICE
The device name specified in bytes 23 and 24 is a
logical device name for which a physical device is
currently not assigned.

NOT AVAILABLE
The device specified in bytes 23 through 26 exists
on the system but the operation fails for one for
the following reasons:

~?NOT

~?DEVICE

The device is currently reserved by another job
(see bytes 17 and 18).

The user does not have sufficient privilege to
own the device.
For example, a user without
HWCTL privilege tried to allocate a device that
7-197

Allocate/Reallocate Device

FO=lO
is currently allocated to another user.
o

The device or its controller is disabled.

The device is a keyboard line for a pseudo
keyboard only.

?PROTECTION VIOLATION
You do not have sufficient privilege to perform
either of these operations:
o

Allocate or reallocate a restricted device.

Reallocate a device to a job that is logged in
to an account other than your current account.

?ILLEGAL NUMBER
An attempt is made to transfer control to a
nonexistent job. This error can occur only during a
reallocate call.

Discussion
The Allocate/Reallocate call uses bytes 17 and 18 to allocate or
reallocate a device that is currently allocated by another job.
For
the call to be successful, the caller must have HWCTL privilege, the
target device must not be open, and the current owner cannot be
performing a directory operation on that device.
The allocate call r~serves a physical device to a job; the reallocate
transfers assignment of a currently owned device to another job.
(The
SET DEVICE/RESTRICT command designates that certain devices are
restricted and therefore require DEVICE privilege to be allocated.)
The action is equivalent to the DCL ALLOCATE command (see the RSTS/E
System User's Guide). Users without HWCTL privilege can only
reallocate a device to a job running under the same PPN as the caller.

7-198

Allocate/Reallocate Device
FO=lO
Example
10
20
30

A$= SYS(CHR$(6%)+CHR$(10%)+STRING$(20%,0%)+
"LP" + CHR$ (1%)+CHR$(255%»
! ALLOCATE LP1: TO CURRENT JOB.
INPUT "ALLOCATE LP1: TO WHICH JOB"; X%
A$= SYS(CHR$(6%)+CHR$(10%)+STRING$(4%,0%)+
CHR$(X%)+CHR$(0%)+STRING$(14%,0%)+
"LP"+CHR$(1%)+CHR$(255%»
! REALLOCATE LP1: TO JOB # X%.

7-199

Assign User Logical

FO=lO
Assign User Logical
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(lO%), the assign/reassign device and assign user
logical code.

3-4

Reserved; should be O.

5-6+

The PPN to be assigned.

7-10

The logical device name (in Radix-SO format) to be assigned.

11-20

Reserved; should be O.

CHR$(2s5%) to enable protection code assignment (see byte
22).

The protection code to be assigned.

23-24+

Device name.
Device unit number.

26+

Unit number flag.

27-30

Reserved; should be O.

Data Returned
No meaningful data is returned.
Privileges Required
None.

7-200

Byte 21 must be 255.

Assign User Logical

FO=lO
PossiblE~

Errors
ERR Value

Meaning
?ACCOUNT OR DEVICE IN USE
During an assign call, more than four user logical
assignments are made (three, if you use a PPN).

'('NOT A VALID DEVICE
The device name specified in bytes 23 and 24 is a
logical device name for which a physical device is
currently not assigned.

Discussion
This call assigns logical device names, logical PPNs, and default
output protection codes.
To assign a user logical device name, bytes
7 through 10 must contain the logical device name and bytes 23 through
26 must contain a physical device name and unit number.
To assign a
user logical PPN, specify the number in bytes 5 and 6.
To assign a
user default protection code, specify the code in bytes 21 and 22.

7-201

Deallocate a Device or Deassign User Logical
FO=ll
(UU.DEA)
Deallocate a Device or Deassign User Logical
Data Passed
Meaning

Bytes

CHR$(6%), the SYS call to FIP.

CHR$(ll%), the code to deallocate a device or deassign user
logical.

3-4

Reserved; should be O.

5-6

For user logical,

-1 to deassign the default PPN.

For device deallocation, must be O.
7-10

For user logical, the logical device name (in Radix-50
format) to be removed.
otherwise, must be O.

11-20

Reserved; should be O.

For user logical, CHR$(255%) to enable protection code
removal. Otherwise, must be O.

Reserved; should be O.

23-24

For device deallocation, the device name to be deallocated.
For user logical, must be O.

For device deallocation, the device unit number to be
deallocated.
For user logical, must be O.

For device deallocation, the unit number flag.
logical, must be O.

27-30

Reserved; should be O.

Data Returned
No meaningful data is returned.
Privileges Required
None.

7-202

For user

Deallocate a Device or Deassign User Logical
FO=ll
Possible Errors
Meaning
?NOT A VALID DEVICE
The device or device type specified in bytes 23
through 26 is not configured on the system.
This
error can occur only on device deallocation calls.

ERR Value
6

Discussion
This call deassigns logical device names, logical PPNs, and default
output protection codes.
To deassign a logical device name, specify
the name in bytes 7 through 10.
To deassign a PPN, specify the number
in bytes 5 and 6.
To deassign a user logical protection code, specify
255 in byte 21.
Note that if these bytes do not contain specific
deassignments, the call deassigns all user logical device names, PPN,
and protection code assignments.
The Deallocate a Device call performs the same action as the
DEALLOCATE DCL command (see the RSTS/E System User's Guide).
For
example, the following statement deallocates line printer unit 1,
which is allocated to the current job:
10

A$ = SYS(CHR$(6%)+CHR$(ll%)+STRING$(20%,0%)+
"LP"+CHR$(l%)+CHR$(255%»
! DEALLOCATE LP1:

7-203

Deallocate All Devices
FO=12
(UU.DAL)
Deallocate All Devices
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(12%), the deallocate all devices code.
Reserved; should be O.

3-30

Data Returned
No meaningful data is returned.
Privileges Required
None.
Possible Errors
None.
Example
The following statement deallocates all devices currently allocated to
the job:
10

= SYS(CHR$(6%) + CHR$(12%»

7-204

FO=l3

Zero a Device
(UU.ZER)

Zero a Device
Itata Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(13%)v the zero a device code.

For disk, CHR$(N%), where N% determines the action taken on
the files and the UFD:
0%

Delete all files except those write-protected against
owner.; retain UFD.

255% Delete all files regardless of their protection codes;
delete UFD (requires GACNT or WACNT privilege).
For magnetic tape and DECtape, set this byte to O.

Reserved; should be O.

5-6+

PPN.

7-10+

volume ID" in two Radix-SO words, for volume label (ANSI
format magnetic tape only).

11-22

Reserved; should be O.

2:3-24+

Device designator (disk, magnetic tape, or DECtape). If no
device is specified, SY: (the public structure) is used.

25+

Uni t

26+

unit number flag.

27-30

Reserved; should be O.

See Discussion.

numbE~ r .

Data Returned
No meaningful data is returned.

7-205

Zero a Device
FO=l3
Privileges Required
None

Zero your own account if it does not reside on a restricted
device

GWRITE

Zero any account in the group

WWRITE

Zero any account

SYSIO

Zero any account in group [0,*] (with WWRITE)

GACNT

Deallocate UFO of any account in the group

WACNT

Deallocate UFO of any account

DEVICE

Access restricted devices

Possible Errors
Meaning

ERR Value

?ILLEGAL FILE NAME
The specified device is a magnetic tape with ANSI
format, and the volume ID specified in bytes 7-10 is
either missing or invalid.

?CAN'T FIND FILE OR ACCOUNT
The account specified in bytes 5 and 6 does not
exist on the device and unit number specified in
bytes 23-26.

?NOT A VALID DEVICE
The device or its type specified in bytes 23 through
26 is not configured on the system.

?DEVICE NOT AVAILABLE
The specified device in bytes 23 through 26 exists
on the system but the attempt to zero it is
prohibited for one of the following reasons:
a file
is currently open on the device, the device is
currently reserved by another job, or the device or
its controller has been disabled by the system
manager.

?PROTECTION VIOLATION
You attempted to zero an account other than your own
without sufficient privilege.

?ILLEGAL SYS() USAGE
Bytes 5 and 6 do not contain a valid PPN.

7-206

Zero a Device
FO=l3
?DEVICE NOT FILE STRUCTURED
The specified device does not allow access by file
name.

This call also returns device-dependent errors such as ?Disk pack not
mounted (ERR=21) and ?Magtape select error (ERR=39).
Discussion
Thi s call zeros DEC tape , magne.Qc tape, or di sk.
For DECtape or magnetic tape, this call zeros the entire medium.
On
DECtape, this call also clears the directory.
The section
"Initializing Magnetic Tapes," in Appendix A, describes what actions
occur when magnetic tape is zeroed.
For disk, you can delete files in a directory.
If you do not have
sufficient privilege you can specify only the current directory, and
you cannot delete the UFD.
Furthermore, if your account resides on a
restricted disk, you must have the DEVICE privilege.
If you have GACNT privilege, you can delete files and the UFO for any
account in your group.
If you have WACNT privilege, you can delete
the files and the UFO of any account.
Note that this call does not
delete accounts.
To delete an account, use the Oelete User Account
call, SYS 1.
Bytes 5 and 6 must contain a valid PPN.
The system returns the error
?Illegal SYS() usage (ERR = 18) if bytes 5 and 6 are zero.
The value in byte 3 determines what happens to the files and the UFO.
A value of 0% in byte 3 deletes files in a directory that are not
write-protected against the owner and retains the UFO. A value of
255% in byte 3 deletes all files in a directory, regardless of
protection code.
In addition, if you have the appropriate GACNT or
WACNT privilege, the~ value 255% in byte 3 deletes the UFO (deallocates
the disk space that was allocated to the UFD).
The UFD is always
retained for insufficiently privileged users.
Note that you should not normally use the option to delete the UFD.
When the account is created, the UFO is often placed in a specific
location on the disk to optimize disk performance.
Oeleting the UFD
causes any prior placement to be lost.

7-207

Zero a Device
FO-13

Example
10
20

PO%=10%
\Pl%=20%
A$=SYS(CHR$(6%)+CHR$(13%)+STRING$(2%,0%)+
CHR$(Pl%)+CHR$(PO%)+STRING$(24%,0%))
ZERO [10,20] ON THE SYSTEM.
IF NONPRIVILEGED, CURRENT ACCOUNT
! MUST BE [10,20]
! UFO AND ANY FILES WRITE-PROTECTED
! AGAINST OWNER ARE RETAINED.
A$=SYS(CHR$(6%)+CHR$(13%)+STRING$(20%,0%)+
"MT"+CVT%$(O%))
! ZERO MT:

7-208

Read or Read and Reset Accounting Data
FO=14
(UU.RAD)
R.ead/Read and Reset Accounting Data
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(14%), the read or read and reset accounting data code.

3-4

CHR$(I%)+CHR$(SWAP%(I%)), where I% is the index number of
the account to read.
I% can be one of the following values:

5-6

Read the account specified in bytes 7 and 8.

Nonzero

Search for an account based either on this index
entry or on a wildcard PPN search.
The value of
W% in byte 9 controls which function the call
performs.
See the table in the Discussion for a
summary of legal byte values.

CHR$(R%), where R% can be one of the following values:
0%

Indicates read-only.

Nonzero

Indicates read and reset.
See the Discussion for
a list of the accounting data that gets reset.
If
the job executing this call does not have the
appropriate privileges, the system does not access
this word and performs only a read operation.

7-8

PPN.
If bytes 7 and 8 are 0%, data for the current account
is returned.
If W% in byte 9 is 2%, bytes 7 and 8 can be
255% to indicate that the PPN contains wildcards.
See the
section "Project-Programmer Number" for a description of
each byte; see the table in the Discussion for a summary of
legal values.

CHR$(D%+W%+Q%+P%), where:
D% indicates whether to return the number of blocks owned by
the account:
D%=O%

Call returns number of blocks used.

D%=l%

Call does not return this data.

7-209

Read or Read and Reset Accounting Data
FO=14
W% indicates whether the PPN in bytes
7 and 8 contains wildcards:
W%=O%

PPN corresponds to a real account.

W%=2%

PPN contains a wildcard.

Q% indicates the type of accounting information to return:
Q%=O%

Call returns general accounting information.

Q%=4%

Call returns disk quota information.

P% indicates whether to return a protection violation if a
caller attempts to perform a function without sufficient
privilege:
P%=O%

Do not perform a privilege check.
The call
performs a read-only lookup on the caller's PPN.

P%=8%

Perform a privilege check and return the error
?Protection violation (ERR=lO) if the caller does
not have sufficient privilege.

10-22

Reserved; should be O.

23-24+

Device name; must be a disk.
SY:
(the public structure).

25+

unit number.

26+

unit number flag.

27-30

Reserved; should be O.

7-210

A zero in both bytes indicates

Read or Read and Reset Accounting Data
FO=14
Data Returned when 0% in byte 9

= 0% (accounting information format)

Bytes

Meaning

The current job number times 2.

The number of clusters used to store the User File Directory
(UFD).

3-4

Same as bytes 3-4 in data passed.

5-6

Number of blocks used.
The maximum number returned is 65535
blocks.
If more than 65535 blocks are in use, only 65535 is
returned.
The quota information is accurately returned in
the quota information format of this call.

7-8

PPN of the account read.

9-12

Password of the account read, in Radix-50 format.
If the
password is marked as not readable (/NOLOOKUP), 0 is
returned.
This data is returned only if the caller has the
appropriate privileges (GA.CNT for group; WACNT for all).

13-14

Low-order word (16 bits) of the CPU time (in tenths of
seconds) used by the account.

15-16

Connect time (in minutes) used by the account.

17-18

Low-order word (16 bits) of kilo-core ticks used by the
account.

19-20

Device time (in minutes) used by the account.

21-22

High-order bits for CPU time and kilo-core ticks.
See the
Discussion for an explanation of how the values are stored.

23-26

Same as bytes 23-26 in data passed.

27-28

Logged-out disk quota in number of blocks; 0 means unlimited
quota.
This value is 16 bits~ 24 bit quotas are returned
by the quota information format of this call.

User file directory cluster size.

Not used.

7-211

Read or Read and Reset Accounting Data
FO=14
Data Returned when Q% in byte 9 = 4% (quota information format)
Bytes

Meaning

The current job number times 2.

Reserved.

3-4

Same as bytes 3-4 in data passed.

5-6

Reserved.

7-8

PPN of the account read.

9-10

Logged-out quota (LSB).

11-12

Logged-in quota (LSB).

Logged-in quota (MSB).

Logged-out quota (MSB).

Reserved.

Current usage (MSB).

17-18

Reserved.

19-20

Current usage (LSB).

21-22

Count of open files, and logged in jobs in that account.
Open files = low 10 bits, number of jobs = high 6 bits.

23-26

Device name and number as passed.

27-30

Reserved.

Privileges Required
None

Read information for your own account

GACNT

Read or read and reset information for accounts in the group

WACNT

Read or read and reset information for all accounts

7-212

Read or Read and Reset Accounting Data
FO=14
Possible Errors
Meaning

ERR value

?BAD DIRECTORY FOR DEVICE
The account does not have all the necessary
directory structures.

?CAN'T FIND FILE OR ACCOUNT
The PPN specified does not exist on the disk, the
index specified is greater than the number of
accounts on the disk, or you specified an illegal
combination of values in bytes 3-4, bytes 7-8, and
byte 9.

?PROTECTION VIOLATION
The caller does not have sufficient privilege to
perform the indicated function.

?ILLEGAL SYS() USAGE
Device specified is not a disk.

Discussion
This SYS call performs the following functions:
o

Looks up accounts on a disk and reads accounting data.
can:

You

Specify an individual account
Specify a search based on an index number
Specify a search based on a wildcard PPN match
o

Looks up accounts on a disk and reads and resets accounting
You can use the same three methods to control the
account search.
This call resets the following accounting
data to zero:

data~

CPU time
Connect time
Kilo-core ticks
Device time
o

Returns information about the number of blocks used and the
logged-out disk quota.
If you are using the new format qisk
quotas feature (V9.0), this call returns information about·
the logged-in and logged-out quotas, as well as the current
usage.
7-213

Read or Read and Reset Accounting Data
FO=14
Note that this system function call does not always perform a password
lookup.
This affects programs that currently look up passwords for
the purpose of logging in to a given account.
These programs should
use the "spawn logged in" subfunction of the create a Job SYS call
(SYS 24).
Bytes 3-4, bytes 7-8, and byte 9 control how the call looks up
accounts.
Table 7-7 lists the legal combinations of byte values and
their corresponding results. Any other combination of values returns
the error ?Can't find file or account (ERR=5).
Table 7-7:

SYS 14 Legal Byte Value Combinations

-1-- - - - - - - - - -

-+- - - - - - - --/-- - - - - - - - - - -+- _ .. - - - - - - _ .. - - - - - - .. - - - - - - - - - - - - - - - --+

I Bytes 3-4
:
1%

I Byte 9 I Bytes 7-8 I
:
W%
:
PPM:

I
Account Accessed

+- - - - - - - - - - -+- - - - - - - -+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - .. - - - - - - - - - - - - - - - --+
I
I 0
I
I 0

Current account

PPN

Account specified by PPN

Nonzero

Forced to
[255,255]

The 'Ith' account, where I is the
value specified in bytes 3-4

Nonzero

[255,y]

The 'Ith' account matching [*,y],
where I is the value specified in
bytes 3-4

[x,255]

The 'Ith' ac~ount matching [x,*],
where I is the value specified in
bytes 3-4

[255,255]

The 'Ith' account, where I is the
value specified in bytes 3-4

+- - - - - - - - - - -+- - - - - - - -+- - - - - - - - - - -+- - - - - - - - - - - ,- - _ .. - -. - - - - - - - _ .. - - - - - _ .. _+

If you want to look up all accounts on a disk, start the index (bytes
3 and 4) at I and increment it for each call.
Note that this call works differently for users without the
appropriate GACNT or WACNT privilege.
If a job without sufficient
privilege executes this call, the system forces bytes 3 through 8 in
the data passed to the values shown:
Byte

Value

3-4

Action
Look up the account specified in bytes 7 and
8.

7-214

Read or Read and Reset Accounting Data
FO=14
5-6

Read-only.

7-8

current .PPN

Look up data for current PPN.

A job with the appropriate privileges can both read and reset
accounting data~
GACNT privil~ge grants access to any account in the
group.
WACNT privilege grants access to all accounts.
You can instruct the call to perform a privilege check by setting P%
in byte 9.
This allows a program to make sure that the system is
performing the proper function, rather than just performing a lookup
on the caller's account.
If an appropriately privileged job executes this call and bytes 5 and

6 of the data passed are nonzero, the following account information is
read and reset to zero:
o

CPU time

Kilo-core ticks

Connect time

Device time

Because the system must scan the entire directory to return the number
of blocks owned b~ an account, significant extra processing time is
required to obtain usage information.
This applies to RDSI.I and
RDSO.O format disks.
If you do not need this information, specify a
value of I for D% in byte 9 to speed up the execution of this call.
For RDSl..2 format disks, no time is saved by using this option.
The word returned in bytes 21 and 22 holds the high-order bits of CPU
time and kilo-core ticks.
The bottom ten bits of this word apply to
kilo-core ticks, and the top six bits apply to CPU time.
Figure 7-3
is a graphic representation.
bit

10 9

[High -Order Part
of CPU Time

Figure 7-3:

High-Order Part
of KCT

MK-00037-01

High-Order Bi ts of CPU Time and KCTs

7-215

Directory Lookup
FO=15
FO=17
Directory Lookup
This section describes the SYS calls that look up file specifications
under program control. Although only two codes are available, four
different operations are possible:
o

Directory lookup on index (SYS 15)

Special magnetic tape directory lookup (SYS 15)

Disk directory lookup by file name (SYS 17)

Disk wildcard directory lookup (SYS 17)

As a result, four descriptions appear in this section.
The four operations return data in the following format:
Data Returned
Bytes

Meaning

The current job number times 2.

Not used.

3-4

Same as bytes 3-4 in data passed.

5-6

PPN (if applicable) of the file read.
these bytes return the value passed.

7-10

File name in Radix-50 format.
See the section "Unpacking
the Returned Data," earlier in this chapter for a
description of converting a string in Radix-50 format.

11-12

File type in Radix-50 format.

13-14

Length in blocks. Not used for Special Magnetic Tape
o.irectory Lookup call (SYS 15); Least Siqnificant Bits (LSB)
for files larger than 65535 blocks.

Protection code of the file.

The Most Significant Bits (MSB) of the file size. If a
nonzero number is returned, it indicates that the file size
is greater than 65535 blocks.
(The Special Magtape
Directory Lookup call (SYS 15) does not return this
information.)

7-216

For magnetic tape,

Directory Lookup
FO=l5
FO=l7
17-18

For disk, the date of last access; for DEC tape and magnetic
tape, returns the date of creation.
(Note that the system
manager can use the DSKINT initialization option on a
particular disk to change the meaning of date of last access
to date of last modification.)

19-20

The date of creation for disk.

21-22

The time of creation for disk; for DOS magnetic tape, the

PPN.
23-26

Same as data passed.
byte.)

27-28

For disk, the file cluster size; for tape, not used.

Number of entries returned:
returned for SYS 17.)

The USTAT byte from the UFD Name entry (returned for disk
only).

(Device name, unit number, and flag

for disk, 8; for tape, 6.

(Not

This byte contains the following internal flag information:
Value

Meaning

Reserved.

File is placed.

Some job has write access now.

File is open in update mode.

16%

File is contiguous; no extend available.

32%

No delete or rename allowed.

64%

Reserved.

128%

File is marked for deletion.

Keep this information in mind when you use the Directory Lookup calls:
o

If you specify either DECtape or magnetic tape, the monitor
allocates the related unit to the calling job while the call
executes.
The unit remains allocated after the call
completes.

When you repeatedly execute one of the calls on disk and
increment the index for each repetition, the execution time

7-217

Directory Lookup
FO=15
FO=17
increases for each successive call.
The increase occurs
because the monitor must read the file name blocks for indexes
numbered 0 through N-l before it reads the file name block for
index number N.
The process is the only one possible because
the index value has no other relationship to the actual disk
address of the file name block.
Note that the index scheme
for SYS call 16 (and 25) differs from that of SYS call 14.
The Open-Next SYS call (SYS 33), on the other hand, has
constant execution time throughout a directory, because it
uses an I/O channel to keep context information.
o

When you repeatedly execute one of the calls on a system disk
structure having multiple public disks, the increase in
execution time related to the index value is more critical.
Because the monitor cannot determine how many files exist on
each unit of a multiple public disk structure, it must read
the file name blocks of each unit beginning at unit 0 until
the Nth file is read.
Therefore, on such a system, you can
decrease the execution time by executing the call repeatedly
on each specific unit of the public structure (for example,
DKO:, DK1:, and upward) rather than on the entire public
structure (SY:).
The Open-Next SYS call (SYS 33) does not have this limitation.

7-218

Directory Lookup on Index
FO=15
(UU.DIR)
Directory Lookup on Index
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(15%), the directory lookup on index code.

3-4

CHR$(N%)+CHR$(SWAP%(N%», where N% is the index of the file
to read.
If N% is 0, the call returns the data for the
first file in the directory.
If N% is x, (some nonzero
value), the call returns the data for the x+l file in the
directory.
On magnetic tape, N% must be 0 to rewind the
tape before reading the first file.
See the Special
Magnetic Tape Directory Lookup SYS call (SYS 15) for a
description of magnetic tape operations.
On DECtape, N%
must be 0 to read the directory blocks from the tape before
reading the first file.
Subsequent calls, where N% is not
zero, read the directory from the BUFF.SYS file.

5-6

PPN of the directory to look up.
If both bytes are 0 and
the device specified in bytes 23 and 24 is disk, the call
returns information for the current account.
If both bytes
are 0 and the device specified in bytes 23 and 24 is
magnetic tape, the call returns information for each file
read.
If the device specified in bytes 23 and 24 is
DECtape, the call does not use these bytes but returns
information for each file read.
See the section,
project-Programmer Number, for a description of these bytes.

7-16

Reserved; should be O.

17-18

CHR$(M%)+CHR$(SWAP%(M%», where M% indicates whether to
return information about jiles that are marked-for-delete:
M%=O%
M%=16384%

Skip marked-for-delete files.
Return information about marked-for-delete files.

18-22

Reserved; should be O.

23-24+

Device name to look up.
If both bytes are 0, SY:
public structure) is used.

25+

unit number.

26+

unit number flag.

27-30

Reserved; should be O.
7-219

(the

Directory Lookup on Index
FO=l5
Data Returned
See the introductory section, "Directory Lookup," for a description of
the Data Returned.
Privileges Required
None

Look up files in your own directory, or in the directory of
another account to which you have read or execute access

GREAD

Look up files in the directory of any account in the group

WREAD

Look up files in the directory of any account

DEVICE

Access restricted devices

Possible Errors
Meaning

ERR Value

?CAN'T FIND FILE OR ACCOUNT
The account specified does not exist on the device
specified or no more files exist on the account (:the
index value is greater than the number of files on
the account).

?DEVICE NOT FILE STRUCTURED
The device specified in the call is not a
file-structured device.

The call also returns device-dependent errors such as ?Device hung or
write lacked (ERR=14) and ?Disk pack not mounted (ERR=2l).
Discussion
This call returns directory information on a file.
The DCL DIRECTORY
command uses the same routines as this call to print a directory
listing.
The order of the files in the listing is by index value from
the lowest to the highest.
You can therefore determine the index
value for a file by counting its position in a DIRECTORY listing and
subtracting one.
If the device specified is magnetic tape, the monit~r, after reading a
file label, skips to the end of the file on the tape· to determine the
number of blocks in the file.

7-220

Special Magnetic Tape Directory Lookup
FO=15
Special Magnetic Tape Directory Lookup
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(15%), the directory lookup on index code.

3-4

CHR$(N%)+CHR$(SWAP%(N%), where N% is the index of the file
to read. If N% is 0, the call rewinds the tape and returns
the data for the first file in the directory. If N% is some
nonzero value, the call returns the data for the next file
on the tape. See Discussion.

5-6

Both bytes are CHR$(255%) to execute the special magnetic
tape directory lookup.

7-22

Reserved; should be O.

23-24

Device name, must be a magnetic tape (not DECtape).

25+

unit numbE~r.

26+

unit number flag.

27-30

Reserved; should be O.

Data Re'turned
See the introductory section, "Directory Lookup," for a description of
the Data Returned.
Privileges Required
DEVICE
]~ossible

Access restricted devices
Errors
Meaning

ERR Value

?CAN'T FIND FILE OR ACCOUNT
No more files exist on the tape.

7-221

Special Magnetic Tape Directory Lookup
FO=15
?DEVICE NOT FILE STRUCTURED
The device specified in bytes 23 and 24 is not file
structured.

Discussion
The standard Directory Lookup on Index call (SYS 15) executed on a
magnetic tape unit causes the monitor to:
1.

Read one record from the tape (a label record).
The
procedure works for either DOS or ANSI labeling. The
description, however, does not distinguish between the,
different types of label records in ANSI processing.

Space the tape forward to the next end-of-file (EOF) or
end-of-volume (EOV) record and calculate the number of
records in the file.

Return the directory information if the account number of the
file matches the one specified in the call or if both bytes
in the account specification in the call are zero.

When the monitor executes the action that step 1 describes, you must
position the tape immediately before a label record.
Otherwise, ~he
operation generates an error or returns incorrect information.
In an application program that must search a tape for a specific file
and read each specific file found, the OPEN FOR INPUT statement
necessitates a rewind operation. When you execute an OPEN FOR INPUT
statement on a file-structured magnetic tape, the monitor:
1.

Reads one record from the tape (must be a label record).
If the read operation is successful, opens the file and
returns control to the user program.
If the read operation is unsuccessful and this is the
first label read, rewinds the tape and executes the
action that step 1 describes.

Returns an error if it detects the logical end-of-tape.

Skips to the end of the file and executes the action in step
1 if the label read does not match.

The required rewind operations consume time.
To avoid the rewind
operations, you can execute the special magnetic tape directory lookup
call and perform certain actions.
By specifying both bytes 5 and 6 as
7-222

Special Magnetic Tape Directory LOOK~Up
FO=lS
CHR$(255%) in the call, you cause the monitor to:
1.

Read a record from the tape, which must be a label record.

Backspace one record, which leaves the tape in a position to
read the label record again.

Return the directory information (except for file length) to
the program.

To take advantage of these special actions, you must determine from
the information returned whether the file is the one required.
Then
follow this procedure:

If the file is the one required, execute the OPEN FOR INPUT
statement using the file name and requesting no rewind.
The
action executes without a rewind because the tape is
positioned properly.
If the file is not required, issue the normal form of the
directory lookup function (Directory Lookup on Index, SYS 15)
with a nonzero index value in bytes 3-4.
This causes the
file to be skipped properly on either DOS or ANSI format
tape.
See Chapter 2 for more information.

After processing the required file, execute a CLOSE statement
to position the tape at the tape mark and to be ready to
execute another call.

The Special Magnetic Tape Directory Lookup call returns directory
information on each file read regardless of its account number.
However, the OPEN FOR INPUT statement must specify the correct account
number if the account number of the file does not correspond to the
current account number.

7-223

Diak Directory Lookup by File Name
FO=l7
(UU.LOK)
Disk Directory Lookup by File Name
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(17%), the disk directory lookup by file name and disk
wildcard directory lookup code.
See the next section for a
description of the Disk Wildcard Directory Lookup call.

3-4

Both bytes must be CHR$(255%).

5-6+

PPN of the file to look up.
current account is used.

7-10+

File name in Radix-50 format.

11-12+

File type in Radix-50 format.

13-22

Reserved; should be O.

23-24+

Device name; must be disk.
public structure) is used.

25+

unit number.

26+

unit number flag.

27-30

Reserved; should be O.

If both bytes are 0, the

If both bytes are 0, SY:

(the

Data Returned
See the introductory section,
the Data Returned.

"Direc~ory

Lookup," for a description of

The following bytes differ for this call.
Bytes

Meaning

23-26

If a name of the public structure, such as SY:
or DK:, is
passed, or if no device name is passed, then the actual
device where the file resides (for example, DB2:) is
returned.

29-30

The file identification index is returned.

7-224

Disk Directory Lookup by File Name
FO=17
Privileges Required
None

Look up files in your own directory, or in the directory of
another account to which you have read or execute access'

GREAD

Look up files in the directory of any account in the group

WREAD

Look up files in the directory of any account

DEVICE

Access restricted devices

Possible Errors
Meaning

ERR Value

?ILLEGAL FILE NAME
File name in bytes 7 through 10 is missing.

?CAN'T FIND FILE OR ACCOUNT
The device specified in bytes 23 and 24 is not a
disk, or the file specified does not exist on the
specified disk.

This error also occurs when the user does not have
sufficient privilege to read the specified file.
Discussion
~~his

call works only on disk files and returns directory information
for the specified file.
If you try to look up a file in some other
account, you must have read or execute access to the file for the
lookup to succeed.
If you do not have access rights, the call returns
the error ?Can't find file or account (ERR=5).

7-225

Disk Wildcard Directory Lookup
FO=l?
Disk Wildcard Directory Lookup
Data Passed
Same as that described in the previous section, "Disk Directory Lookup
by File Name," except for:
Meaning

Bytes
3-4

CHR$(I%) + CHR$(SWAP%(I%».
If I% is 0,
the data for the first file that matches
specification.
If I% is x (some nonzero
returns the data for the x + 1 file that
wildcard specification.

the call returns
the wildcard
value), the call
matches the

7-10+

Radix-50 representation of a wildcard file name
specification where an * character can replace the file name
or a? character can replace any character in the file
name.
Used with the file type in bytes 11 and 12 to create
a wildcard file specification.

11-12+

Radix-50 representation of a wildcard file type
specification, where an asterisk (*) character can replace
the file type or a question mark (?) character can replace
any character in the file type.
Used with the file name in
bytes 7 through 10 to create a wildcard file specification.

17-18

CHR$(M%)+CHR$(SWAP%(M%», where M% indicates whether to
return information about files that are marked-for-delete:
M%=O%

Skip marked-for-delete files.

M%=16384%

Return information about marked-for-delete files.

Data Returned
See the introductory section, "Directory Lookup," for a description of
the Data Returned.
Privileges Required
None

Look up files in your own directory, or in the directory of
another account to which you have read or execute access

GREAD

Look up files in the directory of any account in the group

7-226

Disk Wildcard Directory Lookup
FO=17
WREAD

Look up files in the directory of any account

DEVICE

Access restricted devices

Possible Errors
Meaning

ERR Value

?ILLEGAL FILE NAME
No file name appears in bytes 7 through 10.

?CAN'T FIND FILE OR ACCOUNT
The device specified in bytes 23 and 24 is not a
disk, or no match exists for the index value given
in bytes 3 and 4.

?DEVICE IS RESTRICTED
The disk is in the restricted state and the job does
not have DEVICE privilege.

Discussion
This call allows a program to supply a wildcard specification and to
increment an index value to get directory information for all
occurrences of files matching the wildcard specification.
The
following are typical wildcard specifications:
Specification

Meaning

FILE??*

All files with FILE as the first four characters in the
name and with any file type (including no file type).

*.BAS

All files with .BAS file types.

'*. BA?

All files with BA as the first two characters in the
file type.

'rhe program supplies an index of 0 and executes the call.
The system
returns directory information for the first file that matches the
wildcard specification. The program can increment the index by I and
execute the call again to gain directory information for second and
subsequent matching occurrences of files.
The system returns the
,error ?Can't find file or account (ERR=5) to indicate no more matchin~
occurrences exist in the account.
The entire procedure relieves the
program of the overhead required to translate each file name in the
directory and to compare for a match.

7-227

Set Terminal Characteristics
FO=l6
(UU.TRM)
Set Terminal Characteristics
This call has two subfunctions:
o

Set Terminal Characteristics - Part I

Set Terminal Characteristics - Part II

To use this call, you need to understand the concept of terminal
ownership. A terminal is "owned" when:
o

It becomes attached to a job by logging in. When data is
entered at a free terminal, the system starts a job to handle
the input and gives the job the next available job number.
The system then starts the LOGIN program to allow the user to
log in to the system.
(See the RSTS/E System User's Guide
for the operational details.)
When a user is logged in to the system, the system associates
the activated job with both the terminal at which the user is
typing and the account number used for system identification.
The job is then considered active on the system and in
attached mode (or attached to the terminal).
The system
associates I/O channel 0 with the terminal that activated the
job. The terminal associated with channel 0 is called the
job's console terminal or console keyboard. A job can have
only one console terminal, the keyboard to which it is
attached.

It is opened on a nonzero channel. A job can own several
terminals that are open on nonzero channels.

It is allocated for the use of a job (with the the DCL
ALLOCATE command).

7-228

Set Terminal Characteristics· Part I
FO=16

set Terminal Characteristics . Part I
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(16%), the set terminal characteristics code.

CHR$(O%), the code to specify part I of the SYS call.

CHR$(N%), where N% is 255% for the current keyboard
(requires no privilege) or is the keyboard number of the
terminal to alter (requires HWCFG privilege).

CHR${N%), where N% is 0% for no change or is the terminal
width plus 1. The call sets the number of characters for
each line to N%-l, where N% is in the range 2% to 255%. The
WIDTH n command sets this byte.

CHR$(N%), where N% is:

No change.

128%

Enable the hardware horizontal tab feature. The /TAB
qualifier of the SET TERMINAL command sets this
characteristic. (The device must have the necessary
hardware.)

255%

Enable software horizontal tab positions, which are
set every 8 character positions beginning at position
1. The /NOTAB qualifier of the SET TERMINAL command
sets this characteristic.

CHR$(N%), where N% is:
0%

No change.

128%

Enable the software to perform form feed and vertical
tab operations by executing four line feed operations.
The /NOFORM FEED qualifier of the SET TERMINAL commanc
sets this characteristic.

255%

Enable hardware form feed and vertical tab. The
/FORM_FEED qualifier of the SET TERMINAL command sets
this characteristic.
(The device must have the
necessary hardware.)

7-229

Set Terminal Characteristics· Part I

FO=16
8

CHR$(N%), where N% is:
0%

No change.

128%

Allow the terminal to receive and print lowercase
characters (CHR$(96%) through CHR$(126%». The
/LOWERCASE=OUTPUT qualifier of the SET TERMINAL
command sets this characteristic.

255%

Have the system translate lowercase characters to
uppercase before transmitting to a terminal.
The
/UPPERCASE=OUTPUT qualifier of the SET TERMINAL
command sets this characteristic.

CHR$(N%), where N% is:
0%

No change.

128%

Have the terminal not respond to XON CHR$(17%) and
XOFF CHR$(19%) characters because it lacks the
necessary hardware.
The /NOHOST_SYNC qualifier of the
SET TERMINAL command sets this characteristic.

255%

The terminal has the necessary hardware to respond to
XON and XOFF characters.
The terminal stops sending
characters when it receives a CHR$(19%) character
(XOFF) and resumes sending characters when it receives
a CHR$(17%) character (XON).
The /HOST SYNC qualifier
of the SET TERMINAL command sets this characteristic.

CHR$(N%), where N% is:
0%

No change.

128%

Have characters that are typed at the terminal sent to
the computer only.
The computer echoes (transmits
back to the terminal) the characters it receives and
performs any necessary translation.
The /NOLOCAL_ECHO
qualifier of the SET TERMINAL command sets this
characteristic.

255%

Have the terminal (or its modem) locally echo the
characters typed.
The computer does not echo the
characters received.
The /LOCAL_ECHO qualifier of the
SET TERMINAL command sets this characteristic.

7-230

Set Terminal Characteristics· Part I
FO=16
11

CHR$(N%), where N% is:
0%

No change.

128%

The terminal does not have features of a video display
terminal.
The /HARDCOPY qualifier of the SET TERMINAL
command sets this characteristic.
Specifying this
value causes byte 17 to .be set to 128 (/NOTTSYNC).

255%

The terminal is a video display, or cathode ray tube
(CRT), and uses the following features:
o

JResponds to the synchronization protocol described
by byte 17.

The system executes a DELETE character by sending
a backspace, a space, and a backspace to the
terminal.

Any location on the screen can be addressed by
direct cursor placement.

The /SCOPE qualifier of the SET TERMINAL command sets
this characteristic.
Specifying this value causes
byte 17 to be set to 255 (/TTSYNC).
12

CHR$(N%), where N% is:
0%

No change.

128%

The system treats certain characters that it receives
as follows:
o

Translate CHR$(125%) and CHR$(126%) into the ESC
character CHR$(27%) (unless the /NOALT_MODE
characteristic is subsequently set).

~rranslate

lowercase characters (CHR$(64%) through
CHR$(94%)) to uppercase equivalents (CHR$(96%)
through CHR$(126%)).

The /UPPERCASE=INPUT qualifier of the SET TERMINAL
command sets this characteristic.
255%

The terminal transmits the full ASCII character set
and the system treats special characters as follows:
o

~rreat

only CHR$(27%) as an escape character
(echoed as the $ character and handled as a line
terminating character).

7-231

set Terminal Characteristics . Part I
FO=16
o

Treat CHR$(125%) and CHR$(126%) as printed
characters } and -

Do not translate lowercase characters to uppercase
format.

The /LOWERCASE=INPUT qualifier of the SET TERMINAL
command sets this characteristic.
13

CHR$(N%), where N% is:
0%

No change.

No fill factor for the terminal.
The /NOCRFILL
qualifier of the SET TERMINAL command sets this
characteristic.

Set fill factor of the terminal to N%-l.
The
/CRFILL=n qualifier of the SET' TERMINAL command sets
this characteristic.

255%

Reserved.

CHR$(N%), where N% is:
0%

No change.

The internal speed value to determine the baud rate at
which the terminal receives characters.
If byte 16 is
0, this value also determines the transmit (output)
baud rate (requires HWCFG privilege). Note that you
can set internal speed value only for DHll,
DZll/DZVll/DZQll, and DHVll/DHUll interface lines as
shown in Table 7-8. The /SPEEO qualifier of the SET
TERMINAL command sets this characteristic.

7-232

Set Terminal Characteristics - Part I
FO=16
Table 7-8:

Internal Speed Values for Terminal Interface
Lines
+- - - .. _ .. - - - - - - - - - - - - - -+-.;. - - - - - - - - - _.. - - - - - - - --+- - - - - - - - - - - - - - --+

II DHV11/DHU11:
II
1I
DZ 11/DZV 11 /DZQ 1 1:
+- - - .. _ .. - - - - - - - - - - _ .. - -+- - - - - - - - - - - - - - - - - - - - --+- - - - - _ .... - _ .. - - .. --+
ICode
Speed
Code
Speed
Code
Speed
11
0
1
0
1
0
\2
SO
2
50
2
75
13
75
3
75
3
110
14
110
4
110
4
134.5
15
134.5
5
134.5
5
150
16
150
6
150
6
300
17
200
7
300
7
600
18
300
8
600
8
1200
19
600
9
1200
9
1800
110
1200
10
1800
10
2000
III
1800
11
2000
11
2400
112
2400
12
2400
12
4800
113
4800
13
3600
13
Reserved
114
9600
114
4800
14
9600
I
115
7200
15
19200
I
116
9600
+- - - - _ .... - _ .. - - - - - - - - - -+- - - - - _ .. - - - - - - - - - - - - _. -+- - - .. - - - - - _. - - - --+
15

DHll..

CHR$(N%), where N% is:
0%

No change.

Do not set the output parity bit.
The /NOPARITY
qualifier of the SET TERMINAL command sets this
characteristic.

Generate the output parity bit for even parity format.
The /PARITY=EVEN qualifier of the SET TERMINAL command
sets this characteristic.

Generate an output parity bit for odd parity format.
The /PARITY=ODD qualifier of the SET TERMINAL command
sets this characteristic.

Inhibit altering of the data length.
The data length
is the number of data bits (not counting start, stop,
or parity bits) transmitted on the line.
See
Discussion.

7-233

Set Terminal Characteristics· Part I
FO=16

16%

Turn off the 8-bit characteristic (7 bits).
The
/NOEIGHT_BIT qualifier of the SET TERMINAL command
sets this characteristic.
See Discussion.

24%

Set the 8-bit characteristic.
The lEIGHT_BIT
qualifier of the SET TERMINAL command sets this
characteristic.
See Discussion.

CHR$(N%), where N% is:
0%

Both the receive (input) and transmit (output) speeds
are determined by the value n in byte 14. The /SPEED
qualifier of "the SET TERMINAL command sets this
characteristic.

The internal speed value to determine the baud rate at
which the terminal transmits characters when a split
speed setting is used (requires HWCFG privilege).
You
can use split speed settings with the DHll interface
line only.
The /SPEED=(input[,output)] qualifier of
the SET TERMINAL command sets this characteristic.

CHR$(N%), where N% is:
0%

No change.

128%

The terminal ignores the synchronization protocol that
is described in the following 255 value.
The
/HARDCOPY and /NOTTSYNC qualifiers of the SET TERMINAL
command set this characteristic.
In addition, the
system automatically sets this value when byte 11 is
128.

255%

The terminal obeys the synchronization protocol:
o

The computer stops sending characters if the
terminal transmits a CHR$(19%) character (XOFF, or
the CTRL/S combination).

The computer resumes sending characters when the
terminal transmits a CHR$(17%) character (XON, or
the CTRL/Q combination).

The /SCOPE and /TTSYNC qualifiers of the SET TERMINAL
command set this characteristic.
In addition, the
system automatically sets this value when byte 11 is
255.
18

CHR$(N%), where N% is:
0%

No change.
7-234

set Terminal Characteristics· Part I
FO=16
128%

The system prints a control character as the up arrow
or circumflex character
or A) followed by the
equivalent printable character.
For example, the
CTRL/D combination is printed as AD, CHR$(94%)
followed by CHR$(68%).
The /UP_ARROW qualifier of the
SET TERMINAL command sets this characteristic.

255%

The system treats control characters as such.
The
/NOUP_ARROW qualifier of the SET TERMINAL command sets
this characteristic.

No effect.

CHR$(N%),where:
N%=8+DATA+STOP+PARITY
where:
DATA is

0%
1%
2%
3%

for
for
for
for

STOP is

0%
4%

for 1 stop bit per character
for 2 stop bits per character.
or 1.5 bits if DATA=O%.

PARITY is

0% for no parity bit.
16% for even parity format.
48% for odd parity format.

5
6
7
8

bits
bits
bits
bits

per
per
per
per

character.
character.
character.
character.

This byte applies only to interfaces that support
DATA/STOP/PARITY features.
When you use this byte with
these interfaces, it overrides the setting of byte 15.
In
addition, when you use byte 20, byte 14 must be set to a
nonzero value.
-21

CHR$(N%), where N% is:
0%

No change.

128%

Return the permanent characteristics.

255%

Set the characteristics for a terminal to always
default to permanent characteristics when the terminal
is released (for example, logout or kill).
The
/PERMANENT qualifier of the SET TERMINAL command
determines this value (requires HWCFG privilege).

7-235

Set Terminal Characteristics· Part I
FO=16
22

CHR$(N%), where N% is:
0%

No change.

128%

The system treats an incoming ESC, CHR$(27%),
character as a line terminating character and echoes
it as the $ character.
The /NOESCAPE SEQUENCE
qualifier of the SET TERMINAL command-sets this
characteristic.

255%

The system treats an incoming ESC, CHR$(27%),
character and the following incoming characters as a
special escape sequence.
See Chapter 4 for a
description of incoming escape sequences.
The
/ESCAPE SEQUENCE qualifier of the SET TERMINAL command
sets thIs characteristic.

CHR$(N%), where N% is:
0%
128%

No change.
Disable (clear) the private delimiter.
The
/NODELIMITER qualifier of the SET TERMINAL command
sets this characteristic.

128%+n% Set the private delimiter to ASCII code n (in the
range 1 to 127).
If the character has a special
meaning (for example, horizontal tab or the CTRL/Z
combination), the private delimiter usage has higher
precedence.
You cannot use the delimiter with
INPUT, INPUT LINE, or MAT INPUT statements. These
statements recognize only standard delimiters.
See
Chapter 4, Table 4-3 and the section "Private
Delimiters" for a discussion of delimiters.
The /DELIMITER qualifier of the SET TERMINAL command
sets this characteristic.
24

CHR$(N%), where N% is:
0%
128%

No change.
The terminal in use does not have the ESC key that
generates CHR$(27%).
Therefore, translate ALT MODE,
CHR$(125%), and PREFIX, CHR$(126%), to CHR$(27%).
The
/ALT MODE qualifier of the SET TERMINAL command sets
this-characteristic.

7-236

Set Terminal Characteristics - Part I
FO=16
255%

The terminal in use has an ESC key that generates
CHR$(27%).
Therefore, do not translate CHR$(125%) and
CHR$(126%) but treat them as their ASCII characters,
right brace (}) and ti.lde (''').
The /NOALT MODE
qualifier of the SET TERMINAL command sets-this
characteristic.

CHR$(N%), where N% is:
0%

No change.

128%

Disable the CTRL/R and CTRL/T facilities.
The
/NOCONTROL=R AND /NOCONTROL=T qualifiers of the SET
TERMINAL command set this characteristic.

255%

Enable the CTRL/R and CTRL/T facilities.
The
/CONTROL=R and /CONTROL=T qualifiers of the SET
'rERMINAL command set this characteristic.

The CTRL/R facility retypes your terminal's pending input
buffer.
CTRL/T produces a status report for the current
keyboard (unless this byte is set to 128 to disable CTRL/T).
This byte is only for compatibility with previous releases.
When writing new applications, use Part II of the call
instead.
26

CHR$(N%), where N% is:
0%

No change.

128%

Define XOFF/XON processing such that the keyboard
resumes typeout and echo only after XON or CTRL/C is
typed.
The /RESUME=CONTROL_C qualifier of the SET
TERMINAL command sets this characteristic.

255%

Define XOFF/XON processing such that the keyboard
resumes typeout and echo when any character is typed
after XON.
The /RESUME=ANY qualifier of the SET
TERMINAL command sets this characteristico

CHR$(N%), where N% is:
0%

No change.

128%

Treat BREAK key as a null.
The /NOBREAK qualifier of
the SET TERMINAL command sets this characteristic.

255%

Translate BREAK key to CTRL/C.

The /BREAK qualifier

of the SET TERMINAL command sets this characteristic.

7-237

Set Terminal Characteristics· Part I
FO=16
28

CHR$(N%), where N% is:
0%

No change.

128%

Enable broadcast to the terminal.
The /BROADCAST
qualifier of the SET TERMINAL command sets this
characteristic.

2~5%

Disable broadcast to the terminal.
The /NOBROADCAST
qualifier of the SET TERMINAL command sets this
characteristic.

Data Returned
Bytes

Meaning

This byte returns the status of the keyboard specified in
byte 4 of the data passed.
The following bit tests show the
information returned:

5-28

Value

Information

Byte 3 AND 1%<>0%

Disabled keyboard or pseudo
keyboard that is not in use.

Byte 3 AND 126%=0%

No job owns keyboard.

Byte 3 AND 126%<>0%

(Byte 3 AND 126%)/2 is the job
number that owns the keyboard.

Byte 3 AND 128%<>0%

Modem line hung up or pseudo
keyboard that is not in use.

These bytes return values that define the current keyboard
characteristics, with three exceptions:
o

If you specify 128 in byte 21, then the call returns the
permanent terminal characteristics.

Byte 20 is always returned as O.

7-238

Set Terminal Characteristics - Part I
FO=16
o

Byte 19 returns a code that defines the type of
interface for the line, where:
Value

o
2

4
6
8

10
12
14
16

Type
DLIIA, DLIIB
reserved
DLIIC, DLIID
DLIIE
pseudo keyboard
DJll
DHll
DZll/DZVll
DHVll/DHUll

CHR$(N%), where N% is:

The a-bit characteristic is OFF.

The a-bit characteristic is ON.

Privileges Required
None

set the characteristics of your own terminal

HWCFG

Set the characteristics of a terminal other than your own,
or set permanent terminal characteristics

Possible! Errors
Meaning

ERR Value

?PROTECTION VIOLATION
You do not have sufficient privilege to perform any
of these operations:

Read the characteristics of a terminal not
opened or assigned to your job.

Change the characteristics of a terminal other
than your job's console terminal (KB:).

Change the speed setting for your terminal.
(Byte 14 or 16 is nonzero.)

set the permanent characteristics for a remote
terminal line (byte 21 is nonzero).

7-239

Set Terminal Characteristics· Part I
FO=16

?ILLEGAL SYS() USAGE

The keyboard number specified in byte 4 of the
call is out of the range of valid keyboard
numbers.

The current keyboard is specified (byte 4=255)
but the calling job is detached.

Discussion
Use this call to determine the current or permanent keyboard
characteristics and then to make changes to those characteristics.
If you do not have HWCFG .privilege, you can read the characteristics
of any terminal that you have opened or assigned but can change
terminal characteristics only for your job's console terminal (KB:).
In addition, you cannot set speed or permanent characteristics.
Byte 15 sets the output parity bit, data length, and 8-bit
characteristic. When the 8-bit characteristic is OFF, incoming data
is trimmed to 7 bits (when not in binary mode). When the 8-bit
characteristic is ON, incoming data is not trimmed. As a ~esult, all
a data bits are passed to the user program. DIGITAL recommends you
set the a-bit characteristic to OFF on all 7-bit terminal lines
because some terminals send 7-bit data with the eighth bit set rather
than cleared. Setting the 8-bit characteristic to OFF also ensures
that terminals configured to send 7 data bits with a parity bit,
connected to a line configured for no parity checking, will work as
they did in the past.
If you want to use the 8-bit feature with parity on a terminal, you
must also set up the data length properly. The data length is the
number of actual data bits transmitted on the line. The default data
~ength in RSTS/E is 8 bits, and the default parity setting is
"disabled."
Normally, when you enable parity, the number of data bits decreases to
seven. This would have the wrong effect on 8-bit terminals.
Therefore, the system suppresses the changing of the data size when
the a-bit characteristic is set. If you want to suppress the data
size change without using the 8-bit setting, set bit 4 in byte 15 when
changing the parity setting.
The SET TERMINAL commands use this call to set terminal
characteristics. See the RSTS/E System Manager's Guide for more
information.

7-240

Set Terminal Characteristics· Part II
FO=16
Set Terminal Characteristics . Part II
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(16%), the set terminal characteristics code.

CHR$(l%), the code to specify part II of the SYS call.

CHR$(N%), where N% is 255% for the current keyboard
(requires no privilege) or is the keyboard number of the
terminal to alter (requires HWCFG privilege).

CHR$(N%), where N% is the terminal type code.
(0%-255%) are:
Value

Code

0%
1%
2%
3%
4%
5%
6%
7%
8%
9%
10%
11%
12%
13%
14%
15%
16%
17%
18%
19%
20%
21%
22%
23%
24%
25%
26%
27%
28%

No change
Unknown
LA36
VT52
VT55
LA180S
VT100
LA120
LA12
LAIOO
LA34
LA38
LA50
VT101
VTI02
VT125
VT131
VT132
VT220
VT240
VT241
VT105
VKI00
:RT02
LA30
VT50
VT50H
VT05
VTOSB
7-241

Legal values

Set Terminal Characteristics· Part II
FO=16
29%
LA30S
30%
2741
31%
ASR33
32%
KSR33
33%
ASR35
34%
KSR35
35%-127% Reserved
128%-255% Available for customer use
The /TYPE qualifier of the SET TERMINAL command sets this
characteristic.
6-20

Reserved; should be O.

CHR$(N%), where N% is:
value

Meaning

No change.

128%

Return the terminal's permanent characteristics.

255%

Set the characteristics for a terminal always to
default to permanent characteristics when the terminal
is released (for example, logout or kill).
The
/PERMANENT qualifier of the SET TERMINAL command
determines this value (requires HWCFG privilege).

CHR$(N%), where N% is:
Meaning

Value
0%
6%-255%

No change.
The terminal's new input buffer quota.
The
default value is 6.
The IBUFFER_QUOTA qualifier
of the SET TERMINAL command sets this
characteristic (requires HWCFG privilege).
See
Discussion

CHR$(N%), where N% is:
Value
0%
1%
2%
4%
8%
16%

Meaning
No change.
Enable the
Enable the
Enable the
Enable the
Enable the

CTRL/C control character.
CTRL/T control character.
CTRL/R control character.
CTRL/X control character.
autobaud facility.

7-242

Set Terminal Characteristics - Part II
FO=16
CTRL/C usually halts execution of the current command or
program and returns control to the job keyboard monitor.
CTRL/T produces a status report for the current keyboard.
CTRL/R retypes your terminal's pending input buffer.
CTRL/X
deletes the current line as well as all type-ahead.
The
/CONTROL qualifier of the SET TERMINAL command sets the
control characteristics.
The /AUTOBAUD qualifier of the SET TERMINAL command sets the
autobaud characteristic.
See the Discussion for more
information on the autobaud facility.
24

CHR$(N%), where N% is:
Value
0%
1%
2%
4%
8%
16%

Meaning
No change.
Disable the
Disable the
Disable the
Disable the
Disable the

CTRL/C control character.
CTRL/T control character.
CTRL/R control character.
CTRL/X control character.
autobaud facility.

The /NOCONTROL qualifier of the SET TERMINAL command clears
the control characteristics.
The /NOAUTOBAUD qualifier of the SET TERMINAL command clears
the autobaud characteristic.
25-26

CHR$(N%)+CHR$(SWAP%(N%)), where N% is:
Value
0%
1%
2%
4%
8%
16%
32%
64%
128%
256%
512%
1024%
2048%

Meaning
No change.
Set ANSI escape sequences (/ANSI).
Set advanced video (/ADVANCED VIDEO).
Set 132 columns (/132_COLUMNS).
Set printer port (/PRINTER_PORT).
Set ReGIS graphics (/REGIS).
Set sixel graphics (/SIXEL).
Set Katakana character set (/KATAKANA).
Set selectively eraseable characters
(/SELECT_ERASE).
Set dynamically redefinable character sets
(/LOADABLE).
Set user defined keys, UDKs (/USER DEFINED_KEYS).
Set local copy (/LOCAL_ECHO).
Set noninteractive mode.
See Discussion.

These terminal capability flags let a program check which
functions a terminal can perform.
If you set these flags,
7-243

Set Terminal Characteristics· Part II
FO=l6
no spacial processing is performed.
See the documentation
on your particular terminal for more information on its
capabilities.
The qualifier of the SET TERMINAL command that sets a
characteristic is shown in parenthesis after each bit value
description.
27-28

CHR$(N%}+CHR$(SWAP%(N%}), where N% is:
Value
0%
1%
2%
4%
8%
16%
32%
64%
128%
256%
512%
1024%
2048%

29-30

Meaning
No change.
Clear ANSI escape sequences.
Clear advanced video.
Clear 132 columns.
Clear printer port.
Clear ReGIS graphics.
Clear sixel graphics.
Clear Katakana character set.
Clear selectively eraseable characters.
Clear dynamically redefinable character sets.
Clear user defined keys (UDKs).
Clear local copy.
Clear noninteractive mode.
See Discussion.

Reserved; should be O.
The qualifier of the SET TERMINAL command that clears a
characteristic is the same one shown in parenthesis after
each bit value description in bytes 25-26, with the NO
prefix appended.

Data Returned
Bytes

Meaning

This byte returns the value of the current terminal type.

This byte returns the current control character flag status;
that is, those flags that are set.

25-26

These bytes return the current capability flag status; that
is, those flags that are set.

7-244

Set Terminal Characteristics· Part II
FO=16
Privileges Required
None

Set the characteristics of your own terminal

HWCFG

Set the characteristics of a terminal other than your own,
or set permanent terminal characteristics

Possible Errors
Meaning

ERR Value

?PROTECTION VIOLATION
You do not have sufficient privilege to perform any
of these operations:

Read the characteristics of a terminal not
opened or assigned to your job.

Change the characteristics of a terminal other
than your job's console terminal (KB:).

Change the terminal's buffer quota.

?ILLEGAL SYS() USAGE
One of the following occurred:
o

The keyboard number specified in byte 4 of the
call is out of the range of valid keyboard
numbers.

The current keyboard is specified (byte 4=255)
but the calling job is detached.

The value in byte 22 is not within the range of
6-255.

Discussion
Use this call to determine the current or permanent keyboard
characteristics and then to make changes to those characteristics.
If you do not have HWCFG privilege, you can read the characteristics
of any terminal that you have opened or assigned but can change
terminal characteristics only for your job's console terminal (KB:).
In addition, you cannot set speed or permanent characteristics.

7-245

Set Terminal Characteristics· Part I I
FO=16
The SET TERMINAL command uses this call to set terminal
characteristics.
See the RSTS/E System Manager's Guide for more
information on SET TERMINAL.
Byte 22 sets the input buffer quota.
The default quota value is 6.
Since there are 30 characters in a buffer, this means that terminal
service attempts to buffer 180 (6 times 30) characters before sending
the device an XOFF.
Note that there is no guarantee that a terminal
can allocate its full buffer quota, because a heavy system load may
leave less than the terminal's full buffer quota available. Also,
excessive use of this feature to allocate large numbers of buffers to
several terminals can create a shortage of small buffers.
Bit value 16 in byte 23 sets the autobaud characteristic. Autobaud
enables RSTS/E to detect and then set terminal speed on a particular
multiplexed line.
Once the characteristic is set, the user types
carriage return (CR) until the system prompts with 'User:'. You can
set the autobaud feature on DZll, DZVll, DZQll, DHll, DHVll and DHUl1
multiplexers. Autobaud supported speeds are 110, 150, 300, 600, 1200,
1800, 2400, 4800 and 9600 baud.
RSTS/E does not support split speeds
when using the autobaud feature.
Bit value 16 in byte 24 clears the
autobaud characteristic.
The autobaud characteristic is meaningful
only when setting permanent characteristics.
Bit value 2048% in bytes 25·26 sets noninteractive mode. You can use
the noninteractive characteristic with devices such as printers that
are attached to terminal lines.
These devices do not function as
interactive terminals; in particular, they are never used to initiate
a terminal session.
If the noninteractive characteristic is set, the
system ignores any characters received from the terminal if the
terminal is not owned by a job.
If the terminal is owned by a job,
the system processes characters normally.
Bit value 2048% in bytes
27·28 clears noninteractive mode.
The noninteractive characteristic
is meaningful only when setting permanent characteristics.

7·246

Disk Directory Lookup
FO=17

(UU.LOR)

See the section "Directory Lookup" for a description of this call.

7-247

Enable and Disable Disk Caching
FO=19
(UU.CHE)
Enable and Disable Disk Caching
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(19%), the enable and disable caching code.

CHR$(N%), where N% is:
Value

Meaning

Enable directory and data caching.
In addition to
this byte, data caching requires a value setting
in byte 11. Note that bytes 4 through 12 are used
only if this byte equals o.

To disable all caching.

128%

Return the current ca'ching parameters. A 128
value in this byte does not enable or disable data
caching.

CHR$(C%), where C% is the cache cluster size.
If C% is 0,
the current cluster size is used.
See Discussion. Cache
cluster size can be specified as 1,2,4, or 8 blocks.
If C%
is greater than 8, 8 is used.

5-6

CHR$ (L%)+CHR$(SWAP%(L%», where L% sets a limit on the
total number of cache cluBters that can be used.
If L% is
0, the current limit is used. See Discussion. If L% is
nonzero, it specifies an upper limit on the number of
clusters in the cache.
Note that if the amount of XBUF
available to the cache is less than L%, the cache does not
exceed XBUF.

7-8

CHR$(D%)+CHR$(SWAP%(D%», where D% sets a limit on the total
number of cache clusters allocated for directory caching_
If D% is 0, the current limit is used.
See Discussion.
If
D% is nonzero, it specifies an upper limit for the number of
clusters in the cache that are available for directory
caching. Note that the number of clusters allocated for
diJectory caching during a particular operation can be less
than D%.

7-248

Enable and Disable Disk Caching
FO=19
9-10

CHR$(U%)+CHR$(SWAP%(U%», where U% sets a limit on the total
number of cache clusters allocated to user data caching.
If
U% is nonzero, it specifies an upper limit for the number of
clusters in the cache that a~e available for user data
caching.
Note that the number of clusters allocated for
data caching during a particular operation can be less than
U%.

CHR$(E%), where E% modifies the enabling/disabling of data
caching as follows:

E%=O

Use the current setting.

E%=1

Enable data caching as specified in file OPEN MODE
or UFD setting (see Chapter 1).

E%=128

Disable all data caching.

E%=64

Cache all data transfers regardless of file OPEN
MODE or UFD setting.

CHR$(M%), where M% controls the cache's use of the small
buffer pool, as follows:
M%=O

Use the current setting.

M%=1

Allow use of the small buffer pool.

M%=128

Do not use the small buffer pool.

CHR$(T%), where T% is the new value of the cache replacement
time.
Specify 0% for no change.

14-30

Reserved; should be O.

Data Returned
Bytes
1-2
3

Meaning
Internal coding.
Current cache setting and available options:
Value

Meaning

Cache disabled, user data caching is not
available.

Cache enabled, user data caching is not available.

7-249

Enable and Disable Disk Caching
FO=19
128

Cache disabled, user data caching is available.

129

Cache enabled, user data caching is available.

4-13

Current settings of cache parameters, as described for
passed data. Note that these bytes have meaning only if the
system manager has installed disk caching during system
installation.

14-30

Not used.

Privileges Required
TUNE
Possible Errors
Meaning

ERR Value

?ACCOUNT OR DEVICE IN USE
All of the clusters allotted to the cache are in
use.

?NO ROOM FOR USER ON DEVICE
An attempt was made to enable data caching without
sufficient XBUF space allocated to the cache. The
system manager must allocate at least 2K words of
memory to XBUF for caching.

?DEVICE NOT AVAILABLE
An attempt was made to change the cache cluster size
(see byte 4) while a cached file disk transfer was
in progress. Retry the operation.

?PROTECTION VIOLATION
You do not have the TUNE privilege.

?MISSING SPECIAL FEATURE
Caching was not enabled for the system during system
installation.

Discussion
Bytes 1, 2, and 3 of this call enable or disable the FIP buffering
module that controls directory caching. The SET SYSTEM command uses
these bytes.

7-250

Enable and Disable Disk Caching
FO=19
~

If the system manager installed user data caching on the system during
system installation, bytes 1-13 enable or disable user data caching
and set the parameters of the cache.
The system manager defines the
total size of XBUF during system installation, and some portion of
this space is, in turn, used by the cache.
The disk caching SYS call
defines the size of the directory portion and data portion of the
cache.
The sizes defined in this call set upper limits, not fixed
sizes.
For example, if the system manager defines a 40K word XBUF at
system installation, the SYS call can define the directory and data
portions of the cache as 25K words each.
That is, data can use the
space in the cache up to a maximum of 25K words, which leaves a
nlinimum of 15K words for the directory.
The reverse is also true.
In
this manner, data and directory caching are guaranteed a minimum
allocation and are allowed to overlap, which permits the cache to
dynamically adjust to system and program requirements.
This SYS call is also used to limit the size of the total cache.
Because both the cache and DECnet/E use XBUF, limiting the cache
guarantees that space is always available in XBUF for DECnet/E.
Note
that the system frees the amount of memory allocated to the cache for
other use when it is not performing caching.
Byte 4 of the call sets the cache cluster size.
This parameter
controls the number of contiguous blocks that are copied from the disk
to the cache whenever a file or directory is cached (see Chapter 1).
The cache cluster size should be small enough to contain a reasonable
number of clusters, but large enough to reduce the number of disk
accesses.
That is, you must anticipate data requests and make sure
that the cache is equal to the file cluster size of the most often
accessed file.
If you specify a cache cluster size of 1, only random
caching is allowed (see Chapter 1).
See the RSTS/E System Manager's
Guide for cache cluster size guidelines.
Note that the parameters for cache cluster size and cluster allocation
(bytes 4 through 10) have default settings at system start-up.
The
default settings are a cache cluster size of 4, with no limits on
directory, data, or total cache size, and a cache replacement value of
30.
The system manager can reset these defaults with an INIT option,
as the RSTS/E System Installation and Update Guide describes.

7-251

Date and Time Conversion
FO=20
(UU.CNV)
Date and Time Conversion
Data Passed
Meaning

Bytes

CHR$(6%), the SYS call to FIP.

CHR$(20%), the date and time conversion code.

3-4

CHR$(D%)+CHR$(SWAP%(D%)), where D% is the date to be
converted or 0% for the current date.

5-6

CHR$(D%)+CHR$(SWAP%(D%)), where:
Value
0%=0
0%<0
D%>O

Meaning
Use the system default format.
Use alphabetic date format.
Use ISO numeric date format.

7-16

Reserved; should be O.

17-18

CHR$(T%)+CHR$(SWAP%(T%»), where T% i.s the time to be
converted or 0% for the current time.

19-20

CHR$(T%)+CHR$(SWAP%(T%)), where:
Value
T%=O
T%<O
T%>O

21-30

Meaning
Use the system default format.
Use AM/PM time format.
Use 24-hour time format.

Reserved; should be O.

Data Returned
Bytes

Meaning

The current job number times two.

Not used.

3-6

Same as data passed.

7-16

The date string, padded to the right with nulls.

7-252

Date and Time Conversion
FO=20

17-20

Same as data passed.

21-30

The time string, padded to the right with nulls.

Privileges Required

None.
PossiblE~

Errors

No errors are possible; however, if bytes 3-4 or 17-18 contain illegal
date or time values, unpredictable output may be generated.
Discussion

Use this call in programs that need to override the system date and
time defaults.

7-253

System Logical Names
(FO=21)
System Logical Names
RSTS/E allows users to access devices by logical names as well as by
physical names.
Logical names that apply to all users are called
system logical names. On all systems, users can refer to a disk by
its pack identification or a logical name that replaces the pack
identification.
This SYS call allows you to add, remove, change, and list system
logical names. The total number of additional system logical names
allowed is limited by the size of the extended buffer pool (XBUF).
RSTS/E maintains a table of system logical names in two parts. The
first part exists on all systems and contains an entry for each disk
unit configured on the system.
The position of an entry is fixed to a
specific disk type and unit and never has a PPN associated with the
logical name.
The second part of the logical name table is optional. Space for the
table is taken from XBUF.
The position of entries in the second part
is dynamic. Multiple entries are allowed for a specific device and
unit. Only one entry, however, can appear for any specific logical
name.
In addition, an entry in the second part of the table can have
a PPN associated with the logical name.
This mechanism allows a
default account specification to be applied for a logical name.
The default account associated with a system logical name applies
unless an account is specified immediately after the logical name.
For example, if you associate the system logica.l name SCRATCH with
account [100,100] on RP04 unit 2, and open the file
SCRATCH: [200,240]OTHER.DAT, the system attempts to access the file
OTHER.DAT on RP04 unit 2 under account [200,240]. The specification
SCRATCH:OTHER.DAT refers to the file OTHER.DAT in account [100,100] on
RP04 unit 2, the account associated with the logical name SCRATCH.
The Mount and Dismount SYS calls (SYS 3) create and delete entries in
the first part of the logical name table.
The Mount call places a
pack identification or logical name in the entry for the disk being
mounted (unless NOLOGICAL is specified or the logical name is already
in use).
The Dismount call removes a pack identification or logical
name from the entry for that disk.
The System Logical Name call can change or remove a name (or pack
identification) in the first part of the table.
The Logical Name SYS
call can add or remove entries in the second part of the table.

7-254

System Logical Names
(FO=21)

This call has four subfunctions:
o

Add New Logical Names

Remove Logical Names

Change Disk Logical Name

List Logical Names

The following sections describe the variations of the Logical Name SYS
call.

7-255

Add New Logical Names
(FO=21)
(UU.SLN)
Add New Logical Names
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(21%), the system logical name code.

CHR$(l%), to add a new entry in the logical name table.

Reserved; should be O.

5-6+

PPN to be associated with this logical name. If these bytes
are 0, no account is associated with the logical name.

7-12

The system logical name, in Radix-50 format.

CHR$(N%), where N% is one of the following values:
Value

Meaning

Do not replace an existing logical name.
Discussion.

See

Replace an existing logical name with the new
information. See Discussion.

14-22

Reserved; should be O.

23-26+

The device name and unit number to which the logical name
applies.

27-30

Reserved; should be O.

Data Returned
Bytes

Meaning

If you passed a value of 1% in byte 13, the call returns:
Value

Meaning

The logical name did not already exist

The logical name existed and was replaced.

7-256

Add New Logical Names
(FO=2l)
Privileges Required
INSTAL
PossiblE~

Errors
Meaning

ERR Value

?ILLEGAL FILE N.AME
No name is found in bytes 7 through 12, or the name
found contains nonalphanumeric characters.

?ACCOUNT OR DEVICE IN USE
The name specified in bytes 7 through 12 duplicates
one already in either the first or second part of
the table.

?NOT A VALID DEVICE
The device specification in bytes 23 through 26 is
illegal or the· related device is not configured on
the system.

?ILLEGAL SYS() USAGE
You specified an illegal value in byte 3.

:'NO BUFFER SPACE AVAILABLE
There is no more room on the system for a new entry.
To free up an entry, issue the remove logical name
SYS call.

Discuss:ion
System logical names can be up to nine characters long. When adding a
name of fewer than nine characters, you must fill the extra space at
the end in bytes 7-12 with zeros (RAD50 blanks).
This call scans the
e~ntire system logical name table for the name given in bytes 7 through
12.
Byte 13
specify
logical
whether
logical

specifies whether to replace an existing logical name.
If you
a value of 1% (replace), the system deassigns the existing
name.
The system follows these procedures to determine
to add the new logical name to the first or second part of
name table:

If the device name specified in bytes 23-26 is not a disk,
the system adds the logical name to the second part

If the device name is a disk and you specified a PPN in bytes
5-6, the system adds the logical name to the second part
7-257

Add New Logical Names
(FO=21)
3.

If the device name is a disk and you did not specify a PPN in
bytes 5-6, the system checks to see if the disk is mounted.
If the disk is not mounted, the system adds the logical name
to the second part.
If the disk is mounted, the system
follows these procedures:
1.

If a logical name for the disk does not exist in the
first part of the table, the system adds the new logical
name to the first part

If a logical name for the disk exists in the first part
of the table, the system adds the new logical name to the
second part.

The DCL ASSIGN/SYSTEM command uses this call.

7-258

Remove Logical Names
(FO=21)
Remove Logical Names
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(21%), the system logical name code.

CHR$(O%), to remove a system logical name from either the
first or second part of the logical name table.

4-6

Reserved; should be O.

7-12

The system logical name, in Radix-50 format.

13-30

Reserved; should be O.

Data Returned
No meaningful data is returned.
privileges Required
INSTAL
Possible Errors
Meaning

ERR Value

?ILLEGAL FILE NAME
No name is found in bytes 7 through 12, or the name
found contains nonalphanumeric characters.

?CAN'T FIND FILE OR ACCOUNT
The name specified in bytes 7 through 12 is not
currently defined as a logical name.

?ILLEGAL SYS() USAGE
You specified an illegal value in byte 3.

7-259

Remove Logical Names
(FO=21)
Discussion
This call scans the entire system logical name table for the name
specified in bytes 7 through 12. The call removes the logical name or
pack identification from the first part of the table or removes an
entire entry from the second part of the table.
When you remove a system logical name of fewer than nine characters,
you must fill the extra space at the end in bytes 7-12 with zeros
(RADSO blanks).

7-260

Change Disk Logical Names
(FO=21)
Change Disk Logical Name
Data Passed
lBytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(21%), the system logical name code.

CHR$(255%), to change the logical name associated with a
disk in the first part of the logical name table.

4-6

Reserved; should be O.

7-12

The system logical name, in Radix-50 format.

13-22

Reserved; should be O.

23-26+

The name and unit number of the disk device whose logical
name is to be changed.

27-30

Reserved; should be O.

lData Returned
No meaningful data is returned.
Privileges Required
INSTAL
l?ossible Errors
Meaning

ERR Value

'?ILLEGAL FILE NAME
No name is found in bytes 7 through 12, or the name
found contains nonalphanumeric characters.

?ACCOUNT OR DEVICE IN USE
The logical name specified in bytes 7 through 12
duplicates one already in either the first or second
part of the table.

7-261

Change Disk Logical Names
(FO=21)
?CAN'T FIND FILE OR ACCOUNT
The disk specified in bytes 23 through 26 is not
configured on this system.

?NOT A VALID DEVICE
The device specified in bytes 23 through 26 is
illegally formatted or is not a disk.

?ILLEGAL SYS(} USAGE
You specified an illegal value in byte 3.

Discussion
This call accesses the entry in the first part of the system logical
name table for the disk specified in bytes 23 through 26. The logical
name specified in bytes 7 through 12 is placed in the entry. This
call accepts system logical names up to nine characters long. When
changing a logical name of less than nine characters, you must fill
the extra space in bytes 7-12 with zeros (RAD50 blanks).

7-262

List Logical Names
(FO=21)
List Logical Names
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(2l%), the system logical name code.

CHR$(2%), to list the entries in the logical name table.

Reserved; should be O.

5-6

CHR$(N%), where N% is the index of the logical name entry to
be Ii sted '.

7-30

Reserved; should be O.

Data Returned
Meaning

Bytes
1-4

Not used.

5-6

PPN of the account associated with the logical name.
no PPN is associated with the logical name.

7-12

The system logical name, in Radix-50 format.

13-22

Not used.

23-26+

The device name and unit number of the Nth logical.
no device name is associated with the logical name.

27-30

Not used.

Privileges Required
None.

7-263

0% if

List Logical Names
(FO=2l)

Possible E"rrors
Meaning

ERR Value

?CAN'T FIND FILE OR ACCOUNT

The index entry specified in bytes 5-6 is out of
range.
?ILLEGAL SYS() USAGE

You specified an illegal value in byte 3.
Discussion
This call scans the system logical name table and lists the logical
name that corresponds to the index number passed in bytes 5-6. You
can list all logicals by repeated calls with an index value, starting
at 0 and increasing the index value by 1 each time.

7-264

FO=22

Send/Receive
(.MESAG)

System Call for Local Interjob Communication (Send/Receive)
See Chapter 8 for a description of the Send/Receive system function
call.
See Chapter 9 for a description of the System Call for
print/Batch Services (PBS), a subfunction of the Send/Receive call.

7-265

Add, Remove, and List System Files
FO=23
(UU.SWP)
Add, Remove, and List System Files
Swap files on RSTS/E are dynamically added at the start of timesharing
and can be added and removed during timesharing.
Swap files must be
removed to properly shut down timesharing. Optionally, you can add
three other system files during timesharing to optimize system
performance: the overlay file, the error message file, and the
DECnet/E system file.
This SYS call adds and removes these system files and also lets you
obtain their file specifications.
Through the INIT.SYS program and
the DCL INSTALL command, a system manager can optionally create and
add the swapping files and create other system files.
The SHUTUP
system program removes the files so that the disks on which they
reside can be dismounted during the normal system shutdown.
See the
RSTS/E System Manager's Guide and the RSTS/E System Installation and
Update Guide for details on these operations. Refer to the DECnet/E
System Manager's Guide for more information on the DECnet/E system
file, also called the DECnet/E volatile parameter file.
The following sections describe the three subfunctions of this SYS
call:
o

Add System Files

Remove System Files

List System Files

7-266

Add System Files
FO=23

Add System Files
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(23%), the system files code.

CHR$(N%), where N% designates the file to add:
Value
0%
1%
2%
3%
4%
5%
6%

Meaning
Swap file 0
Swap file 1
Illegal - generates error
Swap file 3
Overlay file
Error message file
DECnet/E system file

To specify codes 0-5, you need read/write access to the
file.
Code 6 requires only read access to the file.
4

CHR$(l%), to add a system file.

5-6

Reserved; should be O.

7-10+

To add a file that currently exists in directory [0,1] and
has a file type of .SYS, specify the name, in Radix-50
format.
If no name is given here (all bytes are zero), the
add operation must be for a non-file-structured disk to be
used as a swapping device.
If a file is specified, the
system makes sure that it exists, is large enough, and has
proper characteristics.

11-22

Reserved; should be O.

23-26+

The name and unit designation of the device (must be disk)
on which the file resides.
If all bytes are zero, the
public structure (SY:) is used.

27-30

Reserved; should be O.

Data Returned
No meaningful data is returned.

7-267

Add System Files
FO=23
Privileges Required
INSTAL

Add system files

WRTNFS

Add a non-file-structured disk as a swapping device

Possible Errors
Meaning

ERR Value

?ILLEGAL FILE NAME
No name is specified in bytes 7 through 10 when an
overlay, error message, or DECnet/E system file is
being added; or the name specified contains
nonalphanumeric characters.

?ACCOUNT OR DEVICE IN USE
A swap file is being added to a non-file-structured
disk but the disk is currently mounted (that is, it
is being used as a file-structured device).

?NO ROOM FOR USER ON DEVICE
If an overlay or error file is being added, this
error indicates that the file is not long enough.
(The overlay file should be at least 128 blocks and
the error file at least 16 blocks.) If a swap file
is being added to a file-structured device, this
error means that the file is not long enough to
store even one job.

?CAN'T FIND FILE OR ACCOUNT
A system file is being added to a file-structured
disk, but the file with the name specified in bytes
7 through 10 and with a .SYS file type does not
exist in directory [0,1].

?NOT A VALID DEVICE
The device specified in bytes 23 through 26 is disk
but is not configured on this system.

?DEVICE NOT AVAILABLE
A swap file is being added to a non-file-structured"
disk, but either the disk unit or its controller has
been disabled.
The system manager must use an
initialization option to enable the unit or its
controller.

?PROTECTION VIOLATION
A system file is being added to a file-structured
disk.
Either the unit is logically write-locked, or

7-268

Add System Files
FO=23
the file specified in bytes 7 through 10 is bad
(that is, it is not contiguous or is currently
open JI •
?NAME Olt ACCOUNT NOW EXISTS
The system file being added as described in byte 3
is already installed on the system.

? ILLEGAL SYS () USAGE:
The number specified in byte 3 is either 2 or is
greater than 6. The swap file for file 2 must exist
on the system disk and cannot be added during
timesharing.
System files to be added are defined
only by the values 0, 1, 3, 4, 5, and 6.

?DISK PACK IS NOT MOUNTED
A system file is being added to a file-structured
disk but that disk is not currently mounted. Use
the MOUNT command to logically mount the disk before
the file is added.

?DEVICE NOT FILE STRUCTURED
The device specified in bytes 23 through 26 is not a
disk device.

Discussion
This SYS call either designates an entire disk to be added as a swap
file or specifies a file to be added as a swap file, overlay file,
error message file, or DECnet/E system file.
By using the
initialization options, the system manager creates system files in
account [0,1] on a system disk or on nonsystem (public or private)
disks.
This call dynamically assigns system file space to provide
flexibility in system operations.
T1he RSTS/E System Installation and update Guide discusses the rules
and guidelines for planning and creating system files. Adding
previouf;ly created system files with this call requires that the
system manager plan resources properly.
For example, swap files need
contiguous space on a disk.
If a file on disk is to be added for
swappinq, the system manager must have created the contiguous space at
the proper size.
If a non-file-structured disk is to be added as a
swap file, the systE~m manager must make sure that the device is
available for such use.
Although this call adds swap file space, it does not alter the job
maximum allowed on the system. Adding a swap file merely increases
the capability of the system to handle a larger number of jobs. To
increase the job maximum after a swap file is added, you must use the
Enable Logins SYS call (SYS -1) or the SET SYSTEM/LOGINS command.
7-269

Remove System Files
FO=23
Remove System Files
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(23%), the system files code.

CHR$(N%), where N% designates the file to remove:
Meaning

Value
0%
1%
2%
3%
4%
5%
6%
4

5-30

Swap file 0
Swap file 1
Illegal - generates error
Swap file 3
Overlay file
Error message file
DECnet/E system file

CHR$(O%), to remove a system file.
Reserved; should be O.

Data Returned
No meaningful data is returned.
Privileges Required
INSTAL
Possible Errors
Meaning
?ACCOUNT OR DEVICE IN USE
The swap file to be removed can be properly removed
but currently contains one or more swapped-out jobs.
The system locks the file and begins swapping jobs
to other files.
Retry the call at a later time when
the swapped-out jobs are no longer in this file.

7-270

ERR Value
3

Remove System Files
FO=23
?PROTECTION VIOLATION
A swap file is to be removed, but its removal will
decrease the swap file space below the limit
required to store the maximum number of jobs on the
system.
To remove the swap file, decrease the
number of logins currently allowed (by either the
SET LOGINS x command or SYS call), wait until the
number of logged-in jobs falls to the maximum, and
try the removal operation again. An attempt to
remove the DECnet/E system file when DECnet/E is
still on also causes this error.

?I ILLEGAL SYS ()

USAGE
The number specified in byte 3 is either 2 or is
greater than 6.
The swap file for file 2 must exist
on the system disk and cannot be removed during
timesharing.
System files to be removed are defined
only by the values 0, 1, 3, 4, 5, and 6.

Discussion
This SYS call removes a system file from operation.
Previously added
system files must bE~ removed in order to shut down time-sharing
operations.
Removing system files for other purposes allows a system
manager to adjust system operation without ending timesharing.
For
example, if a disk currently operating as a swapping device
malfu~ctions during timesharing, the system manager can:
o

Decrease the allowed number of logins appropriately

Remove the swap file for that device

Dynamically add another device or file to replace the disk as
a swap file

Increase thE~ new allowed number of logins to take advantage of
the added swapping space

After shutting down the system, the system manager can disable the
malfunctioning unit to allow maintenance and to isolate the device
from time-sharing access.
Normal time-sharing operations can proceed
without further changes to the system.

7-271

List System Files
FO=23
List System File
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(23%), the system files code.

CHR$(N%), where N% designates the file to list as follows:
Meaning

Value
0%
1%
2%
3%
4%
5%
6%

Swap file 0
Swap file 1
Swap file 2
Swap file 3
Overlay file
Error message file
DECnet/E system file

CHR$(-l%) to list a system file.

5-30

Reserved; should be O.

Data Returned
Meaning

Bytes
5-6+

PPN. These bytes are 0 if the device is
non-file-structured.

7-10+

File name in Radix-50 format.
These bytes are 0 if the
device is non-file-structured.

11-12+

File type in Radix-50 format.
These bytes are 0 if the
device is non-file-structured.

13-22

Not used.

23-24+

Device name in ASCII format.

25+

unit number.

26+

unit number flag.

27-30

Not used.

7-272

List System Files
FO=23
Privileges Required
None.
Possible Errors
Meaning

ERR Value

?CAN'T FIND FILE OR ACCOUNT
The number specified in byte 3 refers to a file that
is not currently installed.

?ILLEGAL SYS() USAGE
The number specified in byte 3 is less than 0 or
greater than 6.

Discussion
This SYS call returns the file specification of a currently installed
system file.
When the file is on a non-file-structured device, the
call returns the device name. When toe file is on a file-structured
device, the call returns the device name, PPN, file name, and file
type.

7-273

Create a Job
FO=24
(UU.JOB)
Create a Job

The Create a Job SYS call allows appropriately privileged users to
create logged-out jobs. In addition, it allows both privileged and
nonprivileged users to create jobs that are automatically logged in to
an account either to run a program, or to enter a keyboard monitor.
This section presents the data passed and returned for the three
functions of this call:
o

Create Logged-Out Job

Create Logged-In Job to Run a Program

Create Logged-In Job to Enter a Keyboard Monitor

The discussion at the end of this section provides further details on
all three functions.
Data Passed -

Logge~Out

Job

Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(24%), the create a job code.

CHR$(N%), where N% is 128% to create the job even if logins
are disabled. Specify 0% for N% to create the job only if
logins are enabled.

Reserved; should be O.

5-6+

The project-programmer number of the program to run.

7-10+

File name of the program to run, in Radix-50 format.

11-12+

File type of the program to run, in Radix-50 format.

13-22

Ten bytes of information to be placed into the created job's
core common area. Note that an eleventh byte is appended
that contains the job number times 2 of the job that
executed the SYS call.

23-26+

The device name and unit number of the program to run.

7-274

create a Jot
FO=24
27-28

The parameter word to be passed to the program to run.
The
parameter word has exactly the same format and functions as
the eCL command parameter word.
Note that for jobs created
under the BASIC-PLUS run-time system,_ the parameter word
equals the program line number to which control is
transferred when the job runs.

29-30

Reserved; should be O.

Data Returned
Meaning

Bytes
3

The job number times 2 of the job just created.

Data Passed - Logged-In Job to Run a Program
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(24%), the create a job code.

CHR$(N%), where N% can contain the following bit values when
you create a logged-in job to run a program:
Value

Meaning

Do not pass the user logicals of the creating account
to the new job.
(Contents of core common are still
passed.)

Create the job with current privileges equal to
"none."

Create the job with the authorized privileges of the
new job equal to the authorized privileges of the
job's account ANDed with the current privileges of the
calling job.
If this bit is not set, the new job is
created with the authorized privileges of the job's
account.

32%

Create the job logged in to the account specified in
bytes 13 and 14 (requires GACNT or WACNT privilege).

64%

Create logged in job.
You must specify this value for
a logged-in job.
The new job runs under the caller's
account unless you also specify 32%.
7-275

create a Job
FO=24
128%

Create the job even if logins are disabled.
This
value is ignored if you do not have JOBCTL privilege.
When you do not include this value, the job is created
only if logins are enabled.

Keyboard to attach the new job to.
To indicate KBO: use
128%.
Specify a value of 0 in this byte to create a
detached job.

5-6+

The PPN of the program to run.

7-10+

File name of the program to run, in Radix-50 format.

11-12+

File type of the program to run, in Radix-50 format.

13-14

The account under which the job will run (requires GACNT or
WACNT privilege; bit 32% must be set in byte 3).
If you do
not have the GACNT or WACNT privilege, set both bytes to O.

Priority of the new job (requires TUNE privilege).
If you
specify 0, the system uses the caller's values.
Use 255% to
explicitly specify priority O. Users without TUNE privilege
must set this byte to O. Note that if you create the job on
a pseudo keyboard, the system reduces the priority to the
controlling job's priority.

Run burst of the new job (requires TUNE privilege).
If you
specify 0, the system uses the caller's values.
Users
without TUNE privilege must set this byte to O.

Maximum job size of the new job (requires TUNE privilege).
If you specify 0, the system uses the caller's values.
Users without TUNE privilege must set this byte to O.

18-22

Reserved; should be O.

23-26+

Device containing the program to be run.

27-28

The parameter word.

29-30

Reserved; should be O.

Data Returned
Bytes
3

Meaning
The job number times 2 of the job just created.

7-276

Create a Job
FO=24
Data Passed - Logged-In Job to Enter a Keyboard Monitor
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(24%), the create a job code.

CHR$(N%), where N% can contain the following bit values when
you create a logged·in job to enter a keyboard monitor:
Value

Meaning

Do not pass the user logicals of the creating account
to the new job.
(Contents of core common are still
passed.)

Create the job with current privileges equal to
"none."

16%

Enter keyboard monitor instead of running a program."
(You must include this value.)

32%

Create job to run under the account specified in bytes
13 and 14 (requires GACNT or WACNT privilege).

64%

Create logged·in job.
(You must include this value.)
The new job runs under the caller's account unless you
also specify 32%.

128%

Create job even if logins are disabled.
This value is
ignored if you do not have JOBCTL privilege. When you
do not include this value, the job is created only if
logins are enabled.

Keyboard to attach to.
The value you specify must be
nonzero.
To indicate KBO: use 128%.

5-6

Reserved; should be O.

7·10

Run·time system name in Radix·50 format.
The run· time
system you specify must be installed and must be a keyboard
monitor.
Specify 0 for the system's default keyboard
monitor, DCL.
7·277

Create a Job
FO=24
11-12

Reserved; should be O.

13-14

Account under which job will run (r.equires GACNT or WACNT
privilege; the value 32% must be included in byte 3).
If
you do not have the GACNT or WACNT privilege, specify 0 in
both bytes.

Priority of new job (requires TUNE privilege).
If you
specify 0, the system uses the caller's values.
Use 255% to
explicitly specify priority O.
Users without TUNE privilege
must set this byte to O.
Note that if you create the job on
a pseudo keyboard, the system reduces the priority to the
controlling job's priority.

Run burst of the new job (requires TUNE privilege).
If you
specify 0, the system uses the caller's values.
Users
without TUNE privilege must set this byte to O.

Maximum job size of new job (requires TUNE privilege).
If.
you specify 0, the system uses the caller's values.
Users
without TUNE privilege must set this byte to O.

18-30

Reserved; should be O.

Data Returned
Meaning

Bytes
3

The job number times 2 of the job just created.

Privileges Required
None

Create a job in your own account

GACNT

Create a job in another account in the group

WACNT

Create a job in any account, or create a logged-out job

EXQTA

Ignore detached-job and total-job quota on create

JOBCTL

Create a job even if no logins are set

TUNE

Specify a priority, run-burst, or maximum job size when
creating a job

7-278

create a Job
FO=24
Possible Errors
Meaning
?NO ROOM FOR USER ON DEVICE
The new job cannot be created.

ERR Value
4

Probable causes are:

Further logins are disabled, and byte 3 does not
include the value 128%. Or, logins are disabled
and byte 3 contains the value 128%, but you do
not have JOBCTL privilege.

The system's job or swap slots are currently
full.

?CAN'T FIND FILE OR ACCOUNT
You have sufficient privilege to create a logged-in
job, but the system cannot log the job in.
Possible
causes are that you specified a nonexistent account
or a no-user account.

~~NOT

A VAL I D DEVI CE
The keyboard number specified in byte 4 is invalid.

?DEVICE NOT AVAILABLE
The keyboard specified in byte 4 is open, is in use,
or is not assigned to the calling job. A user
without sufficient privilege can also get this error
if the system manager has restricted the device to
users with the DEVICE privilege.

?PROTECTION VIOLATION
You do not have the necessary privilege to perform
the specified operation.

?ILLEGA:L SYS() USAGE
You are trying to create a logged-in job to enter a
keyboard monitor, but did not supply a keyboard
number in byte 4.

?NO BUFFER SPACE AVAILABLE
You are trying to create a logged-in job, but not
enough XBUF is available for temporary storage of
your current job's core common and user logicals.

Note that when you create a logged-in job, you can also get any error
that can occur while logging in, running a program, or those errors
associated with the run-time system.
If such an error occurs, the
monitor kills the new job and returns the error to your job instead.
7-279

create a Job
FO=24
Discussion
Creating a Logged-Out Job
If you have the WACNT privilege, you can use this call to create
logged-out jobs. To do so, specify the complete file specification of
the program the created job is to run in bytes 7-12. You must include
the PPN in bytes 5 and 6; there is no default~
The program must be compiled (executable).
The created job is not logged in when it runs.. Therefore, all files
accessed by the job must be completely specified, including PPNs.
Because the created job runs logged out, the system kills the job if
it fails or exits.
The created job runs at priority zero, which, in the case of an
infinite loop, can seriously d~grade system performance. To avoid
this condition, have the created job reset its priority on execution.
Note that this option is provided for compatibility with previous
versions of RSTS/E. Due to the limitations of the Create Logged-Out
Job function, new applications should use the Create Logged-In Job
function instead.
Creating a Logged-In Job
Both appropriately privileged and nonprivileged users can create jobs
that are automatically logged in to an account, either to run an
executable program or to enter a keyboard monitor at the P.NEW entry
point (see the RSTS/E System Directives Manual).
If you specify 64% in byte 3, the job is created and logged in to your
own account. If you have GACNT or WACNT privilege (as appropriate),
you can create the job to run under an account other than your own
account by specifying 64% and 32% in byte 3 (specify the account under
which the job will run in bytes 13 and 14). In addition, users who
have the JOBCTL privilege can create the job even if logins are
disabled by adding 128% in byte 3.
The value in byte 4 determines if the new job is logged in detached or
attached. If this byte is 0, the new job is created logged-in and
detached. If the value in this byte is nonzero, the system sets the
sign bit of the byte to 0, and uses the resulting value as the
keyboard number to attach to. The terminal you specify in this byte
must be a free terminal or must be allocated to the calling job. In
addition, if you do not have the DEVICE privilege you cannot specify a
terminal that is restricted.

7-280

Create a Job
FO=24
When a new job is created logged-in, it receives a copy of
core common and user logicals of the calling job.
You can
in byte 3 to suppress passing of user logicals.
XBUF must
available because it is used for temporary storage of this

all of the
set bit 1
be
data.

If the new job is detached, its channel 0 Device Data Block (DDB)
points to the console terminal of the calling job.
If you have the TUNE privilege, you can pass priority, run burst, and
memory maximum values to the new job in bytes 15, 16, and 17.
If you
pass zeros in these bytes, the system takes them from the calling job.
If you do not have TUNE privilege, the system automatically passes the
values from the calling job to the new job, so specify 0 in all three
bytes.
Note that ij: you create the job on a pseudo keyboard, the
system reduces the priority to the controlling job's priority if you
specify a higher priority.
Creating a Logged-In Job to Enter a Keyboard Monitor
As previously mentioned, both appropriately privileged and
nonprivileged users can use this call to enter a keyboard monitor
instead of running a program.
1~0

enter a keyboard monitor, you must specify 64% and 16% in byte 3.
See the Data Passed section for other values you can specify.

Specify the name of the keyboard monitor to enter in bytes 7-10. When
you specify a keyboard monitor, the new job must be attached to a
keyboard (indicated in byte 4).
If you specify zeros in bytes 7-10,
the system uses the system's default keyboard monitor (DeL). Note
that the keyboard monitor you specify must be an installed run-time
system.
Bytes 13-17 are used as previously described for logged-in jobs that
run a program.

7-281

Wildcard PPN Lookup
FO=25
(UU.PPN)
Wildcard PPN Lookup
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(25%), the look up an account number by index code.

3-4

CHR$(N%)+CHR$(SWAP%(N%», where N% is the index of the
requested PPN.
If N% is 0, the call returns the PPN of the
first account on the disk that matches the wildcard
specification.
If N% is nonzero, the call returns the PPN
of the N+l account on the specified disk that matches the
wildcard specification.

5-6

The requested PPN. A value of 255 in either field
represents a wildcard. A value of 0 for N% in bytes 3-4 and
a non-255 value in bytes 5-6 (no wildcard) verifies the
existence of the specified account on the disk.
If bytes
3-4 and 5-6 are zero, the user's account is looked up.
If
bytes 3-4 and 5-6 are nonzero and contain a PPN with no
wildcard characters, the call returns error 5.

7-22

Reserved; should be O.

23-24+

The device name, which must be a disk.
If bytes 23 and 24
are both 0, SYO:
(the system disk, not the entire public
structure) is used.

25+

The device unit number.

26+

The unit number flag.
disk) is used.

27-30

Reserved; should be zero.

If byte 26 is 0, SYO:

7-282

(the system

Wildcard PPN Lookup
FO=25

Data Re'turned
Bytes

Meaning

3-4

Internal code.

5-6+

The PPN located by the call.

7-30

Not u.sed.

Privileges Required
DEVICE

Access a restricted device

Possible Errors
Meaning

ERR Value

?CAN'T FIND FILE OR ACCOUNT
The specified device in bytes 23-24+ is not a disk,
or no match exists for the specified index value in
bytes 3-4 (also see bytes 5-6).

?DEVICE IS RESTRICTED
The disk is restricted.
You need DEVICE privilege
to override this condition.

Discussion
This call allows you to specify a wildcard account number and
increment an index value to determine a matching PPN.
The wildcard
account specificati()n is in the form that the File Name String Scan
call (SYS -10, -23) returns.

7-283

Return Job Status
FO=26
(UU.SYS)
Return Job status
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(26%), the return job status code.

CHR$(J%), where J% is the number of the job for which status
is desired.
If J% is 0%, information on the caller's job is
returned.
If the caller does not have JOBCTL privilege, J%
is forced to 0%. Note that if a job is running on a pseudo
keyboard, its controlling job may examine the controlled job
regardless of privilege.

CHR$(S%), where S% is 0%, 1%, or 2%. The value of S%
determines the information returned on the job (see Data
Returned).

5-30

Reserved; should be O.

Data Returned
If S% is 0%:
Bytes

Meaning

The calling job's job number times two.

Not used.

Job number times two of the job for which data is being
returned.

Keyboard number of the job's console, if the job is
attached. The job is detached if (M%(4%) AND 128%)<>0%; in
this case, the keyboard number is equal to NOT M%(4%). A
program that uses this byte should test both possibilities
even if the program is not designed to run detached, because
any program can become detached if a dial-up line loses the
telephone connection, or if a sufficiently privileged user
detaches the job.

If the job is attached to a pseudo keyboard, this byte
contains the controlling job's job number times two, plus
one; otherwise, it is O.

7-284

Return Job Status
FO=26

If the job is swapped out, this byte contains the job's swap
slot location; otherwise, it is O.

7-8

The job's logged~in CPU time (least significant word) for
the current session in tenths'of. a second.

9-10

The job's current connect time in minutes.

11-12

The job's current
session.

13-14

The job's accumulated device time for the current session in
minutes.

The most significant byte of the job's ReT.

The most significant byte of the job's CPU time.

17-20

The job's name in two Radix-50 words.

21-22

The job's PPN.

23-26

The name of the job keyboard monitor in two Radix-50 words.

27-30

The name of the job's current run-time system in two
Radix-50 words.

~CTs

(least significant word) for this

If S% is 1%:
Bytes

Meaning

The calling job's job number times two.

Not used.

Job number times two of the job for which data is being
returned.

Keyboard number of the job's console.
If the number is
negative, the job is detached and the number is the one's
complement of the keyboard number.

5-6

The job's current flag word.

The job's current IOSTS byte.

The job's current information posting byte.

9-10

The job's current JBSTAT word.

7-285

Return Job Status
FO=26
11-12

The job's current JBWAIT word.

The size of the job's current user memory area in K words.

The job's control word from its memory control sub-block.

15-16

The job's current physical address in 32-word increments.

The job's priority.
privilege.

The job's allotted run burst in tenths of a second.
the caller does not have TUNE privilege.

The job's maximum allowable memory size in K words.

The value at offset 6 in the job's work block.
This value
is usually the channel number (times two) on which the job
is performing an I/O operation.

21-22

If bytes 9 through 12 indicate that the job is in a keyboard
wait state, bytes 21 and 22 contain the value at offset 12
(octal) in the job's work block.
This value is the timeout
parameter for input from the terminal.
If the value is
negative, it implies that the terminal is in a keyboard
monitor (CTRL/C) input wait state.

0 if the caller does not have TUNE
0 if

If bytes 9 through 12 indicate that the job is in an I/O
stall for a nonkeyboard device, bytes 21 and 22 contain the
generic name (in ASCII) of the device for which the job is
stalled.
If bytes 9 through 12 indicate that the job is in a FIP wait
state, byte 21 contains the byte value corresponding to the
currently executing FIP function and byte 22 has no meaning.
23-24

The value at offset 16 (octal) in the job's work block.
This value is usually an internal code that specifies
whether the job is reading or writing on the current I/O
channel.
If the job is in an I/O wait state and this value
is 2, the I/O operation is a read; if this value is 4, the
I/O operation is a write.

25-26

A pointer to the beginning of the job's Job Data Block.

27-28

A pOinter to the beginning of the job's second Job Data
Block.

29-30

If the job is a receiver, these bytes contain the address of
the job's first receiver identification block; otherwise,
these bytes are O.
7-286

Return Job status
FO=26
If S% is 2%:
Bytes

Meaning

The calling job's job number times two.

Not used.

Job number times two of the job for which data is being
returned.

Keyboard number of the job's console.
If the number is
negative, the job is detached and the number is the one's
complement of the keyboard number.

Job's current I-space s i z€' .

Job's current D-space size.

7-14

Job's current privilege mask.

Job's access type:
Value

Type

0%
1%
2%
4%
6%

Local
Di.alup
Batch
Network
Server ( jobs started by DECnet)

other values reserved

16-30

Reserved.

Privileges Required
None

Read the status of your own job or a job controlled by your
job

JOBCTL

Read the status of any job

TUNE

Read the priority or run burst of any job

7-287

Return Job Status
FO=26
Possible Errors
Meaning

ERR Value

?PROTECTION VIOLATION
The job whose status is requested does not exist.

?ILLEGAL SYS() USAGE
The job number whose status is requested is less
than zero or greater than JOB MAX.

7-288

Set/Clear/Read Current Privileges
FO=28
(UU.PRV)
Set, Clear, or Read Current Privileges
This call has two subfunctions:
o

Set/Clear Current Privileges

Read Current Privileges

Set/Clear/Read Current Privileges
To set or clear current privileges, specify the following bytes:
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(28%), the set/clear/read privileges code.

3-10

The privilege mask of bits to set.
Each set bit corresponds
to a bit that is to be turned ON in the privilege mask.

11-14

Reserved; should be

15-22

The privilege mask of bits to clear.
Each set bit
corresponds to a bit that is to be turned OFF in the
privilege mask.

23-30

Reserved; should be O.

To read current privileges, specify the following bytes:
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(28%), the set/clear/read privileges code.

3-30

Reserved; should be

7-289

Set/ClearjRead Current Privileges
FO=28
Data Returned
Bytes

Meaning

1-2

Not used.

3-10

Privileges now in effect.

11-30

Not used.

Privileges Required
None.
Possible Errors
None.
Discussion
This SYS call reads the current privilege mask or selectively sets
and/or clears bits in it.
This call is distinct from SYS call -21,
Drop/Regain Temporary Privileges, which only applies when you are
running a privileged program and then update the entire current mask
at once.
You pass the bits to set in bytes 3-10.
You pass the bits to clear in
bytes 15-22. Before setting the bits passed in bytes 3-10, the system
ANDs the bits passed with the authorized mask to prevent the caller
from setting unauthorized bits.
Note that this happens whether or not
temporary privileges are in effect.
In other words, a program with
temporary privileges can use this SYS call to drop any single
privilege, but it can regain only those that the user is authorized to
have.
The privileges in effect on completion of the SYS call are returned in
bytes 3-10. To simply read the current privileges, issue the SYS call
with zeros in bytes 3-30.
If a privileged program wants to find out what privileges the user (as
opposed to the program) has, it must perform a Drop Temporary
privileges SYS call (SYS -21) followed by a Read Privileges SYS call.
This makes sure that it will read the normal mask.
See Chapter 1 for more information about privileges.

7-290

Stall/Unstall System
FO=29
(UU.STL)
stall/Unstall System
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(29%), stall/unstall system code.

CHR$(N%), where N% is:
Value

4-30

Meaning

Return the system to normal ("unstalled") state.

Stall the system (suspend all active jobs).

Reserved; should be O.

Data Returned
No meaningful data is returned.
Privileges Required
HWCTL
l?ossible Errors
Meaning

ERR Value

?ACCOUNT OR DEVICE IN USE
You issued a stall request and the system was
already stalled.

?ILLEGAL SYS() USAGE
You issued an unstall request and the system was not
stalled.

7-291

Stall/Unstall System
FO=29
Discussion
This call suspends all currently active jobs except for the calling
job.
The purpose of the call is to stop all system activity before
spinning down the system disk to change the removable platter for
other applications.
This call is used primarily for the RC25 disk in
configurations where the system disk is on the fixeq part of the RC25
and you want to exchange the removable part of that same drive.
The
DCL SET SYSTEM/HOLD and SET SYSTEM/RELEASE commands use this call.
The calling job is not affected when the system is stalled and can
continue to perform any operation.
However, if the system is stalled
for the purpose of spinning down the system disk, an attempt to do
disk I/O to that disk results in an I/O error.
Note that logins are disabled while the system is stalled.

7-292

Third party Privilege Chec~
FO=31

(UU.3Pp)

Third party Privilege Check
])a ta Pa,s sed
l:lytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(31%), the third-party privilege check code.

3-4

Reserved; should be O.

5-6+

PPN to enable the third-party privilege check.
disable the third-party privilege check.

7-14

A privilege mask.

15-30

Reserved; should be O.

Zero to

Data Returned
None.
Privileges Required
None.
:Possible Errors
Meaning

ERR Value

BUF'FER SPACE AVAILABLE
A small buffer is needed to store the third party
information, but none is available.

?NO

:Discussion
This call enables or disables third-party privilege checking. This
call is primarily for server programs such as Print/Batch Services
(PBS) that run detached under a highly privileged account and perform
functions on behalf of normally less privileged users.
To maintain system security, these server programs must enforce
appropriate privilege restrictions that apply to the user issuing
requests to the server. For example, a print server must enforce the
file access restrictions on the user requesting a printout, but does
7-293

Third Party Privilege Check
FO=3l
not want to enforce the access restrictions to the printer device.
Third party privilege checking allows the server program to correctly
perform these checks.
In this call, the server job specifies 'the PPN and privileges of the
requesting user.
From that point, the monitor performs every
privilege check twice:
once against the privileges of the server job
itself, and once against the privileges of the third party.
This
continues until the server job issues the call again to cancel third
party privilege checking.
For example, a print server issues the third party privilege check
call to enable third party privilege checking prior to opening the
file to be printed.
If the requester is not allowed to access the
file, the open fails in the usual manner.
The account number of the
requester is part of the information passed in the call because the
interpretation of privilege flags and file protection code bits
depends on the account number of the requester.
In order to use the third party privilege check call, the server must
have the correct privilege mask for the requester.
The correct way to
obtain this information is for the server to issue the Send Message
with privilege Mask subfunction of the Send/Receive SYS call (see
Chapter 8).
The monitor inserts the requester's current privilege
mask as part of the message and sends it to the server, with a message
code of -11 to indicate the mask is present.
The server then stores
the requesting PPN and privilege mask, both from the message, and uses
them later in the third party privilege check call.
Server programs could use other methods to obtain privilege
information, such as reading the authorized privileges of the account
from the accounting data stored on disk.
However, this method does
not work in all cases.
For example, the request may have come from a
privileged program.
Ln this case, the privileges of the program, not
those of the user, are the relevant ones.
Or, the user may have
turned off some privileges with the SET JOB/PRIVILEGE command.
In
this case, the server should honor the lesser privileges.

7-294

Check Access Function

FO=32

(UU.CHK)

Check Access Function
This SYS call performs three privilege checking functions:
o

Check file access rights.
You can use this subfunction to
check access rights to a file of known protection code and
PPN.
You can also use this subfunction to define file-like
access rules for objects other than files.

Convert privilege name to mask.
You can use this subfunction
to convert a privilege name to its internal representation or
to determine whether a user has a specific privilege.

Convert privilege mask to name.
You can use this subfunction
to generate the symbolic form of a privilege mask.

Check File Access Rights
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(32%), the check access code.

CHR$(O%), the check file access rights code.

Reserved; should be O.

5-6+

PPN.

7-21

Reserved; should be O.

22+

Protection code of the file.

23-30

Reserved; should be

Data Returned
Bytes

Meaning

1-2

Not used.

3-4

The access flags.
The bits are set to indicate access
rights as follows.

7-295

Check File Access Rights
FO=32
Meaning

Bit

o
1
2
3-4

5
6
7

8-15
5-30

Create/rename rights are granted
Read access is not allowed
Write access is not allowed
Reserved
Execute access is not allowed
Accounting rights are granted, or PPN is your own.
See Discussion.
Accounting rights are granted. See Discussion.
Reserved

Not used.

Privileges Required
None.
Possible Errors
No errors are possible.
Discussion
This subfunction checks access rights to a file of known protection
code and PPN without opening it.
If you need to check a file's access rights but do not know the
protection code, or if you need to read or write to 'the file, the most
straightforward method is to simply open it instead~ and then check
for an error on open or the read/write access flags returned in the
STATUS variable. See the BASIC-PLUS Language Manual for a description
of the STATUS variable.
You can also use this subfunction to define file-like access rules for
objects other than files. For example, Print/Batch Services (PBS)
uses it to control access to jobs.
The difference between bits 6 and 7 in the returned flags is that bit
6 is set if the PPN matches the caller's without any privilege
requi.rements, whereas bit 7 is set only if the caller has GACNT or
WACNT privileges, even if the PPN is the caller's.

7-296

convert Privilege Name to Mask
FO=32
Convert Privilege Name to Mask
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(32%), the check access code.

CHR$(l%), the convert privilege name to mask code.

4-6

Reserved; should be O.

7-12

The privilege flag name. This must be a six-character
uppercase ASCII string. For flag names of fewer than six
characters, fill the extra space at the end with nulls.
Specify ALL to indicate all privileges.

13-30

Reserved; should be O.

I>ata Returned
Bytes
1-2
3

Meaning
Not used.
Flag byte. 0 if the job currently has the specified
privilege, or the job has all privileges if ALL was
specified in bytes 7-12. Otherwise, 1.

4-6

Not used.

7-14

A privilege mask with one bit set. If you specified ALL in
bytes 7-12, the call returns a privilege mask with all valid
bits set (all privilege bits that currently have meaning).

15-30

Not used.

Privileges Required
None.

7-297

Convert Privilege Name to Mask
FO=32
Possible Errors
Meaning

ERR Value

?CAN'T FIND FILE OR ACCOUNT
The privilege name passed in bytes 7-12 is not a
valid privilege name.

Discussion
This call performs two functions:
o

Converts privilege names to their internal representation.
This is useful, for example, when issuing SYS call 28,
Set/Clear/Read Current Privileges.

Determines whether a user has a given privilege. A system
program might do this either to verify that a user has
sufficient privilege to proceed or to allow the user
additional choices.

7-298

Convert Privilege Mask to Name
FO=32
Convert privilege Mask to Name
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(32%), the check access code.

CHR$(2%), the convert privilege mask to name code.

4-6

Reserved; should be O.

7-14

Privilege mask.

15-30

Reserved; should be O.

Data Returned
Bytes

Meaning

The current job number times 2.

2-6

Not used.

7-14

A privilege mask, with the first set bit cleared (the bit
for which the name is returned in bytes 15-20). Unused bits
are also cleared.

15-20

The privilege name, as an uppercase ASCII string, padded
with nulls to six characters.

16-30

Not used.

Privileges Required
None.

7-299

Convert Privilege Mask to Name
FO=32

Possible Errors
Meaning

ERR Value

?CAN'T FIND FILE OR ACCOUNT
The privilege mask passed in bytes 7-14 is zero, or
no defined privilege bits are set.

Discussion
This call scans the privilege mask passed in bytes 7-14. First the
call clears undefined bits, then it looks for a set bit. If none are
found, it returns the error ?Can't find file or account (ERR=5).
Otherwise, it clears the first bit found and looks up its name. The
call returns the name of the privilege in bytes 15-20.
A program can use this function to generate the symbolic form of a
privilege mask simply by copying the mask into bytes 7-14, and
repeatedly issuing this subfunction until the error message is
returned. Each time the function returns success, the caller prints
out the string in bytes 15-20.

7-300

Open Next Disk File
FO=33
(UU.ONX)
Open Next Disk File
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(33%), the open next disk file code.

The channel number times twd.

Reserved; should be O.

5-6+

PPN of the file's owner. A value of zero indicates the
current account.
The specification cannot contain
wildcards.

7-10+

File name in Radix-50 format.
wildcards.

The specification can contain

11-12+

File type in Radix-50 format.
wildcards.

The specification can contain

13-16

Reserved; should be O.

17-18

CHR$(N%)+CHR$(SWAP%(N%», where N% specifies one of the
following OPEN modes:
Value
0%
1%
2%
5%
8%
16%
32%
256%
2048%
4096%
8192%
16384%
32767%+1%

Mode
Normal read/write.
UPDATE mode.
APPEND to file.
Guarded UPDATE (4%+1%).
Special extend.
Do not update access dates to files; do not
grant write access (requires DATES privilege).
Do not grant any access to files (directory
lookup only).
User data caching.
Sequential data caching.
Read normally regardless.
Open file read only.
Include files marked-far-delete.
Mode bits are real; you must specify this
value for the other OPEN bits to be examined.

See Chapter 1 for more information about OPEN modes.

7-301

Open Next Disk File

FOz33
19-22

Reserved; should be O.

23-24+

Device name; must be a disk. A zero in both bytes indicates
If you do not specify a name,
SY: (the public structure).
SY: is used.

25-26+

Device unit number.

27-30

Reserved; should be O.

Data Returned
Meaning

Bytes
1-3

Not used.

File size (MSB) .

7-10+

File name in Radix-50 format.

11-12

File type in Radix-50 format.

13-14

File size ( LSB) .

15-16

Date of last access.

17-18

Date of creation.

19-20

Time of creation.

File cluster size.

File protection code.

23-24

Device name.

25-26

Device unit number and flag.

27-28

File identification index.

29-30

Device description.

Privileges Required
None

Access your own file, or a file in another account if the
protection code permits

GREAD

Read a file in any account within the group

7-302

Open Next Disk File

FO=33
WREAD

Read a file in any account

C;WRITE

write a file in any account within the group

WWRITE

write a file in any account

DATES

Use mode bit 16% to suppress updating of last access date

DEVICE

Access a restricted device

Possible Errors
Meaning

ERR Value

?CAN'T FIND FILE OR ACCOUNT
No more files match the passed specification.
channel is closed.

The

-:> ILLEGAL

SYS () USAGE
The parameters passed in the call are inconsistent
with currently open channel.

?DISK PACK IS LOCKED OUT
The disk pack is locked, and you do not have the
DEVICE privilege.

?DEVICE NOT FILE-STRUCTURED
You tried to open a device that is not a disk.

This SYS call also returns device-dependent errors, such as ?Device
hung or write locked (ERR=14) and ?Disk pack is not mounted (ERR=21).
Discussion
This SYS call opens a disk file or a series of disk files matching a
wildcard specification.
The call requires an I/O channel to use, and
grants access to the file if so desired.
When you specify a closed channel, this call finds the first file that
matches the specification. When you specify an open channel, the call
finds the next file that matches the specification.
If there are no
more files to find, this call closes the channel.
Note BASIC-PLUS cannot access the channel, even though it is open.
access the channel, use a MACRO subprogram (see the RSTS/E System
Directives Manual).

7-303

set Device Characteristics and System Defaults
FO=34
(UU.CFG)
Set Device Characteristics and System Defaults
o

Set Device Characteristics

Set Line Printer Characteristics

Set System Defaults

Load Monitor Overlay Code and Return Status/Remove Monitor
Overlay Code

Set Device Characteristics
Data Passed
Meaning

Bytes
I

CHR$(6%), the SYS call to FIP.

CHR$(34%), the set device characteristics or change system
defaults code.

CHR$(O%), the set device characteristics subfunction code.

Reserved; should be O.

CHR$(E%+P%+L%), the flags to indicate changes to device
parameters:
E%

ENABLED/DISABLED status change flag.
E% = 0%
E% - 1%

RESTRICTED/UNRESTRICTED device ownership change flagP% = 0%

P% = 2%
L%

No change.
Use value in next byte to change status.

No change.
Use value in next byte to change ownership.

LOCAL/MODEM keyboard (KB:) control change
L% .. 0%
L% = 4%

flag~

No change.
Use value in next byte to change KB:
modem control.

You can use combinations of the above values.
7-304

Set Device Characteristics

FO=34
6

CHR$(E%+P%+L%), the values you use to change device
parameters.
If byte 5 is 0%, then this byte must also be
0%.
E%

ENABLE/DISABLE flag.
E%
E%

0%
1%

Enable device.
Disable device.

RESTRICTED/UNRESTRICTED flag.
P% = 0%
P%
2%

No privilege needed for device ownership.
DEVICE privilege needed for device ownership.

LOCAL/MODEM keyboard (KB:) control.
L%
L%

0%
4%

No MODEM control
Enable MODEM control.

You can use combinations of the above values.
7-22

Reserved; should be zero.

23-24+

Device name on which to perform the operation.
cannot be a disk.

25+

Device unit number.

26+

Unit number flag.
Should be CHR$(255%) to indicate the
device unit number is real.

27-30

Reserved; should be zero.

The device

Data Returned

Meaning

Bytes
1-5

, Not used.

CHR$(E%+P%+L%), the bit flags indicating device status.
E%
P%

0 if device enabled and free; 1 if disabled or in use.
=

2 if device ownership requires privilege; 0 if not.

L% = 0 if keyboard is LOCAL; 4 if under MODEM control.
7

CHR$(N%), where N% is the job number times 2 of current
device owner.
If N%=O%, the device is enabled and free.
N% is an odd integer (other than 3%), the device was
7-305

set Device Characteristics
FO=34

disabled by the monitor and cannot be reenabled. If N% is
3%, the device was disabled by this call and can be enabled
by this call.
Not used.

8-30

Privileges Required
HWCFG

Change restricted or modem control flags

HWCTL

Enable or disable a device

Possible Errors
Meaning

ERR Value

?ACCOUNT OR DEVICE IN USE
You attempted to disable a device that was either' in
use or had been previously disabled. Or, you tried
to alter the local/modem characteristic of a device
that was in use.

?DEVICE NOT AVAILABLE
You attempted to enable a device that was not
disabled through the use of this call. For example,
the monitor disabled the device. Or, you tried to
alter the local/modem characteristic of a disabled
device.

?PROTECTION VIOLATION
You attempted to alter the device characteristics of
a disk unit.

?ILLEGAL SYS() USAGE
You attempted to perform an invalid subfunction by
specifying a value of less than 0 or greater than 3
in byte 3 of the data passed.

Discussion
This subfunction allows a caller with the appropriate privilege to set
the following device characteristics online:
o

Enable or disable a device.

Designate a keyboard as local or modem.

Designate a device as restricted or unrestricted.
7-306

October 1985

Set Line Printer Characteristics
FO=34
Set Line Printer Characteristics

Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(34%), the set device characteristics or change system
defaults code.

CHR$(l%), the set line printer (LP) characteristics
subfunction code.

Reserved; should be O.

CHR$(N%), where N% is:
Value

Meaning

No change.

1-254

New value for the default printer page width.

CHR$(N%), where N% is:
value

Meaning

No change.

1-255

New value for the default printer form length.

7-8

CHR$(N%), where N% is 0 for no change or is the combined
value of bits to set in the ,characteristics flag word.
See
the Discussion for a description of these bit flags.

9-10

CHR$(N%), where N% is 0 for no change or is the combined
value of bits to clear in the characteristics flag word.
See Discussion.

CHR$(N%), where N% is 0 for no change or nonzero to indicate
a change to the line printer special character.

If byte 11 is CHR$(l%), then this byte is CHR$(N%), where N%
is the ASCII value of the new special character.
Note that
CHR$(O%) disables special character handling.
The
/SPECIAL_CHARACTER qualifier of the SET TERMINAL command
uses this feature.
See the RSTS/E System Manager's Guide
for more information.
7-307

Set Line Printer Characteristics
FO=34
13-22

Reserved; should be O.

23-24+

Device name in two ASCII characters.

25+

Device unit number.

26+

unit number flag.
Should be CHR$(255%) to indicate the
device unit number is real.

27-30

Reserved; should be O.

Must be LP.

Data Returned
Meaning

Bytes
1-4

Not used.

Width of the line printer unit specified in bytes 23-26 in
Data Passed.

The default printer form length.

7-8

Current characteristics flag word.
See the Discussion for a
description of these bit assignments.

9-11

Not used.

Value of the line printer special character.
The
/SPECIAL CHARACTER qualifier of the SET TERMINAL command
uses this feature.
See the RSTS/E System Manager's Guide
for more information.

13-30

Not used.

Privileges Required
HWCFG
Possible Errors
Meaning

ERR Value

?NOT A VALID DEVICE
You attempted to set the characteristics of a
printer that the monitor does not support, or the
device name specified in bytes 23-24 was not LP.

7-308

set Line Printer Characteristics
FO=34
?ILLEGAL SYS() USAGE
You attempted to perform an invalid subfunction by
specifying a value of less than 0 or greater than 3
in byte 3 of the data passed.

%ILLEGAL NUMBER.
You attempted to set a value of 3 in the LPTCHR flag
word.
See the Discussion for a detailed description
of this error condition.

Discuss:ion
This subfunction allows a caller with HWCFG privilege to set the
following line printer characteristics online:
o

Change the default page width

Change the default form length

Change or read the line printer characteristic flag word.

Change or read the line printer special character.

Bytes 7,·8 set bits in the characteristics flag word.
Bytes 9-10 clear
bits in the characteristics flag word.
Legal values are the
f'ollowing:

Value
1%
2%
4%
8%
16%
32%
64%
128%
256%
512%
1024%
2048%

Meaning
Allow BS for backspace (LA180, LNOl)
Do not process BS as backspace
Allow 8-bit characters (LN01)
Allow nonprinting characters (LNOl)
No fill for FF
Allow EOT
No CR required before LF, VT, FF (LPll, LNOl)
Ignore CR if next character is LF (LPll, LNOl)
No TAB expand (LNOl)
Reserved
Reserved
Allow lower case (LNOl)

Note that a value of 3 in the bottom two bits of the characteristics
word is illegal.
If you attempt to set both bits, the call returns
the error %Illegal number (ERR=52).

7-309

Set System Defaults
FO=34
Set System Defaults

Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(34%), the set device characteristics or change system
defaults code.

CHR$(2%), the set system defaults subfunction code.

Reserved; should be O.

5-6

CHR$(N%) + CHR$(SWAP%(N%)), where N% is:

Value

Meaning

No change.

1%-300%

New value for powerfail delay.

CHR$(N%), where N% is:
Value

Meaning

No change.

Numeric date format (yy.mm.dd).

255%

Alphabetic date format (dd-mmm-yy).

CHR$(N%), where N% is:
Value

Meaning

No change.

24 hour time format (hh:mm).

255%

12 hour time format (hh:mm AM/PM).

7-310

Set System Defau1t~
FO=3 i

CHR$(N%), where N% is:
Value

Meaning

No change.

DOS magnetic tape label default.

255%

ANSI magnetic tape label default.

Reserved, should be zero.

11-12

Default magnetic tape density in bpi.

13-30

Reserved; should be zero.

Data Returned
Meaning

Bytes
1-4

Not used.

5-6

Number of seconds to delay on powerfail restarts.

1 if Numeric date format is the default;

255 if Alphabetic.

1 if 24 hour time format is the default;

255 if 12 hour.

1 if DOS magnetic tape labeling is the default;

Not used.

11-12

Magnetic tape density in bpi.

13-30

Not used.

255 if ANSI

Privileges Required
HWCFG

Set the density default

SWCFG

Set the date format, time format, label default, or
powerfail delay

October 1985

7-311

Set System Defaults

FO=34
possible Errors

Meaning

ERR Value

?ILLEGAL SYS() USAGE
You attempted to perform an invalid subfunction by
specifying a value of less than 0 or greater than 3
in byte 3 of the data passed.

%INTEGER ERROR
You attempted to specify an value greater that 300
for the powerfail delay value in bytes-5-6.

Discussion

This subfunction allows a caller with the appropriate privilege to set
the following system defaults online:
o

Date format

Time format

Magnetic tape label

Magnetic tape density

Powerfail delay

The DeL SET SYSTEM command uses this call. See the RSTS/E System
Manager's Guide for more information on system defaults.

7-312

Load/Remove Monitor Overlay Code
FO=34
]~oad

Monitor

O~rerlay

Code and Return Status/Remove Monitor Overlay

Code

Data Passed

Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(34%), the set device characteristics or change system
defaults code.

CHR$(4%), the load/remove monitor overlay code subfunction
codeo

Reserved; should be O.

CHR$(N%), where N% is:

7-8

9-30

Load monitor overlay code and return status

Remove monitor overlay code

Reserved; should be O.
The internal overlay name in Radix-50.
defined overlay names:

The following are

LIN

SYS call -25; Manipulate File, Pack, and Account
Attributes

UUO

SYS calls -3, -12, -29; Get Monitor Tables, Parts I,
II, III. SYS call -8; Get Open Channel Statistics.
SYS call 20; Convert Date and Time. SYS call 26;
Return Job status. SYS call 9; Return Error Messages.

DLN

The RENFQ and DLNFQ subfunctions of the CALFIP monitor
directive. This code handles file delete and rename
operations. See The RSTS/E System Directives Manual
for details.

DIR

SYS calls 15, 17; Directory Lookup.

PFB

Miscellaneous functions used in indirect command file
processing and DCL.

TRM

SYS call 16; Set Terminal Characteristics.

Reser.ved; should be O.
7-313

LoadjRemove Monitor Overlay Code
FO=34
Data Returned for LoadjReturn Status
Meaning

Bytes

1-4

Not used.

5-6

Amount of XBUF used for overlay, in bytes.
not loaded.

7-30

Not used.

0 if overlay is

Data Returned for Remove
No meaningful data is returned.
Privileges Required
SWCFG
Possible Errors for Load/Return Status
ERR Value

Meaning
?ACCOUNT OR DEVICE IN USE
The overlay you specified is already loaded

?CAN'T FIND FILE OR ACCOUNT
The overlay name is not valid.

?NOT A VALID DEVICE
The overlay you specified is not loadable.

?PROTECTION VIOLATION
You don't have SWCFG privilege.

?NO BUFFER SPACE AVAILABLE
There is not enough available extended buffer space
(XBUF) to load the overlay.

Possible Errors for Remove
Meaning

ERR Value

?CAN'T FIND FILE OR ACCOUNT
The overlay name is not valid.

7-314

Load/Remove Monitor Overlay Code
FO=34
?PROTECTION VIOLATION
You don't have SWCFG privilege.

?DISK PACK IS NOT MOUNTED
The overlay name you specified is not loaded.

Discussion
This subfunction allows a caller with SWCFG privilege to make certain
monitor overlay code memory resident.
This can enhance system
performance if the code is frequently used.
The SYS calls grouped in overlay code UUO return monitor, file, and
job information.
You should make these calls memory resident in
almost all cases.
The system uses file delete/rename code (overlay code DLN) whenever
you delete and rename files.
Make this code memory resident if your
system is large or if your applications require a large number of file
delete and rename operations.
The directory lookup code (overlay code DIR) gathers information about
disk directories, performs wildcard disk file lookups, and manipulates
file identification blocks for certain files.
The CATALOG command in
BASIC-PLUS and the PIP.SAV program use this code to obtain directory
information.
The DeL DIRECTORY and COpy commands also use this code.
Make this code memory resident if you frequently use any of these
programs or commands.
The attribute code (overlay code LIN) performs file attribute
read/write operations.
Make this code memory resident if:
o

You plan to use languages such as COBOL-Bl, BASIC-PLUS-2, and
FORTRAN-77.

You plan to use the Task Builder.

You plan to use RMS-ll.

The indirect command file processing code (overlay code PFB) performs
miscellaneous functions related to ICFP.
Make this code memory
resident if your system frequently uses indirect command file
processing.
The set terminal code (overlay code TRM) sets and reads terminal
characteristics.
The SET TERMINAL command also use this code.
Make
this code memory resident if your applications use features that
frequently reset terminals (for example, private delimiters).

7-315

Load/Remove Monitor Overlay Code
FO=34
The internal overlay names are subject to change in future releases.
In addition, the actual function performed by the overlays may change,
without a corresponding name change.
The DeL LOAD/OVERLAY and UNLOAD/OVERLAY command uses this call.
See
the RSTS/E System Manager's Guide for more information about these
commands.
)

7-316

PEEK Function

The PEEK Function
The PEEK function lets a user with RDMEM privilege examine any word
location in the monitor part of memory.
The user program can examine
words in small or large buffers, in the resident portion of the file
processor, and in the low memory and tables section of memory.
The
function does not allow a user program to examine the contents of
another user's program.
Note
When you use the PEEK function, be aware that DIGITAL
reserves thE~ right to change the monitor structure and
internal addresses at any time, except those addresses
listed in Table 7-9.
In addition, accessing some
device registers can cause unpredictable system
results.
Do not use PEEK to examine device registers.
To protect against this, PEEK requires SYSMOD
privilege if the specified address is within the
device register address range (160000 octal or
higher).
The PEEK function has the form:
1%

= PEEK(J%)

The function takes an (even) integer argument (J%) and returns an
integer value (1%).
The value returned is the contents of the address
in memory specified by the argumento
Because addresses of word
locations are always even on the PDP-ll computer, and odd addresses
indicate byte locations, you must always be careful to specify an even
integer address as the argument to PEEK.
To examine an odd address,
you must specify the next lower integer as the argument to PEEK.
The
contents of the odd address is the high order byte of the value
returned by PEEK.
You normally use PEEK to examine either addresses returned by Get
Monitor Tables calls or addresses of fixed monitor locations.
Possible Errors
Meaning

ERR Value

?PROTECTION VIOLATION
A user without RDMEM privilege attempted to execute
this call.

7-317

PEEK Function

?ODD ADDRESS TRAP
The address specified as an argument to PEEK is odd
or an attempt is made to reference a nonexistent or
odd address.
(For the PDP-ll/23 and 11/24, this
error occurs only if nonexistent addresses are
referenced. )

?MEMORY MANAGEMENT VIOLATION
The address specified as an argument to PEEK is
illegal (not mapped in the monitor).

Fixed Locations in Monitor
The information shown in Table 7-9 is stored in fixed locations in the
monitor part of memory and is obtained by executing a PEEK(X%), where
X% is the address shown.
Table 7-9:

Monitor Fixed Locations

+ - - - - - - - - - - - - + - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - '. - - - - - .. - - - - - - - - - - - - - - - - - ....
Address
I
I
(decimal) I Name I
Meaning
+- - - - - - - - - - - -+- - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - ,. - - - - - - - - - - - - - - - - - - - - - - - ...'

36(word)

IDATE I The date when the system was last started.

38(word)

ITIME I The time of day when the system was last
I started.

512(word)

DATE

I
I

514(word)

TIME

I
I Current time of day.

S18(byte)

JOB

Current system date.

I
I
I

Job number times 2 of the job currently
running (always is the user's own job
I number). For example:

I
I J% = (PEEK(518%) AND 255%)/2%
I
I

where J% is the user's job number.

520(word)

JOBDA I Address of the job data block (JDB) of the
I currently running job (always the user's own
I Job Data Block).

522(word)

JOBF

I
I

Address of the JDFLG word in the job data

I block of the currently running job (always
I

the user's own Job Data Block).
7-318

PEEK Function

Table 7-9:

Monitor Fixed Locations (Cont.)

+. - - - - .. - .• - - - - - + - - - - - .. - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
Address!
I
(decimal) I Name I
Meaning
+. - - - - - - .• - - - - _.+ - - - - - •. - + - - - - - - - - - - - - - _. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +

I
I
I

524(word)

I
I
I lOSTS I Address of the JDlOST (low) byte and JDPOST
I
I (high) byte in the Job Data Block of the
I

I currently running

job (always the user's own

I
I Job Data Block).
+. - - - - - - .. - - - - - + - - - - - .. - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +

Finding the Current PPN
Two methods exist for a program to determine the PPN under which it is
running~
The first method, available to all users, is to execute the
Return Job Status SYS call (SYS 26).
The second method, available only to users with RDMEM privilege, is
slightly faster and involves executi.ng the PEEK function to examine
two bytes in the second Job Data Block (JDB2) of the job.
The
contents of the JDB2 bytes 24 and 25 is the PPN of the current job.
The high byte returned by PEEK is the project numbe~; the low byte is
the programmer number.
The address of the JDB of the currently
running job is in the fixed monitor location JOBDA (address 520).
The
following statement puts the project-programmer word into the variable
A.% :
A% = PEEK(PEEK(PEEK(520%)+8%)+24%)
The following statements put the project number in B% and the
programmer number in C%:
B%
C%

= SWAP%(A%) AND 255%
= A% AND 255%

7-319

Chapter 8
System Calls for Local Interjob Communication

Local Interjob Communication
Local communication between jobs running on a single RSTS/E system is
a function of the send/receive facilities available in the RSTS/E
monitor.
Local senders can send messages (with the Send Local Data
Message call) to local receivers.
The receiver controls the
communication by limiting the number of messages that can be queued
and by declaring which senders are allowed to queue messages. The
receiver passes this control information to the monitor by means of a
receiver declaration (with the Declare Receiver call).
The system queues messages until the maximum number of messages
specified by the receiver is pending for that particular receiver.
After that, if a local job tries to send another message to that
receiver, the system returns an error to the sender.
In general,
receivers must process pending messages frequently to avoid tying up
system resources for long periods of time. When message processing is
complete, a job must issue a remove receiver system call so that
unwanted messages are not queued.
DECnet/E network communication uses extensions to the SYS calls
presented in this chapter. DECnet/E is an optional software package
that extends RSTS/E to include network capabilities. You can access
the extended send/receive facilities provided by DECnet/E from
Bj~SIC-PLUS, BASIC-PLUS-2, COBOL, FORTRAN, or MACRO, and through RMS.
See the DECnet/E and RMS documentation for" more information.
If the system manager includes DECnet/E during system installation, a
local job can use the network calls to communicate with other local
jobs.
In this case, the job functions as a network job. The use of
network services to communicate with local jobs imposes DECnet/E
restrictions and additional overhead. Use of the network calls,
however, does allow programs to be coded and debugged locally before
they are run on some other system in the network.
It also provides
additional capabilities not provided by the local send/receive
functions.

8-1

System Calls for Local Interjob Communication
Some parameters or combinations of parameters in the send/receive
calls have meanings that pertain to special applications, such as an
EMT logger, which is a special program that monitors certain types of
system activity. These parameters are mentioned briefly in this
chapter. See Appendix G for more information on EMT logger calls.
Every message is divided into a parameter area and a data area,
whether it is for local or for network communications. For a local
message, the parameter area can contain from 0 to 20 bytes of
user-defined data; the data portion can contain up to 512 bytes.
B~cause the parameter area in a local message can contain data defined
by the sender, the distinction between parametet and data is arbitrary
for local messages. However, the distinction is important for a
network message, in which DECnet/E uses the parameter area for
DECnet/E information.

Format of the Send/Receive SYS Calls
The general format of the SYS calls described in this chapter is:
V$=SYS(CHR$(6%)+CHR$(22%)+CHR$(S%)+ ... +0$)
where:
V$

is the target string returned by the call.

is an assignment operator (the LET verb is implied).

SYS(

indicates a system call.

CHR$(6%)

is the system function code for a call to the file
processor (that is, the FIP call).

is the concatenation operator required between
function, subfunction, and argument codes.

CHR$(22%)

is the send/receive function code.

CHR$(S%)

is the user-specified subfunction code. (For example,
S%=l% indicates a declare receiver and S%=O% indicates
a remove receiver system call).
indicates other arguments that must be specified for
the system calls. Byte arguments have the form
CHR$(X%) where CHR$ is a function that converts data
to character format, and X% is the user-specified
argument defined by the specific system call. Word
arguments have the form CVT%$(SWAP%(X%».

is optional user-defined data.
8-2

System Calls for Local Interjob Communication
The system call descriptions use the following terms:
Term

Meaning

Reserved; should be zero.

This field is reserved for future use.
You must specify zero for each byte in
the field.
Trailing zeros need not be
passed.

Not meaningful; should
be ignored.

The bytes in this field do not contain
useful information.
However, these
bytes may have meaning in future
releases.
This term appears in the data
returned by the various SYS calls.
Note

Unlike the SYS calls to FIP (see Chapter 7), the
arguments passed to and returned from this
Send/Receive call are longer than 30 bytes.
You
should dimension the arrays used in CHANGE statements
to handle 40-byte strings (see the sections, "Building
a Parameter String" and "Unpacking the Returned Data,"
in Chapter 7).

Privileges Required for Send/Receive
SEND

Send to a restricted receiver

SYSIO

Declare a receiver with a nonzero Local Object Type, global
name, or nonzero inbound links limit

JOBCTL

Remove the RIB of another account

8-3

System Calls for Local Interjob Communication
FO=22
(.MESAG)

Declare Receiver
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(22%), the send/receive function code.

CHR$(1%), the declare receiver subfunction code.

CHR$(O%), reserved; should be O.

5-10

The receiver name.
The receiver name must be a one- to six-character ASCII
string.
It must be left-justified and padded to six
characters with spaces.
The receiver name must contain only
printing ASCII characters (characters with ASCII decimal
values in the range 33 to 126) and cannot contain leading or
embedded spaces.
However, you can specify a blank receiver
name (six spaces).
If you do not have SYSIO privilege and you specify a
nonblank name, it must contain six characters and the last
two characters must be your job number, as two ASCII digits.

11-20

Reserved; should be O.

CHR$(O%), the object type code.
Legal values are 0 through 255.
Object type codes for
network send/receive are defined in DECnet/E Network
Programming in BASIC-PLUS and BASIC-PLUS-2.
See the
Discussion for more information on object type codes for
local receivers.

CHR$(L%+P%+N%+O%+S%), Access Control Field.
This byte controls the types of senders that are allowed to
queue messages for this job and also controls system
handling of queued messages.
It is the sum of the following
five bit values:
L%

Local/No Local Senders
8-4

System Calls for Local Interjob Communication
If L%=O%, messages from local senders are not queued.
Local senders who use network functions are considered
network senders in this context.
If L%=l%, messages from local senders are queued.
P%

Local Privileged/Local Nonprivileged
This bit is ignored if L%=O% (no local

sendel~

allowed).

If P%=O%, local senders without the SEND privilege can
queue messages.
If P%=2%, local senders must have the SEND privilege.
N%

Network Logical Links/No Logical Links
This bit controls the queuing of requests for DECnet/E
logical links.
The DECnet/E Network Programming in
BASIC-PLUS and BASIC-PLUS-2 manual describes network
links.
For local interjob communication, this bit
should be zero.
If the receiver does not have SYSIO privilege, this bit
must be zero.

Network Single Links/No Single Links
This bit controls the queuing of single network links.
For more information, see DECnet/E Network programming
in BASIC-PLUS and BASIC- PLUS-2.
For local interjob
communication, this bit should be zero.

Sleep/No Sleep
If 5%=0%, pending messages block execution of a
conditional SLEEP.
(In a conditional SLEEP, the monitor
checks for certain conditions before executing the SLEEP
statement. One of these conditions is pending messages
in the job's message queue.
See the section, "SLEEP and
Conditional SLEEP Statements," in Chapter 10, for more
information.)
If S%=16%, pending messages do not block execution of a
conditional SLEEP.

23-24

Reserved; should be O.

8-5

System Calls for Local Interjob Communication
25

CHR$(M%), the message maximum.
The message maximum can be any value between land 255.
However, if the job does not have EXQTA privilege, this
value cannot exceed the value in the account's second quota
block. See Discussion.

CHR$(L%), the inbound link maximum.
The incoming link maximum declares the maximum number of
incoming DECnet logical links a job will support at anyone
time. For local interjob communication, the incoming link
maximum should be O. If you have SYSIO privilege, the
incoming link maximum can have any value between 0 and 255.
If the receiver does ~ot have SYSIO privilege, this value
must be zero.

27-28

Reserved; should be 0 for all receivers except an EMT
logger. See Appendix G for more information.

CHR$(O%), the outbound link maximum.
DECnet uses this parameter as the number of outgoing links.
If you have EXQTA privilege, the outgoing link maximum can
have any value between 0 and 255. If you do not have EXQTA
privilege, this value must be 0 or 1.
(Note that in either
case, a value of 0 is interpreted as a default to the
maximum value.)

Reserved; should be 0 for all receivers except an EMT
logger. See Appendix G for more information.
CHR$(O%), reserved; should be O.

CHR$(R%), the receiver ID block (RIB) number. It must be a
value between 0 and 255; values 128 through 255 are reserved
for use by DIGITAL.
A job that does not have EXQTA privilege can use only the
number of RIBs specified in the account's second quota
block.

36-40

CHR$(O%), reserved; should be

Data Returned
No meaningful data is returned.

8-6

System Calls for Local Interjob Communication
Privileges Required
SYSIO

Declare a receiver with a nonzero Local Object Type, global
name, or nonzero inbound links limit

Possible Errors
Meaning
?ILLEGAL FILE NAME
One of the following occurred:

ERR Value
2

The receiver name passed in bytes 5-10 contains
nonprinting ASCII characters or leading or
embedded spaces.

A job that did not have SYSIO privilege passed a
nonblank receiver name that does not contain its
job number in bytes 9 and 10.

The specified local object type code is invalid.

?ACCOUNT OR DEVICE IN USE
The calling job already exists in the receiver's
list of declared receivers for the specified
receiver ID block (RIB) number.
This error may
indicate that the program contains a logic error or
that a previous program running under the same job
number failed to remove itself from the receiver
list before terminating~
In the last case, the
calling job should remove itself (with a Remove
call, see the section "Remove Receiver").
?PROTECTION VIOLATION
One of the following occurred:

The specified RIB number is out of range.

The caller does not have sufficient privilege at
the time certain functions were attempted in the
receiver declaration.
(For example, a caller
needs SYSIO privilege to declare
"single-instance" local object type.)

?NAME OR ACCOUNT NOW EXISTS
The receiver name passed in bytes 5-10 is already
being used as a receiver ID (this error cannot occur
if the name specified is blank), or a specified
"Single-instance" local object type is already in
use.

8-7

System Calls for Local Interjob Communication
?ILLEGAL SYS() USAGE
The receiver name, object type, and access
parameters passed are inconsistent.

?ILLEGAL BYTE COUNT FOR I/O
The value you specified in byte 30 is out of range
(refers to an EMT logger; see Appendix G for more
information).

?NO BUFFER SPACE AVAILABLE
When the job attempted to declare itself as a
receiving job, there were no small buffers available
for the declaration arguments.
Since the system's
use of small buffers is dynamic, a retry may
succeed.

?MISSING SPECIAL FEATURE
The call you attempted requires an optional feature
(such as EMT logging) that is not available on your
system.

Discussion
A program identifies itself to the monitor for message send/receive
operations with a Declare Receiver call. The monitor maintains a list.
of receiver ID blocks that hold the arguments passed in the receiver
declaration, the message queue, and other system maintained
information. A job can send local messages without performing a
receiver declaration. However, to be eligible to receive messages, a
job must have at least one receiver ID block.
Using Multiple Receiver ID Blocks
A single job can declare itself as more than one receiver by executing
multiple Declare Receiver calls. Each job has available for its use
256 receiver ID blocks (RIBs), numbered 0 through 255. RIB numbers 0
through 127. are for customer use; RIB numbers 128 through 255 are
reserved for use by DIGITAL. You specify the RIB number in byte 35;
if you do not want to use multiple RIBs, set this byte to zero.
The number of RIBs assigned to jobs that do not have EXQTA privilege
are counted and checked against a quota.
The quota is stored in the
account's second quota block.
For each successful declare, the system sets up a separate 32 byte
RIB.
Each RIB has a separate message q~eue and can have different
characteristics (for example, message maximum and type of senders
allowed).
You specify these characteristics in the call. The system
allocates space for each RIB from the small buffer pool.
n

8-8

System Calls for Local Interjob Communication
Multiple RIBs can be useful in a program that performs several
functions.
For example, in certain applications, you might want to
use one RIB for high priority messages or messages from specially
privileged senders, and another for lower priority messages or
messages from any sender.
If the program consists of several
subroutines or modules, each one can process messages independently
using different RIBs.
Receiver Names
You must associate each RIB that you declare with a receiver name.
Place the receiver name in bytes 5 through 10 of the data passed.
While your program needs to keep track of both the RIB number and the
receiver name, other jobs can send messages to you by using either the
receiver name or the job number.
A receiver name must be either unique or blank (six spaces).
Receivers that receive messages by job number rather than by name use
blank receiver names.
If you do not have SYSIO privilege, you can use
blank names. Any nonblank names you use must have six characters, and
the last two characters must be the job number.
Privileged programs
may use other names.
However, when multiple copies of a program are
active at the same time, DIGITAL recommends that privileged programs
also use the job number as the last two characters of the receiver
name to avoid name conflicts.
Note
To avoid future name conflicts, do not use the $
character in your own receiver names.

8-9

System Calls for Local Interjob Communication
Table 8-1 lists the names currently used by DIGITAL software.
Table 8·1:

RSTS/E Reserved Names

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

I Local Object I
Reserved Name I

I
Use
I
+- - - - - - - - - - - - - - - -+- - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

ERRLOG

Type
1

Error logger

BAnSPL

OPSER batch processor

LPnSPL

OPSER print spooler

OPSER

OPSER message manager

QUEMAN

OPSER queue manager

QM$CMD

PBS spooling package

QM$SRV

PBS spooling package

QM$URP

PBS spooling package

PR$nnx

PBS spooling package

BA$nnx

PBS spooling package

SHUTUP

System shutdown program

EVTLOG

DECnet/E

EVTLSN

DECnet/E

FALnnn

DECnet/E

NCPnnn

DECnet/E

NMLnnn

DECnet/E

NWPKnn

DECnet/E

NWTTnn

DECnet/E

+- - - - - - - - - - - - - - - -+- - - - - - - - - - - _. -+- - - - - - - _. - - - - - - - - - - - - - - - - - - - - - - - - - --+

To see which receiver names are reserved on your system, use the SHOW
RECEIVERS command.

8-10

System Calls for Local Interjob Communication
For example:
$SHOW RECEIVERS
Message Receivers:
Rcvrid
Job
Rib
ERRLOG
1
0
2
0
OPSER

Obj
1

Msgs/Max
0/40
0/30

Links/InMax/OutMax
0/0/0
0/0/255

Access
Prv
Lcl

Local Object Types
A receiver ID block can be associated with an object type (specified
in byte 21).
Object type codes for network send/receive are defined
in the DECnet/E documentation.
If you have SYSIO privilege, you can specify a local object type for
receivers that do not perform network operations.
The code you
specify indicates that a receiver performs a specific function.
For
example, the error logger, which records error information for the
monitor, is assigned local object type 1.
If your system uses an EMT
logger, it is assigned local object type 2.
You can also specify
local object type 64, which allows error messages to be sent to your
program if you open a disk non-file-structured with MODE 512% (see the
section, "Access to Bad Block Information" in Chapter 1).
Local object types 7 through 63 are "single-instance" local objects
used by DIGITAL-supplied programs.
The system makes sure that no more
than one receiver of each single-instance type is declared, allowing
the system to rapidly locate a given receiver for certain functions.
Access Control Field
Byte 22 controls the types of network access permitted and the types
of local senders permitted.
The possible values are 0-31.
However,
for local interjob communication, only the following values are
allowed:
1

Any local sender

Only senders that have SEND privilege

Any local sender; sleep with pending messages

Only local senders that have SEND privilege; sleep with pending
messages

8-11

System Calls for Local Interjob Communication
The "sleep bit" (value 16%) in the access control field is mainly for
use with multiple RIBs. When this bit is set, pending messages do not
block execution of a conditional SLEEP (see the section "SLEEP ~nd
Conditional SLEEP Statements" in Chapter 10). By setting this bit,
you can process messages on a specific RIB only when your program is
executing certain code and, at the same time, prevent pending messages
on that RIB from affecting conditional SLEEP statemeQts in the rest of
your program.
Buffer Space for Messages
Each pending message in the system occupies system b~ffer space.
Except for EMT logger messages~ one 16-word buffer from the monitor's
buffer pool is used for each message to hold the user- or
DECnet-defined parameters and other system-specific information.
Additional buffer space is needed for the data portion of the message.
The monitor allocates buffer space for messages from the extended
buffer pool (XBUF).
Queued Message Limit
The system maintains a count of messages queued for each receiver.
The message maximum (byte 25) limits the number of messages queued for
this receiver.
This limit applies both to messages from local senders
and network data messages.
Local messages and network data messages
are not queued unless the current count is less than the declared
maximum. An error is returned to a local sender who attempts to send
a message to a receiver whose count has reached this maximum.
The declared value for the message limit is constrained by the
account's message quota, which is stored in the account's record quota
block.
The sum of the message limits for all the receivers a job has
declared cannot exceed the message quota.
For example, if you have a
message quota of 12 (the default), you can declare one receiver with a
message limit of up to 12, or one with a limit of 3 and another with a
limit of up to 9.
If the job has EXQTA privilege in effect, the
system ignores the message quota.

8-12

System Calls for Local Interjob Communication
FO=22
(.MESAG)

Send Local Data Message
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(22%), the send/receive function code.

CHR$(-l%), the send local data message subfunction code.

CHR$(J%).
If J%=O, the call uses the logical name in bytes
5 through 10 to determine the receiver.
If J%=128+LOT, the
call uses the local object type (LOT) specified in byte 21.
Only single-instance object types are valid.
See the
Discussion for valid LOTs.
Otherwise, J% can be set to the
job number times 2 of the local receiving job.
For example,
specifying J%=8% directs a message to job 4.

5-10

N$, the receiver name.
The receiver name is a one- to six-character ASCII string.
It is left-justified and padded to six characters with
spaces.
If byte 4 is nonzero and you specify a receiver
name, the send will succeed only if the name in bytes 5-10
is associated with the job number in byte 4.

CHR$(C%), the channel number for the I/O buffer that
contains the data portion of the message.
If this byte is zero, a string beginning at byte 41 contains
the data portion of this message (if any).
If this byte contains a channel number (any value from
1-12), a buffer defined by the length and offset values
contains the data portion of this message.
The message data
(up to 512 bytes) should be left-justified in the buffer for
channel C%, beginning at the offset value defined in bytes
15-16.

8-13

System Calls for Local Interjob Communication
Channel 0 can be used for the I/O buffer if 128 is added to
the channel number, that is, CHR$(128%+0%).
In general,
CHR$(128%+C%) allows channels 0 through 12 to be used for
I/O buffers.
12

CHR$(O%), reserved; should be O.

13-14

L%, the length (in bytes) of the message to send from the
channel buffe r in the form CVT%$ (SW.AP% (L%) ) .
If byte 11 is zero, the system ignores these bytes.
For local data messages, this length field can have any
value between zero and 512, subject to the restriction that
the length of the message is less than or equal to the
buffer size minus the offset value.
If the length is zero,
the system sends the whole buffer (that is, from the offset
to the end of the buffer).

15-16

0%, the offset value in the form CVT%$(SWAP%(O%)).
The value specifies the offset from the beginning of the
where the message data begins.
The offset must be in
the 'range zero to <size of buffer - 1>.

buf~er

17-20

CHR$(O%), reserved; should be O.

21-40

p$, the optional user parameter string.
A maximum of 20 bytes of user-defined data can be passed as
parameters to the receiver of this message.

41+

D$, the optional data string.
A maximum of 512 bytes of user~defined data can be passed to
the receiver's buffer.
The call ignores these bytes if byte
11 is nonzero.

Data Returned
Bytes
4

Meaning
The job number times 2 of the receiving job.

8-14

System Calls for Local Interjob Communication
Privileges Required
SEND

Send to a restricted receiver

Possible Errors
Meaning

ERR Value

?NO ROOM FOR USER ON DEVICE
For local message operations, this error means that
the number of messages pending for this receiver is
at its declared maximum.
The sender should try
again later.
If this error occurs frequently, the
receiver is not processing its messages quickly
enough, or the number of pending messages allowed by
the rec!eiver is too small.
This error can also
occur if the message receiver is hibernating.
Because the hibernating receiver cannot process
messages, the system sets a flag for messages sent
to it and thus minimizes the number of small buffers
that would be tied up.

?CAN'T FIND FILE OR ACCOUNT
For local messages, the receiving job, referenced by
job number or logical name, was not found in the
list of declared receivers.
The receiving job must
be declared (with the Declare Receiver SYS call)
before any data can be transmitted.

11/0 CHANNEL NOT OPEN
The channel specified in byte 11 of the data passed
is not open.
The job must open the channel and try
again.

?PROTECTION VIOLATION
An access violation has occurred.
Either the sender
is nonprivileged and the receiver requires senders
to have SEND privilege, or the receiver does not
allow any local senders.

?ILLEGAL SYS() USAGE
The job number passed in byte 4 is odd.
Byte 4 must
be zero Of the receiver's job number times 2.

8-15

System Calls for Local Interjob Communication
?ILLEGAL BYTE COUNT FOR I/O
The offset and/or length fields passed in bytes
13-16 are illegal.
The following relationships must
be true for a send call:

The offset must be less than the buffer size.

The length must be less than or equal to the
buffer size minus the offset value.
The buffer
size minus the offset value must be less than or
equal to the maximum message length.

The offset and length fields are checked for
validity whenever a channel number is passed in byte
11.
?NO BUFFER SPACE AVAILABLE
System buffers are not currently available to store
this message. A later retry may proceed without
error.

Discussion
A local job can send a message to a declared receiver by specifying:

A job number

A logical name

A logical name, while checking the job number

A single-instance local object type

(if appropriate)s

If byte 4 of the data passed is nonzero and even, and the name field
(bytes 5-10) is null, the call interprets it as the job number (times
2) of the intended receiver.
If bytes 5-10 are not null, the call attempts to send the message to
the receiver whose logical name matches bytes 5-10 of the data passed.
If byte 4 is zero, the message is sent to the named receiver.
If byte
4 is nonzero and even, the message is sent to the named receiver only
if that receiver is owned by the job whose job number times two is
specified in byte 4. Because it does not require a receiver table
search, sending messages by job number or local object type is
slightly more efficient than sending by logical name.

8-16

System Calls for Local Interjob Communication
If byte 4 is 128 + LOT (local object type), the call sends the message
to the receiver designated by the local object type value you specify
in LOT. Legal values are:
LOT

Receiver

Error logger

EMT logger

PBS spooling package

PBS spooling package user request packet

OPSER-based spooling package

A send by job number works only when the receiving job is receiving

messages on RIB O.
(That is, the receiving job must have executed a
declare receiver call with a value of zero in byte 35.) All messages
sent by job number are queued on RIB O. If the job is a receiver on
one or :more nonzero RIBs but not RIB 0, the send by job number fails.
In contrast, a send by logical name (with or without job number check)
works for any RIB number.
In a receiver declaration, the receiving job specifies the types of
senders who are allowed to send messages. If no local senders are
allowed, all attempts to send messages to the receiver fail.
Similarly, if local senders must have SEND privilege, an attempt by an
insufficiently privileged job to send a message to this receiver also
fails. All such access violations terminate with the error
?Protection violation (ERR=lO), and the message is not sent.

8-17

System Calls for Local Interjob Communication
FO=22
(.MESAG)

Send Local Data Message With Privilege Mask
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(22%), the send/receive function code.

CHR$(-ll%), the send with privilege mask subfunction code.

CHR$(J%).
If J%=O, the call uses the logical name in bytes
5 through 10 to determine the receiver.
If J%=128+LOT, the
call uses the local object type (LOT) specified in byte 21.
Only single-instance object types are valid. Otherwise J%
can be set to the job number times 2 of the local receiving
job. For example, specifying J%=8% directs a message to job
4.

5-10

N$, the receiver name.
The receiver name is a one- to six-character ASCII string.
It is left-justified and padded to six characters with
spaces.
If byte 4 is nonzero, the send will succeed only if
the receiver name is associated with the specified job
number. See Discussion.

CHR$(C%), the channel number for the I/O buffer that
contains the data portion of the message.
If this byte is zero, a string beginning at byte 41 contains
the data portion of this message (if any).
If this byte contains a channel number (any value from 1 to
12), a buffer defined by the length and offset values
contains the data portion of this message. The message data
(up to 512 bytes) should be left-justified in the buffer for
channel C%, beginning at the offset value defined in bytes
15-16.
Channel 0 can be used for the I/O buffer if 128 is added to
the channel number, that is, CHR$(128%+0%).
In general,
CHR$(128%+C%) allows channels 0 through 12 to be used for
I/O buffers.

8-18

System Calls for Local Interjob Communication
12

CHR$(O%), reserved; should be O.

13-14

L%, the length (in bytes) of the message to send from the
channel buffer in the form CVT%$(SWAP%(L%».
If byte 11 is zero, the system ignores these bytes.
For local data messages, this length field can have any
value between zero and 512, subject to the restriction that
the length of the message is less than or equal to the
buffer size minus the offset value.
If the length is zero,
the system sends the whole buffer (that is, from the offset
to the end of the buffer).

15-16

0%, the offset value in the form CVT%$(SWAP%(O%».
The value specifies the offset from the beginning of the
buffer where the message data begins. The offset must be in
the range zero to <size of buffer - 1>.

17-28

CHR$(O%), reserved; should be O.

29-40

p$, the optional user parameter string.
You can pass a maximum of 12 bytes of user-defined data as
parameters to the receiver of this message.

41+

D$, the optional data string.
You can pass a maximum of 512 bytes of user-defined data to
the receiver's buffer. The call ignores these bytes if byte
11 is nonzero.

Data Returned

Bytes
4

Meaning
The job number times 2 of the receiving job.

Privileges Required

SEND

Send to a restricted receiver

Possible Errors

This call returns the same errors as the Send Local Data Message call.
See the previous section.

8-19

System Calls for Local Interjob Communication
Discussion
This call sends a data message plus a privilege mask supplied by the
monitor.
This subfunction provides a method for a program to tell
another program about a job's current privileges and guarantees that
the data cannot be falsified.
A local job can send its privileges to a declared receiver in the same
way as the Send Local Data Message call.
See the Discussion in the
previous section.

8-20

System Calls for Local Interjob Communication

FO=22
(.MESAG)

Receive
Data Passed
M~aning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(22%), the send/receive function code.

CHR$(2%), the receive subfunction code.

CHR$(S%+T%+L%+N%), the modifier for this receive.
The modifier is the sum of the following four values:
S%

Sleep/No Sleep
If S%=O% and no messages are pending for this job, the
receive call returns an immediate error (ERR=5).
If S%=l%, the job sleeps until a message is queued.
The
duration of the sleep can be limited by bytes 27-28.
See Discussion.

Truncate/No Truncate
If T%=O%, an attempt to receive a message that is too
long for the buffer (indicated by bytes 11-16 of the
data passed) results in a partial message being
transferred to the caller.
The remainder of the message
is saved and can be retrieved by subsequent receive
calls.
If T%=2%, a message that is too long for the buffer
(specified by bytes 11-16 of the data passed) is
truncated.
In either case, the number of bytes from the data
portion of the message that was delivered to the buffer
is returned in bytes 13-14 of the data returned.
The
number of bytes remaining (T%=O%) or discarded (T%=2%)
is noted in bytes 9-10 of the Data Returned.

8-21

System Calls for Local Interjob Communication
L%

Local Selection
If L%=O%, local selection is disabled.
If N% (described
as follows) is also disabled, the first message on the
receiver's queue of pending messages is delivered to the
caller.
If L%=4%, local selection is enabled.
Only local
messages are delivered on this receive.
The selection
can be further qualified to a particular local sender by
bytes 5 and 6.

Network Selection
If N%=O%, network selection is disabled.
If L% is also
disabled, the first message on the receiver's queue of
pending messages is delivered to the caller.
If N%=8%, network selection is enabled.
Only network
messages are delivered on this receive.
The selection
can be further qualified to a particular DECnet logical
link by specifying a DECnet user link address in byte 5.
Note
If L%=4% and N%=8%, the local bit setting
prevails; the network selective receive is
ignored.

CHR$(S%), the sender selection.
This byte is ignored if both L%=O% and N%=O% in byte 4.
Any nonzero value in this byte selects a particular sending
job.
Zero is a special case described for byte 6.
See the
Discussion for meaningful combinations of bytes 5 and 6.
For local selection (L%=4% as described previously), if this
byte is equal to a job number times 2, the first message on
the queue from that particular job is delivered to the
caller.
For network selection (N%=8% and L%=O%), if this byte is
equal to a user link address, the first message on the queue
from that particular DECnet logical link is delivered to the
caller.
See the DECnet/E Network Programming in BASIC-PLUS
and BASIC-PLUS-2 Manual for details.

CHR$(Q%), the sender selection qualifier.
This byte is ignored if both L%=O% and N%=O% in byte 4.

8-22

System Calls for Local Interjob Communication
This byte is also ignored if byte 5 is nonzero.
See the
Discussion for meaningful combinations of bytes 5 and 6.
For local selection, if byte 5 is zero and byte 6 is
nonzero, this receive is requesting a message from the
"system" (represented by job 0, which is not a real job
number).
This special case is intended for use by ERRCPY or
an EMT logger, which receives messages from the monitor's
error logging or EMT logging routines.
The job number in
these messages is zero.
See Appendix G for more information
on EMT logging.
If both byte 5 and byte 6 are zero, the selection bits (L%
and N% as described above) select only the generic type of
message to be delivered to the caller.
For local selection
(L%=4%), the first local message on the queue is delivered
to the caller.
For network selection (N%=8% and L%=O%), the
first network message on the queue is delivered to the
caller.
7-10

Reserved; should be O.

CHR$(C%), the channel number for the I/O buffer to receive
messages.
If C% is between 1 and 12, the system returns the data
portion of the message in the buffer for channel C%.
The
channel must be open.
If C%=O or the buffer for channel C%
is not large enough to accommodate the data portion of the
message, the action taken depends on the value of the
truncation bit in the receive modifier.
See Discussion.
Channel 0 can be used for the I/O buffer if 128 is added to
the channel number, that is, CHR$(128%+0%).
In general,
CHR$(128%+C%) allows channels 0 through 12 to be used for
I/O buffers.

CHR$(O%) reserved; should be O.

13-14

L%, the maximum message length (in bytes) desired on this
receive in the form CVT%$(SWAP%(L%)).
If byte 11 is zero (that is, no channel is specified), the
offset and length fields are ignored.
The length field limits the number of data bytes that are
returned on this receive.
If the length is zero, the error
?No room for user on device (ERR=4) occurs. Otherwise, a
maximum of L% bytes is returned on this receive.
The
specified length must be less than or equal to the buffer
size minus the specified offset.

8-23

System Calls for Local Interjob Communication
15-16

0%, the offset from the start of the buffer in the form
CVT%$(SWAP%(O%».
The offset field determines where in the buffer the data
portion of the message is returned. The offset value is
added to the location of the beginning of the buffer. The
offset value must be in the range 0 to (size of buffer - 1).

17-20

CHR$(O%) reserved; should be O.

21-26

Reserved; should be O.

27-28

T%, the sleep time in seconds in the form
CVT%$(SWAP%(T%».
If byte 4 requests a sleep and no messages are pending, the
sleep is terminated after T seconds. If T%=O%, the length
of the sleep is indefinite; the job is not awakened until
one of six events awakens the job. When the sleep
terminates, the error ?Can't find file or account (ERR=5)
occurs. See Discussion.

29-34

CHR$(O%) reserved; should be O.

CHR$(R%), the RIB number for this receive. The RIB number
must be a value from 0 to 255; values 128 through 255 are
reserved for use by DIGITAL.

36-40

CHR$(O%) reserved; should be O.

Data Returned for Local Data Message
Bytes

Meaning

1-2

Not meaningful; should be ignored.

CHR$(-l%), the local data message subfunction code.

CHR$(J%), the job number of the local sender.
For local messages, this byte contains the job number times
2 of the local sender.

5-6+

PPN of the sender.

Keyboard number of the sender or 255% if the sender is
detached.

Not meaningful; should be ignored.

8-24

System Calls for Local Interjob Communication
9-10

R%, the number of bytes remaining in the data portion of the
message.
This is a count of bytes not delivered to the caller on this
receive.
If truncation was not requested (T%=O% in byte 4
of the data passed) and not all of the message was
delivered, the message remains queued.
The rest of the data
can be retrieved on subsequent receive calls.
If truncation
was requested (T%=2% in byte 4 of the data passed), the
message is removed from the queue and this count is the
number of bytes discarded.

11-12

Not meaningful; should be ignored.

13-14

L £::o , the length of the message transferred to the buffer.
This count is the number of bytes actually transferred to
the channel buffer on this receive call.
If no channel
number was specified (byte 11 = 0% in the data passed), this
count is zero.
In this case, the size of the data portion
of the message is available in bytes 9-10 of the data
returned.
Note that if the number of bytes transferred (bytes 13-14 of
the data returned) and the number of bytes remaining (bytes
9-10 of the data returned) are both zero, the entire message
consists of parameters that are available in bytes 21-40 of
the data returned.

15-20

Not meaningful; should be ignored.

21-40

p$, the user parameter string.
These bytes contain the data passed as parameters by the
sender of this message.
The system pads any unused bytes
with zeros to a length of 20 bytes.

Data Returned for Local Data Message with Privilege Mask
Bytes
1-2

Meaning
Not meaningful; should be ignored.

CHR$(-ll%), the local data message with privilege mask
subfunction code.

CHR$(J%), the job number of the local sender.
For local messages, this byte contains the job number (times
2) of the local sender.

8-25

System Calls for Local Interjob Communication
5-6+

PPN of the sender.

Keyboard number of the sender or 255% if the sender is
detached.

Not meaningful; should be ignored.

9-10

11-12

Not meaningful; should be ignored.

13-14

L%, the length of the message transferred to the buffer.
This count is the number of bytes actually transferred to
the channel buffer on this receive call.
If no channel
number was specified (byte 11 = 0% in the data passed), this
count is zero.
In this case, the size of the data portion
of the message is available in bytes 9-10 of the data
returned.
Note that if the number of bytes transferred (bytes 13-14 of
the data returned) and the number of bytes remaining (bytes
9-10 of the data returned) are both zero, the entire message
consists of parameters that are available in bytes 21-40 of
the data returned.

15-20

Not meaningful; should be ignored.

21-28

The sender's privilege mask.

29-40

p$, the user parameter string.
These bytes contain the data passed as parameters by the
sender of this message.
The system pads any unused bytes
with zeros to a length of 12 bytes.

8-26

System Calls for Local Interjob Communication
Privileges Required
None.
Possible Errors
Meaning

ERR Value

?CAN'T FIND FILE OR ACCOUNT
If a receive without sleep was issued, this error
indicates that no messages are pending.
If a
receive with sleep was issued, this error indicates
that no messages were pending when the receive call
was issued or that the sleep timer has expired.
The
error is returned when the job is awakened from the
sleep.
The program must execute the receive again
to retrieve any pending messages (see the
Discussion).

?I/O CHANNEL NOT OPEN
An attempt was made to receive a message, but
channel C%, specified in byte 11 of the data passed,
is not open.
The program must open the channel and
try again.

?ILLEGAL SYS() USAGE
The job is not a declared receiver on the specified
RIB number.
Before any receive can succeed on that
RIB number, the job must be entered in the receiver
list.

?ILLEGAL BYTE COUNT FOR I/O
The offset and length fields passed in bytes 13-16
are illegal.
The following relationships must be
true for a receive call:

The offset must be less than the buffer size.

The length must be less than or equal to the
buffer size minus the offset value.

The offset and length fields are checked for
validity whenever a channel number is passed in byte
11.

8-27

System Calls for Local Interjob Communication
Discussion
On any receive call, the system checks the eligibility of the job to
receive messages and returns the error ?Illegal SYS() usage (ERR=18)
if the specified job and RIB number are not in the list of declared
receivers.
If the job is eligible to receive messages, the call
attempts to receive a message based on the receive modifier passed in
byte 4.
Normally, a receive call returns the first message on the
receiver's queue of pending messages.
Use the selective receive bits
(L% and N% in byte 4) to select messages from particular senders
identified by the local job number or DECnet user link address (as
indicated by byte 5).
If the sleep bit is off (S%=O% in byte 4) and
no messages are pending, the system generates the error ?Can't find
file or account (ERR=5) and immediately passes the error to the
calling program.
If no messages are pending and the sleep bit is on
(S%=l% in byte 4), the job is put into a sleep state (called a
receiver sleep).
You can specify the sleep time in bytes 27-28 of the
data passed.
A job in a receiver sleep can be awakened by any of six events:
o

A user types a delimiter (RETURN, LINE FEED, FORM FEED, or
ESCAPE) at:
Any terminal opened by the job.
Any terminal allocated to the job if the job also has a
keyboard open on a nonzero channel.

A dial-up line that is allocated or opened by the job gets
hung up.

The system manager disables logins (that is, sets the number
of logins to 1).

A state change occurs on a pseudo keyboard opened by the job~
This condition can occur when the opened pseudo keyboard has
output for the controlling job or has entered an input wait
state.
See the section "Pseudo Keyboards" in Chapter 4.

The job has declared itself a receiver and a message is
queued for it through the Send/Receive SYS calls.
See
Chapter 8.

The job has a DMC/DMR (XM:) device open and the device driver
receives a message (see Chapter 6).

In all cases, the job is awakened with an error ?Can't find file or
account (ERR=5) but is not passed a message.
To obtain a pending
message, the job must execute the receive call again.
Because the job
may have been awakened by terminal input or expiration of the timer,
8-28

System Calls for Local Interjob Communication
you can check for pending messages by executing the receive call
, without a sleep or by executing a terminal input operation using
RECORD 8192% for immediate return.
The receive ciall returns parameters in the target string and the data
portion of the message (if any) in the I/O buffer s~ecified by byte
11. If the program must handle any DECnet/E messages, or local
messages longer than the 20 bytes of user-defined parameters, a
channel buffer must be available to receive the data portion of the
message.
You can determine the number of bytes from the data portion of a
message actually delivered to the buffer (if any) and the number of
bytes remaining in the message (if any) from the data returned with
the receive call. Bytes 13-14 indicate the number of bytes from the
data portion of the message that were delivered to the buffer.
The truncation bit (T%) in byte 4 determines whether the remaining
bytes in the channel buffer are kept or discarded. If you set T%=O%,
the remaining bytes are kept. If T%=2%, the remaining bytes are
discarded. Bytes 9~10 indicate the nu~ber of bytes that remain to be
transferred or were discarded (depending on the truncation bit in byte
4)•

When pr()cessing large messages in small pieces, each successive
receive call retrieves a limited number of bytes from the same
message. The normal sequence is to issue receive calls until the
number ()f bytes remaining in the data portion of the message is zero
(as indicated by bytes 9-10 of the data returned). The receiver then
knows that the entire message has been delivered and removed from the
queue.
A convenient way to assign a buffer for message operations is to open

the null device (NL:) at the desired buffer size with the RECORDSIZE
option in the OPEN statement. The null device is always available and
can be opened as many times as required to obtain buffer space for any
desired function. If you specify a buffer, the system ensures that
the channel is open. If the channel is not open, the call results in
an immediate error 11/0 channel not open (ERR=9).
The program receiving a message selects the particular sender by
combining receive modifier bits (L% and N% in byte 4) and the values
of bytes 5 and 6.
Table 8-2 summarizes the possible combinations.

8-29

System Calls for Local Interjob Communication
Table 8·2:

Sender Selection Summary

+ - - - - - - - - - - - - - - - - - - - - - - - - - - • - - • - - -+ - - .. - - - - - - - .. - - - - • - - - - - - - - - - - - - - - - .. - +
Data Passed
I
I
+ - - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - -+
I
I
Receive
I
I
I
I
Modifier
I
I
Result
I
+----- ..
I
I
I
Byte 4
I Byte 5
Byte 6 I
I
I

-------+

I
N%
L%
I
I
I
+- - - - - - - - _ .... - - +- - - - - - - - - - - - - - - - - _.+ - - - - - - - - - - '. - - - - - - - - - - - - - - - - - - - - - --+
0%

Bytes 5 and 6 ignored; returns
first queued message.

0%
4%

Selects first local message.

nonzero

Selects job 0; used by error
logging and EMT logging programs
to select messages from monitor
routines.

nonzero
8%

nonzero

Selects local message by job
number times 2 in byte 5.
0%

Selects first network message.

I Selects network message by link

I (user link address) in byte 5.
+ - - - - - - - - - - - - - +. - - - - - - - - - - - - - - - - - -+ - - - _. - - - - - - - ~ - - - - - - - - - - - - - - - - - - - - - - ....

8-30

System Calls for Local Interjob Communication

FO=22)
(.MESAG)

Remove Receiver
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(22%), the send/receive function code.

CHR$(O%), the remove subfunction code.

CHR$(J%), the job number times 2 of the job to remove, or
CHR$(O%) to remove the calling job.
If J%=O%, the calling job need not be privileged.
If J% is
not 0 and not the caller, the caller must have JOBCTL
privilege. Add 128% to this byte for "conditional" remove.
See Discussion.

5-34

CHR$(O%) reserved; should be O.

CHR$(R%), the receiver ID block (RIB) number to remove.
The
RIB number must be a value from 0 to 255; values 128 through
255 are reserved for use by DIGITAL.

CHR$(O%) to remove the RIB specified in byte 35. A nonzero
value in this byte removes all RIBs for the job specified in
byte 4.

37-40

CHR$(O%) reserved; should be O.

Data Returned
No meaningful data is returned.
privileges Required
JOBCTL

Remove the RIB of another account

8-31

System Calls for Local Interjob Communication
Possible Errors
Meaning

ERR Value

?ACCOUNT OR DEVICE IN USE
This occurs for a conditional remove if there still
are messages pending.
See Discussion.

?PROTECTION VIOLATION
The caller does not have JOBCTL privilege and has
attempted to remove another job (that is, byte 4 is
nonzero and does not match the caller's job number).

?ILLEGAL SYS() USAGE
The job number passed in byte 4 is odd.
The job
number must be zero to remove the caller or job
number times two to remove receivers for another
job.

Discussion
This call removes a receiver from the system's list of declared
receivers.
You can remove all RIBs for a job or a specific RIB for a
job.
(Be careful when removing all RIBs for a job.) When this call is
executed, all pending messages for the receiver are discarded. You
should execute this call when message processing is being terminated
but the job is to continue running.
This prevents unwanted messages
from accumulating in the queue of pending messages.
Note that both the LOGOUT SYS function and the KILL SYS function
execute this call with a nonzero value in byte 36.
The "conditional" remove operation is useful for programs that want to
process messages until none remain, then remove the receiver.
If you
do a receive, find that there are no more messages, and then do a
remove, a message could arrive in the time between the receive and the
remove; the remove operation would discard that message.
To avoid
this problem, add 128% to byte 4 for "conditional" remove; in this
case, the system returns the error ?Account or device in use (ERR=3)
rather than discard messages if some messages are still waiting to be
received.

8-32

System Calls for Local Interjob Communication
Lc)cal Send/Receive E:xamples
This section gives several examples of the send/receive SYS calls.
The examples include a receiver declaration, two send local data
calls, five rece~ves to show some of the possible options, and a
r~~move receiver call.
The series of examples is a program that can be
run to demonstrate the operation of the send/receive functions.
The
examples are coded for illustration rather than efficiency. They do
not handle all possible error conditions and do not present all
possible options. The examples should, however, give the general
flavor of the services offered.

Declare Receiver Example
The following receiver declaration establishes the caller as a message
receiver with the logical name "DEMO". Only local senders that have
SEND privilege are allowed to send messages to this receiver. Up to
five messages are queued for this receiver before senders receive an
error (also ERR=4).
Finally, no requests for incoming DECnet logical
links are honored for this receiver.
10
900
1000

EXTEND
DIM X%(40%)
! RECEIVER DECLARATION EXAMPLE

1110
1120
1130

LOGNAME$
OBJTYPE%
ACCESS%

= "DEMO
= 0%
= 1%+2%

1150
1160
1190
1200

MMAX%
LMAX%

= 5%
= 0%

THIS RECEIVER'S LOGICAL NAME
ALL ACCESS BY LOGICAL ·NAME
ONLY LOCAL SENDERS WITH SEND
PRIVILEGE ALLOWED
UP TO 5 MESSAGES
NO DECNET LOGICAL LINKS

= SYS(CHR$(6%)+CHR$(22%)+CHR$(1%)+CHR$(0%)
+ LOGNAME$ + STRING$(10%,0%)
+ CHR$(OBJTYPE%)
+ CHR$(ACCESS%)
+ CVT%$(O%)
+ CHR$(MMAX%)
+ CHR$(LMAX%))

8-33

System Calls for Local Interjob Communication
Send Local Data Examples
The following local send calls send a message from a string and from a
buffer.
In both cases, the receiver is referenced by its logical
name.
The intended receiver is the receiver whose logical name is
DEMO.
Note that if you ran this series of examples as a single
program, the job would be sending messages to itself.
The first example is a send from a string.
There is no need to
distinguish between "parameter" and "data" areas of the message as
long as the receiver is aware that part of the message is delivered in
the target string returned by the SYS call and the remainder is
returned in a specified buffer.
2000
LOCAL SEND EXAMPLES
2100

THE FIRST SEND IS A SIMPLE STRING SEND

2110
2190
2200

MSG1$

= "THIS MESSAGE WAS SENT FROM A STRING."

SYS(CHR$(6%)+CHR$(22%)+CHR$(-1%)+CHR$(O%)
+ LOGNAME$ + STRING$(lO%,O%)
+ MSG1$)

2210

PRINT "1ST MESSAGE SENT

";MSG1$

The second send call sends a message from a buffer.
In this case, the
null device is opened on channel 2 to obtain buffer space, the message
data is loaded into the buffer using LSET, and the data portion of the
message is sent from the buffer.
User-defined "parameters" are also
included with this message and are delivered to the receiver.
The use
of JUNK$ at the beginning of the buffer illustrates the use of the
buffer offset field in send calls.
2300
THE SECOND SEND IS A SEND FROM A BUFFER
2310
2320
2330
2340
2350
2360
2370
2380
2390

CHANNEL% = 2%
OPEN "NL:" AS FILE CHANNEL%, RECORDSIZE 100%
FIELD CHANNEL%, 10% AS JUNK$, 90% AS TEXT$
MSG2$
= "THIS MESSAGE WAS SENT FROM A BUFFER."
PARAM$
"MESSAGE #2
"
MSGLEN%
LEN(MSG2$)
OFFSET%
= LEN(JUNK$)
LSET TEXT$ = MSG2$

8-34

System Calls for Local Interjob Communication
2400

= SYS(CHR$(6%)+CHR$(22%)+CHR$(-1%)+CHR$(0%»
+ LOGNAME$
+ CHR$(CHANNEL%)+ CHR$(O%)
+ CHR$(MSGLEN%) + CHR$(SWAP%(MSGLEN%»
+ CHR$(OFFSET%) + CHR$(SWAP%(OFFSET%»
+ STRING$(4%,0%)
+ PARAM$

2410
2420
2430

PRINT u2ND MESSAGE SENT = "iMSG2$
PRINT "PARAMETERS SENT
";PARAM$
PRINT

Receive Examples
~~his

section presents five receive examples.
If you ran this series
of examples as a program, the receives would retrieve the two messages
sent in the send examples of the previous section.

The first receive is a simple receive into a buffer large enough to
hold any expected message.
The receiver is willing to wait up to 10
seconds for a messaqe, so the sleep bit in the receive modifier is
turned on, and a 10 second limit is passed as the sleep timer.
Truncation is also requested because no messages are expected that
~rill be larger than the buffer available.
In this example, the ON
ERROR GOTO, which is normally used to field the "sleep expired" error
(ERR=5), is omitted for simplicity. As mentioned in the discussion of
the first send example, part of the message is delivered to the
receiver,as "parameters" in the target string, and the rest of the
message is delivered to the channel buffer.
3000
RECEIVE EXAMPLES
THIS

3100

FIRS~~

RECEIVE WILL RECEIVE THE FIRST MESSAGE SENT

3110
3120
3130
3190
3200

3210
3220
3230
3240
3250
3260

CHANGE X$ TO X%
!MAKE TARGET STRING USABLE
MSGLEN% = X%(13%)+SWAP%(X%(14%»
!LENGTH OF RECEIVED MESSAGE
BYTREM% = X%(9%) +SWAP%(X%(10%»
!BYTES LOST DUE TO TRUNCATION
IF BYTREM% <> 0% THEN STOP
!CANNOT OCCUR IN EXAMPLE
FIELD #2%, MSGLEN% AS MSG$
!FIELD FOR LENGTH RECEIVED
PRINT "MESSAGE RECEIVED = ";RIGHT(X$,20%);MSG$ !PRINT RCVD MS(

FIELD # CHANNEL%, 100% AS TEXT$
S% = 1%\ TIMER% = 10%
!REQUEST MAX 10 SECOND SLEEP
T% = 2%
!REQUEST TRUNCATION
SYS(CHR$(6%)+CHR$(22%)+CHR$(2%)
+ CHR$(S%+T%) + STRING$(6%,0%)
+ CHR$(CHANNEL%) + STRING$(15%,0%)
+ CHR$(TIMER%)
+ CHR$(SWAP%(TIMER%»)

8-35

System Calls for Local Interjob Communication

The next receive determines the sender's job number and length of the
next pending message. The call requests an indefinite length sleep to
wait for a message to be queued.
In this case, no buffer is provided
because the program does not receive the data portion of any message
on this call.
3300
THIS SECOND RECEIVE CALL IS USED TO DETERMINE IF ANY
FURTHER MESSAGES ARE PENDING AND TO DETERMINE THE JOB
NUMBER OF THE SENDER FOR SUBSEQUENT SELECTIVE
RECEIVE EXAMPLES

= 0%

3310
3320
3390
3400

3410
3420
3430
3440

CHANGE X$ TO X%
SNDJOB% = X%(4%)
BYTREM% = X%(9%)+SWAP%(X%(10%»
IF BYTREM% = 0% THEN STOP

S%
1%\ TIMER%
T% = 0%

!REQUEST INDEFINITE SLEEP
!NO TRUNCATION ALLOWED NOW

= SYS(CHR$(6%)+CHR$(22%)+CHR$(2%)+CHR$(S%»
!GET SENDING JOB 2
!GET # BYTES IN DATA PORTION
!IMPOSSIBLE IN THIS EXAMPLE

The third receive illustrates sender selection.
For this example,
assume the second message sent above is the only message pending
(which is the case for this series of examples).
If the receive
selects some other sender (SNDJOB%+2% in the example below) and no
sleep is requested, an error (ERR=5) should result as shown. Note
that truncation is not allowed on this receive because the program
preserves the pending message.
3500
THE THIRD RECEIVE SELECTS MESSAGES FROM A PARTICULAR
SENDER. IN THIS EXAMPLE A RANDOM JOB IS SELECTED TO
FORCE AN ERROR.
3510
3520
3590
3600

3610
3620
3630

STOP
IF ERR <> 5% THEN STOP
RESUME 3700

ON ERROR GOTO 3620
LCLSEL% = 4%
=

!REQUEST LOCAL SELECTION

SYS(CHR$(6%)+CHR$(22%)+CHR$(2%)
+ CHR$(LCLSEL%)
+ CHR$(SNDJOB%+2%»
!CANNOT OCCUR IN THIS EXAMPLE
!ERR 5 WAS INTENTIONAL

The sender's job number and the number of bytes in the next pending
message are known.
If buffer space is restricted for some reason, it
may be necessary to retrieve the message in several pieces. For the
example, the receive arbitrarily restricts the number of bytes the
caller will accept to 20 bytes by using the length field in the
receive call.
8-36

System Calls for Local Interjob Communication
3700
THE NEXT RECEIVE SELECTS THE SENDER DETERMINED ABOVE.
ONLY A PORTION OF THE MESSAGE IS RETRIEVED ON THIS CALL.
3710
3790
3800

MAXLEN% = 20%

3810
3820
3830
3840
3850

CHANGE X$ TO X%
IF X%(4%) <> SNDJOB% THEN STOP
MSGLEN% = X%(13%)+SWAP%(X%(l4%»
BYTREM% = X%(9%) +SWAP%(S%(lO%»
IF BYTREM% = 0% THEN STOP

!LENGTH ARBITRARILY RESTRICTED

=SYS(CHR$(6%)+CHR$(22%)+CHR$(2%)
+ CHR$(LCLSEL%)
+ CHR$(SNDJOB%) + STRING$(5%,0%)
+ CHR$(CHANNEL%)+ CHR$(O%)
+ CHR$(MAXLEN%) + CHR$(SWAP%(MAXLEN%»)
!MAKE TARGET STRING USABLE
!CANNOT OCCUR IN THIS EXAMPLE
!GET LENGTH RECEIVED
!GET COUNT NOT DELIVERED
!CANNOT OCCUR IN THIS EXAMPLE

At this point, the program has received part of the message (MSGLEN%
characters).
The rE!st of the message (BY~REM% characters) is still
queued.
The last rE!ceive retrieves the re-st of the message and places
it in the buffer immediately after the portion delivered on the
previous receive.
Sender selection makes sure that the data received
is the remainder of the same message delivered on the previous call.
3900
THE LAST RECEIVE WILL RETRIEVE THE REST OF THE DATA FROM
THE SECOND MESSAGE SENT IN LINE 2400 ABOVE.
!BUFFER OFFSET FOR RECEIVE

OFFSET% = MSGLEN%

3910
3990
4000

4010
4020
4030
4040
4050
4060
4070

CHANGE X$ TO X%
!MAKE TARGET STRING USABLE
IF X%(4%) <> SNDJOB% THEN STOP !CANNOT OCCUR IN THIS EXAMPLE
MSGLEN%=MSGLEN%+X%(l3%)+SWAP%(X%(14%»
!TOTAL LENGTH OF MSG
BYTREM%=X%(9%)+SWAP%(X%(10%»
!AND COUNT NOT DELIVERED
IF BYTREM% <> 0% THEN STOP
!WHICH SHOULD BE ZERO
FIELD #2%,MSGLEN% AS MSG$
!FIELD COMPLETE MESSAGE
PRINT "MESSAGE RECEIVED + u;MSG$!AND PRINT COMPLETE MESSAGE

= SYS(CHR$(6%)+CHR$(22%)+CHR$(2%)
+ CHR$(LCLSEL%)
+ CHR$(SNDJOB%) + STRING$(5%,0%)
+ CHR$(CHANNEL%)+ STRING$(3%,0%)
+ CHR$(OFFSET%) + CHR$(SWAP%(OFFSET%»)

In the last three receive calls, the examples have been working on a
single pending message.
Recall that the data portion of the message
was sent from a buffer and was just received in a buffer.

8-37

System Calls for Local Interjob Communication
However, the second send in the previous section also included some
"parameters" that were actually delivered to the receiver on each of
the last three receives. You can verify this by printing the last 20
characters of the target string returned by the last receive call:
4100
PRINT PARAMETER AREA OF SECOND MESSAGE FOR VERIFICATION
4110

PRINT "PARAMETER AREA

= ";RIGHT(X$,20%)

The example ends with a remove receiver call and a close of the
channel buffer used to receive messages:
5000
REMOVE RECEIVER EXAMPLE
5200 X$ = SYS(CHR$(6%)+CHR$(22%)+CHR$(0%)+CHR$(0%))
6000
6010 CLOSE 2%
32767 END

Summary of Data Values
Figure 8-1 summarizes the data passed and returned in the send/receive
calls.

8-38

1 1
SEND Loc...6L DAT.lt: i
(from buffer)
SEND LOCAL DATA
(from string)
SEND LOCAL DATA
(from buffer)

SEND LOCAL DATA
(from string)

SEND LOCAL DATA WITH
PRIVILEGES (from butler)

ex>
W

1..0

I I I I I
2

i
22

-1

i
O.J

1 7

I I I I

1 12

I I I I I I I I I I I I I I I I I I I I I I I I I

RECEIVER'S LOGICAl NAME

-1

O,J

RECEIVER'S LOGICAL NAME

-1

01010101010

-1

01010101010

-11

O,J

RECEIVER'S LOGICAL NAME

O,J

LENGTH

OFFSET

RESERVE!)
LENGTH

OFFSET

RESERVED

37 1 38 1 39

1 40

I +
41

[D$J

USER-OEFINED PARAMETERS (PS)

RESERVED

USER-OEFINED PARAMETERS (PS)

RESERVED

USER-OEFINED PARAMETERS (PS)

RESERVED

USER-OEFINED PARAMETERS (PS)

[D$J 1

til

LENGTH

OFFSET

USER-OEFINED PARAMETERS (PS)
[D$J 1

fn
C"t'

[D$rj

!:I

SEND LOCAL DATA WITH
PRMLEGES (from stmg)

-11

RECEIVER'S LOGICAL NAME

SEND LOCAL DATA WITH
PRIVILEGES (from butler)

-11

01010101010

SEND LOCAL DATA WITH
PRIVILEGES (from butler)

-11

01010101010

RESERVED

REMOVE RECEIVER

O,J

01010101010

RESERVED

DECLARE RECEIVER

RESERVED

BMAl(

IMMAX! [],lAX PKTMAX OMAXI POTA I

RIB

RESERVED

MOD

S~~tRIJJ..h.1

.....

RECEIVE

RESERVED

SLEEPTNER

RESERVED

RIB

RESERVED

RECEIVE

MOD

S~JlLRIJJ..h.1

RESERVED

SLEEP TIlER

RESERVED

RIB

RESERVED

-1

PPN

RESERVED

-11

PPN

RESERVED
LENGTH

OFFSET

LOCAL DATA
RETURNED ON RECEIVE

RECEIVER'S LOGICAL NAME

LENGTH

OFFSET

RESERVED

i!WE IAcr..ESSI

RIB
RESERVED, ..

D,N 1

RESERVED

SlJ

.....

I'"h

I I I RE'tv.;s~fNG
I
I REt2~fNG
RES

RESERVED

LENGTH

KB 1 RES

RESERVED

LENGTH

I
I

RESERVED

o
t1

PS ~ USER-OEFINED PARAMETERS

RESERVED
PRIVILEGE MASK

PS ~ USER-DEFINED PARAMETERS

tot

o
MK-00038-01

Figure 8-1:

Summary of SendjReceive Data

.....

::s

C"t'

CD
t1

n
o

r::

::s....

....

C"t'

::s

Chapter 9
System Call for Print/Batch Services

This chapter describes the System Call for Print/Batch Services (PBS),
Cl subfunction of the Send/Receive System Function Call (SYS 22).
This
call allows an application program to communicate directly with PBS to
issue print or batch requests.
This system call does not communicate
with the OPSER-based spooling program.
Use the Spooling SYS call (SYS
-28) to issue requests to OPSER.
In its request, the application can include all of the parameters
available with the PRINT and SUBMIT commands.
(See the RSTS/E System
User's Guide for more information on DCL commands.) PBS request
processing differs from DCL, however, in that when PBS receives a
request, it does not check file names and form names that you specify
in the request to see if they exist.

Sending a User Request Packet
application issues a print or batch request by creating a request
packet and sending it to PBS with the Send/Receive subfunction, Send
User Request Packet.
Unlike the Spooling SYS call (SYS -28), most of
the parameters in the request are in the data buffer portion of the
message.
For the parameters and data that you can include in a user
request packet, see the Data Passed and Data Field Layout sections.

J~n

Confirming a User Request
Often an application wants to know whether PBS accepted or rejected a
request and what error caused the request to be rejected.
User
request packets allow an application to include the name of a receiver
to which PBS returns a completion status message. After PBS processes
the request, it returns status information to the designated receiver.
On the other hand, an application that does not need confirmation of
its request can omit a receiver name from the request.

9-1

System Call for Print/Batch Services
Send User Request Packet
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(22%), the send/receive function code.

CHR$(-ll%), the send local message with privilege mask
subfunction code.

CHR$(128% + 5%).
This value indicates a send request for
local\ object type 5.
This object type is reserved for the
queue manager receiver that processes user request packets.

5-10

Reserved; should be O.

CHR$(C%), the channel number for the I/O buffer that
contains the data portion of the message.
If this byte is 0%, a string beginning at byte 41 contains
the data portion of this message (if any).
If this byte contains a channel number (any value from 1 to
12), a buffer defined by the length and offset values
contains the data portion of this message.
The message data
(up to 512 bytes) should be left-justified in the buffer for
channel C%, beginning at the offset value defined in bytes
15-16.
Channel 0 can be used for the I/O buffer if 128 is added to
the channel number, that is, CHR$(128%+0%).
In general,
CHR$(128%+C%) allows channels 0 through 12 to be used for
I/O buffers.

CHR$(O%), reserved; should be O.

13-14

L%, the length (in bytes) of the message to send from the
channel buffer in the form CVT%$(SWAP%(L%».
If byte 11 is 0%, the system ignores these bytes.
For local data messages, this length field can have any
value between 0 and 512, subject to the restriction that the
length of the message is less than or equal to the buffer
size minus the offset value.
If the length is 0, the system
sends the whole buffer (that is, from the offset to the end
of the buffer).

9-2

System Call for Print/Batch Services
15-16

0%, the offset value in the form CVT%$(SWAP%(O%)).
The value specifies the offset from the beginning of the
buffer where the message data begins.
The offset must be in
the range 0 to <size of buffer - 1>.

17-28
29

Reserved; should be O.
CHR$(N%), where N% must be one of the following values:
Value
1%
2%

30
31-36

Meaning
Print request
Batch request

Reserved; should be O.
N$, the receiver ID for confirmation
The receiver name is a one- to six-character ASCII string
containing the name of the receiver to receive a
confirmation message.
It is left-justified and padded to
six characters with spaces.
If the first byte is a null,
CHR$(O%), then no confirmation message is returned.
The
was
why
the

confirmation message either indicates that the request
accepted (success), or contains an error code indicating
the request was rejected and, if applicable, the code of
field that caused the error.
See Discus~ion.

37-38

C$, a confirmation context value.

39-40

Reserved; should be O.

41 +

The data field.

See Discussion.

See the Data Field Layout section.

Confirmation Data Received by Receiver
Bytes
1-2

Meaning
Not used.

CHR$(-ll%), the local data message with privileges
subfunction code.

The job number times 2 of the PBS job that processed the
request.

5-6+

PPN of the PBS job.

CHR$(255%)

9-3

System Call for Print/Batch Services

Not used.

CHR$(O%)

10-28

Not used.

29-30

The confirmation value passed in bytes 37-38 when the
request was sent.

31-32

The error status code, indicating whether the request was
accepted.
If this code is 0, the request was accepted.
If
nonzero, the request was not accepted, and the value in this
field indicates the error code (see the Possible Errors
section).

33-34

The field code.
For rejected requests, these bytes identify
the field in which the error occurred.
For successful
requests, these bytes contains the entry number assigned to
the request.

35-40

Not used.

Privileges Required
EXQTA

Override the queue's maximum limit on priority, pages, time,
and CPU time.

GACNT

Specify a different owner within the group.

WACNT

Specify any owner.

Possible Error Codes in the SYS Call
This call returns the same errors as the Send Local Data subfunction
of the Send/Receive SYS call.
See Chapter 8 for more information.
Possible Error Codes in the Confirmation Message (bytes 31-32)
Meaning
?ILLEGAL FILE NAME
For the /NAME, /QUEUE, /FORMS, or Logfile Queue Name
field, the name specified contains one or more
invalid characters.
For the ASCII file-spec, Binary file-spec, or
/LOG FILE field, the field contains an invalid
RSTS/E file specification or does not refer to a
disk file.
9-4

Value
2

System Call for Print/Batch Services
?NO ROOM FOR USER ON DEVICE
For the /QUEUE field, the specified queue is
currently closed or marked for deletion.

For the Logfile Queue Name field, the specified
print queue is currently closed or marked for
deletion.
?CAN'T FIND FILE OR ACCOUNT
For the /QUEUE field, the specified queue does not
exist, or no default queue is currently defined.

For the Logfile Queue Name field, the specified
print queue does not exist, or no default print
queue is currently defined.
For the /OWNER field, the account specified is not a
valid RSTS/E account or does not exist.
Note that
no-user accounts (without a password attribute
block) are not considered valid accounts.
For the /FORMS field, no /FORMS field was specified,
but the request's print queue does not have a
default form name defined.
?PROTECTION VIOLATION
For the /QUEUE and /LOG QUEUE fields, the owner does
not have sufficient pri~ilege to use the specified
queue.

t'NO BUFFER SPACE AVJ~ILABLE
There is insufficient buffer space in the PBS
package to process the request.
This is a temporary
condition.
Issue the request again after a short
delay.

?VIRTUAL BUFFER TOO LARGE
The internal entry packet generated by the request
exceeded 512 bytes. Reduce the number of file
specification fields or reduce the length of the
/PARAMETERS field.

?ILLEGAL NUMBER
For the /JOB_COUNT field, the job count value
specified was not in the range 0-127.

For the /AFTER field, the date or time value
specified was not a valid RSTS/E date or time.
For the /PRIORITY field, the priority value exceeded
the maximum priority allowed for the request's
queue.
9-5

System Call for Print/Batch Services
For the /PAGE LIMIT, /CPU LIMIT, or /TIME_LIMIT
field, the limit value exceeded the maximum limit
allowed for the request's queue.
?SUBSCRIPT OUT OF RANGE
The specified field code was invalid.
You can use
only the field codes listed in Table 9-1.

?NOT ENOUGH DATA IN RECORD
No ASC~I (code 128) or binary (code 129) file
specification was found.
A User Request Packet
requires at least one file specification field.

?FIELD OVERFLOWS BUFFER
The field was incomplete.
This error occurs when
the end of the data buffer is encountered before the
expected end of a field is reached.

?ARGUMENTS DON'T MATCH
If the field code returned is 0, then the request
type specified in byte 19 was invalid.

If the field code returned is nonzero, then that
field conflicted with the request type specified;
that is, a batch-only field was included with a
print request, or a print-only field was included
with a batch request.
Discussion
Bytes 31-36 contain the name of the receiver to receive a confirmation
message.
If the first byte is 0, PBS does not return a confirmation
message.
If a receiver name is specified, PBS makes sure that the
receiver name belongs to the job issuing the request.
If it does not,
PBS does not return confirmation.
Bytes 37-38 contain a confirmation word for the confirmation message.
PBS returns this value to the requesting job, allowing it to match a
confirmation message with a request message sent.
This is useful when
an application sends several request packets and needs a separate
confirmation for each.
In such cases, you should assign a unique
context value to each request, so that your program can properly match
the confirmation message with its request.
you do not specify a
confirmation message receiver (byte 31 = 0), PBS ignores this word.
PBS returns the confirmation context value in bytes 29-30, if the
caller requested one by specifying a receiver name (other than a null
receiver name) in the request.
However, there are cases when PBS does
not return a confirmation packet, even though the caller specified a
receiver name.
This occurs when the caller passes the parameter data
(bytes 1-40) incorrectly, causing PBS to ignore the request
9-6

System Call for Print/Batch Services
completely.
Also, if the receiver name specified does not exist or
does not belong to the job issuing the request, PBS processes the
request but does not return a confirmation.
If the user request is successful, PBS places the requested entry on a
queue.
This remains true even in cases where confirmation fails.
Programs should perform Receive With Sleep functions while waiting for
confirmation of a request.
See the Receive subfunction of the
Send/Receive SYS call in Chapter 8 for more information.
The time required for PBS to complete a request depends on the request
itself and the overall system load.
It is good programming practice
for programs waiting for confirmation to "time out" after a reasonable
amount of time (30 seconds is usually sufficient), in case the request
was passed improperly.
Data Field Layout
This section describes each of the data fields that you can include in
a user request packet.
You pass these fields in the data buffer
portion of the message, beginning at byte 41.
You can also pass the
fields in an alternate buffer assigned to a channel number.
Each
field in the data buffer must begin on an odd byte and consists of a
I-byte field code fc)llowed by one or more data bytes for the field.
Fields that use word or double-word values require that all word
values start on an odd byte.
Some fields have a fixed length, while others include text strings and
are variable in length. variable-length strings always consist of a
length byte followed immediately by the characters of the string,
called "counted ASCII" strings.
The length byte of a counted ASCII
string should not count itself in its value, only the number of
characters that follow.
PBS ignores all nulls, tabs, and blanks in an
ASCII string, and converts all lowercase characters to uppercase.
PBS
also ignores a counted ASCII string field with a length byte of O.
Normally, the individual fields that make up a User Request Packet are
You can leave some
stored one after the other in the data buffer.
room between fields by filling the unused part of the data buffer with
nulls, CHR$(O%).
In some cases, this may make it easier to deal with
variable-length fields.
You can use one of two fields to specify a file:
o

The ASCII File Specification Field.
This variable-length
field contains the name of a RSTS/E file specification as a
counted ASCII string.

9-7

System Call for Print/Batch Services
o

The Binary File Specification Field. This fixed-length field
contains a RSTS/E file specification in binary format,
similar to that returned by the File Name String Scan SYS
call (SYS -10).

You must include at least one of these two file specification fields
in a User Request Packet.
There can be multiple occurrences of either
or both file specification fields; all other fields in the packet are
optional.
The field descriptions that follow discuss the default
values assigned to such fields.
Some fields represent file qualifier fields, and are used in
conjunction with a file specification field to provide additional
information about the file.
For example, the /COPIES field indicates
the number of file copies to print.
Like file specification fields, you can specify more than one file
qualifier field.
Generally, you place each file qualifier field right
after its file specification field.
However, you can specify a file
qualifier field only once and have it apply to all file specification
fields in the request.
PBS interprets file qualifier fields according
to these rules:
o

If a file qualifier field appears after a file specification
field in the data buffer, then it applies only to the last
file specification field that precedes it.

If a file qualifier field precedes all file specification
fields in the data buffer, then it applies to all file
specification fields in the buffer.
This action corresponds
to the standard DCL rules for file qualifiers.
For example,
if a /COPIES field with the value 2 precedes all file
specification fields, then PBS prints two copies of each file
in the packet.
You can override this global file qualifier
for a single file specification field by placing a second
file qualifier field after it.

If a file qualifier field does not appear anywhere in a
request packet, then PBS assigns a default value.
For
example, if a data buffer includes no /COPIES field, then PBS
prints one copy of each file in the request.

The following fields represent file qualifier fields:
o

/[NO]CONVERT Flag field

/COPIES field

/[NO]DELETE Flag field

/[NO]FEED Flag field

9-8

System Call for Print/Batch Servicef
o

/[NO]FLAG_PAGES Flag field

/[NO]TRUNCATE Flag field

Only file specification fields and file qualifier fields can occur
more than once in a user request packet.
If PBS encounters any other
field more than once, it uses only the value of the last copy of a
duplicate field.
The data buffer that you pass with a user request can be up to 512
bytes long. PBS cdnverts a valid user request packet into a queue
entry packet and places the entry in the queue file.
The maximum
length of an entry packet is also 512 bytes.
It is possible for a
user request to generate an entry packet that is larger than 512
bytes.
In such cases, PBS rejects the user request packet. The
following fields can affect the size of the internal entry packet:
o

ASCII file specification field

Binary file specification field

/PARAMETERS field

Generally, you can prevent an overflow condition by reducing the
number of file specification fields or reducing the length of the
/PARAMETERS field in a User Request Packet.
Do not include duplicate /PARAMETERS fields in a request, because PBS
attempts to allocate space for each occurrence, even though it only
uses the rightmost occurrence of the field. As a result, an overflow
condition can occur.
Each field described in this section corresponds to a command
qualifier, file qualifier, or command parameter in the DeL PRINT and
SUBMIT commands. See the RSTS/E System Manager's Guide for a complet
description of the rules governing the use of the fields.
Table 9-1 summarizes the user request data fields, in ascending order
of code number. The remainder of this section describes each data
field in detail.

9-9

System Call for Print/Batch Services
Table 9·1:

User Request Data Fields

+- - - - - -+- - - - - - - - - - - - - - - - _. - - - - - - - _. _. - - -+- - - - - - - - - - - - --+
I Code I
Field
: Request Type I
+- - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - --+
I
I
I

/NAME

Any

/QUEUE

Any

/OWNER

Any

I
I

/~RIORITY

Any

/FORMS

/AFTER

Any

Batch

/PARAMETERS

Batch

/[NO]HOLD

Any

/[NO]LOG_FILE Flag

Batch

/LOG_FILE File Specification

Batch

/[NO]LOG_QUEUE Flag

Batch

/LOG_QUEUE Name

Batch

/LOG_DELETE Flag

Batch

128

ASCII File Specification

Any

129

Binary File Specification

Any

130

/[NO]CONVERT Flag

131

/COPIES

9-10

October 1985

System Call for print/Batch Services
Table 9·1:

User Request Data Fields (Cont.)

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

Code I
Field
I Request Type I
+- - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - --+
!

132

/[NO]DELETE Flag

Any

133

/[NO]FEED Flag

Print
Print

134
135
-j-- - - - -

/[NO]TRUNCATE Flag

-+_. _ •• _. - - _. - •. - - - - - - - _. - - - - - _. - -+- - - - - - - _. - - - - ..f-

INAME Field
This field specifies the name of the entry to be placed in the queue,
and corresponds to the entry name specified in the PRINT and SUBMIT
commands.
If you omit this field or specify a length of 0, PBS uses
the file name of the first file specific~tion field that represents a
valid entry name.
Since entry names cannot consist exclusively of
numeric characters, PBS uses the name PRINT or BATCH if it encounters
all numeric file names in the request.
PBS truncates all names to
nine characters.
The format of the /NAME field is:
Byte

Specification

CHR$(l%)

CHR$(N%), where N% is the length of the name string.

N$, the entry name.

/QUEUE Field
This field specifies the name of the queue on which PBS is to place
the request, and corresponds to the queue name specified in a PRINT
and SUBMIT commands.
If you omit this field or specify a length of 0,
PBS places the requE~st on the default queue of the same type (print 01
batch).

9-11

System Call for Print/Batch Services
The format of the /QUEUE field is:
Byte

Specification

CHR$(2%)

CHR$(N%), where N% is the length of the name string.

N$, the queue name.

/OWNER Field
This field specifies the PPN for the owner of the request, and
corresponds to the /OWNER qualifier of the PRINT and SUBMIT commands.
If you omit this field, the packet sender becomes the owner by
default.
If the PPN specified is [0,0] or is the same as the
sender's, PBS ignores this field.
You need the GACNT privilege to specify a different PPN within the
group, and WACNT privilege to specify any PPN. Note that when you
specify /OWNER with a PPN other than your own, PBS bases all access
rights and privileges for the request on the authorized privileges of
that owner's account.
The format of the /OWNER field is:
Byte

Specification

CHR$(3%)

CHR$(O%)

Programmer number.

Project number.

/PRIORITY Field
This field defines the priority of the request, and corresponds to the
/PRIORITY qualifier of the PRINT and SUBMIT commands. If you omit
this field or specify a value of 0, PBS uses the default priority for
the queue on which the request is placed. unless the caller has EXQTA
privilege, the priority value cannot exceed the maximum priority
defined for the request's queue.

9-12

System Call for Print/Batch Services
The format of the /PRIORITY field is:
Byte

Specification

CHR$(4%)

CHR$(N%), where N% is the priority.

/JOB_COUNT Field
This field applies to print requests only.
It specifies the number of
job copies to be printed, and corresponds to the /JOB COUNT qualifier
of the PRINT command.
If you omit this field or specify the value 0,
PBS assumes a job count of 1. PBS permits any value in the range 1 to
255.
The format of the /JOB_COUNT field is:
Specification

Byte
1

CHR$(5%)

CHR$(N%), where N% is the job count.

/FORMS Field
This field applies to print requests only.
It identifies the forms
required for the print job, and corresponds to the /FORMS qualifier of
the PRINT command.
If you omit this field or specify a length of 0,
PBS uses the default form name for the queue on which the request is
placed.
PBS truncates all names to nine characters.
Note that PBS does not verify that the specified form name exists in
the Forms Definition file.
The format of the /FORMS field is:
Byte

Specification

CHR$(6%)

CHR$(N%), where N% is the length of the form name string.

N$, the form name.

9-13

System Call for Print/Batch Services

/AFTER Field
This field specifies a date and time before which PBS will not process
the request, and corresponds to the /AFTER qualifier of the PRINT and
SUBMIT commands.
If you omit this field, PBS processes the request as
soon as possible.
The /AFTER Date/Time field consists of a standard
RSTS/E date word and a standard RSTS/E time word.
If the date word is
0, PBS uses the current system date. If the time word is 0, PBS uses
the time 11:59 PM (end-of-day). An error results if the values you
specify do not represent a valid date or time.
The format of the /AFTER field is:
Byte

Specification

CHR$(7%)

CHR$(O%)

3-4

CHR$(D%) + CHR$(SWAP%(D%», where D% is the after date word.

5-6

CHR$(T%) + CHR$(SWAP%(T%», where T% is the after time word.,

/PAGE_LIMIT Field
This field applies to print requests only.
It defines the maximum
number of pages that PBS prints in the requested print job, and
corresponds to the /PAGE_LIMIT qualifier of the PRINT command.
If you
omit this field or specify a value of 0, PBS uses the default page
limit of the request's queue.
Unless the caller has EXQTA privilege,
an error results if this value exceeds the maximum page limit of the
request's queue.
The double-word value -1 instructs PBS to impose no page limit on the
requested print job, and is similar to the /PAGE LIMIT=UNLIMITED
qualifier. An error results if the request's queue does not have its
maximum page limit set to UNLIMITED.
The format of the /PAGE_LIMIT field is:
Byte

Specification

CHR$(8%)

CHR$(O%)

3-4

CHR$(P%) + CHR$(SWAP%(P%», where P% is the least
significant word of the page limit.

5-6

CHR$(P%) + CHR$(SWAP%(P%», where P% is the most significant.
word of the page limit.
9-14

System Call for Print/Batch Services
/CPU LIMIT Field
This field applies to batch requests only.
It defines a CPU limit for
the requested batch job, and corresponds to the /CPU_LIMIT qualifier
of the SUBMIT comfuand.
If you omit this field or specify a value of
0, PBS uses the default CPU limit of th~ request's queue. Unless the
caller has EXQTA privilege, an error results if this value exceeds the
maximum CPU limit of the request's queue.
The double-word value -1 instructs PBS to impose no CPU limit on the
requested batch job p and is similar to' the /CPU_LIMIT=UNLIMITED
qualifier. An error results if the request's queue does not have its
maximum CPU limit set to UNLIMITED.
The format of the /CPU_LIMIT field is:
Byte

Specification

CHR$(9%)

CHR$(O%)

3-4

CHR$(C%) + CHR$(SWAP%(C%»), where C% is the CPU limit.

/TIME_LIMIT Field
This field applies to batch requests only.
It defines an elapsed time
limit for the requested job, and corresponds to the /TIME LIMIT
qualifier of the SUBMIT command.
If you omit this field ;r specify a
value of 0, PBS uses the default time limit of the request's queue.
Unless the caller has EXQTA privilege, an error results if this value
exceeds the maximum time limit defined for the request's queue.
The value -1 instructs PBS to impose no time limit on the requested
batch job, and is similar to the /TIME_LIMIT=UNLIMITED qualifier. An
error results if the request's queue does not have its maximum time
limit set to UNLIMITED.
The format of the /TIME_LIMIT field is:
Byte

Specification

CHR$(10%)

CHR$(O%)

3-4

CHR$(T%) + CHR$(SWAP%(T%», where T% is the time limit.

9-15

System Call for Print/Batch Services
/PARAMETERS Field
This field applies to batch requests only.
It contains a string of
parameters to be passed to the batch job when it starts, and
corresponds to the /PARAMETERS qualifier of the SUBMIT command. You
can specify up to eight parameters, separated by one or more spaces or
tabs (not commas).
PBS accepts only printable characters in the
/PARAMETERS string; PBS strips all nonprintable characters from the
string. Also, you must place quotes around any individual parameter'
that includes embedded spaces or tabs.
If you omit this field or
specify a length of 0, PBS passes no parameters to the batch job.
The format of the /PARAMETERS field is:
Byte

Specification

CHR$(11%)

CHR$(N%), where N% is the length of the parameter string.

p$, the parameter string.

/[NO]HOLD Flag Field
This field consists of a flag byte that determines whether PBS
initially puts the request on hold.
PBS does not process an entry on
hold until you release it with the SET ENTRY/RELEASE command. This
field corresponds to the /[NO)HOLD qualifier of the PRINT and SUBMIT
commands.
If you omit this field or specify a value of 0, PBS does not put the
request on hold.
If the flag byte is nonzero, PBS puts the request on
hold.
The format of the /[NO)HOLD field is:
Byte

Specification

CHR$(12%)

CHR$(N%), where N% is the flag byte.
0%

No hold (the default)

Hold

9-16

Values are:

System Call for Print/Batch Services
/[NO]LOG_FILE Flag Field
This field applies to batch requests only.
It consists of a flag byte
that determines whether PBS creates a log file for the batch job, and
corresponds to the /[NO]LOG_FILE qualifier of the SUBMIT command.
Generally, you include thi~ field to disable logging, since, by
default, PBS always creates a log file.
If you omit this field or if
the fla9 byte is nonzero, PBS creates a log file at the start of the
batch job.
If you also include a /LOG_FILE File Specification field,
PBS uses that file specification as the log file name.
If the flag byte is 0 and you include a /LOG_FILE File Specification
field, PBS use the rightmost rule to resolve the conflicting fields.
That is, PBS ignores the first field and determines whether to create
a log file based only on the second field.
The format of the /[NO]LOG_FILE Flag field is:
Byte

Specification

CHR$(13%)

CHR$(N%), where N% is the flag byte.
0%

No log file

Log file (the default)

Values are:

/LOG_FILE File Specification Field
This field applies to batch requests only.
It specifies the log file
that PBS uses for batch processing, and corresponds to the
/LOG_FILE=file-spec qualifier of the SUBMIT command.
If you omit this field or specify a length of 0 (and you do not
specify a value of 0 in the LOG FILE Flag field), PBS creates a
default log file specification.- Generally, you use this field to
specify a log file ()ther than the default, since the /LOG FILE Flag
field creates the default log file-spec.
If you specify this field and also specify a value of 0 in the
/LOG_FILE Flag field, PBS use the rightmost rule to resolve the
conflicting fields.
That is, PBS ignores the first field and
determines whether to create a log file based only on the second
field.

9-17

System Call for print/Batch Services
This field contains a single RSTS/E file specification
(dev:[PPN]filnam.typ) as a counted ASCII string.
If you do not
specify a device, PBS assumes _SY:.
If you omit the PPN, PBS assumes
the sender's PPN.
You must specify a file name.
If you omit the file
type, then PBS appends the file type .LOG.
The format of the /LOG_FILE field is:
Specification

Byte
1

CHR$(14%)

CHR$(N%), where N% is the length of the log file
specification.

L$, the log file specification.

/[NO]LOG_QUEUE Flag Field
This field applies to batch requests only.
It consists of a flag byte
that determines ~hether PBS queues the batch job's log file for
printing when the job completes, and corresponds to the /[NO]LOG QUEUE
qualifier of the SUBMIT command.
If you omit this field or specify a flag byte 0
0, PBS does not queue
for printing any log file created for the batch job.
If the flag byte
is nonzero, PBS queues the log file for printing on the default queue
when the batch job completes.
If you also include a /LOG QUEUE Name
field, PBS uses that file specification as the queue name:
The /LOG_QUEUE Name field also affects whether PBS queues any log filE~
for printing.
If you specify a flag byte value of 0 and you include a
/LOG QUEUE Name field, PBS use the rightmost rule to resolve the
conflicting fields.
That is, PBS ignores the first field and
determines whether to create a log file based only on the second
field.
PBS ignores this field if you disable logging by using a /[NO]LOG_FILE
Flag field with a 0 value in its flag byte.
The format of the /LOG_QUEUE Flag field is:
Specification

Byte
1

CHR$(15%)

CHR$(N%), where N% is the flag byte.
0%

No log queue (the default)

Log queue
9-18

Values are:

System Call for Print/Batch Services
/LOG_QUEUE Name Field
This field applies to batch requests only.
It defines the queue on
which PBS places the log file print request after it completes the
batch job, and corresponds to the /LOG QUEUE=queue-name qualifier of
the SUBMIT command.
PBS ignores this fiE~ld if you disable logging by using a /[NO]LOG_FILE
Flag field with a 0 value in its flag byte.
If you omit this fiE!ld or specify a length of 0 (and you also specify
a nonzero value in the /LOG QUEUE field), PBS places the log file
print request on the defaulI print queue.
Generally, you include this field to specify a queue other than the
default print queue for PBS to place the log file print request.
If
you want to place the request on the default print queue, use the
/LOG_QUEUE Flag field instead.
T'he /LOG_QUEUE Flag field also affects whether PBS queues any log file
for printing.
If you omit the /LOG QUEUE Flag field or specify a flag
value of 0, and you include a /LOG ~UEUE Name field, PBS use the
r~ghtmost rule to resolve the conflicting fields.
That is, PBS
ignores the first field and determines whether to create a log file
based only on the second field.
The format of the /LOG_QUEUE Name field is:
Specification
1

CHR$(16%)

CHR$(N%), where N% is the length of the log file queue name.

L$, the log file queue name.

/£NO]LOG_DELETE Flag Field
This field applies to batch requests only.
It consists of a flag byte
that determines whether PBS deletes the log file after it is printed,
and corresponds to the /[NO]LOG DELETE qualifier of the SUBMIT
commandQ
PBS ignores this field unless you queue a log file for printing by
using the /[N01LOG_QUEUE Flag field and /LOG_QUEUE Name field.
If you omit this field or specify a fiag byte of 0, PBS does not
delete the log file after printing.
If the flag byte is nonzero, PBS
deletes the log file after printing.

9-19

System Call for Print/Batch Services
The format of the /[NO]LOG_DELETE Flag field is:
Specification

Byte
1

CHR$(17%)

CHR$(N%), where N% is the flag byte.
0%

No log delete (the default)

Log delete

Values are:

ASCII File Specification Field
This field contains the name of a file to be printed (print requests)
or a command file to be processed (batch requests), and corresponds to
the file specification parameter of the PRINT and SUBMIT commands.
The file specification field contains a single RSTS/E file
specification (dev:[PPN]filnam.typ) as a counted ASCII string.
If you
do not specify a device, PBS assumes _SY:.
If you omit the PPN, PBS
assumes the caller's PPN.
You must specify a file name.
If you omit
the file type, then PBS appends the .LST file type for print requests
or the .COM file type for batch requests.
The PPN, file name, and
file type fields can contain wildcard characters.
You must define at least one ASCII or Binary File Specification field
in a user request packet. One request packet can contain several of
these fields.
Note that PBS does not verify the existence of any files matching the
field's file specification.
The format of the ASCII File Specification field is:
Byte

Specification

CHR$(128%)

CHR$(N%), where N% is the length of the ASCTI file
specification.

F$, ASCII file specification.

9-20

System Call for Print/Batch Services
Binary File Specification Field
This field contains, in binary format, the file specification to be
printed (print requests) or the command file to be processed (batch
requests), and corresponds to the file specification parameter of the
PRINT and SUBMIT commands.
.
Unlike the ASCII File Specification field, this field is fixed length.
Its format corresponds closely to that of the data string returned by
the File Name String Scan SYS call (SYS -10) for a file specification.
In most cases, your program can simply copy fields from the data
string to the Binary File Specification field in the packet buffer.
The Binary File Specification field contains a single RSTS/E file
specification (dev:[PPN]filnam.typ).
If the device part is null, PBS
assumes SY:.
If the PPN part is null, PBS assumes the caller's PPN.
The file name cannot be null.
The PPN, file name, and file type
; fields can contain wildcard characters.
You must define at least one ASCII or Binary File Specification field
in a user request packet.
One request packet can contain several of
these fields.
Note that PBS does not verify the existence of any files matching the
field's file specification.
The format of the binary file specification field is:
Byte

Speci.fication

CHR$(129%)

CHR$(O%)

Programmer number.

Project number.

5-8

File name in Radix-50 format.

9-10

File type in Radix-50 format.

11-12

Disk device name.

Device unit number.

Unit number real flag.

9-21

System Call for Print/Batch Services
/[NO]CONVERT Flag Field
This field applies to print requests only.
It consists of a flag byte
that determines whether PBS converts all 0 (zero) characters to 0
("oh") characters, and corresponds to the /[NO]CONVERT qualifier of
the PRINT command.
If the flag byte is nonzero, PBS performs zero-to-oh conversion.
If
you omit this field or specify a flag byte of 0, PBS does not perform
a conversion.
The format of the /[NO]CONVERT Flag field is:

Specification

Byte
I

CHR$(130%)

CHR$(N%), where N% is the flag byte.
0%

Do not convert (the default)

Convert

Values are:

/COPIES Field
This field applies to print requests only.
It indicates the number of
file copies to print, and corresponds to the /COPIES file qualifier of
the PRINT command.
If you omit this field or specify a value of 0, PBS prints one copy of
each file.
PBS accepts any value in the range I to 255.
The format of the /COPIES field is:

Byte

Specification

CHR$(13%)

CHR$(N%), where N% is the number of copies.

/[NO]DELETE Flag Field
This field consists of a flag byte that determines whether PBS deletes
the file after printing or execution, and corresponds to the /DELETE
qualifier of the PRINT and SUBMIT commands.
If the flag byte is nonzero, PBS deletes the file.
If you omit this
field or specify a flag byte of 0, PBS does not delete the file.

9-22

System Call for Print/Batch Services
The format of the /(NO]DELETE Flag field is:
Byte

Specification

CHR$(132%)

CHR$(N%), where N% is the flag byte.
0%

Do not delete (the default)

Delete

Values are:

/[NO]FEED Flag Field
This field applies to print requests only.
It consists of a flag byte
that determines whether PBS performs a form-feed whenever printing
reaches six lines from the bottom of the page, and corresponds to the
/FEED file qualifier of the PRINT command.
If the flag byte is nonzero or you omit this field, PBS performs the
form-feed.
If the flag byte is 0, PBS performs no form-feed.
The format of the /[NO]FEED Flag field is:
Byte

Specification

CHR$(133%)

CHR$(N%), where N% is the flag byte.
0%

No feed

Feed (the default)

Values are:

/[NO]FLAG_PAGES Flag Field
This field applies to print requests only.
It consists of a flag byte
that determines whether PBS prints flag pages at the beginning of each
file listing, and corresponds to the /[NO]FLAG_PAGES file qualifier of
the PRINT command.
If the flag byte is nonzero, or you omit this field, PBS prints flag
pages based on the setting of the request's form.
If the flag byte is
0, PBS prints no flag pages.

9-23

System Call for Print/Batch Services
The format of the /[NO]FLAG_PAGES Flag field is:
Specification

Byte
1

CHR$(134%)

CHR$(N%), where N% is the flag byte.
0%

No flag pages

Flag pages (the default)

Values are:

/[NO]TRUNCATE Flag Field
This field applies to print requests only.
It consists of a flag byte
that determines whether PBS truncates lines that exceed the width of
the request's form, and corresponds to the /[NO]TRUNCATE file
qualifier of the PRINT command.
If the flag byte is nonzero, PBS truncates lines.

If the flag byte is

o or you omit this field, PBS does not truncate lines.
The format of the /[NO]TRUNCATE Flag field is:
Byte

Specification

CHR$(135%)

CHR$(N%), where N% is the flag byte.
0%

No truncate (the default)

Truncate

9-24

Values are:

Chapter 10
System programming Hints

This chapter provides information for designing a BASIC-PLUS program
to run by a CCL command.
It also describes how the monitor handles
the SLEEP and conditional SLEEP statements.

Designing a Program to Run by a ceL Command
Many RSTS/E system programs can be run by special commands called
Concise Command Language (eCL) commands.
For example, the standard
CCL command PIP runs the PIP system program.
CCL commands let you run programs using commands similar to keyboard
monitor commands. When you enter a CCL command, the monitor loads and
runs a program from a predefined account and device.
CCL commands can run user programs as well as system programs. The
system manager can tailor CCL commands to a system by using the DCL
DEFINE/COMMAND command (see the RSTS/E System Manager's Guide).
CCL commands do not have permanent definitions.
Instead, all CCL
commands (including those that run DIGITAL programs) must be either
installed at system start-up or defined during timesharing with the
DEFINE/COMMAND command.
See the RSTS/E System Manager's Guide for
more information.
The rest of this section describes the CCL facility in detail and
explains how it interacts with the BASIC-PLUS run-time system. with
this information, you can design BASIC-PLUS programs to run by eeL
commands.

System Processing of CCL Commands
After you enter a line at your terminal, the run-time system passes
the line you entered to the ceL parser in the monitor to see if it is
10-1

System programming Hints
a valid CCL command.
If the line is not a valid CCL command, the
monitor returns control to the run-time system.
If the line is a
valid eCL command, the monitor:
1.

Sets up the job's core common area.

Extracts the CCL's parameter word from predefined CCL data,
which resides in a linked list of monitor buffers.
(The
BASIC-PLUS run-time system uses the parameter word as the
line number where execution is to start; other run-time
systems may interpret it differently.)

Sets up the program to run.

Transfers control to the run-time system associated with the
program.
The run-time system runs the program.

After the program is finished running, the system returns control to
the keyboard monitor that you are working in.

CCL Precedence Rules
In BASIC-PLUS, the system processes CCL commands before BASIC-PLUS
keyboard monitor commands and immediate mode statements, but after
line-numbered statements.
BASIC-PLUS scans terminal input at command
level and applies the following rules:
o

If the line begins with numbers, the system passes the line
to the BASIC-PLUS syntax analyzer for processing and storage
as intermediate code.

If the line begins with nonnumeric characters, the system
passes the line to the CCL command parser for processing and
validation.

If the line does not contain a valid ·eCL command, the CCL
parser passes it back to the BASIC-PLUS syntax analyzer for
immediate mode execution.

If the line does not contain a valid command or immediate
mode statement, BASIC-PLUS generates an error message.

Thus, a CCL command that duplicates either a BASIC-PLUS command or
immediate mode statement overrides that command or statement.
Except for DCL, other standard RSTS/E run-time systems follow the same
precedence rules for CCL commands as BASIC-PLUS.
Like BASIC-PLUS,
these run-time systems process CCL commands before keyboard monitor
commands.
On the other hand, DCL processes DCL keyboard monitor
10-2

System Programming Hints
commands before CCL commands unless you use the CCL prefix.
RSTS/E System User's Guide for more information.

See the

Effect of CCLs on Your Job Area
Some CCL commands perform the same functions as BASIC-PLUS keyboard
monitor commands.
Unlike keyboard monitor commands, however, CCL
commands destroy the current contents of your job area.
For example, the BASIC-PLUS CATALOG command and the CCL DIR command
both display directory listings. When you enter the CATALOG command,
BASIC-PLUS calls monitor code to produce the listing.
Your job space
is not affected.
The CCL DIR command, however, loads and runs the
DIRECT program from the system library.
DIRECT overwrites your job
space.

eeL Syntax and Switches
The following lines show the proper syntax for a valid CCL command
called COMMAND that can be abbreviated COM.
In these lines,
<anything> represents characters that the CCL parser does not process.
COM[M[A[N[D]])][<switch(es»][/<anything>]
COM[M[A[N[D]]]][<switch(es»][<space><anything>]
The CCL command parser passes one of the following forms of the parsed
command in the job core common area:
COMMAND[/<anything>]
COMMAND[<space><anything>]
Note that the ceL parser always expands each command to its fully
defined form.
The command line that the run-time system passes to the parser can
contain two switches (both optional) in the following format:
[<space>]/SI[Z[E]]:[+][#]<digits>[.]
where:
/SI

denotes the size in K words the program must expand to.
terminates the /SIZE switch.

10-3

System Programming Hints
+

designates an increment in size over the program's
usual size. Without the plus sign, the digits value is
the total size in K words that the program should
expand to.

indicates the digits value is given in octal.
default is decimal.

is the value for size, in K words. Size can be neither
less than I nor greater than 32 (decimal).

The

explicitly indicates a decimal value for digits.
[<space>]/DET[A[C[H]]]
where:
IDET

indicates that the program is to be run detached from
the job's console terminal.

The parser strips the optional switches from the command line. The
monitor extracts these switches and sets status bits for the run-time
system, but takes no action on the switches. The run-time system
optionally interprets and processes the status information.
These CCL switches can occur in any order; however, they must
immediately follow the CCL command. If the parser detects a syntax
error, it generates either the error ?Illegal switch usage (ERR=67) or
the error ?Illegal number (ERR=52). If the command line exceeds 127
characters (the maximum size of core common), the parser generates the
error ?Line too long (ERR=47).
Because the parser searches the typed line for special switches, you
should not define program switches that conflict with either lSI or
IDET.
If such switches are defined, special instructions are required
for their use. For example, to have a lSI or IDET switch passed to a
program, it must be preceded in the command line by text that does not
begin with a slash (I) character (for example, SY: or another device
specification).

CCL Command Line Parsing

When the CCL parser receives a command string, it:
1.

Translates the string.

Checks the string for a valid CCL command.

Writes the fully expanded CCL command into core common, and
makes sure that it is delimited by a space.
10-4

System Programming Hints
4.

Checks the remaining string for both of the valid CCL
switches.

Writes the remaining line (except for CCL switches) to core
common.

Sets up the CCL program to run.

Sets a flag from data in the CCL command definition block.

Passes control back to the program's run-time system, which,
in turn, runs the program (at the appropriate line number for
BASIC-PLUS programs).

Run-time system actions are independent of what the CCL parser does.
To translate the command line, the parser performs several steps:

For all characters in the input string, it discards
end-of-line and excess (NUL and RUBOUT) characters, and
discards leading and trailing space and tab characters.

For the remaining characters not inside quotation marks, the
parser changes all tab characters to spaces, reduces adjacent
spaces to a single space, discards all control characters,
and converts lowercase lettE~rs (CHR$(97) to CHR$(122»
to
uppercase letters (CHR$(65) to CHR$(90».

The parser does not alter characters inside quotation marks.

Next, the parser scans the leftmost part of the translated command
line for a potential CCL command.
The scan ends on the first
occurrence of one of the following:
o

An end-of-line

A slash (/)

A space

Note that if the command begins with a nonalphanumeric character (that
is, if the command is a single-character CCL), the scan ends on the
second character.
The parser compares the scanned string with each entry in the list of
valid CCL commands.
If the scanned string matches a defined CCL
command at its abbreviation point or matches any part of a defined CCL
command beyond the abbreviation point, the parser writes the fully
expanded CCL command to the job core common area.
If no match is
found, the parser writes the translated command line to core common
and returns control to the run-time system.

10-5

System Programming Hints
Because of the translation, spaces typed within a ceL command are
critical. A space typed within the CCL command ends the scan of the
command line. For example, if the CCL command COMMAND (with
abbreviation COM) is typed COM<space>MAND, the parser interprets the
COM as a valid abbreviation for COMMAND and handles <space>MAND as
part of the line to pass to the program. Likewise, the typed command
line CO<space>MMAND is not matched with a command whose minimum
abbreviation is COM.
Note that in the case of a single-character, nonalphanumeric CCL, you
do not need to type the delimiter (such as a space) normally required
to set off the command. For example, $ is permanently defined (by the
monitor) as the CCL to invoke a DCL command, so a command typed as
$COPY is interpreted and passed in core common as $ COPY.
Because of the way the parser interprets CCL commands, the system
manager should make sure that similar commands are defined in the
correct order. For example, MACRO must be defined before MAC during
system start-up. See the RSTS/E System Manager's Guide for more
information.
When the parser determines that the translated string contains a valid
CCL command, it starts moving the CCL command string to the job's core
common area. Any errors found later by the parser result in
unpredictable contents in the core common area.
If the rest of the translated string begins with either a slash or a
space followed by a slash, the parser checks for a valid CCL switch.
If it finds a valid CCL switch, the parser checks further for another
adjacent switch. Duplication of a switch generates the error ?Illegal
switch usage (ERR=67). Any CCL switches found are removed from the
command line. The parser writes the remaining part of the command
line to core common. If any error is found in the CCL command or
switches, the parser stops processing the command line and returns
control to the run-time system with an error indication.
After processing the command line, the monitor sets up the related CCL
program to run. The monitor passes a flag from the CCL command
definition to the run-time system. The monitor passes the fully
defined CCL command and the remaining string in the core common area.

BASIC-PLUS Action
The BASIC-PLUS run-time system receives control from the CCL parser at
one of two points. If the command is not a valid CCL command or if it
generated an error, control is returned inline. When the monitor
fails to validate a CCL command, BASIC-PLUS processes the translated
string for execution in immediate mode. If the parser returns an
error, BASIC-PLUS prints the error message and the Ready prompt. When
the monitor does valldate a CCL command, it passes control to the
10-6

System Programming Hints
run-time system to run a BASIC-PLUS program.

BASIC-PLUS:

Sets the S'l'ATUS variable.

2•

Checks the line number at which the program is to be entered.

3•

Checks whether the program is to be detached.

Based on the results of these actions, BASIC-PLUS runs the program.
Table 10-1 gives the rules that BASIC-PLUS uses when setting the
STATUS variable.
Table 10-1:

STATUS Variable After

eeL Entry

+- - - - - -+- - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Bi t I
Test
Meaning
I
+- - - - - -+- - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
0-7

(STATUS AND 255%)

If bit 13 is 0, this byte must be O.
If bit 13 is 1, this byte is the size
value n (in decimal) passed in the
/SIZE:n switch or is -n to indicate
that the size value was passed in the
/SIZE:+n switch (the plus character
preceded the size value). (To
determine whether the size value is
negative, check the most significant
bit by the (STATUS AND 128%) test.)
Reserved for future use.

8-12
13

(STATUS AND 8192%)

If the /SIZE:n switch was specified,
this bit is 1. Otherwise, it is O.

(STATUS AND 16384%)

If the /DET switch was specified,
this bit is 1. Otherwise, it is O.

(STATUS < 0%)

This bit is always 1 (the value of
STATUS is always negative for a CCL
entry) .
+- - - - - - ..... - - - - -" - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
15

If BASIC-PLUS finds that the line number is nonzero, it checks the
flag passed by the monitor.
BASIC-PLUS permanently drops temporary
privileges unless the CCL definition indicates that privileges are to
be kept for this program.
This action prevents a job from bypassing a
program's protection mechanism by entering a program at a line other
than the lowest numbered one.
If the /DET switch was specified,
BASIC-PLUS detaches the job and closes all channels on which the
10-7

System Programming Hints
console terminal is open.
BASIC-PLUS takes no action for the /SIZE:n switch. For run-time
systems other than BASIC-PLUS, this switch is a signal that an
increase in job size is required. Other run-time systems mqy not
perform dynamic memory expansion during the execution of a program, as
BASIC-PLUS does, and may require the switch to expand job size.

Conventions Used in BASIC-PLUS Programs
As a convention, BASIC-PLUS programs supplied by DIGITAL and invoked
by standard CCL commands reserve lines 30000 to 30999 for CCL
routines. These routines extract the parsed command line passed in
core common, check for errors, and transfer control to other routines
in the program. This convention allows programs to determine that
they were entered by means of CCL. The programs execute the SYS call
to get the core common string and scan the string for the specific eCL
command expanded by the CCL parser. This action also allows a single
program to be run by one of several CCL commands. After determining
which CCL command caused it to run, the program can transfer control
to routines to process the rest of the command line.

SLEEP and Conditional SLEEP Statements
The BASIC-PLUS SLEEP statement lets a running program stop its own
execution for a specified time period. The statement has the format:
SLEEP <expression>
The <expression> indicates the number of seconds to stop execution.
The system suspends the job that is controlling the program, and
execution stops until the system "awakens" the job at the end of the
specified time period. See the BASIC-PLUS Language Manual for more
information.
Although the program controls the sleep state by specifying the time
period for the system to stop execution, certain conditions cause the
system to awaken the job before the time is up:
o

A user enters a delimiter (RETURN, LINE FEED, FORM FEED, or
ESCAPE) at:
Any terminal opened by the job.
Any terminal allocated to the job if the job also has a
keyboard open on a nonzero channel.

10-8

System Programming Hints
o

A dial-up :Line that is allocated or opened by the job gets
hung up.

The system manager disables logins (that is, sets the number
of logins to 1).

A state change occurs on a pseudo keyboard opened by the job.
This condition can occur when the opened pseudo keyboard has
output for the controlling job or has entered an input wait
state.
See the section "Pseudo Keyboards" in Chapter 4 for
more information.

The job has declared itself a receiver and a message is
queued for it through the Send/Receive SYS calls (see Chapter
8).

The job has a DMC/DMR (XM:) device open and the device driver
receives a message (see Chapter 6).

The system date or time is changed.

You can specify a conditional SLEEP by setting the sign bit in the
SLEEP statement argument.
To set the sign bit, specify the SLEEP
statement argument as:
SLEEP <expression> + 32767% + 1%
In a conditional SLEEP, the monitor checks for all conditions except
disabled logins before executing the SLEEP statement.
The monitor
does not execute the SLEEP statement if the job:
o

Has pending terminal input

Has a dial-up line allocated but not in use

Has a message queued through send/receive

Has data pending on the DMC/DMR device (XM:)

Has a pseudo keyboard open that has pending output or is
waiting for input

If any conditions (other than NO LOGINS) that cause a job to to be
awakened is in f~ffect when the conditional sleep is issued, the sleep
does not take place. A "normal" sleep does n6t check these conditions
before sleeping, so the job is awakened only when one of these
conditions occurs again, or when the timer expires.

10-9

Chapter 11
Ethernet Operations

This chapter presents an overview of Ethernet and describes how to use
its local area networking features on RSTS/E with BASIC-PLUS or
BASIC-PLUS-2. Some special functions work only through MACRO-II
programs. You can use Ethernet without these functions, but they can
greatly increase an application's flexibility and its ability to
monitor the network. For descriptions of these special functions, see
the RSTS/E System Directives Manual, under the .SPEC listing for
Ethernet.

Ethernet Concepts
Ethernet consists of a single coaxial cable that connects computers,
terminals, and other devices within a limited geographic area. All
nodes on an Ethernet have equal access to the interconnecting cable.
Ethernet's access method is called "Carrier-Sense, Multiple-Access
with Collision Detect" (CSMA/CD). These terms mean:
o

Carrier Sense -- Each node checks the cable before it sends a
message or data packet. If another node is transmitting, the
first node delays transmission until the cable is no longer
busy.

Multiple Access -- All nodes are on the same coaxial cable,
and all the nodes can hear all message or data packets sent
on the Ethernet. The intended recipient nodes recognize
incoming packets by addresses which are specified within the
packets.

Collision Detect -- If two or more nodes send packets at the
same time, their signals collide. Each node hears such
collisions, then waits before sending a packet again.

June 1987

11-1

Ethernet Operations
TO use Ethernet, you only need four BASIC statements:
OPEN, CLOSE,
GET, and PUT.
See the section Commands for Ethernet for full
descriptions of these functions.
You may also wish to use the special
Ethernet .SPEC functions that have been added to MACRO-II.
See the
RSTS/E System Directives Manual for full descriptions.

The Conversation Analogy
In many ways, Ethernet resembles ordinary conversation at a social
gathering.
To be polite, you do not speak while someone else is
talking; you listen before you speak.
This resembles the
carrier-sense feature of Ethernet; each node makes sure the cable is
clear before sending any information.
In a conversation, anyone may begin to talk once he or she determines
that no one else is talking.
(Compare this to a lecture, where only
one person talks.) This equal right to speak resembles the
multiple-access feature of Ethernet; many nodes can use the same
cable.
If two people start to talk at the same time, they note the fact and
stop talking (that is, each listens while talking and stops if
interfering with someone else).
This resembles the collision-detect
feature of Ethernet; if two nodes start transmitting at the same time,
both nodes detect this and stop.
When the two people stop talking, they wait and start over again.
On
Ethernet, this situation is called backoff and retransmission; a delay
before retransmission will eventually clear the collision situation.
There is another useful analogy between Ethernet and a social event.
When someone at the party talks, everyone (usually) can hear what is
being said.
Some of what is said is intended for everyone, some is
intended for a smaller group (for example, everyone over 21), and some
is intended for an individual.
Likewise, nodes on an Ethernet can
hear every message.
Some messages are intended for all nodes
(broadcast address), some are intended for a subset (multicast
address), and some are intended for individual stations (physical
address).

Ethernet and DECnet/E
DECnet/E is a DIGITAL product using the Ethernet data link layer and
Ethernet physical link layer to communicate.
It uses the Digital
Network Architecture for network control.
In order to increase the
11-2

June 1987

Ethernet Operations
flexibility of Ethernet on RSTS/E, DIGITAL has provided a direct
interface to the Ethernet data link layer for RSTS/E users. This
interface resembles the interface provided for the DMC/DMR
communications devices, and can be programm~d with or without DECnet/E
on the system.
If DECnet/E is on the system, you should start it before any other
jobs are allowed to perform OPENs to the Ethernet devices.

Bthernet Terms
To make Ethernet easier to use, you should become familiar with these
terms:
0

physical layer

channel, controller, and data link layer

protocol type and portal

counters

physical addressing and hardware addressing

multicast addressing

Physical Layer
Digital Equipment Corporation, Intel Corporation, and Xerox
Corporation collaborated in producing the Ethernet specification to
develop a variety of local area network products. DIGITAL's
implementation of the Ethernet specification consists of the lowest
two levels of the overall DNA specification -- the physical layer and
the data link layer.
The physical layer of Ethernet is a bus in the shape of a branching
tree. The medium is a shielded coaxial cable using
Manchester-encoded, digital signaling. Each Ethernet can support up
to 1023 nodes. The maximum length of the cable is 2.8 kilometers
( 1 .74 mi 1 e s ) .

June 1987

11-3

Ethernet Operations
Channel, Controller, and Data Link Layer
Each Ethernet has one channel. The channel is made up of the physical
cable connecting the nodes, together with the nodes' controllers. A
controller is a RSTS/E device connected directly to the cable. Each
node has one or two controllers connecting to the Ethernet. The
controllers and their device drivers make up the Ethernet data link
layer. Controllers come in three types:
o

DELUA, a UNIBUS controller (called UNA in DECnet, XE:
RSTS/E)

DEUNA, an older UNIBUS controller (called UNA in DECnet, XE:
in RSTS/E)

DEQNA, a Q-BuS controller (called QNA in DECnet, XH:
RSTS/E)

Protocol Type and Portal
All incoming Ethernet messages have a protocol type, an identifying
string near the beginning, that identifies the proper portal to
receive the message (for instance, the DECnet/E portal). The portal
is the logical access from the user software to the channel.

Counters
The Ethernet controller keeps records of link performance called the
counters. For example, the counters record the number of times the
controller had to throwaway a packet because it ran out of buffer
space. Use the counters to find problems and fine-tune the system.
For example, if the counters show the controller throws away packets
too often, you should give the controller more buffers, or read from
it more often.
There are two kinds of counters, circuit counters and line counters.
A circuit counter monitors a single portal. A line counter monitors
the whole channel. You cannot work with counters through BASIC
programs; you must use MACRO-II.

11-4

June 1987

Ethernet Operations
Physical Addressing
You address nodes on Ethernet lines by their Ethernet physical
addresses.
Because the Ethernet is a multiaccess broadcast device,
all nodes connected to an Ethernet line are equally accessible.
Therefore, each node on an Ethernet is assigned a unique Ethernet
physical address which is set by the controller software at the node,
or is set to a default value at the factory.
This default physical
address is the hardware address.
Xerox Corporation assigns a block of
hardware addresses for DIGITAL to use with its DEUNA, DELUA, and DEQNA
Ethernet controllers.
One address from the assigned block is
permanently associated with each controller in read only memory.
Ethernet addresses are represented by six pairs of hexadecimal numbers
separated by hyphens, AA-Ol-23-45-D7-0C for example.
DECnet/E on Ethernet
If you have DECnet/E, the controller software sets the physical address
to be within an assigned block of addresses when the node is powered up.
The controller constructs the physical address by appending a
hexadecimal number to the constant hexadecimal number AA-OO-04-00.
The
controller software uses the node address (area-number.node-number) to
construct the last two pairs of hexadecimal numbers it appends to the
constant, D7-0C for example.
In this case, the physical address is
~~-OO-04-00-D7-0C.

NOTE
The system manager must start DECnet/E before any user
portals open.
Once a portal opens, no users can
modify the controller's characteristics.

Multicast Addressing
Use multicast address to send messages to more than one node.
multicast address can be:

A multicast group address, which is an address assigned to
any number of nodes.
Use the group address to send a message
to all nodes in the group with a single transmission.

The broadcast address, which is a single address, the
hexadecimal number FF-FF-FF-FF-FF-FF.
Use a broadcast
address to transmit a message to all nodes on a given
Ethernet.

June 1987

11-5

Ethernet Operations
NOTE
The use of the broadcast address on Ethernet
severely burdens the network resources.
DIGITAL does not recommend using a broadcast
address on a heavily-populated Ethernet.

Ethernet Addresses
Certain Ethernet addresses and ranges of addresses have specialized
functions.
DIGITAL physical addresses are in the range:
AA-OO-OO-OO-OO-OO through AA-OO-04-FF-FF-FF
Multicast addresses assigned for use in cross-company communications
are:
Value
FF-FF-FF-FF-FF-FF
CF-OO-OO-OO-OO-OO

Meaning
Broadcast
Loopback assistance

DIGITAL multicast addresses assigned to be received by other DIGITAL
nodes on the same Ethernet are:
Value
AB-OO-OO-OI-OO-OO
AB-OO-OO-02-00-00
AB-OO-OO-03-00-00
AB-OO-OO-04-00-00
AB-OO-OO-05-00-00
through
AB-OO-03-FF-FF-FF
AB-OO-04-00-00-00
through
AB-OO-04-FF-FF-FF

Meaning
Dump/load assistance
Remote console
All phase IV routers
All phase IV end nodes
Reserved for future use
For use by DIGITAL customers for their
own applications

11-6

June 1987

Ethernet Operations
Commands for Ethernet
You can use the following BASIC statements on the Ethernet:
o

OPEN

GET

PUT

In addition, only the Ethernet controllers use the following special
functions:
0

Set New Physical Address

Enable Multicast Addresses

Get Circuit Counters

Get Line Counters

Transfer Circuit Counters

Transfer Line Counters

Programs written in BASIC-PLUS and BASIC-PLUS-2 can use the OPEN,
CLOSE, GET, and PUT statements to operate the Ethernet interface.
To
use the special functions, you must use MACRO-II programs.
See the
RSTS/E System Directives Manual, the .SPEC listings for Ethernet.

June 1987

11-7

~rnet

~ple

Operations

Open statement:

)EN "XEO:/PO:1600" AS FILE II, CLUSTERSIZE 4, RECORDSIZE 512%+6%+6%+2%+2%
o

XEO specifies Ethernet controller 0

/PO:1600 specifies protocol type 1600.
modifier.

FILE #1 specifies RSTS/E channell.

CLUSTERSIZE 4 specifies four system receive buffers. You
cannot specify more than 127. DIGITAL does not recommend
specifying more than 10.

RECORDSIZE 512%+6%+6%+2%+2% specifies 512 bytes for the size
of the I/O buffer, with 6 bytes each for the source and
destination addresses, 2 bytes each for the portal protocol
type and the Ethernet length field.

MODE 0% is the default and so was not written in the example.
0% defines the portal as using a "padded" protocol.
Use MODE
128% for an "unpadded" protocol.
(See below for descriptions
of padded and unpadded protocols.)

This is the position

format of the OPEN statement for Ethernet is:

N "XEa:/PO:b" AS FILE Ic, CLUSTERSIZE d, RECORDSIZE e%+6%+6%+2%+2%, MODE f%
re a, b, c, d, e, and f are the variables described in the
ceding example.
the OPEN statement to open a portal on a given Ethernet
troller.
The OPEN statement also lets you allocate receive buffers
set the portal protocol type.
er the OPEN statement, the portal receives incoming messages for
specified protocol type at the physical address of the controller.

11-8

June 1987

Ethernet Operations
NOTE
If you intend to use DECnet/E, be sure you start
DECnet/E before you issue any OPEN statements for
users.
Since DECnet/E has to modify the node's
physical address before it can start, it must be the
first portal opened on a channel.
Possible Errors
Meaning

ERR Value

?NO BUFFER SPACE AVAILABLE
There are not enough buffers available in the small
buffer pool to create the portal's data structures,
or the extended buffer pool (XBUF) is too small or
fragmented to allocate the requested number of
system receive buffers.

?ACCOUNT OR DEVICE IN USE
The protocol type requested is already open on the
channel.

?DEVICE HUNG OR WRITELOCKED
The controller is disabled or inoperative.

Note the following restrictions:
o

Each portal supports only one protocol type.
On OPEN, the
protocol for the portal is defined.
You can enable multiple
protocol types by opening several different portals on
different RSTS/E channels.

You cannot open the same protocol type on two portals on the
same channel.

The Ethernet controller physical address is not available to
anyone above the data link layer.

June 1987

11-9

Ethernet Operations
Padded and Unpadded Protocols
Protocols may be padded or unpadded.
When you issue an OPEN
statement, you must decide whether to do the following send and
receive operations in padded or unpadded mode.
Specify MODE 0% for a
padded protocol, MODE 128% for unpadded.
Padded is the default.
It
is easier tD use but takes up more space.
In the padded mode, the data link layer automatically fills in the
length field of the receive buffer and makes sure the message is long
enough to be put on Ethernet, using the length field of the packet.
It also uses the length field of incoming packets.
In the unpadded
mode, the data link layer leaves the length field blank and leaves it
to you to make sure you have the minimum length.

System Receive Buffers
Since a user job may not be in memory when a message for it arrives on
the Ethernet, RSTS/E lets you allocate system receive buffers to hold
messages until the job can pick them up (using GET statements).
Allocate these system receive buffers using the CLUSTERSIZE parameter
on the OPEN statement.
under the current version of RSTS/E, each system receive buffer is 632
bytes long.
Every message received for the portal uses at least one
buffer, and long messages may use as many as three of these system
receive buffers, depending on their length.
RSTS/E keeps careful count of available system receive buffers for
each portal.
When a message comes in for a portal and there are not
enough system buffers available to the portal, RSTS/E discards the
message.
When the user next issues a GET command, it returns ERROR 13
(?Data Error on Device), meaning that at least one message was dropped
by RSTS/E due to a shortage of system receive buffers.
On a normal GET command, the system copies a message (of one or more
system receive buffers) into the buffers in the user program.
Once
this copy is complete, the system receive buffers are once again
available to receive incoming messages.
DIGITAL does not recommend allocating more than 10 system receive
buffers to a portal.
DIGITAL also recommends that user portals do not
routinely handle messages which are larger than can fit into one
system receive buffer.

11-10

June 1987

Ethernet Operations
CLOSE
Example CLOSE statement:
CLOSE #1%
a

#1% specifies the device open on RSTS/E channel 1 as the
device with the portal to close.
The format to close any
channel n is:
CLOSE #n%

Use the CLOSE statement to close the portal on a given Ethernet
controller.
RSTS/E closes the portal on the data link side and frees
all the system resources reserved for it for other system processes.
The CLOSE statement requires no parameters and returns no errors.

GET
Example GET statement:
GET #1% &, RECORD 0%
o

#1% & specifies the device on RSTS/E channel 1 as the device
with the portal to read from.

RECORD 0%
stalled.
operation
the error

specifies that the DET operation should not be
If there are new messages waiting, the GET
returns the first one.
If not, the GET fails with
message ERR 5 (?Can't find file or account).

Users can also use RECORD 8192% to specify a stall for the
GET.
With a stall, the GET returns the first message, if
there are any messages waiting.
Otherwise, it stalls the job
in an XE state, waiting for an Ethernet message addressed to
the portal.
Users can interrupt this stalled GET with
CTRL/C, in case nothing comes over the Ethernet.
The format for any channel a, stalled or not according to the value of
b, is:
GET #a% &, RECORD b%

June 1987

11-11

Ethernet Operations
Use the GET statement to read data from a portal previously opened on
the channel.
If the portal was OPENed in padded mode, then the first
16 bytes are header information, including the length field.
If the
portal was OPENed in unpadded mode, only the first 14 bytes are header
information, followed immediately by message data.
The amount of data read depends on the device and the size of the
buffer area, as defined in the XRB.
The number of bytes transferred
is always less than or equal to the buffer size~
The actual number of
bytes read is returned in the XRB when the directive is complete.
The receive buffer, which must start on a word boundary, contains the
following fields upon completion of a GET:

+-----------------------------+
I
I

DESTINATION ADDRESS FIELD

I
I
I

6 bytes

+-----------------------------+
I

SOURCE ADDRESS FIELD

I
I

I
6 bytes

+-----------------------------+
I
PROTOCOL TYPE FIELD
I
I

2 bytes

+-----------------------------+
LENGTH FIELD
«--- Unless you specify a
2 bytes

"no padding" portal on
OPEN)

+-----------------------------+
DATA
46 - 1500 bytes

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

11-12

June 1987

Ethernet Operations
Possible Errors
Meaning

ERR Value

?MAGTAPE RECORD LENGTH ERROR
Message truncated to fit.

?DATA ERROR ON DEVICE
Lost packets (user buffer unavailable).

?CAN'T FIND FILE OR ACCOUNT
For no stall GETs, when no messages are pending.

PUT
Example PUT statement:
PUT #1%, COUNT 6%+6%+2%+2%+LEN(D$)
o

#1% sp«~cifies the device on RSTS/E channel 1 as the device
with the portal to write to.

COUNT 6%+6%+2%+2%+LEN(D$) specifies 6 bytes each for the
source and destination addresses, 2 bytes each for the portal
protocol type and the Ethernet length field, and LEN(D$) for
the length of the user string to send (that is, the data to
be sent is in buffer 0$).

The format for any channel a, field length b, is:
PUT #a%, COUNT 6%+6%+2%+2%+b
Use the PUT statement to send information through the data link layer
to another node.
In padded mode, the data link layer fills in the
length bytes with the length of the data sent.
The data link layer
always makes sure the transmit packet is between 60 and 1514 bytes
long, and will fill in the source address and protocol type, using the
type passed in the OPEN statement.

June 1987

11-13

Ethernet Operations
The PUT statement expects you to PUT a buffer in the following format,
providing for space for the following information in addition to the
actual data to be transferred:

+-----------------------------+
DESTINATION ADDRESS FIELD
6 bytes
Specified by user

+-----------------------------+
SOURCE ADDRESS FIELD

(------ Specifies the address
of the machine that
will receive the message
(------ Specifies the address
of the originating
node (you)

6 bytes
Filled in by the
data link layer
(RESERVED)

+-----------------------------+
PROTOCOL TYPE
(------ Specifies the portal
that you expect will
receive the message.
Specified during OPEN

2 bytes
Filled in by the
data link layer
(RESERVED)

+-----------------------------+
LENGTH
2 bytes
Filled in by the
data link layer

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

(------ Specifies the length of
the message.
This field is present only
for padded protocols.

DATA

1
1

46 - 1500 bytes

(------

Contains the
message's data

+-----------------------------+
Note the following requirements and restrictions:
o

The total buffer size must be between 60 and 1514 bytes in
length

The buffer must start on a word boundary, but can contain an
even or odd number of bytes

The user specifies the destination address field

11-14

June 1987

Ethernet Operations
o

The data link layer always specifies the source address
field, which is reserved for DIGITAL use

The data link layer also specifies the protocol type, which
is reserved for DIGITAL use

If the protocol is a padded protocol, then the data link
layer fills in the length field as calculated from the
information passed in the XRBC

Possible Errors
Meaning

ERR Value

?ILLEGAL BYTE COUNT FOR I/O
The count is not between 60 and 1514 bytes, or
starts on an odd address.

?DATA ERROR ON DEVICE
The device is disabled or inoperative.

?DEVICE HUNG OR WRITE LOCKED

The controller is disabled or inoperative.

Special Ethernet Functions
MACRO-II provides the following functions to give greater flexibility
in using and monitoring the Ethernet.
These functions are not
available in BASIC.
See the RSTS/E System Directives Manual under
.SPECs for Ethernet for more information.

Set New Physical Address
Use the Set New Physical Address function to change the physical
address of the Ethernet controller.
It is a .SPEC function and
requires too many parameters to call using BASIC-PLUS or BASIC-PLUS-2.
Use MACRO-II.

June 1987

11-15

Ethernet Operations
Enable Multicast Addresses
Use the Enable Multicast Addresses function to let the portal receive
multicast messages. This is a device dependent .SPEC function. The
XRB contains pointers identifying the User Multicast Address Buffer.
RSTS/E allows a maximum of five multicast addresses per portal on an
Ethernet channel.
This is a .SPEC function and requires too many parameters to call
using BASIC-PLUS or BASIC-PLUS-2. Use MACRO-II.

Get Circuit Counters and Get Line Counters
Use the Get Counters functions to bring the counters up to date. The
controllers maintain counters in several places. You must tell the
data link layer when you want to collect them. The controllers update
line or circuit counters only when you issue the call.
These are .SPEC functions and require too many parameters to call
using BASIC-PLUS or BASIC-PLUS-2. Use MACRO-II.

Transfer Circuit Counters and Transfer Line Counters
Use the Transfer Counter functions to read the counter information
from the data link layer to the user space once you have updated the
information with the Get Counters function.
These are .SPEC functions and require too many parameters to call
using BASIC-PLUS or BASIC-PLUS-2. Use MACRO-II.

11-16

June 1987

Appendixes

Appendix A
Magnetic Tape Label Formats

RSTS/E supports two magnetic tape file label formats:
DOS and ANSI.
This appendix discusses DOS and ANSI label formats and describes how
RSTS/E handles tapes written with these labels.
Note that the ANSI
label format described in this appendix refers to the RSTS/E
implementation of the American National Standard X3.27-1978 (magnetic
tape labels and file structure for information interchange).
This appendix uses the following terms:
Record

A physical record on a magnetic tape.
It is the unit of
data transferred in a magnetic tape drive operation.
Each
record on a magnetic tape is separated from the next by a
gap or blank space.

Tape Mark

A special kind of record that magnetic tape drives can
write and detect. A tape mark contains no data.
Instead,
it separates other kinds of records.

DOS Magnetic Tape Format
This section describes the labels and data records on a magnetic tape
in DOS format as well as the order in which these items are placed on
the tape.
For purposes of explanation, assume that the magnetic tape
under discussion has three files, each containing ten data records.
The first part of the magnetic tape is a physical beginning-of-tape
(BOT), which is a reflective (metallic) marker.
Right after this
marker is the first tape label record followed, in this case, by ten
data records and a tape mark.
All magnetic tape files begin with a tape label record, contain any
number of data records (the default size is 512 bytes per record), and
end with a tape mark.
DOS files can contain zero data records, but a
label record and tape mark are always required for each file.

A-I

Magnetic Tape Label Formats
Figure A-I shows the layout of a DOS magnetic tape file.

L
A
B

foE-- N data records ~ 0

L
MK-00039-01

Figure A-I:

DOS-Labeled Magnetic Tape File

Figure A-2 shows the layout of a DOS magnetic tape that contains three
files of ten data records apiece.
OlE

BOT

L
A
B
E
L

1st file

10 data records

T
M

OlE

L
A
B
E
L

2nd file

10 data records

T
M

..,

3rd file

L
A
B
E
L

10 data records

.. _t

Logical End of Tape (LEOT)

.........

T
M

INACCESSIBLE
INFORMATION

PHYSICAL
EOT
MK-00040·01

Figure A-2:

DOS Magnetic Tape Consisting of 3 Files of 10 Data
Records Apiece

After the first file, another label record begins the second file.
This label record is also followed by ten data records and a tape
mark.
This second file is immediately followed by the third and last
file, which consists of a label record, ten data records, and a tape
mark.
In addition, since the third file on this tape is also the last
one, two more tape marks follow.
The magnetic tape has three tape
marks at this point, signifying a logical end-of-tape (LEOT).
After the logical end-of-tape is written on the magnetic tape, it can
be written over, but it cannot be read over.
Therefore, all
information beyond the logical end-of-tape is inaccessible.
If a magnetic tape contains no files,
beginning-of-tape marker.

three tape marks follow the

DOS Labels
The label record that specifies the beginning of a magnetic tape file
in DOS format is 14 bytes long.
Table A-I shows the information
contained in each of the label record bytes, numbered from 0 to 13.

A- 2

Magnetic Tape Label Formats
Table A-l:

DOS Label Record Bytes

+- - - - - _ .. - -+- - - - - - - _.' - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

Byte

contents

Data Format

+- - - - - _ .. - -+- - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I
I
I
I
I
I
I
I
I
I

0,1,2,3

File name

2 words in RADIX 50.

4,5

File type

1 word in RADIX 50.

Programmer number

1 byte in binary.

Project number

1 byte in binary.

Protection code

1 byte
in
(decimal)).

Unused

1 byte of zero.

10,11

Creation date

1 word in internal date format.

12,13

Unused

1 word of zero.

I
i

I
I

binary

(always

155

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

The project-programmer number is the account number of the current
user, unless some other number is specified in the OPEN statement.
If
DOS format magnt~tic tapes are to be ~nterchanged with DOS-II, RSX-ll
or VMS systems, a problem may occur because RSTS/E treats
project-programmer numbers as decimal values, and the others treat
these numbers (called UICs) as octal values.
To avoid interchange
problems, simply write all files on the tape with a [1,1]
project-programmer number, which is the same in both decimal and
octal.
For example:
100 OPEN "MTO:[l,l]ABC" FOR OUTPUT AS FILE 1%
Note that the project-programmer number is part of the file name
string.
There could be several files named ABC on a tape having
different project-programmer numbers associated with them.
Often a
failure to find a file on a magnetic tape is the result of forgetting
to specify the correct account number.
The protection code written by RSTS/E in the DOS label is always 155
decimal (233 octal), which is acceptable to DOS-II.
RSTS/E and DOS-II
use different protection code values.
RSTS/E ignores the value of the
protection code when reading the file.
This avoids interchange
conflicts with DOS-II.

A- 3

Magnetic Tape Label Formats
ANSI Magnetic Tape Format
This section describes the label and data records on a single or
multivolume magnetic tape with ANSI labels. Once again, for purposes
of explanation, assume that the magnetic tape under discussion has
three files, each containing ten data blocks.
The first part of the magnetic tape is a reflective physical
beginning-of-tape marker. The next item is a volume label (VOLl). (A
volume is a reel of magnetic tape. A volume, which may be part of a
volume set, can contain part of a file, a complete file, or more than
one file.)
The first RSTS/E file begins with two label records, called header
labels (HDRI and HDR2). These header labels are followed by a tape
mark. In this case, ten data records are written immediately after
the tape mark. The data records are followed, in order, by a tape
mark, two trailer label records (EOFI and EOF2 or EOVI and EOV2) , and
another tape mark.
When a file is created but no data blocks are written, all the above
label records and tape marks are still present. These labels and
end-of-file markers are always required for each file.
Figure A-3 shows the layout of an ANSI magnetic tape file.

L
A

E
L

TM
AA
P R
E K

TM
N data records

AA
PR
E K

L
A

E
L

ii
H

D
R

Figure A-3:

F
1

0
F
2

E
0
F

MK-00041-01

ANSI-Labeled Magnetic Tape File

Figure A-4 shows the layout of an ANSI magnetic tape that contains
three files of ten data records apiece.

A- 4

Magnetic Tape Label Formats

~~T
~1
L

---;

H H

ODD
L
R R
1

~fl" ~

records

Figure A-4:

Wft
E

o
F
1

E
0
F
2

3rd file

2nd file

H
0
R
1

H
0
R
2

T
M

10
data
records

T
M

10
data
records

T
M

INACCESSIBLE
INFORMATION

t i

ti ~

o 0

F
1

F
2

R
1

R
2

F
1

PHYSICAL
EOT

Logical End of Tape (LEOT)

MK..()()()42-01

ANSI Magnetic Tape Consisting of 3 Files of 10 Data
Records Apiece

After the first file, another set of two header records begins the
second file.
The second file is identical to the first one,
consisting of the two header labels, one tape mark, ten data records,
i another
tape mark, two trailer labels, and a final tape mark.
The third file on the tape is identical to the first and second, and
i~s followed by two more tape marks, signifying a logical end-of-tape
(LEOT) .
After the logical end-of-tape is written on the magnetic tape, it can
be written over, but it cannot be read over. Therefore, all
information beyond the logical end-of-tape is inaccessible.
A magnetic tape must contain at least one complete set of header and
trailer labels. When no file exists on the tape (as on an initialized
magnetic tape), a dummy file is present with a complete set of labels
and tape marks.

A!lSI Labels
Each ANSI label record written by RSTS/E is 80 bytes long.
Each label
can be identified by its first three characters: VOL (volume), HDR
(header), and EOF or EOV (end-of-file or end-of-volume). The fourth
character in each label further defines the sequence of the label
within its group.
For example, the first and second header labels are
HDRI and HDR2, respectively.

A- 5

Magnetic Tape Label Formats
Volume Label
This label identifies which volume (reel) of the magnetic tape is
being used.
Table A-2 shows the character position, field name, and
contents of each byte (character) in the volume label.
Table A-2:

Volume Label Format

+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+- ~ - - - - - - - - - - - - - - - - - - - - --+
I Character I
Field Name
I
Position I
and RSTS/E Usage
Contents
+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - --+
I
I
Label Identifier
1-3
I VOL
I

I
4
5-10

Label Number
Volume Identifier
(Volume label; one to six
alphanumerics, blank padded)

I 1

l I t o 6 alphanumeric
I characters

Accessibility
(RSTS/E writes a space)

Space means no
restrictions

12-37

Reserved

Spaces

38-51

Owner Identifier*
D%B4431JJJGGG

Contents of this field
used for volume
protection

52-79

Reserved

Spaces

Label Standard Version

I
I
I
I

+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - .,+
* The JJJ and GGG in the Owner Identification field represent the
user's project and programmer numbers, respectively. ~hey are
written as ASCII digits in decimal notation with leading zeros if
needed. The characters D%B4431 define the corporation
(D%=DIGITAL), the computer (B=PDPll), and a protection code, which
RSTS/E does not use.
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

A-6

Magnetic Tape Label Formats
Header 1 Label (HDR1)
Table A-3 shows the character position, field name, and contents of
each byte in the header 1 label.
Table .3:

Header 1 Label Format

+.- - - - - - ,. - - - -+- - - - - _ .. - - - - - - - - - - - - - - _., - - -.-+- - - - - - - - - - - - - - - - - - - - - - - - - - --+
I Character I
Field Name
I
and RSTS/E Usage
Contents
I
I Position I
+.- - - - - - - - - - -+- - - - - _ .. - - - - - - - - - - - - - - _ .. - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - --+

Label Number

5-21

File Identifier
(2 to 10 characters
FILNAM. or FILNAM.TYP;
blank filled)

22-27

File-set Identifier
(Volume Identifier from
the VOL1 label)

I
I HDR
I
I 1
I
I Any alphanumeric or
I special character in the
I ASCII code table.
I
I
I Volume ID of first volume
I in the volume set.
I

28-31

File Section Number

I
I

1-3

Label Identifier

Numeric characters; starts

I at 0001. Identifies a

section in the file.
Specified with the
/POSITION switch on the
OPEN statement. Defaults
I to 0001.
I
I
I
I

32-35

File Sequence Number

I
I Numeric characters; starts
I
I

at 0001. Identifies a file
on the volume.

I Not supported by RSTS/E;
I always 0001.
I

36-39

Generation Number (0001)

40-41

Generation Version ( 0 a )

42-47

Creation Date
Today's date in specified
format

(SPACE)YYDDD or
(SPACE)OOOOO if no date.

48-!53

Expiration Date
Today's date in specified
format

(SPACE)YYDDD or
(SPACE)OOOOO if expired.

Accessibility

Space

A-?

Not supported by RSTS/E;
always 00.

Magnetic Tape Label Formats
Table A-3:

Header 1 Label Format (Cont.)

+ - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - + - - - - ,. - - - - - - - - - - - - - - - ~ - - - - - - - +
I Character I
Field Name
I Position I
and RSTS/E Usage
contents
+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - ,. - - - - - - - - - - - - - - - - - - - - - --+

I
I
I
I
I
I
I
I

55 - 60
61-73

I
I Block Count
I
I System Code DECRSTS/E
I
I
I
I Reserved

000000
Name of system that
produced the vo1ume~
Padded by spaces.

74~80
Spaces
+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - '. - - - - - - - - - - - - - - - - - - - - - --+

Header 2 Label (HDR2)
Table A-4 shows the character position, field name, and contents of
each byte in the header 2 label.
Table A-4: Header 2 Label Format
+ - _ _ _ _ _ _ _ _ _ _+ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _+ _ _ _ _ _ _ _ _ _ _ '. _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

_______

I Character I
I Position I

Field Name
and RSTS/E Usage
Contents
+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - ,. - - - - - - - - - - - - - - - - - - - - - --+
1-3

Label Identifier

HDR

Label Number

Record Format
(U is the default)
(S is unsupported)

F = Fixed
D = Variable
S - Spanned
U - Undefined*

6-10

Block Length
(512 is the
default)

Numeric characters settable by
FILESIZE option.

11-15

Record Length

Numeric characters settable by
CLUSTERSIZE option.

A-a

Magnetic Tape Label
Table A-4:

Format~

Header 2 Label Format (Cont.)

of· - - .. - - - - - - - - + - .. - - .. - .. - - - - - - - - - .. .. - - - + - - - - .. - .. .. .. - - - - - - - .. - - - - - - .. - - .. .. .. - - - .. -..,

I Character I
Field Name
I.... _ _Position
I
and
.. .. _ _ .. .. .. _ .. + _ .. _ _ _ _ _RSTS/E
_ _ _ _ .. _ _Usage
_ .... _ _ _ _+ _ .. _ _ .. .. _ _ _ .. _ _ _contents
_ .. _ _ _ ....
D

16-50

I
I System Dependent
I (M is the default)

___

..,

I
Bytes 16-36 (Spaces)
Byte 37
= A means first byte of
record contains FORTRAN
control character.
- (Space) means LF
character precedes and CR
character follows each
record.
= M means record contains
all form control
information.

51-52

Buffer Offset (00)

Not supported by RSTS/E; always
00.

53-80

neserved

Spaces

- .. .. .... - .. .. - - - .. .. .. - - - --- - .. .. - - - - - .. .. --- - -- - .. -- - .. - - - - -- .. - - .. - - - -- - -- - - .. - - - .......
I * U format is not defined by ANSI standard X3.27-1978.
I
.. - .. -- - - ---- - - .. - .. - .. -- - - - - - . - - - .. - - -- - .. - - - .. - - - - - - - - - - - --- - -- - - - - - -- - ---...

End-of-File or

Volumf~

1 Label (EOFI or EOV1)

The EOF1 or EOV1 label is identical to the HDR1 label except for
characters 1-3 and 55-60. EOF indicates the end of the file; EOV
indicates that the end of the ANSI-labeled magnetic tape volume is
reached and the current file is continued on another volume.
For
information on supporting EOV, see the magnetic tape SPEC% function in
Chapter 2.

A- 9

Magnetic Tape Label Formats
Table A-5 shows the character position, field name, and contents of
each byte in the label.
Table A-5:

End-of-File or Volume (EOF or EOV) 1 Record Format

+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - -+- - -" - - - - - - - - - - - - - - - - - - - - - --+
I Character I
Field Name
I
I Position I
and RSTS/E Usage
I
Contents
+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - -+- - _ .. - - - - - - - - - - - - - - - - - - - - - --+

Label Identifier

EOF or EOV.

Label Number

5-21

File Identifier
(2 to 10 characters
FILNAM. or FILNAM.TYPi
blank filled)

Any alphanumeric or
special character in the
ASCII code table.

22-27

File-set Identifier
(Volume Identifier from
the VOL1 label)

Volume 10 of the first
volume in the volume set.

28-31

File Section Number

Numeric characters;
starts at 0001.
Identifies a section in
the file. Specified with
the /POSITION qualifier
on the OPEN statement.
Defaults to 0001.

32-35

File Sequence Number

Numeric characters;
starts at 0001.
Identifies a file on the
volume.

36-39

Generation Number (0001)

Not supported by RSTS/Ei
always 0001.

40-41

Generation Version (00)

Not supported by RSTS/Ei
always 00.

42-47

Creation Date
Today's date in specified
format

(SPACE)YYOOD or
(SPACE)OOOOO if no date.

48-53

Expiration Date
Today's date in specified
format

(SPACE)YYDDD or
(SPACE)OOOOO if expired.

Accessibility

Space

1-3
4

A-10

Magnetic Tape Label Formats
Table A-!5:

End-c)f-File or Volume (EOF or EOV) 1 Record Format (Cont.)

+- - - - - _.' - - - -+- - - - - - - - - - - - - - - - - - - - - - - - _. - -+I Character I
Field Name
I Position I
and RSTS/E Usage
+- - - - - _.' - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - -+-

I
I

Contents
9

55-60

Block Count

Total number of blocks in
this file section.

61-73

System Code DECRSTS/E

Name of system that
produced the volume.
Padded by spaces.

Spaces.
Reserved
74-80
+- - - - - _.' - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - --+

End-of-File or Volume 2 Label (EOF2 or EOV2)

The EOF2 or EOV2 label is identical to the HDR2 label except for
characters 1-3. Table A-6 shows the character position, field name,
and contents of each byte in the label.
Table A-6:

End-of-File or Volume (EOF or EOV) 2 Record Format

+- - - - - _ .. - - - -+- - - - - - - - - - - - - - - - - - - - - -+- - - - - - - ~ - - - - - - - - - - - - - - - - - - - - - - - --+
I Character I
Field Name
Contents
I Position I
and RSTS/E Usage
I
+ - - - - - - .. - - - - + - - - - - - - - - - - - - - - - - - - - - - + - - - - - -, - - - - - - - - - - - - - - - - - - - - - - - - - - - +

Label Identifier

EOF or EOV

Label Number

Record Format
(U is the default)
(S is unsupported)

F = Fixed
D = Variable
S = Spanned
U = Undefined*

6-10

Block Length
(512 is the default)

Numeric characters settable by
FILESIZE option.

11-15

Record Length

Numeric characters settable by
CLUSTERSIZE option.

1-3

A-II

Magnetic Tape Label Formats
Table A-6:

End-of-File or Volume (EOF or EOV) 2 Record Format (Cont.)

+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - ~ - - - - - - - - - - -. -. - - - - - - - - --+
I Character I
Field Name
I
and RSTS/E Usage
Contents
I
I Position I
+- - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - -+- - - - - - - _ .. - - - - - - - - - - - - - _. - - - - - - - --+

16-50

System Dependent
(M is the default)

Bytes 16-36 (Spaces)
Byte 37
= A means first byte of
record contains FORTRAN
control character.
= (Space)
means LF
character precedes and CR
character follows each
record.
- M means record contains
all form control
information.

51-52

Buffer Offset (00)

Not supported by RSTS/Ei always
00.

53-80

Reserved

Spaces

+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - • - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - _. -+
I * U format is not defined by ANSI standard X3.27-l978.
I
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - _. - - - - - - - - - - - - - - - - - - - - -. - --+

Initializing Magnetic Tapes
This section describes how RSTS/E initializes (zeros) DOS and ANSI
magnetic tapes.
To initialize a magnetic tape written in DOS format, RSTS/E:
1.

Rewinds the magnetic tape.

Writes three tape marks on the tape.

Rewinds the magnetic tape again.

To initialize a magnetic tape written in ANSI format, RSTS/E:

Rewinds the magnetic tape.

Writes a volume label (VOLl) on the tape.
The volume
identifier is in bytes 5 through 10, in ASCII.

A-12

Magnetic Tape Label Formats

writes two header labels (HDRI and HDR2).

Writes two tape marks.

Writes two trailer labels (EOFI and EOF2).

Writes three tape marks.

7•

Rewinds the magnetic tape again.

For ANSI-labeled magnetic tapes, the two header labels (HDRI and
HDR2), two tape marks, two trailer labels (EOFI and EOF2) and final
tape mark comprise a dummy file.
For both DOS and ANSI tapes, three
tape marks are the last items written on the tape.
These three tape
marks form the logical end-of-tape (LEOT).
To zero a tape on RSTS/E, use one of the following:
o

The Zero a device SYS call (see Chapter 7)

The UU.ZER directive (see the RSTS/E System Directives
Manual)

The DCL INITIALIZE command (see the RSTS/E System User's
Guide)

The PIP program (see the RSTS/E utilities Reference Manual)

A-13

Appendix B
Card Codes

The RSTS/E card reader driver can be configured for one of four
different ASCII punched card codes:
o

ANSI

DEC029

DEC026

1401

The system manager determines the set of codes used on the system.

all cases, the end-af-file (EOF) card must contain a 12-11-0-1 punch
or a 12-11-0-1-6-7-8-9 punch in column O.
Table B-,l shows the card codes for DEC029, DEC026, 1401, and the ASCII
equivalent.
Table B-1:

Card. Reader Codes

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

ANSI and
1
1
1
ASCII10
DEC029
I
DEC026
1
1401
1
+- - - - - - - - - - - - -+- - - - - - - - - - - - -+- ~ - - - - - - - - - - -+- - - - - - - - - - - - -+- - - - - - - - - - --+
1

Character

1
{

123

12 0

125

11 0

1
1

11 0

unused

SPACE

NONE

12 8 7

8 7

8 3

NONE

12 8 7

11 0

0 8 5

0 8 2

0 8 6

8 3

B-1

1
1

1
'I

1
1

unused

1
1

12 0

1
1

Card Codes
Table

~1:

Card Reader Codes (Cont.)

+- - - - - - - - - - - - -+- - - - - - - - - - - - -+- - - - - - - - - - - - -+- - - - - - - - - - - - -+- - - - - - - - - - - _.+
I
I
I
ANSI and
I
I
I Character I
ASCIIlO
I
DEC029
DEC026
I
1401
I
+- - - - - - - - - - - - -+- - - - - - - - - - - - -+- - - - - - - - - - - - -+- - - - - - - - - - - - -+- - - - - - - - - - --+
$

11 8 3

084

087

084

11 8 7

8 5

8 6

12 8 4

12 8 5

084

8 7

11 8 5

12 8 4

087

11 8 4

12 8 6

o 8 5

083

12 8 3

o 1

8 2

11 8 2

8 5

B-2

Card Codes
Table

~l:

Card Reader Codes (Cont.)

+ .. - - - - - - - - - - - -+- - - - - - - - - - - - -+- - - - - - - '. - - - - -+- - - - - - - - - - - - -+- - - - - - - - - - --+
I
I
I
ANSI and
I
I
I Character I
ASCII10
I
DEC029
I
DEC026
1401
I
+ .. - - - - - - - - - - - -+- - - - - _ .. - - - - - -+- - - - - - - '. - - - - -+- - - - - - - - - - - - -+- - - - - - - - - - --+

11 8 6

082

11 8 6

12 8 4

12 8 6

8 6

8 3

11 8 7

0 8 6

11 8 6

8 6

0 8 7

12 8 2

12 0

8 4

12 1

12 2

12 3

12 4

12 5

12 6

12 7

12 8

12 9

11 1

11 2

11 3

11 4

11 5

11 6

11 7

11 8

B-3

Card Codes
Table ~1: Card Reader Codes (Cont.)
+ _____________ + _____________ + _____________ +_

I
I

___________

+ ____________ +

I
I
I
I
DEC026
I
1401
I
+,- - - - - - - - - - - - - + - - - - - - - - - - - - - + - - - - - - - - - - - - - + - ... - - - - - - - - - - + - - - - - - - - - - - - +

ASCII10

ANSI and
DEC029

11 9

0 2

0 3

0 4

0 5

0 6

0 7

0 8

0 9

12 8 2

11 8 5

12 8 5

082

8 7

0 8 6

11 8 2

12 8 5

11 8 5

11 8 7

8 5

unused

085

8 2

12 8 7

Character

I
R

s
T

I
I
I

I
I

+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ~ --+
I Note: EOF is a 12-11-0-1 punch or a 12-11-0-1-6-7-8-9 punch.
I
+_ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - _.0 _____________________ __ +
~

B-4

Appendix C
Error Messages

RSTS/E generates messages for BASIC-PLUS errors and RSTS/E errors. To
avoid confusion, both types of messages are called RSTS/E error
messages and are described as one set.
The BASIC-PLUS errors cover
compiler and run-tim~ conditions, such as a violation of the syntax
rules (?Syntax error) and referencing an element of an array beyond
the defined limits (?Subscript out of range). The RSTS/E errors
involve operating system conditions, such as failing to locate the
file or account specified (?Can't find file or account) and requesting
the hardware to perform a function for which it is not ready (?Device
hung or write locked). The next two sections describe the RSTS/E
error messages.
Different messages are generated while a job is executing programs
written in languages other than BASIC-PLUS. Such programming
languages include COBOL, BASIC-PLUS-2 and FORTRAN-IV.
For information
about these error messages, consult the appropriate User's Guides.
See Table e-6 for a summary of BASIC-PLUS-2 errors.
In most cases, if you are not trapping errors (that is, an ON ERROR
GOTO statement is not in effect), BASIC-PLUS stops running the
program.
It prints the error message and the line number of the
BASIC-PLUS statement that was being executed when the error occurred.
For example:
10
OPEN 'z' FOR INPUT AS FILE 1%
RUNNH
?Can't find file or account at line 10
Ready
As the Ready prompt indicates, control returns to the system.

Cal

Error Messages
One exception to this procedure occurs when you execute an INPUT
statement at the job's console terminal and error trapping is not in
effect. The system generates the error message and executes the
statement again:
10 ON ERROR GOTO 0 \ INPUT 'INTEGER VALUE'iA%
RUNNH
INTEGER VALUE? C
%Data format error at line 10
INTEGER VALUE?
with error trapping disabled at line 10, an invalid response to the
INPUT statement causes the system to print the error message, clear
the error condition, and execute the statement again.
Each message has an associated error value. 'Whenever an error occurs
with trapping in effect, the system checks the error variable (ERR),
which contains the appropriate decimal error value in the range 0 to
255. An error with a value between 1 and 70 causes the system to
transfer control to the line number indicated in the ON ERROR GO TO
statement. The system does not print the error message. Your program
can check the ERR variable and perform a recovery procedure. If the
error value is between 71 and 127, the system does not transfer
control to the recovery routine but prints the message and returns
control to the system. Error' numbers above 127 are reserved for
BASIC-PLUS-2. Error number 0 is reserved to identify the system
installation name.
Because a BASIC-PLUS program can recover from certain errors, this
appendix lists errors in two categories -- recoverable and
nonrecoverable. The recoverable error messages are listed in
ascending order of their error values. A program can use these error
values to differentiate errors. Non-recoverable errors are in
alphabetical order without error numbers because a program cannot use
these numbers in an error handling routine.
The first character position of each message indicates the severity of
the error. Table C-l describes this standard.

C-2

Error Messages
Table

~l:

Severity Standard in Error Messages

.... - - - - - - - - - - -+- - - - - - ,. - - - - - - -+- - - - - - _ .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I Character I
Severity
Meaning
.... - - - - - - - - - - -+- - - - - _ .. - - - - - - -+- - _ .... - - ~ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I
I

Warning

Execution of the program can continue
but may not generate the expected
results.

Error

Execution cannot continue unless you
remove the cause of the error.

?'?

Severe Error

Execution cannot continue, and you
probably cannot remove the cause of the
error. In most cases, there is no
opportunity for recovery.

none

Information

I
I
I

I
I

A message beginning with neither a
question mark nor a percent is for
information only.
+- - - - - - .. - - - -+- - - - - _ .. - - _ .. - - -+- - - - - - _ .. - - - - - - - - - - _ .. - - _ .. - - - - - - - - _ .. - - - - - --+
In the error message descriptions in the first two sections, the
abbreviations shown in Table C-2 denote special characteristics of the
error.
Table C-2:

Special Abbreviations for Error Descriptions

+- - - - - _. - - - - - - -+- - - - - _ .... _ .. - .. - _ .. _ .... - _ .. - _ .. - - - _ .. - _ .......... - _ .. - - .. - - - - - - - - - --+
I Abbreviation I
Meaning
I
+ - - - - - - . .. - - .. .. - .. ,+ - - - .. - - - .. .. - .. - .. - - - - - - - - - - - - .. .. - - - .. - .. - .. - - - .. - - - - - .. - - - - - - - - +

I
I
I
I
I
I

I
I
I
I
I

(C)

Continue. If an ON ERROR GOTO statement is not in
I
effect, execution continues but with the conditions I
described.
I

(SPR)

Software Performance Report. This error should
occur only under the conditions described. If it
occurs under any other conditions, you should
document the conditions under which the error
occurred and have the appropriate person at your
site send an SPR to DIGITAL. Section C.4 contains
instructions for filling out an SPR.

I
I

I
I
I
I
I

I
I
+ - - - .. - - - - - - - .. .. ...f- - .. - .. - - .. .. .. .. .. - - - - .. - - .. - .. - - - .. .. .. .. .. - .. - .. - - - - - - - - - - - - - - .. - - - - - +

C-3

Error Messages
An error whose description is accompanied by the abbreviation (C)
indicates an exception to the ~rror trapping procedure.
If such an
error occurs in a program with no error trapping in effect, BASIC-PLUS
prints the error message and line number but continues running the
program.
For example:
100 ON ERROR GOTO a \ A% = 32768.
200 PRINT A%
RUNNH
%Integer error at line 100

Ready
The attempt to compute a value outside the range for integers
generates the INTEGER ERROR at line 100. After BASIC-PLUS prints the
error message, processing continues but with the conditions described
in the error meaning.
BASIC-PLUS substitutes a for the erroneously
computed value.
The number of RSTS/E error messages is restricted to 255.
Because of
this restriction, certain error messages have multiple meanings.
The
specific meaning of an error message depends on the operation you are
performing when the error condition occurs.
For example, if the
system attempts a file access and the file cannot be located, RSTS/E
generates the error Can't find file or account (ERR=5).
That same
error condition also applies to other, generically similar access
operations. Thus, if a program tries to send a message to another
program and the system cannot find the proper entry in the system
table of eligible receivers, RSTS/E returns error number 5. Though
the second failure does not involve a file access error, it too is
classified as an access failure.
Certain RSTS/E errors, although classified as user-recoverable, cannot
be trapped by a program.
Table C-3 lists these errors.
Table C-3:

Nontrappable Errors in Recoverable Class

+- - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - --+
I ERR I
Message Printed
+- - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - --+

RESERVED INSTRUCTION TRAP

SP STACK OVERFLOW

DISK ERROR DURING SWAP

38
MEMORY PARITY FAILURE
+- - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - --+

C-4

Error Messages

These errors involve special conditions that your program cannot
control and that should not occur on a normal system.
For example,
the error ??Disk error during swap indicates a hardware problem.
The
system does not return control to the program.
The error condition
itself, however, can be either transient or recurring.
Bring these errors to the attention of your system manager for further
investigation.
These errors are recoverable in the strict sense that
the monitor can take corrective action.
However, the BASIC-PLUS
run-time system doe~; not return control to your program.

User Recoverable Errors
Table C-4 lists the user recoverable errors.
The notations (C) and
(SPR) follow some error explanations.
See Table C-2 for an
explanation of these special abbreviations.
Table C-4:

User Recoverable Errors

+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -. - - - - - - - - - - - --+
Message and Meaning
ERR Value I
+- - - - - _ .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - _. - - --+

(SYSTEM INSTALLATION NAME)
The error code 0 is associated with the system
installation name. System programs use this to
print identification lines.

??BAD DIRECTORY FOR DEVICE
e The directory of the device referenced is in
an unreadable format.
e The magnetic tape label format on tape
differs from the system-wide default format,
the current job default format, or the format
specified in the OPEN statement. Use the
MOUNT command to set the correct format
default or change the format specification in
the MODE option of the OPEN statement.

?ILLEGAL FILE NAME
o The specified file name or type is not
acceptable. It contains unacceptable
characters or violates the file specification
format.
e The ceL command to be added begins with a
number or contains an illegal character.

C-5

Error Messages
Table C-4:

User Recoverable Errors (Cont.)

+- _ .............. _ .. - - - _ .. - - - - - - - - - - - - - .. - - _ .. _ .... - _ ........ _ .. _ .. _ .. - .. - _ .. - .. _.... _ .. - - - - _ .. _+
I
Message and Meaning
ERR Value I
+_ .. __ - .. ______ .. _ .... _ ............ __ .... _ - .... ___ .. __ .. __ .... _ .. ____ .. - .. ____ .... _ - ..

___

?ACCOUNT OR DEVICE IN USE
o An attempt to reassign or dismount the device
fails because the device is open or has one
or more open files.
o The account to be deleted has one or more
files and must be zeroed before being
deleted.
o The run-time system to be deleted is
currently loaded in memory and in use.
o Output to a pseudo keyboard cannot be done
unless the device is in KB wait state.
o An echo control field cannot be declared
while another field is currently active and
the system has input characters for your
program.
o The CCL command to be added already exists.
o The disk being accessed was mounted /NOSHARE
by another user . .

?NO ROOM FOR USER ON DEVICE
o You have already used the available storage
space.
o The device as a whole is too full to accept
further data.
o The directory is full.
o You are sending a message to a message
receiver that already has its maximum number
of messages pending.

?CAN'T FIND FILE OR ACCOUNT
o The specified file or account number was not
found on the specified device.
o The CCL command to be deleted does not exist.

?NOT A VALID DEVICE
The device specification supplied is not valid for
one of the following reasons:
o The unit number or its type is not configured
on the system.
o The specification is logical and
untranslatable because a physical device is
not associated with it.

C-6

-4-'

Error Messages
Table C-4:

User Recoverable Errors (Cont.)

+ - - - - - - .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I
Message and Meaning
ERR Value I
+ - - - - - - .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
?I/O CHANNEL ALREADY OPEN
7
You tried to open an I/O channel that the program
had already opened. Note that this error cannot
occur in BASIC-PLUS or BASIC-PLUS-2, since both
automatically close and then reopen the channel.
(SPR)
?DEVICE NOT AVAILABLE
ThE~ specified device exists on the system but you
cannot assign or open it for one of the following
reasons:
o The device is currently reserved by another
job.
o The device requires privileges for ownership
that you do not have.
o The system manager has disabled the device or
its contr()ller.
o The device is a keyboard line for pseudo
keyboard use only.

11/0 CHANNEL NOT OPEN
You tried to perform I/O on one of the twelve
channels that the program has not previously
opened.

?PROTECTION VIOLATION
You cannot perform the requested operation because
the operation is illegal (such as input from a
line printer) or because you do not have the
necessary privileges (such as deleting a protected
file) .

?END OF FILE ON DEVICE
Attempt to perform input beyond the end of a data
file, or a BASIC-PLUS source file without an END
statement is called into memory.

??FATAL SYSTEM I/O FAILURE
An I/O error has occurred at the system level. You
have no guarantee that the last operation has been
performed. This error is caused by a hardware
condition. Report such occurrences to the system
manager. See the discussion at beginning of this
appendix.

C-7

Error Messages
Table C-4:

User Recoverable Errors (Cont.)

+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+
Message and Meaning
ERR Value I
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
?DATA ERROR ON DEVICE
13
I
One or more characters may have been transmitted
I
incorrectly due to a parity error, bad punch
I
combination on a card, or similar error.
I

?DEVICE HUNG OR WRITE LOCKED
Check hardware condition of the requested device.
Possible causes of this error include a line
printer out of paper or device being offline.

?KEYBOARD WAIT EXHAUSTED
Time that the WAIT statement requests has been
exhausted with no input received from the
specified keyboard.

?NAME OR ACCOUNT NOW EXISTS
Either you tried to rename a file with the name of
a file that already exists, or the system manager
tried to create an account number that is already
in the system.

?TOO MANY OPEN FILES ON UNIT
Only one open DECtape output file is permitted per
DECtape drive. Only one open file per magnetic
tape drive is permitted.

?ILLEGAL SYS() USAGE
Illegal use of the SYS system function.

I
!
I
I

I
I
I
I
I
I
I
I
I
I

?PACK IDS DON'T MATCH
The identification code for the specified disk
pack does not match the identification code
already on the pack.
I
1

I
I

?DISK PACK IS NOT MOUNTED
No disk pack is mounted on the specified disk
drive.
I

I ?DEVICE IS RESTRICTED
I

,I
1

The specified disk pack is marked restricted by
another user. You need DEVICE privilege to access
it.

I
I
I

I ?DISK BLOCK IS INTERLOCKED
The requested disk block segment is already in use
I
(lo~ked) by some other user.
I

I
I
I
I
I
I
I
I
I

I
I
I
I
I
I
I
I
I
I
I
I
1

I
1

C-8

Error Messages
Table C-4:

User Recoverable Errors (Cont.)

.... - - - - - - - - - - - - - - - - - _ .. - - - - - - - - - - - - - - - ~ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I
Message and Meaning
ERR Value I
+ - - - - - - - - - - - - - - - - - _ .. - _. - - - - - - - - - - - - ~ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+
?ILLEGAL CLUSTER SIZE
23
The specified cluster size is unacceptable. The
cluster size must be a power of 2. For a file
cluster, the size must be equal to or greater than
the pack cluster size and must not be greater than
256. For a pack cluster, the size must be equal to
or greater than the device cluster size and must
not be greater than 16. The device cluster size is
fixed by type.

?ACCOUNT DOES NOT EXIST
You tried to create a file in a nonexistent
account on a private disk.

%DISK PACK NEEDS REBUILDING
This is a nonfatal disk mounting error. Use the
DCL MOUNT command.

??DISK PACK MOUNT ERROR
This is a fatal disk mounting error. The disk
cannot be successfully mounted. The disk structure
is corrupt or it is not a RSTS disk. Use DSKINT to
put the RSTS structure on the disk.

?I/O TO DETACHED KEYBOARD
This error has the following possible causes:
o The job is detached and one of the simple
terminal SYS system function calls (function
codes O,lv2,3,4 or 11) is attempted for the
job's console terminal (KB:).
o The job is detached and an open is attempted
using the device name "KB:".
o Any I/O operation, such as INPUT, PRINT, GET,
or PUT, is attempted to a terminal on a
hung-up dial-up line and the terminal is
neither the job's console terminal nor the
terminal from which the job is detached.
Opening a dial-up line that is currently hung
up does not cause an error.

C-9

Error Messages
Table C-4:

User Recoverable Errors (Cont.)

+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ...
Message and Meaning
ERR Value I
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

The job is detached and I/O is attempted to a
terminal that was opened with MODE 16%. (When
MODE 16% is not specified, the job hibernates
when it becomes detached and terminal I/O is
a t tempted. )
Note that the system places a detached job in
hibernation when an I/O request is issued to the
job's console (KB:) terminal or to any channel on
which that terminal is open. Thus, hibernation can
occur with local terminals if the job detaches.
Hibernation can also occur on dial-up lines if the
job detaches or if the line is hung up, causing
the system to automatically detach the job.
PROGRAMMABLE AC TRAP
A CTRL/C was typed while an ON ERROR GOTO
statement was in effect and programmable CTRL/C
trapping was enabled.

??CORRUPTED FILE STRUCTURE

?DEVICE NOT FILE STRUCTURED
An attempt is made to access a device other than a
disk, DECtape, or magnetic tape as a
file-structured device. This error occurs, for
example, when you attempt to get a directory
listing of a nondirectory device.

?ILLEGAL BYTE COUNT FOR I/O
o The buffer size specified in the RECORDSIZE
option of the OPEN statement or the COUNT
option of the PUT statement is not a multiple
of the block size of the device you are using
for I/O or is illegal for the device.
o You tried to run a compiled file that has
improper size due to incorrect transfer
procedure.
o You specified illegal parameters.

?NO BUFFER SPACE AVAILABLE
o You accessed a file and the monitor requires
one small buffer to complete the request but
there is no buffer available.
o The program is sending a message and a small
buffer is not available for the operation.

C-IO

Error Messages
Table C-4:

User Recoverable Errors (Cont.)

+- - - - - _ .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I
Message and Meaning
ERR Value I
+- - - - - _ .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I ??ODD ADDRESS TRAP
33
This error occurs when you attempt to reference a
I
nonexistent address, reference an odd address
I
using a word instruction, or perform a PEEK
I
function with an odd or nonexistent parameter. If
I
you get this error for any other reason, report it
I
to your system manager.
I

I
I ??RESERVED INSTRUCTION TRAP
I

An attempt is made to execute an illegal or
reserved instruction or an FPP instruction when
floating-point hardware is not available. See the
discussion at beginning of this appendix.

I
I
I
I
I ??MEMORY MANAGEMENT TRAP
You specified an illegal monitor address in the
I
I

PEEK function. If you get this error for any other
reason, report it to your system manager.

I
I

??SP STACK OVERFLOW
An attempt to extend the hardware stack beyond its
I
legal size is encountered. See the discussion at
I
beginning
of this appendix. (SPR)
I

I
I ??DISK ERROR DURING SWAP
A hardware error occurs when your job is swapped
I
into or out of memory. The contents of your job
I
area are lost, but the job remains logged in to
I
the system and is reinitialized to run the NONAME
I
program. Report such occurrences to the system
I
manager. See the discussion at beginning of this
I
appendix.
I
I
I
I
I

??MEMORY PARITY FAILURE
A parity error was detected in the memory occupied
by this job. See the discussion at beginning of
this appendix.
I

?MAGTAPE SELECT ERROR
When access to a magnetic tape drive was
attempted, the selected unit was found to be off
I
line.
I
I
I

C-ll

Error Messages
Table C-4:
~

User Recoverable Errors (Cont.)

-- - - - - - - - - - -- - - - - - - - - - - - - -- - - - - - - - - - - - - - - - - - - - - - - - - - - -- - -- - - - - - - - - Message and Meaning
ERR Value I
- - - - - - - - - - - - -- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -- - - - ----- - -- - ----- -.~

-.~

?MAGTAPE RECORD LENGTH ERROR
When performing input from magnetic tape, the
record on tape was longer than the buffer
designated to handle the record.

??NON-RES RUN-TIME SYSTEM
A hardware error occurred when loading a run-time
system or resident library for your job. Report
such occurrences to the system manager.

?VIRTUAL BUFFER TOO LARGE
Virtual array buffers must be 512 bytes long.

?VIRTUAL ARRAY NOT ON DISK
A nondisk device is open on the channel on which
the virtual array is referenced.

?MATRIX OR ARRAY TOO BIG
Memory array size is too large.

?VIRTUAL ARRAY NOT YET OPEN
You tried to use a virtual array before opening
the corresponding disk file.

?ILLEGAL I/O CHANNEL
You tried to open a file on an I/O channel outside
the range of the integer numbers 1 to 12.

?LINE TOO LONG
You tried to input a line longer than 255
characters (which includes any line terminator).
The buffer overflows.

%FLOATING POINT ERROR
You tried to use a computed floating-point number
outside the range lE-38<n<lE38. If no transfer to
an error handling routine is made, zero is
returned as the floating-point value. (C)

%ARGUMENT TOO LARGE IN EXP
Acceptable arguments are within the approximate
range -89<arg<~88. The value returned is zero. (C)

C-12

Error Messages
Table

~4:

User Recoverable Errors (Cont.)

of· - - - - - - - - - - - - - - - - - _ .• - - - - - - - - - - - - - - - .• - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

Message and Meaning

ERR Value I

of· - - - - - - - - - - - - - - - - - - '. - - - - - - - - - - - - - - - .• - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +

I %DATA FORMAT ERROR

A READ or INPUT statement detected data in an
illegal format. For example, 1 .. 2 is an improperly
formed number, 1.3 is an improperly formed
integer, and "HELLO" "THERE" is an illegal string.
( C)

%INTEGER ERROR
You tried to use a computed integer outside the
range -32768<n<32767. For example, you tried to
assign to an integer variable a floating-point
number outside the integer range. If no transfer
to an error handling routine is made, zero is
returned as the integer value. (C)

?ILLEGAL NUMBER
Integer overflow or underflow, or floating-point
overflow can cause this error. The range for
integers is -32768 to +32767; for floating-point
numbers, the upper limit is lE38. (For
floating-point underflow, the FLOATING POINT ERROR
(ERR=48) is generated.)

%ILLEGAL ARGUMENT IN LOG
A negative or zero argument to LOG function causes
this error. Value returned is the argument as
passed to the function. (C)

%IMAGINARY SQUARE ROOTS
You tried to take the square root of a number less
than zero. The value returned is the square root
of the absolute value of the argument. (C)

?SUBSCRIPT OUT OF RANGE
You tried to reference an array element beyond the
number of elements created for the array when it
was dimensioned.

?CAN' 'r INVERT MATRIX
You tried to invert a singular or nearly singular
matrix.

?OUT OF DATA
The DATA list was exhausted and a READ requested
additional data.

C-13

Error Messages
Table C-4:

User Recoverable Errors (Cont.)

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

I
Message and Meaning
ERR Value I
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
?ON STATEMENT OUT OF RANGE
58
The index value in an ON-GOTO or ON-GOSUB
statement is less than one or greater than the
number of line numbers in the list.
?NOT ENOUGH DATA IN RECORD
An INPUT statement did not find enough data in one
line to satisfy all the specified variables.

?INTEGER OVERFLOW, FOR LOOP
The integer index in a FOR loop attempted to go
beyond 32767 or below -32768.

%DIVISION BY 0
Your program attempted to divide some quantity by
zero. If no transfer is made to an error handling
routine, the result is zero. (C)

?NO RUN-TIME SYSTEM
The run-time system referenced has not been added
to the system list of run-time systems.

?FIELD OVERFLOWS BUFFER
You tried to use FIELD to allocate more space than
exists in the specified buffer.

?NOT A RANDOM ACCESS DEVICE
You tried to perform random access I/O to a
nonrandom access device.

?ILLEGAL MAGTAPE() USAGE
Improper use of the MAGTAPE function.

?MISSING SPECIAL FEATURE
o Your program uses a BASIC-PLUS feature not
present on the given installation.
o You attempted to use MODE 512% on a line
printer that has 8 bit capabilities set.
o You attempted to use a DECnet function but
DECnet/E is not installed.

C-14

Error Messages
Table C-4:

User Recoverable Errors (Cont.)

~. _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

_________________________________

Message and Meaning

ERR Value

I ?ILLEGAL SWITCH USAGE
l o A CCL command contains an error in an
otherwise valid CCL switch. (For example, the
SI:n switch was used without a value for n or
1
a colon; or more than one of the same type of
'I
CCL switch was specified.)
Ij
A file specification switch is not the last
element in a file specification or is missing
I
a colon or an argument.

- - -- - --- - - - - ~ - - - - - - -- - - -- - - - - -- - - - - - - - - - - - - -- - -- ----- - ----- -- - - - -- - -~

?END OF VOLUME
You are reading an ANSI magnetic tape and reached
1
an end-of-volume (EOV) label. The message
I
indicates that the data continues 'on another
I
volume. (See the section "Processing Multivolume
I
ANSI Magnetic Tape Files," in Chapter 2.)

I
I
I

I ?QUOTA EXCEEDED
69
. I
You exceeded the logged-in disk quota for your
I
I
I
account. Or, you exceeded some other quota with a
I
I
SYS function call (job, detached job, RIB, or
I
I
message quota.
I
~ - - - -- - .. - - - - - - - - - - -.' - - - - - - - - - - ------- - - - --- - - - - - - ----- - --- - - - - - - - -- --~

Nonrecoverable Errors
Table C··S lists the nonrecoverable errors. The notations (C) and
(SPR) follow some error explanations.
See Table C-2 for an
explanation of these special abbreviations.
Table CaS:
~

Nonrecoverable Errors

____________

~ ____________ ~

____________

______________________________________

Message and Meaning

_____________________________

____________

--~

____________

?ARGUMENTS DON'T MATCH
Arguments in a function call do not match, in number or in
type, the arguments defined for the function.
?BAD LINE NUMBER PAIR
Line numbers specified in a LIST or DELETE command were
formatted incorrectly.

C-IS

I
I
I
I
I
I
I
I

Error Messages
Table C-S:

Nonrecoverable Errors (Cont.)

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

Message and Meaning

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

?BAD NUMBER IN PRINT-USING
Format specified in the PRINT-USING string cannot be used to
print one or more values.
?CAN'T CONTINUE
Program was stopped or ended at a spot from which execution
cannot be resumed with CONT or CCONT.

I
I
I
I
I
I
I
I

?DATA TYPE ERROR
Incorrect use of floating-point, integer, or character string
variable or constant where some other data type was necessary.
?DEF WITHOUT FNEND
A second DEF statement was encountered in the processing of a
user function without an FNEND.
?END OF STATEMENT NOT SEEN
Statement contains too many elements to be processed correctly.

I
I
I
I
I
I
I
I
I
I

I
I
I
I
I
I
I
?EXECUTE ONLY FILE
I
An attempt was made to add, delete, or list a statement in a
I
compiled file.
I
I
?EXPRESSION TOO COMPLICATED
I
This error usually occurs when parentheses have been nested too I
deeply. The depth allowed depends on the individual expression. I
I
?FILE EXISTS-RENAME/REPLACE
I
A file of the name specified in a SAVE command already exists.
I
To save the current program with the name specified, use
I
REPLACE or RENAME followed by SAVE.
I
?ERROR TEXT LOOKUP FAILURE
An I/O error occurred while the system was attempting to
retrieve an error message. Possible causes could be the device
containing the system error file (ERR.SYS) is offline, or the
system error file contains a bad block.

?FNEND WITHOUT DEF
I
An FNEND statement was encountered in your program before a DEF I
statement was seen.
I
?FNEND WITHOUT FUNCTION CALL
A FNEND statement was encountered in your program before a
function call was executed.

C-16

I
I
I
I
I

Error Messages
Table C-S:

Nonrecoverable Errors (Cont.)

+ ~ ~ - - ~ - ~ ~ ~ - - ~ - _ .. - - - - - ~ - - - - - - - - - - - - - - - - - - - - - - - - - - - - ~ ~ ~ ~ - - - - - - ~ - - - - - - - -+
I
Message and Meaning
+- - - - - - - - - - - - - _ .. - - - - - - - ~ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I ?FOR WITHOUT NEXT
I
A FOR statement was encountered in your program without a
I
corresponding NEXT statement to terminate the loop.
I
I

?ILLEGAL CONDITIONAL CLAUSE
You used an incorrectly formatted conditional expression.
I
I
I
I
I
I
I
I
I

?ILLEGAL DEF NESTING
The range of one function definition crosses the range of
another function definition.
?ILLEGAL DUMMY VARIABLE
One of the variables in the dummy variable list of a
user-defined function is not a legal variable name.

I
I ?ILLEGAL EXPRESSION
I
I
I
I

Double operators, missing operators, mismatched parentheses, or
some similar error was found in an expression.
?ILLEGAL FIELD VARIABLE

I
The specified FIELD variable is unacceptable.
I
I ?ILLEGAL FN REDEFINITION
I
An attempt was made to redefine a user function.
I

?ILLEGAL FUNCTION NAME
An attempt was made to define a function with a function name
of incorrect format.
?ILLEGAL IF S~rATEMENT
You used an incorrectly formatted IF statement.

?ILLEGAL IN IMMEDIATE MODE
You entered a statement in immediate mode that can only be
executed as part of a program.
?ILLEGAL LINE NUMBER(S)
A line number reference is outside the range 1<n<32767.
?ILLEGAL MODE MIXING
String and numeric operations cannot be mixed.
?ILLEGAL STATEMENT
An attempt was made to execute a statement that did not compile
without errors.

C-17

Error Messages
Table C-S:

Nonrecoverable Errors (Cont.)

+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - .. - - - - - - - - - - - - - - - - - - - - - - - -+
I
Message and Meaning
I
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - _ .. - - - - - - - - - - - - - - - - - - - - - - --+
?ILLEGAL SYMBOL
An unrecognizable character was encount~~red. For example, a
line consisting of a % character causes this error.
?ILLEGAL VERB
The verb portion of the BASIC-PLUS statement cannot be
recognized.
%INCONSISTENT FUNCTION USAGE
A function is defined with a certain number of arguments but is
referenced elsewhere with a different number of arguments.
Correct the reference to match the definition and reload the
program to reset the function definition.
%INCONSISTENT SUBSCRIPT USE
A subscripted variable is being used with a different number of
dimensions from the number with which it was originally
defined.
?LITERAL STRING NEEDED
A variable name was used where a numeric or character string
was necessary.
?MATRIX DIMENSION ERROR
An attempt was made to dimension a matrix to more than two
dimensions, or an error was made in the syntax of a DIM
statement.
?MATRIX OR ARRAY WITHOUT DIM
A matrix or array element was referenced beyond the range of an
implicitly dimensioned matrix.
??MAXIMUM MEMORY EXCEEDED
o During an OLD operation, the job's private memory size
maximum was reached.
o While running a program, the system required more memory
for string or I/O buffer space, and the job's private
memory size maximum or the system maximum (16K words for
BASIC-PLUS) was reached.
?MODIFIER ERROR
o An attempt is made to use one of the statement modifiers
(FOR, WHILE, UNTIL, IF, or UNLESS) incorrectly.
o An OPEN statement modifier, such as a RECORDSLZE,
CLUSTERSIZE, FILESIZE, or MODE option, is not in the
correct order.

C-1B

Error Messages
Table C-S:

Nonrecoverable Errors (Cont.)

~. _ _ _

________________________________________________________________

___

Message and Meaning

?NEXT WITHOUT FOR
A NEXT statement was encountered in your program without a
previous FOR statement.
?NO LOGINS
Message printed if the system is full and cannot accept
additional users or if further logins are disabled by the
system manager '.
?NOT ENOUGH AVAILABLE MEMORY
An attempt was made to load a nonprivileged compiled program
that is too large to run, given the job's private memory size
maximum. The program must be made privileged to allow it to
expand above a private memory size maximum, or the system
manager must increase the job's private memory size maximum to
accommodate the program.
?NUMBER IS NEEDED
A character string or variable name was used where a number was
necessary.
?l OR 2 DIMENSIONS ONLY
An attempt was made to dimension a matrix to more than two
dimensions.
?ON STATEMENT NEEDS GOTO
A statement beginning with ON does not contain a GOTO or GOSUB
clause.
PLEASE SAY HELLO
Message printed by the LOGIN system program. A user who was not
logged into the! system typed something other than a legal,
logged-out command.
?PLEASE USE THE RUN COMMAND
A transfer of control (as in a GOTO, GOSUB or IF-GOTO
statement) cannot be performed from immediate mode.
?PRINT-USING BUFFE:R OVERFLOW
Format specified contains a field too large to be manipulated
by the PRINT-USING statement.
?PRINT-USING FOR~,T ERROR
An error was made in the construction of the string used to
supply the output format in a PRINT-USING statement.

C-19

Error Messages
Table C-S:

Nonrecoverable Errors (Cont.)

+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Message and Meaning
I
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ,. - - - - - - - - - - - - - - - - - - - - - - - +,
??PROGRAM LOST-SORRY
I
A fatal system error has occurred that caused your program to
I
be lost. This error can indicate hardware problems or use of an I
improperly compiled program. See the next section for more
I
information.
I

?REDIMENSIONED ARRAY
Use of an array or matrix within your program has caused
BASIC-PLUS to redimension the array implicitly.

I
I
I
I
I

?RESUME AND NO ERROR
A RESUME statement was encountered where no error had occurred
to cause a transfer into an error handling routine with the ON
ERROR GOTO statement.
?RETURN WITHOUT GOSUB
RETURN statement is encountered in your program when a previous
GOSUB statement was not executed.
%SCALE FACTOR INTERLOCK
o You set a new scale factor and then executed a program
that was compiled (that is, translated) using a different
scale factor. The program runs, but BASIC-PLUS uses the
scale factor in effect when the program was compiled. To
cause BASIC-PLUS to compile the program with the new scale
factor, use REPLACE and OLD.
o You set a new scale factor and then entered an immediate
mode statement. Immediate mode statements are always
compiled using the current scale factor. The new scale
factor will take effect when you use the NEW or OLD
command or run a program from its source file.
See the BASIC-PLUS Language Manual for more information. (C)
?STATEMENT NOT FOUND
Reference is made in the program to a line number that is not
in the program.
STOP
STOP statement was executed. You can usually continue program
execution by typing CONT and the RETURN key.
?STRING IS NEEDED
A number or variable name was used where a character string was
necessary.

C-20

I
I
I

I
I

Error Messages
Table C·S:

Nonrecoverable Errors (Cont.)

+. - - - - _ .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

Message and Meaning

+- - - - - _. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

?SYNTAX ERROR
BASIC-PLUS statement was incorrectly formatted.
?TOO FEW ARGUMENTS
The function has been called with a number of arguments not
equal to the number defined for the function.
?TOO MANY ARGUMENTS
A user-defined function can have up to five arguments.
?UNDEFINED FUNCTION CALLED
BASIC-PLUS interpreted some statement component as a function
call for which there is no defined function (system or user).
?WHAT?
You entered a command or immediate mode statement that
BASIC-PLUS cannot process. An illegal verb or improper format
error is most likely.
?WRONG MATH PACKAGE
Program was compiled on a system with either the two-word or
four-word math package and an attempt is made to run the
program on a system with the opposite math package. Recompile
the program using the math package of the system on which it
will be run.
+ - - - - - - - - - - - - - - .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -' - - - - - - - - - - - - - - - - - +

BASIC-PLUS-2 Errors
Table C-6 lists the BASIC-PLUS-2 errors. For explanations of these
error messages, see the appropriate BASIC-PLUS-2 documentation.
Table C-6:

BASIC·PLUS-2 Errors

+ .. - - - - - - - - - - - - - .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

Message

+ .. - - - - - - - - - - - - - .. - - - - - - - - - - - - - - - - - - -+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+

I
I ?lst arg to SEQ$ > 2nd
I
I ?Arrays must be same dim
I
I ?Arrays must be square
I
I ?Argument out of bounds

I
I ?Key larger than record
?Key not changeable
?Key size too large
?Move overflows buffer
C-21

I
I
I
I
I
I
I
I

Error Messages

Table C-6:
~

BASIC-PLUS-2 Errors (Cont.)

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

-.~

Message
I
~- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I
I ?Bad record identifier
I
I ?Bad RECORDSIZE on OPEN
I
I ?Cannot change array dims
I
I ?Cannot open file
I
I ?Cannot position to EOF
I
I ?CHAIN to non-existent line
I
I %Decimal overflow
I

?Negative fill or string len
?Negative TAB not allowed
?Network operation rejected
?No current record
?No fields in image
?No file name
?No primary key specified

?Directive error

?No support for op in task

?Duplicate key detected

?Node name error

?Error trap needs RESUME

?Not at end of file

?Exponentiation error

?Null image

?FILE ACP failure

?Numeric image for string

?File attributes not matched

?OPEN' Error - file corrupted

?File is locked

?Primary key out of sequence

?Floating overflow

?Record already exists

?Floating underflow

?Record/bucket locked

?Index not initialized

?Record has been deleted

?Invalid file options

?Record LOCK failed

?Illegal key attributes

?Record not found

?Invalid key of reference

?RECORD number exceeds max

?Illegal ALLOW clause

?Record on file too big

?Illegal exit from DEF*

%RECORDSIZE overflows MAP

?Illegal operation

?RECORDTYPES not matched

C-22

Error Messages
Table C-6:

BASIC-PLUS-2 Errors (Cont.)

+ - - - - - - - - - - - _ .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I
Message
I
+- - - - - - - - - - - _ .. - - - - - - - - - - - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

?Illegal or illogical access

?Recursive subroutine call

?Illegal record format

?REMAP overflows buffer,

?Illegal record lock clause

?RRV not fully updated

?Illegal record on file

?Size of record invalid

?Illegal RESUME to SUBR

?String image for numeric

?Illegal string image

?String too long

?Illegal subroutine return

?Tape BOT detected

?Illegal usage

?Tape not ANSI labeled

?Illegal usage for device

?Tape records not ANSI

?Illogical record accessing

?Terminal fmt file required

?Improper error handling

?TIME limit exceeded

?Indexed not fully optimized

?Too much data in record

?Invalid RFA field

?Unaligned REMAP variable

?Key field beyond record end
?Unexpired file date
+- - - ~ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+- - - - - _.
Q

--+

The ??Program Lost-Sorry Error
The ??Program lost-sorry error occurs when BASIC-PLUS tries to run a
program and cannot'. BASIC-PLUS clears the job image from memory and
returns control to the user.
If possible, BASIC-PLUS prints a second
message that provides more information about what caused the program
to be lost.
In several cases, however, only the ??Program lost-sorry
message is printed, and the system manager must check the error log to
determine the cause. Always report a ??Program lost-sorry message and
its associated message (if printed) to your system manager.

C-23

Error

Message~

The ??Program lost-sorry error has four possible causes:
o

A checksum error occurs on a .BAC file.
(A checksum error is
usually the result of a hardware problem.)

An unrecoverable disk error occurs while BASIC-PLUS is
reading a .BAC file.

BASIC-PLUS tries to load a .BAC file of incorrect size.

BASIC-PLUS tries to run a file whose stored version number
does not match the current BASIC-PLUS run-time system's
version number.

You can often recover by recompiling the program from its source file
and running it again.
To recompile the program:
1.

Use the OLD command to translate (compile) the program from
its source file.
OLD places the translated program in
memory.

Use the COMPILE command to create a new .BAC file that
contains the translated image.

The next four sections describe each of the possible causes in more
detail.

Checksum Error on a .BAC File
A "checksum" is a numeric quantity that is used to detect errors.
When you save a translated program in a disk file with the COMPILE
command, BASIC-PLUS computes a checksum and stores it in the file.
BASIC-PLUS computes another checksum when it loads the .BAC file from
disk. An error occurs if the computed and stored checksums do not
match.
If the checksums are not equal, BASIC-PLUS produces an error to be
logged by the RSTS/E monitor, returns the ??Program lost-sorry error
to the user, and aborts program execution.
Checksum errors are usually caused by a disk error. The disk error
may have occurred when you created the .BAC file or it may have
occurred while BASIC-PLUS was reading the .BAC file into memory.
You can recover by recompiling the program and running it again.

C-24

Error Messages
Unrecoverable I)isk Error Reading a .BAC File
The ??Program lost-sorry error also results when an unrecoverable disk
E~rror occurs while BASIC-PLUS is loading a .BAC file into memory.
Unrecoverable disk errors can result from bad disk blocks, dust,
problems with the disk drive, or a transient hardware problem in the
disk subsystem.
Sometimes these errors produce an error such as
??Disk error during swap, which is logged in the system error logging
j:ile ~
Hecompiling the program may correct the problem.
the problem to your system manager.

Be sure to report

Incorrect .BAC File Size
A .BAC file must be between 2K and 16K words (inclusive).
In
addition, the number of blocks in the file must be an integer that is
one less than a multiple of 4.
If the size of the .BAC file does not follow these rules, BASIC-PLUS
prints two messages when it tries to load the file into memory:
??Program lost-sorry and ?Illegal byte count for I/O.
These errors
are not logged in the system error logging file.
To correct the problem, recompile the program.

Unmatched Version Numbers
~~hen

you use COMPILE to save a translated program, BASIC-PLUS writes
the current version number of the BASIC-PLUS run-time system into the
oBAC file. When BASIC-PLUS runs or chains to a .BAC file, it checks
the version number stored in the file against the version number of
the run-time system being used.
If the version numbers do not match,
the ??Program lost-sorry error results.

Consult the RS2'S/E Release Notes to find out whether recompilation of
current programs is necessary for a new version of BASIC-PLUS.

Software Performance Report Guidelines
~~he Software Performance Report (SPR) forms let you report problems
with DIGITAL software. Before submitting an SPR, make sure that the
problem has not been corrected in the Release Notes or the Software
Dispatch.

C-2S

Error Messages
To speed response and prevent processing dela~{s with an SPR, describe
the problem as completely as possible. The following list contains
the minimal information to include in the SPR:
o

Complete hardware configuration; including CPU type, system
disk, amount and type of memory, hardware options (such as
floating-point processor), and system peripherals.

Monitor options present on the system, including math package
and BASIC-PLUS options.

Program name, version number, and edit level (generally found
on line 1010 of the program listing), and any optional
patches included in the program. Also include the account(s)
under which the program failed and the list of privileges
assigned to the account.

The PRIORITY and SWAP MAX under which the program was
running.

A terminal printout of any relevant command strings and input
data.

A list of any modifications made to the program.

A listing of any applicable log files.

If you submit a crash dump, it must include the output of the
crash dump analysis program. Machine-readable submissions
must include the CRASH.SYS file and monitor .SIL file in use
at the time of the crash. For problems related to run-time
systems, include the .RTS file.

C-26

Appendix D
Radix-50 and ASCII Character Sets

Radix-SO Character Set
f

Many items in RSTS/E, such as file names and file types, are stored in
Radix-50 format. This format allows three characters to be stored as
a, two -byte integer (one 16 -bi t word).
The RAD$ function converts a
Radix-50 word to its three-character representation. In addition, the
file name string scan SYS calls convert three-character strings to
Radix-50 format.
The following chart shows the complete set of characters that can be
represented in Radi)c-50 format, their ASCII octal equivalents, and the
Radix~50 value for each character:
Character

ASCII Octal
Equivalent

Radix-SO
Equivalent (octal)

space

A-Z

101··132

1-32

4~1

0-9

60 ··71

36-47

The value of a charclcter in its two-byte Radix-50 representation
depends on its position in the string. To obtain the octal value of
the character in the Radix-50 representation, multiply its Radix-50
octal equivalent by the appropriate power of 50 (oc~al). To gain the
full value of the Radix-50 representation of a three-character string,
add the values of the three characters. For example, the maximum
Radix-50 value (representing the character string 999) is:

0-1

Radix-50 and ASCII Character Sets
Table D-1 provides an easy way to translate between the ASCII
character set and its Radix-50 equivalents based on position within a
string.
For convenience, the table contains the decimal value of each
character as well as its octal value.
(You can find the decimal value
of a Radix-50 word using the same technique shown here for octal.)
Table D-1:

Radix-50 Character Positions

+- - - - - - -+- - - - - -+- - - - - - - -+- - - - - - -+- - - - - -+- - - - - - - -+- - - - - -+- - - - - -+- - - - - -+.
I Single I
I
1 or 1st I
I
I 2nd I
!
I 3rd I
I
I
1 Char. I Octa11Decima1 I Char. I Octa11Decimal I Char. I Octa11 Dec. I
+- - - - - - -+- - - - - -+- - - - - - - -+- - - - - - -+- - - - - -+- - - - - - - -+- - - - - -+- - - - - -+- - - - --+

I
A
B
C
D
E

F
G

H
I

J
K
L

M
N

o
P

Q
R
S
T
U
V

w
X
Y

z
$
?

o
1
2
3
4
5

0031001
006200 I
0113001
0144001
0175001
0226001
0257001
0310001
034100
037200
042300
045400
050500
053600
056700
062000
065100
070200
073300
076400
101500
104600
107700
113000
116100
1212001
1243001
127400 I
1325001
1356001
1407001
1440001
11471001
11522001
11553001

I
1600
3200
4800
6400
8000
9600
11200
12800
14400
16000
17600
19200
20800
22400
24000
25600
27200
28800
30400
32000
33600
35200
36800
38400
40000
41600
43200
44800
46400
48000
49600
51200
52800
54400
56000

A
B

C
D
E
F

G
H

I
J

K
L
M
N
0
P

Q
R
S
T
U

w
X
Y

$
?

0
1
2
3
4
5

0000501
000120 I
0001701
0002401
0003101
0003601
0004301
0005001
0005501
0006201
0006701
0007401
0010101
0010601
0011301
0012001
0012501
0013201
0013701
0014401
0015101
0015601
10016301
10017001
10017~01

10020201
10020701
1002140 I
10022101
10022601
10023301
10024001
10024501
10025201
!0025701
D-2

I
40
80
120
160
200
240
280
320
360
400
440
480
520
560
600
640
680
720
760
800
840
880
920
960
1000
1040
1080
1120
1160
1200
1240
1280
1320
1360
1400

I
I
I
I
I

A
B

C
D
E

F
G
H
I

J
K
L
M
N

o
P
Q
R

S
T

u
V

w
X
Y

z
$
?

o
1
2
3
4
5

000001
000002
000003
000004
000005
000006
000007
000010
000011
000012
000013
000014
000015
000016
000017
000020
000021
000022
000023
000024
000025
000026
000027
000030
000031
000032
000033
000034
000035
000036
000037
000040
0000411
0000421
0000431

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

Radix-50 and ASCII Character Sets
'rable D.. 1:

Rad:ix-50 Character Positions (Cont.)

-1-- - -" - - -+- - - - - -+- - - - - - - -+- - - - - - -+- - '. - - -+- - - - - - - -+- - - - - -+- - - - - -+- - - - --+

1 Single 1
1
I
I
1
1
I
1
I or 1st I
I
I 2nd I
I
I 3rd 1
I
1 Char. I OctallDec:imal 1 Char. 1 OctallDecimal 1 Char. 1 Octal I Dec.
-1-- - _ .. - - -+- - - - - -+- - - - - - - -+- - - - - - -+- - - - - -+- - - - - - - -+- - - - - -+_ .. - - - -+- - - - --+
1
6 11604001
57600 I
6
10026401
1440 I
6 10000441
36 1
1
7 1163500 I 59200 1
7
1002710 I
1480 1
7 10000451
37 1
1
8 1166600 1 60800 I
8
1002760 I
1520 I
8 10000461
38 I
1
9 11717001 624001
9
10030301
15601
9 10000471
391
+- - - .. - - -+- - - - - -+- - - - - - - -+- - - - - - -+- - - - - -+- - - - - - - -+- - - - - -+- - - - - -+- - - - --+

three-character string is stored left to right in the Radix-50 word.
For example, given the ASCII string X2B, you can compute the Radix-50
representation as follows:

= l13000(octal)

2
B

002400(octal)

= 000002(octal)

X2B = l15402(octal)
(Note that addition is done in octal.)
~ro

represent a three-character string in Radix-50 format:
o

place the first character of a string (or a single character)
in the leftmost position of the Radix-50 word. Thus, for the
character x, multiply its representation 30(octal) by 50 2 to
give l13000(octal), the value shown in Table 0-1 for X when it
is the first character.
A

Place the second character in a string in the next position tc
the right. For the character 2 (in the second position),
multiply its representation 40(octal) by 50 1 to give 002400,
the value shown in Table 0-1 for 2 when it is the second
character.
A

Place the third character in the rightmost position. For the
character B (in the third position), multiply its
representation by 50 O (which is 1) to give 000002, the value
shown in Table 0-1 for B when it is the third character.
A

To get the full octal value of the Radix-50 word, add the value of
each character by its position in the string.

0-3

Radix-50 and ASCII Character Sets
ASCII Character Codes
Table 0-2 lists the ASCII characters and their decimal and octal
values.
Table D-2:

ASCII Character Codes

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

ASCII
I
+- - - - - - - - -+- - - - - - -+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
Decimal +I _______
Octal +I ____________
Character +I ______________ Remarks
+I _________
+
D

o
1
2

3
4
5
6
7

8
9
10
11
12
13
14
15
16
17

18
19
20
21
22
23
24
25
26
27
28

29
30
31
32
33

______________________

000
001
002
003
004
005
006
007
010
011
012
013
014
015
016
017
020
021
022
023
024
025
026
027
030
031
032
033
034
035
036
037
040
041

NUL
SOH
STX
ETX
EOT
ENQ
ACK
BEL
BS
HT
LF
VT
FF
CR
SO
SI
OLE
DC1
DC2
OC3
DC4
NAK
SYN
ETB
CAN
EM
SUB
ESC
FS
GS
RS
US
SP

Null, FILL character
CTRL/A
CTRL/B
CTRL/C
End of transmission, CTRL/O
CTRL/E
CTRL/F
Bell, CTRL/G
Backspace, CTRL/H
Horizontal tab, CTRL/I
Line feed, CTRL/J
vertical tab, CTRL/K
Form feed, page, CTRL/L
Carriage return, CTRL/M
CTRL/N
CTRL/O
CTRL/P
CTRL/Q*, XON
CTRL/R
CTRL/S**, XOFF
CTRL/T
CTRL/U
CTRL/V
CTRL/W
CTRL/X
CTRL/Y
CTRL/Z, end of file
Escape***
File Separator
Group Separator
Record Separator
Unit Separator
Space or blank
Exclamation point

D- 4

Radix-50 and ASCII Character Sets
Table D-2:

ASCII Character Codes (Cont.)

+- - - - - _ .. - -+- - - - - - -+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I Decimal I Octal I Character I
Remarks
+- - - - - _ .. - -+- - - - - - -+- - - - - - - - - - - -+- - - - - - - - - - - ~ - - - - - - - - - - - - - - - - - - - - - - - --+
Quotation mark
34
042
"
Number sign
043
35
#
Dollar sign
36
044
$
Percent sign
045
%
37
Ampersand
046
&
38
Apostrophe
047
39
Left parenthesis
050
40
Right parenthesis
051
41
Asterisk
052
42
*
Plus
053
43
+
Comma
054
44
Hyphen or minus
055
45
Period or decimal point
056
46
Slash
057
47
/
Zero
o
48
060
1
One
061
49
Two
062
2
50
Three
063
51
3
4
Four
064
52
Five
065
5
53
Six
6
54
066
Seven
067
7
55
Eight
070
8
56
Nine
071
9
57
Colon
072
58
Semicolon
073
59
Left angle bracket, "less than"
074
60
<
sign
Equal sign
075
=
61
Right angle bracket, "greater than"
076
62
>
sign
Question mark
077
?
63
@
At sign
100
64
Uppercase A
101
A
65
Uppercase B
B
102
66
Uppercase C
103
C
67
Uppercase D
D
68
104
Uppercase E
E
105
69
Uppercase F
F
106
70
Uppercase G
107
G
71
Uppercase H
H
110
72
Uppercase I
I
III
73
Uppercase J
112
J
74
K
Uppercase K
113
75
L
Uppercase L
114
76

D-5

Radix-50 and ASCII Character Sets
Table D-2:

ASCII Character Codes (Cont.)

+ - - - - - - - - - + - - - - - - - + - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ,+
Remarks
I Decimal I Octal I Character I
I
+ - - - - - - - - - + - - - - - - - + - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ,+
77
115
M
I Uppercase M
78
116
N
I Uppercase N
79
117
0
I Uppercase 0
p
80
120
I Uppercase P
Q
81
121
Uppercase Q
82
122
R
Uppercase R
83
Uppercase S
123
S
84
124
T
Uppercase T
85
125
Uppercase U
U
86
126
V
Uppercase V
87
127
Uppercase W
W
88
130
X
Uppercase X
y
89
131
Uppercase y
90
132
Uppercase Z
Z
91
133
[
Left square bracket
92
134
Backslash
\
93
135
]
Right square bracket
,..
94
136
Circumflex
95
137
Underscore
,
96
140
Grave accent
97
141
a
Lowercase a
98
142
b
Lowercase b
99
143
c
Lowercase c
100
144
d
Lowercase d
101
145
e
Lowercase e
102
146
f
Lowercase f
103
147
Lowercase 9
9
104
150
h
Lowercase h
105
151
i
Lowercase i
106
152
Lowercase j
j
107
153
k
Lowercase k
108
154
1
Lowercase 1
109
155
m
Lowercase m
110
156
n
Lowercase n
111
157
Lowercase 0
0
112
160
Lowercase p
P
113
161
q
Lowercase q
114
162
r
Lowercase r
115
163
s
Lowercase s
116
164
t
Lowercase t
117
165
u
Lowercase u
118
166
v
Lowercase v
119
167
w
Lowercase w
120
170
x
Lowercase x
121
171
Lowercase
y
Y

D-6

Radix-50 and ASCII Character Sets
Table D-2:

ASCII Character Codes (Cont.)

+- - - - - - - - -+- - ~ _ .. - -+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -. - --+
I Decimal I Octal I Character I
Remarks
+- - - - - - - - -+- - - _.. - -+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
z
Lowercase z
122
172
173
Left brace
{
123
174
124
I
Vertical line
125
17!5
}
Right brace ***
126
176
Tilde ***
DEL
Delete
127
177
128
200
Reserved
Reserved
129
201
Reserved
130
202
131
203
Reserved
132
204
IND
Index
20S
133
NEL
New line
134
206
SSA
135
207
ESA
HTS
Horizontal tab set
136
210
137
211
HTJ
138
212
VTS
Vertical tab set
139
213
PLD
Partial line down
PLU
Partial line up
140
214
RI
Reverse Index
141
21S
SS2
Single shift 2
142
216
SS3
Single shift 3
143
217
144
220
DCS
Device control string
PUl
145
221
146
222
PU2
223
STS
147
148
224
CCH
149
225
MW
150
226
SPA
227
EPA
151
230
Reserved
152
Reserved
153
231
Reserved
154
232
155
233
CSI
Control sequence introducer
ST
String terminator
234
156
235
asc
157
158
236
PM
APC
159
237
Reserved
240
160
i
Inverted exclamation pOint
161
241
¢
cent sign
242
162
£
Pound sign
243
163
Reserved
164
244
¥
Yen sign
165
245
Reserved
246
166

D-7

Radix-50 and ASCII Character Sets
Table D-2:

ASCII Character Codes (Cont.)

+ - - - - - - - - - +'- - - - - - - + - - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +

I Decimal I Octal I

Character I

Remarks

+- - - - - - - - -+- - - - - - -+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
247
section sign
167
168
250
General currency sign
169
251
Copyright sign
252
170
Feminine ordinal indicator
«
253
171
Angle quotation mark left
172
254
Reserved
255
Reserved
173
256
174
Reserved
175
257
Reserved
o
260
Degree sign
176
261
Plus/minus sign
177
±2
Superscript 2
178
262
263
Superscript 3
179
264
Reserved
180
265
Micro sign
181
182
266
paragraph sign, pilcrow
183
Middle dot
267
184
Reserved
270
185
271
Superscript 1
186
272
Masculine ordinal indicator
273
187
Angle quotation mark right
188
274
Fraction one quarter
275
189
Fraction one half
190
276
Reserved
191
277
Inverted question mark
l
300
192
A
Uppercase A with grave accent
A
193
301
Uppercase A with acute accent
302
194
A
Uppercase A with circumflex accent
303
195
Uppercase A with tilde
A
304
A
196
Uppercase A with diaeresis or

197
198
199
200
201
202
203

305
306
307
310
311
312
313

204
205
206
207

314
315
316
317

208

320

A
lE.

E
E
E
I
f
i
I

umlaut mark
Uppercase A with ring
Uppercase A wi.th dipthong
Upp~rcase C with cedilla
Uppe rcase. E with grave accent
Uppercase E with acute accent
Uppercase E with circumflex accent
Uppercase E with diaeresis or
umlaut mark
Uppercase I with grave accent
Uppercase I with acute accent
Uppercase I with circumflex accent
Uppercase I with diaeresis or
umlaut mark
Reserved

D-8

Radix-50 and ASCII Character Sets
Table 0-2:

ASCII Character Codes (Cont.)

+- - - - - _ .. - -+- - - - - - -+., - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I Decimal I Octal I Character I
Remarks
I
+ - - - - - - .. - - + - - - - - - - + ., - - - - - - - - - - - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
209
321
Uppercase N with tilde
N
210
o
322
Uppercase 0 with grave accent
211
323
Uppercase 0 with acute accent
6
212
324
Uppercase 0 with circumflex accent
6
213
325
5
Uppercase 0 with tilde
214
326
o
Uppercase 0 with diaeresis or
umlaut mark
215
327
Uppercase OE ligature
CE
{3
216
330
Uppercase 0 with slash
217
331
U
Uppercase U with grave accent
(j
218
Uppercase U with acute accent
332
fj
Uppercase U with circumflex accent
219
333
220
.334
Uppercase U with diaeresis or
ti
umlaut mark
221
335
Uppercase Y with diaeresis or
umlaut mark
222
.336
Reserved
223
German lowercase sharp s
.337
P.>
224
340
Lowercase a with grave accent
a
225
341
a
Lowercase a with acute accent
226
342
a
Lowercase a with circumflex accent
227
343
a
Lowercase a with tilde
228
344
Lowercase a with diaeresis or
a
umlaut mark
345
Lowercase a with ring
229
230
Lowercase ae dipthong
346
231
Lowercase c with cedilla
347
Lowercase e with grave accent
232
350
233
351
Lowercase e with acute accent
234
Lowercase e with circumflex accent
352
235
353
Lowercase e with diaeresis or
umlaut mark
236
Lowercase i with grave accent
354
i
237
355
i
Lowercase i with acute accent
238
356
i
Lowercase i with circumflex accent
239
357
1:
Lowercase i with diaeresis or
umlaut mark
240
360
Reserved
241
Pi
Lowercase n with tilde
361
242
Lowercase 0 with grave accent
362
o
Lowercase 0 with acute accent
243
363
6
244
364
Lowercase 0 with circumflex accent
6
245
Lowercase 0 with tilde
365
5

D-9

Radix-50 and ASCII Character Sets
Table D-2:

ASCII Character Codes (Cont.)

+- - - - - - - - -+- - - - - - -+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -,+
I Decimal I Octal I Character I
Remarks
+- - - - - - - - -+- - - - - - -+- - - - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -,+
Lowercase o with diaeresis or
246
366
0
umlaut mark
(E
367
Lowercase oe ligature
247
248
370
Lowercase o with slash
0
Lowercase u with grave accent
249
371
u
250
372
Lowercase u with acute accent
ii
Lowercase u with circumflex accent
251
373
11
252
374
Lowercase u with diaeresis or
ii
umlaut mark
253
375
Lowercase y with diaeresis or
Y
umlaut mark
376
Reserved
254
255
377
Reserved
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I *
CTRL/Q, or XON, resumes output if the TTSYNC terminal
I
characteristic is set.
I ** CTRL/S, or XOFF, stops output if the TTSYNC terminal
I
characteristic is set.
I *** ALTMODE(ASCII 125) or PREFIX (ASCII 126) keys, which appear on
I
some terminals, are translated internally into ESCAPE if the
I
ALT MODE terminal characteristic is set.
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

0-10

Appendix E
Device Handler Index

Table E-l lists the handler indexes for each device type used on
RSTS/E.
The handler index is an internal index into system device
tables that the system uses to identify device families.
For example,
the handler index is used in SPEC% functions to ensure that the system
operates on the correct device.
Table E-1:

Handler :Index

+- - - - - - .. +- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I Index I
Device
I
+- - - - - - .. +- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I
I
I
I
I
I
I

All disks

Terminals

DEC tape

Line Print.ers

paper Tape Readers

Paper Tape Punches

Card :Readers

Magnetic Tapes

Pseudo Keyboards

Flexible Diskettes [RX01, RX02]

RJ2780

Null Device

E-l

Device Handler Index
Table E-l:

Handler Index (Cont.)

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

I Index I
Device
I
+- - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+
I
I
I
I
I
I
I
I

DMCll/DMRll DDCMP Interface

KMCll

IBM Interface

DMPll/DMVll

I
I
I
I
I
I
I
I

+- - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+.

E-2

Appendix F
Monitor Directives

The RSTS/E System Directives Manual describes monitor directives for
MACRO programmers. Many of these directives correspond to SYS calls
, described in Chapter 7 of this manual.
Table F·,l lists the SYS call to FIP codes and the corresponding
monitor directives. For information on the use of these directives,
see the RSTS/E System Directives Manual.
Table F-l:
f

Monitor Directives

+ ______ .' _____ .. ___ + ________

_+ ______________

I
I Function I
I MACRO Mnemonic I Code(FO) I

______

..;

__________________

Function Name

+- - - - - _.' - - - - - .. - - -+- - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

UU.TB3

-29

Get monitor tables - part III.

UU.SPL

-28

Spooling.

UU.DMP

-27

Snap shot dump.

UU.FIL

-26

File utility functions.

UU.ATR

-25

Read/Write file attributes; Read pack
attributes; Read/Write/Delete account
attributes

I UU.CCL
I
I (.FSS)
I
I (.SET)

-24

Add/delete CCL command.

-23

Terminating file name string scan.

-22

Set special run priority.

-21

Drop/regain (temporary) privileges.

-20

Lock/unlock job in memory.

,I (.SET/.CLEAR)
I
I (.SET/.CLEAR)

F-I

Monitor Directives
Table F-l:

Monitor Directives (Cont.)

+- - - - - - - - - - - - - - - -+- - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ~ - - - - - --+
I
I Function I
I
I MACRO Mnemonic I Code(FO) I
Function Name
I
+- - - - - - - - - - - - - - - -+- - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

UU.LOG

-19

Set number of logins.

UU.RTS

-18

Add/Remove/Unload run-time system;
Add/Remove/Unload resident library;
Create dynamic region.

UU.NAM

-17

Name run-time system.

UU.DIE

-16

Shut down system.

UU.ACT

-15

Accounting dump.

UU.DAT

-14

Change system date/time.

UU.PRI

-13

Change priority/run burst/job size.

UU.TB2

-12

Get monitor tables - part II.

UU.BCK

-11

Change file backup statistics.

( . FSS )

-10

File name string scan.

UU.HNG

-9

Hang up a dataset.

UU.FCB

-8

Get open channel statistics.

-7

Enable CTRL/C trap.

UU.POK

-6

Poke memory.

( . SPEC)

-5

Broadcast to terminal.

( . SPEC)

-4

Force input to terminal.

UU.TBI

-3

Get monitor tables - part I.

UU.NLG

-2

Disable logins.

UU.YLG

-1

Enable logins.

UU.PAS

Create user account.

UU.DLU

Delete user account.

Reser.;ved.
F-2

I
I
I
I

I
I

I
I
I
I
I
I

I
I
I
I
I
I
I
I
I

Monitor Directives
Table F-l:
~.-

Monitor Directives (Cont.)

- - - - - - - - - - - - - - -+_ .. - - - - - - - -+- - - - - - .. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

I
I Function I
I MACRO Mnemonic I Code(FO) I

Function Name

+- - - - - - - - - - - - - - - -+_ .. - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

UU .MN'r

Disk pack status.

UU.LIN

UU.BYE

Logout.

UU .AT~r

Attach; Reattach; Swap console.

UU.DET

Detach.

UU.CHU

Change quota/expiration
date/password;Set password; Kill job;
Disable terminal.

UU.ERR

Return error messages.

UU.ASS ( . UUO)
UU.ASS ( . ULOG)

Allocate/Reallocate device;
Assign user logical.

UU.DEA ( . UUO)
UU.DEA ( . ULOG)

Deallocate device;
Deassign user logical.

UU.DAI., ( . UUO)
UU.DAL ( . ULOG)

Deallocate all devices;
Deassign all user logicals.

UU. ZER

Zero a

UU.RAD

Read/Read and reset accounting data.

UU.DIR

Directory lookup on index; Special
magnetic tape directory lookup.

UU.TRM

Set terminal characteristics.

UU.LOK

Disk directory lookup on file name;
Disk wildcard directory lookup.

UU.CHE

Enable/disable disk caching.

UU.CNV

Convert date and time.

UU.SLN

Add/Remove/Change/List logical names.

( .MESAG)

Message send/receive.

F-3

device~

Monitor Directives
Table F-l: Monitor Directives (Cont.)
+ ________________ + __________ + ________________ '. _______________

_______

I
I Function I
I
I+ _____________
MACRO Mnemonic +I __________
Code(FO) +I ________________________________________
Function Name
I
a

I UU.SWP

I
I UU.JOB
I

I UU.PPN
I

Add/remove/list system files.

Create a job.

Wildcard PPN lookup.

I
I

I
I
I
I

I UU.SYS

Return job status.

I
I

I
I UU.PRV

Set/Clear/Read current privileges.

I UU.STL

Stall/Unstall system.

I
I UU.3PP
I

Third party privilege check.

Check file access rights; Convert
privilege name to mask; Convert
privilege mask to name.

I UU.CHK

I
I
I UU.ONX
I
I UU.CFG
I
I
I
I -

Open next disk file.

Set device/line printer
characteristics; Set system defaults;
Load/Remove monitor overlay code.

I
I
I
I
I

I
I
I
I
I
I
I
I
I

PEEK function.
+- - - - - - - - - - - - - - - -+- - - - - - - - - -+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --+

F-4

Appendix G
EMT Logger Send/Receive Calls

EMT 1099in9 is an optional feature that provides a "window" on the
, process by which time-sharing jobs request and receive services from
~ the RSTS/E monitor.
Thus, EMT logging lets you gather information
about the activity on your system.
For example, you might want to
know the number of logins on a particular terminal, how many files are
accessed on a certain drive, or which nonresident FIP overlays get the
heaviest use.
Such information can help you "tune" a system for
improved performance, identify bottlenecks, establish charging
algorithms, and watch for potential security problems.
To use EMT 1099in9, you must:
o

Include optional code in your monitor at system installation
time.
See the RSTS/E System Installation and update Guide
for more information.

Write a program to process the data extracted by the monitor
code.
This program retrieves extracted data by using
send/receive calls, which are described in Chapter 8 of this
manual. A demonstration program (EMTCPY.BAS) is included in
the Unsupported utility system program package.
This
unsupported program illustrates sample techniques for
retrieving EMT logging data.

EMT logging provides information on time-sharing activity in terms of
what the monitor sees.
Thus, the data returned to your logging
program is in terms of FIRQB and XRB contents, regardless of the
language your program is written in.
See the RSTS/E System Directives
Manual for information on the FIRQB and XRB.
EMT logging can affect system performance.
The impact is variable,
and depends upon which EMTs you decide to log, for which jobs yo~ log
them, and how much processing your logging program attempts to do for
each EMT.

G-l

EMT Logger Send/Receive Calls
Note that a feature patch is available that allows you to spe9ify
which EMTs are to be logged.
See the RSTS/E Maintenance Notebook for
details.
This appendix describes the use of parameters and other features of
the send/receive calls that are specific to an EMT logger.
For more
information on EMT logging see the RSTS/E System Manager's Guide.

EMT Logging and Send/Receive
Writing an EMT logging program requires the use of several
send/receive calls.
The declare receiver call designates your program
as a receiver and tells the monitor to activate EMT logging and build
EMT data packets for selected directives.
The receive local data
message call retrieves EMT data packets from the monitor.
The remove
receiver call removes your program from the monitor's local receiver
table and deactivates EMT logging.
An EMT logger program can receive messages from normal senders as well
as from the monitor.
(The receive call allows this selection; see
Chapter 8.) Your EMT logger program should periodically check for such
messages.
For example, the SHUTUP program sends a message to your
program before shutting down the system after normal time-sharing jobs
are logged out or killed.
This notification lets your program do any
necessary cleanup and exit under its own control.

Declaring an EMT Logger
Your EMT logger program must declare itself as a receiver to receive
messages from the monitor.
The monitor recognizes an EMT logging
receiver by the local object type 2 in byte 21 of the declare call;
see Chapter 8.
You also need to specify the following parameters when you declare an
EMT logging receiver:
o

Message maximum (byte 25) - Indicates the maximum number of
messages that the monitor queues for the EMT logger.
(Message maximum pertains only to messages sent by other
programs using normal send/receive.)

Packet maximum (bytes 27-28) - Indicates the maximum number
of EMT data packets that the monitor queues for the EMT
logger.
If your program cannot keep up with the data traffic
and this maximum is exceeded, EMT data packets are missed
(that is, not created or queued).
EMT data packets may also
be missed if not enough XBUF is available to hold additional

G-2

EMT Logger Send/Receive Calls
packets.
Note that a count of missed EMTs is one of the
parameters returned to your EMT logger program on each
receive.
o

Packets per message (byte 30) - Indicates the number of EMT
data packets for the monitor to consider a complete message.
Note that this value should not be greater than the packet
maximum specified in bytes 27-28. When your program issues
the receive call, the monitor immediately returns any packets
that are pending, regardless of this parameter.
If no
packets arE~ pending, and the receive call specifies a sleep
interval, the monitor does not awaken your job until either
the number of packets specified by this parameter are queued
or the sleep expires.
This lets your program control how
often it is awakened to handle EMT packets and process more
than one packet per receive.
Both operations can reduce
overhead.

The declare receiver call for an EMT logger has the following format.
An asterisk (*) identifies fields specific to an EMT logger declare
call.
other fields are more fully described in Chapter 8.
Note that
this form of declarE~ receiver requires SYSIO privilege.
Data Passed
Bytes

Meaning

CHR$(6%), the SYS call to FIP.

CHR$(22%), the send/receive function code.

CHR$(l%), the declare receiver subfunction code.

CHR$(O%), reserved; should be O.

5-10

The receiver name.

11-20

CHR$(O%), reserved; should be O.

21*

CHR$(2%), the object type code for an EMT logger.

CHR$(3%), the value for local, privileged senders (SEND
privilege required).

23-24

CHR$(O%), reserved; should be O.

CHR$(M%), the message maximum.
This parameter pertains only
to normal messages that are sent to your EMT logger.

CHR$(O%), the inbound link maximum; should be 0 for "no
network links."
G-3

EMT Logger Send/Receive Calls
27-28*

CHR$(P.MAX%) + CHR$(SWAP%(P.MAX%», the maximum number of
EMT data packets that can be queued at one time.

CHR$(O%), the outbound link maximum; should be 0 for "no
network links."

30*

CHR$(P.MES%), the number of packets that the monitor packs
into an EMT logger message before waking up the receiver.

31-34

CHR$(O%),

CHR$(R%), the receiver 1D block (RIB) number.

36-40

CHR$(O%), reserved; should be O.

reserved; should be O.

Data Returned
No meaningful data is returned.
Possible Errors
See the Declare Receiver call in Chapter 8.

Receiving an EMT Logger Message
An EMT logger program asks for messages from the monitor by using a
receive call in the following format.
An asterisk (*) identifies
fields specific to an EMT logger receive call.
Other fields are more
fully described in Chapter 8.
Note
The data returned to your EMT logger program depends
on the internal functioning of the monitor.
For this
reason, both the format and meaning of data returned
are subject to change in future releases of RSTS/E.
Data Passed
Meaning

Bytes
1

CHR$(6%), the SYS call to FIP.

CHR$(22%), the send/receive function code.

CHR$(2%), the receive subfunction code.
G-4

EMT

Logger Send/Receive Calls

CHR$(4%), for L%.
(N% and S% should be 0; T% has no effect
for an EMT logger.)

CHR$(O%), to select the monitor as the sender (with byte 6).

CHR$(-l%), to select the monitor as the sender (with byte
5)•

7-10

Reserved; should be O.

CHR$(C%), the channel number for the I/O buffer to receive
messages.

CHR$(O%), reserved; should be O.

13-14

L%, the maximum message length (in bytes) for this receive,
in the form CHR$(L%) + CHR$(SWAP%(L%».

15-16

0%, the offset from the start of the buffer, in the form
CHR$(O%) + CHR$(SWAP%(O%».

17-26

CHR$(O%), reserved; should be O.

27-28

T%, the sleep time in seconds, in the form CHR$(T%) +
CHR$(SWAP%(T%».

29-34

CHR$(O%), reserved; should be O.

CHR$(R%), the receiver ID block (RIB) number for this
receive.

36-40

CHR$(O%), reserved; should be O.

Data Returned
Bytes
1-2

Meaning
Not meaningful; should be ignored.

CHR$(-l%), the local data message subfunction code.

CHR$(O%), the sending job (the monitor is the sender).

5-6+

0%, the sender's project-programmer number (the monitor is
the sE~nde r ) .

CHR$(O%), the sender's keyboard number (the monitor is the
sender).

Not meaningful; should be ignored.

G-S

BMT Logger SendjReceive Calls
9-10

R%, the number of bytes remaining in the data portion of the
message.

11-12

Not meaningful; should be ignored.

13-14

L%, the length of the message (in bytes) transferred to the
buffer.

15-20

Not meaningful; should be ignored.

21-22*

P.REM%, the number of packets remaining in the data portion
of the message.

23-24*

P.EMT%, the number of EMTs missed (due to insufficient
buffer space) since the last receive.

25-26*

P.TRANS%, the number of packets transferred to the buffer.

27-40

Not ~eaningfu1; should be ignored.

Possible Errors
See the receive call, in Chapter 8.

Message Format
The information returned to your EMT logger program by the receive
call consists of parameters and data, as described in Chapter 8. The
data portion of the message consists of packets, each of which
describes a single EMT that the monitor has processed. To minimize
overhead, the monitor packs as many packets as will fit into the
receive buffer and returns them as a single message.
Three special parameters are returned to your EMT logger program:
o

P.REM% - Indicates the number of packets pending but not yet
transferred

P.EMT% - Indicates the number of EMTs that have been missed
(not logged, due to insufficient buffer space) since the last
receive

P.TRANS% - Indicates the number of packets transferred in the
current receive call

These three parameters are returned in bytes 21-26 of the receive
call. The monitor also returns the standard data for all receive
calls; see Data Returned in the preceding section.

G-6

EMT Logger Send/Receive Calls
Each packet in the returned message is a counted string. The first
t~~o bytes of each packet contain the number of bytes in that packet,
not including the two count bytes.
The rest of the packet consists of the following fields:
Root

Context and control information

FIRQB

Data extracted from the calling program's FIRQB

Although the identities and lengths of the fields returned are the
same for all packets, you should code your EMT logger program to
correctly handle the variable format; that is, honor the packet's
count word and the fields' count bytes.
This will make your program
easier to update if the packet format changes in a future release of
RSTS/E.
Figure G-l shows the parts of an EMT packet. Each packet contains a
count field as its first two bytes.
This count specifies the packet's
length, exclusive of the count bytes.
The "parameters" returned by
the Receive call contains a word (P.TRANS%) that gives the number of
packets returned to your buffer.

PACKET'S BYTE COUNT

ROOT DATA

1_:___________F_IRQB_D_A_T_A__________

~
MK-01019-00

Figure G-I:

EMT Data Packet Layout

G-7

EMT Logger SendjReceive Calls
EMT Root and FIROB Fields
This section describes the EMT packet Root and FIRQB fields.
The
packet described here is for a single EMT.
Note that a single receive
may return a variable number of packets to your EMT logging program,
depending on the buffer space you provide for the data portion of the
message.
The EMT Root field contains the following inform'ation:
Bytes

1-2

Meaning
Reserved

Length of FIRQB data field

Length of Root data field

5-6

Packet sequence number

7-8

System date at reception of EMT

9-10

System time at reception of EMT

Seconds until the next minute at reception of EMT

Ticks until the next second at reception of EMT

Calling job number times two

Reserved

IOSTS byte (at directive's completion).
This byte contains
the returned error code.
0 indicates successful completion
with no error.

Function code of the directive.
The function codes have
MACRO mnemonics of the form xxxFQ.
See the RSTS/E System
Directives Manual for a list of function codes.

Reserved

Calling job's keyboard number.
In the case of a detached
job, this byte is the complement of the number of the
keyboard from which the job detached.

19-20

Reserved

21-22

Calling job's PPN

G-8

EMT Logger SendjReceive Calls
23-24

Job's virtual pc. This is the virtual address, in the
user's job space, of the instruction following the EMT
instruction that invoked the call. The pc may be of
interest if the calling program is written in MACRO. The PC
is within the run-time system in the case of BASIC-PLUS.
For example, the PC could equal Program Counter, the
PDP-II's "next instruction" register.

UUO code, if the call was a directive; otherwise 127. The
code has a MACRO mnemonic of the form UU.xxx. See the
RSTS/E System Directives Manual for a list of UUO codes.

Reserved

The EMT FIRQB field contains the following information:
Bytes

Meaning

1-2

Third word of the caller's FIRQB. The first two words of
the caller's FIRQB are not returned since the same
information is returned in the Root field.

3-4

Fourth word of the caller's FIRQB.

27-28

Last word of the caller's

FI~QB.

See the RSTS/E System Directives Manual for more information about the
FIRQB.

Message from SHUTUP
As previously described, the SHUTUP system program sends a normal
local data message to your'EMT logger program before the system is
shut down, and after normal jobs are removed. This message consists
of parameters only (no data), and contains -1 in the first parameter
byte (byte 21 of the returned data) as a flag.

G-9

INDEX

-A-

Abbreviation point
setting for CCL commands, 7-91
Account
charge accounting data to,
7-120
creating, 1-12
managing, 1-17
optimizing user, 1-47
permanent privileges, 7-93
privileges for managing, 1-17,
1-18t
storing information about, 1-12
system, 1-1
zero a, 7-158
Account [0,1], 1-1
contents, 1-2
creating, 1-2
on nonsystem disk, 1-11
Account [1,2], system library,
1-1, 1-2
Account attributes
deleting, 7··87
description, 7-74
writing, 7-05
Account creation
SYS call for, 7-149
Account deletion
SYS call for, 7-158
Account number
specify wildcard, 7-283
Accounting data, 7-210
dump of, 7-120
read, 7-210
read and reset, 7-210
storage, 1-12
A.ddresses
Ethernet, 11-5, 11-7
multicast, 11-5, 11-16
physical, 11-5
/AFTER
PBS data field, 9-14
ANALYS, system program, 7-66
ANSI format, 2-4
buffer size, 2-9
EOF 1a.bel, A-lOt

ANSI format (Cont.)
EOF2 record format, A-lIt
EOV1 label, A-lOt
EOV2 record format, A-lIt
files, A-5
header 1 label, A-7t
header 2 label, A-8t
initializing magnetic tape,
A-13
magnetic tape, A-3, A-5
search for, 2-13
volume label, A-5
ANSI magnetic tape, 2-14
block length, 2-14, 2-15, 2-16
CLUSTERSIZE values, 2-15t
COUNT option, 2-16
data conversion, 2-17
default characteristics, 2-15
file characteristics, 2-14
FILESIZE option, 2-16
format, A-3
multivolume processing, 2-17
opening for input, 2-6
record format, 2-15
RECORDSIZE option, 2-16
ANSI processing, 2-16
data conversion, 2-17
multivolume files, 2-17
writing blocks, 2-16
Application
privilege checking, 1-25
using privileges in writing,
1-23, 1-24
ASCII character codes, D-4t
ASCII control characters
in escape sequence, 4-21
ASCII file specification
PBS data field, 9-20
ASSIGN command, 2-4
Asynchronous completion routine
for asynchronous I/O request,
1-49, 2-37
Asynchronous I/O request
AST completion routine, 1-49,
2-37
for disk, 1-49
for magnetic tape, 2-37

Index-1

Asynchronous I/O request (Cant.)
restriction, 1-49, 2-37
-B-

.BAC file
size, C-24
Backspace
MAGTAPE function, 2-27
BACKUP file, 1-2
Backup statistics
change for file, 7-67
BACKUP system program, 2-1
Bad block
adding to BADB.SYS, 1-6
BADB.SYS file, 1-6
BADB.SYS, bad block file, 1-6,
1-12
BASIC-PLUS, 11-4, 11-8, 11-16,
11-17
errors, C-l
programs
CCL routines, 10-8
control from CCL parser, 10-6
conventions, 10-8
designing to run by CCL
command, 10-1
recompiling, C-24
using CCL commands, 10-3
Batch request
confirming, 9-1
sending, 9-1
SYS call for, 9-1
using print/Batch Services, 9-1
Baud rate, setting, 7-233
Binary data
end-of-file on terminal, 4-10
from keyboard interface, 4-8
Binary file specification
PBS data field, 9-21
Binary input, 4-8
disabled
channel 0, 4-9
CLOSE, 4-10
OPEN, 4-10
WAIT, 4 - 9
WAIT conditions, 4-9
Binary mode
effect of private delimiters,
4-36

Block
file greater than 65535, 7-31,
7-45
file-structured DECtape, 5-1
first word in DECtape, 5-4
length on magnetic tape, 2-13
locked, 1-34
consecutive, 1-36
range, 1- 36
range of, 1-49
releasing, 1- 49
single, 1-36
unlocking, 1-35
logical, 1- 28
reading non-file-structured,
1-29
writing non-file-structured,
1-29
number
negative on TU56 DECtape, 5-2
on DECtape, 5-2
on DECtape, 5-2
partial operations on disk,
1-47
receiver ID, 8-8
writing on DECtape, 5-2
writing on DOS magnetic tape,
2-13
Block mode I/O, 1-56
flexible diskette, 1-52
magnetic tape, 2-4
BLOCK option
for non-file-structured disk,
1-29
BOT (Beginning-of-Tape), A-3
BUFF.SYS file, 1-6
Buffer
assigning for messages, 8-30
cache, 1-40
default length on magnetic tape y
2-23
monitor space, 3-13
quota for DMCll/DMRll, 6-2
receive (DMCll/DMRll), 6-2
size
channel, 4-8
DECtape, 5-1
default for terminals, 4-8
DMCll/DMRll allocation, 6-2
for magnetic tape, 2-9
on DOS magnetic tape, 2-13

Index-2

Buffer
size (Cont.)
specifying a large, 1-30
Buffering
intermediate line printer, 3-10

-cCache
data replacement in, 1-40
data transfers, 1-40
limiting size, 7-251
operation, 1-40
read requests in, 1-42
size, 1-40
space for, 1-41
speeding replacement, 1-43
updating, 1-40
use of small buffer pool, 7-249
Cache buffers, 1-40
list, 1-42
minimum residency, 1-40
Cache cluster
first block, 1-43
last block, 1-43
Cache cluster size, 1-41
cluster allocation, 7-251
default settings, 7-251
setting, 7-249, 7-251
Caching, 1-40
da ta, 1 - 5
disable data, 7-67, 7-250
disable disk, 7-249
disable sequential, 7-67
enable data, 7-67, 7-250
enable disk, 7-249
enable on the system, 1-40
enable sequential, 7-67
marking UFD entry, 1-42
random mode, 1-41
read operations, 1-40
sequential mode, 1-41, 1-42
SYS call for, 7-249
use of XBUF, 7-251
with OPEN MODE, 1-42
with SYS calls, 1-42
write operations, 1-40
Caching parameters
current settings, 7-250
return the current, 7-249
setting, 1-40

Cancel type ahead
SYS call, 4-18
Card reader, 5-6
ASCII codes, 5-6
binary mode, 5-7
binary read mode, 5-8
codes, B-lt
example of read mode usage, 5-9
input operations, 5-6
packed Hollerith read mode, 5-7
punched card codes, B-lt
read operations, 5-6
setting read modes, 5-8
summary of read modes, 5-8
Card reader modes
ASCII, 5-6
binary, 5-6, 5-8
packed Hollerith, 5-6, 5-7
Carriage return
suppress automatic, 4-10
Carrier sense, 11-1
CCL command, 10-1
abbreviation point, 7-91
add, 7 - 89
and BASIC-PLUS commands, 10-3
BASIC-PLUS actions, 10-6
delete, 7 - 89
designing programs to run by,
10-1
/DETACH switch, 10-4
effect on job area, 10-3
parsing, 10-2, 10-4
precedence, 10-2
proper syntax, 10-3
/SIZE switch, 10-3
spaces, 10-6
SYS call to execute, 7-34
validating, 10-2
CCL entry
STATUS variable after, 10-8
Channel, 11-4
Channel buffer size, 4-8
Channels
close all, 7-170
Character
ASCII codes, D-4t
finding Radix-50 value, D-l
integer representation, 7-39f
terminate printing, 3-10
Character input
delimiterless, 7-22

Index-3

Character input (Cont.)
single, 7 - 22
Character set
Radix-SO, 0-1
Checksum, C-24
Circuit counters, 11-17
CLOSE statement, 1-3S, 11-11
OMCl1/0MR11, 6-8
Cluster, 1- 3
device, 1-28
pack, 1-3
Cluster size
cache, l-S, 1-41
cluster allocation, 7-2S1
default settings, 7-2S1
relationship to pack, 1-41
setting, 7-249, 7-2S1
definition, 1-3
directory, l-S
allowed values, l-S
setting, 1- S
pack
allowed values, 1-4
definition, 1-4
setting, 1-4
with data caching, l-S
range
for directory, 1-4t
for disk, 1-4t
for file, 1-4t
UFO, 1- S
CLUSTERSIZE option
ANSI magnetic tape, 2-S, 2-14
for OMC11/0MR11, 6-2
Code
ASCII character, 0-4t
monitor, 1-2
run-time system, 1-2
system initialization, 1-2, 1-8
Collision detection, 11-1
Command
SET/ACCOUNT, 1-12
Connect time, 1-13t
Console keyboard
detaching from, 7-181
establish terminal as, 7-176
exchange ownership of, 7-178
Contiguous file, 1-38, 1-39
conditions of, 1-39
creating, 1-38
creating conditionally, 1-39

Contiguous file (Cont.)
unset, 7-67
Controlled job
creating, 4-40
Controllers, 11-4, 11-S, 11-9,
11-16
OELUA, 11- 4
OEQNA, 11- 4
OEUNA, 11- 4
Ethernet, 11-4
/CONVERT flag
PBS data field, 9-22
/COPIES
PBS data field, 9-22
Core common, 7-26, 7-27
Core common string
get, 7-26
put, 7 - 27
COUNT option
ANSI magnetic tape, 2-16
for non-file-structured
magnetic tape, 2-23
Counters
circuit, 11-17
circuit counters, 11-4
line, 11-17
line counters, 11-4
CPU time, 1-13t
allocating, 7-124
run burst, 7-124
/CPU_LIMIT
PBS data field, 9-1S
Crash
saving information after, 1-7
CRASH.SYS file, 1-7
estimating size, 1-7
CSPLIB.LIB
description, 1-8
with system programs, 1-8
CTRL/C
enable trapping, 7-137
input from a terminal, 7-139
protecting program from aborts,
7-138
CTRL/O
cancel effect on terminal, 7-18
CTRL/R
disable, 7-238
enable 8 7-238
CTRL/T
disable, 7-238

Index-4

CTRL/T (Cont.)
enable, 7-238
Cursor control
on V'I'lOO, 4-24
on V'I'52, 4-24
CVT functions, 7-40

-D-

Data
forced to disabled terminal,
7-143
forced to hung up modem, 7-143
to a disabled terminal, 7-141
to a hung up dataset, 7-141
Data area
extract string from, 7-26
load a string, 7-27
Data caching, 1-5, 1-40
See also Caching
disable, 7-250
enable, 7-250
mode, 1-42
modify, 7-249
Data field layout, PBS, 9-7
Data format
directory lookup, 7-217
for FIP SYS calls, 7-37
Data link layer, 11-2, 11-4,
11-10, 11-16
Data message
send local, 8-13
send local example, 8-33
send local, by job number, 8-16
send local, by logical name,
8-16
Data transfers
reducing on disk, 1-40
scheduling on disk, 1-40
Data transmission
disable, 6-8
Data values
summary of Send/Receive, 8-40
Dataset
data to a hung up, 7-141
hang up a, 7-132
Date changer, 7-122
Date conversion
SYS call for, 7-253

DCL
precedence of CCL commands,
10-2
DDB information, 7-136
DDCMP, 6-1
restart, 6-2
Deallocate a device
SYS call for, 7-203
Deallocate all devices
SYS call for, 7-205
Deassign user logical
SYS call for, 7-203
Declare receiver
example, 8-33
SYS call for, 8-1
Declare receiver SYS call, 8-4
access control field, 8-11
buffer space for messages, 8-12
local object types, 8-11
multiple receiver ID blocks,
8-8
queued message limit, 8-12
receiver names, 8-9
DECnet/E, 8-1
Ethernet, 11-2, 11-5
in point-to-point configuration,
6-1
logical links, 8-4
Network Service Protocol (NSP),
6-1
SYS calls, 8-1
DECtape, file-structured, 5-1
block, 5-1
processing, 5-1
RECORDSIZE option, 5-1
DECtape, non-file-structured, 5-2
processing, 5-2
writing files, 5-2
DECtape, TU56, 5-1
access time, 5 - 2
access to, 5-2
block number, 5-2
buffer size, 5-1
file opened on, 5-1
first word in block, 5-4
format, 5-4f
link pointers, 5-2
negative block number, 5-2
physical blocks on, 5-2
programming considerations, 5-1
protection codes, 5-4

Index-5

DECtape, TU56 (Cont.)
record number, 5-2
system processing of, 1-6
writing blocks on, 5-2
zero device SYS call, 7-208
/DELETE flag
PBS data field, 9-22
Deleted Data Mark, 1-53, 1-55
writing, 1-56
Delimiter
RUBOUT as, 4-21
Delimiter, private, 7-237
Delimiterless character mode,
7-22
Density
changing default, 2-28
magnetic tape, 2-22
magnetic tape defaults, 2-3
set with MAGTAPE function, 2-28
Detach job
SYS call to, 7-180
/DETACH switch, in CCL command,
10-4
Detached job
attach to terminal, 7-181
Device
access by logical name, 7-255
allocate a, 7-197
assign user logical, 7-201
deallocate a, 7-203
entering logical name, 7-202
handler index, E-lt
nonphysical, 4-37
See also Pseudo keyboard
null, 1-59
reallocate a, 7-197
setting characteristics, 7-305
zero (initialize), 7-206
Device cluster
accessing, 1-28
size, 1-28
specifying number, 1-28
Device time, 1-13t
Device, XM:, 6-1
Devices
deallocate all, 7-205
deassign all, 7-170
Dial-up line
connecting, 7-132
disconnecting, 7-132
hanging up a, 4-20

Dial-up line (Cont.)
lost connection, 7-177
Digital Data Communications
Protocol, DDCMP, 6-1
Directory
default file placement, 1-43,
1- 44.
entries for tentative files,
1-39
organization, 1-47
placing file at beginning, 1-44
placing file at end, 1-43
reducing fragmentation, 1-47
reducing searches on, 1-47
setting cache clusters, 7-249
speeding access to, 1-43
Directory lookup calls, 7-218
data format, 7-218
data returned in, 7-218
disk wildcard, 7-227
file name on disk, 7-225
on index, 7-220
on magnetic tape, 7-222
tape rewind, 7-223
Disk
as swap file, 7-270
change logical names, 7-262
directory lookup by file name,
7-225
extending file update, 1-49
handler index, 1-49
non-file-structured
accessing logical block 0,
1-30
allocating drive, 1-32
default characteristics,
1-29t
opening, 1-27
privilege and access, 1-31
non-file-structured processing,
1-27
nonsystem, 1-11, 1-14
optimization, 1-46
partial block operations on,
1-47
reducing data transfers, 1-40
scheduling data transfers, 1-40
simultaneous access, 1-45
special function SPEC%, 1-49
system, 1-14
update statistics on, 7-170

Index-6

Disk (Cont.)
wildcard directory lookup,
7··227
Disk caching
disabling, 7-249
enabling, 7-249
Disk file
appending data to, 1-37
creating, 1- 32
See also File
extending, 1-36, 1-38
multi-user access, 1-34
no supersede, 1-40
open in default mode, 1-34
opening next, 7-302
preextending, 1-47
reading and writing, 1-34
updating, I·· 34
Disk pack
status, 7-160
Disk quota
setting, 7 -149
SYS call to change, 7-183,
7··187
Disk storage
allocating, 1 .. 3
quota, 1-13t
Diskette, 1-52
See also Flexible diskette
DMCll/DMRll
access to, 6-1
buffer quota, 6-2
CLOSE statement, 6-8
CLUSTERSIZE value, 6-2
count and status information,
6-4 to 6-6
description, 6-1
disable data transmission, 6-8
DTR (Data Terminal Ready), 6-1
effect on sleeping job, 6-3,
6-7
enable data transmission, 6-1
errors, 6-3, 6-4, 6-8
establish operating mode, 6-1
failure in physical link, 6-4
FILESIZE value, 6-2
full duplex mode, 6-2
GET statement on, 6-3
half duplex mode, 6-2
I/O buffer size, 6-3
MODE value, 6-2

DMCll/DMRll (Cont.)
PUT statement, 6-7
receive buffers, 6-2
RECORD option, 6-3
RECORDSIZE value, 6-3
using in point-to-point, 6-1
DOS format, 2-4
buffer size, 2-9
initializing magnetic tape,
A-13
magnetic tape, A-2
contents of label, A-3
data records, A-2
search for, 2-13
DOS format label, A-3t
protection code, A-3
DOS label record
example of reading, 2-42
DOS magnetic tape
block length, 2-13
buffer size, 2-13
opening for input, 2-6
processing files, 2-13
writing blocks, 2-13
DSKINT initialization option, 1-6,
1-11
DTR, Data Terminal Ready, 6-1,
6-8
Dump, snap shot
analyzing, 7-66
SYS call for, 7-66
Dynamic region
create, 7 -114
-E-

Echo
disable on terminal, 7-21
enable on terminal, 7-20
unsolicited data, 7-30
Echo control mode
character set, 4-13t
disabling, 4-12
hard-copy terminal, 4-19
operations, 7-30
parity bit in, 4-12
terminal, 4-11
EMT logging, G-l to G-7
and declare receiver SYS call,
G-4
and receive SYS call, G-4

Index-7

EMT logging (Cont.)
and send/receive, G-2
data packet layout, G-7f
data packets, G-2
declaring an EMT logger, G-2
message format, G-6
message from SHUTUP, G-7
message maximum, G-2
packet maximum, G-2
packets per message, G-2
parameters passed, G-2
parameters returned, G-6
End-of-Volume Labels
MAGTAPE function, 2-35
writing, 2-35
EOF, 2 -13
marker, A-5
record format, A-lOt, A-lIt
tape mark, 2-13
write with MAGTAPE function,
2-27
EOT (End-of-Tape)
logical, 2 -11
marker, 2-19
processing, 2-19
writing logical, 2-19
EOV, A-5
record format, A-lOt, A-lIt
.ERR file, 1-2
ERR variable, C-2
ERR. ERR file, 1-7
ERRDIS error report, for magnetic
tape parity errors, 2-39
Error
DMCl1/DMR11 indications, 6-4
severity of, C-2
Error Condition Acknowledged
MAGTAPE function, 2-35
Error handling, magnetic tape,
2-38 to 2-40
Error message file
extracting data from, 7-195
Error messages, C-1
abbreviations in descriptions
of, C-3t
BASIC-PLUS-2, C-21t to C-23t
file of, 1-7
non-trappable, C-4t
nonrecoverable, C-2, C-15t to
C-21t
number, C-3

Error messages (Cont.)
recoverable, C-2, C-5
return, 7 -195
severity standards, C-2, C-3t
user recoverable, C-5t to C-15t
with multiple meanings, C-3
Error trapping, C-1
exceptions, C-3
exceptions to, C-2
Errors
BASIC-PLUS, C-1
DMC11/DMR1l, 6-3
magnetic tape, 2-38 to 2-40
nontrappable in recoverable
class, C-5
RSTS/E, C-1
ESC character
as a delimiter, 4-22
recogition as a delimiter, 4-29
system translation of, 4-29
ESC SEQ mode, 4-22
terminal in, 4-29
Escape sequence, 4-23
ASCII control characters in,
4~22

characters within, 4-22
data conversion in, 4-22
for VT100, 4-24
for VT200-family, 4-24
input, 4-22, 4-29
interpreting, 4-22
key compatiblity, 4-30
mode setting, 4-29
output, 4-23, 4-29
passed to program, 4-28
received by program, 4-29
set special, 7-237
system processing, 4-30
system processing on input,
4 29
terminating, 4-28
terminators, 4-31t
to a terminal, 4-23
VT100 screen control, 4-25
VT200 screen control, 4-25
Ethernet, 11-1
addresses, 11-5, 11-7
BASIC statements, 11-8
carrier sense, 11-1
channel, 11-4
CLOSE statement, 11-11

Index-8

Ethernet (Cont.)
collision detection, 11-1
controllers, 11-4, 11-5, 11-9,
11-16
counters, 11-4
data link layer, 11-2, 11-4,
11-10
DECnet/E, 11-2, 11-5
Get Counters, 11-16
GET statement, 11-12
multicast addressing, 11-16
multiple access, 11-1
OPEN statement, 11-8
physical addresses, 11-5
physical link layer, 11-2
portal, 11-4, 11-9
protocol types, 11-4, 11-10
PUT statement, 11-14
system receive buffers, 11-10
Transfer Counters, 11-16
Exit with no prompt
effect of, 7-24
Exit with no prompt SYS call,
7-24
Expiration date
SYS call to change, 7-183,
7-187
Extended buffer pool, 1-7
See also XBUF
Extended Interrecord Gap, 2-39
Extended Set Density Function
MAGTAPE function, 2-36
-F-

FCB information, 7-136
/FEED flag
PBS data field, 9-23
Field
deactivate a, 4-18
declare on terminal, 4-16
declaring a, 4-16
PRINT statement declares a,
4-17
File
add system, 7-267
as swap file, 7-270
associate a run-time system
with, 7-117
BACKUP, 1-2
BADB.SYS, 1-6, 1-12

File (Cont.)
BUFF.SYS, 1-6
caching, 1-42
change backup statistics, 7-67
change RTS name field, 7-67
checking access rights, 7-296
contiguous
advantages, 1-39
conditions, 1-36
creating, 1-38
creating conditionally, 1-39
disadvantages, 1-39
CRASH.SYS, 1-7
creating, 1- 32
creating a large, 1-47
DCL run-time system, 1-2
directory placement, 1-43
. ERR, 1 - 2
ERR.ERR, 1-7
error messages, 1-7
extending, 1-38
extending on magnetic tape,
2-13
greater than 65535 blocks, 7-31,
7-45, 7-71
INIT.SYS, 1-2
magnetic tape labels, 2-4
matching wildcard specification,
7-227
monitor save image library, 1-6,
1-7
multiple reads on, 1-45
multiple writes on, 1-44
open on DECtape, 5-1
OVR.SYS, 1-6
placing at beginning of
directory, 1-44
placing at end of directory,
1-43
positioning frequently accessed,
1-44
preextend on disk, 1-47
privileges for accessing, 1-18,
1-20t
processing contiguous, 1-39
read only access to, 1-44
reading during processing, 1-44
remove system, 7-267
restrictions on large, 7-71
return information on last
opened, 7-31

Index-9

File (Cont.)
return retreival information,
7-67
RMS-11, 2-1
RMS-11 attributes, 7-74
RSTS/E monitor, 1-12
.RTS, 1-2, 1-8
SATT.SYS, 1-3, 1-11
.SIL, 1-2
spooling
SYS call for, 7-61
START. COM, 1-2
swap, 1-9
SWAP.SYS, 1-9
system overlay, 1-6
tentative, 1-39
closing, 1- 39
creating, 1-39
directory entries, 1-39
opening, 1-39
renaming, 1-39
unset contiguous bit, 7-67
File attributes, 7-74
description, 7-74
determine number returned, 7-74
reading, 7-75, 7-81
writing, 7-77
File characteristics
ANSI magnetic tape, 2-14
return for magnetic tape, 2-32
word, magnetic tape, 2-33t
File name, 7-48
directory lookup by, 7-225
file name string scan, 7-48
look up under programmed
control, 7-217
File name string scan, 7-45
FIP call, 7-39
flag word 1, 7-49, 7-49t
flag word 2, 7-51t
for a device name, 7-48
for a file name, 7-48
for a file name type, 7-48
for a protection code, 7-48
for file switches, 7-48
for project-programmer number,
7-48
format, 7-43
terminating conditions, 7-56
File placement, 7-71
resetting bit, 7-67

File placement (Cont.)
setting bit, 7-67
File processor
SYS calls to, 7-25
File size
least significant bits, 7-31,
7-45
most significant bits, 7-31,
7-45
on large file systems, 1-38
updating, 1-38
File statistics, change, 7-128
File type
file name string scan, 7-48
File update
gua rded, 1 - 36
MODE value, 1-35
on disk, 1-34
safeguards for, 1-34
File utility functions, 7-67
File, read only
open for update, 1-45
using, 1-45
File-structured disk, 1-32
See also Disk
File-structu~ed operations
DECtape, 5-1
FILESIZE option
ANSI magnetic tape, 2-5, 2-14,
2-16
for DMC11/DMR11, 6-2
FILESIZE statement
with line printer, 3-3
Fill factor
disable, 7-233
enable, 7-233
FIP
function code, 7-36
SYS calls to, 7-36
unpacking SYS call data, 7-39
use of SYS calls, 7-36
FIP (File Processor), 7-36
FIP SYS call, 7-6t to 7-17t
See also SYS call
data formats, 7-37
integer numbers, 7-41
methods for unpacking data,
7-39
notations, 7-40
project-programmer number, 7-40
references, 7-40

Index-10

PIP SYS call (Cont.)
unpacking data, 7-39
unsigned integer, 7-41
FIT, system program, 1-52
Fixed length records, magnetic
tape, 2-15
Flag word 1, file name string
scan, 7-49t
Flag word 2, file name string
scan, 7-51t
/FLAG_Pl\GES flag
PBS data field, 9-23
Flexible diskette, 1-52
accessing logical record zero,
1·· 56
block mode I/O, 1-52, 1-56
Deleted Data Mark, 1-56
determining density, 1-58
device name, 1-52
handler index, 1-58
interleaving algorithm, 1-52
MODE specifications, 1-52t
mounting new, 1-56
organization, 1-52
partial block operations, 1-56
programming operations, 1-59
RECORD modifiers, 1-56
reformat density, 1-57, 1-58
restrictions on density
reformat, 1-59
sector interleaving, 1-52
sector mode I/O, 1-54, 1-57
single density, 1-54
special function SPEC%, 1-57
writing Deleted Data Mark, 1-56
Flexible diskette drive
modifying actions, 1-56
recomputing density, 1-58
Flexible diskette records
access to, 1-54
double density, 1-54
single density, 1-54
FLINT, system program, 1-52
Form feed
enable, 7-229
line printer, 3-6
suppressing printer, 3-8
Form length
default printer, 3-5
line printer, 3-5
setting printer, 3-5

Format label
ANSI, 2-13
DOS, 2-13
/FORMS
PBS data field, 9-13
Forms
handling nonstandard printer,
3-5
-G-

GET statement, 11-12
for DMCll/DMRll, 6-3
magnetic tape, 2-9
with card readers, S-6
-H-

Handler index, E-lt
disk, 1-50
flexible diskette, 1-58
magnetic tape, 2-38
pseudo keyboard, 4-47
Hardware address
default, 11-5
Header label, magnetic tape, A-5
HDRl, A-7t
HDR2, 2-16, A-8t
Hibernation, 7-181
/HOLD flag
PBS data field, 9-16
-I-

Index value, incrementing, 7-283
INIT.SYS program, 1-2
initialization code, 1-8
Input
echoing of unsolicited, 7-30
force to a terminal, 7-143
INPUT LINE statement
with card readers, 5-6
INPUT MODE values
magnetic tape, 2-7t
INPUT statement
with card readers, 5-6
Integers in SYS calls to FIP,
7-41
Integers, unsigned
convert to two bytes, 7-43
in SYS calls, 7-41

Index-II

Intel Corporation, 11-3
Interjob communication
system calls, 8-1
Internal speed values, 7-233
-J-

Job
attach/reattach, 7-173
awaken a sleeping, 6-3, 6-7,
10-9
changing expansion size, 7-124
clear from monitor table, 7-170
consequences of locking, 7-96
controlled
creating, 4 - 40
CTRL/C trap, 4-44
ensuring command level, 4-44
for pseudo keyboard, 4-37
obtaining output from, 4-40
output from, 4-39
output wait state, 4-41
run a program under, 4-44
controlling, for pseudo
keyboard, 4-37
create logged-in, 7-276, 7-281,
7-282
create logged-out, 7-275, 7-281
create to enter keyboard
monitor, 7-278, 7-282
create to run a program, 7-276,
7-281
declare as message receiver,
8-4
detach, 7-180
determining current access,
1-45
hibernation, 7-181
in receiver sleep, 8-28
initial size, 7-124
interjob communication, 8-1
limiting size, 7-125
lock in memory, 7-96
lock out other, 7-125
logged off the system, 7-119
maximum size, 7-125
network, 8-1
priority in monitor, 7-125
priority word, 7-92
privilege handling, 1-21
at creation, 1-21

Job
privilege handling (Cont.)
at login, 1-21
at logout, 1-22
spa.wned, 1-22
raise priority, 7-92
reatt.ach, 7-176
restrictions on creating, 7-276
return status, 7-285
SYS call to kill, 7-191
terminal reserved to, 4-3
unlock in memory, 7-96
/JOB_COUNT
PBS data field, 9-13
Jobs
local communication between,
8-1
-K-

KCT, 1-13t
Keyboard monitor
default, 1-8
Keypunch, overflow handling, 4-16
Kilo-core tick, 1-13t
-L-

Label
DOS format, A-2
search on magnetic tape, 2-8
writing on magnetic tape, 2-12
Label format
default, 2-11
magnetic tape, A-I to A-II
Label record
default format, 2-8
writE~ a, 2-12
LEOT (Logical End-of-Tape), A-5
Line counters, 11-17
Line feed, suppress automatic,
4-10
Line printer, 3-1
binary output, 3-11
check status, 3-13
clearing buffers, 3-10
controlling with MODE values,
3-2
controlling with RECORD option,
3-8

Index-12

Line printer (Cont.)
delay return for complete
output, 3-10
error handling, 3-13, 3-14
extended software formatting,
3-3
form lengths, 3-5
hardware form feed, 3-6
intermediate buffering, 3-10
lower to upper case, 3-7
LPll characters, 3-1, 3-lt
maintain print position, 3-8
MODE Values, 3-2, 3-3t
modifying operation, 3-8
no stall option, 3-11
nonprinting characters on, 3-1
operation, 3-13
output and small buffers, 3-10
preventing loss of data, 3-13
print over perforations, 3-9
RECORD values, 3-9t
setting characteristics, 7-309
skipping perforation, 3-8
suppressing form feed, 3-8
terminating print operation,
3-10
translating 0 to 0, 3-7
truncating long lines, 3-7,
3-11
using FILESIZE statement, 3-3
Line printer special function
SPEC%, 3-12
Link pointers
negative, 5-2
positive, 5-2
Load address
run-time system, 7-100
Local message, 8-1
parameter area, 8-2
Local object types
declare receiver SYS call, 8-11
Locked blocks
explicit, 1-49
implicit, 1-49
unlocking, 1-35
Locked job
consequences of, 7-96
procedure for, 7-96
/LOG DELETE flag
PBS data field, 9-19

/LOG_FILE file specification
PBS data field, q-17
/LOG_FILE flag
PBS data field, 9-17
/LOG_QUEUE flag
PBS data field, 9-18
/LOG_QUEUE name
PBS data field, 9-19
Logical block, 1-28
reading non-file-structured,
1-29
writing non-file-structured,
1-29
Logical names
access devices by, 7-255
add new, 7 - 257
add system, 7-255
change disk, 7-262
change system, 7-255
deassign, 7-204
entering, 7-202
list system, 7-255
remove, 7-260
remove system, 7-255
SYS call to list, 7-264
table, 7-255
using an underscore, 7-46
LOGIN
system program, 1-12
to create a controlled job,
4-40
Login
disable further, 7-147
enable further, 7-148
set maximum number, 7-148
set to one, 7-147
setting number, 7-98
SYS call for, 7-166
Logout, 7-170
and quota enforcement, 7-170
special shutup, 7-119
SYS call for, 7-119
LOGOUT system program, 1-12
Lowercase characteristics, 7-229
translate to uppercase, 7-229
Lowercase characters
enable, 7-232
LPll characters, 3-lt
LSB (Least Significant Bits),
7-31

Index-13

-M-

MACRO-II, 11-4, 11-8, 11-16,
11-17
Magnetic tape, 2-1
ANSI file, A-Sf
ANSI format, 2-4, A-3
appending data, 2-13
automatic rewind, 2-8
block length, 2-16
default buffer length, 2-23
density, 2-22, 2-28
determining status, 2-31
directory lookup on, 7-222,
7-223
DOS file, A-2f
DOS format, 2-4, A-I
EOF marker, A-S
EOV marker, A-S
error conditions, 2-18 to 2-40
error recovery procedures, 2-19
file-structured processing, 2-2
data handling, 2-4
label handling, 2-4
opening, 2-6, 2-9
format labels, 2-13
GET statement, 2-9, 2-10
handler index, 2-38
initializing, A-13
label
search on OUTPUT, 2-11
label formats, 2-4, A-I to A-II
buffer sizes, 2-9
label search
on INPUT, 2-8
MODE values, 2-6, 2-7t, 2-11t
combining, 2-18
multivolume, 2-3S, A-3
non-file-structured MODE value,
2-22

evaluation, 2-22
non-file-structured processing,
2-2
overriding defaults, 2-3
overriding rewind, 2-8
parity, 2-22
default, 2-3
physical record, definition,
A-I
processing, 2-13
processing end of tape, 2-19

Magnetic tape (Cont.)
read-only access, 2-6
reading data, 2-9
recommended block length, 2-7
record
fix e dIe ng t h , 2 - 1 S, 2 - 1 6
variable length, 2-16
record longer than buffer, 2-23
rewind on CLOSE, 2-8
rewinding, 2-8
selecting label format, 2-4
single volume, A-3
special function SPEC%, 2-37
statements and functions for
accessing, 2-2t
stay bit, 2-23, 2-28
system defaults, 2-3t
tape mark, definition, A-I
volume label for ANSI format
tape, A-S
volume labels, A-6t
write-only access, 2-10
writing a label, 2-12
writing a label record, 2-13
writing data, 2-18, 2-19
writing stream ASCII data, 2-19
zero device SYS call, 7-208
Magnetic tape file
example of reading, 2-41
example of writing, 2~40
extending, 2-13
file-structured, 2-6, 2-10
file-structured CLOSE, 2-20
file-structured OPEN, 2-20
non-file-structured CLOSE, 2-22
non-file-structured OPEN, 2-21
reading non-file-structured,
2-42
terminate processing, 2-20
Magnetic tape file
characteristics word, 2-33t
Magnetic tape header label
HDR1, A-7t
HDR2, 2-16, A-8t
Magnetic tape status word, 2-31t
testing bits, 2-31
Magnetic tape, EOF label
EOF1, A-lOt
EOF2, A-lIt
Magnetic tape, EOV label
EOV1, A-lOt

Index-14

Magnetic tape, EOV label (Cant.)
EOV2, A-lIt
F1agnetic tape,
non-file-structured
COUNT option, 2-23
read and write access, 2-23
record shorter than buffer,
2-23
RECORDSIZE option, 2-23
retaining MODE value after
CLOSE, 2-23
MAGTAPE function, 2-23
backspace, 2-27
codes, 2-25t
End-of-Volume Labels, 2-35
Error Condition Acknowledged,
2-35
Extended Set Density Function,
2-36
format, 2-23
function codes, 2-24
in processing end-of-tape, 2-19
off-line, 2-26
return file characteristics,
2-32
rewind, 2-26
rewind on CLOSE, 2-34
set density, 2-28
set parity, 2-28
skip record, 2-27
SPEC% function alternate, 2-38
summary, 2-24
tape status, 2-31
write tape mark, 2-26
1'1ask
privilege, 1-20
Master terminal, 4-3, 4-4
CTRL/C on, 4-6
CTRL/Z on, 4-6
declaring a field, 4-18
establishing, 4-3
input, 4-5
output, 4-4
r-1emory, 7 - 28
change a word in monitor, 7-140
clearing current program from,
7,·28
escape sequence to, 4-28
exit and clear, 7-28
lock job in, 7-96
poke, 7-140

Memory (Cant.)
protection from CTRL/C abort,
7-138
unlock job in, 7-96
Message
assigning buffer, 8-30
buffer space for, 8-12
data area, 8-2
example of receive, 8-34
local, 8-1
parameter area, 8-2
processing, 8-1
processing large, 8-30
queue to DMC11/DMR11, 6-7
receive a, 8-21
transmission of complete, 7-141
MODE option
terminal control with, 4-7
with paper tape, 5-4
MODE values, card reader, 5-9t
MODE values, disk
access to bad block information,
1-31
appending data, 1-37
conditionally contiguous, 1-39
contiguous file, 1-38
directory placement, 1-43, 1-44
extending files, 1-38
file update, 1-34
guarded update, 1-36
no supersede, 1-40
non-file-structured block
access, 1-31
open for update, 1-45
random caching, 1-42
read only, 1-45
read regardless, 1-44
sequential caching, 1-42
table of, 1-33t
tentative file, 1-39
writing UFD, 1-45
MODE values, flexible diskette,
1-52t
block mode I/O, 1-52
sector mode I/O, 1-54
MODE values, line printer, 3-3t
form feed, 3-6
lower to upper case, 3-7
nonstandard forms, 3-5
skipping perforations, 3-8
suppressing form feed, 3-8

Index-IS

MODE values, line printer (Cont.)
o to 0, 3-7
truncating lines, 3-7
using FILESIZE modifier, 3-4t
MODE values, magnetic tape, 2-6,
2-7t, 2-l1t
ANSI format search, 2-13
appending data, 2-13
CLOSE EOF, 2-13
DOS format search, 2-13
label search, 2-8
non-file-structured, 2-22
override rewind, 2-8
overwrite files, 2-12
rewind on CLOSE, 2-8
tape rewind, 2-8
write label record, 2-12
MODE values, paper tape, 5-4
MODE values, pseudo keyboard
detach job, 4-40
kill job, 4-40
MODE values, terminal, 4-7t, 4-7
echo control, 4-11
prevent interrupt, 4-20
RUBOUT, 4-21
suppress CR/LF, 4-10
transparent control character
output, 4-33
XON/XOFF, 4-21
Modem
data forced to hung up, 7-143
permanent characteristics,
7-237
Monitor
CCL command parsing, 10-2, 10-4
change a word in memory, 7-140
changing date, 7-122
examine with PEEK, 7-319
fixed locations, 7-321t
job priority, 7-125
read/write area, size, 1-7
scheduling jobs, 7-125
Monitor code, 1-2
Monitor directives, F-1t
Monitor file, 1-12
Monitor overlay code
loading, 7-315
removing, 7-315
returning status, 7-315
Monitor queues, 7-125

Monitor save image library file,
1-6
Monitor tables
get - part I, 7-144
get - part II, 7-127
get - part III, 7-58
MOUNT command, 2-4
MSB (Most Sigrrificant Bits), 7-31
Multicast addressing, 11-7, 11-16
broadcast address, 11-5
group address, 11-5
Multiple access, 11-1
Mu1titermina1
input from, 4-5
RECORD values, 4-6t
stall on input, 4-6
Multitermina1 service, 4-3
binary data, 4-4
input, 4-5
operations, 4-18
output, 4-4
rule, 7-19
Multivolume magnetic tape, 2-35,
A- 3

-N-

/NAME
PBS data field, 9-11
Names
reserved, 8-10t
Network calls, 8-1
Network job, 8-1
Network message
parameter area, 8-2
NO ESC SEQ mode, 4-22
NONAME, exit and set up, 7-28
NPR, Non-Processor Request, 6-1
NSP, DECnet/E Network Service
Protocol, 6-1
Null device, NL:
as a debugging aid, 1-59
assigning, 1-59
default buffer size, 1-59
in message send/receive, 1-59
read access, 1-59
sharing, 1-59
write access, 1-59
Number
converting to Radix-50 format,
7··43

Index-16

-0-

ODT
submode, 7-22
Off-line
MAGTAPE function, 2-26
OPEN FOR INPUT statement
file-structured magnetic tape,
2-6, 2-9
OPEN MODE, caching with, 1-42
OPEN statement, 11-8
for DMCll/DMRll, 6-1
for non-file-structured disk,
1-27
Options
BLOCK, 1-29
RECORDSIZE, 1-36
Output buffers
clearing all pending line
printer, 3-10
OUTPUT MODE values
magnetic tape, 2-l1t
Overflow characters
deletion sequence, 4-16
keypunch mode, 4-16
normal mode, 4-16
Overlay code, 1-6
creating a file for, 1-6
OVR.SYS file, 1-6
/OWNER
PBS data field, 9-12
-p-

Pack attributes
returning, 7-79
Pack cluster, 1-3
Pack cluster size, 1-4
See also Cluster size, pack
/PAGE: LIMIT
PBS-data field, 9-14
Paint character, 4-11, 4-17
default, 4-17
Paper tape, 5 .. 4
checking parity, 5-4
controlling parity of data, 5-4
enable punching with generated
parity, 5··4
MODE option in OPEN statement,
5·,4
MODE value actions, 5-4

Paper tape (Cont.)
parity of characters read, 5-4
passing parity with each
character, 5-4
punch operations, 5-4
punching with parity, 5-4
read operations, 5-4
Paper tape punch, 5-4
paper tape reader, 5-4
binary data from, 4-8
Parameter string, 7-36
building, 7-36
portions not used, 7-37
/PARAMETERS
PBS data field, 9-16
Parity
changing default, 2-28
checking on paper tape, 5-4
controlling on paper tape, 5-4
error handling, 2-38
magnetic tape, 2-22
magnetic tape defaults, 2-3
set with MAGTAPE function, 2-28
using RECOUNT to check for bad
flag, 5-4
Parity bit
in echo control, 4-12
output
generating, 7-235
setting, 7-235
password, 1-12, l-13t
keeping confidential, 7-21
storage, 1-14
SYS call to set, 7-183, 7-187,
7-189
verifying, 7-166
PBS data field, 9-l0t
/AFTER, 9-14
ASCII file specification, 9-20
binary file specification, 9-21
/CONVERT flag, 9-22
/COPIES, 9-22
/CPU LIMIT, 9-15
/DELETE flag, 9-22
/FEED flag, 9-23
file qualifier fields, 9-8
file qualifiers, 9-8
/FLAG_PAGES flag, 9-23
/FORMS, 9-13
/HOLD flag, 9-16
/JOB_COUNT, 9-13

Index-17

PBS data field (Cont.)
/LOG DELETE flag, 9-19
/LOG=FILE file specification,
9-17
/LOG FILE flag, 9-17
/LOG=QUEUE flag, 9-18
/LOG_QUEUE name, 9-19
/NAME, 9-11
/OWNER, 9-12
/PAGE LIMIT, 9-14
/PARAMETERS, 9-16
/PRIORITY, 9-12
/QUEUE, 9-11
specifying, 9-7
specifying a file, 9-7
/TIME LIMIT, 9-15
/TRUNCATE flag, 9-24
PBS user request packet
data buffer, 9-9
PEEK function, 7-319
executing, 7-319
Physical addresses
Ethernet, 11-5
Physical link layer, 11-2, 11-3
PIP system program, 2-1, 2-17
PK device, 4-41
Placed bit, 7-71
resetting for file, 7-67
setting for file, 7-67
Poke memory, 7-140
Portal, 11-4, 11-9
POSITION option
ANSI magnetic tape, 2-5, 2-14
/POSITION switch, 1-11
PPN (project-programmer Number),
7-40
Print operation
terminating, 3-10
Print request
confirming, 9-1
sending, 9-1
SYS call for, 9-1
using Print/Batch Services, 9-1
PRINT statement
declaring a field, 4-17
for magnetic tape, 2-18, 2-19
Print/Batch Services
data buffer, 9-9
data field layout, 9-7
differences with OPSER, 9-1

Print/Batch Services (Cont.)
SYS call for, 9-1
/PRIORITY
PBS data field, 9-12
Priority
changing, 7-124
Private delimiter, 4-34, 7-237
characteristics, 4-35
declaring, 4 - 35
defining, 4-34
defining with .SPEC, 4-34
defining with SYS call, 4-34
multiple, 4-34
processing binary mode, 4-36
programming hints, 4-36
using, 4-36, 7-237
using on data entry terminal,
4-34
Private disk
advantages, 1-47
f i 1 e on, 1 - 47
Privilege, 1-14, 1-15t
checking in program access, 1-25
clearing current, 7-290
converting mask to name, 7-296,
7-300
converting name to mask, 7-296,
7-298
drop temporary, 7-93
masks, 1- 20
multiple, 1-14
reading current, 7-290
regain temporary, 7-93
send, by job number, 8-20
send, by logical name, 8-20
setting current, 7-290
SYS calls, 1-26
third party checking, 7-294
using in applications, 1-23,
1-24, 1-26
Program
privilege checking, 1-25
privileges on exit, 1-26
running by ceL command, 10-1
running under a controlled job,
4-44
Program execution, CTRL/C
immunity, 7-138
??Program lost-sorry error
causes, C-24

Index-18

??Program lost-sorry error
(Cont. )
description, C-23
Project-programmer number, 1-12
assign user logical, 7-202
deassign a, 7-204
disassociate from job,· 7-170
file name string scan, 7-48
finding current, 7-321
in SYS call, 7-40
wildcard lookup, 7-283
Prompt message, exit with no,
7-24
Protection code
assign user, 7-202
deassign user, 7-204
DECtape, 5-4
DOS label magnetic tape, A-3
file name string scan, 7-48
summary, 1-19t
Protocol types, 11-4, 11-10
padded, 11-10, 11-12
unpadded, 11-10, 11-12
Pseudo keyboard, 4-37
accessing, 4-40
and sleeping job, 10-9
controlled job, 4-37
controlling job, 4-37
creating controlled job, 4-40
defining, 4-37
device designator (PK), 4-37
disable echo, 4-47
enable echo, 4-47
handler index, 4-47
in full duplex mode, 4-39
input, 4-40, 4-41
input buffers, 4-37
operations, 4-39
output buffers, 4-37
output to, 4-41
programming example, 4-45
PUT statement actions, 4-44f
RECORD option, 4-44
special function SPEC%, 4-47
using, 4-37
Pseudo keyboard I/O, 4-40, 4-41
Public structure, 1-14
open a file on, 1-46
Punched cards
ANSI code, B-It
1401 code, B-It

Punched cards (Cont.)
DEC026 code, B-lt
DEC029 code, B-lt
PUT statement, 11-14, 11-15,
11-16
DMCll/DMRl1, 6-7
for magnetic tape, 2-18, 2-19
on pseudo keyboard, 4-41
-Q-

/QUEUE
PBS data field, 9-11
-R-

Race condition, 4-6
Radix-50
character set, D-l
character set values, D-2t
converting numbers, 7-43
representing character string,
D-2
REACT system program, 1-12, 1-14
Receive call
SLEEP cancelled by, 4-2
Receive message
example, 8-34
SYS call, 8-21, 8-34
Receive message SYS call, 8-30
Receiver
declaration, 8-1
example of declaration, 8-33
ID blocks, 8-8
names, 8-9
remove, 8-31
remove example, 8-37
Receiver sleep
awaken from, 8-28
job in, 8-28
R.ecord
skip on magnetic tape, 2-27
Record format
specifying on ANSI tape, 2-14
Record number, on DECtape, 5-2
RECORD option
flexible diskette, 1-53
for DMCll/DMRll, 6-3
line printer, 3-8
RECORD values, card reader, 5-9t

Index-19

RECORD values, flexible diskette
block mode I/O, 1-55
logical record zero, 1-55
write Deleted Data Mark, 1-55
RECORD values, line printer, 3-9t
binary output, 3-11
clear buffers, 3-10
delay return, 3-10
no stall option, 3-10, 3-11
print over perforations, 3-9
truncate long lines, 3-11
RECORD values, terminal
conditional input, 4-1
disable formatting, 4-8
multiple service, 4-3
multi terminal, 4-6t
transparent control character
output, 4-33
Records, variable length
magnetic tape, 2-15
RECORDSIZE option, 1-36, 1-50
ANSI magnetic tape, 2-16
DOS magnetic tape, 2-5, 2-13
file-structured DECtape, 5-1
magnetic tape, 2-9
non-fi1e-structured disk, 1-30
non-file-structured magnetic
tape, 2-23
RECOUNT
use on card reader input, 5-6,
5-7
RECOUNT variable, 4-5
REFRESH initialization option,
1-3, 1-6, 1-12
Remove receiver SYS call, 8-1,
8-31
example, 8-37
REORDR, system utility, 1-46
Reserved names, 8-10t
Resident library
add, 7-108
characteristics, 7-108
control, 7-117
CSPLIB.LIB, 1-8
default protection, 7-108
for system programs, 1-8
protection code, 7-108
remove, 7-112
unload, 7-113
using, 7-108

Retrieval pointers, updating,
1-38
Return file characteristics
MAGTAPE function, 2-32
Rewind
MAGTAPE function, 2-26
Rewind on CLOSE
MAGTAPE function, 2-34
Rewind tape, 2-8
RMSBCK utility program, 2-1
RMSRST utility program, 2-1
RSTS/E errors, C-l
RSTS/E monitor, files, 1-12
RSTS/E system, access to, 1-12
.RTS file, 1-2, 1-8
RUBOUT, as a delimiter, 4-21
Run burst
and CPU time, 7-124
changing, 7-124
RUN command
alternatives, 10-1
Run priority, set special, 7-92
Run time, 1-13t
allocating, 7-124
Run-time system, 7-70
add, 7-100
associate with a file, 7-117
auxiliary, 1-8, 7-117
characteristics, 7-100
control, 7-117
description block, 7-103
establishing private default,
7··28
load address, 7-100
name field, 7-71
name field change, 7-67
remove, 7 -104
temporary switch, 7-28
unload, 7-106
Run-time system code, 1-2

-sSATT.SYS, storage allocation file,
1-3, 1-11
SAVE/RESTORE system program, 2-1
Sector mode I/O, 1-54, 1 56
Send local data message SYS call,
8-13
example, 8-33

Index-20

Send local data message with
privilege mask SYS call, 8-18
Send User Request Packet
SYS call, 9-2
Send/Receive
and EMT logging, G-l
call,argument length, 8-3
data passed, 8-40
data returned, 8-40
examples, 8-33
format ~f SYS calls, 8-2
function, 8-1
function code, 8-2
obsolete number 18 call, 8-3
sender selection summaryv 8-30t
SYS calls, 8-33
Send/Receive data
summary, 8-40f
SET/ACCOUNT command, 1-12
SHOW ACCOUNT command, 1-12
.SIL file, 1-2
Single volume magnetic tape, A-3
/SIZE switch, in CCL command,
10-3
Skip record
MAGTAPE function, 2-27
Slave terminal, 4-3, 4-4
control characteristics, 4-11
controlling, 4-3
CTRL/C on, 4-6
CTRL/Z on, 4-6
declaring a field, 4-18
establishing, 4-3
input, 4-5
output, 4-4
terminal as, 4-3
SLEEP statement, 10-8
conditional, 10-9
terminals, 4-2
Sleep, conditional, 10-9
Small buffer pool
using in cache, 7-249
Snap shot dump
SYS call for, 7-66
.SPEC directive
defining private delimiters,
4-34
.SPEC functions, 11-8, 11-16,
11-17
SPEC% function
disk, 1-49

SPEC% function (Cont.)
flexible diskette, 1-56
handler index, E-1
line printer, 3-12
magnetic tape, 2-37
MAGTAPE function alternate,
2-38
pseudo keyboards, 4-47
terminals, 4-37
cancel CTRL/O, 4-37
cancel type ahead, 4-37
clear private delimiters,
4-37
set MODE for echo, 4-37
set MODE for ODT, 4-37
set MODE for tape, 4-37
Spooling files
SYS call for, 7-61
Spooling, SYS call, 7-61
monitor actions, 7-64
restrictions, 7-64
SPR (Software Performance Report),
C-3, C-25
guidelines, C-25
information on a, C-25
Stall/unstall system
SYS call for, 7-292
START option, 1-2
START.COM file, 1-2
Statement
CLOSE, 1-35
GET, for magnetic tape, 2-9
OPEN, for non-file-structured
disk, 1-27
PRINT, 4-17
PUT, 4,- 41
SLEEP, 4-2
UNLOCK, 1-35
Statistics
get open channel, 7-134
status
check line printer, 3-13
determining disk pack, 7-160
determining terminal, 7-160
DMC11/DMR11 information, 6-4
returning for magnetic tape,
2-31
STATUS variable, 1-45
after eCL entry, 10-8
conditions for setting, 7-55

Index-21

status word
magnetic tape, 2-31t
Storage allocation file, SATT.SYS,
1-3
Storage Allocation Table (SAT),
1-3, 7-164
Storage of accounting data, 1-12
Stream ASCII I/O
magnetic tape, 2-4
String
extract from data area, 7-26
load in data area, 7-27
parameter, 7-36
target, 7-36
Swap files, 1-9, 7-270
adding, 1-11
creating optional, 1-9
device as, 1-10
file as, 1-9
naming, 1-9
optimally positioning, 1-11
removing, 1-11
specifying disk as, 7-270
specifying file as, 7-270
SWAP MAX, 7-125
value, 7-125
Swap times, for disk types and
job sizes, I-lOt
SWAP% function, 7-40
reversal of bytes, 7-40f
SWAP.SYS file, 1-9
Swapping
preventing unnecessary, 7-96
Switch
/POSITION, 1-11
Switches, in file
file name string scan, 7-48
SYS call, 7-4t to 7-5t
account number lookup on index,
7-283
accounting dump, 7-120
add a resident library, 7-108
add a run-time system, 7-100
add CCL, 7-89
add new logical name, 7-257
add system files, 7-267
allocate/reallocate device,
7-197
assign user logical, 7-201
associate run-time system,
7-117

SYS call (Cont.)
attach job, 7-173
broadcast to a terminal, 7-141
cancel all type ahead, 7-30
cancel CTRL/O effect, 7-18
cancel type ahead, 4-18
change disk logical name, 7-262
change disk quota, 7-183, 7-187
change expiration date, 7-183,
7 ··187
change file characteristics,
7 .. 128
check file access rights, 7-296
clear current privileges, 7-290
convert privilege mask to name,
7-300
convert privilege name to mask,
7-298
create dynamic region, 7-114
create user account, 7-149
creating a job, 4-40
CTRL/C trap enable, 7-137
date and time changer, 7-122
date and time conversion, 7-253
deallocate all devices, 7-205
deallocate device, 7-203
deassign user logical, 7-203
declare receiver, 8-1, 8-4
delete account attributes, 7-87
delete CCL, 7-89
delete user account, 7-158
detach job, 7-180
directory lookup on index,
7 .. 220, 7-221
disable further logins, 7-147
disable terminal, 7-193
disable terminal echo, 7-21
disk directory lookup by file
name, 7-225
disk pack status, 7-160
disk wildcard directory lookup,
7 .. 227
drop temporary privilege, 7-93
enable further logins, 7-148
enable single character input,
7 .. 22
enable terminal echo, 7-20
enable/disable cache, 7-249
enter tape mode on terminal,
7-19
execute CCL command, 7-34

Index-22

SYS call (Cont.)
exit and set up NONAME, 7-28
exit with no prompt, 7-24
file name string scan, 7-43,
7··45
file utility, 7-67
force data to terminal, 7-143
get core common string, 7-26
get monitor tables - part III,
7··58
get monitor tables part I ,
7 ··144
get monitor tables part I I ,
7 ··127
get open channel statistics,
7 ··134
hang up a dataset, 7-132
job creation, 7-275
job scheduling, 7-124
kill a job, 7-191
list logical names, 7-264
list privilege related, 1-26
list system files, 7-273
load monitor overlay code and
return status, 7-315
lock/unlock job in memory, 7-96
login ,. 7 -166
logout, 7-170
ODT submode, 7-22
open next disk file, 7-302
poke memory, 7-140
print/batch services, 9-1
priority changer, 7-124
put core common string, 7-27
read account attributes, 7-81
read accounting data, 7-210
read current privileges, 7-290
read file attributes, 7-75
read/reset accounting data,
7-210
reattach job, 7-176
receive message, 8-21, 8-30
receive message example, 8-34
regain temporary privilege,
7-93
remove a resident library,
7-112
remove a run-time system, 7-104
remove logical name, 7-260
remove monitor overlay code,
7-315

SYS call (Cont.)
remove receiver, 8-1, 8-31
remove receiver example, 8-37
remove system files, 7-271
return error message, 7-195
return information on last
opened file, 7-31
return job status, 7-285
return pack attributes, 7-79
run burst changer, 7-124
send local data message, 8-1,
8-13
send local data message example,
8-33
send local data message with
privilege mask, 8-18
send user request packet, 9-2
send/receive, examples, 8-33
set current privileges, 7-290
set device characteristics,
7-305
set line printer
characteristics, 7-309
set logins, 7-98
set password, 7-183, 7-187,
7-189
set special run priority, 7-92
set system defaults, 7-312
set terminal characteristics,
7-229, 7-242
size maximum changer, 7-124
snap shot dump, 7-66
special shutup logout, 7-119
spooling files, 7-61
stall/unstal1 system, 7-292
swap console, 7-178
terminal status, 7-160
third party privilege check,
7-294
unload a resident library,
7-113
unload a run-time system, 7-106
verify password, 7-166
write account attributes, 7-85
write file attributes, 7-77
zero a device, 7-206
SYS calls, 7-2
caching with, 1-41
corresponding monitor
directives, F-lt
format, 7-2

Index-23

SYS calls (Cont.)
format of Send/Receive, 8-2
function code format, 7-2
privileges required, 7-2
to file processor, 7-25
to FIP, 7-45
using, 7-2
SYS calls to FIP, 7-6t to 7-17t,
7-36
integer numbers, 7-41
notations used, 7-40
project-programmer number, 7-40
references used, 7-40
unpacking returned data, 7-39
unsigned integer, 7-41
using, 7-36
SYS system function codes, 7-4t
to 7-5t
System
access to, 1-12
job logged off, 7-119
setting defaults, 7-312
shutting down, 7-119
System account, 1-1
System disk, 1-14
See also Public structure
System files
adding, 7-267
creating, 7-270
listing, 7-273
planning, 7-270
removing, 7-267, 7-271, 7-272
System initialization code, 1-2
System library account, 1-1, 1-2
access during system start-up,
1-2
contents, 1-2
System logical names, 7-255
System operation
adjusting, 7-272
System overlay file, 1-6
System program
ANALYS, 7-66
BACKUP, 2-1
FIT, 1-52
FLINT, 1-52
LOGIN,1-12
LOGOUT, 1-12
PIP, 2-1, 2-17
REACT, 1-12, 1-14
REORDR, 1-46

System program (Cont.)
runn i ng, 10 - 1
SAVE/RESTORE, 2-1
System receive buffers, 11-10,
11-13
System start-up procedure, 1-2
-T-

Tab
enable horizontal, 7-229
enable vertical, 7-229
Tape
See also magnetic tape
logical end of, 2-11
read access, 2-23
rewinding, 2-8
write access, 2-23
Tape mode
enter on terminal, 7-19
set on terminal, 4-47
Tape status
MAGTAPE function, 2-29
Target string, 7-36
TEIO magnetic tape
MODE for 9-track, 2-23
TE16 magnetic tape
MODE for 9-track, 2-23
Temporary privilege
drop permanently, 7-93
drop temporarily, 7-93
Tentative file, 1-39
See also File
closing, 1-39
creating, 1-39
directory 'entries, 1-39
multiple copies, 1-39
opening, 1-39
renaming, 1-39
Terminal, 4-1
attach detached job to, 7-181
binary input from, 4-7
binary output to, 4-8
broadcast to, 7-141
cancel CTRL/O effect on, 7-18
conditional input from, 4-1
control of several, 4-3
control with MODE option, 4-7
CTRL/C at, 4-20
CTRL/C input from, 7-139
data forced to disabled, 7-143

Index-24

Termina.l (Cont.)
data to disabled, 7-141
deassigning the console, 7-181
declare a field on, 4-11, 4-16
default buffer size, 4-8
detaching from, 7~181
difference between VT100 and
VT52, 4-24
disable, 7-193
disable echo, 4-12, 7-21
disable scope, 7-232
echo control, 4-11
enable echo, 7-20
enable scope, 7-232
enable XONXOFF, 4-21
end-of-file on, 4-10
enter tape mode on, 7-19
escape sequence to, 4-22
establish as console, 7-176
force input to, 7-143
forcing interactive input, 4-3
handling overflow, 4-16
locally echo, 7-232
losing data, 4-8
rna s t e r, 4 - 3, 4 - 4
MODE values, 4-7
multiple service, 4-3
multiple service rule, 7-19
ODT submode on, 7-22
open in echo control mode, 4-16
override default buffer size,
4-8
paint characters, 4-11
prevent CTRL/C interrupt, 4-20
prevent hibernation, 4-21
processing, 4-1
prompt on screen, 4-11
reserved to a job, 4-3
same function on several, 4-3
set advanced characteristics,
7-242
set characteristics, 7-229,
7-242
slave, 4-3, 4-4
sleep operation, 4-2
special use of RUBOUT, 4-21
suppress CR/LF, 4-10
synchronization protocol, 7-235
type ahead, 4-11
video, 4-11

Terminal buffer
clearing input from, 7-30
Terminal characteristics
determining current, 7-240,
7-245
setting, 7-229, 7-242
setting advanced, 7-242
Terminal echo, 7-232
Terminal input
cancellation of SLEEP, 4-2
from one field, 4-11
less than a line, 7-22
Terminal output, no stall option,
4-2
Terminal service, 4-4
from paper tape reader, 4-8
from terminal, 4-8
au t pu t
4 - 4, 4 - 7
transfer, 4-9
Terminal status, 7-160
Terminal, detached
attaching to, 7-181
Terminal, SPEC%, 4-37
Terminal,VTlOO
ANSI-compatible mode, 4-24
escape sequences, 4-24
VT52-compatible mode, 4-24
Terminal,VT200-family
escape sequences, 4-24
Time conversion
SYS call for, 7-253
Time of day, changing, 7-122
/TIME_LIMIT
PBS data field, 9-15
Trapping, of CTRL/C, 7-137
/TRUNCATE flag
PBS data field, 9-24
TS03 magnetic tape
MODE for 9-track, 2-23
TSl1 magnetic tape
MODE for 9-track, 2-22
TSV05 magnetic tape
MODE for 9-track, 2-22
TU10 magnetic tape
MODE for 9-track, 2-23
TU16 magnetic tape
MODE for 9-track, 2-23
TU45 magnetic tape
MODE for 9-track, 2-23
TU77 magnetic tape
MODE for 9-track, 2-23

Index-25

TU80 magnetic tape
MODE for 9-track, 2-22
Type ahead
cancel all, 7-30
cancelling, 4-30

-uUFD
cluster size, 1-5
contents, 1-12
marked for caching, 1-42
placed bit, 7-71
positioning, 7-149
preextending, 7-149
setting cluster size, 7-149
writing, 1-45
Underscore, in logical device
name, 7-46
UNLOCK statement, 1-35
Unlocked job
procedure for, 7-96
Unsigned integer, convert to two
bytes, 7-43
Update mode, for disk, 1-34
User logical
assign, 7-201
assign device name, 7-202
assign project-programmer
number, 7-202
deassign, 7-204
remove, 7-203, 7-204
User request data fields
PBS, 9-l0t
User request packet, PBS, 9-1
data buffer, 9-9
definition, 9-1

-vvariable length records, magnetic
tape, 2-15
Variables
ERR,

C-2

STATUS, 1-45
Video terminal, 4-11
See also Terminal

Virtual disk, 1-48
advantages, 1-49
limitations, 1-49
using, 1-48

Volume label, A-3
ANSI magnetic tape, A-5
VT100
ANSI-compatible escape
sequences, 4-25t, 4-27
ANSI-compatible mode, 4-24
escape sequences, 4-24
restrictions in VT52-mode, 4-24
VT52-compatible mode, 4-24
VT200
ANSI-compatible escape
sequences, 4-25t
VT200-family
escape sequences, 4-24
restrictions in VT52-mode, 4-24

-wWCB information, 7-136
Wildcard
disk directory lookup, 7-227
Wildcard lookup, 7-283
Wildcard specifications
files matching the, 7-227
Window turning, 1-46
reducing, 1-46
Write tape mark
MAGTAPE function, 2-26

-xXBUF (Extended Buffer Pool), 1-7,
1-41
caching use of, 7-251
contents, 1-7
estimating size, 1-7
in message send/receive, 8-12
Xerox Corporation, 11-3
XM: device, 6-1
XOFF
define, 7 - 238
disable, 7-232
enable, 7-232
XON
define, 7-238
disable, 7-232
enable, 7-232
XONXOFF processing, 4-21

Index-26

HOW '·0 ORDER ADDITIONAL DOCUMENTATION
DIRECT TELEPHONE ORDERS
In Continental USA
and Puerto Rico
call 800-258-1710

In Canada
call 800-267-6215

In New Hampshire,
Alaska or Hawaii
call 603-884-6660

DIRECT MAIL ORDERS (U.S. and Puerto Rico*)
DIGITAL EQUIPMENT CORPORATION
P.O. Box CS200B
Nashua, New Hampshire 03061

IJIRECT MAIL ORDERS (Canada)
DIGITAL EQUIPMENT OF CANADA LTD.
100 Herzberg Road
P.O. Box 13000,
Kanata, Ontario, Canada K2K 2A6
Attn: DECDIRECT OPERATIONS

ELECTRONIC ORDERING
Dial BOO-DEC-DEMO with any VT100 or VT200
compatible terminal and a 1200/2400 baud modem.
If you need assistance, call BOO-DEC-INFO.

INTERNATIONAL
DIGITAL EQUIPMENT CORPORATION
P&SG Business Manager
c/o Digital's local subsidiary
or approved distributor

Internal orders should be placed through the Software Distribution Center (SDC),
Digital Equipment Corporation, Westminster, Massachusetts 01473-0471
*Any prepaid order from Puerto Rico must be placed

with the Local Digital Subsidiary:
809-754-7575

RSTS/E
Programming Manual
AA-EZ09A-TC
Including AD-EZ09A-T1,T2

Reader's Comments
Note: This form is for document comments only. DIGITAL will use comments submitted on this form at
the company's discretion. If you require a written reply and are eligible to receive one under
Software Performance Report (SPR) service, submit your comments on an SPR form.
Did you find this manual understandable, usable, and well-organized? Please make suggestions for
improvement.

Did you find errors in this manual? If so, specify the error and the page number. _ _ _ _ _ _ _ __

Please indicate the type of user/reader that you most nearly represent.

D
D

D
D
D
D

Assembly language programmer
Higher-level language programmer
Occasional programmer (experienced)
User with little programming experience
Student programmer
Other (please specify) _ _ _ _ _ _ _,_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __

Name.

Date _ _ _ _ _ _ _ _ _ _ _ _ _ _ __

Organization
Street _____
City

State

Zip Code
or
Country

I
I

I
I
I
I

----Do Not Tear - Fold Here and Tape _____________________________________ ...1

IIIIII

No Postage
Necessary
if Mailed in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

ATTN: Office Systems Documentation MK01-2/E02
DIGITAL EQUIPMENT CORPORATION
Continental Boulevard
Merrimack N.H. 03054

111'111111.11 •••• 1.1 •• 11111.1 •• 1.1 •• 1.1"111.11.1111
----Do Not Tear - Fold Here and Tape - - - - - - - - - - - - - - - - - . - - - - - - - - - - - - - - - - - - - -