Digital PDFs

AA-EZ10B-TC

August 1990

690 pages

Original

143MB

Document:	RSTS/E System Directives Manual
Order Number:	AA-EZ10B-TC
Revision:	0
Pages:	690
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsts_e/V10/AA-EZ10B-TC_RSTS_E_System_Directives_Manual_Aug1990.pdf

OCR Text

RSTS/E
System Directives Manual
Order Number: AA-EZ1 08-TC

RSTS/E
System Directives Manual
Order Number: AA-EZ1 OB- TC

This manual contains general information on run-time systems and describes RSTS/E monitor,
RSX emulator, and RT11 emulator directives for the assembly-language programmer.

Operating System and Version: RSTS/E Version 10.0
Software Version:

digital equipment corporation
maynard, massachusetts

RSTS/E Version 10.0

August 1990
The information in this document is subject to change without notice and should not be
construed as a commitment 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 only be used
or copied in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment not supplied
by Digital Equipment Corporation or its affiliated companies.
Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to
restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer
Software clause at DFARS 252.227-7013.

© Digital Equipment Corporation 1990. All rights reserved.
Printed in U.S.A.
The postpaid READER'S COMMENTS form on the last page of this document requests
the user's critical evaluation to assist in preparing future documentation. The following are
trademarks of Digital Equipment Corporation:
ALL-IN-1
DEC/CMS
DECdx
DEC/FMS-11
DECmaii
DECnet
DECnetiE
DECSA
DECserver
DECsystem-10
DECSYSTEM-20
DECUS
DECworld
DELUA
DEQNA

DEUNA
DIBOL
EDT
lAS
LA
LN01
MicrciRSX
OS/8
PDP
PDP-11
PDT
Q-BUS
RMS-11
RSTS

RSX
RT
RT-11
TOPS-10
TOPS-21
ULTRIX
UNIBUS
VAX
VAXmate
VMS
VT
WPS-PLUS
Rainbow

mamaDmD~

IBM is a registered trademark of International Business Machines Corporation.
RMS is a trademark of American Management Systems, Inc.

(

Contents
Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Part I

Introduction

Chapter 1
1.1

Introduction
Run-Time Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
User Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Program Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.2.1
High-Level Languages . . . . . . . . . . . . . . . . . . . . . . . . .
1.1.2.2
Program Development Tools .................... .
1.1.2.3
Resident Libraries .. , ........................ .
1.1.2.4
Instruction and Data Space ..................... .
1.1.3
Directives for Each Programming Environment ................ .
1.1.4
Writing or Modifying a Run-lime System .................... .

1-1
1-1
1-2
1-2

Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-5

1.1.1
1.1.2

1.2

Chapter 2
2.1

2.2

1-3
1-3

1-4
1-4
1-4

General RSTS/E Environment
How RSTS/E Allocates Memory: Physical and Virtual Addressing

2-1

Job Space: High Segment and Low Segment ....................... .
Low-Segment Details: First 512. Bytes of the Low Segment ....... .
High-Segment Details: Pseudovectors ...................... .
2.2.2.1
Run-Time System Capability and Default Definitions .... .
2.2.2.2
Synchronous Exception Handler Addresses .......... .
2.2.2.3
Asynchronous Exception Handler Addresses ......... .
2.2.2.4
Entry Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-6
2-9
2-'-16
2-18
2-21
2-23
2-25

2.2.1
2.2.2

Part II

xiii

Monitor Directives

iii

Chapter 3

General Monitor Directives

3.1

Summary of General Monitor Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.1
Prefix File COMMON. MAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.1.1.1
How to Assemble with COMMON.MAC ............. .
3.1 .1 .2
Macros Provided in COMMON .MAC ............... .
Error
Mnemonics:
Symbol Table File ERR.STB ................ .
3.1.2
Programming
Hints
................................... .
3.1.3

3-1
3-2
3-3
3-3
3--6
3--6

3.2

Trap Handling with Supervisor Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-8

3.3

.AST-Enable/Disable AST Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-10

3.4

.ASTX-Exit from AST Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-11

CAlFiP -

3-12
3-13
3-16

3.5

3.5.15

Cail the File Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ASSFO (Allocate a Device) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CLSFQ (Close a Channel) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CRBFO (Create a Binary [Executable] File and Open It on a
Channel) .......................................... .
CREFO (Create a File and Open It on a Channel) ............. .
CRTFQ (Create and Open a Temporary File) ................. .
DALFO (Deallocate All Devices and Deassign All User logicals) .... .
DEAFO (Deallocate a Device) ........................... .
DIRFO (Get Directory Information) ........................ .
DLNFQ (Delete a File) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ERRFQ (Return Error Message Text) ...................... .
LOKFO (Disk FilelWildcard Lookup) ....................... .
OPNFO (Open a File/Device on a Channel) .................. .
RENFO (Rename a File) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RSTFO (Reset a Channel) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UUOFO (Hook to File Processor) ......................... .

3-46
3-53
3-59
3--61
3--63

3.6

.eCl -

Check String for eCl Command . . . . . . . . . . . . . . . . . . . . . . . . . . .

3--64

3.7

.CHAIN -

Execute Under Same RTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3--68

3.13

.CLEAR -

Clear Keyword Bits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3--69

3.9

.CMDlN-Read/Write Command line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . _

3-71

3.10

.CORE -

Change Memory Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-73

3.11

.DATE -

Return Current Date and Time . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-77

3.12

.ERlOG -

Log an Error from FITS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-79

3.13

.EXIT -

Exit to Default Keyboard Monitor ......................... .

3-80

3.14

.FSS -

Check File Specification String . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-81

3.15

.LOGS -

Check for logical Device Names ........................ .

3-92

.MESAG -

Message Send/Receive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Declare Receiver Subfunction . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Remove Receiver Subfunction . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Send local Data Message Subfunction ..................... .
Receive Subfunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-100
3-100
3-103

3.5.1
3.5.2
3.5.3
3.5.4
3.5.5
3.5.6
3.5.7
3.5.8
3.5.9

3.5.10
3.5.11
3.5.12
3.5.13
3.5.14

3.16

3.16.1
3.16.2
3.16.3

3.16.4
iv

3-18
3-23
3-30
3-34
3-35
3-37
3-42
3-44

3-104

3-107

3.16.5
3.16.6
3.16.7
3.16.8
3.16.9
3.16.10
3.16.11
3.16.12

Send Privileges Subfunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Create Local LAT Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Delete Local LAT Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assign a Local LAT Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deassign Local lAT Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Return Local lAT Port Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Return Local LAT Port Characteristics ...................... .
Show LAT Sessions . . . . . . . . . . . . . ..................... .

3-110
3-113
3-115
3-117
3-120
3-122
3-125
3-131

3.17

.NAME -

Set Program Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-135

3.18

.PEEK -

look at Monitor Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-137

3.19

.PlAS 3.19.1
3.19.2
3.19.3
3.19.4
3.19.5

Access Resident library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ATRFO (Attach Resident library) ......................... .
CRAFO (Create Address Window) . . . . . . . . . . . . . . . . . . . . . . . . .
DTRFQ (Detach Resident library) ........................ .
ELAFO (Eliminate Address Window) ....................... .
MAPFO (Map Address Window) . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.19.5.1
Fast-Mapping Facility ......................... .
UMPFO (Unmap Address Window) ........................ .

3-139
3-140
3-144
3-149
3-151
3-154
3-159
3-161

3.19.6
3.20

.POSTN -

Return Current Horizontal Position ...................... .

3-163

3.21

.READ -

Read Data from File or Device . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-165

3.22

.READA-Read Data from a Device (Asynchronous) .................. .

3-170

3.23

.RTS -

Pass Control to Run-Time System ......................... .

3-178

3.24

.RUN -

Run a Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-182

3.25

.SET -

Set Keyword Bits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-185

3.26

.SLEEP -

Suspend Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-187

3.27

.SPEC-Special Functions for I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.27.1
.SPEC for Disk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.27.2
.SPEC for Ethernet Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.27.2.1
Set New Physical Address ..................... .
3.27.2.2
Enable Multicast Addresses ..................... .
3.27.2.3
Get Circuit Counters . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.27.2.4
Get line Counters . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.27.2.5
Transfer Circuit Counters ....................... .
3.27.2.6
Transfer line Counters . . . . . . . . . . . . . . . . . . . . . . . . .
3.27.3
.SPEC for Flexible Diskette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.SPEC for line Printer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.27.4
3.27.5
.SPEC for Magnetic Tape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.SPEC for Pseudo Keyboards ......................... .. .
3.27.6
.SPEC for Terminal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.27.7

3-189
3-190
3-193
3-193
3-194
3-195
3-196
3-197
3-199
3-204
3-206
3-209
3-214
3-216

3.28

.STAT -

Return Job Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-225

3.29

.TIME -

Return Timing Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-227

3.30

.TTAPE -

Enter Tape Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-229

3.31

.TTDDT -

Disable FUll-line Buffering . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-230

3.32

·TTECH -

Undo. TTAPE or .TINCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-231

3.33

· TTNCH -

Stop Echo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-232

3.34

·TTRST -

Restart Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-233

3.35

.ULOG 3.35.1

Modify User Logical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UU.ASS (Allocate/Reallocate a Device, or Assign or List User
Logical) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UU.DAL - Deallocate All Devices and Deassign All User Logicals .. .
UU.DEA - Deallocate a Device or Deassign a User Logical ...... .

3-234

3.35.2
3.35.3
3.36

.UUO - Execute BASIC-PLUS SYS Call . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.36.1
UU.ACT (Accounting Information Dump) . . . . . . . . . . . . . . . . . . . . .
3.36.2
UU.ASS (Allocate/Reallocate Device) . . . . . . . . . . . . . . . . . . . . . . .
3.36.3
UU.ATR (ReadlWrite Attributes) . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.36.4
UU.ATI (Attach/Reattach Job/Swap Console) . . . . . . . . . . . . . . . . . .
3.36.5
UU.BCK (Change File Statistics) . . . . . . . . . . . . . . . . . . . . . . . . . .
3.36.6
UU.BYE (Logout) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UU.CCL (Add/Delete CCL Command) . . . . . . . . . . . . . . . . . . . . . . .
3.36.7
3.36.8
UU.CFG (Set Device/System Default Characteristics) ............ .
3.36.9
UU.CHE (Enable/Disable Disk Caching) . . . . . . . . . . . . . . . . . . . . . .
3.36.10
UU.CHK (Check File Access/Privilege Name/Privilege Mask
Handling) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.36.11
UU.CHU (Set Password, Change Password/Quota/Expiration Date,
Disable Terminal,KiII Job) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.36.12
UU.CNV (Date and Time Conversion) . . . . . . . . . . . . . . . . . . . . . . .
UU.DAL (Deallocate All Devices and Deassign All User Logicals) ... .
3.36.13
3.36.14
UU.DAT (Change System Datemme) . . . . . . . . . . . . . . . . . . . . . . .
3.36.15
UU.DEA (Deallocate Device) . . . . . . . . . . . . . . . . • . . . . . . . . . . . .
3.36.16
UU.DET (Detach) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.36.17
UU.DIE (System Shutdown) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.36.18
UU.DIR (Directory Lookup) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.36.19
UU.DLU (Delete User Account) . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.36.20
UU.DMP (Snap Shot Dump) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.36.21
UU.ERR (Return Error Messages) . . . . . . . . . . . . . . . . . . . . . . . . .
3.36.22
UU.FCB (Get Open Channel Statistics: WCB/DDB/FCB) ......... .
3.36.23
UU.FIL (File Placement and Modification) . . . . . . . . . . . . . . . . . . . . .
UU.HNG (Hang Up a Dataset) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.36.24
UU.JOB (Create Job) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.36.25
3.36.26
UU.LlN (Login) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.36.26.1 Verify System Password Function . . . . . . . . . . . . . . . . . .
UU.LOG (Set Number of Logins) . . . . . . . . . . . . . . . . . . . . . . . . . .
3.36.27
3.36.28
UU.LOK (Disk Directory Lookup by File NamelWildcard Lookup) .... .
3.36.29
UU.MNT (Disk Pack Status) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UU.NAM (Associate a Run-lime System with a Rle) ............ .
3.36.30
3.36.31
UU.NLG (Disable Further Logins) . . . . . . . . . . . . . . . . . . . . . . . . . .
UU.ONX (Open Next Disk File) . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.36.32
UU.PAS (Create User Account) . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.36.33
3.36.34
UU.POK (Poke Memory) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UU.PPN (Wildcard PPN Lookup) . . . . . . . . . . . . . . . . . . . . . . . . . .
3.36.35
UU.PRI (Change Priority/Run Burst/Job Size) . . . . . . . . . . . . . . . . . .
3.36.36
3.36.37
UU.PRV (Set/Clear/Read Current Privileges) . . . . . . . . . . . . . . . . . .
UU.RAD (Read or Read-and-Reset Accounting Data) ........... .
3.36.38
UU.RTS (Add/Remove/Run-lime System or Resident Library, or Create
3.36.39
Dynamic Region) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.36.40
UU.SLN (System Logical Names) . . . . . . . . . . . . . . . . . . . . . . . . . .
UU.SPL (Spooling) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.36.41

3-235
3-243
3-245
3-248
3-251
3-252
3-254
3-262
3-266
3-267
3-269
3-271
3-282
3-284
3-290
3-295
3-297
3-298
3-299
3-300
3-302
3-303
3-307
3-308
3-309
3-311
3-315
3-319
3-320
3-327
3-330
3-332
3-334
3-338
3-342
3-343
3-344
3-348
3-352
3-353
3-355
3-356
3-358
3-362
3-374
3-379

3.36.42
3.36.43
3.36.44
3.36.45
3.36.46
3.36.47
3.36.48
3.36.49
3.36.50
3.36.51

UU.STL (StalilUnstall System) ........................... .
UU.SWP (Add, Remove, and List System Files) ............... .
UU.SYS (Return Job Status Information) .................... .
UU.TB1 (Get Monitor Tables, Part I) ....................... .
UU.TB2 (Get Monitor Tables, Part II) ....................... .
UU.TB3 (Get Monitor Tables, Part III) . . . . . . . . . . . . . . . . . . . . . . .
UU.TRM (Set Terminal Characteristics) ..................... .
UU.YLG (Enable Logins) ............................... .
UU.ZER (Zero Device) ................................ .
UU.3PP (Third-Party Privilege Checking) .................... .

3-382
3-383
3-389
3-394
3-396
3-398
3-400
3-409
3-411
3-413

3.37

.WRITA -

Write Data to File or Device (Asynchronously) .............. .

3-414

3.38

.WRITE -

Write Data to File or Device ............................ .

3-419

Part III

Chapter 4

RSX and RT11 Emulator Directives

RSX Run-Time System Environment

4.1

Advantage: Transportable Code ................................ .

4-1

4.2

General Services ........................................... .

4-1

4.3

RSX Directive Emulation Within RSTS/E Monitor ..................... .

4-2

4.4

System Macro Library ........................................ .

4-2

4.5

Directive Processing ......................................... .

4-3

4.6

Directive Forms ($, $C, $S) and Their Expansions .................... .
4.6.1
$ Form (and DIR$ Directive) ............................ .
4.6.2
$C Form .......................................... .
$S Form .......................................... .
4.6.3

4-4
4-4

4.7

Using Resident Library Access Directives from FORTRAN ............. .

4-8

4.8

First 512. Bytes of Low Segment for RSX ......................... .

4-9

Chapter 5

4-6

4-7

RSX Emulator Directives

5.1

ABRT$ -

Abort ............................................ .

5-4

5.2

ALUN$ -

Assign Logical Unit Number ........................... .

5-5

5.3

ASTX$ -

Asynchronous Exception Exit ........................... .

5-6

5.4

ATRG$ -

Attach Resident Library ............................... .

5-8

5.5

CRAW$ -

Create Address Window .............................. .

5-11

5.6

CRRG$ -

Create Dynamic Region ............................... .

5-16

5.7

DTRG$ -

Detach Resident Library .............................. .

5-18

vii

viii

5.8

ElAW$ -

Eliminate Address Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5-20

5.9

EXIT$ -

Task Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5-22

5.10

EXST$ -

Exit with Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5-23

5.11

EXTK$ -

Extend Task. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5-24

5.12

EXTM$-Extend Task by Mask. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5-26

5.13

FEADF$ -

Define System Feature labels ..........................

5-29

5.14

FEAT$ -

Test for System Feature. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5-30

5.15

GlUN$ -

Get lUN Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5-31

5.16

GMCR$ -

Get MCR (CCl) Command Line. . . . . . . . . . . . . . . . . . . . . . . . . .

5-33

5.17

GPRT$ -

Get Partition (Job) Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . .

5-34

5.18

GTIM$ -

Get Time Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5-36

5.19

GTSK$ -

Get Task (Job) Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5-38

5.20

MAP$ -

Map Address Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.20.0.1
Fast-Mapping Facility. . . . . . . . . . . . . . . . . . . . . . . . . .

5-40
5-42

5.21

MSDS$-Map Supervisor Mode D-Space ...........................

5-44

5.22

QIO$ and QIOW$ -

Queue I/O Request (and Walt) . . . . . . . . . . . . . . . . . . . .

5-47

5.23

RDBBK$ and RDBDF$-Deflne and Fill ROBs. . . . . . . . . . . . . . . . . . . . . . . .

5-52

5.24

SCCA$S -

Specify Control/C AST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5-54

5.25

SFPA$ -

Specify Floating-Point-Processor Exception Address . . . . . . . . . . .

5-55

5.26

SPND$S -

Suspend. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5-56

5.27

SSTX$ -

System Synchronous Trap Exit. . . . . . . . . . . . . . . . . . . . . . . . . . .

5-57

5.28

SVDB$ -

Specify SST Vector Table for Debugging Aid. . . . . . . . . . . . . . . . .

5-58

5.29

SVTK$ -

Specify SST Vector Table for Task ,.......................

5-60

5.30

TFEA$ -

Test for Task Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5-62

5.31

UMAP$ -

Unmap an Address Window ............................

5-63

5.32

WDBBK$ and WDBDF$-Define and Fill WDBs . . . . . . . . . . . . . . . . . . . . . . .

5-65

5.33

WSIG$ -

Wait for Significant Event Flag . . . . . . . . . . . . . . . . . . . . . . . . . . .

5-66

5.34

WTSE$ -

Wait for Single Event Flag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5-67

Chapter 6

RT-11 Run-Time System Environment

6.1

Advantage: Transportable Code ................................ .

6-1

6.2

General Services ........................................... .

6-2

6.3

System Macro Library ........................................ .

6-3

6.4

Directive Processing ......................................... .

6-4

Call Forms ................................................ .
Format for Calls Using Argument Blocks .................... .
Format for Calls Not Using Argument Blocks ................. .

6-5
6-5
6-7

Channel Number and Device Block Arguments ...................... .
Channel Number Arguments ............................ .
Device Block Arguments ............................... .

6-7
6-7

6.7

low 512. Bytes for RT-11 Run-Time System ........................ .

6-9

6.8

Scratch Pad Area in User Job Image ............................. .

6-10

6.5

6.5.1
6.5.2
6.6

6.6.1
6.6.2

Chapter 7

6-8

RT-11 Emulator Directives

7.1

.CHAIN -

Pass Control to Another Program Under RT-11

7-6

7.2

.ClOSE -

Close a Channel ................................... .

7-8

7.3

.ClRFaB -

Clear the FIRaB .................................. .

7-9

7.4

.ClRXRB -

Clear the XRB .................................... .

7-10

7.5

.CSIGEN -

Examine String for RT Command, Open Files .............. .

7-11

7.6

.CSISPC -

Examine String for RT Command, Create Devblk ............ .

7-15

7.7

.DATE -

Return Current Date to RO ............................. .

7-18

7.8

.DATTIM -

Return Date or Time ................................ .

7-20

7.9

.DElETE -

Delete File from Disk or DECtape ...................... .

7-22

7.10

.DOCCl -

Do a RSTS/E .CCl .................................. .

7-23

7.11

.DOFSS -

Do a RSTS/E .FSS .................................. .

7-24

7.12

.DORUN -

Chain to Non-RT-11 RTS Program ....................... .

7-25

7.13

.DSTATUS -

Return Device Status .............................. .

7-26

7.14

.ENTER -

Open File for Output ................................ .

7-28

7.15

.ERRPRT -

Print RSTS/E Error Message .......................... .

7-30

7.16

.EXIT -

Program Exit ........................................ .

7-31

7.17

.FETCH -

Check Whether Device Exists .......................... .

7-32
ix

7.18

.GETCOR -

7.19

Changes Job Image Size ............................ .

7-33

.GTIM -

Return Time-of-Day ................................... .

7-34

7.20

.GTJB -

Return Job High Limit ................................ .

7-35

7.21

.GTLlN -

Get Line from Job's Terminal ........................... .

7-36

7.22

.GVAL -

Get Value from Scratch Pad ..............•..............

7-37

7.23

.HRESET -

Hardware Reset ......................•.............

7-38

7.24

.LOOKUP -

Open File for Input .................••.•............

7-39

7.25

.PRINT -

Display String on Job's Terminal ...............•.........

7-41

7.26

.PURGE -

Release Channel ..............•.....................

7-42

7.27

.RCTRLO ...,.... Reset CtrllO ..................................... .

7-43

7.28

.READ/.READW/.READC -

Read Data ............................ .

7-44

7.29

.RENAME -

Rename a File ..............•......................

7-46

7.30

.REOPEN -

Reopen File Closed with .SAVESTATUS .................. .

7-47

7.31

.SAVESTATUS -

7.32

Save Status of File for Later .REOPEN ............... .

7-48

.SCCA -

Pass CtrllZ to User Program ............................ .

7-49

7.33

.SETCC -

Process CtrllC ..........................•...........

7-51

7.34

.SETFQB -

Set Up FIRQB ........•............................

7-52

7.35

.SETTOP -

Expand to Start of Scratch Pad ........................ .

7-53

7.36

.SFPA -

Set Floating-Point Error Address ........•....•............

7-54

7.37

.SPFUN -

Special Functions for 1/0 • . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7-55

7.38

.SRESET -

Software Reset ................................... .

7-57

7.39

.TRPSET -

Intercept Traps to 4 and 10 ...............•............

7-58

7.40

.TTYIN/.TTINR -

7.41

.TTYOUT/.TTOUTR -

7.42

One-Character Read From Terminal ................. .

7-59

Transfer One Character to Job's Terminal .......... .

7-61

.TWAIT -

Timed Wait ........................................ .

7-62

7.43

.WAIT -

Check for Channel Open ............................... .

7-63

7.44

.WRITEI.WRITW/.WRITC -

7.45

..V1 ..l..V2.. -

Write Data ............................ .

7-64

Use Version 1IVersion 2 Expansion .................... .

7-66

Appendixes
Appendix A

Full List of Errors

Appendix B

Device Information

B.1

Disks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

B-1

B.2

Flexible Diskettes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

B-3

B.3

Magnetic Tape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

B-4

B.4

Line Printers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

B-6

B.5

Terminals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

B-7

B.6

Pseudo Keyboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

B-1 0

2-1

How a Physical Address Is Formed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-2

Index

Figures
2-2

Memory Mapping with the APRs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-4

2-3
2-4
2-5

Conventional Task Linked to a Library in an I&D-Space System ............ .

2-5

I&D-Space Task Mapping in an I&D-Space System ..................... .

2-6

Job Area in Virtual Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-6

First 512. Bytes of Low Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-8
2-10

2-7
2-8

General FIRQB Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-13

General XRB Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-14

2-9

Format of Pseudovector Region of High Segment . . . . . . . . . . . . . . . . . . . . . . .

2-16

4-1

General Form of the Directive Parameter Block . . . . . . . . . . . . . . . . . . . . . . . .

4-3

1-1

RSX and RT-11 Development Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-3

3-1

Summary of General Monitor Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-1

3-2
3-3
3-4
3-5

Summary of CALFIP Subfunctions .... : . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-12

Fixed Monitor Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-138

Summary of .PLAS Subfunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-139

Data Input with .READ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-166

3-6

Special Functions for Magnetic Tape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-210

3-7
3-8

Value Returned by .SPEC for Magnetic Tape . . . . . . . . . . . . . . . . . . . . . . . . . .

3-211

Private Delimiter Masks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-220

3-9

Summary of .ULOG Subfunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-234

3-10

.UUO Subfunctions -

Calls to the File Processor (FIP) .................. .

3-248

3-11

Data Output with .WRITE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-419

4-1

Example of RSX Directive Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4-4

Tables

xii

4-2

First 512. Bytes of low Segment for RSX . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4-9

5-1

Summary of the RSX Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5-1

5-2

Vertical Format Control Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5-49

6-1

EMT Instructions Recognized by the RT-11 Run-Time System .............. .

6-2

locations in First 512. Bytes That RT-11 Uses . . . . . . . . . . . . . . . . . . . . . . . . .

6-5
6-9

6-3

Offsets to Important Scratch Pad Area locations . . . . . . . . . . . . . . . . . . . . . . . .

6-11

7-1
7-2

RT-11 Calls Not Functional on RSTS/E . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RT-11 Run-Time System Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7-1
7-2

A-1

RSTS/E Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

A-1

B-1
B-2

MODE Values for File-Structured Disk Access (FIROB+FOMODE) ........... .

8-1

MODE Values for Non-File-Structured Disk Access (FIROB+FOMODE) ........ .

B-2

B-3

Disk Device Sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-2

B-4

Flexible Diskette MODE Values (FIROB+FOMODE) . . . . . . . . . . . . . . . . . . . . . .

B-5

Flexible Diskette RECORD Values (XRB+XRBlK) . . . . . . . . . . . . . . . . . . . . . . .

B-3
B-3

B-6

MODE Values for File-Structured Magnetic Tape (FIROB+FOMODE) ......... .

B-4

B-7

ClUSTERSIZE Values for File-Structured Magnetic Tape Files
(FIROB+FOClUS) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

B-4

B-8

line Printer MODE Values (FIROB+FOMODE) . . . . . . . . . . . . . . . . . . . . . . . . .

B-6

B-9
B-1 0

line Printer RECORD Values (XRB+XRMOD) . . . . . . . . . . . . . . . . . . . . . . . . . .

B-6

Terminal MODE Values (FIROB+FOMODE) . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-7

8-11

RECORD Values for Terminal Input (XRB+XRMOD) . . . . . . . . . . . . . . . . . . . . .

B-7

8--12

RECORD Values for Terminal Output (XRB+XRMOD) . . . . . . . . . . . . . . . . . . . .

B-8

8-13

Echo Control Mode Character Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

B-8

8-14
8-15
8-16

Pseudo Keyboard MODE Values (FIROB+FOMODE) . . . . . . . . . . . . . . . . . . . . .

8-10

RECORD Option Bit Values for Pseudo Keyboard Output (XRB+XRMOD) ...... .

8-10

Possible Errors on Pseudo Keyboard Output Request . . . . . . . . . . . . . . . . . . . .

8-11

Preface

Objectives
This manual describes directives to the RSTSIE monitor, the RSX emulator,
and the RTll emulator that you can use in MACRO programs. 'lb use these
directives, you should be familiar with the MACRO-ll assembly language.
MACRO is the standard assembler for DIGITAL PDP-ll computers and is
available under various operating systems for the PDP-ll. Note that the syntax
is basically the same for all operating systems.

Manual Structu re
This manual contains seven chapters and two appendixes:
Chapter 1

Gives an overview of run-time systems and jobs as they relate to the
system directives.

Chapter 2

Describes the RSTSIE environment (memory allocation and job space) for
the general monitor directives.

Chapter 3

Contains reference material for the general monitor directives that you
can use in programs compiled under either the RSX or RTll run-time
systems.

Chapter 4

Describes the RSX environment for the RSX directives.

Chapter 5

Contains reference material for the directives processed by the RSX
emulator or the RSX run-time system.

Chapter 6

Describes the RTll environment for the RTll directives.

Chapter 7

Contains reference material for the directives processed by the RTll
emulator in the RTll run-time system.

Appendix A

Lists the RSTSIE errors you can get during directive processing.

AppendixB

Summarizes MODE and RECORD values and other useful information
for disks, flexible diskettes, magnetic tape, line printers, terminals, and
pseudo keyboards.

xiii

Related Documents
For infonnation about the syntax of MACRO assembly language, see the PDP-ll
MACRO-ll Language Reference Manual.
Where appropriate, this manual references the following manuals from the RSTS
IE documentation set:

RSTS / E System Installation and Update Guide
RSTS / E System Manager's Guide
RSTS / E System User's Guide
BASIC-PLUS Language Manual
RSTS / E Programming Manual
RSTS / E Programmer's Utilities Manual
RSTS / E 7hsk Builder Reference Manual

Conventions
This manual uses the following conventions:
--t

The arrow means points to, or contains the address of, as when the stack
pointer register points to the first item in the stack. For example:
SP--t
item at top of stack
item one word down from top of stack

()

Parentheses mean the contents of the item that the parentheses surround. For
example, the contents of the program counter would be represented as:
(PC)

[]

Brackets around an item indicate that the item is optional. For example:

()

Braces around two or more items indicate that you must choose one of the
enclosed items. For example:
}
{ QIO$
QIOW$

Angle brackets around two or more items tell the MACRO assembler that the
items make up a list. For example:

QIO$ paraml [,param2]

GLOBAL<namel[,name2, ... ]>

xiv

Summary of Technical Changes for V10.0
Significant changes to the RSTS / E System Directives Manual are:
•

Allowable pack cluster sizes now go up to 64. See Appendix B.

•

RSTS/E now supports the RA70, RA90, RD31, RD32, RD53, and RD54 disk
drives. See Chapter 2.

•

RSTS/E now supports online creation and deletion of the virtual disk (device
DVO:). See Chapter 3, the section ".UUO-Execute BASIC-PLUS SYS Call,"
the subsection "UU.RTS."

•

RSTS/E now supports Local Area Transport (LAT) for both in-bound and
host-initiated connections. See Chapter 3, the section ".MESAG-Message
SendlReceive. "

•

RSTS/E now supports command recall and command line editing. See
Chapter 3, the section ".UUO-Execute BASIC-PLUS SYS Call," the subsection "UU.TRM."

•

RSTS/E now has a new in-memory structure called the job header, used
for user logical names and command line editing information. See Chapter
2 and Chapter 3, the sections "FSS-Check File Specification String" and
UU.ASS-AllocatelReallocate a Device, or Assign or List User Logical."

•

RSTS/E now supports extended user and system logical names. See Chapter
2 and Chapter 3, the sections "FSS-Check File Specification String" and
UU.ASS-AllocatelReallocate a Device, or Assign or List User Logical."

•

You can now use the UU.FIL call to control a file's BACKUP and IGNORE
bits. See Chapter 3, the section ".UUO-Execute BASIC-PLUS SYS Call," the
subsection "UU.FIL."

•

RSTS/E now supports floating resident libraries. See Chapter 3, the section
".UUO-Execute BASIC-PLUS SYS Call," the subsection "UU.RTS."

•

You can now use the UU.CFG call to set Answerback messages for electronic
messaging services such as TELEX and TWX. See Chapter 3, the section
".UUO - Execute BASIC-PLUS SYS Call," the subsection "UU.CFG."

•

RSTS/E now supports the new RSX emulator directives, EXTM$, FEADF$,
FEAT$, MSDS$, SSTX$, TFEA$, and the fast-mapping facility. See Chapter 5.

Part I
Introduction

(
Chapter 1

Introduction

There are two MACRO assemblers available for the run-time systems on RSTSIE:
one for RSX and one for RT-ll. You will use one of these two run-time systems
to assemble and, in most cases, run your programs. In addition to user programs,
you can also write or modify run-time systems that run under direct control of
the RSTSIE monitor.
This manual describes the three types of system directives available to RSTSIE
assembly language programmers:
•

General monitor directives

•

RSX emulator directives

•

RT-ll emulator directives

Before you start using these directives, it is helpful to understand some basic
concepts about RSTSIE run-time systems and jobs.

1.1

Run-Time Systems
A run-time system lets you write code that can be shared by many users when
it is in memory. In a time-sharing system such as RSTSIE, shareable code is an
important consideration.
Run-time systems are nonnally written as pure (or shareable) code. This means
they have only instructions and fixed data, and contain no variable data. Such
code saves space, since many jobs can use it. It also saves time since run-time
systems are not swapped in and out of memory like user programs. Because the
run-time systems contain no variable data, they do not need to be swapped out to
disk; they are simply reloaded when they are needed again.

1.1.1

User Environment
The DCL, BASIC-PLUS, RSX, and RT-ll run-time systems all have a keyboard
monitor. That is, they can accept, analyze, and act on commands you type at a
terminal keyboard. The RSTS / E System User's Guide gives an overview of the
user environment these run-time systems provide.

(

Introduction

1-1

1.1.2

Program Environment
Run-time systems also provide an environment for programs. A run-time system
may include:
•

A loader. This code loads a program from disk into memory and starts its
execution.

•

An emulator. This code emulates directives handled by Digital's RT-ll
operating system for the PDP-ll computer.

•

A command interpreter. This code receives command lines from the user and
acts on them.
NOTE

The RSX run-time system provides only a user (command) environment. Both the program loader and the emulation functions for the
RSX environment are built into the RSTS/E VIO.O monitor.
A run-time system usually takes up space in the 34K-word area called the user
job area. Therefore, it limits the size of your program to less than 32K words.
The RT-ll run-time system takes 4K words of virtual memory. Since the monitor
emulates the RSX directives, programs running under the RSX run-time system
do not give up any addressing space. Chapter 2 explains space requirements in
greater detail.
Should you program under the RSX or RT-ll run-time system? RSX is usually a
better choice because it is in the monitor and it offers easy access to most resident
libraries. Your decision depends on:

1.1.2.1

•

Whether you are coding MACRO subroutines for use in a high-level language
program

•

Which set of program development tools better satisfies your needs

•

Whether you want to use resident libraries

•

Whether you need separate Instruction and Data Space (I&D Space) support
for programs larger than 32K words

High-Level Languages
When you write MACRO subroutines for use in high-level language programs,
the high-level language dictates which run-time system you must use. BASICPLUS-2, COB0L-81, PDP-ll COBOL, DIBOL, and FORTRAN-77 all run under
the RSX emulator, while FORTRAN-IV runs under the RT-ll run-time system.
You must compile, link, and run all the modules in your program under the same
run-time system, whether your program is written in MACRO or in a high-level
language.

1-2

Introduction

1.1.2.2

Program Development Tools

As Table 1-1 shows, RSTSIE provides one set of program development tools for
the RSX environment and another set for the RT-ll environment.
Table 1-1: RSX and RT"':11 Development Tools
Tool

RSX

Assembler

MAC
TKB

Linker
Librarian
Patch Utility

RT-ll
MACRO

LBR

LINK
LIBR

PAT

While the tools for each environment perform similar functions, they differ in
their speed and capabilities:
•

Assemblers-RSTSIE supports two MACRO-ll assemblers, the RSX-based
MAC assembler and the RT-ll-based MACRO assembler. The two assemblers
are nearly identical in function and performance and produce similar output.

•

Linkers-RSTSIE supports two linkers: the Task Builder (TKB) for RSXbased programs and LINK for RT-ll-based programs. While LINK is faster
than the Task Builder, the Task Builder is more powerful. It can link much
larger and more complex overlay structures (including co-trees) than LINK.
Unlike LINK, the Task Builder has options for linking to resident libraries
and support for separation of instructions and data.

•

Librarians-RSTSIE provides LBR for RSX-based programs and LIBR for
RT-ll-based programs. You can create object and macro libraries with either
utility. LBR also lets you create universal libraries, which can contain any
type of file, including text files.

•

Object module patch utilities-RSTSIE provides a PAT utility for each environment. Both let you update code in a relocatable binary object module.

For details on these program development tools, see the:

1.1.2.3

•

RSTS / E Task Builder Reference Manual-Describes the Task Builder

•

RSTS / E Programmer's Utilities Manual-Describes the RSX-based MACRO
assembler, librarian, and object module patch utilities

•

RSTS / E RT-ll Utilities Manual-Describes the RT-ll-based MACRO assembler, librarian, linker, and object module patch utilities

•

PDP-ll MACRO-ll Language Reference Manual-Describes the MACRO-ll
relocatable assembler

Resident Libraries

When you program under RSX, you can easily use Digital-supplied resident
libraries (such as RMS-ll and FMS-ll) as well as create your own resident
libraries. Also, because of the Task Builder's cluster library feature, many
resident libraries can share the same virtual address space in your program.
You can also use resident libraries under the RT-ll emulator, but the coding is
more difficult. Unlike RSX, you must use .PLAS directives to map and create
address windows inside your task. Coding these directives can be quite complex.
The Task Builder, on the other hand, has options that build tables describing
your task and the window to map, and automatically includes the code to perform
Introduction 1-3

the necessary .PLAS directives for you. Thus, RSX is a more practical choice than
RT-ll if you plan to use resident libraries.

1.1.2.4

Instruction and Data Space
The manipulation of Instruction and Data Space (I&D Space) is an advanced
programming technique that effectively doubles the user's virtual address range
from 32K words to 64K words. The memory management unit in some PDP-ll
processors can relocate data and instruction references with separate base address values. Thus, it is possible to have a user program of 64K words consisting
of 32K words of pure instructions or procedure code and 64K words of data-all
within a program's virtual address range.

1.1.3 Directives for Each Programming Environment
RSTSIE has three types of directives:
•

Monitor ("native" RSTSIE directives)

•

RSX emulator

•

RT-ll emulator

Monitor directives are processed directly by the RSTSIE monitor (see Chapter 3).
You can assemble monitor directives using either the RSX-based or the RT-llbased MACRO assembler, and you can use these directives in both user programs
and run-time systems. (When you write a program to run under the RT-ll
run-time system, you must precede all monitor directives with a special "prefix
EMT"; see Chapter 6 for details.)
The RSX emulator, which is part of the RSTSIE monitor, processes the RSX
emulator directives. These directives, which have basically the same form and
function as a subset of the RSX-llM-PLUS operating system monitor directives,
perform non-file-structured 110, trap handling, and memory management.
You must use the RSX-based MAC assembler to assemble the RSX emulator
directives, and you can use them only in a user program that runs under the RSX
emulator. Chapters 4 and 5 describe the RSX run-time system environment and
emulator directives in detail.
RT-ll emulator directives are processed by the RT-ll emulator, which is in
the RT-ll run-time system. These directives provide most of the single-job
programmed requests available to MACRO programmers using the RT-ll
operating system. The RT-ll run-time system also provides directives for the
RSTSIE environment not available under the RT-ll operating system. You must
use the RT-ll-based MACRO assembler to assemble RT-ll emulator directives;
you can use them only in a user program that runs under the RT-ll run-time
system. Chapters 6 and 7 describe the RT-ll run-time system environment and
emulator directives in detail.

1.1.4 Writing or Modifying a Run-Time System
If you want to modify an existing run-time system or code your own run-time

system, you can use either assembler. You may find the RT-ll-based programming tools easier to use for this purpose than the RSX-based programming tools,
mainly because it is easier to link run-time systems with the LINK program than
with the Task Builder. Run-time systems always have a specific address for their
top (highest) address. When you use LINK, you can specify the top address the
first time you link the run-time system. But when you use the Task Builder, you
1-4 Introduction

have to link your run-time system twice-once to find its size, and again to adjust
its top address to the value you want.
Unlike a program, a run-time system can contain monitor directives only, not
RSX or RT-ll emulator directives. In addition, you must store the run-time
system file (the product of assembling and linking) on the system disk in save
image library (SIL) format. Th create a SIL file, use:
•

[1,2]MAKSIL.TSK-For run-time systems assembled with MAC and linked
with the Task Builder

•

[1,2]SILUS.SAV-For run-time systems assembled with MACRO and linked
with LINK.

1.2 Jobs
Like run-time systems, you can view "jobs" from several angles. To the RSTSIE
monitor, a job is a unit of work generally associated with activity at a terminal.
For example, suppose that a user types a line at a previously inactive terminal.
The monitor creates a job, assigning a job number and allocating internal tables
for bookkeeping. The monitor then passes control to a new-user entry point in
the default keyboard monitor, DCL.RTS.
The default keyboard monitor has code at this entry point that causes the LOGIN
program to be loaded from the system disk and executed. LOGIN analyzes what
was typed and performs the normal log-in dialogue. When LOGIN exits for
a valid login, control passes to the default keyboard monitor, which waits for
further input from the terminal.
The monitor considers running the LOGIN program and the default keyboard
monitor, and whatever else occurs at the terminal until the user logs out as the
same job. (If the log-in sequence was not valid, LOGIN exits with the job still
logged out. The monitor destroys the job and releases the job number.)
As a MACRO programmer, your awareness of the job concept probably focuses
on the work space RSTSIE provides for each job, and the fact that the run-time
system can take part of this work space. Chapter 2 describes the allocation of
work space.

(

Introduction

1-5

Chapter 2

General RSTS/E Environment

This chapter explains how and why one copy of a run-time system, shared by
many users, can still take up space in each user's work area. The sections in this
chapter and their purposes are:
•

How RSTS/E Allocates Memory: Physical and Virtual Addressing
This section provides some background on memory accessing in the PDP-11.

•

Job Space: High Segment and Low Segment
This section explains how RSTS/E uses memory accessing to define a job
space for each user to run programs.

•

Important Installation Options
This section briefly describes resident libraries and the special-case
disappearing RSX run-time system.

•

Low-Segment Details: First 512. Bytes of the Low Segment
This section gives specifics on how the monitor uses the low 512. bytes of
virtual address space.

•

High-Segment Details: Pseudovectors
This section explains how the monitor and the run-time systems use
pseudovectors to communicate with each other.

2.1

How RSTS/E Allocates Memory: Physical and Virtual
Addressing
All RSTS/E systems use the memory management feature available on PDP-11
computers. This feature extends the addressable memory range of the PDP-11
processor by using hardware registers called Active Page Registers (APRs).
The PDP-11 processor handles 16-bit operand addresses. The PDP-11 is
byte-addressable, so the address range is from through 2 A 16 -1 (65535
decimal, 177777 octal), which equals 64K bytes or 32K words. With the memory
management unit, RSTS/E treats a 16-bit address as a relocatable (virtual)
address that is combined with information in an APR to form an 18-bit (22-bit,
for the PDP-11/23+, 11/44, 11/53, 11170, 11173, 11/83, 11/84, 11/93, and 11/94)
physical address. On some PDP-11s (11/44, 11/45, 11/50, 11/53, 11/55, 11170,
11173, 11/83, 11/84, 11/93, and 11/94), the memory management unit gives you
two areas of 32K words each. You can put code (instructions) in one of these
areas and data in the other. RSTS/E requires that you write your program using
special techniques to take advantage of both of these areas. This capability is

General RSTS/E Environment

2-1

known as Instruction and Data (l&D) Space. You have to use the RSX tools
(specifically TKB) to build programs with separate instruction and data sections.
The PDP-ll Architecture Handbook explains in detail how the APRs function.
Briefly, an APR consists of two 16-bit registers. These registers define a page
of contiguous memory. The Page Address Register (PAR) defines the physical
memory location where the page begins. The Page Descriptor Register (PDR)
defines, among other things, the maximum length of the page and how you can
access it (for example, read/write or read-only).
In Figure 2-1, the virtual address of 72322 (octal) identifies APR 3 and byte
12322 (octal) of the page defined by APR 3. The PAR of APR 3 indicates a
starting address of 146000 (octal) for the page. The physical address obtained is
146000+012322, or 160322 (octal). The byte offset field in the virtual address is
13 bits long. The maximum size of a page, then, is 21\13 bytes, or 4096 words. In
other words, one APR can map a virtual address range of up to 4K words into an
equal extent of physical memory.
Figure 2-1 shows how you can combine a virtual address and a PAR to form a
physical address in memory.
Figure 2-1:

How a Physical Address Is Formed

Virtual Address

15 13 12

111 0 1 0 0 1 1 0 1 0 0 1 0 I

10 1
3

'" . - ) , - - - - -___ r - - - - - - J )

-yAPR

byte offset within page

Page Address Register

(21)
15

(18 17)
12 11

(6)

(0)

I0 0 0 010 0 1 1 0 0 1 1 000 010 0 0 0 0 01
146

000

,~------------~y ~------------~)
starting address of page

18 17

I0 0 0 010 0 1 1 1 0 0 0 0 0 1 110 1 0 0 1 0 I
,~

6
________________

2
2-J)
o________________
3

V
Physical Address

2-2

General RSTS/E Environment

The 16-bit virtual address defines which APR the system uses and the byte offset
within that page. The system handles the PAR of the indicated APR as though it
contains bits 6-17 (6-21 for the PDP-1l/23+, 11/24, 11/44, 11170, 11173 and 11/84)
of an 18-bit (or 22-bit) physical address, defining the start of the page.
The memory management unit on the PDP-11 consists of two sets of APRs; eight
in each set on machines without I&D Space, 16 in each set on machines with
separate I&D Space. Since each APR can map a 4K segment of virtual memory
to physical memory, each set of APRs can provide access to 32K words of physical
memory on non-I&D Space machines, or 64K words on machines with I&D Space
capability.
NOTE

The PDP-11/44, 11/45, 11/50, 11/53, 11/55, 11170, 11173, 11/83, 11184,
11193, and 11/94 have three sets of APRs; the additional set is for
supervisor mode mapping. RSTSIE supports supervisor mode only
under the RSX run-time system. Using supervisor mode outside the
RSX run-time system may cause unpredictable results, including fatal
aborts.
The monitor uses one set, called the "kernel mode APRs," to map itself in physical
memory. It uses the other set, called the "user mode APRs," to map the job that
is active during the current time slice of time-shared processing.
Figure 2-2 shows the concept of mapping with the APRs.

General RSTS/E Environment

2-3

Figure 2-2:

Memory Mapping with the APRs

ACTUAL ADDRESSES
(PHYSICAL MEMORy)

4KW

8KW

12KW

:,:,

12KW

16KW

20KW

24KW

28KW

32KW

124KW
128KW

On the PDP 11/44, 11/45, 11/50, 11/53, 11/55, 11170, 11173, 11/83, 11/84, 11/93,
and 11/94, the RSTSIE monitor can take advantage of a hardware function, called
I&D Space. This function lets a program separate its instructions and data into
their own virtual address space. On these processors, there are actually two sets
of eight APRs for each mode. RSTSIE uses one set to map instructions, and the
other set to map data. So, instead of 32K maximum job size, there can be 32K of
I-Space and 32K of D-Space.
The monitor may use this type of mapping, depending on the number of small
buffers the system manager selects with the INIT option. (The RSTS / E System
Installation and Update Guide describes INIT.) For example, if the number of

2-4 General RSTS/E Environment

requested small buffers is large enough, the monitor may use D-Space APR 1 to
map small buffers and I-Space APR 1 to map common routines.
Figure 2-3 shows a task executing on an I&D-Space system without using
separate I&D Space. Note how the I-Space APRs and the D-Space APRs point to
the same physical memory.
Figure 2-3:

Conventional Task Linked to a Library in an I&D-Space System

PHYSICAL
MEMORY

VIRTUAL
ADDRESS
SPACE
Ubrary
28KW..---....:........,r

TASK

20KWI----. . . .

8KWI---~

OKWI---

8K
Ubrary

General RSTS/E Environment

2-5

Figure 2-4 shows a task using separate I&D Space. Note how the task's I-Space
APRs and D-Space APRs point to different physical memory. User programs
can also take advantage of I&D Space to increase their available virtual address
space.
Figure 2-4:

I&D-Space Task Mapping in an I&D-Space System

D-Space
32KWr--.....;...-...
Ubrary

PHYSICAL
MEMORY

24KW t---..:...12KWt----....

OKW I - - - - - f......

32KWt--....:....-......
24KWt---20K
TASK

8KW 1-----11-----Task
1

III:-s~p~a~ce~____------~O~~:L----------:----:
OKWL

2.2 Job Space: High Segment and Low Segment
The RSTSIE monitor is designed to handle work requested by a user through
an interface: the run-time system. For example, the BASIC-PLUS, DCL, RSX,
and RT-ll run-time systems (available as part of a RSTS/E system) each provide
their own keyboard monitor to accept and process user commands. Some of
these run-time systems also contain code to handle their own sets of directives,
accepting and expanding user program calls to the monitor. For example, the
RT-ll run-time system provides I/O calls to the monitor using the monitor
requests native to RT-ll, which the run-time system translates to the equivalent
requests known to RSTSIE, which are handled directly by the monitor.
Thus, the run-time system communicates with both the user program and
the monitor. Execution control passes back and forth between these three
independent elements; data is passed between them using established ranges of
virtual addresses. The monitor must be able to access both the run-time system
2-6 General RSTS/E Environment

and the user job image at any given time. The monitor does this by setting up
the run-time system as part of the 32K words accessible through the eight user
APRs.
The monitor assigns an area for the run-time system in the high portion of virtual
address space, called the high segment. The user job image (that is, the utility
program, compiler, assembler, or executable user program that is currently being
executed for the job) is in the low portion of virtual address space, called the low
segment.
NOTE

If you are using the monitor's RSX emulation, there is no high segment
at all.

As part of its housekeeping for each job, the monitor keeps track of:
•

Where the currently appropriate run-time system is

•

Where the user job image is

•

What the values were in the program counter register (PC), program status
word (PSW), and other job-context information at the end of the last time
slice

Before the next time slice for the job, the monitor loads the APRs with the correct
values for the job and loads the PC, PSW, and so forth, so execution continues
where it left off.
In any case, the high segment or run-time system takes up some multiple of
4K words of virtual address space, due to the APR mapping (see the previous
section). For example, the BASIC-PLUS run-time system, can take from 13 to
16K words of physical memory, depending on options selected when the system is
installed. Even though the physical memory required may be only 13K words, it
still requires four APRs to map this range, leaving four APRs (or a maximum of
16K words) for a user program. The monitor uses certain areas within the high
segment and the low segment to get information from the job (defining what work
the monitor is to do for it) and to pass information back to the job.

General RSTS/E Environment

2-7

Figure 2-5 shows the job area in virtual addresses. RSTSIE uses the first 512.
bytes to pass information between the monitor, the run-time system, and the
user job image for certain types of monitor directives. The monitor uses the
pseudovector region in high virtual memory to determine, for example, where
control is to be passed when a job is initially entered. The run-time system loads
this area with entry points and values to define itself to the monitor.
Figure 2-5:

Job Area in Virtual Memory

o~----------------------~_
Used by monitor; run-time
system, and user job image
to exchange information

User
Job Image
(Low
Segment)

A
"job"
to
RSTSIE

Run-lime

Pseudovector region used by the
monitor and the run-time system

System
(High
Segment)

The following subsections give more detail on these areas:
•

If you are interested in using the general monitor directives Chapter 3
describes, read the next section in this chapter, "Low-Segment Details: First
512. Bytes of the Low Segment."

•

If you want to code your own run-time system or modify one of the existing
ones and need to know about the pseudovector region, read the section in this
chapter entitled "High-Segment Details: Pseudovectors."

•

If you are using only the directives Chapters 5 or Chapter 7 describe, the RSX
and RT-ll run-time system directives set up the first 512. bytes of memory
for you.

2-8 General RSTS/E Environment

2.2.1

Low-Segment Details: First 512. Bytes of the Low Segment
The monitor attaches special significance to the first 512. bytes of virtual
address space in the low segment. The RSX Task Builder and RT-ll Linker
automatically allocate this space. These programs always assign relocatable
addresses beginning at location 1000 unless you request otherwise. If you want
to use the general monitor directives Chapter 3 describes, your program must
fill parts of this area with information for the monitor; the monitor passes
information back in this area.
Rather than use octal addresses, you can use the COMMON.MAC prefix file,
which Chapter 3 describes ("Prefix File COMMON.MAC"), to assign mnemonic
names to commonly used addresses and offsets. COMMON.MAC does not allocate
space, but rather assigns mnemonic names to areas within the first 512. bytes
of virtual address space. Use the mnemonics assigned with COMMON.MAC to
make the code more readable and easier to maintain.
Figure 2-6 shows the general regions in this area. Note that a run-time system
may use some of the areas differently when it assumes control. For example,
the RSX emulator uses the memory labeled default SP stack area as a table of
logical units. The Task Builder automatically generates a user stack after the
first 512. bytes of virtual address space. The section titled "First 512. Bytes of
Low Segment for RSX" in Chapter 4 briefly describes how RSX uses the first 512.
bytes.
If you use the general RSTSIE directives, you should reference only the areas that

are shown with mnemonics provided by COMMON.MAC. The mnemonics to the
right in Figure 2-6 are assigned through COMMON.MAC. A general description
of these mnemonics follows Figure 2-6. The general monitor cans in Chapter 3
describe specific formats for the areas the calls use.
Jobs do not have access to the job headers as part of the low segment.

General RSTS/E Environment

2-9

Figure 2-6:

First 512. Bytes of Low Segment
o

controlled solely by job-user job
image or run-time system
60
used by monitor for job
context information to make job swappable
110
used by monitor for
hardware floating-point context information
to make job swappable
170
default SP stack area
400 KEY USRSP
keyword
402 FIRQB
file request block
442 XRB
transfer request block
460 CORCMN
core common area
660
controlled solely by job
734 USRPPN
user-assignable project-programmer number
736 USRPRT
user-assignable default protection code
740 USRLOG
old user logical device name table

776

KEY (Keyword)

The keyword defines the job's status in the time-sharing environment; for example, the job's privilege. Bits in the keyword can be set and cleared by the monitor
or by the job (either the run-time system or the user job image). The job can
manipulate some bits in the keyword with the .SET and .CLEAR directives.
The keyword is "refreshed" by the monitor at certain points; for example, when a
run-time system is entered at P.RUN, where the intent is to load and execute a
program file in the user job image (.RUN directive). For a keyword refresh, the
monitor clears bit 15 and bits 7-0 and sets the remaining bits to indicate the job's
current status. Only seven bits (8-14) are significant to the monitor. You can use
the other bits in whatever manner you want.
JFSPRI ----------~
JFFPP------,
JFPRIV - - - - - - ,

JF~bg~~~~S! 1 1
15

II
2-10

General RSTS/E Environment

status bits

The following descriptions apply when the keyword status bit is set to one:
JFLOCK

The job does not want to be swapped. You can change this bit with .SET and
.CLEAR. When this bit is set, the only normal condition that causes the job
to be swapped is when the job asks for a memory size expamlion (Ree .CORE
directive) and there is not enough room to do the expansion where the job now
is in memory.

JFBIG

The job can exceed its private memory maximum (see .CORE directive). This
bit is set if the job currently has EXQTA privilege, usually because the job is
running a privileged program. JFBIG is an informational bit that the system
updates whenever the EXQTA privilege is turned on or off.

JFNOPR

The job is not yet logged in. JFNOPR is an informational bit that the monitor
can alter when the job is logged in.

JFSYS

The job is currently running with temporary privileges. The monitor sets
JFSYS when a job with insufficient privileges needs to run a privileged
program. Once the program is run, the job can regain temporary privilege by
setting this bit and can drop privilege temporarily by clearing it.

NOTE

When a job exits from a privileged utility
that can be executed by users with insufficient privileges, the monitor clears this bit
so another user cannot use the temporary
privilege set up for the job.
JFPRIV

This bit is only for compatibilty with RSTSIE releases prior to V9.0. JFPRIV
is set if the current job has all of the following privileges: HWCFG, SWCFG,
SYSIO, RDMEM, and WWRITE.

NOTE

Any new software should not reference
JFPRIV.
JFFPP

The contents of the hardware floating-point unit (if any) should be part of
the context of this job. That is, information in the floating-point registers
should be saved and restored along with the rest of the user job image during
swapping. Any program that uses the hardware floating-point unit should set
this bit. It can be changed with the .SET and .CLEAR directives.

JFSPRI

The job is running with a special run priority: 1/2 level higher than normal.
This bit can be changed with the .SET and .CLEAR directives. The monitor
clears JFSPRI when the program exits.

USRSP (User Space)

COMMON.MAC assigns the value 400 to USRSP. The monitor automatically
loads this value into the stack pointer register (SP) when a job is created. SP is
also reset to this value under certain conditions, effectively establishing a default
user stack area for the job beginning at word 376. The user stack area ends at
location 170. Any attempt to push the stack past location 170 results in a stack
overflow error that is handled by the run-time system (see the description of
P.BAD later in this chapter).

General RSTS/E Environment

2-11

You can change SP if you want. However, any attempt to reset SP to any location
between 0 and 167 causes a stack overflow error. In addition, the monitor resets
SP to 400 when a run-time system is entered with a .RUN, .CCL, or .RTS directive, and when certain catastrophic errors occur, such as a fatal disk error while
the user job image was being swapped.
NOTE

You need to be aware that the monitor resets SP at these times only if
you are coding or modifying a run-time system. The system does not
return control to a user program under these conditions, because the
program cannot recover.
FIRQB (File Request Block)

The FIRQB is the main communication area between the monitor and the job for
monitor directives that involve file or device operations such as open, close, and
so forth. Either the run-time system or the user job image can use this area:
•

If you use the general monitor directives that Chapter 3 describes, your
MACRO program must store values in the FIRQB before issuing some of the
directives.

•

If you choose to use the directives in the RSX emulator or the RT-ll run-time

system, the RSX or RT-ll emulation code intercepts the request, sets up the
FIRQB and other relevant areas, then calls the monitor to handle the request.
Figure ~7 shows the general format of the FIRQB, with all mnemonics that
COMMON.MAC assigns. In addition, the size of the FIRQB (32. bytes) has the
mnemonic FQBSIZ.

2-12 General RSTS/E Environment

Figure 2-7:

Mnemonic

General FIRQB Format

Octal
Offset

Mnemonic

1/1/1/1/1/

returned status

FIROB

FOFUN

CALFIP/.UUO subfnc.

job number· 2

FOJOB

FOSIZM

MSB of file size

channel number· 2

project number

programmer number

FOFILI
FOERNO
FOPPN

FONAM1

file name in RAD50 format
(2 words)

file type in RAD50 format (1 word)

FOEXT

LSB of file size

FOSIZ

buffer length

mode

FOBUFLI
FONAM2
FOMODE

status flags

FOFLAG

FOPFLG

FODEV

FODEVN

FOPROT 27
31
33

protection code

=0, prot. code real

device name (2 ASCII characters)
=O,unit number real

device unit number

cluster size

FOCLUS

number of entries in directory lookup

FONENT

XRB (Transfer Request Block)

The XRB is the main communication area between the monitor and the user for
monitor directives handling file or device 110. It is also the area in which the
monitor stores information requested by straightforward information-request
calls. As with the FIRQB, the general monitor directives (see Chapter 3) require
that you store and retrieve information directly to and from the XRB. The RSX
and RT-ll emulators handle additional directives, which they translate to calls
using the XRB (see Chapters 5 and 7). Figure 2-8 shows the general format of
the XRB, with all mnemonics that COMMON.MAC assigns. In addition, the size
of the XRB (14. bytes) has the mnemonic XRBSIZ.

General RSTS/E Environment

2-13

Figure 2-8:

Mnemonic

XRBLKM

General XRB Format

Octal
Offset

Mnemonic

buffer size in bytes

XRLEN

number of bytes transferred

XRBC

buffer address

XRLOC

XRCI

Octal
Offset

MSB of block number

channel number * 2

LSB of block number

XRBLK

wait time for terminals

XRTIME

device modifier

XRMOD

A buffer, as defined by XRLOC for its start and (XRLOC+XRLEN)-l for its last
byte, can be either an input buffer or an output buffer. RSTSIE uses input
buffers to read data into user memory and output buffers to write data from user
memory. These buffers must lie wholly within either the job image (low segment),
or the run-time system (high segment), or they must start in a window mapped to
some library. Buffers within libraries must lie wholly within the library, but need
not be wholly mapped.
For input buffers, the value passed in XRB+XRBC must be zero. For output
buffers, the value passed in XRB+XRBC is the number of bytes to be sent and
cannot be zero if the value in XRB+XRLEN is nonzero. In addition, input buffers
are subject to the following rules:
•

If the buffer is in the low segment, the address defined by the contents of
XRB+XRLOC must be greater than 170 to avoid destroying the job-context
data used in swapping the job.

•

If the buffer is in the high segment, it must not fall within the pseudovector
region. That is, it must not fall above the location P.OFF. In addition, the
run-time system must currently be mapped read/write because the monitor
is writing data to the buffer for the receive (see PF.RW bit description in
P.FLAG word).

•

If the buffer is in a library window, the library must be installed as read/write
and must be attached and mapped read/write.

CORCMN (Core Common Area)

The CORCMN is used as a common data exchange area when it is necessary
to exchange lengthy data (such as strings) between the monitor and the job or
between programs running under the same job number.

2-14 General RSTS/E Environment

For example, the monitor uses CORCMN to pass to the job a string that is the
full name of a command that has been recognized as a valid Concise Command
Language (CCL) command. The RSTSIE CCL lets users type one-line commands
to call utilities that might otherwise require several input lines from the terminal.
For example:

CCLForm
$ PIP FILE1.=FILE2.

Regular Form
$ RUN $PIP
*FILE1.=FILE2.

*"Z
$

To centralize decoding, the monitor analyzes CCL commands by comparing them

to those defined by the system manager (usually during system start-up). With
the .CCL directive, a job can ask the monitor to analyze a string to see if it is an
acceptable command. If it is, the monitor passes control to the run-time system
associated with that CCL command and passes the command and any argwnents
to the job in the CORCMN area.
The general format of the CORCMN area is:

byte 1 of string

number of bytes
in string

460 CORCMN

byte 3 of string

byte 2 of string

462

(up to 127. bytes of data)

USRPPN, USRPRT, USRLOG and the Extended Logical Area

These bytes are set up using the .ULOG directive to store the assigned projectprogrammer number (USRPPN), default protection code (USRPRT), and assigned
logical device names (USRLOG or the extended logical area of the job header),
which the monitor then uses when an .FSS directive is executed. The .FSS
directive causes the monitor to convert a file name string to the standard RSTSIE
file specification format; that is, to the FIRQB format.
The USRLOG byte is no longer used in RSTSIE VlO.O. The information formerly
passed in that byte is now passed in the extended logical area of the job header.
The .FSS directive first processes the extended logical area of the job header. If
there are no logicals there, it checks the old USRLOG area for logicals before
returning an error.
The .ULOG and .FSS directives also let you define and use some nonstandard
area to contain these values (see Chapter 3). However, the .ULOG directive now
sets up the extended logical area of the job header; the .FSS directive expects
these values in the same relative locations.
NOTE

The only way you can manipulate the extended logical area of the job
header is by using the the .ULOG directive.
General RSTS/E Environment

2-15

2.2.2

High-Segment Details: Pseudovectors
The monitor and the run-time system use the pseudovector region to communicate
with each other. Figure 2-9 shows the general layout of this area. As with
the low 512. bytes of virtual address space, the file COMMON.MAC assigns
mnemonic names to locations in this area. These names are shown to the right
in Figure 2-9. The following text describes each of these areas in detail. If you
want to modify or code your own run-time system, the format and meaning of
these areas is important. Otherwise, you might want to examine them to see how
the run-time system and the monitor communicate.
Figure 2-9:

Format of Pseudovector Region of High Segment
Addresses

flags describing the run-time system

177732

normal executable file type

177734

(reserved)

177736

Mnemonics

P.FLAG/
P.OFF
P.DEXT

minimum size, in K words, of user job image

177740

P.MSIZ

exception address fOi FIS hardware option

177742

P.F!S

(reserved)

177744

(reserved)

177746

entry point for new user

177750

P.NEW

entry point for new user with program to run

177752

P.RUN

exception address for various "bad" errors

177754

P.BAD

exception address for BPT instruction and T -bit

177756

P.BPT

exception address for lOT instruction

177760

P.IOT

exception address for nonmonitor EMT instruction

177762

P.EMT

exception address for all TRAP instructions

177764

P.TRAP

exception address for FPP or FPU

177766

P.FPP

exception address when user types one CTRLlC

177770

P.CC

exception address when user types two CTRLlCs

177772

P.2CC

maximum size (in K words) of user job image

177774

P.SIZE

(reserved)

177776

In general, the pseudovector region contains:
..

2-16

Values and flags that define the capabilities of the run-time system for the
monitor. For example, one flag indicates whether the run-time system has a
keyboard monitor.

General RSTS/E Environment

•

Addresses pointing to locations in the run-time system where the monitor is
to pass control when certain conditions occur. These addresses fall into three
categories:
Addresses for Synchronous Exceptions. Control passes to these locntions
when the job executes an instruction that causes a trap to the monitor.
The monitor passes control to the run-time system along with the contents
of the program counter (PC) and program status word (PSW). The term
"synchronous" is used in the sense that the trap occurs at the same time
as (and is a direct result of) some instruction executed by the job. These
traps mayor may not indicate an error. For example (except for the
PDP-11/23 PLUS or 11/24), if the job executes an instruction with an odd
address, control passes to one of these trap addresses. If the job simply
executes a BPT instruction, control passes to another of these addresses.
Addresses for Asynchronous Exceptions. Control passes to these locations
as a result of some event, which can be either of the following:
•

External to the execution of the job (for example, the user types a
CtrllC at the terminal)

•

Internal but asynchronous process (such as an error in the hardware
floating-point processor, whose execution overlaps that of the PDP-11
CPU)

When such conditions occur, control passes to the monitor, which passes
control to the run-time system, along with the contents of the PC and
PSW. If a floating-point trap occurred, the monitor also passes along the
floating exception code (FEC) and floating exception address (FEA). For
the asynchronous traps, the PC and PSW do not refer to the instruction
that caused the trap, but to the instruction that was executing in the
central processor when the trap occurred.
Entry Point Addresses. The monitor passes control to the run-time system
at entry-point addresses when some major transition point is reached for
the job. For example, when you type a RUN or CCL command at the
terminal, the monitor passes control to an entry point in the appropriate
run-time system, to load and execute the requested program.
NOTE

The term pseudovector arises from the relationship of some of these
(one-word) trap addresses in the pseudovector region to the (two-word)
vector addresses in kernel-mode memory set up to handle error traps
and interrupts in the PDP-11. When the RSTSIE monitor receives
control as a result of a trap to certain of these vector addresses, it
passes control on to the run-time system at addresses specified in the
pseudovector region.
Normally, you code the contents of the pseudovector region as part of the runtime system file. However, the INSTALLIRUNTIME_SYSTEM command, used
to define a file as an auxiliary run-time system, has qualifiers that cause the
monitor to override certain portions of the pseudovector region in the file and use
values assigned in the INSTALL command. For example, one bit in one word
of the pseudovector region states whether the run-time system is read/write or
read-only when it is loaded in memory. Normally, this would be read-only, but
for debugging a run-time system with the Octal Debugging Tool (ODT), which
allows you to change memory, the run-time system must be read/write. The
INOREAD_ONLY qualifier in the INSTALL command lets you tell the monitor
that until further notice, this run-time system is read/write, regardless of what is

General RSTS/E Environment

2-17

specified in the pseudovectors. The RSTS / E System Manager's Guide describes
the INSTALLIRUNTIME_SYSTEM command.
2.2.2.1

Run-Time System Capability and Default Definitions

The following mnemonics refer to values and flags that define run-time system
capabilities for the monitor.

P.OFF
Use the P.OFF mnemonic to define the first word of the pseudovector region. It is
currently set equivalent to 177732, the same as P.FLAG.

P.FLAG
The monitor expects the P.FLAG word to be set with flags that define the capabilities of the run-time system:
PF.KBM------,
PF.1 us:-----,
PF.R:W-----,

prffizill
15

flags

(prefix EMT code if PF.EMT=1)

PF.EMT
This bit is set to indicate that the run-time system wants to handle a call that
would normally be handled by the monitor. To show how the bit works, it is
necessary to first describe what normally happens when a monitor directive is
translated and executed.
All of the monitor directives that this manual describes are translated to emulator
trap (EMT) instructions. The direct monitor calls are one-for-one translations;
that is, one call is translated to one EMT (see Chapter 3). The code to process the
call is in the monitor itself.
The RSX and RT-11 emulator calls may be translated to more than one instruction, but the code always contains an EMT. In addition, the direct monitor calls
are translated to an EMT with a low byte that is an even number within the
range 0 to 114 (octal). When such an instruction is executed, control transfers
directly to the monitor, the call is processed, and control returns to the instruction
following the EMT.

An EMT instruction with an odd value in the range 1 to 113 in the low byte,
or any value in the range 115 to 377, also transfer control to the monitor. The
monitor examines the low byte, discovers that the EMT is not one of its own, and
transfers control to the run-time system at the entry point defined by location
P.EMT in the pseudovector region.
Now the PF.EMT bit is set to one to indicate that the run-time system wants
to process EMTs that are normally processed by the monitor, that is, with an
even low byte in the range 0 to 114. When PF.EMT is set to one, all EMTs cause
control to pass to the run-time system at the P.EMT entry point, except those

2-18 General RSTS/E Environment

immediately preceded by a special prefix EMT-an EMT whose low byte is equal
to the low byte of P.FLAG.
Specifically, when PF.EMT equals one, the monitor handles all EMT instructions
as follows:
•

Any EMT whose low byte is not equal to the low byte of P.FLAG causes
control to pass through the monitor (unprocessed except for examination), and
back to the run-time system at the address contained in the P.EMT word.

•

An EMT whose low byte is equal to the low byte of P.FLAG causes control
to pass to the monitor, which looks at the word following the EMT with the
special code; that is, at the word in location (PC)+2. Action is taken according
to the value of this word:

(PC)+2 =
an EMT instruction?

Pass control to
(P.EMT)

YES

Low byte of (PC)+2
even,O-114?

YES
Execute second EMT
@(PC)+2 as normal,
return control to (PC)+4

In other words, the run-time system does special processing for all EMTs, except
those preceded by a special prefix EMT. The RT-ll run-time system uses this
feature so it can emulate the RT-ll operating system's directives properly.
PF.CSZ

For a user job image executed as a result of a .RUN directive, the monitor
preallocates memory based on information provided by the run-time system
under which the image is executing. When this bit is set, the monitor preallocates
memory based on the size of the file referenced in the .RUN directive:
space (in K words) = (filesize + 3)/4
Filesize is the number of 512-byte blocks required for the file on disk. (The
division by four is performed because there are four 512-byte blocks in lK word.
The addition of three rounds any fraction of the integer divide to the next whole
integer.)
When PF.CSZ is clear, the monitor preallocates memory for the image according
to the value specified in the P.MSIZ word of the pseudovector region.

General RSTS/E Environment 2-19

PF.REM

When the PF.REM bit is set, the monitor immediately removes the run-time
system from memory when no job is using it. When this bit is clear, the monitor
leaves the run-time system in memory until the space is actually needed by
something else.
PF.NER

When this bit is set, the monitor does not log errors occurring within the run-time
system to the system error log.
PF.RW

When this bit is set, the monitor maps the run-time system as read/write. (See
the read/write feature of the Page Descriptor Register of an APR, in the section,
"How RSTSIE Allocates Memory: Physical and Virtual Addressing.") This is a
useful feature when debugging a run-time system. In normal operation, this bit
should be clear, indicating that the run-time system is to be mapped read-only.
PF.1US

When the PF.IUS bit is set, the monitor allows only one job to use the run-time
system; that is, it is not handled as shareable code.
PF.KBM

When this bit is set, the monitor expects that the run-time system can function
as a keyboard monitor. Note that the run-time system can function as a job
keyboard monitor only when this bit is set. See the .RTS directive in Chapter 3
for a discussion of job keyboard monitors.
P.FLAG COMBINATIONS

The PF.IUS, PF.RW, PF.NER, and PF.REM bits are useful flags when you are
debugging a run-time system:
•

PF.IUS limits access to the run-time system to one user.

•

PF.RW is necessary if you want to use the ODT routine to change memory.

•

PF.NER keeps the run-time system from logging useless errors while debugging.

•

PF.REM ensures that the run-time system will be reloaded each time it is
used. (Otherwise, an old copy might still remain in memory when you really
wanted to debug a new copy.)

P.DEXT

You can set this word to three Radix-50 characters that the monitor uses as a
default runnable file type. If a .RUN directive executes with no file type given,
the monitor scans its list of installed run-time systems in the order they were
installed (see Chapter 3).
NOTE

The order of installation shows up in the display that the SHOW
RUNTIME_SYSTEM command produces.

2-20

General RSTS/E Environment

The monitor first checks for .TSK files which are executed by the null run-time
system. If such a file is found, it is set up for the .RUN. If no such file is found,
the monitor searches for a file with the given file name and the next run-time
system's default runnable file type, and so forth. Note that the order in which
the file types are chosen does not depend in any way on the run-time system
executing the .RUN.
P.MSIZ

The P.MSIZ word gives the minimum allowable size for a user job image, in K
words, for this run-time system. The monitor uses this value as a check when the
job issues a .CORE directive to change the size of the user job image in memory
(see Chapter 3). The value of P.MSIZ must be an integer between 1 and the value
in P.SIZE, inclusive.
P.SIZE

The P.SIZE word contains the maximum size, in K words, that a user job image
can be for this run-time system. The monitor uses this value as a check when a
job issues a .CORE directive to change the size of the user job image in memory.
P.SIZE must be an integer between 1. and 32., inclusive. The effective upper
limit is 32. minus the size of the run-time system, rounded up to a multiple of
foW'. (Remember that the APR mapping requires that space for the run-time
system be allocated in units of 4K words.) Thus, a run-time system that required
5K words could set an upper limit here of 24. (32.-8.). However, it could set
P.SIZE to some smaller value.

2.2.2.2

Synchronous Exception Handler Addresses

These mnemonics refer to locations in the run-time system where control is to
pass for synchronous exceptions.
P.FIS

The monitor interprets the P.FIS word as the trap address for the hardware
floating-point instruction set available on the PDP-1l/35 and 40. Whenever
an instruction from this set causing a trap to the kernel mode vector at 244
is executed, the monitor passes control to the run-time system at the location
specified by the contents of the P.FIS word.
This exception pushes two words onto the user's SP stack: the contents of the PC
and PS registers at the time of the exception. For example:
SP---+

(PC) at the time of the exception
(PS) at the time of the exception
word to which SP pointed before the exception

Whatever action the run-time system wants to take for this exception should be
done at the location specified by the contents of P.FIS. A return from interrupt
(RTI) instruction returns control to the point where it was when the exception
occurred.
P.BAD -

Synchronous Exceptions

The monitor passes control to the run-time system at the location specified by the
contents of P.BAD when any of the following synchronous exceptions occw':
•

Memory management unit exception (trapped to kernel mode vector at 250).

•

The job tries to execute a reserved instruction (trapped to kernel mode vector
at 10).

General RSTS/E Environment

2-21

•

The job issues an instruction with an odd address (trapped to kernel mode
vector at 4).

This exception pushes two words onto the user's SP stack: the contents of the PC
and PS registers at the time of the exception. For example:
SP----+

(PC) at the time of the exception
(PS) at the time of the exception
word to which SP pointed before the exception

The monitor returns an error code in the first byte of the FIRQB so the run-time
system can determine which error occurred. The error codes are:
B.4
B.IO
B.250

Odd address
Reserved instruction
Memory management unit exception

The run-time system is responsible for processing these errors in whatever
manner it sees fit. In general, most run-time systems provided with RSTSIE
systems report the error, using the UU.ERR subfunction of the .UUO directive
and perhaps print the PC value from the top of the stack. You can use an RTI
instruction to return control to the point where it left off when the exception
occurred. Note that some asynchronous exceptions also use this address.

P.BPT
The P.BPT word contains the exception address for a BPT instruction and for
T-bit exceptions. When the job issues a BPT instruction or a T-bit exception
occurs (to the kernel mode vector at 14), the monitor passes control to the runtime system for the job at the address specified by the contents of this word.
This exception pushes two words onto the user's SP stack: the contents of the PC
and PS registers. For example:
(PC) at the time of the exception
(PS) at the time of the exception
word to which SP pointed before the exception

The run-time system processes these exceptions in any fashion it sees fit at the
location specified by the contents of P.BPT. The RTI or RTT instructions can be
used to return control to the user's program at the point where it was when the
exception occurred.

P.IOT
The P.lOT word contains the exception address for an lOT instruction. Whenever
the job issues an lOT instruction (trapped to kernel mode vector at 20), the
monitor passes control on to the run-time system at the address specified by the
contents of this word.
This exception pushes two words onto the user's SP stack: the contents of the PC
and PS registers at the time of the exception. For example:
(PC) at the time of the exception
(PS) at the time of the exception
word to which SP pointed before the exception

The run-time system can process the exception in any fashion it sees fit. You
can use an RTI instruction to return control to the point where it was when the
exception occurred.

2-22

General RSTS/E Environment

P.EMT

This word contains the location to which control is transferred for nonmonitor
EMT instructions; that is, for EMT instructions whose low byte is odd within the
range 1 to 113 or any value in the range 115 to 377. If the PF.EMT hit is set. in
the P.FLAG word in the pseudovector region, control is transferred here for all
EMT instructions except those preceded by the special prefix EMT, as described
previously.
The exception pushes two words onto the user's SP stack: the contents of the PC
and PS registers at the time of the exception. For example:
SP----.

(PC) at the time of the exception
(PS) at the time of the exception
word to which SP pointed before the exception

The run-time system is responsible for processing the EMT as it sees fit. You
can use the RTI instruction to return control to the point where it was when the
exception occurred.
NOTE

All EMT instructions are reserved for use by Digital.
P.TRAP

This is the location to which control is transferred for all TRAP instructions
(operation codes 104400 through 104777, inclusive). Whenever the job executes
such an instruction (trapped to kernel mode vector 34), the monitor passes control
to the run-time system at the location specified by the contents of this word.
This exception pushes two words onto the user's SP stack: the contents of the PC
and PS registers at the time of the exception. For example:
SP----.

(PC) at the time of the exception
(PS) at the time of the exception
word to which SP pointed before the exception

The run-time system is responsible for processing the exception as it sees fit. You
can use an RTI instruction to return control to the point where it was when the
exception occurred.

2.2.2.3

Asynchronous Exception Handler Addresses
These mnemonics refer to locations within the run-time system where control is
to pass for asynchronous exceptions.
P.FPP

This location is the exception address for the hardware floating-point processor
(FPP) for the PDP-11/34A, 44, 45, 50, 53, 55, 60, 70, 73, 83, 84, 93, and 94
asynchronous unit or the KEF11-AA or FPF-11 for the PDP-11/23-PLUS and 24.
Whenever the unit takes an exception trap (to kernel mode vector at 244), the
monitor passes control to the run-time system at the location specified by the
contents of this word. The Floating-point Exception Code (FEC) and Floatingpoint Error Address (FEA) of this unit are not otherwise accessible.

General RSTS/E Environment

2-23

Therefore, the monitor pushes these two values onto the user's SP stack, in
addition to the contents of the PC and PS registers at the time of the interrupt.
For example:
SP----+

FEC
FEA
(PC) at the time of the exception
(PS) at the time of the exception
word to which SP pointed before the exception

The run-time system can process the exception as appropriate, clean the stack
(remove the FEC and 'FEA), and issue an RTI instruction to return control to the
user's program at the point where it was when the exception occurred.
P.CC

This is the location to which control passes when a CtrllC is entered at any terminal on any channel that this job accepts. The monitor stops further programmed
output for the job (CtrllO effect) and cancels any pending character output.
The user's SP stack is modified at entry. For example:
SP----+

(PC) at the time of the exception
(PS) at the time of the exception
word to which SP pointed before the exception

The run-time system can process the CtrllC as you want. All run-time systems
supplied with a RSTSIE system abort the job, unless the user job image has
indicated that it wants to handle CtrllC traps itself (see the SCCA$S and the
.SETCC directives).
P.2CC

This is the exception address taken when the user enters a second CtrllC before
the run-time system has been able to respond to the first CtrllC. (That is, the
monitor has received two CtrllCs before it has been able to pass control to the
run-time system at the location specified by the contents of P.CC in the timesharing environment.) As with one CtrllC, when the P.2CC point is entered,
further programmed output is canceled (CtrllO effect), and any pending character
output is canceled. Two words are pushed onto the user's SP stack. For example:
(PC) at the time of the exception
(PS) at the time of the exception
word to which SP pointed before the exception

The run-time system can process the condition as you want (BASIC-PLUS exits
immediately, returning control to the P.NEW entry point in the default keyboard
monitor). An RTI instruction would return control to the point where the program
left off, but this annoys the user who entered the two CtrllCs expecting to get out.
P.BAD -

Asynchronous Exceptions

The monitor passes control to the location specified by P.BAD whenever any of
the following asynchronous errors occur:
•

The user's SP stack overflows.

•

A fatal disk error occurs when the job is swapped. The original contents of
the user job image are lost.

•

A memory parity fault occurs in the user job image. The original contents of
the user job image are lost.

2-24 General RSTS/E Environment

•

A fatal disk error occurs when a run-time system or resident library is loaded.
Control passes to P.BAD in the default keyboard monitor when the load error
occurs for a run-time system.

None of these errors are recoverable. An error is returned in the first byte of the
FIRQB to indicate which error occurred, KEY is refreshed, and the contents of the
general registers (RO through R5) are random. SP is reset to the value USRSP.
In general, most run-time systems provided with RSTSIE systems report the error, using the UU.ERR subfunction of the .UUO directive, and also the ??Program
lost-sorry message (UU.ERR call with FUCORE value). Then, the run-time
systems exit to the job keyboard monitor, using .RTS. The ??Program lost-sorry
message prints to warn you that the program is no longer in memory and you
user logical values may have been lost.
The error codes that RSTSIE returns in the first byte of the FIRQB are:
RSTAK
RSWAP
RPRTY
NRRTS

The user's SP stack overflowed
Fatal disk error on swap
Memory parity fault
Fatal disk error on run-time system or resident library load

Control is also transferred to P.BAD for some synchronous exceptions.
2.2.2.4

Entry Points

These mnemonics refer to locations within the run-time system where control is
to pass at certain transition points for the job.
P.NEW

The monitor passes control to this entry point under the assumption that new
user or next request processing is to be done. Compare this to the P.RUN entry
point, where a specific program is to be run under this run-time system. P.NEW
is commonly used as the entry point to switch back to a job's keyboard monitor.
For example, the .EXIT directive passes control to this entry point in the system
default keyboard monitor. You can use the .RTS directive to pass control to
P.NEW in a job's keyboard monitor or a specifically named run-time system. Note
that a job can establish its own job keyboard monitor, which is different from the
default keyboard monitor (see the section on .RTS in Chapter 3).
By examining KEY and the XRB, the run-time system can determine how and
by whom it was entered at P.NEW, if this is significant. (Run-time systems that
do not have keyboard monitors would probably want to exit (using .EXIT) to the
default keyboard monitor at P.NEW.)
The three conditions under which control passes to the P.NEW entry are:
•

Brand new job on the system-In this case, JFNOPR (bit 12 in KEY) is set
(the job is not yet logged in), and the words at location XRB+2 and XRB+4 are
zero (the monitor requested the entry, not a run-time system). This indicates
that the monitor has passed control to this location, having received input
over channel zero in a logged-out state (occurs only for the default keyboard
monitor).
The run-time system should run some predetermined program to read CREAD
directive) the input line that the monitor has buffered. For example, DCL
executes SY:[1,2]LOGIN.* (the LOGIN utility) in this case.

General RSTS/E Environment

2-25

•

Switch to this run-time system when job logged out-In this case, JFNOPR
(bit 12 in KEY) is set, and the name of the calling run-time system is given
as two RAD50 words in locations XRB+2 and XRB+4. The calling run-time
system is the run-time system under whose control the directive was issued
that caused the switch.
For this case, the run-time system should issue a logged-out prompt message.
For example, the BASIC-PLUS run-time system prints "Bye" and returns
control to the monitor. (Normally, control does not pass to the run-time
system in this case. If LOGIN does not recognize the line that it read (as in
previous case), it kills itself, destroying the job and returning control to the
monitor.)

•

Switch to this run-time system when job logged in-In this case, JFNOPR (bit
12 in KEY) will be clear. The name of the calling run-time system is given as
two words of RAD50 in locations XRB+2 and XRB+4 or is zero if this job was
just created by UU.JOB (see Chapter 3).
For this situation, the run-time system should issue its logged-in prompt and
attempt to read the next command from the terminal open on channel zero.
BASIC-PLUS prints "Ready", DCL prints "$", RSX prints ">", and RT-ll
prints ".". Then, all wait for further input.

Keyboard monitors should read channel zero (the job's terminal) using the keyboard monitor wait feature of .READ. The monitor will kill jobs that execute this
read in a logged-out state; otherwise, it is an infinite-wait read.
The monitor usually does some housekeeping for the job at the time the P.NEW
entry point is entered. Specifically, the word at location FIRQB+FQJOB is always
set to two times the job number assigned by the monitor when the job was
created, and KEY is refreshed with current information about the job. Thirdparty privilege checking is turned off if it was on (see UU.3PP). Furthermore, SP
is reset to 400 (see USRSP description), all the general registers (RO through R5)
contain zero, and all I/O channels are closed.
On exit from privileged programs, some additional clean-up is done:
•

Temporary privileges are dropped

•

User memory is cleared (upwards from location 1000)

•

User job image size is reset to the value in P.MSIZ
NOTE

This housekeeping is not done if a specific request is made to pass control to a run-time system without changing the job-context information
(see the .RTS directive).

2-26

General RSTS/E Environment

The following infonnation exists in the XRB at the time the P.NEW entry point is
entered:
XRB on P.NEW Entry
Octal MneOffset monic

Octal
Offset
1 for switch without housekeeping; else 0

XRLEN

XRBC

name of the calling run-time system
(2 words in RAD50 format)

XRLOC

-1 if calling RTS = new RTS; else 0

XRCI

XRBLK

XRTIME

XRMOD

13
15

whatever values were here
when the switch was made

This word contains a value of one, if control was transferred by an .RTS directive using the switch without changing the job-context option (see Chapter 3).

XRB+2

The two words beginning here contain the name of the calling run-time
system, in RAD50 format. If control was transferred here directly by the
monitor, these two words contain zero.
This word contains minus one if the calling run-time system is the same
as the one that now has control. This word is zero otherwise; that is, if the
calling run-time system is not the same as the called run-time system.

XRB+I0

The contents of the next three words will be the same as they were when
the switch occurred. That is, data can be passed from run-time system to
run-time system here. If control has been transferred to P.NEW directly by
the monitor, these three words are zero.

P.RUN

The monitor passes control to the P.RUN entry point when an executable program
is to be run for a job under control of this run-time system. This can occur as the
result of either a .RUN or a .CHAIN directive (in which a job has directly asked
for a file to be run) or a .CCL directive (in which a job has asked the monitor
to check a string to see if it is a valid CCL command, and if so, execute the
appropriate file).
The monitor opens the file to be run (a disk file) on channel 15. However, the file
has not been read; it is up to the run-time system to load and execute the file.
The run-time system should also reset all 110 channels except 15, in case they are
open.
The monitor perfonns the same housekeeping operations as with P.NEW (reset
the stack, and so on). In addition, if the program to be run is a privileged
program, and the caller does not have all of the program's privileges, the monitor
sets the JFSYS bit in KEY, saves the current privileges, and adds the program's
privileges to the current privileges.

General RSTS/E Environment

2-27

The monitor passes data to the run-time system in the XRB, FIRQB, and KEY
areas of the user job image (low segment).
XRB on P.RUN Entry
Octal
Offset
flag bits describing entry conditions

Octal
Offset

Mnemonic

XRLEN

XRBC

name of run-time system which issued
the call to this one

XRLOC

random value

XRCI

XRBLK

XRTIME

XRMOD

same value as when the caller
issued the .RUN or .CCL

This word contains flag bits that describe the entry conditions. (The
STATUS variable in BASIC-PLUS returns these values.)

Bit

Meaning

0-7

If the value of these bits is zero, then no special size for this

program run is called for. If the value is greater than zero, it
indicates the size, in K words, that the program should be run
at. If the value is less than zero, the absolute value indicates
an increment, in K words, to the size that the program would
normally run at.
8-12

Reserved for future use.

When set, indicates that the caller issued a directive with a
ISIZE switch; that is, the file is to be run at a specific size. The
size is given in bits 0-7. It is up to the run-time system to set
the size as indicated (see the .CORE directive).

When set, indicates the caller issued a .CCL directive with a
!DETACH switch, with the intent that this run-time system
executes the file in detached mode. It is up to the run-time
system to take action on this flag. You can detach a job by
using the UU.DET subfunction of the .UUO directive; see
Chapter 3.

When set, indicates the entry was made as the result of a .CCL
directive. When clear, indicates the entry was made as the
result of a .RUN or a .CHAIN directive.

XRB+2

These two words contain the name of the run-time system under which
the .RUN, .CHAIN, or .CCL directive to this run-time system was issued,
in RAD50 format.

XRB+6

The contents of this word are random.

XRB+I0

The three words beginning here contain the same information that they
held when the job issued the .RUN, .CHAIN, or .CCL directive.

2-28 General RSTS/E Environment

FIROB on P.RUN Entry
Mnemonic

Octal
Offset

3
5
7
11

Octal
Offset
////1//1///1//1/1/11/

1/1//1/1/1

job number * 2

Mnemonic

FOJOB

/1//1///1//1///////1/

FOPPN

FONAM1

project number

programmer number

file name in RAD50 format
(2 words)

file type in RAD50 format (1 word)

FOEXT

file size in 512-byte blocks

FOSIZ

default buffer size for disk

FOBUFL

////1//////1///////1/

device description

FOFLAG

FOPFLG

FOP ROT 27

protection code

cluster size

device name (2 ASCII characters)

FODEV

flag byte

FODEVN

device unit number

file identification index

FOCLUS

entry parameter

FONENT

FIRQB+FQJOB

The job number (assigned by the monitor when this job was
created) times two.

FIRQB+FQPPN

The project-programmer number for the file that is to be run.

FIRQB+FQNAMI

The name of the file that is to be run, as two words in RAD50
format.

FIRQB+FQEXT

The type of the file that is to be run, as one word in RAD50
format.

FIRQB+FQSIZ

The file size, in 512-byte blocks.

FIRQB+FQBUFL

The recommended size, in bytes, for the buffer size in a .READ
directive for this file.

FIRQB+FQFLAG

Flag bits defining the device. They are set to indicate that this is
a disk file. (See the FQFLAG description in the open function of
the CALFIP directive.)

FIRQB+FQPFLG

The file cluster size, modulo 256. (That is, a file cluster size of
256 is indicated by a zero byte here.) This byte is the same as
the FQCLUS value supplied in the open functions of the CALFIP
directive, except that it is returned in a byte instead of a word.

FIRQB+FQPROT

The protection code of the file.

FIRQB+FQDEV

The device name of the disk device, as two ASCII characters.

FIRQB+FQDEVN

The unit number of the disk device.

General RSTS/E Environment

2-29

FIRQB+FQDEVN+1

The low-order two bits of this byte are set to indicate whether or
not the device is part of the public structure:
Bit 0
=0 The device is in the public structure.
Bit 1

FIRQB+FQCLUS

2-30

General RSTS/E Environment

The device is a private disk.

A specific device was not specified in the open
function.

A specific device was specified in the open function.

The file identification index of this file. This word is significant
in that you can use it in place of the file name in subsequent
opens of the file on disk. You can open the file with the OPNFQ
subfunction of CALFIP, using:
•
•
•
•

FIRQB+FQNENT

An explicit PPN in FIRQB+FQPPN
A zero word in FIRQB+FQNAM1
An explicit device name in FQDEV and FQDEVN
The file identification index in FIRQB+FQNAM1+2

Parameter word from the caller. The .RUN or .CHAIN directive,
which causes entry at P.RUN in a run-time system, allows the
caller to specify a parameter word to be passed to the run-time
system. Bit 15 of this word mayor may not be the same as
the caller passed, however. If the .RUN or .CHAIN directive
was issued from a privileged program with temporary privileges
enabled, bit 15 is passed by the caller. Otherwise, bit 15 is cleared.
For .CCL entries, bit 15 is- set by the monitor. If the CCL definition for the CCL being executed has the /PRIVILEGED qualifier
included in it, the bit 15 is set; otherwise, it is cleared.

Part II
Monitor Directives

Chapter 3

General Monitor Directives
This chapter describes the general directives to the RSTSIE monitor. These
directives are available to the MACRO programmer under both the RSX and
RT-U run-time systems. They are Emulator Trap (EMT) instructions that are
processed directly by the monitor. A run-time system does not examine or process
these general directives.

3.1

Summary of General Monitor Directives
Table 3-1 summarizes the general monitor directives. Detailed descriptions are
given in the sections that follow this introductory material. The descriptions are
arranged alphabetically by mnemonic name.
Some directives, which cause a change in run-time system or change in job size,
should not be executed by a program (user job image) running under the RT-ll
run-time system, or unpredictable results may occur. These directives are marked
with a dagger (t) or double dagger (:j:) in Table 3-1. (Note, however, that these
are not restrictions for assembling using MACRO-the assembler for the RT-ll
run-time system. If you are coding a run-time system, you use these directives
and assemble under either MACRO or MAC.)
Table 3-1:

Summary of General Monitor Calls

Name

EMT
Code
(Octal)

CALFIP

Call the File Processor portion of the RSTSIE monitor. Includes
"housekeeping" functions for file/device I/O such as OPEN,
CLOSE.

.READ

Read from a previously opened file or device .

.WRITE

Write to a previously opened file or device .

.COREt

Change memory size allocated for user job image .

. SLEEP

Sleep job for n seconds .

.PEEK

Peek at the monitor's memory.

. SPEC

Special function .

Enter tape mode.

.'!TAPE

Description

tThese directives should not be used by a program running under control of the RT-ll run-time
system.
.

(continued on next page)

General Monitor Directives

3-1

Table 3-1 (Cont.):

Name
.TTECH
.TTNCH
.TTDDT
.TTRST
.TIME
.POSTN
.DATE
.SET
.STAT

EMT
Code
(Octal)

20
22
24
26
30
32
34
36
40

.UUO

42
44
46
50
52
54
56
60
62
64
66

.CHAINt
.PLAS

70
72

.ULOG

76
102
104
106
112
114

.RUNt
.NAME
.EXITt
.RTSt
.ERLOG
.LOGS
.CLEAR
.MESAG
.CCLt
.FSSt

.READA
.WRITA
.ASTX
.CMDLN
.AST

Summary of General Monitor Calls

Description
Enable echo on a channel.
Disable echo on a channel.
Enter ODT submode on a channel.
Cancel Ctr1JO effect.
Get timing information.
Get device's horizontal position.
Get current date.
Set keyword bits.
Get statistics for job.
Run new program (user job image).
Install a new program name.
Exit to default keyboard monitor.
Switch to new run-time system .
Log an error from run-time system.
Check for logical devices.
Clear keyword bits.
Message send/receive.
Check string to see if Concise Command Language (CCL).
Scan a string for valid RSTSIE file specifications .
Execute monitor FIP call (access to BASIC-PLUS SYS calls to
FIP).
Execute user job image under same run-time system.
Access a shared library.
Assign/reassign/deassign device or user logical.
Asynchronous read.
Asynchronous write.
AST exit.
Read/write command line buffer.
AST enable/disable.

tThese directives should not be used by a program running under control of the RT-ll run-time
system.
*This directive should not be used by a program running under control of either the RT-ll run-time
system or the RSX emulator.

3.1.1

Prefix File COMMON.MAC
The monitor directives that this chapter describes require that you pass parameters to the monitor in the FIRQB and XRB; values are also returned to your
program in these areas. The file COMMON.MAC, provided with all RSTSIE kits,
relates mnemonics to often-used addresses, offset values, and function codes,
eliminating the need for octal coding and addressing. These mnemonics are
used in the directive descriptions that follow; Digital recommends their use for
readable, maintainable code.

3-2

General Monitor Directives

3.1.1.1

How to Assemble with COMMON.MAC

COMMON.MAC is a prefix file; it is assembled with your other MACRO
source files Wlder either the RSX or RT-ll run-time systems. For example,
Wlder the RT-ll rWl-time system, the following sequence would assemble the
files COMMON.MAC, SRC1.MAC, and SRC2.MAC into the object module file
OBJ.OBJ with an assembly listing file OBJ.LST:
RUN $MACRO
*OBJ,OBJ=COMMON,SRC1,SRC2

Similarly, Wlder the RSX rWl-time system, this sequence would assemble the
files COMMON.MAC, SRC1.MAC, and SRC2.MAC into the object module file
OBJ.OBJ with an assembly listing file OBJ.LST:
RUN $MAC
MAC>OBJ,OBJ=COMMON,SRC1,SRC2

You can also use the .INCLUDE assembly directive to include COMMON.MAC.
Use the following line as the first line of the source file:
.INCLUDE /COMMON/

3.1.1.2

Macros Provided in COMMON. MAC

In addition to providing mnemonics, the COMMON.MAC file contains macros
that can be used in programs assembled Wlder either the RSX or RT-ll rWl-time
systems, as long as COMMON.MAC is assembled with the source, as described
previously. These macros are:

TITLE nam.e,desc,nn,date,editors
The TITLE macro sets a title (.TITLE) from the name and description (desc)
parameters and builds an identification (.IDENT) from the specified nwnber
nn. The IDENT has the form xx.xnn, where xx.x is the current RSTSIE version number (09.0 for V9.0), and nn is the edit level you specify. Descriptive
information is placed in the table of contents as follows:
EDIT:
nn

DATE:
date

BY:
editors

ORG section[,offset]
ORG defines the origin address of a program section. The first occurrence of
an ORG with a given section name causes all instructions requiring memory
space following the ORG to be assigned consecutive relocatable addresses
starting with zero or, if an offset is given, with the octal address given. Later
occurrences of an ORG with the same section name causes resumption of
addressing wherever it left off before, because of an intervening ORG.
The ORG macro also defines a symbol with the same name as the section at
the first relative location within the section. Every invocation of ORG also
defines (or redefines) the section to be returned to by the macro UNORG.

DEFORG section
The DEFORG macro is the same as the ORG macro except that the symbol at
relative 0 (the section name) is declared as a global symbol. By convention,
the module that defines the section (rather than just uses it) issues the
DEFORG macro.

General Monitor Directives

3-3

TMPORG section[,offset]
TMPORG is the same as ORG except that it does not define (or redefine) the
section to be reentered by the UNORG macro. In this way, the module can
temporarily enter a new section and then return to the main section using
UNORG without having to know the main section name.
UNORG
The UNORG macro will reenter the section most recently declared in an ORG
or DEFORG macro.
INCLUDE name1[,name2, ... ]
The INCLUDE macro indicates that the module issuing the INCLUDE
requires the named modules (namel, ... ). The name(s) should be declared
with DEFORG(s) in the required modules.
INCLUDE declares the listed section names as global symbols and issues
the macro directive .SBTTL with the heading "INCLUDE FROM LIBRARY
'name'" to be inserted in the assembly listing table of contents. INCLUDE
documents the named sections as required by this section .
.DSECT [start] [,erel]
The .DSECT macro starts a dummy program section (with the MACRO
directive .ASECT) at relocatable address 0 or at the address given by the
optional argument start. If the cross-reference (cref) parameter is given
(nonblank), the program section is included in the cross-reference listing, if
you request one for the assembly.
The .DSECT macro is used in the file COMMON. MAC to define the system
parameters and offsets.
For example, coding of this form is used in COMMON.MAC to assign the
proper values to the mnemonics in the pseudo-vector region:
.DSECT
P.SIZE:
P.2CC:
P.CC:

177776,NOCREF
.BLKW
-1
.BLKW
-1
.BLKW
-1
.BLKW
-1

NOTE

A .DSECT is used at the end of the file COMMON.MAC. This
means that you must explicitly start your MACRO program with
an ORG macro or .PSECT directive to begin your program at
relocatable address O. Otherwise, your code win be regarded as a
continuation of the .DSECT, and the program will not assemble
properly.

3-4

General Monitor Directives

.BSECT [HIGH] [,crefj
The .BSECT macro is like the .DSECT macro except that the default starting
address is 1 instead of O. If the argument HIGH is used, the starting address
is 400 (octal). This starting address lets you use .BSECT to generate bit
values. The .BSECT macro is used in COMMON.MAC to define mnemonics
for bit locations. For example, the following coding assigns the mnemonics to
the bit locations in the keyword (KEY; see Chapter 2). Note that the period (.)
after .BLIrn is required .
. BSECT
JFSPR1:
JFPP:

HIGH,NOCREF
.BLKB
.BLKB

.EQUATE symbol,value
.EQUATE defines the given symbol to have the supplied value (which may be
an expression) by using the equivalent of:
.DSECT
. symbol:
UNORG

value

.BLKWO [quantity][,value]
The .BLKWO macro is similar to the MACRO directive .BLKw, which reserves
a specified number of words of storage space. The quantity can be any
expression, the default is one. While .BLKW just reserves space, .BLKWO fills
the space with the value you specify; the default is zero .
.BLKBO [quantity][,value]
The .BLKBO macro is similar to the MACRO directive .BLKB, which reserves
a specified number of bytes of storage space. The quantity can be any expression, the default is one ..BLKBO fills the space with the value you specify; the
default is zero.
GLOBAL <namel[,name2, ...]>
GLOBAL declares the name symbols as external global symbols.
RETURN [register]
The RETURN macro generates an RTS PC by default but can generate any
other RTS instruction if you specify an explicit register.

JMPXlabel
JMPX is just like the JMP instruction but will also declare the label to be an
external global (that is, jump external).

CALL subroutine[,register[,argument list]]
You can use CALL instead of JSR PC to call subroutines. If an explicit
register is specified, then the call is JSR using that register. If an argument
list is specified, it generates a list of .WORD arguments in line with the
subroutine call.

General Monitor Directives 3-5

CALLR subroutine
CALLR is equivalent to a CALL to a subroutine immediately followed by a
RETURN. CALLR generates a JMP instruction.

CALLX subroutine
CALLX is just like CALL, but it also declares the subroutine name as an
external global symbol.

CALLRX subroutine
CALLRX is just like CALLR except that the subroutine name is declared as
an external global symbol.

3.1.2

Error Mnemonics: Symbol Table File ERR.STB
When the monitor processes the directives that this chapter describes, any errors
that it detects are passed back to the job in the first byte of the FIRQB as a
binary value. The ERR.STB file, provided with all RSTSIE kits, relates mnemonic
values to these binary codes, so you do not have to analyze and process errors
in octal. The descriptions in this chapter all refer to the mnemonics provided by
ERR.STB. See Appendix A for a list of all possible errors.
The symbols are automatically resolved at link time if you include ERR.STB with
the files you link with either TKB (the Task Builder for the RSX run-time system)
or LINK (the linker for the RT-ll run-time system). For example, under the RSX
run-time system, the following code links ERR.STB and MAIN.OBJ to produce
the executable file IMG1.TSK, a memory allocation file MP1.MAP, and a symbol
definition file SF1.STB:
RUN $TKB
TKB>IMG1,MP1,SF1=ERR.STB,MAIN

Similarly, under the RT-ll run-time system, the following sequence links
ERR.STB and MAIN.OBJ to produce the executable file IMG1.SAV, a memory
allocation file MP1.MAP, and a symbol definition file SF1.STB:
RUN $LINK
*IMG1,MP1,SF1=ERR.STB,MAIN

3.1.3

Programming Hints
Preset the FIRQB and XRB to Zero

The monitor directives in this chapter pass information to the monitor in the
FIRQB and XRB areas of the low 512. bytes of memory. It is usually a good
idea to clear the entire FIRQB and XRB before issuing a call, to ensure that no
extraneous information (for example, from data returned on a previous call) has
been left in the areas that could affect how the call executes.
In some cases, however, you may want to leave the FIRQB and XRB alone. The
.FSS call, for example, scans a string and, if it is a valid file specification, returns
to the FIRQB the information needed to open the file with the CALFIP call. You
do not want to clear the FIRQB before opening the file with CALFIP.
NOTE
To ensure compatibility with future releases of RSTSIE, you should

always set to zero any fields in the FIRQB and XRB diagrams that are
shaded or are documented as reserved or not used.
3-6

General Monitor Directives

The following example contains three routines that clear the FIRQB and XRB.
CLRFQX clears both the FIRQB and XRB.
CLRFQB clears the FIRQB.
CLRXRB clears the XRB.
The values FQBSIZ and XRBSIZ used in these routines are defined in
COMMON.MAC .
. ENABL

LSB

CLRFQX: :

PUSH
MOV
MOV
BR

<RO,R1>
:fI:FIRQB,RO
:fI:«FQBSIZ+XRBSIZ>/2>,R1
10$

;Save RO,R1
;Point to FIRQB.
;Compute how many words
;to clear.

CLRFQB: :

PUSH
MOV
MOV
BR

<RO,R1>
:fI:FIRQB,RO
:fI:<FQBSIZ/2>,R1
10$

;Save RO,R1
;Point to FIRQB.
;Compute how many words
;to clear.

CLRXRB: :

PUSH
MOV
MOV

<RO,R1>
:fI:XRB,RO
:fI:<XRBSIZ/2>,R1

;Save RO,R1
;Point to XRB
;Compute how many words
;to clear.

10$:

CLR
SOB
POP
RETURN

(RO)+
R1,10$
<R1,RO>

;Zero it out
; , til all done
;Restore RO,R1.

. DSABL

LSB

...

Data Returned to FIRQB and XRB

If a call completes without error, the monitor sets byte 0 of the FIRQB to zero. If
an error occurs on a call, the monitor sets byte 0 of the FIRQB to an error code.
Likewise, the monitor always sets the byte at FIRQB+2 to the current job number
times two when a call completes.
In some circumstances, it may be useful to know what happens to the passeddata when a call completes. For instance, is the file name still there? Bytes not
specified as containing returned-data are undefined. Do not rely on these values
when coding your programs because Digital reserves the right to change the
values returned in these bytes at any time. In addition, if an error occurs, the
data returned mayor may not have replaced the data passed. It depends on how
far processing for the call got before the error occurred.
Channel Numbers for 1/0

Directives that handle 1/0 use a channel number to refer to a device. In device
or file opens, a channel number is related to a specific device defined in the call.
Directives that transfer data CREAD, .WRITE, .READA, .WRITA) can then refer
to a channel number rather than define a device or file.
Valid channel numbers range from 0 through 17. Channel 0 is the job's terminal;
for example, a .WRITE to channel 0 writes to the terminal which is running the
job. Channel 0 is always open. Similarly, the monitor opens a file to be run on
channel 17 when control transfers to the P.RVN entry point in a run-time system.
Thus, user jobs may define and use channels 1 to 16.

General Monitor Directives 3-7

Directives That Do 1/0

The CALFIP subfunctions OPNFQ, CREFQ, CRBFQ, and CRTFQ open a file or
device and relate the specified channel number to that file or device:
•

OPNFQ opens a file or device for input

•

CREFQ creates a file, that is, opens a file or device for output

•

CRBFQ creates a binary (executable) output file on disk

•

CRTFQ creates a temporary file on disk

The directives .READ and .WRITE transfer data between memory and a device or
file specified by channel number.
The CLSFQ (close) and RSTFQ (reset) subfunctions of CALFIP close a device or
file and free the associated channel number so it can be used with another device
or file.
Directives That Support 1/0

The file string scan (.FSS) directive is useful for programs that process files
specified by a terminal user. The .FSS directive examines a string of characters
and, if it is a valid RSTSIE file specification, converts it to the FIRQB format
used to open a file. Thus, your program can accept a typed string from the job's
terminal and use .FSS to convert the string to the FIRQB format to do 110 on the
file.
You can use the LOKFQ subfunction of CALFIP to search for disk files that meet
wildcard file specifications. For example, you could search an account on disk for
all files with names beginning with the characters DD.

3.2 Trap Handling with Supervisor Mode
Although asynchronous 1/0 calls (.READA and .WRITA) are illegal for a task
using supervisor mode, other traps may require handling by a task using
supervisor mode. The legal asynchronous system traps for supervisor-mode tasks
are:
•

FPP exception

•

CtrllC interception

•

all forms of Synchronous Service Traps (SSTs)

The trap service routines for these may be located in either user or supervisor
mode. If the service routines reside in supervisor mode, they must adhere to
additional requirements that their user mode counterparts do not need:
•

The service routine must exit via either the SSTX.$ or ASTX.$ calls. In
user mode only, service routines can clean the PC & PSW off the stack and
continue without returning, but if supervisor mode in use, tasks must use an
exit call. Note that the hardware prohibits an RTI instruction from returning
a task to supervisor mode from a service routine in user mode.

•

Routines located in supervisor space must obey all the rules of supervisor
library routines such as not calling user mode routines and having no data
within the code.

3-8 Trap Ham.. llng with Supervisor Mode

The task tells RSTSIE the space of the service routine when the respective service
vectors are set up. The following calls set up the trap service vectors for the task:
•

FPPA$---floating point exception

•

SCCA$---CtrllC interception

•

SVTK$---SST trap vector table

•

SVDB$---SST debugging trap vector table

In the FPPA$ and SCCA$ calls, the task issues a single address vector. If bit

o of the vector is zero, the service routine is in user space. If bit 0 is 1 (an odd
address vector), the routine is in supervisor space.
In the SVTK$ and SVDB$ calls, the task issues a list of vectors associated with
the different events (BPT etc.). Bit 0 in each of the individual service routine
vector addresses gives the mode the routine is in, but in a different way from
FPPA$ and SCCA$. If the vector entry is even, the SST routine executes in the
same mode (either user or supervisor) that the processor was in when the SVTK$
or SVDB$ call was issued. If the vector entry is odd, the SST routine executes in
the other mode.
For example, if the processor is in supervisor mode when an SVTK$ is issued
and the vector is odd (bit 0 set), the SST routine executes in the user mode. This
method is the same as RSX-llM-PLUS. It lets the individual SSTs be different
modes at the same time (BPT in user and address trap in supervisor). Bit 0,
which is the flag(s), is a member of the vector list, not the address pointer to the
vector list.

Trap Handling with Supervisor Mode 3-9

3.3 .AST-Enable/Disable AST Delivery
Form

.AST
Function

The .AST directive has two functions: disable AST delivery and enable AST
delivery. The .AST disable function stalls all AST deliveries from the monitor
until the user explicitly enables them with the AST enable directive.
Privileges Required

None
Data Passed

The only data passed for this directive is in byte 0 of the XRB. If zero, enable
AST deliveries. If minus one, disable AST deliveries.
Data Returned

Except for a possible error code in byte 0 of the FIRQB, this directive does not
return any meaningful data.
Errors
BADFUO

3-10

.AST

Illegal function code.

3.4 .ASTX-Exit from AST Routine
Form

.ASTX
Function

The .ASTX directive is similar to a RETURN in a normal subroutine. It instructs
the monitor that the asynchronous routine has completed and that control should
return to the job at the point it was interrupted. All AST routines must finish
with a .ASTX directive.
When an AST routine issues the .ASTX directive, the PSW previously stored on
the user's stack is validated. The PSW is forced into the standard mode (previous
user/current user mode, register set 1, and priority 0). The PC and PSW are then
used to return control to the program at the point where it was interrupted.
The XRB and bytes 0, 6, and 7 of the FIRQB are restored. If the user has altered
the PC, PSW, or destroyed the stack contents, no specific error is returned.
Instead, bad PC and/or stack causes fatal errors which are handled in the usual
way (entry to P.BAD in the RTS).
The AST routine must make sure all general registers (RO to R5) and the stack
pointer have the same contents as on entry to the AST routine. In addition,
if any part of the FIRQB other than bytes 0, 6, and 7 has been used, the AST
routine must restore the contents of the FIRQB to what it had on entry. Failure
to observe these rules may produce unexpected results.

.ASTX

3-11

3.5 CALFIP - Call the File Processor
Form

CALFIP
Function

The CALFIP directive to the RSTSIE monitor handles housekeeping necessary for
input/output on RSTSIE. For example, CALFIP lets you open a channel for file or
device 1/0.
You select the particular function by setting a function field in the FIRQB (at
offset FQFUN). Other parameters are also passed to the monitor in the FIRQB,
depending on the function requested.
Table 3-2 lists the CALFIP subfunctions by function code. The sections following
Table 3-2 describe the subfunctions in alphabetical order. .

3-12 CALFIP

Table 3-2:

Summary of CALFIP Subfunctlons

FQFUN
Value
(Octal)

Mnemonic

Action Performed (BASIC.PLUS Equivalent)

CLSFQ

Close an open channel (CLOSE)

OPNFQ

Open a channel (OPEN FOR INPUT)

CREFQ

Create/extend a file (file-structured OPEN FOR OUTPUT)

DLNFQ

Delete a file by name (KILL)

RENFQ

Rename a file (NAME ...AS)

DIRFQ

Get directory information

UUOFQ

Process UUO

ERRFQ

Get error message text

RSTFQ

Reset (close) a channel or all channels (except channel 0)

LOKFQ

Look up a file

ASSFQ

Allocate a device

DEAFQ

Deallocate a device

DALFQ

Deallocate all devices

CRTFQ

Create/extend a temporary file on disk

CRBFQ

Create/extend a compiled image file on disk (file-structured
OPEN FOR OUTPUT, protection code bit 6 always set)

3.5.1

ASSFQ (Allocate a Device)
Form
MOVB #ASSFQ,FIRQB+FQFUN

(Set up FIRQB to define device)

CALFIP

Function

The ASSFQ subfunction reserves a physical device for a job or transfers assignment of a currently owned device to another job. For host-initiated LAT ports,
this directive initiates a connection to the server currently assigned to the port.
Privileges Required

DEVICE to allocate a device for the current job if the requested device is restricted. HWCTL to seize a device or reallocate a device to a job in another
account.
Data Passed
FIROB
Mnemonic

Octal MneOffset monic

Octal
Offset

FOFUN 3

/////////////////////

ASSFO (= 24)

//////////

/////////////////////

//////////

l=o,assign;<>o,jOb no.

FONAM1

/////////////////////

DOS or ANS (1 word RAD50) or 0 (magtape)

/////////////////////

mode

/////////////////////

device name (2 ASCII characters)

FODEV

FODEVN

<>0, unit no. real

device unit number

/////////////////////

FIRQB+FQFUN

FOEXT

FOMODE

The function code ASSFQ (octal value = 24).

CALFIP-ASSFQ 3-13

FIRQB+FQNAM1

This byte is set to zero to indicate an assign; if nonzero, it is used
as the job number to which the device is to be reassigned. The
high byte of this word (FIRQB+ll) must be set to zero. If you do
not have HWCTL privilege, you can reassign a device only to a job
that is logged in to the same account as your current account.

FIRQB+FQEX.T

When the device is magnetic tape, this word can contain either
DOS or ANS in RAD50 format, to indicate DOS or ANSI label
format for the tape drive. It can also be set to zero to indicate the
system default for the drive.

FIRQB+FQMODE

This word contains the mode to use when allocating the device.
Valid modes are:
Mode
Description
100001

100002

U sed to allocate a device that is currently allocated to another user. This is a snagging
allocation, available to users with the HWCTL
privilege.
Only used when allocating a LAT port and used

to tell the LAT driver that the request to initiate
the connection should not be queued if the remote
port is not available.
100004

Only used when allocating a LAT port and used to
tell the LAT driver that the request to initiate the
connection should be queued if the remote port is
not available.

Used when you do not want a snagging allocation
and when you want the LAT driver to use the
port's default queueing setting.

FIRQB+FQDEV

Device name, as two ASCII characters.

FIRQB+FQDEVN

The device unit number is passed here in binary. A nonzero value
in FIRQB+FQDEVN+1 indicates an explicit device unit number.
A zero value in FIRQB+FQDEVN+1 indicates no unit number.

Data Returned

Byte 0 of the FIRQB contains a possible error code. FIRQB+FQFIL contains
the previous owner of the device. If the device is a keyboard, FIRQB+FQFIL+l
contains a 0 for an interactive keyboard or a 1 for a LAT port used for hostinitiated connections.
Errors

For Assign (byte at FIRQB+FQNAMl

=0):

NODEVC

The device name specified at FIRQB+FQDEV is not a valid device name.

NOTAVL

The device and unit specified exists on the system, but the attempt to
reserve it is prohibited because:
•
•
•

NOBUFS

The device is currently reserved by another job.
The device or its controller has been disabled by the system manager.
The device is a keyboard line for a pseudo keyboard only.

No buffers available to initiate the connection to the terminal server.

For Reassign (byte at FIRQB+FQNAMl =1= 0):
BDNERR

The job number specified does not exist.

INUSE

The device specified is currently open or has an open file.

3-14 CALFIP-ASSFQ

NODEVC

The device name is a logical device name for which a physical device is not
currently assigned.

NOTAVL

(See previous description for Assign.)

PRVIOL

You do not have HWCTL privilege and you tried to reallocate a device to a
job that is logged in to an account other than your current account.

Example

The following code reassigns magnetic tape unit 0 (MTO:) to job 12:
MAGT:

.ASCII
CALL
MOVB
MOVB
MOV
MOV
CLRB
MOVB
CALFIP
TSTB
BNE

/MT/
CLRFQB
#ASSFQ,FIRQB+FQFUN
#12.,FIRQB+FQNAM1
#"'RANS, FIRQB+14
MAGT,FIRQB+FQDEV
FIRQB+FQDEVN
#377,FIRQB+FQDEVN+1

;CALL ROUTINE TO CLEAR FIRQB
;SET FUNCTION CODE
;ASSIGN TO JOB 12
;ANSI-LABEL TAPE
;MAGTAPE DEVICE
;UNIT NO. 0
;UNIT NO. REAL

FIRQB
ERRTN

;ANY ERRORS?
;BRANCH TO PROCESS ERROR

See the section entitled "Programming Hints" for information on the CLRFQB
routine.

CALFIP-ASSFQ 3-15

3.5.2

CLSFQ (Close a Channel)
Form/Example
CHANO=8.
MOVB
MOVB
CALFIP

Set value for ohannel
Set funotion oode in FIRQB
Set ohannel 8 for CLOSE
Exeoute monitor direotive

iCLSFQ,FIRQB+FQFUN
iCHANO*2,FIRQB+FQFIL

Function

The CLSFQ function closes a channel. The specific action taken depends on the
device or file that was previously opened on the channel and whether it was
opened for input or output, as well as the mode with which it was opened. For
example, closing a channel on which a magnetic tape was opened for input in
file-structured mode causes the monitor to position the tape at the end-of-file
(EO F). See the RSTS / E Programming Manual for a description of the actions
taken on closing various devices/files.
Requesting CLSFQ for a channel that is not currently open returns with no action
taken and no error is indicated.
Privileges Required

None
Data Passed
FIR08
Mne- Octal
monic Offset

Octal
Offset
111111111111111111111

3-16

FOFUN 3

CLSFO (= 0)

1111111111

channel no. * 2

CALFIP-CLSFQ

Mnemonic

111111111111111111111

1111111111111111/1111

111111111111111111111

1/1/111111111111/1111

1/1111111/11111111111

111111111111111111111

1/1111111/111111/1111

1/11111111111111/1111

1/1111111111111111111

1/11111111111111/1111

1/ I I I I I I 1/ I I I I I 1/ I I I I

1/1 I I I I I 1/ I I I I I 1/ I I I I

FOFIL

FIRQB+FQFUN

The function code CLSFQ (octal value = 0).

FIRQB+FQFIL

Channel number times two; defines the channel to be closed.

Data Returned

Except for a possible error in byte 0 of the FIRQB, the CLSFQ function of
CALFIP does not return any meaningful data.
Errors

All errors with the CLSFQ function of CALFIP are device-dependent. See
Appendix A for a full list of errors.
Example

The following MACRO code closes the file or device on channel 12:
CALL
MOVB
MOVB
CALFIP
TSTB
BNE

CLRFQB
tCLSFQ,FIRQB+FQFUN
#12.*2,FIRQB+FQFIL
FIRQB
ERRTN

;CLEAR FIRQB
;SET FUNCTION CODE IN FIRQB
;SET CHANNEL 12 FOR CLOSE
;EXECUTE MONITOR DIRECTIVE
iTEST BYTE a FOR ERROR
;BRANCH TO PROCESS ERROR

See Programming Hints for information on the CLRFQB routine.

CALFIP-CLSFQ 3-17

3.5.3

CRBFQ (Create a Binary [Executable] File and Open It on a Channel)
Form
MOVB #CRBFQ,FIRQB+FQFUN

;SET FUNCTION CODE

(Set parameters in FIRQB appropriate to device)

CALFIP

Function

The CRBFQ function creates and opens a binary (executable) file. It is identical
to the CREFQ function, except that the protection code is automatically set to
indicate an executable file, and the file must be opened on a disk device.
Privileges Required

TUNE to set caching mode. SYSIO to set the privileged-program bit (bit 7 in
FQPROT). A matching PPN, GWRITE, or WWRITE, and/or SYSIO to create or
rename a file. You also need write access (by protection code, GWRITE, WWRITE,
and/or SYSIO) to supersede an existing file.
Data Passed
FIRQB
Mnemonic

Octal
Offset

Octal
Offset
111111111111111111111

Mnemonic

CRBFQ (= 34)

1111111111

FQSIZM 5

(must = 0)

channel no. * 2

FQFIL

project number

programmer number

FQPPN
FQNAM1

FQFUN

file name in RAD50 format

(2 words)

file type in RAD50 format (1 word)

FQEXT

(file size in 512-byte blocks)

FQSIZ

111111111111111111111

mode

111111111111111111111

FQPROT 27
31
33
35
37

3-18 CALFIP-CRBFQ

file protection

<>0. prot.code.real

device name (2 ASCII characters)
<>0, unit no. real

device unit number
file clustersize

device cluster number for first block

FQMODE

FQPFLG

FQDEV

FQDEVN

FQCLUS

FQNENT

FIRQB+FQFUN

The function code CRBFQ (octal value =34).

FIRQB+FQFIL

Channel number times two; defines the channel upon which the
file is to be opened.

FIRQB+FQSIZM

On other types of create opens, this byte contains the most significant bits (MSB) of the file size. Executable (binary) files cannot be
greater than 65,535 blocks so this byte must always be passed as
zero.

FIRQB+FQPPN

The PPN with which the file is to be created. The project number
is in the high byte (FQPPN+l) and the programmer number in
the low byte (FQPPN). A value of zero in both bytes defaults to
the PPN under which the calling program is running.

FIRQB+FQNAMI

The file name created, as two words of RAD50 data.

FIRQB+FQEXT

The file type, as one word of RAD50 data.

FIRQB+FQSIZ

The desired file size, in 512-byte blocks. The file is preextended to
the specified size; that is, the space for the file is allocated when
the file is opened, rather than as it is written.

FIRQB+FQMODE

The mode with which the file is to be opened; values and actions
taken are as described for the MODE modifier in file-structured
OPEN FOR OUTPUT statements for disk, as the RSTS / E
Programming Manual describes. If a mode value is used, bit
15 of this word must be set to l.

FIRQB+FQPROT

File protection code; values for this field define read/write and
execute access to the created file (see the RSTS / E System User's
Guide). If you want a default protection code, then set a full
word of zeros at FIRQB+FQPFLG. In this case, either the system
default for protection code will be used, or, if the CRBFQ will be
deleting a previously existing file with the same file name, type,
PPN, and device, the file protection code of the previously existing
file will be used.
To assign a specific file protection code, a nonzero value is passed
in byte FIRQB+FQPFLG (by convention, 255) and the specific file
protection code in byte FIRQB+FQPROT. Bit 6 is automatically
set, indicating that the file is executable. The RSTS / E System
User's Guide describes the protection codes for executable files.

FIRQB+FQDEV

The device name is passed here as two ASCII characters; it must
be a disk device. If this word is zero, the public disk structure is
assumed.

FIRQB+FQDEVN

The device unit number is passed here in binary. A nonzero value
in FQDEVN+l indicates an explicit device unit number. A zero
value in FQDEVN+l indicates no unit number.

FIRQB+FQCLUS

This parameter has the same function as the CLUSTERSIZE
option in BASIC-PLUS. The BASIC-PLUS Language Manual
describes the CLUSTERSIZE option for disks.

CALFIP-CRBFQ 3-19

Device cluster number for placement of block 1 of the file. When
you are creating a new file, you can place block 1 of the file on
a particular block by specifying the disk device cluster number
in this word. If this word is zero, no placement is done. If it
is nonzero, the monitor will try to place the file at the specified
device cluster or as near after it as possible.
If the first block of the file can be placed at or after the specified
device cluster number, the monitor sets a bit in the file's entry in
the User File Directory (UFD). If the first block of the file cannot
be placed at or after the specified device cluster number, the file
is placed at the lowest free block on the disk, the bit in the file's
entry in the UFD is not set, and no error is returned.
A value of -1 specifies the center of the disk; a value of -2 means
immediately after the directory.

FIRQB+FQNENT

Data Returned
FIROB
Mnemonic

Octal
Offset

Octal
Offset
111111111111111111111

Mnemonic

1111111111

current job no .• 2

FOJOB

FOSIZM 5

(always 0)

channel number· 2

FOFIL

project number

programmer number

FOPPN
FONAM1

file name in RA050 format

(2 words)

file type in RA050 format (1 word)

FOEXT

(file size in 512-byte blocks)

FOSIZ

reasonable buffer size for device

FOBUFL

(as passed)

FOMOOE

FOFLAG

FOPFLG

FOOEV

FOOEVN

device description

25
FOPROT 27

protection code

31
33

clustersize, mod256

device name (2 ASCII characters)
flag byte

device unit number

file identification index

FOCLUS

(as passed)

FONENT

FIRQB+FQJOB

Current job number times two.

FIRQB+FQFIL

Channel number times two; defines the channel on which the file
is open.

FIRQB+FQPPN

The PPN under which the file is open. An actual PPN is returned
here even if this word was passed as zero.
.

FIRQB+FQNAM1

The file name created, as two words of RAD50 data.

FIRQB+FQEXT

The file type created, as one word of RAD50 data.

FIRQB+FQSIZ

The size to which the file was preextended, in 512-byte blocks.

3-20 CALFIP-CRBFQ

FIRQB+FQBUFL

Reasonable buffer size for disk reads and writes, in bytes. (Always
512 for disk.)

FIRQB+FQFLAG

Description of the device just opened (the same information as
the BASIC-PLUS STATUS variable). The low byte contains the
device's handler index, always zero (DSKHND) for disk. The high
byte contains a set of status flags, irrelevant here since the device
is always disk. (See the OPNFQ subfunction for more information
on these settings.)

FIRQB+FQPFLG

The file cluster size, modulo 256. That is, a file cluster size of
256 is indicated by zero. This is the same as the value passed at
FIRQB+FQCLUS, except that it is returned in a byte instead of a
word.

FIRQB+FQPROT

The protection code of the file. Bit 6 is 1, and bits 5 through 0 are
as passed. Bit 7 is as passed if the caller has SYSIO privilege;
otherwise it is O.

FIRQB+FQDEV

The device name of the disk device, as two ASCII characters. The
actual device name is returned here, even if this word was passed
as zero.

FIRQB+FQDEVN

The device unit number. The actual unit number is returned here,
even ifFIRQB+FQDEVN+1 was passed as zero.

FIRQB+FQCLUS

The file identification index of this file. This word is significant
mainly in that it can be used in place of the file name in subsequent opens of the file on disk. You can open the file with
the OPNFQ subfunction of CALFIP using an explicit PPN in
FIRQB+FQPPN, a zero word in FIRQB+FQNAM1, an explicit
device name in FQDEV and FQDEVN, and the file identification
index in FIRQB+FQNAM1+2.
Note that there is no performance gain for using the file identification index instead of the file name. The file identification
index is provided for compatibility with RSX Furthermore, the file
identification index is changed when the REORDR utility is run
(see the RSTS / E System Manager's Guide).

Errors
NOTCLS

The specified channel is already open. It must be closed before it can be
opened again.

PRVIOL

The specified device is not a disk device. The CRBFQ function can be
executed only for a disk device.

QUOTA

Extending the file causes the disk quota to be exceeded. This error does not
occur if the user has EXQTA privilege.

xxxxx

Other errors are device-dependent. See Appendix A for a full list of possible
error codes.

CALFIP-CRBFQ 3-21

Example
The following MACRO code sets up the FIRQB for the CRBFQ function of
CALFIP. The PPN is set to 2,210; the file name and type are set to FILNAM.TYP.
The protection code is set such that the file is read/write-protected against everyone but the caller (user with PPN 2,210), and execute-protected against all
but the caller and those in the caller's project (users with project number = 2).
The file is opened on disk unit 2 (DK2:). File size and cluster size are not specified. The cluster size defaults to the pack cluster size and the file size is not
preallocated.
DK:

.ASCII
CALL
MOVB
MOVB
MOVB
MOVB
MOV
MOV
MOV
MOVB
MOVB
MOV
MOVB
MOVB
CALFIP

IDKI
CLRFQB
iCRBFQ,FIRQB+FQFUN
i4*2,FIRQB+FQFIL
i2,FIRQB+FQPPN+l
i210.,FIRQB+FQPPN

;CLEAR FIRQB
;SET FUNCTION CODE
;SET CHANNEL = 4
;SET PROJECT NUMBER =2
;SET PROG. NO.=210.
i~RFIL,FIRQB+FQNAMl
;SET FILE NAME AND
i~RNAM,FIRQB+FQNAM1+2
;TYPE TO
i~RTYP,FIRQB+FQEXT
; "FILNAM.TYP"
i<8.+16.+32.>,FIRQB+FQPROT ;SET PROTECTION CODE
i255.,FIRQB+FQPFLG
;SET PROTECTION CODE REAL
DK,FIRQB+FQDEV
;SET DEVICE TO DISK,
i2,FIRQB+FQDEVN
;UNIT 2
; (EXPLICIT DEVICE NO.)
i255.,FIRQB+FQDEVN+l

See Programming Hints for information on the CLRFQB routine.

3-22 CALFIP-CRBFQ

3.5.4
(

CREFQ (Create a File and Open It on a Channel)
Form
MOVB

*CREFQ,FIRQB+FQFUN

;SET FUNCTION CODE

(set parameters appropriate to device)

CALFIP

Function

The CREFQ function performs the same action as a file-structured OPEN FOR
OUTPUT statement in BASIC-PLUS. Parameters defining the device, file name
and type, protection code, mode, file size, and cluster size can be used by setting
values in the FIRQB. The choice depends upon the device.
For example, CREFQ with a file name and type on a magtape device with mode
= 128 causes an OPEN for APPEND operation. A search for an existing file with
the specified name and on the specified device is made; the file would have to
be the last file on the tape. When found, the tape is positioned after the last
record in the file, ready for data to be written and appended. The RSTS / E
Programming Manual describes the file-structured OPEN for OUTPUT operation
for the various devices.
Privileges Required

TUNE to set caching mode. SYSIO to set the privilege bit (bit 7 in FQPROT). A
matching PPN, GWRITE, WWRITE, and/or SYSIO to create or rename a file. You
also need write access (by protection code, GWRITE, WWRITE, and/or SYSIO) to
supersede an existing file.

CALFIP-CREFQ 3-23

Data Passed
FIROB
Octal
Offset

Mne- Octal
monic Offset
I I 1/ I I I I I I 1/ I I I I I 1/ I I

Mnemonic

FOFUN 3

CRBFO (= 4)

1/1/1/1/1/

FOSIZM 5

MSB of file size

channel no .• 2

FOFIL

project number

programmer number

FOPPN
FONAM1

file name in RAD50 format

(2 words)

file type in RAD50 format (1 word)

FOEXT
FOSIZ

LSB of file size

111/1111111/111111111

mode

I I 1/ I I I I I I 1/ I I I I I 1/ I I

file protection

FOPROT 27

device name (2 ASCII characters)

31
33

<>0, prot.code.real

<>0, unit no. real

file clustersize

35
37

device unit number

device cluster number for first block

FOMODE

FOPFLG

FODEV

FODEVN

FOCLUS

FONENT

FIRQB+FQFUN

The function code CREFQ (octal value = 4).

FIRQB+FQFIL

Channel number times two; defines the channel upon which the
file is to be opened.

FIRQB+FQSIZM

For large disk files (greater than 65,535 blocks), this byte contains
the most significant bits (MSB) of the file size. See FIRQB+FQSIZ,
for a discussion of the entire 24-bit field used for large files on
disk.

FIRQB+FQPPN

The PPN with which the file is to be created. The project number
is in the high byte (FIRQB+FQPPN+l), and the programmer
number in the low byte (FIRQB+FQPPN). A value of zero defaults
to the PPN under which the calling program is running.

FIRQB+FQNAMI

The file name to create, as two words of RAD50 data.

FIRQB+FQEXT

The file type, as one word of RAD50 data.

FIRQB+FQSIZ

The desired file size, in 512-byte blocks. This parameter is relevant only for disk and ANSI magtape files. For disk files, this
word forms the least significant bits (LSB) of the file size. It is
combined with the byte at FIRQB+FQSIZM to form a 24-bit integer. The disk file is automatically preextended to the indicated
size. (That is, the space for the file is allocated when the file is
opened, not as it is written.) If preextending is not desired then
this value and FIRQB+FQSIZM should be zero.
For ANSI magtape, this word has the same function as the
FILE SIZE option in BASIC-PLUS (see the RSTSIE Programming
Manual).

3-24 CALFIP-CREFQ

FIRQB+FQMODE

The mode with which the file is to be opened; values and actions
taken for specific devices are as described for the MODE modifier
for file-structured OPEN for OUTPUT statements in the RSTS / E
Programming Manual. If a mode value is used, bit 15 of this word
must be set to 1.

FIRQB+FQPROT

File protection code; values for this field define subsequent read
and write access to the opened file (see the RSTS / E System User's
Guide). If you want a default protection code, then set a full
word of zeros at FIRQB+FQPFLG. In this case, either the system
default for protection code will be used, or, if the CREFQ will be
deleting a previously existing file with the same file name, type,
ppn, and device, the file protection code of the previously existing
file will be used.
To assign a specific file protection code, put a nonzero value in
byte FIRQB+FQPFLG (by convention, 255) and the specific file
protection code in byte FIRQB+FQPROT. This allows an explicit
file protection code of O.

FIRQB+FQDEV

The device name is passed here as two ASCII characters. A zero
word indicates the public disk structure.

FIRQB+FQDEVN

The device unit number is passed here in binary. A nonzero value
in FIRQB+FQDEVN+l indicates an explicit device unit number.
A zero value in FIRQB+FQDEVN+l indicates no unit number.

FIRQB+FQCLUS

This parameter has the same function as the CLUSTERSIZE
option in BASIC-PLUS. It is relevant only for disk files and ANSI
magtape files. A description of the CLUSTERSIZE option for
disk is given in the BASIC-PLUS Language Manual; for ANSI
magtape, in the RSTS / E Programming Manual.

FIRQB+FQNENT

For disk files, the device cluster number for placement of block
1 of the file. When creating a new file, you can place block 1 of
the file on a particular block by specifying the disk device cluster
number in this word. If this word is zero, no placement is done. If
it is nonzero, the monitor will try to place the file at the specified
device cluster or as near after it as possible.
If the first block of the file can be placed at or after the specified
device cluster number, the monitor sets a bit in the file's entry in
the UFD. If the first block of the file cannot be placed at or after
the specified device cluster number, the file is placed at the lowest
free block on the disk, the bit in the file's entry in the UFD is not
set, and no error is returned.
A value of -1 means the center of the disk; a value of -2 means
immediately after the directory.

CALFIP-CREFQ 3-25

Data Returned
FIROB
Octal
Offset

Mne- Octal
monic Offset
111111111111111111111

Mnemonic

1111111111

current job no .• 2

FOJOB

FOSIZM5

MSB of file size

channel number· 2

FOFIL

project number

programmer number

FOPPN
FONAM1

file name in RAD50 format

(2 words)

file type in RAD50 format (1 word)

LSB of file size

FOEXT

FOSIZ

reasonable buffer size for device

FOBUFL

(as passed)

FOMODE

device description

FOFLAG

FOPFLG

FOP ROT 27

protection code

clustersize, mod256

device name (2 ASCII characters)

FODEV

flag byte

FODEVN

device unit number

file identification index

FOCLUS

(as passed)

FONENT

NOTE

For nondisk devices, the relevant infonnation returned with the
CREFQ subfunction is in the two words at FIRQB+FQBUFL and
FIRQB+FQFLAG. All other words are simply returned as passed.

3-26

FIRQB+FQJOB

Current job number times two.

FIRQB+FQFIL

Channel number times two; defines the channel on which the file
is open.

FIRQB+FQSIZM

For large files, this byte contains the MSB of the size to which the
file was preextended, in 512-byte blocks. This byte is combined
with the word at FIRQB+FQSIZ to form a 24-bit field giving the
file size.

FIRQB+FQPPN

The PPN under which the file is open. An actual PPN is returned
here even if this word was passed as zero.

FIRQB+FQNAMI

The file name created, as two words of RAD50 data.

FIRQB+FQEXT

The file type created, as one word of RAD50 data.

FIRQB+FQSIZ

The size to which the file was preextended, in 512-byte blocks.

CALFIP-CREFQ

FIRQB+FQBUFL

Reasonable buffer size for this device, in bytes. If you are doing
device-independent 110 (that is, if you do not want to keep track
of which device is being opened and perform specific opens, reads,
and writes, depending on the device), this value is the monitor's
best guess for a buffer size to use in subsequent reads and writes
on the opened channel. (See the .READ and .WRITE directives.)

FIRQB+FQFLAG

Description of the device just opened (same information as the
BASIC-PLUS STATUS variable). The low byte contains the
device's handler index. There is one unique handler index for all
device types. The high byte contains a set of status flags to allow
for device-independent 110 routines.

DDNFS
DDRLO
DDWLO
FLGPOS
FLGMOD
FLGFRCl

FLciitf 1
15

14 13 12 11 10 9

device-type flags

7
device handler index

High Byte - Device-Type Flags

The bits in the high byte of the flags word are set to indicate the type of file or device just
opened:
FLGRND
FLGKB

FLGFRC

FLGMOD

=1
=0
=1

The device or file is random-access.

The file or device is not a terminal-type file or
device.

The file or device is byte-oriented. That is,
the .READ and .WRITE directives handle
data in byte units.

The file or device is block-oriented. The
.READ and. WRITE directives handle data in
block units.

The file or device accepts modifiers in .READ
and .WRITE directives.

The file or device does not accept modifiers in
.READ and .WRITE directives.

The device or file is sequential.
The file or device is a terminal-type file or
device (or is generically a terminal).

CALFIP-CREFQ 3-27

FLGPOS

DDWLO

DDRLO
DDNFS

The file or device keeps track of its horizontal position and expands characters such as
TAB into whatever is appropriate for the
file or device. You can determine the current horizontal position with the .POSTN
directive.

The file or device does not keep track of its
horizontal position.

The file or device has been write-locked (with
the mode value in the open) or is generically
a read-only device.

The file or device is not write-locked.

The device is generically a write-only device.

The file or device is not read-locked.

The file or device is non-file-structured (or is
generically not a file-structured device).

The file or device is file-structured.

Low Byte - Device Handler Index
Bits 0-7 of the flags word contain a handler index that indicates the generic kind of device.
The currently defined values follow.
Octal
Value

Symbol

Meaning

DSKHND

All disks

T1'YHND

All terminals

LPTHND

AlIHne printers

Reserved

6
10

Reserved

CDRHND

Card reader

MTAHND

Magnetic tape

PKBHND

Pseudo keyboards

RXDHND

Flexible diskettes

NULHND

The null device

24
26

Reserved

30-36

Reserved

KMCHND

KMCll

IBMHND

IBM interconnect

Reserved

DMPHND

DMPlllDMVll device

ETHHND

Ethernet device

FIRQB+FQPFLG

FIRQB+FQPROT

The protection code of the file. Bit 7 is as passed if the caller has
SYSIO privilege, and 0 otherwise; bits 6 to 0 are as passed.

3-28 CALFIP-CREFQ

FIRQB+FQDEV

The devicce name of the disk device, as two ASCII characters. The
actual device name is returned here, even if this word was passed
as zero.

FIRQB+FQDEVN

The device unit number. The actual unit number is ret.urned here,
even ifFIRQB+FQDEVN+l was passed as zero.

FIRQB+FQCLUS

The file identification index of this file. This word is significant
mainly in that it can be used in place of the file name in subsequent opens of the file on disk. You can open the file with
the OPNFQ subfunction of CALFIP using an explicit PPN in
FIRQB+FQPPN, a zero word in FIRQB+FQNAMl, and the file
identification index in FIRQB+FQNAMl+2.
Note that there is no performance gain for using the file identification index rather than the file name. The file identification
index is provided for compatibility with RSX. Furthermore, the file
identification index is changed when the REORDR utility is run
(see the RSTS/E System Manager's Guide).

Errors
NOTCLS

The specified channel is already open. It must be closed before it can be
opened again.

QUOTA

Extending the file causes the disk quota to be exceeded. This error does not
occur if the user has EXQTA privilege.
Other errors are device-dependent. See Appendix A for a full list of errors.

Example

The following MACRO code sets up the FIRQB for a CREFQ that opens a file
called FILE01.LST on the public disk structure. (The assumption here is that
previous code has filled the FIRQB with zeros, so the words at FIRQB+FQDEV
and FIRQB+FQDEVN are zero, indicating the public disk. Similarly, the mode
(FIRQB+FQMODE) and cluster size (FIRQB+FQCLUS) are zero, indicating normal read/write and the default cluster size.) A protection code of 56 is assigned
(write-protected against all but the owner, read-protected against all but those in
the owner's project).
MOVB
MOVB
MOV
MOV
MOV
MOVB
MOVB
CALFIP

#CREFQ,FIRQB+FQFUN
#5*2,FIRQB+FQFIL
#~RFIL,FIRQB+FQNAMl
#~RE01,FIRQB+FQNAM1+2

#ARLST,FIRQB+FQEXT
#56.,FIRQB+FQPROT
#255.,FIRQB+FQPFLG

Set function code in FIRQB
Set channel = 5
Set file name
and type to
FILE01.LST
Set protection code to
explicit protection code

CALFIP-CREFQ 3-29

3.5.5

CRTFQ (Create and Open a Temporary File)
Form
MOVB

#CRTFQ,FIRQB+FQFUN

(set appropriate parameters)

CALFIP

Function

The CRTFQ function can be used to create and open a temporary file on disk.
The file is temporary only in that the monitor generates a file name and type
for the file, which is recognized by the LOGOUT utility, and sets the IGNORE
attribute for the file, which is recognized by BACKUP. LOGOUT destroys such
files when the user logs out; the monitor does not inherently destroy temporary
files created with CRTFQ.
Most parameters relevant on an open are defaulted. You do not define or refer to
the file by name; subsequent read and write operations refer to the channel on
which the temporary file is open.
In addition to the function code, you specify a channel and, if desired, a file
size and/or file cluster size. If an explicit cluster size is specified, it is used. A
specified file size mayor may not be used. The monitor attempts to reuse an
existing temporary file for the same job by simply reopening that file. In this
case, the file's size is the size of the previous file. If no previous temporary file
for the job exists, or if one does exist but is already in use by somebody else, then
a new file is created, with the specified file size .. A new file is also created if an
explicit device name or cluster size is given.
Privileges Required

TUNE to set caching mode. You also need write access (by protection code,
GWRITE, WWRITE, and/or SYSIO) to supersede an existing file.

3-30 CALFIP-CRTFQ

Data Passed
FIROB
Mne- Octal
monic Offset

Octal MneOffset monic
111111111111111111111

FOFUN 3

CRTFO (= 32)

1111111111

FOSIZM5

MSB of file size

channel no .• 2

111111111111111111111

LSB of file size

II I I I 1/ I I I I I I 1/ I I I I I I

mode

111111/1111111/111111

111111111111111111111

device name (2 ASCII characters)

<>0, unit no. real

35
37

device unit number

file cluster size
device cluster number for this block

FOFIL

16 FOSIZ

FOMODE

FODEV

32 FODEVN
34 FOCLUS
36

FONENT

FIRQB+FQFUN

The function code CRTFQ (octal value =32).

FIRQB+FQFIL

Channel number times two; defines the channel on which the file
is to be opened.

FIRQB+FQSIZM

For large disk files (greater than 65,535 blocks), this byte contains
the MSB of the file size. See FIRQB+FQSIZ, for a description of
how the entire 24-bit field is used.

FIRQB+FQSIZ

This word contains the LSB of the file's size in 512-byte blocks.
(It is combined with the byte at FIRQB+FQSIZM.) The file size
mayor may not be used. If a temporary file already exists that
is not in use, the monitor uses the space allocated to the previous
temporary file. However, if cluster size is specified, a new file is
created, and the file size indicated by the 24-bit file size is used.

FIRQB+FQMODE

The mode with which the file is to be opened. Values are as described for the MODE modifier in OPEN for OUTPUT statements
for disk (see the RSTS/E Programming Manual). The only relevant modes are for creating a tentative file, creating a contiguous
file, creating a conditionally contiguous file, and for data caching.
All other mode bits are ignored, except bit 15. If a mode value is
used, bit 15 of this word must be set to 1.

FIRQB+FQDEV

The device name is passed here as two ASCII characters; it must
be a disk device. A value of zero in this word indicates _SY:, the
public disk.

CALFIP-CRTFQ 3-31

FIRQB+FQDEVN

The device unit number is passed here in binary. A nonzero value
in the high byte (FIRQB+FQDEVN+1) indicates an explicit device
unit number. A zero value in FIRQB+FQDEVN+1 indicates no
unit number.

FIRQB+FQCLUS

File cluster size. Performs the same function as the CLUSTERSIZE
option in BASIC-PLUS.
The device cluster number for placement of block 1 of the file on
disk. When creating a new file, you can place block 1 of the file
on a particular block by specifying the disk device cluster number
in this word. If this word is zero, no placement is done. If it is
nonzero, the monitor tries to place the file at the specified device
cluster or as near after it as possible.
If the first block of the file can be placed at or after the specified
device cluster number, the monitor sets a bit in the file's entry in
the UFD. If the first block of the file cannot be placed at or after
the specified device cluster number, the file is placed at the lowest
free block on the disk, the bit in the file's entry in the UFD is not
set, and no error is returned.
A value of -1 means the center of the disk; a value of -2 means
immediately after the directory.

FIRQB+FQNENT

Data Returned
FIROB
Octal
Offset

Mne- Octal
monic Offset

/////////////////////

Mnemonic

//////////

current job no .• 2

FOJOB

FOSIZM5

MSB of file size

channel no .• 2

FOFIL

project number

programmer number

FOPPN
FONAM1

file name in RAD50 format

(2 words)

file type in RAD50 format (1 word)
LSB of file size

17
21

reasonable buffer size for device
(as passed)

device description

25
FOPROT 27

protection code

clustersize, mod256

FOEXT

FOSIZ

FOBUFL

FOMODE

FOFLAG

FOPFLG

device name (2 ASCII characters)

FODEV

flag byte

FODEVN

device unit number

file identification index

FOCLUS

(as passed)

FONENT

FIRQB+FQJOB

Current job number times two.

FIRQB+FQFIL

Channel number times two; defines the channel on which the file
is open.

3-32 CALFIP-CRTFQ

FIRQB+FQSIZM

For large disk files (greater than 65,535 blocks), this byte contains
the MSB ofthe file size in 512-byte blocks. It is combined with the
word at FIRQB+FQSIZ to form a 24-bit field giving the file size.

FIRQB+FQPPN

The PPN under which the file is open. An actual PPN is ret.urned
here even if this word was passed as zero.

FIRQB+ FQN.AM:1

The file name created; two words of RAD50 data.

FIRQB+FQEXT

The file type created; one word of RAD50 data.

FIRQB+FQSIZ

The size t.o which t.he file was preextended, in 512-byte blocks.

FIRQB+FQBUFL

Reasonable buffer size for disk reads and writes, in bytes. (Always
512. for disk.)

FIRQB+FQFLAG

Description of the device just. opened (t.he same informat.ion as
the BASIC-PLUS STATUS variable). The low byte contains the
device's handler index, always zero (DSKHND) for disk. The high
byte contains a set of status flags, irrelevant here since the device
is always disk. See the OPNFQ subfunction for more information
about these set.tings.

FIRQB+FQPFLG

FIRQB+FQPROT

The protection code of the file.

FIRQB+FQDEV

The device name of the disk device, as two ASCII characters. The
actual device name is returned here, even if this word was passed
as zero.

FIRQB+FQDEVN

The device unit number. The actual unit number is returned here,
even if FIRQB+FQDEVN+1 was passed as zero.

FIRQB+FQCLUS

The file identification index of this file. This word is significant
mainly in that it can be used in place of the file name in subsequent opens of the file on disk. You can open the file with
the OPNFQ subfunction of CALFIP using an explicit PPN in
FIRQB+FQPPN, a zero word in FIRQB+FQN.AM:1, and the file
identification index in FIRQB+FQN.AM:1+2.
Note that there is no performance gain for using the file identification index rather than the file name. The file identification
index is provided for compatibility with RSX. Furthermore, the file
identification index is changed when the REORDR utility is run
on the directory (see the RSTSjE System Manager's Guide).

Errors
QUOTA

Extending the file causes the disk quota to be exceeded. This error does not
occur if the user has EXQTA privilege.

xxxxx

All other errors for this directive are device-dependent. See Appendix A for
a full list of errors.

Example

The following MACRO code opens a temporary file on channel 13. Assume that
the FIRQB has been initialized to all zeros. Hence, the temporary file is created
on the public disk structure:
MOVB
MOVB
CALFIP

#CRTFQ,FIRQB+FQFUN
#13.*2,FIRQB+FQFIL

;SET FUNCTION CODE
;SET CHANNEL TO 13

CALFIP-CRTFQ 3-33

3.5.6

DAlFQ (Deallocate All Devices and Deassign All User logicals)
Form
MOVB
CALFIP

#DALFQ,FIRQB+FQFUN

Function
The DALFQ subfunction deallocates all devices currently allocated to the job and
deassigns all user logicals assigned by the job.

Privileges Required
None

Data Passed
FIRQB
Octal
Offset

Mne- Octal
monic Offset

FQFUN

/ / II / / / / / / II / / / / / II / /

DALFQ (= 30)

1/1/1/1/1/

/ / 1/ / / / / / / II / / / / / 1/ / /

/ / II / / / / / / II / / / / / II / /

/ / 1/ / / / / / / II / / / / / II / /

/ / II / / / / / / II / / / / / II / /

/ / II / / / / / / II / / / / / / / / /

/ / II / / / / / / II / / / / / II / /

/ / II / / / / / / II / / / / / / / / /

/ / II / / / / / / II / / / / / II / /

FIRQB+ FQFUN

Mnemonic

The function code DALFQ (octal value = 30).

Data Returned

The DALFQ subfunction of CALFIP does not return any meaningful data.

Errors
No errors are possible with DALFQ.

3-34

CALFIP-DALFQ

3.5.7

DEAFQ (Deallocate a Device)
Form
MOVB

#DEAFQ,FIRQB+FQFUN

-(Define device to be deallocated in FIRQB)

CALFIP

Function
The DEAFQ subfunction deallocates (that is, releases it for use by other jobs) a
device from the current job. If the device is an outbound LAT keyboard, DEAFQ
terminates any connection before deallocating the keyboards.

Privileges Required
None

Data Passed
FIRas
Octal MneOffset monic

Mne- Octal
monic Offset

/11///1//1////1////1/

OEAFa (= 26)

FaFUN 3

1/1/1/1/1/

//1/////1//1/1//1////

/11////1/1/1///1/1/1/

(must = 0)

/11////1/1//1/1///1//

1/ / / / / / / / / / / / / / / / / / / /

//1//1/1/1/1//1////1/

1/1//1/1/1/1/////1/1/

///1//1/////1/////1//

///////1///1////1////

//////1/1///1///1////

device name (2 ASCII characters)

FaOEV

FaOEVN

<>0, unit no. real

device unit number

//1//////11/////1////

///////1///////1/////

FaNAM1

FIRQB+FQFUN

The DEAFQ function code (octal value =26).

FIRQB+FQNAMI

The word at this location must be set to zero.

CALFIP-DEAFQ 3-35

FIRQB+FQDEV

The name of the device to be deallocated, as two ASCII characters.

FIRQB+FQDEVN

The device unit number is passed here in binary. A nonzero value
in FIRQB+FQDEVN+l indicates an explicit device unit number,
while a zero value indicates no device unit number.

Data Returned
Except for a possible error in byte 0 of the FIRQB, the DEAFQ subfunction of
CALFIP does not return any meaningful data.
Errors
NODEVC

The device or its type specified at FIRQB+FQDEV and FIRQB+FQDEVN is
not part of your system configuration.

Example
The following code deallocates LP: from the current job:
CALL
MOVB
MOV
CALFIP

CLRFQB
#DEAFQ,FIRQB+FQFUN
#"LP,FIRQB+FQDEV

Clear FIRQB
Set function code
Device=line printer

See Programming Hints for information on the CLRFQB routine.

3-36 CALFIP-DEAFQ

3.5.8

DIRFQ (Get Directory Information)
Form
MOVB

tDIRFQ,FIRQB+FQFUN

(Define device for the directory wanted)

CALFIP

Function

The DIRFQ subfunction of CALFIP returns directory information about a disk,
DECtape, or magtape file. Two forms of the call are available. One leaves a
magtape file positioned at the EOF and returns the size of the file as part of the
directory information. The second form, for magtape only, leaves a magtape file
positioned at the beginning of the file, and does not return the size of the file.
NOTE

For disk directory lookup on a PPN other than that of the caller,
DIRFQ returns only those files to which the caller has read or execute
access.
Privileges Required

DEVICE to perform a directory lookup or disk lookup on caller's account if the
referenced device is restricted. You need read or execute access (by protection
code, GREAD, or WREAD) to perform a disk directory lookup on another account.

CALFIP-DIRFQ 3-37

Data Passed -

Directory Lookup on Index
FIR08

Mne- Octal
monic Offset

Octal MneOffset monic

FOFUN 3

/1///////1//////1////

DIRFO (= 12)

5
7

//////////

index of file to read

FOFIL

FOPPN

project number

programmer number

/I / / / / / / // / / / / / /I / / / /

/////////1//////1////

/1///////1///////////

/////////1///////////

/I / / / / / / // / / / / / /I / / / /

/////////1//////1////

/ / / / I) / / / / / / / / / / / / / / /

device name (2 ASCII characters)

FODEV

FODEVN

<>0, unit no. real

device unit number

/I / / / / / / // / / / / / /I / / / /

FIRQB+FQFUN

The function code DIRFQ (octal value = 12).

FIRQB+FQFIL

The index of the file to read. If this word is zero, the monitor
returns data for the first file in the directory. For some positive
value n, the monitor returns data for the n+1 file in the directory.
For magtape, a value of zero causes the monitor to rewind the tape
before it gets the information for the first file (by reading the label
record of the file). The monitor then spaces the tape forward to
the next EOF record and calculates the number of records in the
file. The tape is left in that position. A nonzero value performs
the same action, except that the tape is not rewound.
For DECtape, the first call issued must have a value of zero in
this word to read the directory blocks from the tape before reading
the first file. Subsequent calls with this word nonzero read the
directory from the BUFF.SYS file. (Directory information for
DECtape is kept in this system file on disk to speed up DECtape
file processing: see the RSTS / E Programming Manual.)

FIRQB+FQPPN

The PPN of the directory to look up, for disk or magnetic tape,
(The monitor does not use these bytes if the device is DECtape but
simply returns information for each file read on the device.)
If this word is zero and the device is disk, this directive returns
information for the PPN under which this job is being executed.
If this word is zero and the device is magnetic tape, this directive
returns information for each file read, regardless of the PPN under
which it was written.

3-38 CALFIP-DIRFQ

FIRQB+FQDEV

The device name, as two ASCII characters. Must be disk, magnetic tape, or DECtape. If this word is zero, the public disk
structure CSY:) is used.

FIRQB+FQDEVN

The device unit number is passed here in binary. A nonzero value
in FQDEVN+1 indicates an explicit device unit number. A zero
value in FQDEVN+1 indicates no unit number.

Data Passed - Special Magnetic Tape Lookup
FIR08
Mne- Octal
monic Offset

FOFUN

Octal
Offset
1/1/1///////1//////1/

DIRFO (= 12)

1/1/1/1/1/

index of file to read

Mnemonic

FOFIL
FOPPN

must = 177777 for magnetic tape lookup

1//1//1/////1//////1/

/1//1///////1//////1/

////1///////1//////1/

/1//1/1///1/1//////1/

/ / / / 1/ / / / / / / 1/ / / / / / 1/

1///1///////1//////1/

1//1/1/1////1//////1/

//1/1///////1//////1/

device name (2 ASCII characters)

FODEV

FODEVN

<>0, unit no. real

device unit number

//1/1///////1//////1/

/ / / / 1/ / / / / / / 1/ / / / / / 1/

FIRQB+FQFUN

The function code DIRFQ (octal value =12).

FIRQB+FQFIL

Index number of the file to be read. If this word is zero,
information is returned for the first file in the directory. If this
word is some positive value n, information is returned for the
n+1 file in the directory. A value of zero causes the monitor
to rewind the tape before getting information from the first
file (by reading the label record). It then back spaces the tape
one record, leaving it positioned at the beginning-of-file (BOF).
(This action leaves the tape positioned such that an open on
this file will succeed on a single read from tape.)

CALFIP-DIRFQ 3-39

A nonzero value does not cause the tape to be rewound;
the next record is read (it must be a label), and the tape is
backspaced one record. When you are searching a tape for specific files to read, the normal action is to execute this directive
with a value of zero first. If the file is one to be read, open
the file requesting no rewind, process the file, and close it to
position the tape at the EOF. If the file is not one to be read,
space the tape forward to the next EOF. (You can do this in
MACRO with the .SPEC directive.) Then issue the DIRFQ call
with a nonzero value in the word beginning at FIRQB+FQFIL,
and continue the process.

FIRQB+FQPPN

This word must be set to 177777 for the special magnetic tape
lookup operation.

FIRQB+FQDEV

The device name as two ASCII characters. The device must be
a magnetic tape drive.

FIRQB+FQDEVN

The device unit number, in binary. A nonzero value in
FIRQB+FQDEVN+l indicates an explicit device unit number. A zero value in FIRQB+FQDEVN+l indicates no unit
number.

Data Returned (Both)
FIRQB
Mne- Octal
monic Offset

Octal MneOffset monic
I 1/ I I I I I I 1/ I I I I I 1/ I I I

I
J

1/1/1/1/1/

curren! job no .• 2

(as passed)
project number

programmer number

0
2

FQJOB

FQFIL

FQPPN
FQNAM1

file name in RAD50 format

(2 words)

file type in RAD50 format (1 word)

14 FQEXT

LSB of file length in blocks

16 FQSIZ

MSB of file length

protection code

FQNAM2

date of last access

FQMODE

date of creation

FQRAG

time of creation

FQPFLG

FQDEV

FQDEVN

file clustersize (disk only)

FQCLUS

FQNENT

31
(as passed)
33
35

USTAT byte

number entries ret.

FIRQB+FQJOB

The current job number times two.

FIRQB+FQPPN

The PPN of the file. The project number is in the high byte
(FIRQB+FQPPN+1) and the programmer number is in the low

byte (FIRQB+FQPPN).

3-40

CALFiP-DIRFQ

FIRQB+FQNAM1

The file name; two words in RAD50 format.

FIRQB+FQEXT

The file type; one word in RAD50 format.

FIRQB+FQSIZ

The LSB of the file size, in 512-byte blocks. This word is combined
with the byte at FIRQB+21 to form a 24-bit value giving the file's
size.

FIRQB+FQNAM2

The protection code of the file.

FIRQB+FQNAM2+1

The MSB ofthe file's size in 512-byte blocks (see FIRQB+FQSIZ).

FIRQB+FQMODE

The date the file was last accessed, in system internal format:
[(year/1970) * 1000.] + day-with in-year

See the .DATE directive for a discussion of the system internal
format for dates.
FIRQB+FQFLAG

The date the file was created, in system internal format.

FIRQB+FQPFLG

The time that the file was created, in system internal format:
minutes before midnight, where midnight = 1440. (See the .DATE
directive for a discussion of the system internal format for time.)

FIRQB+FQCLUS

The file cluster size for disk devices. It is not used for tape.

FIRQB+FQNENT

Number of entries returned: 8 for disk; 6 for tape.

FIRQB+FQNENT+1

Internal flag information (disk only):
Bit
Meaning When Set
1

File is placed

Some job has write access now

File is open in update mode

File is contiguous; no extend allowed

No delete or rename allowed

File is marked for deletion

Errors
DEVNFS

The device specified is not a file-structured device.

NOSUCH

Either account (PPN) does not exist on the device specified, or no more files
exist on the account (the index number is greater than the number of files
on the account). Or, for the special magnetic tape lookup, no more files exist
on the tape.

xxxxx

Other errors are device-dependent. See Appendix A for a full list of errors.

Example

The following code searches the disk directory to examine files for user [2,101]:
LOOP:

MOVB
CLR
MOV
CLR
CLR
CALFIP

#DIRFQ,FIRQB+FQFUN
FIRQB+FQFIL
#<2.*400+101.>,FIRQB+FQPPN
FIRQB+FQDEV
FIRQB+FQDEVN

iSET FUNCTION CODE
;SET PROJ.,PROG.NO.
iSEARCH SYSTEM DISK

(Error processing, examine file name, process file)

INCB
JMP

FIRQB+FQFIL
LOOP

;INCREMENT INDEX
;GO BACK FOR NEXT ROUND

CALFIP-DIRFQ 3-41

3.5.9

DLNFQ (Delete a File)
Form
MOVB

#DLNFQ,FIRQB+FQFUN

(Define file to be deleted in FIRQB)

CALFIP

Function
The DLNFQ function of CALFIP deletes a file from disk or DECtape. The monitor's internal data on the location of the file are destroyed, and the file's space on
the device is made available for general use.
Privileges Required

DEVICE to delete a DECtape file if the referenced device is restricted. You need
write access (by protection code, GWRITE, WWRITE, and/or SYSIO) to delete
a disk file. Note that files marked nondeletable (using SET FILEINODELETE)
cannot be deleted regardless of the caller's privileges.
Data Passed
FIRQB
Octal MneOffset monic

Mne- Octal
monic Offset
1/ I I I / / I 1/ I I / I I 1/ I / / /

FQFUN 3

5
7

CALFIP-DLNFQ

I
I

111/111111

1/ / / / I / / 1/ / / / / / 1/ / / / /

project number

programmer number

2
4
6

FQPPN
FONAM1

file name in RAD50 format

(2 words)

file type in RAD50 format (1 word)

1/ / / / / I I 1/ I / I I I 1/ I I / I

1/ I / / / I I 1/ / / I I / 1/ I I I I

1/ I I / I / I 1/ I I / / I 1/ / / I I

1/ / / I / I I 1/ / / I I I 1/ I I I I

1/ I / I / I I 1/ I I I I I 1/ I I / I

device name (2 ASCII characters)

FODEV

FODEVN

3-42

DLNFQ (= 6)

<>0, unit no. real

device unit number

1/ I / I I I / / / / I I / / / / I I I I

I I I I / I I I 1/ / I / / I I I I I I I

FOEXT

FIRQB+FQFUN

The function code DLNFQ (octal value =6).

FIRQB+FQPPN

The PPN of the file to deleted. The project number is in the high
byte (FIRQB+FQPPN+l), and the programmer number is in the
low byte (FIRQB+FQPPN). A value of zero defaults to the PPN
under which the calling program is running.

FIRQB+FQNAMI

The name of the file to be deleted, as two words of RAD50 data.

FIRQB+FQEX.T

The file type, as one word of RAD50 data.

FIRQB+FQDEV

The name of the device containing the file to be deleted, as two
ASCII characters; it must be a disk or DECtape device. A value of
zero in this word indicates the public disk structure CSY:).

FIRQB+FQDEVN

The device unit number, in binary. A nonzero value in FQDEVN+l
indicates an explicit device unit number. A zero value in
FQDEVN+l indicates no unit number.

Data Returned
Except for a possible error in byte 0 of the FIRQB, the DLNFQ fWlCtion of
CALFIP does not return any meaningful data.

Errors
NOSUCH

The file specified in the data passed cannot be found.

PRVIOL

Protection violation. An attempt was made to delete a file that is either
write-protected against the caller or marked for no delete.

Example
The following code deletes the file MYFIL.LST from the user's account on the
public structure. Assume that the FIRQB has been filled with zeros previously:
MOVB
MOV
MOV
MOV
CALFIP

*OLNFQ,FIRQB+FQFUN
*ARMYF,FIRQB+FQNAMI
*ARILE,FIRQB+FQNAMl+2
iARLST,FIRQB+FQEXT

;SET FILE NAME
;ANO TYPE
;TO "MYFILE.LST"

CALFIP-DLNFQ 3-43

3.5.10

ERRFQ (Return Error Message Text)
Form/Example
MOVE
MOVE

#ERRFQ,FIRQB+FQFUN
#ERR,FIRQB+FQERNO

Function

The ERRFQ subfunction of CALFIP returns error message text from the system
error message file 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 error code
passed as byte 4 of the FIRQB. This call returns the full RSTSIE error message
text associated with errors returned in byte 0 of the FIRQB on all the monitor
directives.
Privileges Required

None
Data Passed
FIR08
Mne- Octal
monic Offset

Octal MneOffset monic

111111111111111111111

FOFUN 3

ERRFO (= 16)

1111111111

error code

111111111111111111111

I II I I I I I I I I I I I I I I I I I I

111111111111111111111

111111/11111111111111

11111111/111111111111

FOERNO

FIRQB+FQFUN

The function code ERRFQ (octal value = 16).

FIRQB+FQERNO

The error code value (in binary) for which the corresponding error
message text is to be returned.

3-44 CALFIL-ERRFQ

Errors
The ERRFQ subfunction of CALFIP does not return any errors.

Data Returned
FIRQB
Octal MneOffset monic

Mne- Octal
monic Offset
111111111111111111111

KB*2(-1-KB*2.detaCh)1

job number· 2

0
2 FQJOB

4 FQFIL

11
error message-padded with nulls

13
15

to 28 characters (ASCII format)

FIRQB+FQJOB

The current job number times two.

FIRQB+3

If the job is attached, two times the currently attached keyboard
number. If the job is detached, the one's complement of two
times the currently detached keyboard number. For example, if
the keyboard number is 5, the value in FIRQB+3 is: 12 for an
attached job and 365 (377-12) for a detached job.

FIRQB+FQFIL

The error message text begins in this byte. The text is padded
with zeros to 28 characters, if necessary.

CALFIL-ERRFQ 3-45

3.5.11

LOKFQ (Disk File/Wildcard Lookup)
Form
MOVB

#LOKFQ,FIRQB+FQFUN

(Set up FIRQB to define file/wildcard)

CALFIP

Function

The LOKFQ subfunction of CALFIP does one of two actions:
•

Looks for a file on disk by name and returns directory information (date of
creation, and so forth)

•

Performs a wildcard file search

For example, with a file name and type in the FIRQB of *.TXT it searches an
account for a file with any file name and a type of .TXT. By incrementing an
index and reexecuting LOKFQ, you can search through an entire directory for all
such files.
NOTE

For disk directory lookup on a PPN other than that of the caller,
LOKFQ returns only files to which the caller has read or execute
access.
Privileges Required

DEVICE to perform a disk directory lookup on the caller's account if the referenced device is restricted. You need read or execute access (by protection code,
GREAD, or WREAD) to perform a disk directory lookup on another account.

3-46 CALFIP-LOKFQ

Data Passed -

Disk Directory Lookup
FIR08

Mne- Octal
monic Offset

Octal MneOffset monic
1/ / / / / / / / / / / / / / / / / / / /

LOKFO (= 22)

FOFUN 3

(must equal 177777 octal)

FOFIL

FOPPN

FONAM1

project number

/11//1/1/1

programmer number

file name
in RA050 format
(2 words)

file type in RA050 format (1 word)

/I / / / / / / 1/ / / / / / /I / / / /

II / / / / / / / / / / / / / /I / / / /

/I / / / / / / II / / / / / 1/ / / / /

II / / / / / / / / / / / / / 1/ / / / /

device name (disk) (2 ASCII characters)

FOOEV

<>0, device no. real

FOOEVN

device unit number

II / / / / / / / / / / / / / 1/ / / / /

II / / / / / / / / / / / / / / / / / / /

FOEXT

FIRQB+FQFUN

The function code LOKFQ (octal value = 22).

FIRQB+FQFIL

The word beginning at this location must be set to 177777 (octal)
to indicate the "disk directory lookup by file name" option of
LOKFQ.

FIRQB+FQPPN

The PPN for the file to be looked up. A value of zero for this word
defaults to the PPN under which the calling program is running.

FIRQB+FQNAM1

The file name to be looked up; two words in RAD50 format.

FIRQB+FQEXT

The file type of the file to be looked up; one word in RAD50 format.

FIRQB+FQDEV

The device name (must be disk), as two ASCII characters. If both
bytes are zero, the public disk structure LSY:) is used.

FIRQB+FQDEVN

The disk device unit number is passed here in binary. A nonzero
value in FQDEVN+1 indicates an explicit device unit number. A
zero value in FQDEVN+1 indicates the system default.

CALFIP-LOKFQ 3-47

Data Returned -

Disk Directory Lookup by File Name
FIROB
Octal MneOffset monic

Mne- Octal
monic Offset
/////////////////////

//////////

I job number· 2

2 FOJOB

same as data passed (177777 octal)

4 FOFIL

6 FOPPN

project number

programmer number

file name in RAD50 format

(2 words)

10 FONAM1
12

file type in RAD50 format (1 word)

14 FOEXT

LSB of file length in 512-byte blocks

16 FOSIZ

MSB of file length

protection code

20 FONAM2

date of last access

22 FOMODE

date of creation

24 FOFLAG

time of creation

26 FOPFLG

device name (2 ASCII characters)

30 FODEV

32 FODEVN

<>0, unit no. real

device unit number

file clustersize

34 FOCLUS

file identification index

36 FONENT

FIRQB+FQJOB

The current job number times two.

FIRQB+FQFIL

The word at this location is the same as the data passed, in this
case, 177777 (octal).

FIRQB+FQPPN

The PPN of the file (same as data passed).

FIRQB+FQNAM1

The file name; two words in RAD50 format (same as data passed).

FIRQB+FQEXT

The file type; one word in RAD50 format (same as data passed).

FIRQB+FQSIZ

The LSB of the file's size in 512-byte blocks. This word is combined with the byte at FIRQB+21 to form a 24-bit field giving the
file size.

FIRQB+FQNAM2

The file's protection code, in binary, is returned in this byte.

FIRQB+21

The MSB ofthe file size in 512-byte blocks. It is combined with
the word at FIRQB+FQSIZ to form a 24-bit field giving the file
size.

FIRQB+FQMODE

The date the file was last accessed, in system internal format:
[(year - 1970) * 1000.] + day-within-year.

See the .DATE directive for a discussion of the system internal
format for dates.
FIRQB+FQFLAG

The date the file was created, in system internal format (see
FIRQB+FQMODE).

FIRQB+FQPFLG

The time the file was created, in system internal format: minutes
until midnight, with 1440 equal to midnight.

3-48 CALFIP-LOKFQ

FIRQB+FQDEV

The device name, as two ASCII characters. Always a specific
name, even if zero was passed here.

FIRQB+FQDEVN

The device unit number, in binary. A specific number is always
returned here; FIRQB+FQDEVN+l is always nonzero.

FIRQB+FQCLUS

The file cluster size is returned in this word.

FIRQB+FQNENT

The file identification index is returned in this word. You can
use the file identification index instead of the file name to open
a file on disk with the OPNFQ subfunction of CALFIP. To do so,
specify an explicit device name at FIRQB+FQDEV, a device unit
number at FIRQB+FQDEVN, an explicit PPN at FIRQB+FQPPN,
a zero word at FIRQB+FQNAM1, and the file identification index
at FIRQB+FQNAM1+2. (The file identification index is used by
utilities that access software subroutines in the RMS libraries, for
example.)
Note that there is no performance gain in using the file identification index instead of the file name. The file identification index is
provided for compatibility with RSX. Furthermore, the file identification index is changed when the REORDR utility is run on the
directory (see the RSTSjE System Manager's Guide).

Errors
BADNAM

The file name in bytes FIRQB+FQNAMl through FIRQB+13 is missing or
invalid.

NOSUCH

The device specified at FIRQB+FQDEV is not disk, or the file specified does
not exist on the specified disk. This error also occurs when a user does not
have read or execute access to the specified file.

Example
The following code looks for the file MATRIX.DAT on the system disk:
CALL
MOV
MOV
CLR
MOV
MOV
MOV
CLR
CLR
CALFIP

CLRFQB
#LOKFQ,FIRQB+FQFUN
#177777,FIRQB+FQFIL
FIRQB+FQPPN
#ARMAT,FIRQB+FQNAMl
#ARRIX,FIRQB+FQNAM1+2
#ARDAT,FIRQB+FQEXT
FIRQB+FQDEV
FIRQB+FQDEVN

;CLEAR FIRQB
;SET FUNCTION CODE
;FILENAME LOOKUP
;CALLER'S ACCOUNT
;SET FILENAME
;AND TYPE
;TO "MATRIX.DAT"
;SYSTEM DISK
; DEVICE

See Programming Hints for information on the CLRFQB routine.

CALFIP-LOKFQ 3-49

Data Passed -

Disk Wildcard Directory Lookup
FIR08
Octal MneOffset monic

Mne- Octal
monic Offset
111111111111111111111

LOKFO (= 22)

FOFUN 3

1111111111

index: n means search for n+1 occurrence

project number

programmer number

wildcard file name
specification in RAD50 format
(2 words)

11
13

15 wildcard file type in RAD50 format (1 word)

4 FOFIL
6

10 FONAM1
12
14 FOEXT

111111111111111111111

marked-for-delete flag

I /I I I I I I I II I I I I I II I I I

111111111111111111111

device name (disk) (2 ASCII characters)

<>0, device no. real'

device unit number

FOPPN

22 FOMODE

30 FODEV
32 FODEVN

I /I I I I I I I II I I I I I II I I I

111111111111111111111

FIRQB+FQFUN

The function code LOKFQ (octal value =22).

FIRQB+FQFIL

An index number specifying the occurrence of the file name
meeting the wildcard specifications. A value of zero in this word
causes the monitor to search for the first file name in the directory
that meets the specification. A value of one causes the monitor to
search for the second file name, and so forth.

FIRQB+FQPPN

The PPN of the account whose directory of disk files is to be
searched.

FIRQB+FQNAM1

The wildcard file name; as two words in RAD50 format. Either
an asterisk (*) character can replace the entire file name, or a
question mark (1) character can replace any character in the
file name. For example, a file name of FILE?? would cause the
monitor to search the directory for any file name beginning with
the characters FILE. An * character indicates that the file name
does not matter in the search.

FIRQB+FQEX.T

The wildcard file type; as one word in RAD50 format. An *
character can replace the entire file type, or a ? character can
replace any character in the file type. For example, a file type of
BA? causes the monitor to search the directory for any file type
beginning with the characters BA. An * character indicates that
the file type does not matter in the search.

FIRQB+FQMODE

If bit 14 is set, LOKFQ returns information about marked-fordelete files.

3-50 CALFIP-LOKFQ

FIRQB+FQDEV

The name of the device to be searched (must be disk). A value of
o in this word indicates the public disk structure LSY:).

FIRQB+FQDEVN

The device unit number in binary. A nonzero value in
FIRQB+FQDEVN+l indicates an explicit device unit number.
A zero value in FIRQB+FQDEVN+l indicates the system default.

Data Returned -

Disk Wildcard Directory Lookup
FIROB
Octal MneOffset monic

Mne- Octal
monic Offset
I 1/ I I I I I I 1/ I I I I I 1/ I I I

I
I

11111/1111

job number' 2

project number

2 FOJOB
4 FOFIL

(as passed)

programmer number

file name in RAD50 format

(2 words)

FOPPN

10 FONAM1
12

file type in RAD50 format (1 word)

14 FOEXT

LSB of file length in 512-byte blocks

16 FOSIZ

MSB of file length

protection code

20 FONAM2

date of last access (disk only)

22 FOMODE

date of creation

24 FOFLAG

time of creation

26 FOPFLG
30

FODEV

(as passed)
32 FODEVN

33
35

file clustersize (disk only)

34 FOCLUS

36 FONENT

USTAT byte

1111111111

FIRQB+FQJOB

The current job number times two.

FIRQB+FQPPN

The PPN of the file (same as data passed).

FIRQB+FQNAMI

The actual file name of a file meeting the wildcard specification in
the data passed; two words in RAD50 format.

FIRQB+FQEXT

The actual file type of a file meeting the wildcard specification in
the data passed; one word in RAD50 format.

FIRQB+FQSIZ

The LSB of the file's size in 512-byte blocks. This word is combined with the byte at FIRQB+21 to form a 24-bit field giving the
file's size.

FIRQB+FQNAM2

The file's protection code, in binary, is returned in this byte.

FIRQB+21

The MSB of the file's size in 512-byte blocks. The byte is combined
with the word at FIRQB+FQSIZ to give the file's size.

FIRQB+FQMODE

The date the file was last accessed, in system internal format:
[(year - 1970) * 1000.] + day-within-year.
See the .DATE directive for a discussion of the system internal
format for dates.

CALFIP-LOKFQ 3-51

FIRQB+FQFLAG

The date the file was created, in system internal format (see
FIRQB+FQMODE).

FIRQB+FQPFLG

The time the file was created, in system internal format: minutes
until midnight, with 1440 equal to midnight.

FIRQB+FQDEV

The device name, as two ASCII characters. Always a specific
name, even if zero was passed here.

FIRQB+FQDEVN

The device unit number, in binary. A specific number is always
returned here; FIRQB+FQDEVN+1 is always nonzero.

FIRQB+FQCLUS

The file cluster size is returned in this word.

FIRQB+FQNENT+1

Internal flag information:
Bit
Meaning When Set
1

File is placed

Some job has write access now

File is open in update mode

File is contiguous; no extend allowed

No delete or rename allowed

File is marked for deletion

Errors
BADNAM

No file specification appears at FIRQB+FQNAM1 or the file name is invalid.

NOSUCH

Either the device specified at FIRQB+FQDEV and FIRQB+FQDEVN is
not a disk, or no match exists for the occurrence specified in the word at
FIRQB+FQFIL.

PAKLCK

The disk is restricted and the caller does not have DEVICE privilege.

Example

The following code asks the monitor to search the directory for account [2,130] for
the first occurrence of a file specification beginning with the letter X:
CALL
CALL
MOV
MOV
MOV
.FSS
MOVB
CALFIP

CLRFQB
CLRXRB
#FILNAM,XRB+XRLOC
#NAMSIZ,XRB+XRLEN
#NAMSIZ,XRB+XRBC
#LOKFQ,FIRQB+FQFUN

iMAKE SURE FIRQB
i AND XRB ARE CLEAR
;POINT TO FILE NAME
;SET ITS LENGTH
;AND AGAIN
iCONVERT TO FIRQB FORMAT
;SET FUNCTION CODE

FILNAM:
NAMSIZ =

.ASCII "[2,130]X?????*"
.-FILNAM

iSTRING FOR .FSS TO CONVERT
iAND ITS LENGTH

See Programming Hints for information about the CLRFQB and CLRXRB routines.

3-52 CALFIP-LOKFQ

3.5.12

OPNFQ (Open a File/Device on a Channel)
Form
MOVB

#OPNFQ,FIRQB+FQFUN

(Set parameters appropriate to file or device)

CALFIP

Function
The OPNFQ function has the same effect as an OPEN FOR INPUT statement
in BASIC-PLUS; it opens a device or existing file on a channel. Parameters
defining the device, file name and type, protection code, and mode are passed to
the monitor in the FIRQB. If a file name is given in the FIRQB, a file-structured
open for input is performed. If no file name is given, a non-file-structured open
for input is performed. The RSTS / E Programming Manual describes file- and
non-file-structured OPEN FOR INPUT statement and the actions taken for the
mode parameter (MODE modifier in BASIC-PLUS) for each device.
If the device being opened is an outbound LAT keyboard, OPNFQ initiates a
connection to the terminal server if no such connection already exists.
NOTE

Privileges are required to open a disk for non-file-structured processing.
Whenever you use a disk as a non-file structured device, be aware that
all RSTSIE data structures you access are subject to change at any
time. The same applies if you open a UFD as a file.

Privileges Required
No privileges are required to open the caller's UFD for read-only access.
Privileges are needed to perform the following:
"

GREAD to open the UFD of any other account in the caller's group for
read-only access

•

WREAD to open the UFD of any account outside the caller's group for readonly access

•

DEVICE to open a restricted device

Read access (protection code, GREAD, or WREAD) to open a disk file for
read-only access

Write access (protection code, GWRITE, WWRITE, and/or SYSIO) to open a
disk file for write access

EXQTA to specify detach on close option on a pseudo keyboard

TUNE to select data caching mode on open

•

RDNFS to gain non-file-structured read access to a disk

SYSMOD to gain non-file-structured write access to a mounted disk

WRTNFS to gain non-file-structured write access to a disk, or to gain write
access to a UFD

CAlFIP-OPNFQ 3-53

Data Passed
FiR08
Mnemonic

Octal
Offset

Octal
Offset
I I I I I I I I I I I II I I I I I I I I

FOFUN

Mnemonic

OPNFO (= 2)

1111111111

channel number· 2

FOFIL

project number

programmer number

FOPPN
FONAM1

file name in RAD50 format

(2 words)

file type in RAD50 format (1 word)

FOEXT

receive buffer size for DMC11/DMR11

FOSIZ

I I I II I I I I I I II I I I I I I I I

mode

I I I II I I I I I I II I I I I I II I

I I I I I I I I I I I II I I I I I I I I

device name (2 ASCII characters)

FODEV

FODEVN
FOCLUS

<>0, unit no. real

no. rec. bfrs. to allocate for DMC11/DMR11

I I I II I I I I I I II I I I I I II I

device unit number

FOMODE

FIRQB+FQFUN

The function code OPNFQ (octal value = 2).

FIRQB+FQFIL

Channel number times two; defines the channel on which the file
is to be opened.

FIRQB+FQPPN

The PPN of the file to be opened. The project number is in the
high byte (FQPPN+l), and the programmer number in the low
byte (FQPPN). A value of zero defaults to the PPN under which
the calling program is running. (Zero for non-file-structured open.)

FIRQB+FQNAMI

The file name to be opened; two words of RAD50 data. May also
be specified as a zero word followed by the file identification index
(see LOKFQ). (Must be two zero words for a non-file-structured
open.)

FIRQB+FQEXT

The file type; one word of RAD50 data. (Must be zero for a
non-file-structured open.)

FIRQB+FQSIZ

This parameter has the same function as the FILE SIZE option
in BASIC-PLUS. It is only used for the DMCllIDMR11, where it
specifies the receive buffer size. You can specify a value between 1
and 632 (1170 octal). See the RSTS / E Programming Manual for
more information.

FIRQB+FQMODE

The mode with which the file is to be opened; values and actions
taken are as described for the MODE modifier in OPEN FOR
INPUT and non-file-structured OPEN statements for various
devices, as described in the RSTS / E Programming Manual. If
you use a mode value at all, you must set bit 15 of this word to 1.

3-54 CALFIP-OPNFQ

FIRQB+FQDEV

The device name is passed here as two ASCII characters. A value
of zero indicates "SY", public disk.

FIRQB+FQDEVN

The device unit number is passed here in binary. A nonzero value
in the high byte ofthis word (FIRQB+FQDEVN+1) indicates an
explicit device unit number. A zero value in FIRQB+FQDEVN+1
indicates no unit number.

FIRQB+FQCLUS

This parameter has the same function as the CLUSTERSIZE
option in BASIC-PLUS. For OPNFQ, it is used only for the
DMCllIDMRll, where it specifies the number of receive buffers
to allocate. You can specify a value between 1 and 127, but values greater than four are not recommended. See the RSTS / E
Programming Manual for more information.

Data Returned
FIRQB
Mnemonic

Octal
Offset

Octal
Offset
/11//////11/////11///

FQSIZM

Mnemonic

11111/1//1

current job no .• 2

FQJOB

MSB of file size

channel no .• 2

FQFIL

project number

programmer number

FQPPN
FQNAM1

file name in RAD50 format

(2 words)

file type in RAD50 format (1 word)

FQEXT

LSB of file size

FQSIZ

reasonable buffer size for device

FQBUFL

(as passed)

FQMODE

device description

FQFLAG

FQPFLG

FQPROT 27

protection code

clustersize, mod256

device name (2 ASCII characters)

FQDEV

flag byte

FQDEVN

device unit number

file identification index

FQCLUS

/ II / / / / / / II / / / / / II / / /

FQNENT

NOTE

For nondisk devices, the relevant information returned with the
OPNFQ subfunction is in the two words at FIRQB+FQBUFL and
FIRQB+FQFLAG. All other words are returned as passed.
FIRQB+FQJOB

The current job number times two.

FIRQB+FQFIL

Channel number times two; defines the channel on which the file
is open.

CALFIP-OPNFQ 3-55

FIRQB+FQSIZM

For large disk files (greater than 65,535 blocks), this byte contains
the MSB of the file's size in 512-byte blocks. This byte is combined
with the word at FIRQB+FQSIZ to form a 24-bit field giving the
file size.

FIRQB+FQPPN

The PPN under which the file is open. An actual PPN is returned
here even if this word was passed as zero.

FIRQB+FQNAM1

The file name; two words ofRAD50 data.

FIRQB+FQEXT

The file type; one word of RAD50 data.

FIRQB+FQBUFL

Reasonable buffer size for this device, in bytes. If you are doing
device-independent 1/0 (that is, if you do not want to keep track
of which device is being opened and perform specific opens, reads,
and writes, depending on the device), this value is the monitor's
best guess for a buffer size to use in subsequent reads and writes
on the opened channel. (See the .READ and .WRITE directives.)

FIRQB+FQFLAG

Description of the device just opened. The low byte contains the
device's handler index. There is one unique handler index for all
device types. The high byte contains a set of status flags to allow
for device-independent I/O routines.

DDNFS
DDRLO
DDWLO
FLGPOS
FLGMODI
FLGFRC

FL:itr !1
15 14

13 12

11 10

device-type flags

device handler index

High Byte - Device-Type Flags
The bits in the high byte of the flags word are set to indicate the type of file or device just
opened.
FLGRND
FLGKB

FLGFRC

3-56 CALFIP-OPNFQ

The device or file is random-access.

The device or file is sequential.

The file or device is a terminal-type file or
device (or is generically a terminal).

The file or device is not a terminal-type file or
device.

The file or device is byte-oriented. That is,
the .READ and .WRITE directives handle
data in byte units.

The file or device is block-oriented. The
.READ and .WRITE directives handle data in
block units.

FLGMOD

FLGPOS

DDWLO

DDRLO

DDNFS

The file or device accepts modifiers in .READ
and .WRITE directives.

The file or device does not accept modifiers in
.READ and .WRITE directives.

The file or device does not keep track of its
horizontal position.

The file or device has been write-locked (with
the protection code or mode value in the open)
or is generically a read-only device.

The file or device is not write-locked.

The file or device has been read-locked (with
the protection code in the open) or is generically a write-only device.

The file or device is not read-locked.

The file or device is non-file-structured (or is
generically not a file-structured device).

The file or device is file-structured.

Low Byte - Device Handler Index
Bits 0-7 of the flags word contain a handler index that indicates the generic kind of device.
The currently defined values follow.

Octal
Value

Symbol

Meaning

DSKHND

All disks

TTYHND

All terminals

DTAHND

DECtape

LPTHND

All line printers

PTRHND

Paper tape reader

PTPHND

Paper tape punch

CDRHND

Card reader

MTAHND

Magnetic tape

PKBHND

Pseudo keyboards

RXDHND

Flexible diskettes

RJEHND

2780 remote job entry

NULHND

The null device

DMCHND

The DMCIl1DMRll DDCMP interface

36
40

(

Reserved
KMCHND

KMCll

IBMHND

IBM interconnect

DMPHND

DMPlllDMVll device

ETHHND

Ethernet device

CALFIP-OPNFQ 3-57

FIRQB+FQPFLG

The file cluster size, modulo 256. That is, a file cluster size of 256
is indicated a zero.

FIRQB+FQPROT

The protection code of the file.

FIRQB+FQDEV

The device name; two ASCII characters. (For disk, the actual
device name is returned, even if a zero word was passed in this
word.)

FIRQB+FQDEVN

The device unit number. (For disk devices, the actual unit number
is returned here, even ifFIRQB+FQDEVN+l was passed as zero.)

FIRQB+33

For a file-structured open, this byte contains two relevant bits:
Bit 0 =0
The device is in the public structure
Bit 0 =1

The device is a private disk

Bit 1 =0

A specific device was not specified

A specific device was specified
Bit 1 = 1
These bits are meaningless for a non-file-structured open.
The file identification index of this file. This word is significant
mainly in that it can be used in place of the file name in subsequent opens of the file on disk. You can open the file with the
OPNFQ subfunction by using an explicit PPN in FIRQB+FQPPN,
a zero word in FIRQB+FQNAM1, and the file identification index
in FIRQB+FQNAM1+2.
Note that there is no performance gain in using the file identification index instead of the file name. The file identification index is
provided for compatibility with RSX. Furthermore, the file identification index is changed when the REORDR utility is run on the
directory (see the RSTS/E System Manager's Guide).

FIRQB+FQCLUS

Errors
NOBUFS

No buffers are available to initiate the connection to the terminal server.

NOTCLS

The specified channel is already open. It must be closed before it can be
opened again.

PRVIOL

You do not have the necessary privilege and you tried to:
•
•

xxxxx

Open a disk for non-file-structured access.
Open a device that the system manager has restricted to users with
DEVICE privilege.

All other possible errors are device-dependent. See Appendix A for a full list
of errors.

Example
The following MACRO code sets up the FIRQB for the OPNFQ function. A
non-file-structured open of magnetic tape unit 2 is done on channel 3:
MAG:

.ASCII

/MT/

CALL
MOVB
MOVB
MOV
MOVB
MOVB
CALFIP

CLRFQB
iOPNFQ,FIRQB+FQFUN
i3*2,FIRQB+FQFIL
MAG,FIRQB+FQDEV
i377,FIRQB+FQDEVN+l
i2,FIRQB+FQDEVN

;CLEAR FIRQB
;SET FUNCTION CODE
; SET CHANNEL = 3
; SET DEVICE = MT
;SET FLAG DEVICE NO. EXPLICIT
;SET DEVICE NO. = 2

See Programming Hints for information on the CLRFQB routine.

3-58 CALFIP-OPNFQ

3.5.13

RENFQ (Rename a File)
Form
MOVB

#RENFQ,FIRQB+FQFUN

(Define file to be renamed and new name in FIRQB)

CALFIP

Function

The RENFQ function renames an existing file on disk or DECtape and, if requested, deletes any existing file with the new name.
Privileges Required

DEVICE is required if the device is restricted. Create/rename access (GWRITE,
WWRITE, and/or SYSIO) to rename a disk file outside the caller's account.
SYSIO to set the privilege hit (bit 7 in FQPROT).
Data Passed
FIR08
Octal
Offset

Mne- Octal
monic Offset

FQFUN 3
5
7

11
13
15

17
21
23
25
FQPROT 27

I I I I I / I I I /I I I I I I I I I I I

RENFQ (~ 10)

/1///1///1

Mnemonic

I /I I I I I I I /I I I I I I II I I I

FQPPN

FQNAM1

project number

programmer number

file name
in RAD50 format
(2 words)
file type in RAD50 format (1 word)
-1 to delete existing file (disk only)
new file name
in RAD50 format
(2 words)
new file type in RAD50 format (1 word)
file protection

I
I

~ 0 if no change

12
14

FQEXT

FQSIZ

FQNAM2

22
24

FQFLAG

FQPFLG

device name (disk) (2 ASCII characters)

FQDEV

<>0, device no. real

FODEVN

device unit number

IIIIIIII IIIIIIIIIII I I

/I /I /I I I I /I I I I I /I /I I I

CALFIP-RENFQ 3-59

FIRQB+FQFUN

The function code RENFQ (octal value = 10).

FIRQB+FQPPN

The PPN of the existing file to be renamed. The project number is
in the high byte (FIRQB+FQPPN+1), and the programmer number
is in the low byte (FIRQB+FQPPN). A value of zero defaults to the
PPN under which the calling program is running.

FIRQB+FQNAM1

The old (existing) name for the file; two words of RAD50 data.

FIRQB+FQEXT

The old (existing) type for the file; one word of RAD50 data.

FIRQB+FQSIZ

This word is set to -1 to indicate that any existing file on the
specified device with the new name is to be deleted. If any other
value is given here and a file already exists with the new name,
the RENFQ function will return an error.

FIRQB+FQNAM2

The new file name and type; three words of RAD50 data. You
can use RENFQ to change the protection code on a file by setting
FQPROT and making these three words the same as the three
words beginning at FIRQB+FQNAMl.

FIRQB+FQPROT

The new protection code for the file, if any, is specified in
this byte. To retain the old protection code, this entire word
(FIRQB+FQPFLG and FIRQB+FQPROT) must be zero. If the
word is nonzero, the high byte will be used as the new protection
code.

FIRQB+FQDEV

The device name is passed here as two ASCII characters. It
must be a disk or DECtape device. A value of zero in this word
indicates the public disk structure CSY:).

FIRQB+FQDEVN

The device unit number is passed here in binary. A nonzero value
in FIRQB+FQDEVN+1 indicates an explicit device unit number.
A zero value in FIRQB+FQDEVN+1 indicates the system default.

Data Returned

Other than a possible error in byte 0 of the FIRQB, the RENFQ function of
CALFIP does not return any meaningful data.
Errors
FIEXST

The new file name specified already exists.

NOSUCH

The old file specified cannot be found.

Example

The following code renames the file OLDNAM.TXT to NEWNAM. TXT on the
public disk structure under the caller's account. FQSIZ is set to -1, so any
existing file named NEWNAM.TXT is deleted:
CALL
MOVB
MOV
r.lOV
MOV
MOV
MOV
MOV
MOV
CALFIP

CLRFQB
#RENFQ,FIRQB+FQFUN
#AROLD,FIRQB+FQNAMl
#ARNAM,FIRQB+FQNAM1+2
#ARTXT,FIRQB+FQEXT
#-l,FIRQB+FQSIZ
#ARNEW,FIRQB+FQNAM2
#ARNAM,FIRQB+FQNAM2+2
#ARTXT,FIRQB+FQNAM2+4

;CLEAR FIRQB
;SET FUNCTION CODE
;SET OLD FILE NAME
;AND TYPE
;TO "OLDNAM.TXT"
;DELETE EXISTING FILE
;SET NEW FILE NAME
;AND TYPE
;TO "NEWNAM. TXT"

See Programming Hints for information about the CLRFQB routine.

3-60

CALFIP-RENFQ

3.5.14

RSTFQ (Reset a Channel)
Form
MOVE

#RSTFQ,FIRQB+FQFUN

(Define channel to be reset)

CALFIP

Function

The RSTFQ function closes a channel, all channels, or all channels except one
without performing any of the normal clean-up operations. For example, no
trailer tape is written to paper tape punch; no form feed is given on the line
printer; and no trailer labels are written to magnetic tape. This function is useful
as a backup to a normal close operation. If a normal close fails, RSTFQ will close
the channel regardless. You can also use RSTFQ to closes a channel on which a
tentative file is open if you do not want to make the file permanent. The RSTFQ
directive functions the same as a CLOSE statement with a negative channel
number in BASIC-PLUS. See theRSTS/E Programming Manual for description
of tentative files.
Privileges Required

None

CALFIP-RSTFQ 3-61

Data Passed
FIRQB
Mne- Octal
monic Offset

Octal
Offset

111111111111111111111

Mnemonic

FQFUN 3

RSTFQ (= 20)

1111111111

channel number' 2

111111111111111111111

1IIIIIIIilllllllllill

FQFIL

FIRQB+FQFUN

The function code RSTFQ (octal value =20).

FIRQB+FQFIL

The value is set as follows:
•
•
•

To reset one channel, set FIRQB+FQFIL to the channel
number to reset times two
To reset all channels, set FIRQB+FQFIL to zero
To reset all but one channel, set FIRQB+FQFIL to -(channel
number times two); that is, the negative of two times the
channel number to remain open

Data Returned
The RSTFQ function does not return any meaningful data.

Errors
No errors are possible with the RSTFQ function. If the channel or channels
specified are not open, the call simply returns without error.

Example
The following code resets all channels currently open for the job, except channel 2:
CALL
MOVB
MOVB
CALFIP

CLRFQB
#RSTFQ,FIRQB+FQFUN
#-4,FIRQB+FQFIL

;CLEAR FIRQB
;SET FUNCTION CODE
;RESET ALL CHANNELS BUT 2

See Programming Hints for information about the CLRFQB routine.

3-62 CALFIP-RSTFQ

3.5.15

UUOFQ (Hook to File Processor)
Form
MOVE

#UUOFQ,FIRQB+FQFUN

(Set up FIRQB for UUOFQ subfunction)

CALFIP

Function
The UUOFQ subfunction of CALFIP performs the same operations as the .UUO
directive. The same subfunctions are available, and a similar format is used
for the data passed. The data returned is in the same format as for the .UUO
directive.
The data passed for the UUOFQ subfunction of CALFIP is moved down one byte
from the .UUO subfunction format. The value UUOFQ is stored in byte 3 in the
FIRQB, the UU.xxx code is stored in byte 4 in the FIRQB, whatever is shown in
byte 4 for .UUO is stored in byte 5 for UUOFQ, and so forth.
The UUOFQ subfunction of CALFIP is not recommended (although it does work),
because values that are normally set up as whole words must be stored as a
high-byte in location n and a low-byte in location n+1.
For example:

.UUO form:

UUOFQ form:

~ n+1
Privileges Required
See the .UUO directive.

(

CALFIP-UUOFQ 3-63

3.6 .CCl -

Check String for CCl Command

Form

.CCL
Function

The .CCL directive asks the monitor to check a string (defined in the XRB) to
see if it is a valid Concise Command Language (CCL) command. If the string is
a valid CCL command, the monitor passes control to the appropriate run-time
system for that CCL (as defined by the system manager), using the equivalent of
a .RUN directive. If the directive is successful, control does not return in line.
Control passes to the run-time system at the location specified in the P.RUN word
in the pseudovector region (Chapter 2). Data in the job's CORCMN, XRB, FIRQB,
and KEY areas in the low segment are passed to the run-time system because
they are of interest to the run-time system being entered as a result of a .CCL,
not to the caller. The file containing the program to be run as a result of the .CCL
command is opened on channel 15. See Chapter 2 for a description of these areas
in the P.RUN word.
If the string is not a valid CCL command, the monitor returns control to the
caller (the run-time system or user job image that issued the .CCL directive) with
no error. Control resumes with the instruction following the .CCL. Since control
would not be returned here otherwise, the program does whatever housekeeping
it deems necessary here for an unsuccessful CCL.
The system manager defines the CCL command, an abbreviation point, the name
of the file that is to be executed when the command is given, and an entry point
for the program (see the RSTS / E System Manager's Guide).
The command can be a string from one to nine characters long. The allowed
single-character commands are A through Z, @, $, and #. Commands that are
longer than one character must begin with a letter; the remaining characters can
be letters or digits.
The abbreviation point defines how many characters must be specified before
the command is accepted as valid. For example, if "DIRECTORY" were defined
as a CCL command, the system manager could indicate three characters as the
abbreviation point for the command. Then DIR, DIRE, DIREC and so forth, up
to the full DIRECTORY, would all be interpreted by the monitor as correct CCL
commands. (The monitor always fills in the full CCL command in CORCMN
when it passes control to the appropriate run-time system.) When you issue a
.CCL directive, the monitor compares the indicated string with the commands
defined by the system manager:

3-64 .CCl

•

All null (ASCII code 000) and delete (ASCII code 177) characters are ignored
and are never passed on to the run-time system in CORCMN.

•

ASCII code 200 is ignored and is never passed on to the run-time system in
CORCMN.

•

Leading spaces (ASCII code 040) and tabs (ASCII code 011) are ignored and
are never passed on to the run-time system in CORCMN.

•

When not enclosed by the quote characters " (ASCII code 042) and ' (ASCII
code 047):
All tabs (ASCII code 011) are changed to spaces (ASCII code 040).
All control characters (ASCII codes 001 through 037, inclusive, and
ASCII codes 201 through 237, inclusive) are ignored and never passed in
CORCMN.
Adjacent spaces (ASCII code 040) are merged into a single space.
All lowercase alphabetics (ASCII codes 141 through 172, inclusive, and
ASCII codes 341 through 376, inclusive) are changed into their uppercase
equivalents (ASCII codes 101 through 132, inclusive, and ASCII codes 301
through 336, inclusive).

•

When enclosed by the quote characters " (ASCII code 042) and' (ASCII code
047), all characters are kept as is and passed on to the run-time system in
CORCMN.

Immediately following the CCL command text (for example, DIRlSI:nJDET) the
monitor also analyzes two switches. These switches are passed on to the run-time
system as status flags set in the XRB (see the P.RUN description in Chapter 2).
The two switches may appear in either order, but must immediately follow the
command. Both are optional switches.
The ISIZE switch has the format:
[space] lSI [Z [E]] : [+] [#] n[.]

where n indicates the size, in K words, of the user job image that the program,
when executed, will require. If the + sign is given, n indicates the additional
amount of space, in K words, that the file will require over that indicated by the
computed size or minimum size (see the description of the PF.CSZ bit in P.FLAGS
word, Chapter 2). If the + sign is omitted, then n simply indicates the size, in K
words, at which the invoked file should run. If the # sign is given, n is assumed to
be octal. If the period (.) is given, n is assumed to be decimal. If both are given,
an error is returned, and if neither is given, n is assumed to be decimal. The
value of n must be between 1 and the system-wide maximum for a user job image
(see the SWAP MAX discussion in the RSTS / E System Installation and Update
Guide). If you run the program with separate D-Space, /SIZE only increases the
D-Space. Otherwise, it increases the overall program size.
The !DETACH switch has the format:
[space]/DET[A[C[H]]J

This switch indicates that the invoked program should be run detached. In this
state, channel 0 (the terminal associated with the job) is marked as detached
while the program is running. This switch is useful for noninteractive programs;
it frees the terminal for other use and prevents the user from interrupting the job
by entering a CtrllC.
Remember that the monitor simply examines these switches and passes the
information on to the run-time system. The run-time system is responsible for
doing the appropriate processing. For more information on the CCL facility, see
the RSTS / E Programming Manual.
NOTE

Do not use this directive from a user job image running under the
RT-ll run-time system, since the lowest 512. bytes are used by RT-ll
differently from other run-time systems. Instead, use .DOCCL (see
Chapter 7).
.CCl

3-65

Privileges Required

Execute access (by protection code, GREAD, or WREAD) is needed to execute a
program for a CCL command.
Data Passed
XRB
Octal MneOffset monic

Mne- Octal
monic Offset

length of proposed command string. bytes

o XRLEN

length of proposed command string. bytes

2 XRBC

starting address of command string

4 XRLOC

/ /1/ / / / / / / / / / / / / /I / / /

10 XRBLK

11
13
15

(passed to
new run-time system
unaltered)

12
14

XRB+XRLEN

The length of the proposed CCL command string, in bytes.

XRB+XRBC

The length of the proposed CCL command string, in bytes, is also
passed in this word.

XRB+XRLOC

The starting address of the proposed CCL command string. (See
the section "XRB (Transfer Request Block)" in Chapter 2 for more
information.)

XRB+XRBLK

The remaining three words are unaltered here if the string is
indeed a CCL command and the monitor takes over and does the
equivalent of a .RUN directive. That is, the run-time system that
is given control as a result of this command finds the same three
words here that the caller left. These three words are also be
unchanged if control returns back to the caller for any reason. See
the .RUN monitor call in this Chapter and the P.RUN entry point
in Chapter 2 for details.

Data Returned

No useful data is returned to the calling program. (The P.RUN description
describes the data passed to the run-time system if the call is successful.) If the
call is unsuccessful, the last three words of the XRB are unaltered, but the first
four words are random. In addition, an error code is returned in the first byte of
the FIRQB.

3-66

.CCl

Errors
(none)

No error is returned if the command part of the string passed was not a
valid CCL command. The contents of CORCMN have not been altered; the
XRB (except for the last three words) has been altered.

BADCNT

The first three words of the XRB, which describe the CCL command string,
are illegal.

BADSWT

An illegal switch was given in the CCL command string.

BDNERR

An illegal number was the argument to one of the switches found in the
CCL command string. For example, the n value in the /SIZE switch was
greater than the system-wide maximum for a user job image (see the SWAP
MAX discussion in the RSTSjE System Installation and Update Guide).

LINERR

The indicated string is too long to be passed in CORCMN.

xxxxxx

Any other error returned results from the monitor's execution of a .RUN
directive for the program. See the .RUN directive in this chapter.

Example

The following example asks the monitor to check a 72-byte string beginning at
location BUFFER to see if it is a CCL command:
BUFFER:

. BLKB

72 .

CALL
MOV
MOV
MOV
.CCL

CLRXRB
#72., XRB+XRLEN
#72. ,XRB+XRBC
#BUFFER,XRB+XRLOC

Clear XRB
Set length
Set length again
Set starting address

See the section entitled "Programming Hints" for infonnation on the CLRXRB
routine.

.CCl

3-67

3.7 .CHAIN - Execute Under Same RTS
Form
.CHAIN
Function
The .CHAIN directive is the same as the .RUN directive, except that it returns an
error if the program to be run would cause a new run-time system to be entered.
That is, if the call succeeds, the current run-time system is entered at the P.RUN
entry point (see Chapter 2). In addition, there is no change in the user job image
size. Otherwise, the error code NORTS is returned in byte 0 of the FIRQB.
Use this call to bypass the special protection afforded by the compiled-file bit
in the protection code. The run-time system can use this directive to access
an executable file without the problem of possibly losing control (unlike .RUN,
which can transfer control to a different run-time system). The .CHAIN directive
reenters the run-time system so a user cannot take control of the file once it is
open on channel 15.
See the .RUN directive, for Data Passed, Data Returned, and Errors. For the
example, substitute .CHAIN for .RUN.
NOTE

Do not use this directive from a user job image running under the
RT-ll run-time system. Use the RT-ll .CHAIN directive (see Chapter
7) to transfer control to another program running under RT-ll.
Privileges Required

Execute access (by protection code, GREAD, or WREAD) is required to execute a
program.

3-68 .CHAIN

3.8 .CLEAR -

Clear Keyword Bits

Form

.CLEAR
Function

Use the .CLEAR directive to clear certain bits in the keyword (KEY) location in
the user job image. The XRB passes the bits to be cleared to the monitor.
Privileges Required

None
Data Passed
XRB
Octal MneOffset monic

Mne- Octal
monic Offset

o XRLEN

bits to be cleared are set to 1 here

111111111111111111111

1111111/11/1111/11111

1111111/1/111//11/111

111111/11/1111/1/1//1

1IIItllllllllllllllll

1111111111111/1111111

The bits to be cleared are set to 1 here.

XRB+XRLEN

JFSPRI
JFFPP
JFPRIV

JDFSTM

JFSYS]

JFNOPR

JFL~6~~~
15

JFLOCK

Clearable by any caller. Clearing JFLOCK indicates that the job wants to
be swapped. When JFLOCK is clear, the monitor swaps the job (that is,
the user job image) to and from disk as necessary.

JFBIG

Not clearable by any caller; masked off. That is, the corresponding bits in
KEY cannot be cleared by the job with the .CLEAR directive.

JFNOPR

Not clearable by any caller; masked off.

JFSYS

Clearable by any caller. If the job has temporary privileges and this bit is
cleared in a .CLEAR call, the temporary privileges are temporarily lost.

.CLEAR

3-69

JFPRIV

If a .CLEAR directive is issued with this bit indicated for clearing, any
temporary privileges that the job has or had are permanently lost.

JFFPP

Clearable by any caller. Clearing JFFPP indicates that this job no longer
wants the state of the hardware floating-point unit (if any) to be swapped
along with the job's normal context information.

JFSPRI

Clearable by any caller. Clearing JFSPRI lowers the job's run priority by
one-half step. That is, it clears bit 2 of the system- controlled low-order
three bits of the run priority. See the SET JOB command RSTS / E System
Manager's Guide.

JDFSTM

Clearable by any caller. Deactivates the fast-map facility and restores
normal lOT trapping. If you leave this bit set, clear all the others.

All other bits in the XRB are masked off.
Data Returned

The .CLEAR directive does not return any meaningful data.
Errors
No errors are possible with the .CLEAR directive.
Example

The following code clears the JFLOCK bit:
CALL
MOV
. CLEAR

CLRXRB
#JFLOCK,XRB+XRLEN

;CLEAR XRB
;SET JFLOCK FOR CLEAR

See Programming Hints for information on the CLRXRB routine.

3-70

.CLEAR

3.9 .CMDlN-Read/Write Command Line
Form
.CMDLN

Function
The .CMDLN directive lets programs pass up to lK words of data (2048 characters) when chaining to another program. DCL uses this capability to pass long
command lines to some server programs. If possible, the .CMDLN directive stores
the data in core common. If not, it stores the data in XBUF.
NOTE

The read function deletes the command line after it has been read,
therefore the command line can only be read once.

Privileges Required
None

Data Passed (Write a Command Line)
XRB
Mne- Octa.!
monic Offset

Octal MneOffset monic
length of command line to write

o XRLEN

length of command line to write

2 XRBC

address of command line to write

4 XRLOC

I II I I II II I I I /I /I II /I I

I I I I I I I I II I I I I I I I I I I I

111111111111111111111

XRB+XRLEN

The length of the command line to be written, in bytes.

XRB+XRBC

The length of the command line to be written, in bytes.

XRB+XRLOC

The starting address of the command line to be written. (See the
section "XRB (Transfer Request Block)" in Chapter 2 for more information.)

Errors
BADCNT

XRB parameters were invalid, or the command line was too long.

NOBUFS

Not enough XBUF was available to store the command line.

.CMDLN

3-71

Data Passed (Read a Command Line)
XRB
Octal MneOffset monic

Mne- Octal
monic Offset
length of buffer to receive command line

o XRLEN

zero

2 XRBC

address to place command line

4 XRLOC

111111111111111111111

XRB+XRLEN

The length of the buffer to receive the command line, in bytes.

XRB+XRBC

Zero to indicate a read operation.

XRB+XRLOC

Starting address of the area where the command line is placed. (See
the section ''XRB (Transfer Request Block),' in Chapter 2 for more
information.}

Data Returned
XRB+XRBC

The length of the command line read, in bytes.

Errors

3-72

.CMDLN

NOSUCH

There was no command line to be read.

LINERR

The command line was too long for the user's buffer.

3.10 .CORE -

Change Memory Size

Form
.CORE

Function
The .CORE directive asks the monitor to change the amount of memory currently
allocated for the user job image (low segment) for this job. The monitor preallocates space for a user job image at the time a .RUN directive is issued. The
space is based on the size of the file (if PF.CSZ = 1 in the P.FLAG word of the
pseudovector region) or is equal to the P.MSIZ word in the pseudovector region.
NOTE

If the I&D Space split is enabled, .CORE alters only the size of the
D-Space.
You can change this initial size with the .CORE directive as many times as you
want, as long as the requested size falls within the minimum and maximum
memory range for the current run-time system.
The monitor first checks the size requested against maximum and minimum
values, using this algorithm:
lKword <

P.MSIZ

size requested <
with .CORE

private ~
maximum
for job

P.SIZE

system
maximum

The monitor determines the maximum allowable amount of space for a user job
image as follows:
•

Set <max> (the maximum size that a job image can be) to the system-wide
maximum. This maximum is set by the system manager at startup time (see
the SWAP MAX discussion in the RSTS / E System Installation and Update
Guide).

•

If the maximum user job image size imposed by the run-time system (P.SIZE

in the pseudovectors) is less than the current <max>, set <max> to P.SIZE.
•

If the job's private memory maximum is less than <max> and if the caller

does not have EXQTA privilege, then set <max> to the job's private memory
maximum. The system manager can set a particular job's private memory
maximum with the SET JOB/SIZE=n command. You can also set a private
memory maximum with the UU.PRI subfunction of the .UUO directive (in
this chapter). Ajob's private memory maximum is initially defaulted to the
system maximum.
•

The size of I-Space and the size of D-Space can not exceed 32K words each.

Thus, the size requested with .CORE is checked against <max>, as determined by
the four previous steps. The size requested with .CORE is also checked against a
minimum (the P.MSIZ word in the pseudo vectors, which must be greater than or
equal to lK words). Any size between P.MSIZ and <max>, inclusive, is legal.

.CORE 3-73

There are two special cases:
•

If the size requested with .CORE is exactly equal to the run-time system's
minimum size (P.MSIZ), that request is considered legal even if the requested
size is greater than the job's private maximum.

•

If the size requested with .CORE is less than the job image's current size and

within the allowable bounds for the run-time system, but it is still larger than
the private maximum, that request is considered legal. This could happen
if the caller had EXQTA privilege, allowing the current size to be greater
than the private maximum, and then dropped EXQTA privilege. The monitor
would still allow the size greater than the private maximum.
If .CORE requests a decrease in job image size, no further checks are made.
If .CORE requests an expansion and the size is legal according to the cases

previously described, the monitor then determines if the expansion overlaps any
windows created by CRAFQ or CRAW$. If there are no overlaps, .CORE proceeds.
If there is an overlap, the monitor rejects the .CORE expansion under any of the
following conditions:
•

If separate 1- and D-Space hardware does not exist.

•

If the APR mask value in XRB+XRBC is zero.

•

If the overlapped window was created in D-Space (WS.UDS bit is set).

Mapping a dynamic region can produce this.
•

If the expansion would use an APR marked for protection by the APR mask

in XRB+XRBC.
The APR mask tells the monitor how to handle the D-Space mapping when using
concurrent APR windows. The possible options are:
Mask
Value

3-74 .CORE

Meaning

Concurrent window usage is not allowed. The monitor rejects .CORE with
an error if it finds any overlap with a created window. The RSTSIE RSX
emulator handles the EXTK$ directive in the same way. This insures that
all I-Space libraries in use also have D-Space as well.

Concurrent window usage is allowed and all libraries in use are presumed
to be I-only code and all D-Space is available for the task. The RSX-lllMPLUS native operating system handles the EXTK$ directive in the same
way.

Mask
Value

l+n

Meaning
The value n is the inclusive OR of values representing the D-Space APRs
being protected. If an APR is protected, it means the D-Space for that
APR remains mapped along with the I-Space window at the same APR.
If the .CORE expansion also requires this APR, the request is rejected
with an error. This is the equivalent of the EXTM$ directive under both
RSX-111M:-PLUS and the RSTSIE RSX emulator. Bit 0 must be set.
Value

D-Space APR Protected

None, a118 APRs are available for task data

APR 1 and above protected

APR 2 and above protected

APR 3 and above protected

APR 4 and above protected

APR 5 and above protected

101
201

APR 6 and above protected
APR 7 and above protected

This mask should be treated as a fence; that is, the lowest bit (other than
bit 0) determines the protection. (41 and 341 are equivalent and protect in
APRs 5,6 and 7.)
This mask passes the information to the monitor at execution time about the
D-Space requirements for the libraries associated with this job, accumulated
by the Task Builder. The Task Builder, if requested, passes this mask in
a location called $$TSKP. See the RSTS / E Task Builder Manual for more
details.

If .CORE requests a legal expansion that cannot be made in place, that is, if there

is not enough free memory available for the expansion, the job is swapped out
and swapped back in at the larger size. (This swap occurs even when JFLOCK =
1 in the keyword (KEY).)
When a user job image expands, the content of the newly added memory is zeroed
as protection against a malicious user reading memory to look for passwords.
NOTE

Do not use this directive from a user job image running under the RT11 run-time system. Expanding memory size should be done through
the RT-11 emulator, using the appropriate RT-11 directive.
When the image runs under the RSX run-time system, use the EXTK$ or EXTM$
directive to extend the task size, so that subsequent GTSK$ directives can return
the task size correctly.

Privileges Required
EXQTA to exceed private memory maximum.

.CORE 3-75

Data Passed
XRB
Octal MneOffset moni'c

Mne- Octal
monic Offset

1&0 flag

desired size, K words

o XRLEN

1111111111

o or O-APR mask

2 XRBC

/ / / / / / 1/ / / / / / / / / / / / / /

/ / / / // 1/ / / / / / / / / / // / /

1111111/1111//1/1111/

//////1// III / / / / / / / / /

/ / // / / /I fill / / / / / / / / /

XRB+XRLEN

The desired size for the user job image, in K words.

XRB+XRLEN+1

If this byte contains a -1, the user is requesting that the I&D
APRs be split to map different physical memory. XRB+XRLEN
is the requested size of the D-Space. The I-Space size is fixed at
the job's current size. If this byte contains a -1 and XRB+XRLEN
contains a zero, the I&D split is disabled.

XRB+XRBC

Either zero or the D-Space APR mask. If the value is zero, .CORE
acts as the EXTK$ directive; otherwise, .CORE acts as the EXTM$
directive. See Chapter 5 for descriptions of these directives. If you
use the D-Space APR mask, the first bit must be set.

Data Returned
Other than a possible error in the byte 0 of the FIRQB, the .CORE directive does
not return any meaningful data.

Errors
BADFUO

The program is requesting that the I&D Space be split, but it cannot be split
or is already split.

EDBMCE

The requested user job image size is illegal. It is either too large or too
small, or it overlaps a mapped window.

ERRERR

The program is requesting use of separate I&D Space but the hardware does
not exist on this system.

INUSE

There is outstanding asynchronous 110 for this job.

Example
The following code requests a user job image of 24K words:
CALL
MOVB
• CORE

CLRXRB
i24.,XRB+XRLEN

;CLEAR THE XRB
;SET XRB TO INDICATE 24K WORDS

See the section "Programming Hints" for information on the CLRXRB routine.

3-76 .CORE

3,11

.DATE -

Return Current Date and Time

Form

.DATE
Function

The .DATE directive returns the current date and time, the current program
name (as installed by the .NAME directive), and the current run-time system
name in the XRB.
Privileges Required

None
Data Passed

The .DATE directive does not pass any meaningful data.
Data Returned
XRB
Mnemonic

Octal
Offset

5
7

11
13

Octal
Offset

Mnemonic

current date, in system internallormat

XRlEN

minutes until midnight

XRBC

XRlOC

XRCI

ticks until second

seconds until minute

program name in RAD50 format
(2 words)
(as installed with .NAME)
run-time system name in RAD50 format
(2 words)

XRB+XRLEN

10
12

XRTIME

The current date, in system internal format. The monitor calculates the date as:

[(year - 1970) * 1000.] + day-within-year
where day-within-year is 1 for January 1, 2 for January 2, and so
forth. (Every leap year, the day-within-year value for March 1 and
following is one higher than in other years.)

XRB+XRBC

The number of minutes until midnight. A value of 1440 is midnight; 720 is noon; 0 is never returned.

XRB+XRLOC

The number of seconds until the next minute. A value of 60 is
xx:xx:OO; 1 is xx:xx:59; 0 is never returned.
The number of ticks until the next second. A tick is either 1I60th
or 1/50th of a second, depending on the clock in use and/or the
line frequency. (Systems running with the KWllP clock at crystal
speeds, rather than at line frequency, or systems running the
11/73, 11/83, 11/84, 11/93, or 11/94800 Hertz clock, have a tick of
1/50th of a second. Otherwise, if the system is operating with a 60
Hz power line, a tick is 1I60th of a second.)

.DATE

3-77

The current program name (as set by the most recent .NAME
directive); two words in RAD50 format.
XRB+XRTIME

The current run-time system name; two words in RAD50 format.

Errors
No errors are possible with the .DATE monitor call.
Example

Since no data is passed to the monitor, the call is:
.DATE

3-78

.DATE

3.12 .ERLOG -

log an Error from RTS

Form

.ERLOG

Function
You can issue the .ERLOG directive only from the high segment (run-time system). It allows the run-time system to log an error into the RSTS/E error log
file, which can then be printed by the system manager (see the RSTS / E System
Manager's Guide). For example, you might want to place an entry into the
RSTS/E error logging scheme on a hardware floating-point unit exception that
has an illegal error code because the monitor makes no such checks.
You can issue this directive only from the job's current run-time system (high
segment). Since this call does not require privilege, the monitor does not let users
fill up the system error log with unimportant errors. If .ERLOG is issued from
the user job image (low segment), RSTSIE ignores it.
Privileges Required

None
Data Passed

The .ERLOG directive records in the system error log file the contents of the
program counter (PC) and program status word (PS) at the time of the call, as
well as the contents of the general registers (RO through R5). These registers will
then be displayed at the system manager's request. Hence, the registers should
contain whatever information you want to record when the .ERLOG is executed.
Data Returned

The .ERLOG directive does not return any meaningful data.
Errors

No error is possible with .ERLOG.
Example
If the general registers contain relevant information, the call is:

.ERLOG

3-79

3.13 .EXIT -

Exit to Default Keyboard Monitor

Form

.EXIT
Function

The .EXIT directive returns control to the system default keyboard monitor (DCL)
at the P.NEW entry point (see Chapter 2). When a program exits, it normally
passes control to the job's keyboard monitor with the .RTS directive. You can use
the .EXIT call as a backup to return control to the default keyboard monitor if the
.RTS fails, or for any other reason when you want to enter the default keyboard
monitor at the entry point specified by P.NEW. The .EXIT directive needs no
arguments and never returns in line to the caller.
Privileges Required

None
Data Passed

The .EXIT directive needs no arguments; however, the three words beginning at
XRB+lO are passed unaltered to the default keyboard monitor. The monitor also
passes information to the default keyboard monitor when .EXIT is executed. See
the discussion of the P.NEW entry point in Chapter 2.
Data Returned

The .EXIT directive does not return any meaningful data; control never returns
in line.
Errors

No errors are possible with .EXIT.
Example

Since no data is passed or returned with .EXIT, the call is:
.EXIT
NOTE

Do not use this RSTS/E directive from a user job image running under
the RT-ll run-time system. The correct way to terminate such a
program is to exit to the RT-ll emulator, which then returns control to
the job's keyboard monitor.

3-80

.EXIT

3.14 .FSS -

Check File Specification String

Form
.FSS

Function
The .FSS directive examines a string of characters presumed to be a file specification and, if possible, converts it to the internal RSTS/E file specification format
(FIRQB format). The monitor returns information to the XRB describing what
it found in the string and returns the converted file specification to the FIRQB.
Thus, programs that manipulate files can use .FSS to translate a user-typed
string to the FIRQB format.
The monitor examines the string from left to right and stops without error when
it finds:
•

The end of the string.

•

An equal sign (=), which is ASCII code 075.

•

A semicolon (;), which is ASCII code 073.

•

A slash (/), which is ASCII code 057, that is followed by anything other than
the following switches, which the monitor translates to the FIRQB format:
/CL[USTERSIZE]:[-][#]n[.]
where n is the cluster size used in opening files and devices. The variable
n can specify a value ranging from -32768 through 32767.
/MO[DE]:[#]n[.]
where n is the mode used in opening files and devices. The variable n can
specify a value between 0 and 32767.
IFI[LESIZE]:[#]n[.] or /SI[ZE]:[#]n[.]
where n is the filesize used in opening files and devices. The value of
n defines the file's size in 512-byte blocks and can be in the range 0 to
8,388,607 blocks.
IPO[SITION]:n
where n is the position used in creating files (to position block 1 of the file
at a device cluster). The variable n can specify a value between -2 and
65,535.
IPR[OTECTION]:[#]n[.]
where n is the protection code used in opening or creating files. The variable n can specify a value between 0 and 255. The value of n determines
the file's protection from users; see the RSTS / E System User's Guide.
The brackets ([ ]) in the previous switches enclose optional characters. Where
more than one character is enclosed in brackets, any or all of the enclosed
characters can be omitted. For example, MO, MOD, and MODE would all be
accepted and the following quantity translated to the mode location in the
FIRQB.
The value n is assumed to be decimal, unless the optional pound sign [I]
appears, indicating that n is octal. The optional decimal point also indicates a
decimal value.

.FSS 3-81

•

A comma (,), which is ASCII code 054. An exception is the comma separating
the project and programmer numbers in a PPN.

The monitor translates the components in a file specification string as follows:
device name

A device name can be either a logical device name or a physical device
name:
logical
A logical device name is a string of alphanumeric
characters or dollar sign ($) or underscore L), terminated with a colon (:). The logical name can contain
the $ character anywhere except as the first character. Only the first 15 characters are examined;
the remainder are ignored. If the logical name does
not contain a $ character, the monitor checks the
name against the user's own logical device name
assignments in the extended logical portion of the job
header. If the monitor finds a definition, it returns
the physical device name associated with that logical
device name to the FIRQB. If the logical name is not
found in the user-logical area or if the logical name
contains a $ character, the monitor makes a search of
systemwide logical names. If the logical is not found
in the logical lists, the monitor searches the logical
table given in the XRB. If the logical name is not
found, the monitor returns the logical device name
and sets a flag in the XRB to indicate that it could
make no association. For a logical device name beginning with an underscore (J, the monitor does not
attempt any translation to a physical device name.
physical:

A physical device name consists of two alphabetic
characters optionally followed by digits and ended
with a colon (:). The digits are translated as decimal
and must have a value between 0 and 127 (decimal).
Leading zeros are allowed.
For some devices (for example, terminals) a physical
name can also be specified as a two-letter device
name, a one-letter controller identifier, and a number
specifying the unit on that controller. For example,
TTG2: is the third terminal on a DZU controller.

3-82

.FSS

account or PPN

A PPN can be expressed either as a single special character or as two
separate numbers enclosed in square brackets [] or parentheses ()
and separated by a comma.
The following special characters are translated as:
$
The dollar sign ($) is equivalent to [1,2].
The exclamation point (!) is equivalent to [1,3].
%

The percent sign (%) is equivalent to [1,4].

The ampersand (&) is equivalent to [1,5].

The number sign (#) is translated to the caller's group library.
It is always equivalent to [proj,O] where proj is the project
number of the user issuing the .FSS directive.

The at sign (@) is translated to the caller's assignable PPN,
the USRPPN value (see Chapter 2). If USRPPN is set, its
value is placed in the FIRQB at offset FQPPN. IfUSRPPN is
zero, a string with an @ causes an error.

NOTE

Digital does not recommend
the use of the special characters !, %, &, #, or @. They are
provided only for compatibility with pre-V9.0 releases of
RSTSIE.
[n,m]

This is the explicit construct for a PPN. The value n specifies
the project number, and m specifies the programmer number.
The variables nand m can specify any value from 0 through
254, except for [0,0]. If a number sign (#) precedes either n or
m, the string is assumed to specify an octal value. Either n
or m, or both, can also be the asterisk (*). The * is converted
to 255 and placed in its corresponding FIRQB location. The
asterisk character indicates a wildcard specification.
Either n or m, or both, can be omitted; in that case, the
monitor uses the corresponding part of the user's PPN. For
example, [,] or [] specifies the user's PPN; [,0] is equivalent to
#.

(n,m)

This is an alternate way to specify an explicit PPN. The
same rules for nand m apply as when they are enclosed by
brackets.

NOTE

Digital does not recommend
the use of parentheses in
the PPN specification. This
format is provided only for
compatibility with pre-V9.0
releases of RSTSIE.

.FSS 3-83

file name

A file name can consist of alphanumeric characters and the question
mark (?). It is the only field in the file specification with no explicit
delimiter. Only the first six characters are examined; the rest are
ignored. The asterisk character (*) is also an acceptable file name. It
is translated to two words of RAD50, where each RAD50 character
is the unused code (29). Each? character is also converted to this
unused code. This indicates that the file name field is a wildcard.
(The LOKFQ subfunction of CALFIP and UU.LOK subfunction of
.UUO can be used to look up wildcard files.) The asterisk can also
represent trailing question marks. *.FIL and A*.FIL are legal file
names; A*Z.FIL is illegal.

type

A file type can consist of alphanumeric characters and the? character, preceded by a. character. The * character is also an acceptable
file type. It is translated to one word of RAD50, where each RAD50
code is the unused code (29). Each? character in the file type is also
converted to this unused code. This indicates that the file type field,
or character in the file type field, is a wildcard. The asterisk can also
represent trailing question marks. FILE.* and FILE.A* are legal file
names; FILE. *Z is illegal.
If given, the file type must always follow the file name.

protection code

A file protection code can consist of numeric digits enclosed by angle
brackets <>. The general form of a protection code is <nnn>, where
n may be numeric characters indicating a value from 0 through 255.
If the numeric characters are preceded by a # character, they are
converted as specifying an octal value. Alternatively, the protection
code can be specified using the !PROTECTION switch. If no file
protection code is specified in the string and a default value has been
assigned in USRPRT (see Chapter 2), the default value is placed in
the FIRQB.

These special characters can appear in the string in any order, with the exception
of the file type and PPN. The file type must follow the file name, if specified.
In addition, if the device name is a system or user logical device name that has
an account (PPN) associated with it, the position of an explicit PPN in the file
specification string is significant. If the order is device:[PPN}, then the explicit
PPN overrides the PPN associated with the logical device name. If the order is
[PPN}device:, RSTS/E displays the error message ?Illegal device name.
NOTE

Do not use this directive from a user job image running under the RT11 run-time system, since the user logical area is not in the standard
location.

Privileges Required
None

3-84 .FSS

Data Passed
XRB
Mne- Octal
monic Offset

Octal
Offset

Mnemonic

length of the string, bytes

XRLEN

length of the string, bytes

XRBC

starting address of the string

XRLOC

/ / / / / 1/ / / / / / / 1/ 1/ / / / /

length of nonstandard user defaults

XRBLK

starting address of nonstandard users

XRTIME

/ / / / / 1/ / / / / / / 1/ I / I I I I

XRB+XRLEN

The length of the character string to be translated, in bytes.

XRB+XRBC

The length of the character string to be translated, in bytes.

XRB+XRLOC

The starting address of the string to be translated. {See the
section "XRB ('Iransfer Request Block)" in Chapter 2 for more
information.)

XRB+XRBLK

If the user logical information (USRPPN, USRPRT, and the
extended logical area of the job header) is in its standard location,
this word is passed as zero. If the user logical information is
in some nonstandard location, the beginning address goes here.
Digital does not support the nonstandard location and strongly
recommends you use only standard locations.

XRB+XRTIME

If the word at XRB+XRBLK is nonzero, then this word defines
the starting location for the user logical information. {The order
of the information is assumed to be the same as in its standard
location; that is, the user logical PPN, user logical protection code,
user logical device name table. The format is also expected to
be the same (see the descriptions of USRPPN, USRPRT, and the
USRLOG area in Chapter 2 for details).

Data Returned
XRB
Octal MneOffset monic

Mne- Octal
monic Offset
I / / / 1/ / / / / / / 1/ / / I / / 1/

number of untranslated characters in string

XRBC

address of first untranslated character

XRLOC

111/1///111/1/1/111//

flag word 2

XRBLK

flag word 1

XRTIME

device description

XRMOD

.FSS 3-85

XRB+XRBC

A count of the untranslated characters in the string. If all characters
were translated, the value of this word is zero.

XRB+XRLOC

The address of the first untranslated byte of the string. If
XRB+XRBC is zero, this word identifies the end of the string. (See
the section "XRB (Transfer Request Block)" in Chapter 2 for more
information.)

XRB+XRBLK

Bit flags describing the translated string. Note that this word is the
same as "flag word 2" for the BASIC-PLUS file name string scan SYS
call (see the RSTS / E Programming Manual).
Meaning
Bit
Setting
0

6
7

3-86 .FSS

Set

A file name was found in the source string; two
words in RAD50 format at FIRQB+FQNAMI.

Clear

No file name was found (and bits 1 and 2 of
this word are also 0).

Set

The translated file name consisted of a single *
character and has been translated to two words
at FIRQB+FQNAMI consisting of the RAD50
representation of the string "??????".

Clear

The translated file name was not an * character.

Set

The file name contained at least one? character.

Clear

The file name did not contain any? characters.

Set

A period (.) was found in the source string.

Clear

No period was found, implying that no file type
was specified (and bits 4, 5, and 6 of this word
are also 0).

Set

A file type was found; that is, the field after the
period was not null.

Clear

No file type was found (the field after the
period was null), and bits 5 and 6 of this word
are also O.

Set

The file type was an * character and is returned in the word at FIRQB+FQEXT as the
RAD50 representation of the string "???".

Clear

The file type was not an * character.

Set

The file type contained at least one? character.

Clear

The file type did not contain any? characters.

Set

A PPN was found in the source string.

Clear

No PPN was found (and bits 8 and 9 of this
word are also 0).

10
11

Set

The project number was an * character. That
is, the PPN was of the form [*,n].) RSTSIE
returns a value of 377 at FIRQB+FQPPN+1.

Clear

The project number was not. an * character.

Set

The programmer number was an * character.
That is, the PPN was of the form [n,*]. RSTSIE
returns a value of 377 at FIRQB+FQPPN.

Clear

The programmer number was not an * character.

Set

A valid protection code was found.

Clear

No protection code was found.

Set

No file protection code was found in the string,
but there was a default output file protection
code in location USRPRT. The default has been
returned in the FIRQB.

Clear

The user-assignable default protection code (at
location USRPRT) was not used. Either zero
or the protection code given in the string is
returned to the FIRQB.

Set

A colon (:), but not necessarily a device name,
was found in the source string.

Clear

No colon was found (no device was specified);
bits 13, 14, and 15 of this word are also O.

Set

A device name was found in the source string.

Clear

No device name was found; bits 14 and 15 of
this word are also O.

Set

The device name in the string was a logical
device name.

Clear

The device name in the string was an actual
device name; bit 15 of this word is also O.

Set

This bit. set indicates an invalid device name.
(The characters that were specified are simply
returned at FIRQB+FQDEV, FIRQB+FQDEVN,
and FIRQB+FQFLAG as three words in RAD50
format.) This bit can be set in one of two ways:

•
•

Clear

If the device name contained an underscore
but was not a recognizable device name for
any device on the system, this bit is set.
If the device name did not contain an
underscore but the name could not be
translated to a physical device name, this
bit is set.

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 has been returned
to the word at FIRQB+FQDEV as two ASCII
characters, and the unit information has been
returned appropriately at FIRQB+FQDEVN.

. FSS

3-87

XRB+XRTIME

Remaining bit flags describing what was translated. Some of these
bits duplicate information returned at XRB+XRBLK Digital recommends that you use the bits at XRB+XRBLK to allow for enhancements in future releases. Note that this word is the same as "flag
word 1" for the BASIC-PLUS file name string scan SYS call, see the
RSTS / E Programming Manual.
Bit
Setting
Meaning

o
1

Set

The /CLUSTERSIZE:n switch was specified.

Clear

The /CLUSTERSIZE:n switch was not specified.

Set

Either the /MODE:n or /RONLY switch was
specified.

Clear

Neither the /MODE:n nor the /RONLY switch
was specified.

Set

The IFILESIZE:n or /SIZE:n switch was specified.

Clear

Neither the IFILESIZE:n nor the /SIZE:n
switch was specified.

Set

The IPOSITION:n switch was specified.

Clear

No /POSITION:n switch was specified.
(Not currently used.)

4-7
8

3-88 .FSS

Set

A file name was found in the source string; two
words in RAD50 format at FIRQB+FQNAMI.
Note that this is the same meaning as for bit 0
at XRB+XRBLK
.

Clear

No file name was found in the source string.

Set

A period (.) was found in the source string.
Note that this is the same meaning as for bit 3
at XRB+XRBLK

Clear

No period was found in the source string,
implying that no file type was specified either.

Set

A PPN was found in the source string. Note
that this is the same meaning as for bit 7 at
XRB+XRBLK

Clear

No PPN was found.

Set

A valid protection code was found. Note that
this is the same meaning as for bit 10 at
XRB+XRBLK

Clear

No protection code was found.

Set

A colon (but not necessarily a device name) was
found in the source string. Note that this is the
same meaning as for bit 12 at XRB+XRBLK

Clear

No colon was found, implying that no device
could have been specified.

Set

Device name was specified and was a logical device name. Note that this is the same
meaning as for bit 14 at XRB+XRBLK

Clear

Device name (if specified) was an act.un] device
name. (If device name was not specified, this
bit is also 0.)
(Not currently used.)

14
15

XRB+XRMOD

Set

Source string contained wildcard characters
(either ?, *, or both) in file name, type, or PPN
fields. In addition, the device name specified,
although 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. Flag word 2
contains more specific information.

The device description (the same information returned by the BASICPLUS STATUS variable and returned at FIRQB+FQFLAG when a
file or device is opened with the OPNFQ or CREFQ subfunctions of
CALFIP). The device handler index is in the low byte and descriptive
flags are in the high byte.
FIROB
Octal
Offset

Mne- Octal
monic Offset

I I 1/ I I I I I I 1/ I I I I I 1/ I I

111/1/1/11

FOSIZM5

MSB of file size

project number

current job no .• 2

111/111111

programmer number

Mnemonic

FOJOB

FOPPN
FONAM1

file name in RAD50 format

(first 2 words)

file type in RAD50 format (1 word)

FOEXT

LSB of file size

FOSIZ

11111111111/111111/11

mode parameter

FOMODE

3rd word of logical name (not translated)

FOFLAG

FOPFLG

FODEV

FODEVN

FOP ROT 27
31

protection code

=255, explicit prot.

device name (2 ASCII characters)
<>0, unit no. real

device unit number

cluster size parameter

FOCLUS

position parameter (DCN for first block)

FONENT

NOTE

For each of the following field definitions that begin with the word "If,"
a corresponding statement applies: "If not, the field is left alone." That
is, you can insert values in the FIRQB before executing the .FSS to
serve as default values for fields when the .FSS returns no result .

. FSS 3-89

FIRQB+FQJOB

The current job number times two.

FIRQB+FQSIZM

If a IFILESIZE:n or /SIZE:n switch was specified, the most significant bits of the file size are contained in this byte.

FIRQB+FQPPN

If a PPN was part of the translated string or if a logical name
was found to be the same as a system or user logical name with
an associated PPN, this word contains the binary value of that
PPN. The project number is in the high byte; the programmer
number in the low byte. Any value returned here by .FSS has
been verified by the monitor as being within the range for PPNs
on a RSTSIE system.

FIRQB+FQNAM1

If a file name was encountered, it is translated to two words
of RAD50, beginning at this location. If less than 6 characters,
the file name is left-justified and padded with blanks (0 RAD50
characters ).

FIRQB+FQEXT

If a file type was encountered, it is translated to one word of
RAD50, beginning at this location. If less than 3 characters,
the file type is left-justified and padded with blanks (0 RAD50
characters).

FIRQB+FQSIZ

If a IFILESIZE:n or /SIZE:n switch was encountered, the value of
n is translated to binary and the LSB of the value are placed in
this word. The MSB are placed in the byte at FIRQB+FQSIZM.

FIRQB+FQMODE

If a IMODE:n switch was encountered, the value specified is
translated to binary and returned in this word. Bit 15 is set to
indicate that a mode switch was translated and to differentiate
between a mode of and no mode at all. (Note that bit 15 must
be set for a mode value to work on opens.)

FIRQB+FQPFLG

If a file protection code was encountered, a word is returned
here. The high byte (FIRQB+FQPROT) is the binary value of
the protection code, and the low byte (FIRQB+FQPFLG) is 255.
Setting the low byte indicates that a protection code was specified
and differentiates a protection code of zero from no protection code
at all.

FIRQB+FQDEV

If a device name was specified, it is returned here as two ASCII
characters. If less than two characters were specified, the device
name is left-justified and padded with spaces (ASCII 32.).

FIRQB+FQDEVN

If a device name but no explicit unit number was specified, this
word is zero. If an explicit unit number was specified, then
that unit number is in the low byte and 255 is in the high byte.
Setting the high byte indicates an explicit device number and
differentiates a device number of zero from no device number at
all.

NOTE

If a syntactically correct logical device name was encountered that
could not be translated to a physical device name, then the first six
characters of the logical device name are returned as two words of
RAD50 starting at offset FQDEV and the next three characters are
returned as one word of RAD50 at offset FQFLAG. Characters beyond
the first nine are not returned.

3-90 .FSS

FIRQB+FQCLUS

If a /CLUSTERSIZE:n switch was encountered, the value of n is
returned here, in binary.

FIRQB+FQNENT

If a !POSITION:n switch was encountered, the value of n is returned here, in binary. (The value n is the device cluster number
for the first block ofthe file.)

Errors
BADCNT

The first three words of the XRB are illegal, or an odd or illegal address for
nonstandard user logical table.

BADNAM

Some illegal specification occurred in the string. .FSS found a sign bit set
on at least one character.

BADSWT

Some .FSS switch was encountered, but it was in an illegal format.

BDNERR

The numeric argument to one of the .FSS switches was illegal.

Example
The following code causes the monitor to scan a string beginning at location
BUFFER as a possible file name. BUFFER is defined as an 80-byte area and is
filled with zeros to terminate the string scan if what the user typed did not fill
the buffer. For example:
BUFFER:

.BLKWO

40.

(read string into BUFFER from terminal)

CALL
CLRXRB
MOV
#80. ,XRB+XRLEN
#80. , XRB+XRBC
MOV
#BUFFER,XRB+XRLOC
MOV
.FSS
(test for error; if none, try open)

;DEFINE LENGTH
;DEFINE LENGTH AGAIN
;START OF BUFFER

.FSS 3-91

3.15 .LOGS -

Check for Logical Device Names

Form

.LOGS
Function

The .LOGS directive:
•

Translates a system logical device name to a physical device name

•

Translates a user logical device name to a physical device name

•

Translates RAD50 format to ASCII

•

Verifies that a physical device name is valid

•

Obtains generic information about a particular device

You specify either a logical device name, a physical device designation (name
and, if relevant, unit number), or both, in the XRB and the FIRQB. The monitor
compares the logical device name specified, if any, against the selected logical list
(system or user). If it finds a match, the monitor returns the device designation
associated with the logical device name to the FIRQB. This physical device
designation consists of a name, unit number, and in some cases, a PPN.
You can use the .LOGS directive simply to translate the RAD50 text stored in
the XRB into ASCII text using the same rules of translation that .FSS uses. The
number of words that are illegal in RAD50 and the number of translation rule
violations are returned to the caller.
The underline character C) is illegal in RAD50 but legal in logical names. To
resolve this, RSTSIE stores underline characters as periods (.) internally. When
a logical name that includes an underline is translated to RAD50, you must
substitute the period character. (If you use .FSS to generate the RAD50 text, this
substituion happens automatically.)
RSTSIE provides two translation functions: one returns a period when it finds
a period, and the other returns an underline when it finds a period. In each
case, the input data is in the XRB in RAD50 format. XRB+O must be nonzero;
otherwise .LOGS just retums the device status of the device in FQDEV.
.LOGS Subfunctions:

There are six subfunctions of the .LOGS directive.

FQDEVValue

Meaning

-2

Translate the logical in the XRB, using the user logical list instead
of the system logical list.

-3

Translate the RAD50 data in the XRB into an ASCII string, using
the rules for logicals ("." maps to "_").

-4

Translate the RAD50 data in the XRB into an ASCII string without
mapping ("." is returned as ".").

-1

Translate the logical in the XRB using the system logical list.

Use SY: as the physical device name.

Physical device
name

As two ASCII characters, overriden if the logical contains a device
also.

Next, the monitor checks the physical device designation (either the one passed
or the one returned by the monitor in the logical-name translation) to be sure it
is valid. If so, information describing the device is returned in the FIRQB.
3-92

.LOGS

Privileges Required
None

Data Passed
XRB
Octal MneOffset monic

Mne- Octal
monic Offset

o XRLEN
3

logical device name in RAD50 format

(5 words)

13
15

XRB+XRLEN

1////1//1/1///1//////
/1////1////1//1/1////
/ / / / / / 1/ / / /I / / 1/ / / / / /

12
14

The logical device name to be checked is passed as five words in RAD50
format beginning at this location. If only a physical device name check
or description is needed, then the first word of the XRB should be
passed as zero. The physical device name is passed in the FIRQB.
FIRQB
Octal MneOffset monic

Mne- Octal
monic Offset
////1///////1////////

////1///////1//////1/

////1//////////////1/

/ / / / 1/ / / / / / / 1/ / / / / / 1/

/ / / / / / / / / / / / / / / / / II / /

////1///////1//////1/

////1//////////////1/

/ / / / 1/ / / / / / / 1/ / / / / /I /

/ / / / 1/ / / / / / / 1/ / / / / / 1/

/ / / / 1/ / / / / / / 1/ / / / / /I /

physical device name (ASCII format)

30 FQDEV

32 FQDEVN

<>0, real dev. no.

device unit number

/ / / / 1/ / / / / / / 1/ / / / / / 1/

.LOGS

3-93

FIRQB+FQDEV

The physical device name, as two ASCII characters, or one of the
following codes:
o
For the public disk structure (SY:). (You must also
have 0 at offset FIRQB+FQDEVN).
-1

For a translation from a logical device name to a
physical device name. (A -1 is guaranteed not to be a
valid physical device name.)

-2

For a translation of the logical name passed in the
XRB using the user logical table rather than the
system logical table, which is the default.

-3

For a translation of the RAD50 data passed in the XRB
to ASCII data using special conversion rules. RAD50
dot (.) characters are translated as underscores C).

-4

For a translation of the RAD50 data passed in the XRB
to ASCII data without using conversion rules.

Other

For a translation of the logical name passed in the
XRB using the system logical tables only.

If the first word of the XRB is zero, the .LOGS directive makes
no translations and returns generic information about the device
specified in FQDEV and FQDEVN.
FIRQB+FQDEVN

The unit number of the physical device name is passed in this
byte, in binary. To indicate an explicit device number, set the
high byte (at FIRQB+FQDEVN+1) to some nonzero value. If the
physical device name is of the form ''XY:'' (that is, no unit number
is specified), then set the entire word at this offset to zero to
indicate no explicit unit number.

Data Returned

XRB

Octal MneOffset monic

Mne- Octal
monic Offset

XRB+XRLOC

/ II / / / / / II / / / / / / / / / / /

/ II / / / / / II / / / / / / II / / /

logical device flag: -1=N, -2=Y, O=N.A.

4 XRLOC

device description

6 XRCI

reasonable buffer size for device

10 XRBLK

/ / / / / / / / II / / / / / / II / / /

/ II / / / / / II / / / / I I II I I I

If there was no logical device name specified or if the logical device
name cannot be translated to a physical device name, this word is
returned as zero.
If the passed logical device name has a PPN associated with it,
this word is returned as -2. If not, -1 is returned.

XRB+XRCI

3-94

.LOGS

Description of the device. The low byte contains the device's
handler index. The high byte contains a set of status flags.

DDNFS
DDRLO
DDWLO
FLGPOS

FLGMODl
FLGFRC

FL:Rr~r !
15

13 12 11 10 9

device-type flags

7
device handler index

High Byte - Device-Type Flags
The bits in the high byte of the flag word are set to indicate the type of device specified:
FLGRND
FLGKB
FLGFRC

FLGMOD

FLGPOS

DDWLO
DDRLO
DDNFS

=1
=0
=1

The device is random-access.

The device is not a terminal-type device.

::::1

The device is byte-oriented. That is, the
.READ and .WRITE directives handle data in
byte units.

The device is block-oriented. The .READ and
.WRITE directives handle data in block units.

The device accepts modifiers in .READ and
.WRITE directives.

The device does not accept modifiers in
.READ and .WRITE directives.

The device keeps track of its horizontal
position and expands characters such as TAB
to whatever is appropriate for the device. You
can determine the current horizontal position
with the .POSTN directive.

The device does not keep track of its horizontal position.

=1
=0
=1
=0
=1
=0

The device is a read-only device.

The device is sequential.
The device is a terminal-type device.

The device is not write-locked.
The device is a write-only device.
The device is not read-locked.
The device is non-file-structured.
The device is file-structured.

.LOGS

3-95

Low Byte - Device Handler Index
Bits 0-7 of the flags word contain a handler index that indicates the generic kind of device.
The currently defined values follow.
Octal
Value

0
2
4
6
10
12
14
16
20
22
24
26
30
32-36
40
42
44
46
50
XRB+XRBLK

3-96

.LOGS

Symbol

Meaning

DSKHND

All disks

TrYHND

All tenninals
Reserved

LPI'HND

All line printers
Reserved
Reserved

CDRHND

Card reader

MTAHND

Magnetic tape

PKBHND

Pseudo keyboards

RXDHND

Flexible diskettes

NULHND

The null device

DMCHND

The DMClllDMRll DDCMP interface

Reserved

Reserved
KMCHND

KMCll

IBMHND

IBM interconnect
Reserved

DMPHND

DMPlllDMVll device

ETHHND

Ethernet device

If the physical device name is valid (either the one returned by
the monitor's translation of logical device name or the one passed),
this word contains the monitor's "best guess" as a reasonable
buffer size for this device. See the .READ and .WRITE directives
in this chapter.

FIRQB
Mne- Octal
monic Offset

Octal MneOffset monic
/ / / / / / / / /I / / / / / / / / / / /

/1//1/1//11/1/////1//

/I / / / 1/ 1/ / 1/ / / 1/ 1/ 1/ /

project number

programmer number

/1//1////11//1//1/1//

1/ / 1/ / 1/ /I 1/ / / 1/ / / / 1/

/1/1/////1/1/1/1/1///

1/1//1/1/1/1//1/1/1//

/I / / / 1/ 1/ / 1/ / / / 1/ / / / /

/I / / / 1/ 1/ / 1/ / / 1/ 1/ / / /

/11//1///11/////1/1//

II / / / /I II / / /I / 1/ / 1/ / /

device name (2 ASCII characters)

<>0, unit no. real

device unit number

FQPPN

FQDEV

32 FQOEVN

1/ / / / 1/ 1/ / 1/ ; 1/ 1/ 1/ / /

/1////11///1/1/1//1//

FIRQB+FQPPN

If a logical device name was passed and it was translated to a
device designation with an associated PPN, the PPN is returned
in this word. Otherwise, this word is the same as before the
.LOGS call was executed.

FIRQB+FQDEV

The physical device name, either the one returned when a successful translation of logical device name is made or the one passed,
if no logical device name was passed. The physical device name is
returned as two ASCII characters.

FIRQB+ FQDEVN

The physical device unit number, either the one returned when
a successful translation of logical device name is made or the
one passed, if no logical device name was passed. The low
byte contains the unit number, in binary. The high byte (at
FIRQB+FQDEVN+l) is either zero, to indicate no explicit device
number, or nonzero, to indicate an explicit device number.

.LOGS

3-97

Data Returned-RAD50 Translation Subfunctions
If -3 or -4 is passed at FIRQB+FQDEV, the return FIRQB contains the ASCII

translation of the RAD50 logical names.
FIROB
Mne- Octal
monic Offset

Octal MneOffset monic

1111111111111111111//

111111111111//1111111

4 FOFIL

ASCII data

translated

from RAD50

111111//11

# illegal RAD50 wds

30 FODEV

# illegal chars

32 FODEVN

111111111111//1111111

FIRQB+FQFIL

The ASCII translation of the RAD50 data passed in the XRB. Any
unused bytes translate as zeroes. Each RAD50 word translates
as three ASCII characters. Translation ends at the first zero
encountered in the XRB. megal RAD50 word values translate as
three question marks (711).

FIRQB+FQDEVN

The number of illegal characters encountered. The subfunctions
search for the following errors:
•
•
•
•

FIRQB+FQDEVN+l

Leading spaces. (Trailing spaces are legal.)
Dollar sign ($) characters. (Only system logicals may have $
characters.)
Question mark (1) characters.
Dot (.) characters (subfunction -4 only).

The number of illegal RAD50 word values detected.

Errors
NODEVC

3-98

.LOGS

The physical device name (either the one passed or the one corresponding to
the logical device name) is invalid.

Example
The following code asks the monitor to check the name SYSDEV to see if it is a
defined system logical device name and, if so, to return the physical device name
and characteristics to the XRB and FIRQB:
CALL
MOV
MOV
. LOGS

CLRXRB
iARSYS,XRB+XRLEN
iARDEV,XRB+XRBC

;SET XRB TO TRANSLATE LOGICAL
;DEVICE NAME "SYSDEV"

.LOGS

3-99

3.16 .MESAG -

Message Send/Receive

Form

(Load FIRQB and/or XRB for appropriate subfunction)

• ME SAG

Function

The .MESAG directive provides access from a MACRO program to the RSTS/E
local message send/receive services and, if your system is a DECnetIE system, to
DECnet/E network message send/receive services.
This section contains FIRQB and XRB formats and error descriptions for local
message send/receive. (Unless data passed and returned show specific values for
the XRB, it should be all zeros.) When using SENDIRECEIVE calls, you must
clear both FIRQB and XRB, even if XRB is not used.
For detailed information about each call, see the RSTS/E Programming Manual.
For information about network message send/receive, see RSTS/E DECnet/E
Network Programming in MACRO-ll.

3.16.1

Declare Receiver Subfunction
Privileges Required

SYSIO to declare a receiver with an unrestricted name, network server, or local
object. EXQTA to suppress RIB or message quota checks.

3-100

.MESAG-Declare Receiver

Data Passed
FIROB
Octal MneOffset monic

Mne- Octal
monic Offset

I I I I I I I I I I I I I I I I /I I I I

1/1/111/11/1/1/1//1/1

1/1/111/1/

I function code 1
=

4 FOFIL
6

FQPPN

receiver name in ASCII
10

(space fill to six bytes)
13

access

object type

14 FQEXT

buffer maximum

inbound link max

16 FOSIZ

message max

20 FOBUFL

packet maximum

pkts/msg

22 FOMODE

I outbound link max

24 FaRAG

I II I I I I I I I I I I I I I I I I I I

IIIIIIIII IIIIIIIIIIII

1111111/1/

RIB number

32 FODEVN

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

FIRQB+FQPPN

If the caller does not have SYSIO privilege, the fifth and sixth
characters of the receiver name must be the caller's job number as
two ASCII digits.

FIRQB+FQMODE

Specifies the maximum number of packets that can be queued at
anyone time. See the RSTS / E Programming Manual for more
information. Used only in an EMT logging program.

FIRQB+FQFLAG+l

Specifies the number of packets that make up a complete message.
See the RSTS / E Programming Manual for more information.
Used only in an EMT logging program.

Data Returned

Except for a possible error code in byte 0 of the FIRQB, the declare receiver
subfunction of .MESAG does not return any meaningful data.

Errors
BADCNT

The specified packet maximum is out of range.

BADFUO

The receiver name, object type, and access parameters passed are inconsistent.

.MESAG-Declare Receiver

3-101

BADNAM

This error can occur for one of the following reasons:
•
•
•

The receiver name passed contains nonprintable characters or leading
or embedded spaces
A job without SYSIO privilege passed a nonblank receiver name whose
fifth and sixth characters are not its job number
The specified local object type is invalid

ERRERR

The call you attempted requires an optional feature (such as EMT logging
or DECnet) that is not available on your system.

FIEXST

The receiver name passed is being used by another receiver, or the local
object type you specified is single instance and is already in use.

INUSE

The calling job already exists in the system's list of declared receivers. This
error may indicate a logic error in the program 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, issue a remove receiver call, and
then reissue the declare receiver. (It is common practice to code a remove
receiver immediately before the declare receiver call.)

NOBUFS

There were no small buffers available to hold the arguments passed in the
declaration. Since the system's use of small buffers is dynamic, a retry may
succeed.

PRVIOL

This can occur for one of the following reasons:
•
•

QUOTA

3-102

The specified RIB number is out of range
The caller does not have the privilege required for a particular option

You have exceeded the RIB or message quotas.

.MESAG-Declare Receiver

3.16.2 Remove Receiver Subfunction
Privileges Required

JOBCTL to remove the RIB of another job.
Data Passed
FIROB
Mne- Octal
monic Offset

Octal MneOffset monic

3
FOSIZM5

11111/1111111/111111/

(See discussion.)

function code = 0

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

/ / / / /I / / / / / / /I / / / / / /I

/////1//////1///11/1/

/ / / / /I / / / / / / /I I I I / / /I

/ / / / /I / / / I / / /I / / / / / /I

/ / / / /I / / / / / / /I / / / / / /I

<>0, remove all RIBs

RIB number

/ / / / /I I I / / / / /I / / / / / /I

/ / / / /I / / / / / / /I / / / / / /I

FIRQB+FQSIZM

FOFIL

FOOEVN

The value is two times the job number of the receiver (s) you want to
remove or zero if the receiver (s) belong to your own job. To specify
a conditional remove, set the sign bit. For example, to conditionally
remove receivers for your own job, set this byte equal to 200.
When the sign bit is set, the remove operation is rejected if there are
any messages pending for the receiver.

Data Returned
Except for a possible error code in byte 0 of the FIRQB, the remove receiver
subfunction of .MESAG does not return any meaningful data.

Errors
BADFUO

The argument at FIRQB+FQSIZM was odd. It must be zero to remove the
calling program or job number times two to remove another job.

INUSE

Occurs on a conditional remove if there are messages pending for the receiver.

PRVIOL

The caller does not have JOBCTL privilege and has attempted to remove the
receiver ID block (RIB) of another job (that is, FIRQB+FQSIZM is nonzero) .

.MESAG-Remove Receiver 3-103

3.16.3 Send Local Data Message Subfunction
Privileges Required

SEND to send to a restricted receiver.
Data Passed
FIR08
Mne- Octal
monic Offset

FOSIZM5

Octal MneOffset monic
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 I I I I I I /I I I I I I I I

FOFIL

FOPPN

destination

function code = -1

7
receiver name in ASCII
11

10
(space fill to six bytes)

17
21
23

3-104

optional user parameter string
up to 20 bytes of additional
user data can be specified here
(zero fill to 20 bytes)

16
20
22

.MESAG-Send Local Data

FOEXT

FIRQB+FQSIZM

You can specify the destination in one of three ways:
•

A zero value indicates that the destination is the receiver
name that starts at FIRQB+FQPPN.
A value equal to the job number times two indicates that
the destination is this job number. If you do not specify a
name (FIRQB+FQPPN = 0), the system locates the receiver
by job number; this works only when the the receiving job
is receiving messages on RIB O. If you specify a name, the
system sends to the specified receiver name. However, the
system also checks that the receiver's job number matches the
value in FIRQB+FQSIZM.
A value equal to the local object type (LOT) plus 200 indicates
that the destination is the receiver for the specified local
object type number. Only single-instance object types are
valid (see the RSTS/E Programming Manual). Legal values
are:
LOT Receiver

Error logger

EMT logger

PBS-command interpreter

PBS-server interpreter

PBS-user request packet

OPSER

OMS

Specifies the receiver name. If FIRQB+FQSIZM is zero, this field
must be nonzero.

FIRQB+FQPPN

XRB
Mne- Octal
monic Offset

Octal MneOffset monic
length of output buffer, in bytes, 0-512

o XRLEN

number of bytes to send, 0 to buffer length

2 XRBC
4 XRLOC

starting address of buffer

/ / / / / / / / II / / / / / / / / / / /

/ / / / / / / / / / / / / / / / II / / /

/ II / / / / / II / / / / / / / / / / /

/ / / / / / / / II / / / / / / II / / /

XRB+XRLEN

Length of the output buffer, in bytes. This value can range from
zero through 512.

XRB+XRBC

The number of bytes to be sent. This value can range from zero
through the size of the buffer, as specified at XRB+XRLEN.

XRB+XRLOC

Starting address of the output buffer. (See the section "XRB
(Transfer Request Block)" in Chapter 2 for more information.)

.MESAG-Send Local Data

3-105

Data Returned
FIR08
Octal
Offset

Mne- Octal
monic Offset

FOSIZM5

I I I I I I I I / / I I I I I I II I I I

I II I / / / I I I / / / / / / / / / / ~

job nO.'2 of rec. job

1111111111

I / I I I I I I / / / I I / I / II I I I

I 1/ I I I I I I I I I I I / I II I I I

11111///1/ II / I 11///11

I II I I I I I I I / I / I / I / / / I I

I II I I / / / / I I / / / / I II / / I

lllIlIlIlIlllllIlIlil

/11 III IIIIIIII IIIIII I

I 1/ I I I II II I I I II II II I I

I / / I I I I I I I I I I I I I II I I I

11//1111/11 I I 11/11111

I 1/ / II II II II I I I II II I /

I I I I I I I I I I I I I I I / 1/ I I I

111/11111//11///11111

Mnemonic

Errors

3-106

BADCNT

The XRB+XRLEN value is illegal. It can range from 0 through 512.

BADFUO

The value at FIRQB+FQSIZM is odd. It must be zero or the receiver's job
number times two.

NOBUFS

System buffers are currently not available to store this message for the
intended local receiver. A later retry may proceed without error.

NOROOM

The number of pending messages for the intended local receiver is at its
declared maximum, or the receiving program is hibernating. This program
should try again later. If this error occurs repeatedly, the receiver is not
processing messages often enough.

NOSUCH

The intended local receiver could not be located in the system's list of
declared receivers. The receiver must be declared (with a declare receiver)
before any data can be transmitted to it.

PRVIOL

Some access violation has occurred. Either the receiver does not allow any
local senders, or the sender does not have SEND privilege and the receiver
allows only restricted senders.

.MESAG-Send local Data

3.16.4

Receive Subfunction
Privileges Required

None
Data Passed
FIROB
Mne- Octal
monic Offset

Octal MneOffset monic

3
FOSIZM5

I I I I II I I I I I I I 1/ I I I I I I

I I I I I 1/ I I I I I I 1/ I I I I I I

receive modifier

function code = 2

FOFIL

qualifier (norm = 0)

sender select

FOPPN

I I I I I 1/ I I I I I I II I I I I I I

I I I I I 1/ I I I I I I 1/ I I I I I I

I I I I II I I I I I I I 1/ I I I I I I

I I I I I II I I I I I I 1/ I I I I I I

sleep time, in seconds

I I I I I II I I I I I I 1/ I I I I I I

I I I I II I ! I I I I I 1/ I I I I I I

I I I I I 1/ I I I I I II I I I I I I I

1111111111

RIB number

FOMODE

32 FODEVN

I I I I I 1/ I I I I I I II I I I I I I

I I I I I 1/ I I I I I I 1/ I I I I I I

XRB
Mne- Octal
monic Offset

Octal MneOffset monic
buffer size in bytes, or 0

o XRLEN

must be 0

2 XRBC

starting address of buffer

I 1/ I I I I I 1/ I I I I I I 1/ I I I

11/111111/1111111/111

I II I I I I I II I I I I I I 1/ I I I

4 XRLOC

.MESAG-Receive

3-107

XRB+XRLEN

The size of the receive buffer, in bytes. This word can be zero
if no user data is desired on the receive. The amount of data
transferred from a pending message will never be greater than the
buffer size.

XRB+XRBC

This word must be passed as zero. The monitor returns the actual
number of bytes of user data transferred in this word location, as
shown in the Data Returned sections.

XRB+XRLOC

The starting address of the receive buffer. {See the section "XRB
(Transfer Request Block),' in Chapter 2 for more information.}

Data Returned

The Receive call returns data to the FIRQB and XRB, identifying the type of
message received and user data, if any, to the buffer defined in the data passed.
The FIRQB and XRB formats for the local data message follow.
Data Returned (Local Data Message)
FIROB
Octal MneOffset monic

Mne- Octal
monic Offset

I I I I II I I I I I I II I I I I I II

FOSIZM5

job number· 2

function code = -1

FOFIL

project number

programmer number

FOPPN

1111111111

sender KB no. or 377

FONAM1

13 remainder (number of bytes not transferred)

14 FQEXT

.MESAG-Receive

Data passed as parameters by the
sender of this message.

FIRQB+FQNAMI

3-108

111111111111111111111

A value of 377 means the sender is detached.

3.16.4

Receive Subfunction
Privileges Required

None
Data Passed
FIROB
Mne- Octal
monic Offset

Octal MneOffset monic

3
FOSIZM5

111111111111111111111

I I I I I 1/ I I I I I I 1/ I I I I I I

receive modifier

function code = 2

FOFIL

qualifier (norm = 0)

sender select

FOPPN

11111/1/1/1111/111111

I I 1/ I 1/ I I I I I I 1/ I I I I I I

I I I I I 1/ I I I I I I 1/ I I I I I I

I I I 1/ 1/ I I I I I I 1/ I I I I I I

sleep time, in seconds

I I I I I 1/ I I I 1/ I 1/ I I I I I I

I I I I I 1/ I I I I I I 1/ I I I I I I

I I 1/ 1/ I I I I I I I 1/ I I I I I I

RIB number

11/11/1111

22 FOMODE

I I I I I 1/ I I I I I I 1/ I I I I I I

I I I I II I I I I I I I 1/ I I I I I I

FODEVN

XRB
Mne- Octal
monic Offset

Octal MneOffset monic
buffer size in bytes, or 0

o XRLEN

must be 0

2 XRBC

starting address of buffer

I 1/ I I I I I 1/ I I I I I I 1/ I I I

11111/11111111111/111

I /I I I I I I 1/ I I I I I I II I I I

4 XRLOC

.MESAG-Receive

3-107

XRB+XRLEN

XRB+XRBC

This word must be passed as zero. The monitor returns the actual
number of bytes of user data transferred in this word location, as
shown in the Data Returned sections.

XRB+XRLOC

The starting address of the receive buffer. (See the section "XRB
(Transfer Request Block)" in Chapter 2 for more information.)

Data Returned

Mne- Octal
monic Offset

111111111111111111111

I I I I II I I I I I I II I I I I I II

FOSIZM5

job number· 2

function code = -1

FOFIL

project number

programmer number

FOPPN

1111111111

sender KB no. or 377

FONAM1

remainder (number of bytes not transferred)

15
17

.MESAG-Receive

14
Data passed as parameters by the
sender of this message.

FQEXT

FIRQB+FQNAMl

3-108

A value of 377 means the sender is detached.

For an EMT logger message, the monitor returns three values:

FIRQB+FQEXT

•

Bytes 14-15 contain the number of data packets not transferred.
• Bytes 16-17 contain the number of EMTs your program
missed, either because it is not processing data packets
quickly enough, or because not enough XBUF is available to
store all the data packets that the monitor is creating.
• Bytes 20-21 contain the number of data packets transferred.
See the RSTS IE Programming Manual for more information.
XRB
Octal MneOffset monic

Mne- Octal
monic Offset

I I II I I I I I II I I I I I I II I I

o
2 XRBC

length (actual number of bytes transferred)

111111111111111111111

I I II I I I I I II I I I I I I II I I

111111111111111111111

I II I I I I I I II I I I I I I II I I

Errors
BADCNT

The buffer descriptor in the first three words of the XRB is invalid.

BADFUO

Not a declared receiver. Before any receive can succeed, you must execute a
declare receiver call to define the RIB number you want to use.

NOSUCH

For a receive without sleep (bit 0 in receive modifier =0), this error indicates
that no appropriate messages are pending. For a receive with sleep (bit 0 in
receive modifier = 1), this error is returned when the program is awakened
from the sleep. The program must execute another receive call to retrieve
any pending messages.

.MESAG-Receive

3-109

3.16.5

Send Privileges Subfunction
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. Data
can be sent at the same time.
Privileges Required

SEND to send to a restricted receiver.
Data Passed . Send Privileges
FIRQ8
Octal MneOffset monic

Mne- Octal
monic Offset

3
FQSIZM5

111111111111111111111

I I I I II I I I I I I I I I I I I I I I

FQFIL

FQPPN

destination

function code = -11

7
receiver name in ASCII

11
(space fill to six bytes)

13
15

17
21
23

111111111111111111111
111111111111111111111
111111111111111111111
111111111111111111111
111111111111111111111
111111111111111111111
111111111111111111111

14
16
20
22
24

optional user parameter string
26

27
31

3-110

(up to 12 bytes of additional
user data can be specified here,
zero fill to 12 bytes)

.MESAG-Send Privileges

FQEXT

You can specify the destination in one of three ways:

FIRQB+FQSIZM

•
•

•

LOT

Receiver

Error logger

EMT logger

PBS--command interpreter

PBS-server interpreter

PBS-user request packet

OPSER

OMS

Specifies the receiver name. If FIRQB+FQSIZM is zero, this field
must be nonzero.

FIRQB+FQPPN

XRB
Octal MneOffset monic

Mne- Octal
monic Offset

length of output buffer, in bytes, 0-512

o XRLEN

number of bytes to send, 0 to buffer length

2 XRBC
4 XRLOC

starting address of buffer

/1//////1///////1////

/ 1/ / / / / / 1/ / / / / / II / / / /

/ 1/ / / / / / 1/ / / / / / / 1/ / / /

/1//////////////1////

XRB+XRLEN

Length of the output buffer, in bytes. This value can range from
zero through 512.

XRB+XRBC

The number of bytes to be sent. This value can range from one
through the size ofthe buffer, as specified at XRB+XRLEN. If the
value in XRB+XRLEN is zero, this value must be zero.

XRB+XRLOC

Starting address of the output buffer. (See the section "XRB
(Transfer Request Block)" in Chapter 2 for more information.)

.MESAG-Send Privileges

3-111

Data Received by Receiver
FIRQB
Octal MneOffset monic

Mne- Octal
monic Offset

I I I I /I I I I I I I /I I I I I I /I

FQSIZM5

job number· 2

function code = -11

FQFIL

project number

programmer number

FQPPN

1/1//11//1

sender KB no. or 255

FQNAM1

remainder (number of bytes not transferred)
sender's privilege mask

(4 words)

12
14

FQEXT

22
24

25
data passed as parameters by
the sender of this message

32
34

Errors

3-112

BADCNT

The XRB+XRLEN value is illegal. It can range from 0 through 512.

BADFUO

The value at FIRQB+FQSIZM is odd. It must be zero or the receiver's job
number times two.

NOBUFS

System buffers are currently not available to store this message for the
intended local receiver. A later retry may proceed without error.

NOROOM

The number of pending messages for the intended local receiver is at its
declared maximum, or the receiving job is hibernating. This program should
try again later. If this error occurs repeatedly, the receiver is not processing
messages often enough.

NOSUCH

The intended local receiver could not be located in the system's list of
declared receivers. The receiver must be declared (with a declare receiver)
before any data can be transmitted to it.

PRVIOL

Some access violation has occurred. Either the receiver does not anow any
local senders, or the sender does not have SEND privilege and the receiver
allows only restricted senders.

.MESAG-Send Privileges

3.16.6

Create Local LAT Port
This directive creates a local LAT port for the host to use to initiate LAT
connections. You can specify the name and unit number of the port to be created;
if you specify no name, the monitor selects the next available port. The directive
returns the name and unit number of the local LAT port created in the FIRQB.
Privileges Required

SWCTL
Data Passed
FIRQB

Octal MneOffset monic

Mne- Octal
monic Offset

3
FQSIZM5

/ / / / 1/ / / / / / / 1/ / / / / / 1/

/ / / 1/ / / / / / / / 1/ / / / / / 1/

-14 octal

FQFIL

////1///1///1//////1/

/ / / 1/ / / / / / / / 1/ / / / / / 1/

/ / / / 1/ / / / / / / 1/ / / / / / 1/

/ / / 1/ / / / / / / / 1/ / / / / / 1/

/ / / / 1/ / / / / / / 1/ / / / / / 1/

///1/1//////1//////1/

/ / / / 1/ / / / / / / 1/ / / / / / 1/

"KB"

FQOEV

FQOEVN

unit number flag

unit number

///1/1//////1//////1/

/ / / / 1/ / / / / / / 1/ / / / / / 1/

FIRQB+FQFIL

Specifies the SET LAT function.

FIRQB+FQSIZM

Specifies Create Local LAT Port.

FIRQB+FQDEV

Must be the ASCII characters "KB" or zero. If zero, the monitor
selects the next available port.

FIRQB+FQDEVN

Unit number of the port to be created.

FIRQB+FQDEVN+l

Must be nonzero.

.MESAG-Create LAT Port 3-113

Data Returned
FIROB

Mne- Octal
monic Offset

Octal MneOffset monic
error code or 0

11111/1111111/111111/

I I I I 1/ I I I I I I 1/ I I I I I 1/

11111/1111111/111111/

I I I I 1/ I I I I I I 1/ I I I I I 1/

11111/1111111/111111/

I I I I 1/ I I I I I I 1/ I I I I I 1/

"KS"

-1

30 FOOEV

unit number

32 FOOEVN

I I I I 1/ I I I I I I 1/ I I I I I 1/

FIRQB+O

Error code or zero.

FIRQB+FQDEV

The two ASCII characters "KB".

FIRQB+FQDEVN

Unit number of the port created.

FIRQB+FQDEVN+l

Nonzero value.

Errors

3-114

ERRERR

LAT is not installed on the system.

lNUSE

The device specified is currently in use.

NOBUFS

Not enough small buffers are available to create the local LAT port.

NODEVC

The device specified is not a dynamic keyboard.

PRVIOL

The caller does not have the SWCTL privilege.

.MESAG-Create LAT Port

3.16.7

Delete local lAT Port
This directive deletes the local LAT port created by the Create Local LAT Port
directive. The caner passes the name of the port in the FIRQB. If a session is
active on the port, the port is deleted once the session has finished. The caller
can request that the session be terminated immediately by setting the abort bit
in the flag byte.
Privileges Required
SWCTL
Data Passed
FIROB
Mne- Octal
monic Offset

Octal MneOffset monic

/ / / / /I / / / / / / / / / / / / / / /

-14 octal

FOFIL

/11/1/1/1/

Flag

FOPPN

/ / / / 1/ / / / / / / / / / / / / / / /

/I / /1/ / / / / / /I / /I /I / /I

/ / / / /I / / / / / / / / / / / / / / /

/ / / / /I / / / / / / /I / / / / / / /

/ /I 1/ / / / / / 1/ 1/ 1/ 1/ / /I

/ 1/ 1/ / / 1/ / 1/ /I / 1/ / / 1/

/ / / / /I / / / / / / /I / / / / / / /

/1/1/1////1//11/1///1

ilKS"

FODEV

FOOEVN

FOSIZM5
7

unit number flag

unit number

/ / / / /I / / / / / / /I / / / / / / /

/ / / / /I / / / / / / / / / / / / / /I

FIRQB+FQFIL

Specifies the SET LAT function.

FIRQB+FQSIZM

Specifies Delete Local LAT Port.

FIRQB+FQPPN

The flag byte. If bit zero is set to one, the directive aborts any
currently active session on the specified port.

FIRQB+FQDEV

Must be the ASCII characters "KB".

FIRQB+FQDEVN

The unit number of the port to be deleted.

FIRQB+FQDEVN+l

Must be nonzero.

.MESAG-Delete lAT Port

3-115

Data Returned
FIRQ8

Mne- Octal
monic Offset

Octal MneOffset monic
error code or 0

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

1/1/1/1/11

Flag

6 FQPPN

I I I I I I I I /I I I I I I I /I I I I

IIII IIIIIIIIII I IIIIII

I /I I I I I I /I I I I I I I I I I I I

/1/1/111/11////11//11

I I I I I I I I /I I I I I I I I I I I I

I 1/ I I I I I 1/ I I I I I I 1/ I I I

IIII IIIIIIIIIII IIIIII

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

I /I I I I I I 1/ I I I I I I /I I I I

I /I I I I I I 1/ I I I I I I I I I I I

FIRQB+FQPPN

The flag byte. If bit zero is set to one, the port to be deleted has
an active session.

Errors

3-116

BADFUO

No port name was specified.

ERRERR
NODEVC

The port named is not a local LAT port.

PRVIOL

The caller does not have the SWCTL privilege.

LAT is not installed on the system.

.MESAG-Delete LAT Port

3.16.8

Assign a local lAT Port
This directive lets the caller specify the server name and the remote LAT port
name, the remote service name that the port will be assigned to, or both. It also
lets the user set the default of whether or not requests can be queued. The caller
must specify the server name as well as the remote port name, the remote service
name, or both. The directive returns an error if any data is missing.
Privileges Required

SWCFG
Data Passed
FIR08
Mne- Octal
monic Offset

Octal MneOffset monic

FOSIZM5

II I II II I I I I I II II I II II

II I II I II I I I II I I II II I I

-14 octal

FOFIL

1111111111

o (assign)

FOPPN

set default flags

clear default flags

FQNAM1

II I II I I I I I II II II II II I

II II II II II I II I I I I I II I

II II I I I I I II II II II II I I

II I II I I I I I I I II II I II I I

II II I I 1/ I II II I II I I II I

1111/1111111111111111

II II I II II II II I I I I I II I

"KS"

unit number flag

unit number

32 FODEVN

111111111111111111111

II I II I I I II I II I II II II I

FIRQB+FQFIL

FODEV

Specifies the SET LAT function.

FIRQB+FQSIZM

Specifies Set Local LAT Port.

FIRQB+FQPPN

Must be zero for Assign Port.

FIRQB+FQNAM1

Default settings to clear. If bit seven is set to one, access type is
set to NO QUEUED.

FIRQB+FQNAMl+l

Default settings to set. If bit seven is set to one, access type is set
to QUEUED.

FIRQB+FQDEV

Must be the ASCII characters "KE".

FIRQB+FQDEVN

The unit number ofthe port to be mapped.

FIRQB+FQDEVN+l

Must be nonzero.

.MESAG-Assign LAT Port

3-117

XRB

Mne- Octal
monic Offset

Octal MneOffset monic
length of buffer. in bytes

o XRLEN

number 01 bytes used in buffer

2 XRBC

starting address of buffer

4 XRLOC

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

/I /I I /I 1/1/ I I I I /I /I I I

XRB+XRLEN
XRB+XRBC
XRB+XRLOC

Specifies the length of the buffer. Must not be zero.
Specifies the number of bytes used in the buffer.
Specifies the starling address of the buffer. The buffer must start
on a word boundary or an error will be returned.

The XRB describes a buffer used to pass the remote server, and either the service
name, the port name, or both. The format of the buffer is:

I I I
Type

Len

Data

I I I
Type

Len

Data

The buffer has the long format if all three names are used.
Type

A one-byte unsigned value specifying the type of name that
follows. The valid types are:
o
remote server name
1

remote service name

remote port name

Len

A one-byte unsigned value specifying the length of the data field
that follows. The maximum length is 16 bytes.

Data

The name of the server, service, or remote port.

The names may contain alphanumeric characters, eight-bit characters with ASCII
values of 192 to 253 decimal, dollar sign ($), hyphen (-), period (.), or underscore
C). Note that spaces are invalid characters.
Data Returned

Except for a possible error code in byte 0 of the FIRQB, the assign local LAT port
directive of .MESAG does not return any meaningful data.

3-118

.MESAG-Assign LAT Port

Errors
BADCNT

The length of the fields specified in the user buffer exceeds the length of the
buffer as given in XRB+XRLEN, or the buffer address was not on a word
boundary.

BADFUO

This error can occur for the following reasons:

An invalid type code was found in the user buffer.
The remote server, service, or port name length was not in the range of
1 to 16 decimal bytes.
The remote server, service, or port had no name specified.
No local LAT port name was specified.
BADNAM

The remote server, service, or port name contained invalid characters.

ERRERR

LAT is not installed on the system.

lNUSE

The port is currently in use.

NODEVC

The port named is not a local LAT port.

PRVIOL

The caller does not have the SWCFG privilege.

.MESAG-Assign LAT Port 3-119

3.16.9

Deassign Local LAT Port
This directive lets the caller disassociate the local LAT port from the server it
was assigned to. Once deassigned, the LAT port cannot be used for host-initiated
connections until it is once more assigned to a server.
Privileges Required

SWCFG
Data Passed
FIRQB
Octal MneOffset monic

Mne- Octal
monic Offset

3
FQSIZM5

/ / / II / / / / / / II / / / / / II /

-14 octal

FQFIL

1 (deassign)

FQPPN

/1/1/1/1/1

/ / / /I / / / / / / /I / / / / / 1/ /

/ / / 1/ / / / / / / II / / / / / 1/ /

/ / / 1/ / / / / / / 1/ / / / / / 1/ /

/ / / /I / / / / / / 1/ / / / / / 1/ /

/ / / 1/ / / / / / / 1/ / / / / / II /

//1/1//////1//////1//

/1/1///////1//////1//

"Ksn

FQOEV

FQOEVN

unit number flag

unit number

///1/////1/1//////1//

/ / / /I / / / / / / /I / / / / / 1/ /

FIRQB+FQFIL

Specifies the SET LAT function.

FIRQB+FQSIZM

Specifies Set Local LAT Port.

FIRQB+FQPPN

Must be one for Deassign Port.

FIRQB+FQDEV

Must be the ASCII characters "KB".

FIRQB+FQDEVN

The unit number of the port to be unmapped.

FIRQB+FQDEVN+l

Must be nonzero.

Data Returned

Except for a possible error code in byte 0 of the FIRQB, the deassign local LAT
port directive of .MESAG does not return any meaningful data.

3-120

.MESAG-Deassign LAT Port

Errors

BADFUO
ERRERR
lNUSE
NODEVC
PRVIOL

No local LAT port name was specified.
LAT is not installed on the system.
The port is currently in use.
The port named is not a local LAT port.
The caller does not have the SWCFG privilege.

.MESAG-Deassign LAT Port 3-121

3.16.10

Return Local LAT Port Status
This directive lets the caller get current infonnation on the status of the local
LAT port. The caller must specify the port name of the local LAT port.
Privileges Required

No privileges required.
Data Passed
FIRQB
MneOctal
monic Offset

Mnemonic

///1//////////////1//

//////////////////1//

FQSIZM

+14 octal

FQFIL

FQPPN+1

FQPPN

///1//////////////1//

//////////////////1//

/1111////11////1111//

/1111////////////////

///1//////1///////1//

///111111111///11////

///11/111111//11//111

11/11111///////11/1//

"KB"

FQOEV

FQOEVN

FQOEVN+133

3-122

Octal
Offset

unit number flag

unit number

/////////////////1///

//1/11////11///11////

FIRQB+FQFIL

Specifies the SHOW LAT function.

FIRQB+FQSIZM

Specifies the Show Local LAT Port subfunction.

FIRQB+FQPPN

Must be zero.

FIRQB+FQPPN+l

Must be one to return status.

FIRQB+FQDEV
FIRQB_FQDEVN

The local port name, always the ASCII characters "KB".
The local port unit number.

FIRQB+FQDEVN+l

The unit number real flag.

.MESAG-Return LAT Status

Data Returned
FIRQB
Mne- Octal
monic Offset

Octal MneOffset monic
error code or 0

/////////////////////

/ / / / /I / / / / / / /I / / / / / /I

11
13

status

6 FQPPN

port char

10 FQNAM1

queue position
reject reason code

error code

/ / / / /I / / / / / / /I / / / / / /I

///////1//

26 FQPFLG

owning job #

30 FQOEV

"KB"

32 FQOEVN

-1

/ / / / /I I / / / / / /I / / / / / /I

/ / / / /I / / / / / / /I / / / / / /I

unit number

FIRQB+O

Error code or zero.

FIRQB+FQPPN

The port characteristics bit mask.
Bit
Description

FIRQB+FQPPN+1

Set if application (host-initiated) port

Set if interactive (server-initiated) port

Set if dialup

Set if access type is QUEUED

The status bit mask.
Bit
Description

Set if connected

Set if connection failed

Set if connection in progress

FIRQB+FQNAM1

Entry position in queue (if bit 2 in Status is 1).

FIRQB+FQNAM1+2

RSTSIE error code (if bit 1 in Status is 1).
Value
Meaning
10

Connection request rejected by server

No response from server

Insufficient resources on this system to initiate a
connection

.MESAG-Return LAT Status 3-123

FIRQB+FQNAMl+3

Reject reason code (if bit 1 in Status is 1). The reject reason code
is returned by the server when a request has been rejected. The
codes (octal) are defined as follows:
Value
Meaning

Reason is unknown.

User requested disconnect.

System shutdown in progress.

Invalid slot received.

Invalid service class.

Insufficient resources to satisfy request.

Service in use.

No such service.

Service is disabled.

Service is not offered by the requested port.

Port name is unknown.

Invalid password.

Entry is not in the queue.

Immediate access rejected.

Access denied.

Corrupt solicit request.

Command type is illegal or not supported.

Can't send start slot.

Queue entry is deleted by local node.

Inconsistent or illegal request parameter.

FIRQB+FQEXT

Owning job number.

FIRQB+FQDEV

Local port name, always the ASCII characters "KB".

FIRQB+FQDEVN

Local port unit number.

FIRQB+FQDEVN+l

Unit number real flag.

Errors

3-124

BADFUO

No local LAT port name specified.

ERRERR

LAT is not installed on the system.

NODEVC

The port named is not a local LAT port.

.MESAG-Return LAT Status

3.16.11

Return Local LAT Port Characteristics
This directive lets the caller get infonnation on the current characteristics of the
local LAT port. The caller must provide a buffer of at least 132 octal bytes. The
infonnation returned is:
•

Local LAT port name

•

Port type (Application or Interactive)

•

Actual remote server name

•

Actual remort port name

•

Specified remote server name (Application only)

•

Specified remote LAT port name (Application only)

•

Specified remote service name (Application only)

•

Queued port characteristic

•

Status

•

Queue position

•

Error code

•

Reject reason code

•

Owning job number

The caller can request infonnation for a specific port by providing the port name
or by index. When using the index, the caller must specify the port type, which
detennines the list to search for the nth port. The directive returns infonnation
on only one port at a time. To get infonnation about all local LAT ports of a given
type, the caller must issue the directive repeatedly, incrementing the index each
time. When there are not more ports of that type, the directive returns the error
NOTAVL (ERR=8). An index value of zero means that the port name has been
provided; the directive then returns infonnation on the named port. If the index
is zero and no name is provided, the directive returns an error.
Privileges Required

None

.MESAG-Return LAT Characteristics 3-125

Data Passed
FIROB
Mne- Octal
monic Offset

Mnemonic

111111111111111111/11

111/111111/1111111/11

FOSIZM

+14 octal

FOFIL

FOPPN+1

port index

FOPPN

1/1111/1/1

port type

FONAM1

111/11/111/1111111/11

111/111111/1111111/11

111/111111/1111111/1/

I I 1/ I I I I I 1/ I I I I I I 1/ I I

111/111111/1111111/11

"KS"

FOOEV

FOOEVN

FOOEVN+133

3-126

Octal
Offset

unit number flag

unit number

I I 1/ I I I I I 1/ I I I I I I 1/ I I

111/1111/1/1111111/11

FIRQB+FQFIL

Specifies the SHOW LAT function.

FIRQB+FQSIZM

Specifies Show Local LAT Port.

FIRQB+FQPPN

Index value. Zero if port name is specified.

FIRQB+FQPPN+l

Must be zero to return port characteristics.

FIRQB+FQNAMI

One of the following port type codes:
Value
Meaning

Specific port requested

Application (host-initiated) port

Interactive (server-initiated) port

FIRQB+FQDEV

Must be the ASCII characters "KB" ifindex=O.

FIRQB+FQDEVN

The unit number of the local port to be shown if index=O.

FIRQB+FQDEVN+l

Must be nonzero if index=O.

.MESAG-Return LAT Characteristics

XRB
Mne- Octal
monic Offset

Octal MneOffset monic
length of buffer, in bytes

o XRLEN

2 XRBC

starting address of buffer

4 XRLOC

I /I I I I I I /I I I I I I I /I I I I

11/111111111111111111

I /I I I I I I /I I I I I I I II I I I

I /I I I I I I /I I I I I I I /I I I I

XRB+XRLEN

Specifies the length of the buffer. Must be at least 132 octal bytes
long.

XRB+XRBC
XRB+XRLOC

Must be zero.
Specifies the starting address of the buffer. The buffer must start
on a word boundary or an error will be returned.

The XRB describes a buffer used to return infonnation to the caller. The buffer
must be at least 132 octal bytes long. If there is not enough room in the buffer,
some infonnation will not be returned. The number of bytes actually used in the
buffer is returned in XRB+XRBC.

.MESAG-Return LAT Characteristics

3-127

Data Returned
FIROB
Octal MneOffset monic

Mne- Octal
monic Offset
error code or 0

111111111111111111111

11
13

status

port char

6 FOPPN

queue position

reject reason code

error code

111111111111111111111

11111111111/11111111/

1/1/11111/

owning job #

30 FOOEV

"KS"

26 FQPFLG

32 FOOEVN

-1

I I I 1/ I I I I I I I III I I I I II

1111111111111111/1111

unit number

Error code or zero.
FIRQB+FQPPN

FIRQB+FQPPN+l

3-128

The port characteristic bit mask.
Bit
Description

Set if application (host-initiated) port

Set if interactive (server-initiated) port

Set if dialup

Set if the access type is QUEUED

The status bit mask.
Bit
Description

Set if connected

Set if connection failed

Set if connection in progress

FIRQB+FQNAMI

Entry position in queue (if bit 2 in Status is 1).

FIRQB+FQNAMl+2

RSTSIE error code (if bit 1 in Status is 1).
Value
Meaning
10

Connection request rejected by server.

No response from server.

Insufficient resources on this system to initiate a
connection.

.MESAG-Return LAT Characteristics

FIRQB+FQNAMl+3

Reject reason code (if bit 1 in Status is 1). The reject reason code
is returned by the server when a request has been rejected. The
codes (octal) are defined as follows:
Value
Meaning

Reason is unknown.

User requested disconnect.

System shutdown in progress.

Invalid slot received.

Invalid service class.

Insufficient resources to satisfy request.

Service in use.

No such service.

Service is disabled.

Service is not offered by the requested port.

Port name is unknown.

Invalid password.

Entry is not in the queue.

Immediate access rejected.

Access denied.

Corrupt solicit request.

Command type is illegal or not supported.

Can't send start slot.

Queue entry is deleted by local node.

Inconsistent or illegal request parameter.

FIRQB+FQPFLG

Owning job number

FIRQB+FQDEV

Local port name, always the ASCII characters "KB".

FIRQB+FQDEVN

Local port unit number.

FIRQB+FQDEVN+l

Unit number real flag.
XRB
Octal MneOffset monic

Mne- Octal
monic Offset
length of buffer, in bytes

o XRLEN

number of bytes used in buffer

2 XRBC

starting address of buffer

4 XRLOC

11/111111/1/11111/111

I /I I I I I I /I I I I I I I /I I I I

11/111111/1111111/111

I /I I I I I I /I I I I I I I /I I I I

XRB+XRLEN

Specifies the length of the buffer. Must not be zero.

XRB+XRBC

Specifies the number of bytes used in the buffer.

.MESAG-Return LAT Characteristics 3-129

Specifies the starting address of the buffer. The buffer must start
on a word boundary or an error will be returned.

XRB+XRLOC

The XRB describes a buffer used to pass additional information about the local
LAT port. The format of the buffer is:

I I I
Type

Len

Data

I I I
Type

Len

Data

The buffer always includes at least two names. For server-initiated connections,
it contains the names of the actual server and the remote port. For host-initiated
connections, it contains the name of the specified server and the name of either
the specified service or the specified remote port. The buffer may also contain
as many as five names if the port is used for host-initiated connections and is
connected.
Type

A one-byte unsigned value specifying the type of name that
follows. The valid types are:
1
specified server name
2

specified service name

specified remote port name

actual server, if connected

actual remote port, if connected

Len

A one-byte unsigned value specifying the length of the data field
that follows. The maximum length is 16 bytes.

Data

The name of the server, service, or remote port.

Either the length of the user buffer is zero and the Get Port Information
form of the SHOW PORT directive was used, or the buffer address is not on
a word boundary.

BADFUO

This error can occur for the following reasons:
The value in FIRQB+FQPPN was not 0 or 1.
An invalid port type code was specified.
No port name was specified with an index value of zero.

3-130

ERRERR

LAT is not installed on this system.

NODEVC

The port name specified is not a local LAT port.

NOTAVL

No match for index specified.

.MESAG-Return LAT Characteristics

3.16.12 Show LAT Sessions
This directive lets the caller get information on the LAT sessions currently active
on the host node. The caller must provide a buffer of at least 65 octal bytes. The
information returned includes:
•

The number of the keyboard the user is currently using.

•

The node name of the server the user is on.

•

The name given to the server port the user is on.

Session information can be accessed in three ways:
•

By index across all servers.

•

By index for a particular server.

•

By keyboard number.

If no session matches the specified index, the directive returns the error NOTAVL
(ERR=8).
Privileges Required

None
Data Passed
FIRQ8
Octal MneOffset monic

Mne- Octal
monic Offset

/ / / / I! / / / / / / I! / / / / / I!

SF$SES (=6)

SR$LSH (=14 octal)

FQFIL

server name length

session index

FQPPN

1/1//1/1//

sender keyboard no.

FQNAM1

FQSIZM5

/ / / / I! / / / / / / 1/ / / / / / I!

/ / / / I! / / / / / / I! / / / / / I!

////I!I/////I!/////I!

FQNAM2

25
server name, if any, in ASCII

27
31

(FQPPN+ 1 bytes long)

FIRQB+FQFIL

Specifies the SHOW LAT function.

.MESAG-Show LAT Sessions

3-131

FIRQB+FQSIZM

Specifies Show LAT Sessions.

FIRQB+FQPPN

Index value. If there is no session matching this index, the
directive returns the NOTAVL error. A value of one returns the
first session. A value of zero means the keyboard number is
passed in FIRQB+FQNAMI

FIRQB+FQPPN+l

The length of the server name starting at FQNAM2. A non-zero
value means this is an index lookup by server name. A value of
zero means that no server is specified and information is returned
on all servers known to the LAT host node, by index. This byte is
ignored if FIRQB+FQPPN is zero.

FIRQB+FQNAMI

The keyboard number for which the session information is returned. This byte is ignored if FIRQB+FQPPN is non·zero.

FIRQB+FQNAMI

If FIRQB+FQPPN+l is non-zero, then FQNAM2 is the start of
the name of the server for which session information is returned.
All lowercase characters in the service name are converted to
uppercase for comparison.
XRB
Octal MneOffset monic

Mne- Octal
monic Offset
length of buffer, in bytes

o XRLEN

2 XRBC

starting address of buffer

4 XRLOC

11/111111/111111/1111

I 1/ I I I I I 1/ I I I I I I 1/ I I I

I 1/ I I I I I 1/ I I I I I /I I I I I

XRB+XRLEN

Specifies the length of the buffer. Must be at least 65 octal bytes
long.

XRB+XRBC

Must be zero.

XRB+XRLOC

Specifies the starting address of the buffer. The buffer must start
on a word boundary or an error will be returned.

The XRB describes a buffer used to return information to the caller. The buffer
must be at least 65 octal bytes long. If there is not enough room in the buffer,
some information will not be returned. The number of bytes actually used in the
buffer is returned in XRB+XRBC.

3-132

.MESAG-Show LAT Sessions

Data Returned

The data returns in a buffer at most 65 octal bytes long. The number of bytes
actually used is returned in XRB+XRBC. The buffer contains information on the
session requested by specific index or by keyboard number. The format of the
buffer is:
Buffer Contents On Return
port bitmask

keyboard number

port name length
(max. 20 octal bytes)

server port name
(length = port name length)
node name length
(max. 20 octal bytes)
server node name
(length = node name length)

service name length
(max. 20 octal bytes)
service port name
(length = service name length)

Keyboard Number

A 1-byte unsigned value giving the number of the
keyboard on which the session is currently active.

Port Bitmask

A 1-byte bitmask describing the port.
Bit
Description
0-6

Reserved

Set if the port is a dialup line; otherwise
clear.

Port Name Length

A 1-byte unsigned value indicating the length, in
bytes, of the server port name that follows. The
maximum length of the server port name is 20 octal
bytes.

Server Port Name

The name of the port on the server on which the user
is physically connected.

Node Name Length

A 1-byte unsigned value indicating the length, in
bytes, of the server node name that follows. The
maximum length of the server node name is 20 octal
bytes.

Server Node Name

The name of the server on which the user is connected.

Service Name Length

A 1-byte unsigned value indicating the length, in
bytes, of the service name that follows. The maximum
length of the service name is 20 octal bytes.

Service Name

The name of the service that the user is currently
running.

.MESAG-Show LAT Sessions

3-133

Errors

3-134

BADCNT

The buffer address is not on a word boundary.

BADFUO

The server name length in FQPPN+l was larger than 20 octal.

ERRERR

LAT is not installed on this system.

NODEVC

The keyboard number specified at FQNAMI is not a valid keyboard number.

NOTAVL

No match for the index specified.

NOSUCH

There was no server matching the server specified in the FIRQB.

.MESAG-Show LAT Sessions

3.17 .NAME -

Set Program Name

Form

.NAME
Function

The .NAME directive sets the program name in the monitor tables. The monitor
enters the name in an internal table; otherwise, it makes no use of the program
name. However, the SHOW USERS command uses the names in listing current
information for jobs (under the "What" column) on the system. The BASIC-PLUS
run-time system uses this directive when the user issues an OLD, NEW, or
RENAME command.
The program name is passed as two words of RAD50 data in the FIRQB. Note
that the data is passed in the same location in the FIRQB where the file name
exists at the P.RUN entry point into a run-time system. If you are coding or
modifying a run-time system, one of the first things to do on entry at P.RUN is to
set the program's name. Thus, the file name's position in the FIRQB at this point
is convenient for use.
Privileges Required

None
Data Passed
FIROB
Octal MneOffset monic

Mne- Octal
monic Offset
111111111111111111111

11111/1111111/111111/

111111111111111111111

I I I I II I I I I I I II I I I I I /I

program name in RAD50 format
(2 words)

10 FONAM1
12

13
15

11111/1111111/111111/

11111111111111111111/

I I I I /I I I I I I I /I I I I I I II

11111/1111111/111111/

11111111111111111111/

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 I 1 1 1 /I 1 1 1 1 1 /I

11111/1111111/111111/

1 1 1 II 1 1 I I 1 I 1 /I 1 1 1 1 1 /I

1/111/1111111/111111/

.NAME 3-135

FIRQB+FQNAMI

The program name to be set; two words in RAD50 format.

Data Returned

The .NAME directive does not return any meaningful data.
Errors

No errors are possible with the .NAME directive.
Example

The following code sets the name PROGRM in the monitor tables:

MOV
MOV
• NAME

3-136

.NAME

#ARPRO,FIRQB+FQNAMl
#ARGRM,FIRQB+FQNAM1+2

Set FIRQB to declare
Name of "PROGRM"

3.18 .PEEK -

Look at Monitor Memory

Form

.PEEK
Function

The .PEEK directive returns the contents of one word of the monitor's memory;
that is, the memory mapped by the kernel mode APRs (see Chapter 2). Only a
job with the required privileges can execute the .PEEK directive. (However, you
should not base any of your code on the contents of monitor memory because
Digital Reserves the right to change the monitor structure and internal addresses
at any time, except for the addresses listed in Table 3-3.)
Privileges Required

RDMEM to read kernel memory other than the I/O page and WRTMEM to read
the I/O page.
Data Passed

XRB
Mne- Octal
monic Offset

Octal MneOffset monic
virtual address of desired monitor word

XRB+XRLEN

o XRLEN

/ / / / / / II / / II / / II / / / / /

/ / / / / / II / / / / / / II / / / / /

The virtual address of the data word in monitor memory whose
contents are to be returned. The value must be even, since word
addresses on the PDP-11 are always even. Peeking at data in the
I/O page (kernel APR 7, or 111 (binary) in bits 15, 14, and 13) can
cause unpredictable system results; Digital does not recommend
this. Furthermore, using .PEEK to obtain data in APRs 5 or 6
returns data in the file processor's private buffer pool.

Use .PEEK to examine addresses returned by get monitor tables calls or addresses of fixed monitor locations.
Table 3-3 shows fixed monitor locations and their addresses. The RSTS / E
Internals Manual lists other monitor data structures and their locations in
memory, but the locations listed in Table 3-3 will not change in future releases of
RSTSIE.

.PEEK 3-137

Table 3-3: Fixed Monitor Locations
Address
(Octal)

Name

Meaning

44(word)

IDATE

The date when the system was last started by START.

46(word)

ITIME

The time of day when the system was last started by
START.

1000(word)

DATE

CUITent system date.

1002(word)

TIME

CUITent time of day.

1006(byte)

JOB

Job number times 2 of the job cUITently running (always the
user's own job number.)

1010(word)

JOBDA

Address of the job data block (JDB) of the cUITently running
job (always the user's own JDB).

1012(word)

JOBF

Address of the JDFLG word in the JDB of the cUITently
running job (always the user's own JDB).

1014(word)

IOSTS

Address of the JDIOST (low) byte and JDPOST (high) byte
in the JDB of the cUITently running job (always the user's
ownJDB).

Data Returned
XRB
Mne- Octal
monic Offset

Octal MneOffset monic
contents of the monitor memory word

XRB+XRLEN

o XRLEN

1111111/1111111/11111

I I I I I I 1/ I I I I II 1/ I I I I I

I I I I I I 1/ I I I I I II I I I I I I

111111111111111/11111

1111111/1111111/11111

The contents of the requested monitor memory location.

Errors
B.4

The address specified caused a trap to the kernel mode vector at 4 (UNIBUS
timeout, odd address, and so forth).

B.250

The address specified caused a memory management unit violation (trap to
the kernel mode vector at 250).

PRVIOL

The caller does not have the required privilege.

Example
The following code obtains the contents of monitor memory location 1006 (the low
byte of which is the current job number times two):
MOV
.PEEK

3-138

.PEEK

#JOB,XRB+XRLEN

; Set address to that of "JOB"

3.19 .PLAS -

Access Resident Library

The .PLAS (Program Logical Address Space) directive has six subfunctions that
allow a MACRO program to access a resident library. Resident libraries must
be so defined by the system manager with the INSTALL LIBRARY command
(see the RSTS / E System Manager's Guide). As noted in Chapter 2, the easiest
way to do this is to link the resident library to your program using TKB, the
Task Builder that links modules assembled or compiled under the RSX run-time
system or its derivatives. However, you can use .PLAS subfunctions to directly
access resident libraries.
Table 3-4 lists the .PLAS subfunctions by function code. The following subsections describe the subfunctions in alphabetical order.

Table 3-4:

Summary of .PLAS Subfunctions

FQFUN
Value
(Octal)

Mnemonic

Action Performed

ATRFQ

Attach resident library. Attaches the job to a resident
library; necessary before the job can map a window to the
library.

DTRFQ

Detach resident library. Detaches the job from a resident
library.

CRAFQ

Create address window. Defines a range of virtual addresses
to be a window for looking at all or some portion of a
resident library. Optionally, CRAFQ maps the window to
all or some portion of a resident library. (The mapping can
be done separately with MAPFQ.) The CRAFQ subfunction
reserves one or more APRs, so CRAFQ takes space in the
job area even though the window may not actually be
mapped.

ELAFQ

Eliminate address window. Releases the APRs used by a
particular window.

MAPFQ

Map window. Maps an already created address window of
virtual addresses to actual memory locations in an attached
resident library. The monitor loads the library from disk if
necessary.

UMPFQ

Unmap address window. Releases a window of virtual
addresses from a mapping to actual memory locations.

When a program exits or a user logs out, the monitor automatically detaches all
libraries and unmaps and eliminates all windows for the job.

Privileges Required
Depends on the subfunction; refer to the individual descriptions that follow this
introductory information on the .PLAS directive.

.PLAS

3-139

3.19.1

ATRFQ (Attach Resident Library)
Form
MOVB

iATRFQ,FIRQB+FQFIL

(set appropriate parameters)

.PLAS

Function
The ATRFQ subfunction of .PLAS declares your intent to access a resident library.
The type of access is specified in the call. The number of resident libraries that
can be attached to a job at any given time is unlimited (subject to the availability
of system small buffers).
The job's ability to access the resident library depends upon the protection
assigned to the library by the system manager when the library was installed.
The default protection grants read access to all users and denies write access to
all users.
If the calling job can access the library in the specified fashion, the monitor sets
up its own internal tables, which lay the groundwork for the job to map windows
to the library. Note, however, that the resident library does not take up space in
the job area (virtual memory) with an attach. APRs are assigned (virtual memory
in the job area is taken) when a window is created (using CRAFQ).
Privileges Required

Read-only or read/write access to the library. The protection code is interpreted
exactly like a file protection code; as with files, access is granted either on the basis of the protection code or because of GREAD, GWRITE, WREAD, or WWRITE
privileges.

3-140

.PLAS-ATRFQ

Data Passed
FIR08
Mne- Octal
monic Offset

3
5

Octal MneOffset monic
IIIII II I IIIIIIIIIIIII

II II I I I I I II I I I I II II II

1111111111

ATRFO (= 0)

111111111111111111111

I I II II I I I II II I I II I I II

resident library name in RAD50 format
(2 words)

FOFIL

IIIIIIIIIIII IIIIII III

II II II I I I II II I I I II I I I

access mode

111111111111111111111

I I II II I I II I I II II II II I

I II II II I I II I I I I II II I I

IIIIIII IIIIIIII III II I

II II II II I II I I I I I II I I I

I I II II I I I II I II II II I II

FOMODE

FIRQB+FQFIL

The function code ATRFQ (octal value = 0).

FIRQB+12

The name of the resident library to which the job is to be attached;
two words in RAD50 format.
Resident libraries are made known to the monitor by the system manager with the INSTALL/LIBRARY command (see the
RSTSjE System Manager's Guide) With this command, the system manager defines a file (filename. LIB) as a resident library.
The monitor regards "filename" as the resident library's name.

FIRQB+FQMODE

The low-order two bits of this word define the way the job wants
to access the library:
Bit 0
=1
Read-only access is desired.
Bit 1

Read/write access is desired.

.PlAS-ATRFQ 3-141

Data Returned
FIROB
Mne- Octal
monic Offset

Octal MneOffset monic
I I I I I I I I I I I I I I 1/ I I I I I

1/1/11/1/1

current job no .• 2

0
2 FOJOB

I I I I I I I I I I I I I I 1/ I I I I I

resident library identification

size, in 32-word blocks, of the library

FOPPN

10 FQNAM1

I I I I I I 1/ I I I I I I 1/ I I I I I

11111111 I I I 11111I1111

11IIII111 II 111IIIII1I

I /I /I I 1/ I /I 1/ I 1/ I I I 1/

I11I11111III1 I 1111III

1//11/1/1/11/11/11/11

I /I /I /I I I /I I I 1/ /I 1/ I I

I11III111I1 II I 11111II

111//11/11/1//1/1111/

111I11111II1 I I 11111II

1/11/1/11/11/111/1/1/

FIRQB+FQJOB

The current job number times two.

FIRQB+FQPPN

This word is an identifier that must be used, rather than the
resident library name, in subsequent calls to identify a resident
library. Thus, you use this identifier to detach the job from the
library (DTRFQ) and map and unmap windows to the library
(MAPFQ and UMPFQ).

FIRQB+FQNAIY.U

The size of the resident library, in 32-word blocks.

Errors
NOSUCH

The resident library specified in the data passed is not known to the monitor. The system manager must install a resident library before it can be
used.

PRVIOL

The attach did not succeed because the caller's privilege did not allow the
access specified in the data passed. This could happen either:
..

3-142

.PLAS-ATRFQ

Because the access code specified in the data passed is not compatible
with the possible access defined when the library was installed by the
system manager.
Because the protection code associated with the resident library file
excludes access by the user.

Example
The following code attaches the job to a resident library called DATBAS. The
access desired is defined as read/write:
MOVB
MOV
MOV
MOV
.PLAS

*ATRFQ,FIRQB+FQFIL
*"RDAT,FIRQB+12
*"RBAS,FIRQB+FQEXT
*2,FIRQB+FQMODE

;DEFINE FUNCTION CODE
;LIBRARY NAME IS
;DEFINED AS "DATBAS"
; ACCESS=READWRITE

.PLAS-ATRFQ 3-143

3.19.2

CRAFQ (Create Address Window)
Form
MOVB

#CRAFQ,FIRQB+FQFIL

(set up parameters)

.PLAS

Function

The CRAFQ subfunction of .PLAS can be used either to create a window (a
range of virtual addresses) or to create a window of virtual addresses and map
it to a range of actual addresses in an attached library. You define the range of
addresses by:
•

Naming a base APR (which defines the starting address of the window)

•

Specifying the size of the window in 32-word blocks

Thus, a window always begins on a 4K-word boundary in virtual memory and
always takes at least 4K words. It may take more than 4K words, depending on
the size of the window.
If the required hardware is not present, the CRAFQ fails with an error.
If the address range overlaps the user job image, the call fails with an error. The
address range cannot overlap the run-time system (high segment). However, if
the job is currently running under RSX emulation, this is not a consideration.
APR 7, normally used to map a run-time system, can be used instead to map a
window to a resident library.
The difference between creating a window and creating and mapping a window is
best shown by example. By using create without map, you can define one window,
which can be mapped to a library or portion of a library and then remapped to
another portion of the same library or another library, as many times as desired,
using the MAPFQ subfunction of .PLAS.
For example, suppose your program takes up 24K words and you want to access a
24K-word resident library of data values. You can use create without map to set
up a 4K-word window in APR 6. You can then map the window (using MAPFQ)
to the first 4K words of the library, process the data, map to the next 4K words
of the library, and so forth. If, on the other hand, you had a 4K program and still
wanted to access a 24K-word library, you could use CRAFQ to create a 24K-word
window and map it to the entire library in APR 1 to 6.
A job can create a maximum of seven windows. A window takes at least one APR
(it may take more, depending on the size you specify for the window). Thus, the
maximum of seven assumes seven windows in APR 1 to 7. APR 0 can never be
used to create a window, since the user program takes at least this much space.
As mentioned previously, a window cannot overlap the user job image; thus, the
size of the user job image determines the lowest base APR that can be used. If
the program (user job image) is less than 4K words, APR 1 and up (to the limit
imposed by the run-time system boundary) can be used to create windows. If the
user job image is between 4K words and 8K words, APR 2 and up can be used to
create windows, and so forth.

3-144

.PLAS-CRAFQ

If a window is created that overlaps an already existing window, the old window
is eliminated. For example, if you create a 6K-word window using a base APR
of 5, the window uses APR 5 and APR 6. If you then create a 4K-word window
using a base APR of 6, the entire old window is eliminated. APR 5 is then free
for other use; APR 6 is used for the new window.

Privileges Required

RDMEM to map physical memory other than 1/0 page read-only. SYSMOD to
map physical memory read/write or to map the 1/0 page read/only.
Data Passed
FIROB
Mne- Octal
monic Offset

Octal MneOffset monic

/1/11////1//////1////

/ 1/ / / / / / / 1/ / / / / / 1/ / / /

/11/1/1/11

CRAFO (= 4)

base APR (1-7)

1111111111

/ 1/ / / / / / / 1/ / / / / / 1/ / / /

size of windows, in 32-word blocks

FOFIL

library identification (for map only)

14 FOEXT

offset, in 32-word blocks (for map only)

16 FOSIZ

length, in 32-word blocks (for map only)

FOBUFL

access flags

FOMODE

/ 1/ / / / / / / 1/ / / / / / 1/ / / /

/ 1/ / / / / / / 1/ / / / / / / / / / /

/ 1/ / / / / / / 1/ / / / / / 1/ / / /

/ 1/ / / / / / / II / / / / / 1/ / / /

FIRQB+FQFIL

The function code CRAFQ (octal value = 4).

FIRQB+7

The base APR of the window, 1 to 7. Implicitly defines the starting
virtual address of the window. This byte cannot be zero; in
addition, it cannot name an APR already being used to map the
user job image.

FIRQB+12

The desired size of the window, in 32-word blocks. For example, a
value of 128. equals 4K words.

FIRQB+FQEXT

The identifier of the resident library to which the window is to
be mapped. (This is the value returned by the ATRFQ function
of .PLAS at FIRQB+FQPPN.) This word is ignored for calls
requesting a create without mapping (bit 7 at FIRQB+FQMODE
equals 0). You can also map the window to physical memory by
passing a value of -4. See MAPFQ for details .

.PLAS-CRAFQ 3-145

FIRQB+FQSIZ

The offset, in 32-word blocks, from the start of the library where
the mapping is to begin. This word is ignored if no mapping is
requested (bit 7 at FIRQB+FQMODE equals 0).
A value of zero for this word indicates the window is to be mapped
beginning at the first byte of the library. A value of one indicates
the window is to be mapped beginning at the 33rd word of the
library (starting address + 64), and so forth.

FIRQB+FQBUFL

The length, in 32-word blocks, of the area to be mapped (ignored if
bit 7 at FIRQB+FQMODE equals 0). This value cannot be greater
than the size ofthe window specified at FIRQB+12. Furthermore,
this value, combined with the offset value at FIRQB+FQSIZ,
cannot indicate an address beyond the end of the library or into
the high segment (run-time system),
A value of zero for this word defaults to either the size of the
window (specified at FIRQB+12) or the space remaining in the
library, whichever is smaller.
The octal value to set WS.MAP is 200; the value to set WS.WRT is
2. Thus, an octal value of 202 for this word requests mapping and
write access. A separate setting for write access in CRAFQ and
in ATRFQ allows you to attach to a library read/write and map a
portion of the library read-only.
If neither WS.UDS nor WS.SIS is set, then CRAFQ uses I-Space,
and D-Space too if it is available. There is a functional correspondence between WS.UDS and WS.SIS in the CRAFQ mode byte
and the region options available in TKB. This correspondence is
as follows:
RESCOM & COMMON
WS.UDS set
RESSUP & SUPLIB

WS.SIS set

RESLIB & LIBR

neither, WS.UDS and WS.SIS clear

IfWS.UDS = 1, the window is created in the D-Space APR only;
no mapping in the I-Space is done. If another window is already
created in both the 1- and D- Spaces at this APR, the I-Space
window remains as it is, but the D window is moved to the
requested area. If a CRAFQ is done to the same APR with neither
WS.UDS nor WS.SIS set, the resulting mapping is such that the
D-Space APR is given to the CRAW with WS.UDS set and the
I-Space APR is assigned to the region of the second CRAFQ.
It is illegal to CRAFQ a region with both WS. UDS and WS.8IS
set. With this directive, supervisor Data Space is always mapped
the same as user Data Space. See Chapter 5, the section on
MSDS$, for information on changing supervisor Data Space under
RSX.

3-146

.PLAS-CRAFQ

The octal value to set WS.MAP is 200; the value to set WS.WRT is
2. Thus, an octal value of 202 for this word requests mapping and
write access. A separate setting for write access in CRAFQ and
in ATRFQ allows you to attach to a library read/write and map a
portion of the library read-only.
If neither WS.UDS nor WS.SIS is set, then CRAFQ uses I-Space,
and D-Space too if it is available. There is a functional correspondence between WS.UDS and WS.SIS in the CRAFQ mode byte
and the region options available in TKB. This correspondence is
as follows:
RESCOM & COMMON
WS.UDS set
RESSUP & SUPLIB

WS.SIS set

RESLIB & LIBR
neither, WS.UDS and WS.SIS clear
If WS.UDS 1, the window is created in the D-Space APR only;
no mapping in the I-Space is done. If another window is already
created in both the 1- and D- Spaces at this APR, the I-Space
window remains as it is, but the D window is moved to the
requested area. If a CRAFQ is done to the same APR with neither
WS.UDS nor WS.SIS set, the resulting mapping is such that the
D-Space APR is given to the CRAW with WS.UDS set and the
I-Space APR is assigned to the region of the second CRAFQ.
It is illegal to CRAFQ a region with both WS.UDS and WS.8IS
set. With this directive, supervisor Data Space is always mapped
the same as user Data Space. See Chapter 5, the section on
MSDS$, for information on changing supervisor Data Space under
RS:x.

Data Returned
FIRQB
Mne- Octal
monic Offset

Octal MneOffset monic
/I I I I I I I /I I I I I I /I I I I I

1/1/1/1/1/

current job no. * 2

0
2 FQJOB

1/11/1111/111111/1111

FQPPN

1/1/1/1/1/

starting virtual address of new window

/I / I I I / / /I / I I I I /I I I I I

1/ 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 I I I I I I I I I I I

mapped length, in 32-word blocks

20 FQBUFL

status flags

22 FQMOOE

/I / I I I I I 1/ 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 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 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 I /I I I I I

window 10

10 FQNAM1

.PLAS-CRAFQ

3-147

FIRQB+FQJOB

The current job number times t.wo.

FIRQB+FQPPN

The window ID. Use in later MAPFQ calls to map the newly
created window; it must be used in any ELAFQ calls to eliminate
the newly created windows. The value returned may be from
1 to 7.

FIRQB+FQNAMI

The starting virtual address of the new window.

FIRQB+FQBUFL

Length actually mapped by the window, in 32-word blocks.

FIRQB+FQMODE

Status flags. The monitor returns the status of the new window
as follows:
Bit 15 = 1
Window was created successfully.
Bit 14

Bit 13

Window was not created successfully.

An existing window was unmapped because it
overlapped the newly created mapping.

No existing windows were unmapped by this
mapping.

An existing window was eliminated because it
overlapped the newly created window.

No existing windows were eliminated by this
create.

Errors
BADFUO

Either the base APR and window length specified were invalid, or the offset
and mapping length values specified were invalid. (For example, an offset
indicating a starting address for the mapping that is beyond the end ofthe
library or into the run-time system is invalid.)

NOBUFS

Creating a window requires a small buffer; a small buffer is not currently
available.

NOROOM

You attempted to create more than seven address windows.

NOSUCH

The library ID specified for mapping is not a library currently attached to
the job.

PRVIOL

The create was unsuccessful because the user privileges do not allow the access desired. At this point, since the library has been attached successfully
with some access defined, this error means that the access requested in the
CRAFQ is not allowed by the access requested in the ATRFQ.

Example

The following code creates a 4K-word address window and maps it to the beginning of a library whose ID (returned from a previous ATRFQ) has been stored at
location LIBID:

3-148

MOVB
MOV
MOV
MOV
CLR
CLR

iCRAFQ,FIRQB+FQFIL
i6,FIRQB+7
i200,FIRQB+12
LIBID,FIRQB+FQEXT
FIRQB+FQSIZ
FIRQB+FQBUFL

MOV
.PLAS

i200,FIRQB+FQMODE

.PLAS-CRAFQ

;DEFINE FUNCTION CODE
;BASE APR = 6
;WINDOW = 4K WORDS
; SET LIBRARY ID
;OFFSET = 0
; MAP 4K WORDS OR TO
; END OF LIBRARY
; MAP WINDOW, READ-ONLY

3.19.3

DTRFQ (Detach Resident library)
Form
MOVB

#DTRFQ,FIRQB+FQFIL

(define library to be detached)

.PLAS

Function
The DTRFQ subfunction of .PLAS detaches a previously attached resident library.
Any windows mapped to the library by the calling job are unmapped. If no other
jobs are currently attached to the library and it was installed with the /UNLOAD
option, the monitor removes the library from memory.
If this is a dynamic region and there are no other jobs currently attached to it,

and the region is marked for deletion after the last job detaches, the monitor
removes the region from memory and deletes jt from the resident library list.

Privileges Required
None

Data Passed
FIRQB
Mne- Octal
monic Offset

Odal MneOffset monic
1/11/1/1/1/1/1/1/1111

111111111111111111 II I

1///1///1/

DTRFO (= 2)

4 FOFIL
6 FOPPN

library identification (returned by ATRFO)

111111111111111111 I I I

1/ I 1/ 1/ 1/ 1/ 1/ I I I 1/ I I I

I I I I I I I I 1/ I I I I I I I I I I I

1111111111111111 II II I

1/11/1/1/1/1/11/1/1/1

1/11/1/1/1/11/1/1/111

1/ I 1/ 1/ 1/ I 1/ I I I I 1/ I I I

1/1/1//11/1/111/1/111

I 1/ I 1/ 1/ 1/ 1/ 1/ I 1/ I I I I

1/ I I 1/ 1/ 1/ 1/ 1/ /I 1/ I I I

1/11/1/1/11//11/1/111

1/ I 1/ 1/ 1/ 1/ 1/ I I 1/ I I I I

.PLAS-DTRFQ

3-149

FIRQB+FQFIL

The function code DTRFQ (octal value = 2).

FIRQB+FQPPN

The library identification returned at FIRQB+FQPPN by the
ATRFQ that attached the job to the library.

Data Returned
FIRQB
Mne- Octal
monic Offset

Octal MneOffset monic
11/1111111/1111111111

II 111111 Ii

current job no .• 2

0
2 FQJOB

1111111111/111111//1/

I 1/ I I I I I I 1/ I I I I I 1/ I I I

I II I I I I I I II I I I I I 1/ I I I

1111111111/111111/111

1111111111/1111111111

I II I I I I I I 1/ I I I I I 1/ I I I

I 1/ I I I I I I 1/ I I I I I 1/ I I /

status flag

11/1111111/1111/1/111

11/1111111/1//111////

I 1/ I I I I I I 1/ I I I I I 1/ I I I

I II I I I I I I 1/ I I I I I 1/ I I I

I 1/ I I I I I I 1/ I I I I I I I I I I

I II I I I I I I 1/ I I I I I 1/ I I I

22 FQMODE

FIRQB+FQJOB

The current job number times two.

FIRQB+FQMODE

Bit 14 of this word is set if any windows were unmapped as a
result of this detach.

Errors
NOSUCH

The library ID specified at FIRQB+FQPPN in the data passed does not
identify any library currently attached to the job.

Example
The following code detaches the library whose ID is stored at LIBID:
MOVB
MOV
.PLAS

3-150

.PLAS-DTRFQ

#DTRFQ,FIRQB+FQFIL
LIBID,FIRQB+FQPPN

;SET FUNCTION CODE
;SET LIBRARY ID

3.19.4

ELAFQ (Eliminate Address Window)
Form
MOVB

#ELAFQ,FIRQB+FQFIL

(set up parameters in FIRQB)

.PLAS

Function
The ELAFQ subfunction of .PLAS eliminates an address window that was created
by the job, unmapping the window if necessary. ELAFQ frees the APRs used
by the window and makes them available for creating another window or for
expanding the user job image size.

Privileges Required
None

Data Passed
FIRQB
Mne- Octal
monic Offset

Octal MneOffset monic
/ II / / / / / II / / / / / / II / / /

/ II / / / / / II / / / / / / II / / /

/1//111/11

ELAFQ (= 6)

4 FQFIL

/111/11111

window ID

6 FQPPN

/ II / / / / / II / / / / / / II / / /

/ II / / / / / II / / / / / / / / / / I

/ II I / / / I II / / I I I I II I I /

/ II / I / / / II / / / / I / II / I /

/ II / I I / I II / I / I I / II / I I

I II / I I / I II I I I I I I I I I / /

/ II I / / / / II / / / I I I II I I /

/ II I I I I I II I I I I / / II / / /

FIRQB+FQFIL

The function code ELAFQ (octal value equals 6).

.PLAS-ELAFQ

3-151

FIRQB+FQPPN

The ID ofthe window to be eliminated (returned at FIRQB+FQPPN
by the CRAFQ that created the window).

Data Returned
FIRQ8
Octal MneOffset monic

Mne- Octal
monic Offset

I II I I I I I I II I I I I I I I I I I

1/1/111/1/

current job no .• 2

0
2 FQJOB

I II I I I I I I 1/ I I I I I 1/ I I I

I II I I I I I I 1/ I I I I I I I I I I

1/1/1/1/1/11/1111/1/1

I II I I I I I I II I I I I I I I I I I

I II I I I I I I 1/ I I I I I I I I I I

I II I I I I I I II I I I I I I I I I I

status flags

//// /I I /I II I I I I / 1/ / / /

I II I / I / I / 1/ / / / I / / / / / /

I II I I I I I I II I I / I / I / I / /

I II I I I I I I II I / / / / / / / / /

I /I I I I I / / II / / / / / / i / / /

I II I I I I / / II / / I / / / / I / /

22 FQMODE

FIRQB+FQJOB

The current job number times two.

FIRQB+FQMODE

Two bits in this word indicate the status of the window:
Bit 13
=1
The window was successfully eliminated.

Bit 14

The window was not eliminated,

= 1

The address window was mapped to a resident
library and has been unmapped.

The address window was not mapped; no unmapping was done.

Errors
BADFUO

An invalid window ID was given in the data passed at FIRQB+FQPPN
(outside the range 1 through 7).

NOSUCH

The window ID specified at FIRQB+FQPPN is in the range 1 through 7 but
matches no currently created window for this job.

3-152 .PLAS--ElAFQ

Example
The following code eliminates an address window whose ID is stored in location
WINID:
MOVB
MOVB
.PLAS

*ELAFQ,FIRQB+FQFIL
WINID,FIRQB+FQPPN

;SET FUNCTION CODE
;SET WINDOW ID

.PLAS-ELAFQ

3-153

3.19.5

MAPFQ (Map Address Window)
Form
MOVB

#MAPFQ,FIRQB+FQFIL

(set up parameters)

.PLAS

Function
The MAPFQ subfunction of .PLAS maps a previously created address window
to an attached resident library. In other words, the MAPFQ relates the virtual
address range defined by a CRAFQ to actuallocations in memory within a
resident library that has been attached to the job by an ATRFQ. MAPFQ maps
the window in the address space given by the CRAFQ, supervisor I-Space, user
I -Space, or user D-Space.
If the window specified is already mapped, it is unmapped from its previous
actual memory locations and remapped to the new area. A job may map a
maximum of seven address windows at any given time.
If the resident library being mapped is not in memory when the MAPFQ is

executed, the system makes the library memory resident at that time.

Privileges Required
None, except to map physical memory (see the section "Map Physical Memory").

3-154 .PLAS-MAPFQ

Data Passed
FIR08
Mne- Octal
monic Offset

Octal MneOffset monic

11///11111/111111/111

I 1/ I I I I I I 1/ I I I I I /I I I I

//////1/1/

MAPFO (=10)

FOFIL

1///1/////

window 10

FOPPN

11/1/11111/111111/111

1/1 I I I I I I /I I I I I I /I I I /

resident library 10
offset, in 32-word blocks

17
21

length, in 32-word blocks, to be mapped

14 FOEXT
16 FOSIZ
20

F08UFL
FOMOOE

desired access mode

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

/ 1/ I I I / / I 1/ / / / / / / / I / /

I 1/ / I / I / / 1/ / / I / / / / I / I

FIRQB+FQFIL

The function code MAPFQ (octal value equals 10).

FIRQB+FQPPN

The ID of the window to be mapped (returned at FIRQB+FQPPN
by the CRAFQ subfunction call that created the window). The
window ID can be for any cun-ent window that uses some D-Space;
it cannot refer to a window using only I-Space.

FIRQB+FQEXT

The ID of the resident library to which the window is to be
mapped (returned as a full word at FIRQB+FQPPN by the ATRFQ
subfunction call that attached the job to the resident library).

FIRQB+FQSIZ

The offset from the start of the library where the mapping is to
begin, in 32-word blocks.
A value of zero for this word indicates the window is to be mapped
beginning at the first byte of the library. A value of 1 indicates
that the window is to be mapped beginning at the 33rd word of
the library (starting address = 64), and so forth.

FIRQB+FQBUFL

The length of the area to be mapped, in 32-word blocks. This
value cannot be greater than the size of the window (specified at FIRQB+12 in the CRAFQ which created the window).
Furthennore, this value, combi.ned with the offset value at
FIRQB+FQSIZ, cannot indicate an address beyond the end of
the library.
A value of 0 for this word defaults to either the size of the window
specified in FIRQB+ 12 in the CRAFQ or the space remaining in
the library, whichever is smaller.

.PLAS-MAPFQ

3-155

FIRQB+FQMODE

Bit 1 of this word specifies whether the window is to be mapped
read/write or read-only:
Bit 1
= 1 Read/write access.
=0
Read-only access.
A separate setting for access in MAPFQ and in ATRFQ allows you
to attach to a library read/write and map a portion of the library
read-only. You cannot, however, attach to a library read-only and
then map to the library read/write.

Data Returned
FIRQB
Octal MneOffset monic

Mne- Octal
monic Offset

////1/////1///////1//

current job no .• 2

/1//1/1///

/ / / /I / / / / / /I / / / / / / /I I

/ / / /I / I I I I /I I I I I / I /I I

/1111//1/1/1111//1111

/11//11111/11/1111/11

/////11111/11111111/1

///1//11111/111111/11

length, in 32-word blocks, actually mapped

status flag

FQJOB

FQBUFL

22 FQMODE

/ I / /I I I I I I /I / I I I / / /I I

/ / / /I I I I I / /I / I I / I I /I /

/1//1/1111//11/11//11

1/1/11/1111/1111111//

I I I /I I I I I I /I I I I I I I 1/ I

/1//1111111/111//1/11

FIRQB+FQJOB

The current job number times two.

FIRQB+FQBUFL

Length actually mapped by the call, in 32-word blocks.

FIRQB+FQMODE

Bit 14 of this word is a status flag:
Bit 14 = 1
The window specified was already mapped; the
window was unmapped before this mapping was
done.

3-156

.PLAS-MAPFQ

The window specified had no previous mapping;
no unmapping was done for this call.

Errors
BADFUO

The offset and length specified are inconsistent; either the mapping attempted to go beyond the end of the library or the length is greater than the
created window.

NOSUCH

Either the resident library ID or the address window ID is incorrect. (The
job is not currently attached to the specified resident library or no address
window has been created with the specified window ID.)

Example

The following code maps a window whose ID is stored at WINID to the attached
library whose ID is stored at LIBID. The offset of 256 indicates that the mapping
is to begin 8K words from the start of the library. Access to the library is readonly. For example:
MOVB
MOVB
MOV
MOV
CLR

#MAPFQ,FIRQB+FQFIL
WINID,FIRQB+FQPPN
LIBID,FIRQB+FQEXT
#256.,FIRQB+FQSIZ
FIRQB+FQBUFL

CLR
.PLAS

FIRQB+FQMODE

;SET FUNCTION CODE
; SET WINDOW ID
;SET LIBRARY ID
;OFFSET 8K WORDS
;MAP WINDOW SIZE OR
;TO END OF LIBRARY
;READ-ONLY ACCESS

Map Physical Memory

You can also use MAPFQ to map a window to physical memory. The data passed
is the same as for a resident library except FIRQB+FQEXT contains -4. The data
returned is the same.
You can map to monitor memory, XBUF, user memory, and so on, but not to
locked memory (including virtual disk), or non-existent memory. If you try to map
to locked or non-existent memory, you get a privilege violation error.
Privileges

You need RDMEM to map read/write or read-only. You need SYSMOD to map
read/write. If the starting address in memory is 17760000 or higher (block
number 177600), you also need SYSMOD for read-only.

.PLAS-MAPFQ 3-157

Data Passed (Map Physical Memory)
FIRQB
Octal MneOffset monic

Mne- Octal
monic Offset

3-158

/1//1////1//1///1////

/ 1/ / / / / / / /I / / / / / 1/ / / /

/1/11//1/1

MAPFQ (=10)

FQFIL

/1/11///1/

window 10

FQPPN

/ 1/ / / / / / / 1/ / / / / / 1/ / / /

/ 1/ / / / / / / 1/ / / / / / 1/ I I I

-4

14 FQEXT

starting address, in 32-word blocks

16 FQSIZ

length, in 32-word blocks, to be mapped

FQBUFL
FQMOOE

desired access mode

I 1/ / / I I / I 1/ I I I / I 1/ I I I

/ 1/ / / I / I / 1/ / / I I I 1/ I I I

/ 1/ / / I / I I 1/ I / I I I 1/ I I I

/I / / I / / I I 1/ / I I I I 1/ I I I

/ 1/ / / I I I I 1/ I I / I I 1/ I I I

/1////1/1////1111/11/

FIRQB+FQFIL

The function code MAPFQ (octal value equals 10).

FIRQB+FQPPN

The ID of the window to be mapped (returned at FIRQB+FQPPN
by the CRAFQ subfunction call that created the window).

FIRQB+FQEXT

4 to indicate map to physical memory.

FIRQB+FQSIZ

The offset from the start of memory where the mapping is to
begin, in 32-word blocks.
A value of zero for this word indicates the window is to be mapped
beginning at the first byte of physical memory. A value of 1
indicates that the window is to be mapped beginning at the 33rd
word of physical memory (starting address = 64), and so forth.

FIRQB+FQBUFL

The length of the area to be mapped, in 32-word blocks. This
value cannot be greater than the size of the window (specified at FIRQB+12 in the CRAFQ which created the window).
Furthermore, this value, combined with the offset value at
FIRQB+FQSIZ, cannot indkate an address beyond the end of
physical memory.
A value of zero for this word defaults to either the size of the
window or the space remaining in physical memory, whichever is
smaller.

.PLAS-MAPFQ

FIRQB+FQMODE

Bit 1 of this word specifies whether the window is to be mapped
read/write or read-only:
Bit 1
= 1 Read/write access.

Read-only access.

You need SYSMOD privilege to map read/write. You need
RDMEM privilege to map either way. If you want to map the
I/O page by specifying a starting address of 17760000 or higher
(block number 177600), you need SYSMOD privilege to map either
way.
You can map to monitor memory, XBUF, or user memory, but not
to locked memory (including virtual disk), or nonexistent memory.

Errors
PRVIOL

3.19.5.1

The mapping was unsuccessful because user privileges did not allow the
access desired or you attempted to map to locked or nonexistent memory.

Fast-Mapping Facility
You may want to use the fast-mapping facility instead of the MAPFQ subfunction.
It enhances perfonnance and is compatible with the fast-mapping facility of
RSX-llM-PLUS. The RSTSIE RSX emulator also provides the following features:
•

The Task Builder IFM switch.

•

The TFEA$ RSX monitor call can tell a program if fast-mapping is enabled.

•

The .SET and .CLEAR monitor calls allow a task to enable and disable
fast-mapping.

You can use fast-mapping if your program does not use any lOT instructions
except to perform the fast-map operations. To use the fast-mapping facility,
set parameters as shown in the following calling sequence, then issue an lOT
instruction:
Calling Sequence
RO
Rl
R2

parameter 1
parameter 2
parameter 3

lOT

see table of APR parameter values
offset field, 32 decimal words from library base
optional length specification (if used, bit 15 in RO
must =1)
calls the monitor to execute mapping

Returned Data
RO

Status

length mapped
Rl & R3

IS.SUC if successful
IE.TIS or IE.ALG if unsuccessful
if successful length actually mapped in slivers
indeterminate

.PLAS-MAPFQ 3-159

Table of Parameter Values

If
Base

UNo Length
Given

Length
Given

Space

APR

User-1

000010

100010

User-1

000020

100020

User-1

000030
000040

100030
100040

User-1

000050

100050

User-1

000060

100060

User-1

000070

100070

User-D

000110

100110

User-D

100120

User-D

000120
000130

User-D

000140

100130
100140

User-D

000150

100150

User-D

000160

100160

User-D

000170

100170

APR 1-0 cannot be changed

APR D-O cannot be changed

The fast-mapping facility has the following restrictions:
•

The fast-mapping facility can modify only the map field (FQSIZE) and,
optionally, the length to the map field (FQBUFL).

•

The interface to the fast-mapping facility is designed for speed, not for ease of
programming. It may be harder to debug a task using fast-mapping than one
using the .PLAS directive. The only validation fast-mapping does is to protect
the operating system and its data structures

•

The interface uses the lOT instruction. Tasks that use fast-mapping cannot
use the lOT instruction for any other purpose.

•

The interface uses registers to pass parameters instead of using a FIRQB.
This means that the MACRO-ll programmer must be careful about register
use when fast-mapping.

Examples

Change the window offset in an I-Space library:
MOV
MOV

:/t60,RO
:/t200,R1

rOT
TST
BMr

RO
ERROR

;r-Space window in APR 6
; offset 4K words from the beginning of library
;R2 not used
;do the re-map
;any errors?
;if minus yes, otherwise ok

Change the D-Space window offset and the actual window length:
MOV
MOV
MOV
rOT
TST
BMr

3-160

.PLAS-MAPFQ

:/tl00150,RO
#400,R1
:/t500,R2
RO
ERROR

;D-Space window in APR 5, length to be given
;offset 8K words from library base
;length to be 10K words (use APR 5,6 &7)
;issue instruction
;any errors?
;if minus yes, otherwise ok

3.19.6

UMPFQ (Unmap Address Window)
Form
MOVB

tUMPFQ,FIRQB+FQFIL

(set up parameters)

.PLAS

Function

The UMPFQ subfunction of ,PLAS unmaps a specified address window from a
resident library. (Note that a MAPFQ on an already mapped window unmaps the
existing windows,)
Privileges Required

None
Data Passed
FIRQ8
Octal MneOffset monic

Mne- Octal
monic Offset

I /I I I I I I /I I I I I I I /I I I I

1/1/1/1/1/

UMPFQ (= 12)

4 FQFIL

1/1/1/1/1/

window ID

6 FQPPN

I /I I I I I I 1/ I I I I I I I I I I I

I /I I I I I I 1/ I I I I I I 1/ I I I

/I I I I I I I 1/ I I I I I I /I I I I

I 1/ I I I I I 1/ I I I I I I 1/ I I I

I 1/ I I I I I 1/ 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 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 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 I I I I I I I I I

FIRQB+FQFIL

The function code UMPFQ (octal value equals 12),

FIRQB+FQPPN

The ID ofthe window t.o be unmapped (ret.urned at FIRQB+FQPPN
by t.he CRAFQ that created t.he window),

,PLAS-UMPFQ 3-161

Data Returned
FIROB
Octal MneOffset monic

Mne- Octal
monic Offset
I I I I I I I I I I I I I I I I III II

1/1/11/1/1

current job no. • 2

0
2 FOJOB

1/1/1/1/1/1/11111/1/1

I 1/ 1/ I 1/ 1/ I 1/ I I 1/ I I 1/

1/1/1/1/1/1/11111/11/

I 1/ I I I I I I 1/ I I I I I I I I I I

I II 1/ I 1/ I 1/ I 1/ / I 1/ 1/ I

1/1/1/1/1/1//11/1////

1/ I 1/ I 1/ I 1/ 1/ I / / 1/ / 1/

status flag

1/ 1/ 1/ 1/ / 1/ / / / / / 1/ / / /

1/ 1/ 1/ 1/ 1/ 1/ / / I I 1/ I / I

1/ 1/ 1/ I I I 1/ 1/ I I I 1/ / / /

1/1/1/11/1/1/////////

111111//11//// I / //1/ /

I 1/ / I I I I I / / I I / / I / / / / /

22 FOMODE

FIRQB+FQJOB

The current job number times two.

FIRQB+FQMODE

Bit 13 of this word is set if the unmapping was successful.

Errors
BADFUO

The window ID specified is invalid (not in the range 1 to 7).

NOSUCH

The window ID specified is in the range 1 to 7, but no such window is
currently created for the job.

Example
The following code unmaps the window whose ID is stored at WINID:
MOVB
MOVB
.PLAS

3-162

.PLAS-UMPFQ

#UMPFQ,FIRQB+FQFIL
WINID,FIRQB+FQPPN

;SET FUNCTION CODE

3.20 .POSTN -

Return Current Horizontal Position

Form

.POSTN
Function

The .POSTN directive retw-ns the maximum line width and the current horizontal position of devices for which this information is relevant (line printers and
terminals). Data is passed in the XRB defining the channel where the device is
currently opened. The information is retw-ned in the XRB.
Privileges Required

None
Data Passed

XRB

Mne- Octal
monic Offset

Octal MneOffset monic
I I I I I I I 1/ I I I I I I I I I I I I

111111111111111111111

I I II I I I I I I II I I I I I 1/ I I

1111111111

channel number' 2

I I II I I I I I I 1/ I I I I I I I I I

111/1111111/111111/11

I I 1/ I I I I I I 1/ I I I I I 1/ I I

XRB+XRCI

XRCI

Channel number times two; defines the channel on which the file
or device is open.

Data Returned

XRB

Octal MneOffset monic

Mne- Octal
monic Offset

1/1/11111/

maximum line length

1/1/111111

current position

o XRLEN
2

1/1111111/111111/1111

1/ I I I I I I 1/ I I I I I 1/ I I I I

1/ I /I I I I 1/ I I I I I I I I I I I

1/1111111/111111/1111

1/ I I I I I I 1/ I I I I I /I I I I I

XRBC

.POSTN

3-163

XRB+XRLEN

The file or device's maximum line length plus one. For example, a
value of 81. would indicate a maximum line length of 80. bytes.

XRB+XRBC

The file or device's current horizontal position is returned here.
The value can range from zero (leftmost character) to the value
returned at XRB+XRLEN minus one (rightmost character), If the
device does not keep track of its own horizontal position, then
this value is zero. The FLGPOS status bit returned in the FIRQB
when the file or device was opened indicates whether the value
returned here is meaningful.

Errors
NOTOPN

No file or device is open on the specified channel.

DETKEY

The device is a terminal that is detached.

Example
The following code requests the current horizontal position of the device open on
channel 4:
MOVB
.POSTN

3-164

.POSTN

#4*2,XRB+XRCI

;SET CHANNEL TO 4

3.21

.READ -

Read Data from File or Device

Form
.READ

Function
The .READ directive reads data from a file or device previously opened on a
channel. 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. Specific details for each device are
given in Table 3-5. The "best guess" buffer sizes (returned by the monitor at
FIRQB+FQBUFL when the device was opened) are also shown, for comparison.
When you do 110 to or from a resident library mapped in D-Space, such as a
dynamic region, you can use 110 buffer sizes larger than the greatest size that
can be mapped into the program's virtual address space. You can get single 1/0
block sizes up to 65,534 bytes (177776 octal). Note that not all devices can use
such large block sizes.
You only need to map the first word of the 1/0 buffer into the the virtual address
space, so the monitor can locate the buffer in the resident library. However, the
entire buffer must reside in the resident library; otherwise, the monitor rejects
the 110 request. This feature is available only for resident libraries mapped in
D-Space.

.READ

3-165

Table 3-5:

Data input with .READ
What Happens When
Block
Size, Bytes
(Decimal)

Device

''Best
Guess,"
Bytes
(Decimal)

.READ's
Intent to
Deliver

Buffer Size
>= Intent

Buffer Size
< Intent

Byte-Oriented Devices (FLGFRC=l, FLGRND=O)
Keyboard
(Terminal)

N/A

128

1 line 1

Fill buffer; next .READ
reads next part of line.

Pseudo
Keyboard

N/A

128

Full buffer

N/A

Paper Tape
Reader

N/A

128

Full buffer

N/A

Card Reader

N/A

160

1 card

Fill buffer;next .READ
reads next part of card.

Block-Sequential Devices (FLGFRC=O. FLGRND=l)
Magnetic
Tape

18 to 32,767

512

1 block

Fill buffer; next .READ
starts with new block.
(Error returned.)

DECtape
(filestructured)

510

1 block

Fill buffer; next .READ
starts with new block. (No
error returned.)

DMCIDMR

1 to 632

512

1 message

Delivers partial message.
Next .READ delivers next
message.

Block-Random Devices (FLGFRC=O. FLGRND=O)
Disk

18 to 32,767

512

Full buffer

Fills buffer; next .READ starts with new
block. 2

Flexible
Diskette

512

Full buffer

Fills buffer; next .READ starts with new
block or sector. 2

DECtape
(non-filestructured)

512

1 block

Fill buffer; next .READ
starts with new block. (No
error returned.)

lA line is any number of characters terminated by RETURN, LINE FEED, ESCAPE, FORM FEED, CtrlJZ, CtrllD,
CtrVC, or a user-set private delimiter.
2If the buffer size is not a multiple of the blocksize, the remainder of the last block is not read. The next .READ starts
with a new block: either the next sequential block (XRB+XRBLK=O) or the nth block (XRB+XRBLK=n). No error is
returned.
3512 (block mode) or 128 (RX01 or RX02 single-density sector mode) or 256 (RX02 double-density sector mode)

Privileges Required

None

3-166

.HEAD

Data Passed
XRB
Mne- Octal
monic Offset
size of the buffer in bytes, must <> 0

Octal
Offset

Mnemonic

XRLEN

(must be 0)

XRBC

starting address of buffer

XRLOC

XRCI

XRBLK

XRBLKM 7
11

MSB of block number

channel number' 2

LSB of block number to begin (0 = next)

wait time for terminal input

XRTIME

device-dependent modifier

XRMOD

XRB+XRLEN

The length of the input buffer, in bytes. This word must be
nonzero. The amount of data read depends on both the device
and the buffer size. However, the amount of data is never more
than the buffer size. See Table 3-5 for details on reads for specific
devices.

XRB+XRBC

This word must be passed as zero. The monitor returns the actual
number of bytes transferred in this word location (see the Data
Returned section).

XRB+XRLOC

The starting address of the buffer. For disk, flexible diskette, and
magtape devices, this address must be on a word boundary. For
all other devices, the buffer can begin on an odd address. (See
the section "XRB (Transfer Request Block)" in Chapter 2 for more
information.)

XRB+XRCI

Channel number times two; defines the channel for the read,
as previously defined in an open (OPNFQ, CRTFQ, CREFQ, or
CRBFQ functions of CALFIP).

XRB+XRBLKM

For files on disk, this byte contains the MSB of the block number
to begin the read. This byte is combined with the word at XRBLK
to form a 24-bit field defining the block number. This byte is
ignored for nondisk devices.

XRB+XRBLK

For channels opened as file-structured, this word defines the
starting block number for this read. (For large files, this word
forms the LSB of the block number to start the read.) The value
performs the same action as the BLOCK option for disk and
the RECORD option for flexible diskette and non-file-structured
DECtape (see the RSTS / E Programming Manual). Note that this
word is ignored if the device is not a random-access device.
If the device is random-access and this field is nonzero, it is
interpreted as the block number where the read is to start (1 to n,
where n is the length of the file, in 512-byte blocks). If the field
is zero, the next sequent.ial block is read. For example, if a disk
file is being read with a 1024-byte buffer size, a .READ with this
parameter equal to four would cause the fourth and fifth blocks of
the file (512 bytes each) t.o be read into the buffer.

.READ 3-167

For channels opened on disk as non-file-structured MODE 0, this
word defines the device cluster number where the read is to begin.
In this case, each .READ begins with a new device cluster, so the
buffer size at XRB+XRLEN should be a multiple of the device
cluster size.
XRB+XRTIME

If positive, the maximum time to wait for terminal input data, in
seconds. Zero indicates an infinite wait. A negative value (bit 15
equals 1) indicates an infinite keyboard monitor wait. This wait
is used by run-time systems that act as keyboard monitors for
their command input. This type of wait time acts as a flag to the
monitor and to the batch subsystem that the job is in a command
input wait state.

XRB+XRMOD

Input operation modifier; significant only for card reader, terminal,
DMCIDMR, or paper tape devices. (The monitor informs you with
the FLGMOD bit ofthe flag word returned at FIRQB+FQFLAG
on the open whether or not the device accepts modifiers.) This
parameter performs the same action as the RECORD modifier in
BASIC-PLUS for these devices (see the RSTSIE Programming
Manual).

Data Returned
XRB
Octal
Offset

Mne- Octal
monic Offset

111111111111111111111

actual number of bytes read

111111111111111111111

111/111111

LSB of block number where .READ began

111111111111111111111

XRBLKM7

XRB+XRBC

MSB of block number

Mnemonic

XRBC

XRBLK

Actual number of bytes just read. The value is between zero
and the value of XRB+XRLEN passed in the XRB. If an error is
returned on the read (as indicated by byte of the FIRQB), this
word mayor may not be zero. That is, data may be input even if
an error occurs. For example, if the card reader detects an illegal
card column punch combination, it places the decoded card data
in the input buffer, substituting a special character for the bad
column. The XRB+XRBC field is correctly set for the number of
characters input, and an error is returned.

3-168

.READ

XRB+XRBLKM

For disk files, this byte contains the MSB of the block number just
read. (See XRB+XRBLK)

XRB+XRBLK

For random-access devices (see TabJe 3-5), this word contains
the block number of the block just input with this .READ. Block
numbers range from 1 to n (where n is the length of the file,
in 512-byte blocks); they define the order in which the file was
written. (For disks opened non-file-structured MODE 0, this is the
device cluster number.)

Errors
The possible device-independent errors are:
BADCNT

The first three words of the XRB describing the input buffer are illegal.
(Illegal byte count for 110.)

BSERR

The specified channel number is illegal.

NOTOPN

No file or device is open on the specified channel number.

PRVIOL

The file or device open on the specified channel is write-only, or the caller
did not obtain read access to the file or device when it was opened.

All other errors are device-dependent. Some common errors are:
DATERR

Some data error occurred. There mayor may not be any valid data in the
input buffer. This error is issued for parity errors, bad card columns, and so
on.

HNGDEV

Some hard device 110 error occurred. There is usually no data in the input
buffer when this error occurs. (For example, a .READ for an off-line device
causes this error.)

Example
In this example, we assume that a disk file has been opened on channel 2.
Space for the buffer is allocated with the .BLKB directive, and the buffer size
and location are defined. The next sequential block in the file is to be read
(XRB+XRBLK is zero).
BUFFER:

.BLKB

512.

;ALLOCATE SPACE FOR BUFFER

CALL
MOV
MOV
MOVB
. READ

CLRXRB
i512., XRB+XRLEN
iBUFFER,XRB+XRLOC
i2*2,XRB+XRCI

;SET BUFFER SIZE TO 512. BYTES
;STARTING ADDRESS OF BUFFER
;CHANNEL 2 FOR INPUT

.READ

3-169

3.22 .READA-Read Data from a Device (Asynchronous)
Form
.READA

Function
The asynchronous read directive (.READA) perfonns the same basic functions
as the synchronous read directive (.READ): both move data between a device
and a user program. The difference lies in the completion of the request. While
synchronous read requests stall the job's execution until the request completes,
asynchronous read requests do not stall; the program continues to run while the
110 request completes in parallel with program execution. The mechanism that
the RSTS operating system uses to notify the user job upon 1/0 completion is an
asynchronous completion routine.
When you do 110 to or from a resident library mapped in D-Space, such as a
dynamic region, you can use 1/0 buffer sizes larger than the greatest size that
can be mapped into the program's virtual address space. You can get single 1/0
block sizes up to 65,534 bytes (177776 octal). Note that not all devices can use
such large block sizes.
You only need to map the :first word of the 110 buffer into the the virtual address
space, so the monitor can locate the buffer in the resident library. However, the
entire buffer must reside in the resident library; otherwise, the monitor rejects
the 1/0 request. This feature is available only for resident libraries mapped in
D-Space.

Privileges Required
TUNE is required to perfonn multiple asynchronous read functions.

3-170

.READA

Data Passed
FIROB
Mne- Octal
monic Offset

Octal
Offset

Mnemonic

II II II II / II / / II / / II / /

/ / II / / / / / II / / / / / / / / / /

Completion Routine Address

4 FOFIL

User-supplied parameter

6 FOPPN

/ / II / / / / / / / / / / / / / / / / /

II 1/ II II / 1/ / II / / / 1/ / /

II 1/ / II 1/ 1/ / II / / / 1/ / /

/ II II II / / 1/ / II / / / 1/ / /

II 1/ / II II 1/ / / / / / / 1/ / /

111/11/111//1111/1///

/111111111//11///1/11

/ II II II II / II II / / / /I / /

II /I / II / II / / / / / / / /I / /

111/1/1111/11/11/1///

1/ II / II / /I / / / / / II II / /

II 1/ II / II 1/ / / / / / / 1/ / /

FIRQB+FQFIL

Identifies the address in the user job where program flow should
begin when the asynchronous read completes. If FIRQB+FQFIL
is zero, no AST completion routine is executed. In this case, it
is understood that the user is using some other mechanism to
determine whether the I/O request has successfully completed.

FIRQB+FQPPN

This field is used by the user job to communicate information to the AST completion rout.ine with the user's program. If
FIRQB+FQFIL is zero, this value is ignored.
XRB

Mne- Octal
monic Offset
size of the buffer in bytes, must <> 0

Octal
Offset

Mnemonic

XRLEN

(must be 0)

XRBC

starting address of buffer

XRLOC

XRCI

XRBLKM7

MSB of block number

channel number * 2

LSB of block number to begin (0 = next)

XRBLK

wait time for terminal input

XRTIME

XRMOD

device-dependent modifier

.READA

3-171

XRB+XRLEN

The length of the input buffer, in bytes. This word must be
nonzero. The amount of data read depends on both the device and
the buffer size. However, the amount of data can never be more
than the buffer size. See Table 3-5 for details on reads for specific
devices.

XRB+XRBC

This word must be passed as zero. The monitor returns the actual
number of bytes transferred in this word location (see the Data
Returned section).

XRB+XRLOC

XRB+XRCI

Channel number times two; defines the channel for the read,
as previously defined in an open (OPNFQ, CRTFQ, CREFQ, or
CRBFQ functions of CALFIP).

XRB+XRBLKM

XRB+XRBLK

For channels opened as file-structured, this word defines the
starting block number for this read. (For large files, this word
forms the LSB of the block number to start the read.) The value
performs the same action as the BLOCK option for disk and
the RECORD option for flexible diskette and non-file-structured
DECtape (see the R8T8/E Programming Manual). Note that this
word is ignored if the device is not a random-access device.
If the device is random-access and this field is nonzero, it is
interpreted as the block number where the read is to start (1 to n,
where n is the length of the file, in 512-byte blocks). Ifthe field
is zero, the next sequential block is read. For example, if a disk
file is being read with a 1024-byte buffer size, a .READA with this
parameter equal to four would cause the fourth and fifth blocks of
the file (512 bytes each) to be read into the buffer.
For channels opened on disk as non-me-structured MODE 0, this
word defines the device cluster number where the read is to begin.
In this case, each .READA begins with a new device cluster, so
the buffer size at XRB+XRLEN should be a multiple of the device
cluster size.

XRB+XRTIME

XRB+XRMOD

Input operation modifier. For disk asynchronous reads, a value of
one in this byte indicates that a read check should be performed.
A read check does not transfer any data. The buffer address
specified in the XRB is compared with the data on the disk.

Data Returned on Completion of the Directive
No meaningful data is returned by the directive except for a possible error code in
byte 0 of the FIRQB. Useful data is returned instead to the completion routine.

3-172

.READA

Data Returned to the Completion Routine
FIRQB
Octal MneOffset monic

Mne- Octal
monic Offset

1111111111

error code

1111111111

job number * 2

111111111/1111111/111

User-supplied parameter

I II I I I I I II I I I I I I /I I I I

I II 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 I I I I I I /I I I I

11111111111111111/111

I II I I I I I II 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 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 1/ I I I I / I I I I I I

I II 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 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 / I / I /I / / I

FQJOB

FQPPN

XRB
Octal
Offset

Mne- Octal
monic Offset
11/1111111/111111/11/

actual number of bytes read

I /I I / I I I / /I / I I / / /I / I I

111/11111/

LSB of block number where .READ began

/ /I I I I I / / /I / / / / / I / I / I

I /I I / / / / / /I I I I I / /I / I I

XRBLKM7

MSB of block number

Mnemonic

XRBC

XRBLK

XRB+XRBC

Actual number of bytes just rea(l. The value is between zero
and the value of XRB+XRLEN passed in the XRB. If an error is
returned on the read (as indicated by byte 0 of the FIRQB), this
word mayor may not be zero. That is, data may be input even if
an error occurs.

XRB+XRBLKM

For disk files, this byte contains the MSB of the block number just
read. (See XRB+XRBLK)

.READA 3-173

XRB+XRBLK

For random-access devices (see Table 3-5), this word contains the
block number of the block just input with this .READA. Block
numbers range from 1 to n (where n is the length of the file,
in 512-byte blocks); they define the order in which the file was
written. (For disks opened non-file-structured MODE 0, this is the
device cluster number.)

Errors
There are three classes of errors that can cause the failure of an asynchronous
I/O request: directive errors; system-driver errors; and device-dependent errors.
Directive errors are immediately visible upon examination of the FIRQB on
return from the directive. These errors are similar to the syntax errors checked
by a compiler. If an error is found, the I/O is not attempted, and the error is
reported through the standard FIRQB+O mechanism. Some common directive
errors are:
BADCNT

The completion routine address is invalid or odd.

BSERR

The specified channel number is illegal.

NOTOPN

No file or device is open on the specified channel number.

PRVIOL

The file or device open on the specified channel is write-only, or the caller
did not obtain read access to the file or device when it was opened.

System-driver errors occur before the asynchronous request is issued to the appropriate device driver. These errors are related to the lack of system resources,
for example:
lNUSE

Too much outstanding I/O for the job, or the job does not have the TUNE
privilege and already has outstanding asynchronous I/O.

NOBUFS

The system could not get a small buffer for the request.

Any of the previous errors are reported on return from the .READA directive.
If none of these errors occurred, the read operation is started and the directive
returns a value of 0 in FIRQB+O. The read operation may still fail at a later
point; its success or failure is indicated in FIRQB+O when the completion routine
is entered.
Other system-driver errors are reported within the AST completion routine:
EOF

End-of-file (EOF) on the specified device.

NOROOM

No room for the user on the specified device.

Device-dependent errors can only be found during the attempt of the actual I/O
transfer. These errors can only be reported to the job in the asynchronous I/O
completion routine. Some common device-dependent errors are:
DATERR

Some data error occurred. There mayor may not be any valid data in the
input buffer. This error is issued for parity errors, bad card columns, and so
on.

HNGDEV

Some hard device I/O error occurred. There is usually no data in the input
buffer when this error occurs. (For example, a .READA for an off-line device
causes this error.)

Example

The following is an example of an asynchronous disk-to-disk copy. The program
initially issues three read requests (.READA, which requires the TUNE privilege
for multiple read operations) on the first disk and issues a corresponding write
request (.WRITA) on the second device when each .READA completes. Mter each
.WRITA completes, another advanced .READA is issued. Thus, there is always
one outstanding .READA and at least one outstanding .WRITA. Each new I/O
3-174

.READA

request within the routine uses the same buffer address as the request that has
just finished. This is an easy way to keep track of the free buffers.
Note that the program does not handle bad blocks efficiently; nor does it prompt
for the disk specifications. All errors are treated as fatal.
Register usage:
; R2 = Input block number
; R4 = Buffer number (carried in the user-created parameter field)
.PSECT

CODE

START:

CALL

CLRFQB

Clear FIRQB

Open input disk device = DLO:
MOVB
MOVB
MOV
MOV
MOV
CALFIP
MOV
BNE

tOPNFQ,FIRQB+FQFUN
Function code
t3*2,FIRQB+FQFIL
Set input channel = 3
t"DL,FIRQB+FQDEV
on an RL02
t377*400+0,FIRQB+FQDEVN
unit 0, device real
t200*400+8192.,FIRQB+FQMODE
read-only mode
Go for it
FIRQB,RO
Error?
FATAL
stop and check it out

Open output disk device = DLl:
MOVB
MOVB
MOV
MOV
CALFIP
MOV
BNE

tOPNFQ,FIRQB+FQFUN
t4*2,FIRQB+FQFIL
t"DL,FIRQB+FQDEV
t377*400+1,FIRQB+FQDEVN
FIRQB,RO
FATAL

Function code
Set output channel
4
on an RL02
unit I, device real
Go for it
Error?
stop and check it out

Issue the first three initial reads

10$:

CLRFQX

CALL
MOV
CLR
MOV

R2
tBUFFER,R4

MOV
CLR
MOV
MOVB
INC
MOV
MOV
MOV

t512., XRB+XRLEN
XRB+XRBC
R4,XRB+XRLOC
t3*2,XRB+XRCI
R2
R2,XRB+XRBLK
tR$AST,FIRQB+FQFIL
R4,FIRQB+FQPPN

B,Rl

MOV
BNE
ADD
SOB

FIRQB,RO
FATAL
t512.,R4
Rl,10$

Set buffer size to 512.
XRBC = 0
Set our next buffer address
Input channel times 2
Next input block number
Read that block
Go to R$AST after read
User-created parameter
Do an asynchronous read
Directive error?
Yes, stop
Get next buffer address
Issue next read-ahead

MOV
. SLEEP
BR

UOOOOl, XRB+O

Conditional sleep

20$

and do that until done

.READA

20$:

Clear FIRQB & XRB
1 read + 2 read-aheads
Start at virtual block zero
Load 1st buffer address

;All .READA's come here at completion time
R$AST:

MOV
BEQ
CMPB
BEQ
BR

FIRQB,RO
60$
U3,RO
CLSIN
FATAL

Error?
No, continue
End-of-disk (EOD) ?
Yes, close I/O disks
No, unexpected error, stop

.READA 3-175

60$:

MOV
MOV
MOV
MOVB

#512., XRB+XRLEN
#512., XRB+XRBC
FIRQB+FQPPN,XRB+XRLOC
#4 *2, XRB+XRCl;

MOV
.WRITA
BR

#W$AST,FIRQB+FQFIL
ASTDON

Reset buffer size
Want to write entire buffer
Use the same buffer address
Output channel * 2
XRBLK has block number
Completion routine address
Write that block
Join the common code

All .WRITA's come here at completion time
W$AST:

MOV
BEQ
CMPB
BEQ
BR

FIRQB,RO
70$
#13,RO
CLSIN
FATAL

Error?
No, continue
End-of-disk (EOF) ?
Yes, close I/O disks
No, unexpected error, stop

70$:

MOV
CLR
MOV
MOVB
INC
MOV
MOV

#512., XRB+XRLEN
XRB+XRBC
FIRQB+FQPPN,XRB+XRLOC
#3*2,XRB+XRCI
R2
R2,XRB+XRBLK
#R$AST,FIRQB+FQFIL

Set buffer size
XRBC = zero
Use the same buffer address
Input channel * 2
Increment to next block
XRBLK has block number
Completion routine address
Read that block
Join the common code

.READA

ASTDON

AST common code

3-176

.READA

ASTDON:

MOV
BNE
.ASTX

.SBTTL
.ENABL

FIRQB/XRB clearing routines
LSB

CLRFQX:

PUSH
MOV
MOV
BR

<RO,R1>
#FIRQB,RO
#«FQBSIZ+XRBSIZ>/2>,R1
200$

CLRFQB:

PUSH
MOV
MOV
BR

<RO,R1>
; Save RO, R1
#FIRQB,RO
; Point to FIRQB
#<FQBSIZ/2>,R1; Compute how many words
200$

CLRXRB:

PUSH
MOV
MOV

<RO,R1>
; Save RO, R1
#XRB,RO
; Point to XRB
#<XRBSIZ/2>,R1; Compute how many words

FIRQB,RO
FATAL

Any directive errors
Yes, stop
No, just return to mainline

Save RO, R1
Point to FIRQB
Compute how many words

200$:

CLR
SOB
POP
RETURN

(RO) +
R1,200$
<R1,RO>

Zero it out
Until all done
Restore RO, R1

Errors (code in RO) come here
FATAL:
OUT:

All errors come here
All done

BPT
.EXIT

; Close input disk (may still have outstanding .READAs)
CLSIN:

CALL
MOVB
MOVB
CALFIP

CLRFQB
tCLSFQ,FIRQB+FQFUN
t3*2,FIRQB+FQFIL

Clear FIRQB
CLOSE function
Set channel = 3
Do it

Close output disk (may still have outstanding .WRITAs)
CLSIN:

CALL
MOVB
MOVB
CALFIP
BR

.PSECT

DATA

BUFFER:

. BLKB
.BLKB
. BLKB

BUFEND:
. END

CLRFQB
tCLSFQ,FIRQB+FQFUN
t4*2,FIRQB+FQFIL
OUT

512 .
512.
512 .
; Address for EOB

Clear FIRQB
CLOSE function
Set channel = 4
Do it
Then, exit

Buffer one
Buffer two
Buffer three

START

.READA 3-177

3.23 .RTS -

Pass Control to Run-Time System

Form
.RTS

Function
The .RTS directive passes control to a run-time system at the P.NEW entry point,
where the intent is not to run an executable file (see Chapter 2). .RTS performs
one of four functions:
•

Passes control to the job's keyboard monitor

•

Passes control to a named run-time system

•

Passes control to a named run-time system and establishes it as the job's
keyboard monitor

•

Passes control to a named run-time system without changing job context
information

The first function is generally part of a run-time system's exit processing; you do
not normally use .RTS for this purpose in a user program. The following code
shows how .RTS is used in exit processing (for example, in the RT-ll run-time
system's .EXIT directive):
EXIT:

CALL
.RTS

CLRFQB

JMP

PROMPT

Clear FIRQB
Exit to default KBM
If that's this KBM, then
prompt for another command

The other three functions of .RTS apply to both user programs and run-time
systems.
Note that once established, a job's keyboard monitor replaces the default keyboard
monitor as the one to which control passes by default. This concept is best
explained by example.
The SET JOBIKEYBOARD_MONITOR command uses the .RTS directive to
establish the run-time system to which it passes control as the job's keyboard
monitor (see the RSTS/E System Manager's Guide). Consider the following
sequence:
$ SET JOB/KEYBOARD_MONITOR=RTll
• MAC
MAC>CTRL/C
.CTRL/C
.$SET JOB/KEYBOARD_MONITOR

The first line shows the DCL prompt ($), indicating that the user is in the DCL
keyboard monitor. Then:

1. The user executes the SET JOBIKEYBOARD_MONITOR command to pass
control to the RT-ll run-time system. This command establishes RT-ll as
the job's keyboard monitor. The RT-ll run-time system displays the period
prompt.
2. The user runs MAC, the RSX assembler. Control passes to the RSX emulator,
which loads the assembler and runs it. MAC displays the "MAC>" prompt.
3. The user, realizing the mistake in typing MAC instead of MACRO, enters
CtrJlC to exit. Since RT-ll has been established as the job's keyboard monitor,
control passes back to RT-ll, and it displays the period prompt.
3-178 .RTS

4. The user, wanting to get back to DCL, enters another CtrllC. Since RT-ll is
the job's keyboard monitor, however, another period prompt appears.
5. The user finally issues the SET JOB/KEYBOARD_MONITOR command (with
the $ prefix to indicate that it is a DCL command), leaving out the run-time
system name. This command transfers control back to the system default
keyboard monitor (DCL), establishing it once again as the job's keyboard
monitor.
The four cases in which the .RTS directive can be used are:
•

In the first case, the .RTS directive is used to switch control back to the
run-time system already established as the job's keyboard monitor. In this
case, the name of the run-time system is not known. The word in the FIRQB
that would contain the first part of the run-time system name is zero. If the
run-time system that issues the .RTS is not itself the job's keyboard monitor,
or the currently running program is a privileged program, control is passed to
the job keyboard monitor at entry point P.NEW. If the run-time system that
issues the .RTS is the job's keyboard monitor and the current program is not
a privileged program, control returns to the instruction following the .RTS
with no error indicated.

•

In the second case, the .RTS directive is used to switch control to the runtime system named in the FIRQB. (Run-time systems are made known to the
monitor by the system manager with the INSTALURUNTIME_SYSTEM command. With this command, the system manager defines a file (filename.RTS)
as an auxiliary run-time system. The monitor regards "filename" as the runtime system's name.) If the run-time system that issues the .RTS directive
is not itself the named run-time system, or the currently running program
is a privileged program, control passes to the named run-time system at the
P.NEW entry point. If the run-time system that issues the .RTS directive
is the named run-time system and the current program is not a privileged
program, control returns to the instruction following the .RTS with no error
indication. If the named run-time system does not exist or is not available
for some reason, control returns to the instruction following the .RTS with an
error in byte 0 of the FIRQB.

•

In the third case, the .RTS directive is used to switch control to a named
run-time system and establish it as the job's keyboard monitor. If the runtime system that issues the .RTS is not itself the named run-time system,
or the currently running program is a privileged program, control passes
to the named run-time system at the P.NEW entry point, and the named
run-time system is established as the job's keyboard monitor. If the runtime system that issues the .RTS names itself as the run-time system and the
current program is not a privileged program, control returns to the instruction
following the .RTS with no error, and the run-time system is established as
the job's keyboard monitor. If the named run-time system does not exist or
is unavailable, control returns to the instruction following the .RTS with an
error in byte 0 of the FIRQB.

•

In the fourth case, the .RTS directive is used to switch control to a named
run-time system preserving the job's current job-context information. Control
passes to the named run-time system at the P.NEW entry point, but the
monitor does not refresh the keyword, reset the stack pointer, or perform any
of the initialization operations (see the discussion of P.NEW in Chapter 2) .

.RTS

3-179

In the first three cases, if the program cWTently running had temporary privileges in effect at one time (whether it has since dropped them or not), then the
transfer of control to the P.NEW entry point is unconditional. In addition, all of
the user's memory above NSTORG is cleared to ensure any restricted data kept
by the program is erased from memory. Finally, the monitor drops temporary
privileges.
NOTE

Do not use this directive from programs running under the RT-ll
run-time system, because RT-ll uses the lowest 512 bytes differently
than other run-time systems. The correct way to terminate a program
running under RT-ll is to exit through the RT-ll emulator.
Although you can use this directive to terminate a program running
under the RSX run-time system, Digital recommends that you use the
RSX EXIT$ or EXST$ directive instead (see Chapter 5). Using .RTS
may cause unexpected results.
Privileges Required

None
Data Passed
FIROB
Mne- Octal
monic Offset

3-180 .RTS

Octal MneOffset monic

////1////////////////

/////////////1//////1

////1///////////////1

/////////////////////

run-time system name

10 FONAM1

(2 words of RAD50)

12
14 FOEXT

-1, Switch Kbm.; -2, don't change context

////////////////////1

////1////////1//////1

////////////1//////1/

/ / / / 1// / / / / / / / / / / / / / /

/////////////1/////1/

////1///////1////////

////1////////////////

FIRQB+FQNAMI

If control is being passed to a named run-time system (cases 2, 3,
and 4 described previously), the name of the run-time system is
stored as two words in RAD50 format beginning here. If control
is being passed to the job's keyboard monitor (case 1), the word
beginning here must contain a value of zero.

FIRQB+FQEXT

To establish a named run-time system as the job's keyboard
monitor (case 3), set this word to -1. To switch control to a named
run-time system without altering job-context information (case 4),
set this word to -2. When the word at FIRQB+FQNAMI is zero,
this word is ignored.
XRB
Octal MneOffset monic

Mne- Octal
monic Offset
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 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 I I I I I

11
13

10 XRBLK
unaltered whether or not
control passes to new run-time system

XRB+XRBLK

12
14

The three words starting at this location pass unaltered to the
new run-time system. They are also unaltered if control returns
in line.

Data Returned

Since control usually passes to some other run-time system at its P.NEW entry
point, no arguments as such are returned by .RTS. The three words starting at
XRB+l0 remain unaltered if control returns in line.
Errors
NORTS

No run-time system exists with the specified name.

PRVIOL

The named run-time system does exist but cannot be switched to for some
reason. (For example, if the switch is made to a named run-time system
with the intent of establishing it as the job's keyboard monitor and its
PF.KBM bit in the P.FLAG word is not set to 1.)

Example

The following example establishes NEWRTS (which the system manager must
have installed with INSTALURUNTIME_SYSTEMIKEYBOARD_MONITOR
command) as the job's keyboard monitor:
MOV
MOV
MOV
.RTS

#ARNEW,FIRQB+FQNAMl
#ARRTS,FIRQB+FQNAM1+l
#-l,FIRQB+FQEXT

Set run-time system
Name to "NEWRTS"
Establish as job kbm

.RTS

3-181

3.24 .RUN -

Run a Program

Form

.RUN
Function

The .RUN directive searches for a binary (executable) file (defined in the FIRQB),
opens it on channel 15, and passes control to the P.RUN entry point of the runtime system associated with the file. The associated run-time system is identified
in the file's directory information. This directory information is initially set to
indicate the run-time system under which the file was created. The system
manager can change the run-time system associated with the file with the SET
FILEIRUNTIME_SYSTEM command (see the RSTS / E System Manager's Guide).
The run-time system is responsible for loading and executing the file (see the
P.RUN description in Chapter 2). Control is not returned in line unless an error
occurs. The monitor drops any temporary privileges in effect under the previously
running program.
Privileges Required

File execute access required; either by protection code or privilege (GREAD or
WREAD).
Data Passed
FIR08
Mne- Octal
monic Offset

/ / / /I / / / / / / / / / / / / / / / /

/ / / /I / / / / / /I / / / / / / / / /

/ / / /I / / / / / / / / / / / / / / / /

FOPPN
FONAM1

.RUN

project number

programmer number

file name in RAD50 format

(2 words)

file type in RAD50 format (1 word)

/ / / /I / / / / / / / / / / / / / / / /

/ / / 1/ / / / / / /I / / / / / / / / /

/ / / /I / / / / / / / / / / / / / / / /

device name (2 ASCII characters)

FODEV

FQDEVN

3-182

Octal MneOffset monic

<>0, unit no. real

device unit number

/1//1////////////1///

entry parameter

FOEXT

FONENT

FIRQB+FQPPN

The PPN of the file to be opened. The project number is specified
in the high byte, the programmer number in the low byte. If this
word is passed as zero, the PPN defaults to the PPN of the job
that issues the .RUN directive.

FIRQB+FQNAMI

The file name of the file to be opened; two words in RAD50 format.

FIRQB+FQEXT

The file type for the file to be opened; one word in RAD50 format.
If you set this word to -1, the monitor will search for the file
name supplied, substituting the default file type for the currently
installed set of run-time systems until a file with the given name
and one of the default file types is found.

FIRQB+FQDEV

The device name of the file to be opened, as two ASCII characters.
If the device name is not a disk, the .RUN directive returns in line
with one of the soft. errors described in the Errors section. If you
pass a full word of zero here and in FIRQB+FQDEVN, the public
disk structure (SY:) is searched for the named file.

FIRQB+FQNENT

A 16-bit parameter word can be passed to the run-time system
here. If the calling program has temporary privileges in effect,
bit 15 is unchanged. Otherwise, bit 15 is cleared. The monitor
takes no other action as a result of the contents of this word; any
processing is up to the run-time system. (See the P.RUN entry
point, Chapter 2.)

Errors
When an error occurs in a .RUN, FIRQB+FQFLAG is set to zero to indicate a
hard error or -1 to indicate a soft error.
A hard error means the .RUN failed. A soft error also means the .RUN failed,
but the run-time system may be able to recover. For example, when you use the
BASIC-PLUS RUN command, BASIC-PLUS first executes a .RUN. If the .RUN
returns a soft error, BASIC-PLUS performs an OLD (which compiles the program)
and then executes .RUN again.
Hard Errors
BADNAM

The specified file name was zero. This is an illegal file name for disk files.

DEVNFS

The specified disk device is currently being used non-file-structured.

NOTCLS

Channel 15 is currently open. It must be closed before any .RUN call. (This
error occurs only if channel 15 is open on a nondisk device. If a disk file is
open, the channel is closed automatically.)

NODEVC

The specified device does not exist or is in an illegal format.

NORTS

The run-time system named in the file's directory information has not been
installed.

NOTMNT

The specified disk device is not now mounted.

PAKLCK

The disk pack on which the file exists is locked against further file opens.

Soft Errors
NOSUCH

The file was not found. Note that if FIRQB+FQEXT was -1 in the data
passed, the monitor has looked for the given file name with all default
runnable file types for the currently installed run-time systems. In this
case, a source version of the tile may still exist.

PRVIOL

The device is not disk but is still a legal device on the system. Or the file
was found and is on disk but. does not have the compiled program bit set in
its file protection code (bit 6).

.RUN

3-183

Example

The following example uses the .FSS directive to translate a user-typed string
to the FIRQB format. If no errors in the .FSS occur, a test is made to see if a
file type was specified. If not, a -1 is supplied in FIRQB+FQEXT so the monitor
searches for the given file name with an possible default file types that are
runnable.
(read user-typed line, set up FIRQB for .FSS)

SKIPl:

3-184

.RUN

.FSS
TSTB
BNE
BIT
BNE
BIT
BNE
MOV
CLR
. RUN

FIRQB
ERRTN
tlOOOOO,XRB+XRBLK
BADDEV
tlO,XRB+XRBLK
SKIPl
t-l,FIRQB+FQEXT
FIRQB+FQNENT

Error on .FSS?
Branch to process error
Invalid device name?
Branch to process error
File type given?
Yes, skip next
No, search all
Entry parameter is zero

3.25 .SET - Set Keyword Bits
Form
.SET

Function
The .SET directive sets certain bits in the keyword (KEY) location in the user job
image (see Chapter 2). The bits to be set are passed to the monitor in the XRB.

Privileges Required
TUNE is required to set the special run priority bit (JFSPRI) or the lock in
memory bit (JFLOCK).

Data Passed
XRB
Mne- Octal
monic Offset

Octal MneOffset monic
bits to be set are set to 1 here

o XRLEN

1/ 1/ 1/ 1/ 1/ / 1/ / 1/ / / / I /

/ / / / 1/ 1/ 1/ 1/ / / 1/ / / / 1/

1/ 1/ 1/ 1/ / / 1/ / / 1/ / / / / /

1/1/1/1/1/1/1/1////1/

1//1/1/1/1//1/1//////

/ / / / / / 1/ / / / / / / / / / / / / /

JFSPRI
JFFPP
JFPRIV

JDFSTM

JFSYSll

JFNOPR

JFLi6~lll
15

JFLOCK

Can be set only by jobs with TUNE privilege. When this bit is set, the
monitor swaps the user job image out of memory only when:
•

The job issues a .CORE directive to expand the memory allocated for
the user job image, and there is not sufficient room in physical memory
to do the expansion. In this case, the job is swapped out to disk and
back in at the indicated size.
A fatal error, such as a memory parity failure, occurs.

.SET 3-185

JFBIG

Cannot be set by any job; masked off, that is, the corresponding bits in KEY
cannot be set by the job with the .SET direct.ive.

JFNOPR

Cannot be set by any job; masked off.

JFSYS

Can be set by a job only if JFSYS was set at one time and the temporary
privileges gained were only temporarily dropped. (See description of KEY,
Chapter 2 and the .CLEAR directive.)

JFPRIV

Cannot be set by any job; masked off.

JFFPP

Can be set by any caller ifthe PDP-1l/45 compatible hardware floating-point
unit exists; masked off if it does not exist. When this bit is set, the monitor
will save information in the floating-point unit as part of the job-context
information kept when jobs are swapped in and out of memory.

JFSPRI

Can be set only by a caller with TUNE privilege. Setting JFSPRI raises
the job's run priority by one-half step. (That is, it sets bit 2 of the systemcontrolled low-order three bits of the run priority. Priorities are normally
set by the system manager.)

JDFSTM

Can be set by any caller. Enables the fast-mapping facility for the current
job. If you set this bit, clear all the others.

All other bits in the XRB word are masked off.

Data Returned
The .SET directive does not return any meaningful data.

Errors
No errors are possible with the .SET directive.

Example
The following code sets JFLOCK, allowing the job to remain locked in memory:
MOV
.SET

3-186

.SET

#JFLOCK,XRB+XRLEN

;SET JFLOCK

3.26 .SLEEP -

Suspend Job

Form
.SLEEP

Function
The .SLEEP directive causes the monitor to suspend the job for some specified
time interval or until an event occurs that the job should be aware of. Optionally,
the monitor checks, before the job is suspended, to see if some event has already
occurred which would cause it to awaken. If so, the job is not suspended. Control
returns in line in either case.
When a .SLEEP is executed, execution of the job is suspended until one of the
following happens:
•

The sleep time (specified in the XRB) expires.

•

A local or network message is queued for the job assuming that the job is
using local or network send/receive services. (See the .MESAG directive.)

•

A delimiter is typed on a terminal that this job has opened or assigned.

•

The system manager disables logins. (This could occur if the system is being
shut down.)

•

A state change occurs on a pseudo keyboard assigned to the job. (The job has
printed output for the controlling job to read or has entered an input wait
state.)

•

The DMClllDMRll driver (XM:) is open and a message is pending for the
job.

•

Ail AST completion is queued.

•

The system time is changed.

If you request it, the monitor checks for the following conditions before suspending the job:

•

A delimiter has been typed on any terminal opened by the job or any terminal
assigned to the job if the job also has a keyboard open on a nonzero channel.

•

A message has been queued for the job.

•

A state change has occurred on a pseudo keyboard opened by the job.

•

The job has a DMClllDMRll device driver open and a message has been
received by that device driver.

•

One or more AST completion routines are pending.

If the monitor determines that any of these conditions are true, it does not
execute the .SLEEP. This feature is known as conditional sleep.

.SLEEP 3-187

Data Passed
XRB
Mne- Octal
monic Offset

Octal MneOffset monic
sleep time, in seconds

o XRLEN

111111111111111111111

I I I I I I /I II I I I I I I I I I I I

XRB+XRLEN

This word defines the sleep interval, in seconds. If the value is
zero, then .SLEEP returns immediately. If bit 15 is set, the monitor performs the conditional sleep checks. If any of the previously
listed conditions are present, the .SLEEP is not executed.

Data Returned
The .SLEEP directive does not return any meaningful data.

Errors
No errors are possible with the .SLEEP directive.

Example
MOV

. SLEEP

3-188

.SLEEP

:fI:5,XRB+XRLEN

Set timer to 5 seconds

3.26 .SLEEP -

Suspend Job

Form

.SLEEP
Function

The .SLEEP directive causes the monitor to suspend the job for some specified
time interval or until an event occurs that the job should be aware of. Optionally,
the monitor checks, before the job is suspended, to see if some event has already
occurred which would cause it to awaken. If so, the job is not suspended. Control
returns in line in either case.
When a .SLEEP is executed, execution of the job is suspended until one of the
following happens:
•

The sleep time (specified in the XRB) expires.

•

A local or network message is queued for the job assuming that the job is
using local or network send/receive services. (See the .MESAG directive.)

•

A delimiter is typed on a terminal that this job has opened or assigned.

•

The system manager disables logins. (This could occur if the system is being
shut down.)

•

A state change occurs on a pseudo keyboard assigned to the job. (The job has
printed output for the controlling job to read or has entered an input wait
state.)

•

The DMClllDMRll driver (XM:) is open and a message is pending for the
job.

•

An AST completion is queued.

•

The system time is changed.

If you request it, the monitor checks for the following conditions before suspending the job:
•

A delimiter has been typed on any terminal opened by the job or any terminal
assigned to the job if the job also has a keyboard open on a nonzero channel.

•

A message has been queued for the job.

•

A state change has occurred on a pseudo keyboard opened by the job.

•

The job has a DMClllDMRll device driver open and a message has been
received by that device driver.

•

One or more AST completion routines are pending.

If the monitor determines that any of these conditions are true, it does not
execute the .SLEEP. This feature is known as conditional sleep.

.SLEEP

3-187

Data Passed
XRB
Octal MneOffset monic

Mne- Octal
monic Offset
sleep time, in seconds

o XRLEN

I I I I I I /I I I I I I I I I I I I I I

XRB+XRLEN

This word defines the sleep interval, in seconds. If the value is
zero, then .sLEEP returns immediately. If bit 15 is set, the monitor performs the conditional sleep checks. If any of the previously
listed conditions are present, the .sLEEP is not executed.

Data Returned

The .SLEEP directive does not return any meaningful data.
Errors

No errors are possible with the .SLEEP directive.
Example
MOV
. SLEEP

3-188

.SLEEP

#5,XRB+XRLEN

Set timer to 5 seconds

3.26 .SLEEP -

Suspend Job

Form

.SLEEP
Function

The .SLEEP directive causes the monitor to suspend the job for some specified
time interval or until an event occurs that the job should be aware of. Optionally,
the monitor checks, before the job is suspended, to see if some event has already
occurred which would cause it to awaken. If so, the job is not suspended. Control
returns in line in either case.
When a .sLEEP is executed, execution of the job is suspended until one of the
following happens:
•

The sleep time (specified in the XRB) expires.

•

A local or network message is queued for the job assuming that the job is
using local or network send/receive services. (See the .MESAG directive.)

•

A delimiter is typed on a terminal that this job has opened or assigned.

•

The system manager disables logins. (This could occur if the system is being
shut down.)

•

A state change occurs on a pseudo keyboard assigned to the job. (The job has
printed output for the controlling job to read or has entered an input wait
state.)

•

The DMClllDMRll driver (XM:) is open and a message is pending for the
job.

•

An AST completion is queued.

•

The system time is changed.

If you request it, the monitor checks for the following conditions before suspending the job:
•

A delimiter has been typed on any terminal opened by the job or any terminal
assigned to the job if the job also has a keyboard open on a nonzero channel.

•

A message has been queued for the job.

•

A state change has occurred on a pseudo keyboard opened by the job.

•

The job has a DMClllDMRll device driver open and a message has been
received by that device driver.

•

One or more AST completion routines are pending.

If the monitor determines that any of these conditions are true, it does not
execute the .SLEEP. This feature is known as conditional sleep.

.SLEEP

3-187

Data Passed
XRB
Octal MneOffset monic

Mne- Octal
monic Offset
sleep time, in seconds

o XRLEN

/ / / / / / II / / / / / / II / / / / /

/ / / / / / II / / / / / / II I / / / /

/ / / / / / II / / / / / / II / / / / /

/ / / / / / II / / / / / / 1/ / / / / /

/ / / / / / II / / / / / / II / / / / /

XRB+XRLEN

Data Returned
The .sLEEP directive does not return any meaningful data.
Errors
No errors are possible with the .sLEEP directive.
Example
MOV
. SLEEP

3-188

.SLEEP

#S,XRB+XRLEN

Set timer to 5 seconds

3.27 .SPEC-Special Functions for 1/0
Form

(set XRB for special function)

.SPEC

Function

The .SPEC directive performs special functions for:
•

Disks

•
•
•
•

Flexible diskettes
Line printers
Magnetic tapes
Pseudo keyboards

• Terminals

•

Ethernet devices

.SPEC 3-189

3.27.1

.SPEC for Disk
For disk, the .SPEC directive lets you explicitly lock up to seven disk blocks on
a file open for update (mode parameter). A locked block cannot be accessed by
another user (or from another channel). This extends the implicit lock feature, by
which the last block or blocks read on a file open for update cannot be accessed by
anyone else. The disk special functions also let you release explicit and implicit
locks. (All locks, both explicit and implicit, are released when the file is closed.)
There are also two other .SPEC options:
•

Perform a comparison operation between the contents of a buffer and one or
more blocks of a disk file.

•

Truncate a file on an open channel.

Privileges Required

None
Data Passed (Disk-Except Compare and Truncate)

XRB
Mne- Octal
monic Offset

XRBLKM

3-190

.sPEC-Disks

Octal
Offset

Mnemonic

special function code

XRLEN

. LSB of block number (release)

XRBC

XRLOC

XRCI

1/1/1/1/1/

DSKHND (=octal 0)

MSB of block no. (rl)
channel number· 2

111111111111111111111

XRB+XRLEN

Defines function to be perfonned:
Code
Meaning

Release any implicit lock and all explicit locks. The
monitor deallocates the extended internal t.able space
it needed to do the explicit locks. (See code 3.)

Release implicit lock.

Make implicit lock into explicit lock.

Release the explicit lock on the block specified by
the word at XRB+XRBC (LSB) and the byte at
XRB+XRLOC (MSB). If all three bytes are zero, all
explicit locks are released, but the monitor does not
deallocate t.he extra space needed to do explicit locks.
(This is useful if you intend to use the explicit lock
feature again during this run. An error occurs if no
space is available for this purpose.)

Make implicit lock into explicit lock and release the
implicit lock.

Truncate the file on channel * 2 (XRB+XRCl) at the
block number briven in XRB+XRBC and XRB+XRLOC.

XRB+XRBC
XRB+XRLOC

Both these bytes specifY the starting block number for releasing
an explicit lock. If these byt.es are zero, all explicit locks are
released, but t.he monit.or ret.ains t.he extended table area it needs
to maintain these locks. (This is useful if you want to use this
capability again during a run.)

XRB+XRCI

Channel number times two; defines the channel for the lock/unlock
operation.

XRB+XRBLKM

Handler index for disk: DSKHND (octal value = 0).

Data Passed (Disk-Compare)
XRB
Mne- Octal
monic Offset

Octal
Offset

Mnemonic

XRLEN

-1

XRBLKM

buffer size

XRBC

buffer address

XRLOC

XRCI

XRBLK

channel number' 2

DSKHND (=0)

LSB of block number to begin compare

13
15

///////////////////1/

//////////

MSB of block number

XRMOD

XRB+XRBC

Size of the data buffer to be compared.

XRB+XRLOC

Address of the data buffer to be compared.

XRB+XRBLK

LSB of the first block number on the disk to be compared with the
data buffer.

XRB+XRMOD

MSB of the first block number on t.he disk to be compared with
the data buffer.

.SPEC-Disks

3-191

Data Passed (Disk-Truncate)

XRB
Octal
Offset

Mnemonic

XRLEN

111111111111111111111

XRBC

1111111111111///1111/

XRLOC

XRCI

XRBLK

Mne- Octal
monic Offset

XRBLKM

DSKHND (=0)

channel number' 2

LSB of block number to become last block

13
15

/111//1///////////11/

//////////

MSB of block number

XRMOD

XRB+XRBLK

LSB of the block number on the disk to become the last block of
the file.

XRB+XRMOD

MSB of the block number on the disk to become the last block of
the file.

Data Retu rned

Except for a possible error code in byte 0 of the FIRQB, the disk subfunctions of
.SPEC do not return any meaningful data.
Errors

For subfunction code 1:
DATERR

The data in the buffer does not match the data on the disk.

For subfunction code 2:
INTLCK

Occurs if the implicit lock overlaps any current explicit lock. For example, if
you read blocks 1 and 2 into a l024-byte buffer in update mode, an implicit
lock exists on blocks 1 and 2. If you explicitly locked these blocks, and then
read blocks 2 and 3 and tried to explicitly lock blocks 2 and 3, you would get
this error. An exact match is legal (for example, if the second read also read
blocks 1 and 2) and results in a no operation.

NOBUFS

Occurs if the monitor needs to expand its internal table space but memory
is not available.

NOROOM

There are already seven explicit locks on this channel.

PRVIOL

There is no current implicit lock; that is, no blocks have been read.

For subfunction code 3:
NOSUCH

3-192 .sPEC-Disks

The block number specified does not correspond to the first block number of
an explicit lock.

3.27.2

.SPEC for Ethernet Interface
The following functions allow the user to manipulate and monitor the Ethernet
interface.

3.27.2.1

Set New Physical Address

The Set New Physical Address .SPEC function changes the physical address of
the Ethernet controller.
The following figure illustrates the Physical Address Buffer:

byte 1

byte 0

byte 3

byte 2

byte 5

byte 4

NOTE

This call succeeds only if the portal requesting the physical address
change is the only portal currently open on the controller. The Set
Physical Address .SPEC function requires SWCTL privilege.
Data Passed

XRB
Mne- Octal
monic Offset
special function code

XRBLKM

(-4)

Octal
Offset

Mnemonic

XRLEN

must be 6

XRBC

starting address

XRLOC

XRCI

ETHHND (= octal 50)

channel number' 2

/ / / / / II / / / / / / II / / / / / /

/ II / / II / / / / / / II / / / / / /

XRB+XRLEN

Special function code -4; defines function to be performed.

XRB+XRBC

Must be 6, denoting a 6-byte physical address.

XRB+XRLOC

Starting address of the Physical Address Buffer.

XRB+XRCI

Channel number times two; defines the channel.

XRB+XRBLKM

Device handler index: ETHHND.

.SPEC-Ethernet 3-193

The following errors may occur on a Set Physical Address call:
Errors

3.27.2.2

BADCNT

XRBC not equal to six, can't be a valid physical address.

BADNAM

Invalid physical address (Least Significant Bit must be 0).

HNGDEV

Controller is disabled or inoperative.

INUSE

Other portals are currently open on the controller.

PRVIOL

You do not have appropriate privilege (SWCTL).

Enable Multicast Addresses

Use the Enable Multicast Addresses function to let the portal and controller
receive multicast messages. 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.
The following figure illustrates the User Multicast Buffer:

byte

byte 0

byte 3

byte 2

byte 5

byte 4

byte

byte 0

byte 3

byte 2

byte 5

byte 4

byte

byte 0

byte 3

byte 2

byte 5

byte 4

User Multicast Address

User Multicast Address
(N is an integer < = 5)

(N ·6-2)

The addresses are loaded into the user buffer with the least significant byte
loaded in Byte 0 of the address block and the most significant byte loaded in Byte
5 of the address block.
Each portal can have a maximum of five six-byte multicast addresses. Each time
the Enable Multicast Address call is issued, the new addresses supersede the old
list.
You can specify a null list (by issuing the call with XRBC = 0) that will supersede
the old list, thus disabling all multicast reception for that portal.

3-194 .sPEC-Ethernet

Data Passed
XRB
Mne- Octal
monic Offset

Octal
Offset

Mnemonic

XRLEN

XRBC

starting address

XRLOC

XRCI

special function code

(-3)

number of multicasts • 6 bytes

3
5

ETHHND (= octal 50)

XRBLKM7

channel number· 2

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

XRB+XRLEN

Special function code -3; defines function to be performed.

XRB+XRBC

Number of multicasts times 6 (byte count of buffer). Maximum
size is 30 bytes. You can issue a byte size of zero to remove all
enabled multicasts from the portals list without replacing them
with new ones.

XRB+XRLOC

Starting address of Multicast Buffer.

XRB+XRCI

Channel number times two; defines the channel.

XRB+XRBLKM

Device handler index: ETHHND.

The following errors may occur on an Enable Multicast Address call:

Errors

3.27.2.3

BADCNT

Attempt to add too many multicast addresses, or buffer size input was not a
multiple of six bytes, indicating an incomplete address.

BADNAM

At least one address is not a valid multicast address, that is, the least
significant bit of the address is not equal to one.

HNGDEV

The controller is disabled or inoperative.

Get Circuit Counters
Use the Get Counters function 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. This call does not require privileges.

.sPEC-Ethernet

3-195

Data Passed
XRB
Mne- Octal
monic Offset
special function code

(0)

Octal
Offset

Mnemonic

XRLEN

111111111111111111111

ETHHND (= octal 50)

XRBLKM 7

channel number' 2

111111111111111111111

XRCI

XRB+XRLEN

Special function code 0; defines function to be performed.

XRB+XRCI

Channel number times two; defines the channel.

XRB+XRBLKM

Device handler index: ETHHND.

All other fields are reserved. The XRB is not modified on return.
The following errors may occur on a Get Circuit Counters call:

Errors
The controller is disabled or inoperative.

HNGDEV

3.27.2.4

Get Line Counters
Use the Get Line Counters function before a Transfer Line Counters function to
instruct the data link layer to update the appropriate counters. This call does
not require privileges. Wait a couple of seconds before issuing the Transfer Line
Counters call.
Data Passed

XRB
Mne- Octal
monic Offset
special function code

XRLEN

111111111111111111111

ETHHND (= octal 50)

channel number' 2

111111111111111111111

I I I I I II I I I I I II I I I I I I I

XRB+XRLEN

.sPEC-Ethernet

Mnemonic

XRBLKM 7

3-196

(-1 )

Octal
Offset

XRCI

Special function code -1; defines function to be performed.

XRB+XRCI

Channel number times two; defines the channel.

XRB+XRBLKM

Device handler index: ETHHND.

All other fields are reserved. The XRB is not modified on return.
The following errors may occur on a Get Line Counters call:
Errors
HNGDEV

3.27.2.5

The controller is disabled or inoperative.

Transfer Circuit Counters
Use the Transfer Counter function 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.
Data Passed

XRB
Mne- Octal
monic Offset
special function code

(1 )

Octal
Offset

Mnemonic

XRLEN

byte count of transfer

XRBC

start address of user buffer

XRLOC

XRBLKM 7

ETHHND (= octal 50)

channel number' 2

XRCI

//1//////1

clear after read

XRBLK

///11/11/////////1111

I I I I I /I I I I I I I I I I I I I I I

XRB+XRLEN

Special function code 1; defines function to be performed.

XRB+XRBC

Length (in bytes) of transfer. There are up to 32 (octal) bytes of
counters to return. RSTS/E returns fewer counters if requested,
but will not transfer an odd number of bytes.

XRB+XRLOC

Start address of user buffer to receive transfer counters. It must
start on a word boundary.

XRB+XRCI

Channel number times two; defines the channel.

XRB+XRBLKM

Device handler index: ETHHND.

XRB+XRBLK

If XRBLK is zero, it means you only wish to read counters. If
XRBLK is nonzero, it means the circuit counters will be cleared
after they are transferred, if:
..
..

You have SWCTL privilege
All circuit counters are read. A partial read of counters
succeeds, but the counters are not reset after the read.

All other fields are reserved.

.SPEC-Ethernet 3-197

Data Returned

XRB
Mne- Octal
monic Offset

Octal MneOffset monic
111111111111111111111

2 XRBC

1111111/11/1111111111

1111111111/1111111111

11111111111/111111111

111111111/1/111111111

111111111111111111111

XRB+XRBC

Cleared. All other fields are reserved and contents are not guaranteed.
Buffer Contents on Return

r--

current dateltime

r-r--

dateltime last

zeroed

(MSB)
bytes received

(LSB)

(MSB)

(LSB)

bytes sent

(MSB)

packets received

(LSB)

(MSB)

(LSB)

packets sent
user buffer unavailable

3-198

0-2

Current date/time stored in standard RSTSIE format.

4-6

Date/time of last zeroing returned in standard RSTSIE format.

10-12
14-16
20-22

Bytes received, stored as an unsigned 32-bit number.

.sPEC-Ethernet

Bytes sent, stored as an unsigned 32-bit number.
Packets received, stored as an unsigned 32-bit number. The number of messages received for this portal, regardless of length.

24-26

Packets sent, stored as an unsigned 32-bit number. The number of packets sent
by this portal.

User buffer unavailable. The number of times that messages received for this
portal had to be discarded because all of its allocated system receive buffers
contained pending messages. This is kept as a single 16-bit word.

Any counters exceeding their maximum value stay at that maximum value
(65,535 for a single word, 4,294,967,295 for a long word).
The following errors may occur on a Get Line Counters call:
Errors
BADCNT

Returned if:
The user buffer did not start on a word boundary
The requested transfer size is not for all counters and is for an odd
number of bytes.

3.27.2.6

HNGDEV

The controller is disabled or inoperative.

MAGRLE

A record length error is returned if the transfer requests less than the actual
number of counters available. However, as many counters as requested are
transferred into the user buffer. If a clear after transfer was requested, it
was not done.

PRVIOL

If a transfer and clear operation was attempted and the user doesn't have
SWCTL privileges, this error is returned and no operation is performed.

Transfer Line Counters

Use the Transfer Line Counters function to read the counter information from the
data link layer to the user space. Issue this call a short time after issuing the Get
Line Counters function.
Data Passed

XRB
Mne- Octal
monic Offset
special function code

(-2)

Octal
Offset

Mnemonic

XRLEN

byte count of transfer

XRBC

start add ress of user buffer

XRLOC

XRBLKM7
11

ETHHND (= octal 50)

channel number' 2

XRCI

1111111111

clear after read

XRBLK

/ / / / / / II / / / / / / II / / / / /

/ / / / / / II / / / / / / / / / / / / /

XRB+XRLEN

Special function code -2; defines function to be performed.

XRB+XRBC

Length (in bytes) of transfer. There are up to 76 (octal) bytes of
counters to return. RSTS/E returns fewer counters if requested,
but will not transfer an odd number of bytes.

XRB+XRLOC

Start address of user buffer to receive transfer counters. It must
start on a word boundary.

.SPEC-Ethernet

3-199

XRB+XRCI

Channel number times two; defines the channel.

XRB+XRBLKM

Device handler index: ETHHND.

XRB+XRBLK

IfXRBLK is zero, it means you only wish to read counters. If
XRBLK is nonzero, it means the circuit counters will be cleared
after they are transferred, if:
•
•

You have SWCTL privilege
All circuit counters are read. A partial read of counters
succeeds, but the counters are not reset after the read.

AU other fields are reserved.
NOTE

If DECnetiE is operating on the controller, as well as a user portal,
Digital recommends that the line counters only be cleared using the
NCP Zero Line Counters function. This helps in troubleshooting line
problems by keeping all the line counters in one place.

Data Returned

XRB
Mne- Octal
monic Offset

Octal
Offset

Mnemonic

XRBC

/ / / / 1/ / / / / / / 1/ / / / / / / /

XRB+XRBC

3-200

.SPEC-Ethernet

////1/1/1///1//////1/

/ / / / 1/ / / / / / / 1/ / / / / / 1/

/ / / / 1/ / / / / / / 1/ / / / / / / /

/ / / / 1/ / / / / / / 1/ / / / / / II

Cleared. All other fields are reserved and contents are not guaranteed.

Buffer Contents on Return

current date/time

2
date/time last

zeroed

6
(MSB)

(LSB)

(MSB)

(LSB)

(MSB)

(LSB)

(MSB)

(LSB)

(MSB)

(LSB)

(MSB)
multicast packets received
(LSB)

bytes received

bytes sent

multicast bytes

packets received

packets sent

packets sent,

(MSB)

initially deferred

(LSB)

packets sent,

(MSB)

single collision

(LSB)

packets sent,

(MSB)

multiple collision (LSB)

transmit failures (count)

transmit failures (type)

collision detect check failure

RCV failures (count)

RCV failures (flag)

unrecognized destination

data overrun

system buffer unavailable

user buffer unavailable

.SPEC-Ethernet

3-201

0-2

Current date/time stored in standard RSTSIE format.

4-6

Date/time of last zeroing returned in standard RSTS/E format.

10-12

Bytes received on channel, stored as an unsigned 32-bit number.

14-16

Bytes sent on channel, stored as an unsigned 32-bit number.

20-22

Multicast bytes received, stored as an unsigned 32-bit number. (Also included
in the total bytes received, above.)

24-26

Packets received on channel, regardless of length, stored as an unsigned 32-bit
number. The number of messages received for this portal, regardless of length.

30-32

Packets sent on channel, regardless of length stored as an unsigned 32-bit
number. The number of packets sent by this portal.

34-36

Multicast packets received on channel, regardless of length, stored as an
unsigned 32-bit number. (Also included in total number of packets received,
above.)

40-42

Packets sent but initially deferred, stored as an unsigned 32-bit number. This
indicates that transmission of a packet was delayed because the Ethernet cable
was busy when it was first attempted. Subsequent transmission was successful.

44-46

Packets sent with a single collision, stored as an unsigned 32-bit number. This
indicates that a collision occurred during the first attempted transmission of
the packet. The second attempt succeeded.

50-52

Packets sent with multiple collisions, stored as an unsigned 32-bit number.
This indicates that a collision occurred during more than one attempted transmission of the packet. Eventually, it succeeded.

Transmit failed count, stored as an unsigned 16-bit number. The number of
failed transmissions that have occurred on the line.

Transmit failure flag word. This word contains bits indicating the causes for
transmission failures:
•
•
•
•

Collision detect check failures, stored as an unsigned I6-bit word.

Receive failure count, stored as an unsigned 16-bit word.

Receive failure flag word. This word contains bits indicating what types of
receive failures have occurred since t.he counters were last cleared:
•
•
•

3-202

I-indicates transmission failed because of too many collisions. The data
link layer typically tries 16 times to put a message on the Ethernet.
2-indicates a loss of carrier on the last transmission attempt.
100indicates that the attempted transmission length was greater than
1518 bytes long. This should not occur on RSTS/E systems.
20-indicates that a late collision happened on the last transmission
attempt.

I-CRC was invalid indicating garbled recept.ion
2-Framing error. Invalid CRe and a partial byte received.
4--Message exceeded Ethernet maximum length of 1518 bytes.

Unrecognized destination, stored as an unsigned I6-bit word. This is a count
of the number of times that the controller received messages dest.ined for the
physical address of this controller, but. wit.h unrecognized protocol type field.
That is, there is no portal open to process messages of this type but someone is
still sending them.

Data overrun, stored as an unsigned I6-bit word.

.sPEC-Ethernet

System buffer unavailable, stored as an unsigned I6-bit word. This contains
a count of the number of times the controller had to throwaway received
messages because there were no buffers available at the time.

User buffer unavailable, stored as an unsigned I6-bit word. The number of
times that messages received for this portal had to be discarded because all of
its allocated receive buffers contained pending messages.

If any counters exceed their maximum value, they stay at that maximum value

(65,535 for a single word, 4,294,967,295 for a long word).
The following errors may occur on a Get Line Counters call:

Errors
BADCNT

Returned if:
The user buffer did not start on a word boundary
The buffer size in XRBC is less that the total line counters and is for an
odd number of bytes.

DATERR

The data link layer has not yet finished processing the Get Line Counters
function. Try again in a few seconds.

HNGDEV

The controller is disabled or inoperative.

MAGRLE

A record length error is returned if the transfer requests less than the actual
number of counters available. However, as many counter as requested are
transferred into the user buffer. If a clear after transfer was requested, it
was not done.

PRVIOL

If a transfer and clear operation was attempted and the user doesn't have
SWCTL privileges, this error is returned.

.sPEC-Ethernet

3-203

3.27.3

.SPEC for Flexible Diskette
For RX02 flexible diskette devices, the .SPEC directive lets you:
•

Obtain the density (single or double) of the current flexible diskette

•

Mount a new flexible diskette and recompute the density

•

Reformat an RX02 flexible diskette for a desired density

Because the RX02 flexible diskette drive supports single and double density
flexible diskettes, the .SPEC function is especially useful for programmed flexible
diskette operations. For example, .SPEC allows you to mount a series of single
and double density flexible 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 flexible diskette that is incompatible with the
initially computed density, a read or write operation fails .. SPEC lets you include
an instruction in your program that causes the driver to recompute the density.
In addition, for RX02 flexible diskette drives, .SPEC permits you to specify a
density reformat operation.
.SPEC can require as much as 20 seconds to reformat the density of the RX02
flexible diskette and cannot be interrupted with CtrllC. Note that if the operation
is interrupted (by power failure or catastrophic error), the flexible diskette is
rendered unusable. That is, the flexible diskette contains both single and double
density. To recover, you must reformat the flexible diskette.
Privileges Required

None
Data Passed (Flexible Diskette)

XRB
Mne- Octal
monic Offset

XRBLKM

3-204

Octal
Offset

Mnemonic

special function code

XRLEN

parameter word

XRBC

111111/1111111/11//1/

RXDHND (=octal 22)

channel number' 2

111111/11/1/11/11/11/

111111/1111111/1111/1

I I I I I 1/ I I I I I I 1/ I I I I I /

.SPEC-Flexible Diskettes

XRCI

Function code specifying the desired operation:
Code
Meaning

XRB+XRLEN

Returns density of currently mounted flexible diskette.
(The parameter word at XRB+XRBC must be zero.)

Recomputes density and returns density. (The parameter
word at XRB+XRBC must also be zero.) This code must
be issued prior t.o any I/O operation on the flexible
diskette.

Reformats the current flexible diskette to the density
specified in the parameter word at XRB+XRBC. Allowed
only on RX02 drives.

Must equal zero when the function code equals zero or one.
Otherwise, the parameter word can be:
Value Meaning

XRB+XRBC

Reformats as single-density (one sector equals 128 bytes)

Reformats as double-density (one sector equals 256
bytes)

XRB+XRCI

Channel number times t.wo; defines the channel on which the
flexible diskette is currently open.

XRB+XRBLKM

Handler index for flexible disket.te: RXDHND (octal value equals
22).

Data Retu rned

XRB
Octal MneOffset monic

Mne- Octal
monic Offset

XRB+XRBC

II I I I I I I II I I I I I 1/ I I I I

111111/1/1

density

II I I I I I I 1/ I I I I I II I I I I

II I I I I I I I I I I I I I II I I I I

II I I I I I I 1/ I I I I I II I I I I

II I I I I I I II I I I I I II I I I I

XRBC

Density; only returned when the data passed in XRB+XRLEN is
one or zero. The possible values are:
1
Single-density (sector equals 128 bytes)
2

Double-density (sector equals 256 bytes)

Errors
ERRERR

You tried to reformat on an RX01 flexible diskette drive. You can use .SPEC
to reformat flexible diskette densit.y only on RX02 drives.

HNGDEV

A hardware error occurred. This can often be a transient condition. Retry
the operation.

.SPEC-Flexible Diskettes 3-205

3.27.4

.SPEC for Line Printer
Privileges Required

None
Data Passed (Line Counter Subfunction)

XRB
Mne- Octal
monic Offset

XRBLKM

Octal
Offset

Mnemonic

= 0 for line counter

XRLEN

I I I I I /I I I I I I I /I I I I I I I

XRBC

I / / I / /I I / I / I / /I I / / I / I

XRLOC

XRCI
XRBLK

LPAHND (= 6)

channel number' 2

/ / / / / /I / / / / / / /I / / I I / /

/ / / / / /I / / / / / / /I / / / / / /

I / / / / /I / / / / / / /I / / / / / /

XRB+XRLEN

The special line printer function to be performed.

XRB+XRCI

Channel number times two; defines the channel on which the line
printer is currently open.

XRB+XRBLKM

Handler index for line printer: LPAHND (octal value equals 6).

Data Returned (Line Counter Subfunction)

XRB
Mne- Octal
monic Offset

Octal MneOffset monic
/ I /I / / / / / /I / I I I / / /I / I

XRB+XRBC

3-206

.sPEC-line Printers

LSB of the 32-bit line counter

2 XRBC

MSB of the 32-bit line counter

/ / /I / / / / / /I / / / / I / I I / /

/ / /I / / / / / / / / / / / / / / / / I

/ / /I I I / / / /I / / / / / / /I / /

/ / /I I / I / I /I / I / / / I / / / /

The value of the 32-bit line counter. The LSB are returned in
XRB+XRBC and the MSB are in XRB+XRBC+2. The counter is
reset to zero when the lir,e printer is opened.

Data Passed (Line Position Subfunction)

XRB
Mne- Octal
monic Offset

Octal
Offset

Mnemonic

= 1 for line position

XRLEN

I I I I I 1/ I I I I I I 1/ I I I I I I

XRBC

I I I I I 1/ I I I I I I 1/ I I I I I I

XRLOC

XRCI
XRBLK

XRBLKM

LPAHND (= 6)

channel number * 2

I I I I I 1/ I I I I I I 1/ I I I I I I

XRB+XRLEN

The special line printer function to be performed.

XRB+XRCI

Channel number times two; defines the channel on which the line
printer is currently open.

XRB+XRBLKM:

Handler index for line printer: LPAHND (octal value equals 6).

Data Returned (Line Position Subfunction)

XRB
Octal MneOffset monic

Mne- Octal
monic Offset

XRB+XRBC

I I 1/ I I I I I 1/ I I I I I I I I I I

curr horiz position

curr vert position

I I 1/ I I I I I 1/ I I I I I I 1/ I I

111/1111/1/1111111/11

I I 1/ I I I I I 1/ I I I I I I 1/ I I

111/111111/1/11111/11

I I 1/ I I I I I 1/ I I I I I I 1/ I I

XRBC

The current vertical line position. The value is in the range 0 (top
of page) to L-l, where L is the page length.
The current horizontal line position. The value is in the range 0
(left margin) to W-l, where W is the page width .

.sPEC-line Printers 3-207

Errors (Line Printer)
BSERR

An illegal channel number is spe<.;fied at XRB+XRCI.

NOTOPN

The channel specified at XRB+XRCI is not open.

PRVIOL

Privilege violation; one of the following conditions has occurred:
•
•
•

3-208 .sPEC-line Printers

The calling job does not own the specified printer and does not have
DEVICE privilege.
The function code is not 0 or 1.
The device open on the channel specified at XRB+XRCI is not a line
printer.

3.27.5

.SPEC for Magnetic Tape
On MT, MM, and MU tape drives, to set the drive density (function code = 13),
you must mount a tape and position it at the beginning-of-tape (BOT) mark. You
do not need to mount a tape to check legal densities of a drive or to return the
current density.
NOTE

Any density changes you make with this call remain in effect until
either a new density is set, or you read a magnetic tape that has a
density different than the one formerly set. This action is equivalent to
the STAY value 8192% in the Set Density and Parity function (function
code = 6).

Privileges Required
None

Data Passed (Magnetic Tape)
XRB
Octal
Offset

Mne- Octal
monic Offset

o XRLEN

special function code

parameter

/ / / / / II / / / / / / /I / / / / / /

XRBLKM 7

MTAHND (=octaI16)

Mnemonic

channel number * 2

II / / / II / / /I / / /I /I / / / /

II /I / II / / /I / / II / / / / II

/I / / / II / / / / /I /I / /I / /I

XRBC

XRCI

XRB+XRLEN

The special magnetic tape function to be performed (see
Table 3-6). For a detailed discussion of these functions, see
the discussion of the MAGTAPE function in the RSTS / E
Programming Manual.

XRB+XRBC

The meaning of this word varies according to the special function
code specified at XRB+XRLEN. Table 3-6 summarizes these
values; for a detailed discussion, see the MAGTAPE function
description in the RSTS / E Programming Manual.

XRB+XRCI

ChanJ;lel number times two; defines the channel on which the tape
is currently open.

XRB+XRBLKM

Handler index for magnetic tape: MTAHND (octal value equals
16).

.SPEC-Magnetic Tape 3-209

Table 3-6:

Special Functions for Magnetic Tape

Code

Action

Parameter

Value Returned

Rewind and off-line

Unused

Write end-of-file

Unused

Rewind

Unused

Skip record

# records to skip

# records not skipped

Backspace over
record

# records to

# records not backspaced

Set density and
parity

D+P+S 1

Tape status function

Unused

(see Table 3-7)

File characteristics

Unused

(see Table 3-7)

Rewind on close

Unused

End of volume

Unused

Error condition
acknowledged

Unused

Extended set density

Density

backspace

(see Table 3-7)

14 = 800. bpi
400 = 1600. bpi, phase-encoded
P=

Parity (0 = odd, 1 = even) 3 (800. bpi only)

Stay

o = MODE value specified in OPEN does not stay on CLOSE
20000 = MODE value specified in OPEN is retained after CLOSE

Current density

I/)

If bit 15 is set, the density is set according to the value in Bits 0-14 as follows:
77777 = highest legal density for the drive
1 = lowest legal density for the drive
n = set to n, if legal; otherwise unchanged

I/)

If Bit 15 is clear, the density is unchanged but the value passed is tested

Iparameter word for function code 5:
2Parameter word for function code 13:
3Digital recommends that you use odd parity. When you use even parity, you cannot write binary
data. In addition, many operating systems and tape drives do not support even parity.

3-210 .sPEC-Magnetic Tape

Data Returned (Magnetic Tape)

XRB
Mne- Octal
monic Offset

Octal MneOffset monic

I I 1/ I I I I I 1/ I I I I I I 1/ I I

Bit

2 XRBC

value (see Table 3-7)

I I 1/ I I I I I 1/ I I I I I I I I I I

111/1/1111/1111111/11

I I 1/ I I I I I 1/ I I I I I I II I I

I I 1/ I I I I I 1/ I I I I I I I I / /

The meaning of this word varies according to the value at
XRB+XRLEN in the data passed. Table 3-7 summarizes these
values. For a detailed discussion, see the MAGTAPE function
description in the RSTS / E Programming Manual.

XRB+XRBC

Table 3-7:

Value Returned by .SPEC for Magnetic Tape

Octal
Value

Meaning

Value Returned at XRB+XRBC for Function Code 6 (Magnetic Tape Status Word)

100000

14-13

If bit 3 = 0, these bits indicate density:
00000
20000
40000
60000

Last command caused an error.
Reserved
Reserved
800. bpi
Reserved

If bit 3 = 1, these bits indicate density:
00000
20000
40000
60000

1600. bpi
Reserved
Reserved
Reserved

00000
10000

9-track tape
Reserved

0000
4000

Odd parity
Even parity

2000

Magnetic tape is physically write-locked

1000

Tape is beyond end-of-tape (EOT) marker

400

Tape is at beginning-of-tape (BOT)

200

Last command detected an end-of-file (EOF)

100

The last command was .READ and the record read was longer than
the I/O buffer size; that is, part of the record was lost

Unit is nonselectable (off-line)

(continued on next page)

.SPEC-Magnetic Tape 3-211

Table 3-7 (Cont.):
Octal
Value

Bit

Value Returned by .SPEC for Magnetic Tape
Meaning

Value Returned at XRB+XRBC for Function Code 6 (Magnetic Tape Status Word)
4

00
20

Unit does not accept 1600. bpi
Unit accepts 1600. bpi

00
10

See values for bits 14-13
See values for bits 14-13
Indicates last command issued:

2-0

0= Off-line
1 Read
2 Write
3 Write EOF
4 Rewind
5 Skip record
6 Backspace record

=
=
=
=
=
=

Value Returned at J{RB+XRBC for Function Code 7 (File Characteristics Word)
word

=0, DOS format or ANSI U (undefined) format

word of. 0, ANSI format, with bit meanings:

15-14

40000
100000
140000

F (fixed-length)
D (variable-length)
S (spanned)t

13-12

00000
10000
20000

Carriage control embedded 'M'
FORTRAN carriage control 'g
Implied LF/CR before record' ,

11-0

For Format F, this value is t.he record length, in bytes.
For Format D, this value is the maximum record length, in bytes.

Value Returned at XRB+XRBC for Function Code 13 (File Characteristics Word)
If value passed was zero, the value returned is t.he current density
If value passed was nonzero, the value returned depends on the value passed as follows:
Bits
Passed
Returned
14-0

77777

Highest legal density for t.he drive

Lowest legal density for t.he drive

Nearest legal density for the drive not greater
thann

tANSI format S is not supported by RSTSIE systems.

3-212

.SPEC-Magnetic Tape

Errors (Function Code = 13)
BDNERR

The value passed in bits 0-14 ofXRB+XRBC is not legal for the specified
tape drive. The density of the drive is unchanged.

NOTMTA

An attempt was made to set the density of an MT, MM, or MU tape drive for
which no tape was mounted, or the tape was not at BOT. When you specify
a density that is not a valid density, the next highest density for the drive
is returned. If the specified density is higher than the maximum density for
the drive, the maximum density is returned.

.SPEC-Magnetic Tape 3-213

3.27.6

.SPEC for Pseudo Keyboards
For pseudo keyboards, the .SPEC function lets you:
..
<I>

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.
Determine the current exit status of the controIled job.

A pseudo keyboard receives two kinds of output from a controlled job: character
echo, which is done by the RSTSIE 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.
Privileges Required

None
Data Passed

XRB
Mne- Octal
monic Offset

XRBLKM

Mnemonic

special function code

XRLOC

parameter

XRBC

1/11///1/1/1///1/1111

PKHND (= 20)

channel number' 2

I I I I I I I I I I I I I I I I I I I II

1/ 1/ 1/ I I I 1/ I 1/ 1/ I I 1/ I

1/11/1/1/1/1///1/111/

XRB+XRLOC

3-214

Octal
Offset

.SPEC-Pseudo Keyboards

XRCI

The special function codes; the possible values are:
Code
Meaning

Enable/disable echo or read flag.

Read exit status.

The action to be performed for the Sl'~
Value
Meaning

XRB+XRBC

Read the flag word

255

Enable echo

-1

Disable echo

XRB+XRCI

Channel number times two; defines the channel on which the
pseudo keyboard is open.

XRB+XRBLKM

Handler index for pseudo keyboard PKHND (octal value = 20).

Data Returned

XRB
Octal MneOffset monic

Mne- Octal
monic Offset

XRB+XRBC

/1/1/1//1/1//1/1///1/

flag word or exit status

1/ 1/ / / / / 1/ II / II 1/ / / / /

1/ 1/ / II / 1/ / / / 1/ 1/ / II /

1/ 1/ 1/ 1/ 1/ / / / 1/ II / / / /

1/ 1/ / 1/ / 1/ / 1/ / / 1/ / II /

II 1/ / / / II / / / / / / 1/ 1/ 1/

XRBC

For special function code 0:
If bit 5

Keyboard ~cho is enabled.

= 1

Keyboard echo is disabled.

For special function code 1, the exit status for the job you are
controlling. The current exit status value is returned in bits
0-2 The values have the following meanings:

o
1
2
4

Warning
Success
Error
Severe error

Errors
No errors are possible with the pseudo keyboard subfunction of .SPEC .

.SPEC-Pseudo Keyboards

3-215

3.27.7

.SPEC for Terminal
The .SPEC directive for tenninals has two forms. The first fonn lets you perfonn
several different functions, such as cancel CtrllO, set modes for tape, echo, and
ODT, and cancel type-ahead. The second fonn lets you set, read, and clear private
delimiters.
Privileges Required

SEND to broadcast a message to a tenninal. SYSIO to force a command to a
tenninal.
Data Passed (Terminal-Except Private Delimiters)

XRB
Mne- Octal
monic Offset

XRBLKM

Octal
Offset

Mnemonic

special function code

XRLEN

KB number or number of bytes to send/force

XRBC

starting address of bytes to send/force

XRLOC

TTYHND (=octal 2)

XRCI
XRBLK

channel number' 2

KB number (XRB+XRLEN = 5, 6, or 12)

I I I I I /I I I I I I / / / / / I / / /

I I I I / /I I I / / / / /I / I / / I /

XRB+XRLEN

Defines a special function:
Code
Meaning

Cancel CtrllO (see the .ITRST directive)

Set tape mode (see the .ITAPE Set tape mode directive)

Enable echo and clear tape mode (see the .ITECH
directive)

Disable echo (see the .ITNCH directive)

Set ODT mode (see the .ITDDT directive)

Force to keyboard (SYSIO privilege required)

Broadcast to keyboard (SEND privilege required)

Cancel all type-ahead

Reserved

Multiple private delimiters

Read CtrllC flag

For XRB+XRLEN = 12, if the caller owns the terminal being
checked, the CtrllC flag is cleared after it is read. Otherwise, the
flag is just read.

3-216

.SPEC-Terminals

XRB+XRBC

For XRB+XRLEN = 0, 1, 2, 3,4,7, or 12:
When XRB+XRBC equals 0, these functions take place on the
terminal currently open for this job. When XRB+XRBC does
not equal 0, these functions take place on the keyboard number
specified in XRB+XRBC. This keyboard must be assigned to but
not opened by the calling job.
For XRB+XRLEN = 5 or 6:
XRB+XRBC is the number of bytes to send or force.

XRB+XRLOC

For XRB+XRLEN equal to 5 or 6, this word contains the starting
address of the bytes to be sent or forced.

XRB+XRCI

Channel number times two; defines the channel for the terminal
specified at XRB+XRBC.

XRB+XRBLKM

Handler index for terminals; TTYHND (octal value

XRB+XRBLK

For XRB+XRLEN = 5, 6, or 12, this word contains the keyboard
number to which the data is to be sent or forced.

=2).

Data Returned (Terminal-Except Private Delimiters)

XRB
Octal MneOffset monic

Mne- Octal
monic Offset

/1/111//1/

CTRLlC flag

o XRLEN

number of bytes not sent

2 XRBC

/ / / / / II / / / / / / II / / / / / /

/ / / / / II / / /I / / II / / / / / /

/ / / / / II / / / / / / II / / / / / /

XRB+XRLEN

A value of zero indicates the CtrllC flag was not set. A value of
377 indicates the CtrllC flag was set. This value is only meaningful when the data passed in XRB+XRLEN was 12.

XRB+XRBC

Number of bytes that could not be sent (returned only when
XRB+XRLEN in the data passed was six).

Errors (Terminal-Except Private Delimiter)
BSERR

An illegal channel number is specified at XRB+XRCI.

NOTOPN

The channel specified at XRB+XRCI is not open.

PRVIOL

Privilege violation; one of the fol1owing conditions has occurred:
•
•
•
•

The calling job does not own t.he specified keyboard and does not have
DEVICE privilege
The function code is not to 7 or 11 (returned for all .SPEC calls for
terminals)
An illegal terminal number at XRB+XRBLK
The device open on the channel at XRB+XRCI is not a terminal

.SPEC-Terminals 3-217

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 CtrllZ

•

A 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 lwy as the delimiter key. Private
delimiters are also useful in keypad applications.
You can declare one character as a private delimiter or you can declare up to 256
multiple private delimiters.
Multiple private delimiters let you do special character processing without using
single character I/O. For example, by combining escape sequences with private
delimiters, you can define your own function keys in keypad applications.
The rest of this section:
•

Provides general information about private delimiters

•

Shows the XRB layouts for setting, reading, and clearing private delimiters

•

Lists all private delimiter masks

Characteristics of Private Delimiters

Declaring a character as a private delimiter with the .SPEC directive overrides
the existing interpretation for the character. Thus, unlike a standard delimiter
such as RETURN or LINE FEED, a private delimiter does not echo at the
terminal. In addition, a special character no longer performs its normal function.
For example, when the DELETE key is a private 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:
•

Terminates a .READ on the terminal.

•

Cannot be deleted except by CtrllX. The DELETE key and CtrllU do not affect
private delimiters in the type-ahead buffer. (CtrllX cancels all type-ahead
buffering.)

•

Causes the system to awaken a sleeping job when typed at a terminal that
the job has open or assigned.

Once set, a private delimiter remains in effect for a terminal until one of the
following occurs:
•

The program clears it

•

The job releases the terminal by deassigning it or by closing the I/O channel
where the terminal is open

•

The job terminates

In addition, the system clears private dellmiters when a dial-up line gets hung up
or the job controlling the terminal is killed.

3-218

.sPEC-Terminals

Private delimiters change the way characters are processed 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 delimiters are in use, the system terminates a read only when a
private delimiter is typed.
The system processes private delimiters after processing CtrllS and CtrllQ (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 delimiters before all other characters, including
control characters such as Ctrl/C. Thus, when you use a standard delimiter
character as a private delimiter, it does not echo on the terminal.
Programming Hint

By combining escape sequences with private delimiters, you can define your own
function keys without using single character I/O. For example:

1. Make sure the keypad is in the right mode for your application
2. Define each function as the PF1 key followed by a character
3. Define each character as a private delimiter so it does not echo on the terminal
For example, you might define PF1 + A as one function and PF1 + M as another
function.
Data Passed (Terminal -

Private Delimiters)

XRB
Mne- Octal
monic Offset

XRBLKM

Octal
Offset

Mnemonic

= octal 11 for private delimiters

XRLEN

o or byte count when XRB+XRMOD = 1 or 2

XRBC

o or address when XRB+XRMOD = 1 or 2

XRLOC

TTYHND (=octal 2)

channel number' 2

XRCI

flag byte

KB number

XRBLK

must = 0

XRTIME

subfunction code = 0, 1, or 2

XRMOD

XRB+XRLEN

Function code; set to octal 11 for private delimiter mask.

XRB+XRBC

For XRB+XRMOD equals zero, this word must be set to zero.
For XRB+XRMOD equals one (set private delimiter mask), this
word is the byte count for the private delimiter bit mask. For
XRB+XRMOD equals two (read private delimiter mask), this word
is the buffer length for a buffer into which the mask is to be read.
For XRB+XRMOD equals one or two, the value of XRB+XRBC
must be less than or equal to 32.

.SPEC-Terminals

3-219

For XRB+XRMOD equals zero, this word must be set to zero.
For XRB+XRMOD equals one, this word is the address of the
private delimiter mask. The mask itself can be up to 32 bytes
long (32 bytes = 256 bits). Each bit in the mask represents an
ASCII character (see Table 3-8). Setting a bit indicates that the
associated ASCII character is to serve as a private delimiter. For
XRB+XRMOD equals two, this word is the address of a buffer into
which the terminal's private delimiter mask is to be read.

XRB+XRLOC

Table 3-8:
Octal
Value

Private Delimiter Masks
Byte Value

ASCII Character

Byte,
address-tn

Bit

Octal

Decimal

NUL

n=O

SOH

STX

ETX (CtrIlC)

EOT

ENQ

ACK

100

BEL

200

128

BS (backspace)

HT (horizontal tab)

LF (line feed)

VT (vertical tab)

FF (form feed)

CR (carriage return)

100

S1 (CtrlJO)

200

128

DLE

DC! (CtrIlQ)

DC2

DC3 (CtrIl8)

DC4

NAK (CtrIJU)

8YN

100

ETB

200

128

CAN

SUB (CtrIlZ)

ESC (ESCAPE)

t Octal code 0 can be used only for terminals openl'd in binary mode because nulls are ignored in
normal mode.

(continued on next page)

3-220

.SPEC-Terminals

Table 3-8 (Cont.):
Octal
Value

Private Delimiter Masks

ASCII Character

Byte Value

Byte,
address+n

Bit

Octal

Decimal

100

200

128

SP (space)

2
4

100

' (apostrophe)

200

128

50
51
54

, (comma)

- (dash/minus)

. (period)

100

200

128

100

200

128

100

>
?

200

128

100

10 (8)

101

10 (8)

102

10 (8)

103

10 (8)

104

10 (8)

105

10 (8)

(continued on next page)

.SPEC-Terminals

3-221

Table 3-8 (Cont.):
Octal
Value
106

Private Delimiter Masks
Byte Value

ASCII Character

Byte,
address+n

Bit

Octal

Decimal

10 (8)

100

107

10 (8)

200

128

110

11 (9)

111

H
I

11 (9)

112

11 (9)

113

11 (9)

114

11 (9)

115

11 (9)

116

11 (9)

100

117

11 (9)

200

128

120

12 (10)

121

12 (10)

122

R
S

12 (10)

123

12 (10)

124

12 (10)

125

12 (10)

126

12 (10)

100

127

12 (10)

200

128

130

13 (11)

131

13 (11)

132

Y
Z

13 (11)

133

[

13 (11)

134

13 (11)

135

]

13 (11)

or *

13 (11)

100

or +-

13 (11)

200

128

136

137
140

' (grave accent)

13 (12)

141

13 (12)

142

13 (12)

143

13 (12)

144

13 (12)

145

13 (12)

146

13 (12)

100

147

13 (12)

200

128

150

15 (13)

151

15 (13)

152

15 (13)

153

15 (13)

(continued on next page)

3-222 .SPEC-Terminals

Table 3-8 (Cont.):
Octal
Value

Private Delimiter Masks

ASCII Character

154

Byte Value

Byte,
address+n

Bit

Octal

Decimal

15 (13)

155

156

15 (13)

100

15 (13)

200

128

161

P
q

16 (14)
16 (14)

162

16 (14)

157
160

163

16 (14)

164

16 (14)

165

16 (14)

166

16 (14)

100

167

16 (14)

200

128

170

17 (15)

171

17 (15)

172

17 (15)

174

I (vertical)

17 (15)

175

}

17(15)

176

- (tilde)

17 (15)

100

177

DEL (RUB OUT)

17 (15)

200

128

200377

Can only be used for terminals with the lEIGHT_BIT characteristic set or open
in binary mode; the 8th bit is cleared in normal mode for terminals with the
INOEIGHT_BIT characteristic.

173

XRB+XRCI

Channel number times two. When this byte equals zero, it indicates the job's keyboard. When this byte does not equal zero, a
keyboard must be open on the indicated channel.

XRB+XRBLKM

Handler index for terminals; TTYHND (octal value is 2).

XRB+XRBLK

Specifies the keyboard number that the subfunction is to take
place on. If this byte and the byte at XRB+l1 equal zero, then
the subfunction is performed on the terminal open on the channel
indicated by XRB+XRCI.
Flag byte. If bit 7 of this byte is set (byte equals 128), it indicates that the keyboard number at XRB+XRBLK is real. (When
XRB+XRBLK is zero, this bit set indicates that KBO: is the desired terminal. If this bit is cleared and XRB+XRBLK is zero,
it indicates that the keyboard open on the channel indicated at
XRB+XRCI is the desired t~rminal.) All other bits must equal
zero.

XRB+XRTIME

This word must be set t.o zero.

.SPEC-Terminals

3-223

Subfunction code:

XRB+XRMOD

o = Clear private delimiter mask.

1 =Set private delimiter mask.
2 =Read private delimiter mask.
Once set, private delimiters remain in effect for a terminal until
cleared (XRB+XRMOD = 0) or until implicitly cleared by:

• Deassigning or closing the terminal
• Killing the job or hanging up the line
• Keyboard monitor read (negative wait time on .READ)
Note that clearing the delimiter mask to all zeros is not the same
as issuing the clear subfunction (XRB+XRMOD = O). Use the clear
subfunction to free system resources used when any mask is set.

Data Returned (Terminal-Private Delimiters)

Except for a possible error in byte 0 of the FIRQB, the private delimiter subfunctions of .SPEC do not return any meaningful data.
Errors (Terminal-Private Delimiters)
BADCNT

One of the following conditions has occurred:
•
•

Byte count at XRB+XRBC does not equal zero or is greater than 32
Invalid address at XRB+XRLOC

BSERR

An illegal channel number is specified at XRB+XRCI.

ERRERR

Multiple delimiter feature is not included in the monitor.

NOBUFS

The monitor needs to expand its internal buffer space, but memory is not
available; a retry may succeed.

NOSUCH

You are trying to read the private delimiter mask, but no private delimiters
are set.

NOTOPN

The channel specified at XRB+XRCI is not open.

PRVIOL

Privilege violation; one of the following conditions has occurred:
•
•
•
•
•

3-224 .SPEC-Terminals

Job does not own the specified keyboard and does not have the required
privilege
Subfunction code at XRB+XRMOD is not 0, 1, or 2
Function code is not 0 through 7 or 11 (returned for all .SPEC calls for
terminals)
An illegal terminal number is specified at XRB+XRBLK
The device open on the channel specified at XRB+XRCI is not a terminal

3.28 .STAT -

Return Job Statistics

Form

.STAT
Function

The .STAT directive returns current statistics on the job to the XRB.
Privileges Required
TUNE is required to read the current run priority or run burst settings.
Data Passed
The .STAT directive does not pass any meaningful data.
Data Returned

XRB
Mne- Octal
monic Offset

Octal MneOffset monic
current job image size, in K words

XRLEN

current run-time system size, in K words

XRBC

curren! private memory max, in K words

XRLOC

maximum job image size, in K words

XRCI

current PPN

XRBLK

current run priority

XRTIME

current run burst

XRMOD

XRB+XRLEN

The current size of the user job image for this job, in K words. If
I&D Space is enabled, this is the size of only the D-Space of the
task.

XRB+XRBC

The size of the current run-time system for this job, in K words.

XRB+XRLOC

The current private memory maximum for the user job image, in
K words. If the job has an unlimited memory maximum or if its
private memory maximum is larger than the possible maximum
size allowed by its current nm-time system, then the value returned here is the maximum size possible for the current run-time
system, in K words. If the job's private maximum is less than the
run-time system minimum, then the value retv.rned here is the
run-time system's minimum size (see the .CORE directive). In
all cases, this value represents the maximum size of the user job
image under its current run-t.ime syst.em.
The maximum job image size possible (under the current runtime system), in K words. If I&D Space is enabled, this is the
maximum size to which D-Space can expand.

XRB+XRBLK

The job's current PPN is ret.urned here. The programmer number
is returned as a binary value in the low byte (XRB+XRBLK), the
project number as a binary value in the high byte (XRB+l1). If
the job is not logged in, a value of 0 is ret.urned here .

.STAT

3-225

XRB+XRTIME

The job's current run priority (if caller has TUNE privilege;
otherwise, .STAT returns zero). Run priority may range from
-128, indicating a suspended job, to +127, the highest priority.
The monitor schedules jobs for time-shared execution according
to this priority. When a user first logs in to RSTSIE, LOGIN is
run with priority O. LOGIN sets the user's job run priority to -8.
Only in unusual cases should the run priority be changed. It can
be changed by a user with TUNE privilege for any job with the
SET JOBIPRIORITY command. It can also be changed with the
UU.PRI subfunction of the .UUO directive. It can be modified by
the job by one-half step (4) with the .sET and .CLEAR directives.
The special-case value of -128 indicates that the job is never
scheduled to run; it is suspended.

XRB+XRMOD

The job's current run burst (if caller has TUNE privilege; otherwise, .STAT returns zero). The run burst is the amount of time
that the job is allowed to execute compute-bound before the next
job in the schedule is given control. The units of run burst are
1/6Oths or 1I50ths of a second, depending on the clock in use
and/or the line frequency. (Systems running with the KW11-P
clock at crystal speeds, rather than at line frequency, or 11/83,
11/84, 11/93, or 11194 systems with 800 Hertz clocks, have a run
burst unit of 1/50th of a second. Otherwise, if the system is operating with a 60 Hz power line, one run burst unit equals 1/60th
of a second.) The range of values for run burst is from 1 to 127.
When a job is created, the monitor set.s the run burst to a value of
six. This value can be modified by the system manager for a particular job with the SET JOBIRUN_BURST command. It can also
be modified with the UU.PRI subfunction of the .UUO directive.

Errors

No errors are possible on this directive.
Example

Since the .STAT directive does not pass any data to the monitor, the call is simply:
.STAT

3-226

.STAT

3.29 .TIME -

Return Timing Information

Form
.TIME

Function
The .TIME directive returns job timing information: elapsed CPU time, elapsed
time connected to a user terminal (channel 0), elapsed device time, and memory
utilization.
Privileges Required

None.
Data Passed

The .TIME directive does not pass any meaningful data.
Data Returned

XRB
Octal MneOffset monic

Mne- Octal
monic Offset
low 16 bits of elapsed CPU time, : 1 sec.

o XRLEN

elapsed connect time to channel 0, min.

2 XRBC

low 16 bits of memory utilization, KCTs

XRLOC

XRCI

elapsed device time, minutes

high 16 bits of elapsed CPU time, .1 sec.

I I I I I I I /I I I I I I /I I I I I I

high 16 bits of memory utilization, KCTs

10 XRBLK

12
14 XRMOD

XRB+XRLEN

The low-order 16 bits of the job's elapsed CPU time, in tenths of a
second of CPU utilization.

XRB+XRBC

The elapsed time that the job has been connected to a channel 0
terminal, in minutes.

XRB+XRLOC

The low-order 16 bits of the job's memory utilization, in kilocore-ticks (KCTs). A kilo-core-tick is the use of 1K of memory for
one-tenth of a second.

XRB+XRCI

The job's elapsed device time. Device time is the use of an allocatable device for one minute. If a job owns two devices for one
elapsed minute, then two units of device time are accrued.

XRB+XRBLK

The high-order 16 bits of the job's elapsed CPU time (see
XRB+XRLEN).

XRB+XRMOD

The high-order 16 bits of the job's memory utilization (see
XRB+XRLOC).

.TIME

3...:.227

Errors
No errors are possible with the .TIME directive.

Example
Since the .TIME directive does not pass any data, the call is simply:
.TIME

3-228 .TIME

3.30 .TTAPE -

Enter Tape Mode

Form
.TTAPE

Function
The .TTAPE directive enters tape mode on the job's terminal (channel 0). Use
this directive when it is necessary to read data from the low-speed paper tape
reader available on some terminals. Make sure the terminal is open on channel
0, and call this directive before the .READ directive. Three things happen:
•

No incoming characters are echoed, preventing needless output at the terminal while the tape is being read.

•

The DELETE character (ASCII code 177) is ignored, rather than deleting the
previous character.

•

A LINE FEED character (ASCII code 012) is not automatically appended to
an incoming RETURN (ASCII code 015).

The .TTECH directive returns character processing to normal on channel O.

Privileges Required
None

Data Passed
The .TTAPE directive does not pass any data.

Data Returned
The .TTAPE directive does not return any data.

Errors
DETKEY

Channel 0 is not currently available for this job; it is running detached.

Example
Since the .TTAPE directive does not pass or return any data, the call is simply:
.TTAPE

.1TAPE 3-229

3.31

.TTOOT -

Disable Full-Line Buffering

Form
.TTDDT

Function
The .TTDDT directive disables the monitor's usual practice of buffering a full line
of data from the user's terminal (channel 0) before passing it on to the job on a
.READ directive.
The monitor accepts data typed at a user terminal and stores it in a buffer
until the job associated with the terminal reads the data. Normally, a .READ
causes the monitor to pass a line to the job's buffer. (A line is any number of
characters ending with a RETURN, LINE FEED, ESCAPE, FORM FEED, or
Ctrl/D combination.) If a full line is not in the monitor's buffer, the monitor stalls
the job until it gets a delimiter and then awakens the job and passes the line on
to the job's buffer.
The .TTDDT directive tells the monitor that, when the next .READ on the user's
terminal is issued, it is to pass on whatever is currently in the monitor's buffer,
whether or not a delimiter has been typed. If no characters are in the monitor's
buffer, the job is stalled until at least one character has been typed .
.TTDDT is a one-shot directive: it affects only the next .READ on the user's
terminal. If you want to do this type of input consistently, you must execute a
.TTDDT before each .READ.
This type of input is useful when you want to respond to each character that a
user types. (Note that more than one character may be in the monitor's buffer. If
you really want only one character, use .TTDDT before each .READ, and define
a I-character input buffer for the .READ.) For example, the ODT utility (see
the ODT Reference Manual) uses this capability to accept commands without
requiring that you type a delimiter. This type of input puts a high load on the
system; Digital does not recommend its use except in unusual circumstances.

Privileges Required
None

Data Passed
The .TTDDT directive does not pass any data.

Data Returned
The .TTDDT directive does not return any data.

Errors
DETKEY

Channel 0 is not currently available for t.his job; the job is running detached.

Example
Since the .TTDDT directive does not pass any data, the call is simply:
.TTDDT

3-230 .TIDDT

3.32 .TTECH -

Undo .TTAPE or .TTNCH

Form
.TTECH

Function
The .TTECH directive causes the monitor to resume normal character input
processing on channel 0 when it has been disabled with either a .TTAPE directive
or a .TTNCH directive.

Privileges Required
None

Data Passed
The .TTECH directive does not pass any data.

Data Returned
The .TTECH directive does not return any data.

Errors
DETKEY

Channel 0 is not available for this job; the job is running detached.

Example
Since the .TTECH directive does not pass any data, this call is simply:
.TTECH

.TTECH

3-231

3.33 .TTNCH -

Stop Echo

Form

.TTNCH
Function

The .TTNCH directive disables terminal echo on the job's terminal (channel 0).
That is, whatever the user types is accepted, but it is not echoed back for display
on the terminal. Otherwise, all normal character processing occurs. (The .TTECH
directive returns character processing to normal on channel 0.)
Privileges Required

None
Data Passed

The .TTNCH directive does not pass any data.
Data Returned

The .TTNCH directive does not return any data.
Errors
DETKEY

Channel 0 is not available for this job; the job is running detached.

Example

Since the .TTNCH directive does not pass any data, the call is simply:
.TTNCH

3-232

.TINCH

3.34 .TTRST -

Restart Output

Form
.TTRST

Function
The .TTRST directive restarts program output to the user's terminal when such
output has been stopped by the user's typing a Ctrl/O or Ctrl/C.
Terminal service in the RSTSIE monitor maintains a "discard all program output"
indicator for each terminal. When this indicator is set, the driver ignores a
.WRITE directive to the terminal rather than display the data at the user's
terminal. When the indicator is clear, a .WRITE to the terminal is processed
normally. The .TTRST directive clears this indicator.
The driver sets the indicator when the user enters a Ctrl/C combination. It
reverses the indicator when the user enters a Ctrl/O combination. A .READ
directive to the user's terminal clears the indicator.
One use of .TTRST is in run-time systems with keyboard monitors. By issuing
.TTRST before displaying any prompt, you can ensure that the prompt is actually
displayed at the user's terminal.

Privileges Required
None

Data Passed
The .TTRST directive does not pass any data.

Data Returned
The .TTRST directive does not return any data.

Errors
DETKEY

The user's terminal is not currently available for this job; the job is running
detached.

Example
Since the .TTRST directive does not pass any data, the call is simply:
.TTRST

.TTRST 3-233

3.35 .UlOG -

Modify User logical

Form

.ULOG
Function

The .ULOG directive has three subfunctions. You select the particular action
desired by setting a function field in the FIRQB (at offset FQFUN). Table 3-9
lists the subfunctions by function code. The following sections describe the
subfunctions in alphabetical order.
Table 3-9:

Summary of .ULOG Subfunctions

FQFUN
Value
(Octal)

Mnemonic

Action Performed

UU.ASS

Allocate, reallocate, assign, or reassign a device, or assign or
list user logicals

13
14

UU.DEA

Deallocate a device or deassign a user logical

UU.DAL

Deallocate all devices and deassign all user logicals

Privileges Required

See the descriptions of each .ULOG subfundion.

3-234

.UlOG

3.35.1

UU.ASS (Allocate/Reallocate a Device, or Assign or List User Logical)
Form
MOVB

iUU.ASS,FIRQB+FQFUN

(set up FIRQB and XRB)

.ULOG

Function
The UU.ASS subfunction of .ULOG lets you do one of four things:
•

Allocate a device to a job. If you assign a LAT port for host-initiated connections, this directive initiates a connection to the server currently assigned to
the port.

•

Reallocate a device to another job.

•

Enter a user logical. This feature lets you:
Assign a logical name to a device. The monitor then uses this assignment
for logical-to-physical device translation by the .FSS directive.
Associate a PPN with a particular logical name. This user logical PPN
is used if the associated logical name (but no PPN) is found in a string
scanned by .FSS. Use this feature if you want to override a system-wide
logical name with an associated PPN. For example, the logical name LB is
commonly associated with a disk on the public structure and some specific
PPN (usually [1,1]). With this feature, you can set up a different device
and PPN for the logical name LB.
Assign a PPN to be substituted for an at sign (@) character encountered
in a file specification string scanned by an .FSS directive.
Assign a protection code to be used as a default if no protection code is
specified in a file specification string translated by an .FSS directive.

•

List all assigned user logical names by index.
NOTE

Assigning user logicals assigns values to the USRPPN and USRPRT
areas in the low 1000 bytes of virtual memory and to the extended
logical area of the job header (see Chapter 2).
CAUTION

Digital strongly recommends you do not write or run programs that
directly manipulate user logicals in low core. Such programs may
perform erratically. Instead, use the .ULOG directive.

Privileges Required
No privileges are required to manipulate user logicals or deallocate a device.
DEVICE is required to allocate a restricted device. HWCTL is required to seize a
device or reallocate a device to a job in another account.

.ULOG-UU.ASS

3-235

Data Passed -

Allocate/Reallocate Device
FIR08
Octal MneOffset monic

Mne- Octal
monic Offset
/11/1/1///1/1//11//11

FOFUN 3

UU.ASS (= octal 12)1

//1//1///1/1//1111/11

(must be 0)

FOPPN

FONAM1

(must be 0)

O=assign; <>O=job

I I 1/ I I I I I /I I I I I I I /I I I

DOS or ANS in RAD50 format (1 word)

11111111111111111 II I I

I I 1/ I I I I I I I I I I I I I I I I I

mode

//1/1///11/1///1//111

(must be 0)

device name (2 ASCII characters)

FODEV

FODEVN

3-236

<>0, unit no. real

14 FOEXT

22 FOMODE

device unit number

I I 1/ I I I I I I I I I I I I I I I I I

1//////1/////1/111/11

FIRQB+FQFUN

The function code UU.ASS (octal value = 12).

FIRQB+FQNAM1

For allocating a device, the two bytes beginning here must
equal zero. For reallocating a device, this byte is the job
number to which the device is to be reallocated. The byte at
FIRQB+FQNAM1+1 must equal zero. If you do not have HWCTL
privilege, you can reallocate a device only to a job that is logged in
to the same account as your current account.

FIRQB+FQEXT

For allocating or reallocating a magnetic tape device, this word is
either DOS or ANS (in RAD50 fonnat) to indicate DOS or ANSI
label fonnat for the magnetic tape drive.

.ULOG-UU.ASS

FIRQB+FQMODE

This word contains the mode to use when allocating the device.
Valid modes are:
Mode
Description

100001

Used to allocate a device that is currently allocated to (but. not. opened by) anot.her user. This is
a snagging allocation, available to users wit.h the
HWCTL privilege.

100002

Only used when allocating a LAT port and used
to t.ell the LAT driver that the request to initiate
the connection should not be queued if the remote
port is not. available.

100004

Only used when allocating a LAT port and used to
tell the LAT driver that the request to initiate the
connection should be queued if the remote port is
nM available.

Used when you do not want a snagging allocation
and when you want the LAT driver to use the
port's default queueing setting.

FIRQB+FQDEV

Device name to be allocated or reallocated, specified as two ASCII
characters. If this word is zero, the public disk structure is
assumed.

FIRQB+FQDEVN

Device unit number, passed as a binary value in byte FIRQB+FQDEVN.
A nonzero value in byte FIRQB+FQDEVN+1 indicates an explicit
device unit number. A zero value in byte FIRQB+FQDEVN+1
indicates no device unit. number.

NOTE

The XRB should be cleared to zeros for an allocate or reallocate device
operation.

.ULOG-UU.ASS

3-237

Data Passed -

Enter User logical
FIRQ8

Mne- Octal
monic Offset

Octal
Offset

1/ 1/ /I 1/ 1/ / /I / / / / / / /I

Mnemonic

UU.ASS (= octal 12)

1////1/1//

/1//1/111/

no-replace flag

FQFIL

project number

programmer number

FQPPN

FQNAM1

FQFUN 3

11
13

12
user logical device name in RAD50 format

14
(5 words)

111/1/1111//1///1///1

/ / / / /I / / / / / / / / / / / / / / /

FQPROT 27

protection code

device name (2 ASCII characters)

31
33

3-238

255=assign prot. code

<>0, unit no. real

device unit number

FQPFLG

FQDEV

FQDEVN

/ / / / /I / / / / / / / / / / / / / / /

1/ / / /I / II / II / / / / / / II /

FIRQB+FQFUN

The function code UU.ASS (octal value = 12).

FIRQB+FQFIL

The no-replace flag. Set bit 7 of this byte to 1 to avoid replacing
existing user logicals.

FIRQB+FQPPN

The PPN for those features that use a PPN (see the discussion
under Function at the beginning of this section). For a userassignable PPN, this is the PPN to be used to replace an @ sign in
a string parsed by an .FSS directive. In this case, the two bytes at
FIRQB+FQNAM1 and FIRQB+FQNAM1+1 must be zero. If the
four bytes FIRQB+FQNAM1 through FIRQB+FQNAM1+3 contain
a logical device name, and a PPN is to be associated with that
name, specifY the PPN here. If no PPN is to be associated with
the logical device name, set this word to zero.

FIRQB+FQNAM1

To assign a user logical name to a device, set the five words
beginning here to the logical name, in RAD50 format. Otherwise,
set these bytes to zero.

FIRQB+FQPFLG

To assign a user-assignable default protection code, set this byte
to nonzero. (See FIRQB+FQPROT.)

FIRQB+FQPROT

The protection code to be used as a default if no protection code
is specified in a string scanned by an .FSS directive. The byte
at FIRQB+FQPFLG must. be nonzero, and the two words at
FIRQB+FQPPN and FIRQB+FQNAM1 must. be zero.

FIRQB+FQDEV

Device name for assigning a logical name to be associat.ed with a
device. Specify the device as t.wo ASCII characters. If this word is
zero, the public disk structure is assumed.

.ULOG-UU.ASS

FIRQB+FQDEVN

Device unit number for assigning a logical name to be associated with a device. The device unit number is passed as a
binary value in byte FIRQB+FQDEVN. A nonzero value in byte
FIRQB+FQDEVN+1 indicates an explicit device unit number. A
zero value in byte FIRQB+FQDEVN+1 indicates no device unit
number.
XRB

Mne- Octal
monic Offset

Octal MneOffset monic
length of user logical information

o XFlLEN

length of user logical information

XRBC

starting address for user logical info.

XRLOC

I I I I I I I I I I I I I 1.1 I I I I I I

111111111111111111111

1/1/1/1/1/11/1/11/111

1/ I 1/ 1/ 1/ I I 1/ I I 1/ I I I I

XRB+XRLEN

If the user logical information is in its standard location
(USRPPN, USRPRT, and USRLOG), this word is passed as zero.
If some nonstandard set of locations is being used, then specifY the
length (in bytes) of that information, here. Thus, when the user
logical information is in a nonstandard location, this word must be
at least four (for user-assignable PPN and default protection code).

XRB+XRBC

The length of the information (same as the word at XRB+XRLEN).

XRB+XRLOC

If the word at XRB+XRLEN is nonzero, then this word defines
the starting location for the user logical information (the default
PPN). See Chapter 2 for a description of the order and format of
the information created by .ULOG.

Data Returned
FIRQB

The error code (if any).

FIRQB+FQFIL

The previous owner of the device as follows:
•
e
e

If you own a device already and allocate it, UU.ASS returns
your own job number.
If you seize a device, you can see who you seized it from.
If the value in FIRQB+FQFIL is zero, then you know that the
device was not previously owned.

Errors
BADCNT

This error has two possible causes:
..

•

The length specified at XRB+XRLEN and XRB+XRBC must be 4 + 8n,
where n = 0, 1, 2, 3, or 4. If it is not, this error is returned. (Other
lengths are not valid user logicals.)
The value at XRB+XRLOC is odd.

.ULOG-UU.ASS

3-239

BDNERR

An attempt was made to reallocate a devi.ce to a nonexistent job. This error
can occur only for a reallocate call.

FIEXST

The logical name specified in FIRQB+FQNAMI already exists and the
no-replace flag in FIRQB+FQFIL is set. The logical name is not replaced.

lNUSE

For allocating or reallocating a device, the specified device is currently
open or has an open file. For assigning a user logical, no space is currently
available for storing the information.

NODEVC

The device name specified at FIRQB+FQDEVN is a logical device name for
which a physical device is not currently allocated.

NOTAVL

The device specified exists on the system, but the operation failed for one of
the following reasons:
•
.•
•
•

The device is currently reserved by another job (see description of
FIRQB+FQMODE).
Ownership of the device requires DEVICE privilege, which the user
does not have.
The device or its controller is disabled.
The device is a keyboard line for a pseudo keyboard only.

PRVIOL

You do not have the required privileges and tried to reallocate a device to a
job that is logged in to an account other than your current account.

NOBUFS

No buffers available to initiate the connection to the terminal server.

Example
The following code allocates the user logical name OUT to the public disk structure. Assume that the FIRQB and XRB have been previously cleared to zero. For
example:
MOVB
MOV
MOV
.ULOG

3-240 .ULOG-UU.ASS

tUU.ASS,FIRQB+FQFUN
t~ROUT,FIRQB+FQNAMl
t~R

,FIRQB+FQNAM1+2

Set function code
Set logical name as
two words RAD50

Data Passed-List User Logicals
FIR08
Octal MneOffset monic

Mne- Octal
monic Offset
11111/111111/1111111/

FOFUN 3

UU.ASS (= octal 12)

1111111/11

1111111111

index

FOFIL

(must be 0)

FOPPN

(must be 200 octal)

FONAM1

11111/11111111111111/

11111/111111/111111/1

1111111111111111111/1

I I I / 1/ / / / / / 1/ / / / / I I 1/

/ / / / 1/ / / / / I /I / / I I I I /I

/ / / / /I I I I I I /I I I I I I I /I

FOPROT 27

(must be 0)

11111//11/

/ / / / 1/ / / I / I 1/ I I I I I I 1/

111111//1//1//11111/1

1111/111111/1111111/1

/ / / / 1/ / / I / I 1/ I / I I I I 1/

FIRQB+FQFUN

The function code UU.ASS (octal value = 12).

FIRQB+FQFIL

The index number of the logical name to return. Passing a 1
returns information about the first assigned user logical, passing a
2 returns information about. the second assigned user logical, and
so on.

.ULOG-UU.ASS

3-241

Data Returned-List User Logicals
FIRQB
Mne- Octal
monic Offset

Octal MneOffset monic
1111/111111/1111111/1

I I I /I I I I I I /I I I I I I I 1/ I

1111/11111111111111/1

FQPPN

FQNAM1

project number

programmer number

13
user logical device name in RAD50 format
(5 words)

15
17

1111/111111/1111111/1

I I I /I I I I I I /I I I 1 1 1 1 1/ 1

I I I 1/ I 1 I I I /I I I I 1 I 1 1/ 1

device name (2 ASCII characters)

3-242

<>0, unit no. real

device unit number

FQDEV

32 FQDEVN

I I I /I I I I I I 1/ I I I I I 1 1 1 1

I I I /I I I I I I /I I I I I I 1 1/ I

FIRQB+FQPPN

The PPN assigned to this user logical, or zero if no PPN was
assigned.

FIRQB+FQNAMI

The five words beginning here contain the returned user logical
name in RAD 50 format

FIRQB+FQDEV

The physical device name assigned to this user logical. If no
device name was assigned, this word and the next word both
contain zero.

FIRQB+FQDEVN

Device unit number for assigning a logical name to be associated with a device. The device unit number is passed as a
binary value in byte FIRQB+FQDEVN. A nonzero value in byte
FIRQB+FQDEVN+l indicates an explicit device unit number. A
zero value in byte FIRQB+FQDEVN+l indicates no device unit
number.

.ULOG-UU.ASS

3.35.2

UU.DAL -

Deallocate All Devices and Deassign All User Logicals

Form

MOVE

#UU.DAL,FIRQB+FQFUN

(set up FIRQB and XRB)

.ULOG

Function
The UU.DAL function of .ULOG deallocates all devices and deassigns all user
logicals for the calling program.

Privileges Required
None

Data Passed
FIROB
Octal
Offset

Mne- Octal
monic Offset
/ 1/ / / / / / / 1/ / / / / / 1/ / / /

FOFUN 3

UU.DAL (=octaI14)

1/11111111

1/1//1/1//

deassign-only flag

/1//////11//////1////

/1/1/////1/1////1////

/ 1/ / / / / / / /I / / / / /I / / / /

/ 1/ / / / / / / 1/ / / / / / 1/ / / /

/ 1/ / / / / / / 1/ / / / / / /I / / /

/ 1/ / / / / / / /I / / / / / /I / / /

/1//1////1///////1///

/1/////1////////1////

/ 1/ / / / / / / /I / / / / / /I / / /

/1///////////1///////

/ 1/ / / / / / / 1/ / / / / / 1/ / / /

/ 1/ / / / / / / 1/ / / / / / /I / / /

FIRQB+FQFUN

Mnemonic

FOFIL

The function code UU.DAL (octal value equals 14).

.ULOG-UU.DAL

3-243

The deassign-only flag. Set this byte to 1 to deassign all user
logicals without deallocating devices.

FIRQB+FQFIL

XRB
Octal MneOffset monic

Mne- Octal
monic Offset
length of user logical information

o XRLEN

length of user logical information

2 XRBC

starting address for user logical info.

11/11/111/1111111/111

1/ I I I I I I 1/ I I I I I I 1/ I I I

I 1/ I I I I I 1/ I I I I I I 1/ I I I

11/1/111/111/1111/111

XRLOC

XRB+XRLEN

If the user logical information is in its standard location
(USRPPN, USRPRT, and USRLOG), set this word to zero. If
some nonstandard set of locations is being used, then specify the
length (in bytes) of that information.

XRB+XRBC

The length of the information (same as the word at XRB+XRLEN).

XRB+XRLOC

If the word at XRB+XRLEN is nonzero" then this word defines
the starting location for the user logical information (the default
PPN). See Chapter 2 for a description of the order and format of
the information created by .ULOG.

Data Returned

The UU.OAL subfunction of .ULOG does not return any meaningful data.

Errors
BADCNT

This elTor has two possible causes:
•

•

The length specified at XRB+XRLEN and XRB+XRBC must be 4+8n,
where n 0, 1, 2, 3, or 4. If it is not, this elTor is returned. (Other
lengths are not valid user logicals.)
The value at XRB+XRLOC is odd.

Example

The following code deallocates all devices and deassigns user logicals for the
current job. The user logical information is in its standard location. For example:
MOVB
CLR
CLR
CLR
.ULOG

3-244

.ULOG-UU.DAL

iUU.DAL,FIRQB+FQFUN
XRB+XRLEN
XRB+XRBC
XRB+XRLOC

3.35.3

UU.DEA -

Deallocate a Device or Deassign a User Logical

Form
MOVB

#UU.DEA,FIRQB+FQFUN

(set up FIRQB)

.ULOG

Function

The UU.DEA subfunction of .ULOG deallocates a device from the current job
(releases it for use by other jobs) or deassigns a user-logical assignment.
Privileges Required

None
Data Passed for Deallocate Device
FIROS
Mne- Octal
monic Offset

FOFUN 3

Octal MneOffset monic

1/ / / / / / / 1/ / / / / / 1/ / / / /

UU.DEA (=octaI13)

1//1//1/1/

1/ / / / / / / 1/ / / / / / 1/ / / / /

(must be 0)

FOPPN

(must be 0)

FONAM1

1///////1//////1/////

1/ / / / / / / 1/ / / / / / 1/ / / / /

1/ / / / / / / 1/ / / / / / / / / / / /

1/ / / / / / / 1/ / / / / / 1/ / / / /

1///////1//////1/////

(must be 0)

FOPFLG

device name (2 ASCII characters)

FODEV

FODEVN

<>0, unit number real

device unit number

1///1///1//////1/////

1/ / / / / / / 1/ / / / / / 1/ / / / /

FIRQB+FQFUN

The UU.DEA function code (octal value equals 13).

FIRQB+FQDEV

The name of the device to be deallocated; two ASCII characters .

.ULOG-UU.DEA 3-245

The device unit number is passed in this byte, in binary. A
nonzero value in FIRQB+FQDEVN+1 indicates an explicit device
unit number. A zero value in FIRQB+FQDEVN+1 indicates no
device unit number.

FIRQB+FQDEVN

NOTE

The XRB should be cleared to zeros for deallocating a device.
Data Passed for Deassign User Logical
FIROB
Mne- Octal
monic Offset

Octal MneOffset monic

1/ / / / / / / 1/ / / / / / 1/ / / / /
FOFUN 3

UU.DEA (=octaI13) I

1111111111

II / / / / / / II / / / / / II / / / /

<>0, deassign default ppn; else must be 0

FOPPN

FONAM1

11
13
15

12
user logical device name in RAD50 format
(5 words)

II / / / / / / 1/ / / / / / II / / / /

1/ / / / / / / II / / / / / II / / / /

3-246

1/1/1/1/1/

I<>o,deass def prt cde

1/ / / / / / / 1/ / / / / / / / / / / /

1/ / / / / / / 1/ / / / / / 1/ / / / /

1/ / / / / / / 1/ / / / / / II / / / /

FOPFLG

FIRQB+FQFUN

The UU.DEA function code (octal value equals 13).

FIRQB+FQPPN

Any nonzero value deassigns any previously assigned default
PPN. (In this case, set the word at FIRQB+FQNAM1 to zero.) If
deassigning the default protection code, set this word to zero.

FIRQB+FQNAM1

The logical device name to be deassigned; five words in RAD50
format. If deassigning a default PPN or protection code, set the
word at FIRQB+FQNAMI to zero.

FIRQB+FQPFLG

Set this byte to nonzero if deassigning a protection code.

.ULOG-UU.DEA

XRB
Mne- Octal
monic Offset

Octal MneOffset monic
must be 0

o XRLEN

length of user logical information

2 XRBC

must be 0

/ / 1/ 1/ / / 1/ / / 1/ / / 1/ / / /

1/ 1/ / 1/ 1/ 1/ / / / / 1/ / / 1/

1/ 1/ 1/ 1/ 1/ / / / / 1/ 1/ / / /

1/1/1/1/1/1/1///1//1/

XRLOC

XRB+XRLEN

Must be zero. If the user logical information is in its standard
location (USRPPN, USRPRT, and USRLOG), it will be deassigned.
If it is in any nonstandard location, UU.DEA cannopt deassign the
logicals individually. You can clear logical tables in nonstandard
locations with UU.DAL.

XRB+XRBC

The length of the information (same as the word at XRB+XRLEN).

XRB+XRLOC

Must be zero.

Data Returned
Except for a possible error in byte 0 of the FIRQB, the UU.DEA subfunction of
.ULOG does not return any meaningful data.

Errors
BADCNT

This error has two possible causes:
•

•
NODEVC

The length specified at XRB+XRLEN and XRB+XRBC must be 4+8n,
where n = 0, 1, 2, 3, or 4. If it is not, this error is returned. (Other
lengths are not valid user logicals.)
The value at XRB+XRLOC is odd.

The device or its type specified at the locations FIRQB+FQDEV and
FIRQB+FQDEVN is not part of your system configuration.

Example
The following code deallocates MTO: from the current job:
MOVB
CLR
MOV
MOVB
MOVB
.ULOG

#UU.DEA,FIRQB+FQFUN
FIRQB+FQNAMl
#"MT,FIRQB+FQDEV
#O,FIRQB+FQDEVN
#377,FIRQB+FQDEVN+l

Set function code
Clear name
Set device
Set unit number
Unit number real

.ULOG-UU.DEA

3-247

3.36 .UUO -

Execute BASIC-PLUS SYS Call

Form

.UUO
Function

The .UUO directive lets a MACRO program execute the BASIC-PLUS SYS calls
to the File Processor (FIP). The RSTS / E Programming Manual describes the
SYS calls. For the MACRO programmer's convenience, the FIRQB formats for
the calls are shown here; however, for detailed descriptions see the RSTS / E
Programming Manual.
Table 3-10 summarizes the FIP SYS calls; note that some of the calls are handled by directives other than .UUO. (.FSS, for example, handles the file name
string scan in MACRO.) The mnemonic subfunction names are provided by the
COMMON.MAC prefix file; the decimal values are the BASIC-PLUS FIP call
subfunction codes and the .UUO subfunction codes that COMMON.MAC relates
to the mnemonics listed.
The rest of this section gives the FIRQB formats for data passed and returned for
the .UUO subfunctions; the subfunctions are organized in alphabetical order of
the mnemonics provided by COMMON.MAC.
Table 3-10:

.UUO Subfunctions -

Mnemonic

BASIC·PLUS
SYS Call
Code
(Decimal)

Calls to the File Processor (FIP)

Privileges

That Apply

Function

UU.TB3

-29

None

Get monitor tables-Part III

UU.SPL

-28

r!w file

Spooling

UU.DMP

-27

SYSIO

Snap shot dump

UU.FIL

-26

DATES,TUNE
SYSIO,r!w

File placement and modification

UU.ATR

-25

r!wacct

Read or write attributes

UU.CCL

-24

INSTAL

Add/delete CCL command

(.FSS)

-23

None

Terminating file name string scan

(.SET)

-22

TUNE

Set special run priority

(.SET! .CLEAR)

-21

None

Drop!regain temporary privilege

(.sET! .CLEAR)

-20

TUNE

Lock/unlock job in memory

UU.LOG

-19

SWCTL

Set number of logins

UU.RTS

-18

read file INSTAL

Install run-time system

INSTAL

Load, remove, or unload run-time system

INSTAL

Declare default keyboard monitor

read file INSTAL

Install resident library

INSTAL

Load, remove, or unload resident library

UU.NAM

-17

write file

Name run-time system

UU.DlE

-16

SHUTUP

System shutdown

(continued on next page)

3-248

.UUO

Table 3-10 (Cont.):

.UUO Subfunctions -

Calls to the File Processor (FIP)

Mnemonic

BASIC-PLUS
SYS Call
Code
(Decimal)

Privileges
That Apply

Function

UU.ACT

-15

write acct

Accounting dump

UU.DAT

-14

DATES

Change system date/time

UU.PRI

-13

TUNE

Change priority/run burst/job size

UU.TB2

-12

None

Get monitor tables-Part II

UU.BCK

-11

DATES

Change file backup statistics

(.FSS)

-10

None

File name string scan

UU.HNG

-9

HWCTL

Hangup a dataset

UU.FCB

-8

None

Get open channel statistics

(internal to
BASIC-PLUS)

-7

None

Ctrl/C trap enable

UU.POK

-6

SYSMOD

Poke memory

(.SPEC)

-5

SEND

Broadcast to terminal

(.SPEC)

-4

SYSIO

Force input to terminal

UU.TBI

-3

None

Get monitor tables-Part I

UU.NLG

-2

SWCTL

Disable logins

UU.YLG

-1

SWCTL

Enable logins

UU.PAS

write acct

Create user account

UU.DLU

write acct

Delete user account

UU.MNT

MOUNT

Disk pack status

UU.LIN

None

UU.BYE

WACNTEXTQA

Logout

UU.ATT

write acct DEVICE

Attach Reattach Swap console

UU.DET

JOBCTL EXQTA

Detach

UU.CHU

write acct JOBCTL
HWCTL

Change password/quota Kill job Disable
terminal

UU.ERR

None

Return error message

UU.ASS

DEVICE HWCTL

Allocate/reallocate device t

UU.DEA

None

Deallocate device t

UU.DAL

None

Deallocate all devices t

UU.ZER

DEVICE write acct

Zero a device

UU.RAD

write acct

Read or read-and-reset accounting data

UU.DIR

DEVICE execute or read
file

Directory lookup on index Special magnetic tape directory lookup

UU.TRM

HWCFG

Set terminal characteristics

UU.LOK

DEVICE read file

Disk directory lookup on file name Disk
wildcard directory lookup

UU.CHE

TUNE

Enable/disable disk caching

UU.CNV

None

Date and time conversion

tTo assign or deassign user logicals, use .ULOG.
(continued on next page)
.UUO

3-249

Table 3-10 (Cent.):

Mnemonic

.UUO Subfunctions -

Calls to the File Processor (FIP)

BASIC-PLUS
SYS Call
Code
(Decimal)

Privileges
That Apply

Function

UU.SLN

INSTAL

System logical names

(.MESAG)

SEND SYSIO

Message send/receive

UU.SWP

r/w files INSTALL

Install, remove, list system files

UU.JOB

WACNT JOBCTL
EXQTA

Create job

UU.PPN

DEVICE

Wildcard PPN lookup

UU.SYS

JOBCTLTUNE

Return job status information

UU.PRV

None

Set/clear/read current privileges

UU.STL

HWCTL

Stalllunstall system

UU.3PP

None

Third-party privileges

UU.CHK

None

Check access function

UU.ONX

DEVICE DATES
r/w files

Open next disk file

UU.CFG

HWCFG SWCFG
HWCTL

Change system characteristics and device
defaults

3-250

.UUO

3.36.1

UU.ACT (Accounting Information Dump)
Privileges Required

GACNT or WACNT is required for access to accounting data.
Data Passed
FIRQ8
Mne- Octal
monic Offset

Octal MneOffset monic
1/ I I I I I I 1/ I I I I I 1/ I I I I

UU.ACT (= -17)

FQFUN 3

1/ I I I I I I 1/ I I I I I I I I I I I

project number

/11/1/1/11

programmer number

/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 /I I I I I I 1/ 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 I I I I /I I I I I I /I / / / /

/I I / / / / / /I / / / / / /I / / / /

/I / / / / / / /I / / / / I /I / / / /

/I / / / / / / /I / / / / / /I / / / /

FIRQB+FQPPN

FQPPN

Zero in both bytes means the current account.

Data Returned

Except for a possible error in byte 0 of the FIRQB, The UU.ACT subfunction of
.UUO does not return any meaningful data.
Errors
NOSUCH

The account specified does not exist.

PRVIOL

A caller with GACNT privilege specified an account outside the caller's
group.

.UUO-UU.ACT 3-251

3.36.2

UU.ASS (Allocate/Reallocate Device)
Privileges Required

DEVICE is needed to al10cate a restricted device. HWCTL is required to seize a
device or reallocate a device to a job in another account.
Data Passed
FIR08
Mne- Octal
monic Offset

Octal MneOffset monic

FOFUN 3

UU.ASS (= 12)

1/1/1/1///

I 1/ I I I I I I 1/ I /I I I I I I I I

I 1/ I I I I I I 1/ I I I I I I I I I I

(must be 0)

lo,alloc.;<>o ,realioc.

FONAM1

11/1111111/111111/111

DOS or ANS in RAD50 format (1 word)

I 1/ I I I I I I 1/ I I I I I 1/ I I I

I 1/ I I I /I I 1/ I I I I I I I I I I

mode

I 1/ I I I I I I 1/ I I I I I 1/ I I I

must be 0

FOPFLG

device name (2 ASCII characters)

FODEV

FODEVN

31
33

3-252

11/11111/1/111111/111

<>O,unit no. real

device unit number

12
14 FOEXT

I II I I I I I I 1/ I I I I I I I I I I

I 1/ I I I I I I 1/ I I I I I 1/ I I I

FOMODE

FIRQB+FQFUN

The function code ASSFQ (octal value = 24).

FIRQB+FQNAMI

FIRQB+FQEXT

When the device is magnetic tape, t.his word can contain either
DOS or ANS in RAD50 format, to indicate DOS or ANSI label
format for the tape drive. It can also be set to zero to indicate the
system default for the drive.

.UUO-UU.ASS

FIRQB+FQMODE

This word contains the mode to use when allocating the device.
Valid modes are:
Mode
Description

100001

Used to allocate a device that is ctUTently
allocated to (but not opened by) another user.
This is a snagging allocation, available to users
with the HWCTL privilege.

100002

Only used when allocating a host-initiated LAT
port and used to tell the LAT driver that the
request to initiate the connection should not be
queued if the remote port is not available.

100004

Only used when allocating a host-initiated
LAT port and used to tell the LAT driver that
the request to initiate the connection should be
queued if the remote port is not available.

Used when you do not want a snagging allocation and when you want to use the default
queueing setting on a host-initiated LAT port.

FIRQB+FQDEV

Device name, as two ASCII characters.

FIRQB+FQDEVN

The device unit number is passed here in binary. A nonzero value
in FIRQB+FQDEVN+1 indicates an explicit device unit number.
A zero value in FIRQB+FQDEVN+1 indicates no unit number.

Data Returned
FIRQB

The error code (if any).

FIRQB+FQFIL

The previous owner of the device as follows:
•
•
•
•

If you own a device already and allocate it, UU.ASS returns
your own job number.
If you seize a device, you can see who you seized it from.
If you reallocate the device, you can see who owned it before
the reallocation.
If the value in FIRQB+FQFIL is zero, then you know that the
device was not previously owned.

Errors
BDNERR

Your program attempted to reallocate a device to a nonexistent job.

INUSE

For a reallocate, the specified device is open or has an open file.

NODEVC

Device name at FIRQB+FQDEV is not a valid device name on this system.

NOTAVL

The device specified exists on the system, but the operation failed for one of
the following reasons:
•
•
•
•

The device is currently reserved by another job (see description of
FIRQB+FQMODE).
The device or its controller is disabled.
The device is a keyboard line for a pseudo keyboard only.
You do not have DEVICE privilege and the device is restricted.

PRVIOL

You do not have the required privileges and tried to reallocate a device to a
job that is logged in to an account ot.her that you current account.

NOBUFS

No buffers available to initiate the connection to the terminal server.

.UU~UU.ASS

3-253

3.36.3

UU.ATR (Read/Write Attributes)
Privileges Required (Read/Write File Attributes)

None
Data Passed (Read/Write File Attributes)
FIROB
Mne- Octal
monic Offset

Octal
Offset

/ / / / I! / / / / / / / / / / / / / I!

Mnemonic

FOFUN

UU.ATR (= -31)

I/////I!I!

FOSIZM

=O,read; i-11,write

channel number

FOFIL

FOPPN

FONAM1

FOEXT

FOSIZ

attribute data (used only for write)

FONAM2

number of words written = 1-11. as
specified in byte 5

FOMODE

1 attribute per word

FOFLAG

FOPFLG

FODEV

FODEVN

/ / / / I! / / / / / /I / / / / / / /I

/ / / / I! / / / / / / / / / / / / / /I

Data Returned (Read/Write File Attributes)

Other than a possible error in byte 0 of the FIRQB, data is returned on a read
only (byte 5 of data passed equals zero).

3-254

.UUO-UU.ATR

FIROB
Mne- Octal
monic Offset

3
5

Octal MneOffset monic

/ / / / / / / / / 1/ / / / / / / / / / /

1/1/1//1//

current job no .• 2

1/ / 1/ / 1/ / 1/ / / II / II II /

FOJOB

FQPPN

FONAM1

FOEXT

FOSIZ

FONAM2

FOMODE

FQFLAG

FOPFLG

FODEV

FODEVN
FOCLUS

attribute data
(If file has no attributes,
FIRQB+6 and FIROB+7 = 0)

name of run-time system in RAD50 format

(2 words)

Errors (Read/Write File Attributes)
BADCNT

Write only. No value greater than 11 can be specified at FIRQB+FQFIL+l.

BSERR

Attributes can be written only on channels 1 through 15.

DEVNFS

Device on which file is open must be disk.

NOROOM

Occurs only on a write. The User File Directory (UFD) ofthe account is fun.
Some files must be deleted to free entries for attributes.

NOTOPN

Channel specified at FIRQB+FQFIL must have file open.

PRVIOL

Job does not have read/write access to the file open on the channel, or a
UFD is open on the channel.

Privileges Required (Read/WritelDelete Account Attributes)

No privileges are required to read attributes 1, 2, and 4 to 191 of your own
account. That is, of the Digital-defined attributes you can read an except the
password. Of the user-defined attributes (128 to 255) you can read the first
64. To read attribute 3 (password) or attributes 192 to 255, you need GREAD,
WREAD, GACNT, or WACNT privilege.
Read or accounting privileges (GREAD, GACNT, WREAD, or WACNT) are required to read accounting data of other accounts. Accounting access (GACNT or
WACNT) is required to write or delete accounting data of any account .

.UUO-UU.ATR

3-255

Data Passed (Read/Write/Delete Account Attributes)
FIROB
Octal MneOffset monic

Mne- Octal
monic Offset

/ / / / /I / / / / / / /I / / / / / /I

FOFUN 3

UU.ATR (= -31)

1/1/1/1/1/

FOSIZM5

attribute type code

subfunction code

project number

programmer number

FOPPN

(see discussion)

FONAM1

7
11

13
15

13 bytes of data
(only on write)

FONAM2

/ / / / / 1/ / / / / / /I / / / / / 1/

device name (2 ASCII characters)

FOOEV

FOOEVN

3-256

FOFIL

<>0, unit no. real

device unit number

////1///////1//1///1/

/ / / / /I / / / / / / II / / / / / II

FIRQB+FQFUN

The function code UU.ATR (octal value =-31).

FIRQB+FQFIL

The subfunction code:
-1
Read account attributes
-2
Write account attributes
-3
Delete account attributes

FIRQB+FQSIZM

The attribute type code:
o
Look-up by index
1
Quotas
2
Authorized Privilege Mask
3
Password
4
Date/time information
5
User name information
6
Nondisk quotas

FIRQB+FQPPN

The PPN of the account accessed. The project number is in the
high byte (FQPPN+1), and the programmer number is in the low
byte (FQPPN). A value of zero defaults to the caller's PPN.

FIRQB+FQNAM1

The index in a "look-up by index." Look-up by index is specified by using a type code of zero in FIRQB+FQSIZM and -1 in
FIRQB+FQFIL. For programs like BACKUP, it is useful to read
all the account attributes without having to try each of the 255
possible type codes. The value n of the index specifies that you
want nth attribute type.

.UUO-UU.ATR

FIRQB+FQNAM1+1

The account attributes to be written to one attribute block. See
the RSTS! E Internals and Data Structures Manual for details
about each account attribute. The data is written exactly as
passed except for attribute types 2 and 4.
For type 2 (authorized privilege mask), when writing the mask,
any attempt to turn on privilege bits are ignored if the caller
does not have the corresponding privilege currently in effect. The
layout of the 13 bytes are:
•
..
..

FIRQB+ll-reserved
FIRQB+12 through +21-authorized privilege mask
FIRQB+22 through +25-reserved

For type 4 (date/time information), the last login fields are left
alone unless the fields are currently null. This ensures that any
logins to an account leave a trace that cannot be tampered with.
The layout of the 13 bytes are:
"
..

FIRQB+ll-keyboard oflast interactive login
FIRQB+12,+13--date oflast interactive login (RSTS internal
format)

FIRQB+14,+15-time oflast interactive login (RSTS internal
format)

"
..
..
"

FIRQB+16,+17-date oflast password change
FIRQB+20,+21-time of last password change and flags
FIRQB+22,+23-date of account creation
FIRQB+24,+25--expiration date (-1 if none)

The flags in FIRQB+14,+15 are:
"
"

Bit 11-no password required ("guest" account)
Bits 12-15-reserved

The flags in FIRQB+20,+21 are:
..
"
"
•
..

Bit 11-password cannot be looked up ("hashed" password)
Bit 12-no dial-up logins allowed
Bit 13-no network logins allowed
Bit Vl·-no interactive logins allowed (spawn and batch only)
Bit I5-captive account

If bit 11 is set, then passwords can be up to 14 characters long and
the system stores them in hashed form. The hash uses parts of
the date/time attributes; so, altering any bits of bytes FIRQB+16
through FIRQB+23 (except for the flag bits) renders the password
useless. The read accolmting data directive (UD.RAD) returns two
zero words if this bit is set. If bit 11 is clear, then passwords can
be up to six characters long and must consist of uppercase letters
and numbers; that is, the RAD50 character set.
FIRQB+FQDEV

The device name passed; two ASCII characters. A value of zero
indicates "SY", public disk.

FIRQB+FQDEVN

The device unit number passed in binary notation. A nonzero
value in the high byte of this word (FIRQB+FQDEVN+I) indicates
an explicit device unit number. A zero value in the high byte
indicates no unit number.

.UUO-UU.ATR

3-257

Data Returned (Read/Write/Delete Account Attributes)

Other than a possible error in byte 0 of the FIRQB, data is returned only on a
read subfunction (-1 in FIRQB+FQFIL).
FIROB
Mne- Octal
monic Offset

Octal MneOffset monic

/ / / /I / / / / / /I / / / / / / / / /

FOJOB

11/1/1/1/1

current job no .• 2

attribute type code

///1////1/

project number

programmer number

FOPPN

attribute type

FONAM1

11
13

14
13 bytes of data

//1//////1///////1//1

II I /I /I I I I /I I I II II II I

/1111/1 II I 11111111/11

I I I I I / / I I I /I / I I I I I / I I

/1/ /1/// ////1/1111111

FIRQB+FQNAMI

The attribute type code. Contains the type code of the attributes
just read (same as passed except for lookup by index).

FIRQB+FQNAMl+1

The actual attribute data.

Errors (Read/Write/Delete Account Attributes)
DEVNFS

The specified device is not a disk.

EOF

The attribute type not found (read or delete only). The index specified for an
indexed look-up call is greater than the number of attributes (read only).

NODEVC

The specified device does not exist.

NOROOM

The attribute block did not exist and it cannot be added because the directory is full (write only).

NOSUCH

The specified account does not exist.

NOTMNT

The specified disk is not mounted.

PRVIOL

You do not have sufficient privilege for the operation. The disk is writelocked (write and delete only). Attempt to delete in the Digital-reserved
type range (delete only).

Privileges Required (Read Pack Attributes)

DEVICE is required if the device specified is restricted.

3-258

.UUO-UU.ATR

Data Passed (Read Pack Attributes)
FIR08
Mne- Octal
monic Offset

Octal MneOffset monic
I I! I I I I I I I! I I I I I I! I I I

FOFUN 3

UU.ATR (= -31)

I! I! I! I! I!

1/1/1/1/1/

subfunction code (-4)

FOFIL
FOPPN

I 1/ I I I I I I 1/ I I I I I 1/ I I I

1/ I I I I I I I 1/ I I I I I 1/ I I I

10 FONAM1

I 1/ I I I I I I 1/ I I I I I I! I I I

I I! I I I I I / II / I / / / I! / / I

14 FOEXT

I I! I I I I I I 1/ / I I I / I! I I I

16 FOSIZ

I I! I I I / / I I! / I I I I I! I I I

FONAM2

I II / / I / I / I! I I I I I I! I I I

FOMODE

/111/1/1/1/1//1/1////

FOFLAG

I I! I I I / / / 1/ I I I I I I! I I I

FOPFLG

device name (2 ASCII characters)

FODEV

FODEVN

<>0, unit no. real

device unit number

I 1/ 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 I I I! I / I

.UUO-UU.ATR

3-259

Data Returned (Read Pack Attributes)

This call returns information about mounted disks. It is used to obtain the
characteristics of a disk and the drive the disk is mounted in.
FIRQB
Octal
Offset

MneOctal
monic Offset

Mnemonic

I I 1/ I I I I I I 1/ I I I I I 1/ I I

1/1/1/11111/111111/11

I I 1/ I I I I I I 1/ I I I I I 1/ I I

1st DCN of MFD

10 FQNAM1

Pack Revision Level

Pack Cluster Size

14 FQEXT

Pack Status/Flags

16 FQSIZ

Pack ID in RAD50 format

20 FQNAM2

(in 2 words)

22 FQMODE

Size of disk in DCNs

24 FQFLAG

Device Cluster Size

26 FQPFLG

111/1111111/11/111/11

I I 1/ I I I I I I 1/ I I I I I 1/ I I

FIRQB+FQNAMI

The starting device cluster number (DON) of the MFD.

FIRQB+12

The pack revision level.

FIRQB+FQEXT

The pack cluster size.

FIRQB+FQSIZ

The pack status/flags. The defined bits are:
• Bit 9--Pack is initialized "new files first"
• Bit ll-Pack is initialized to maintain date of last write
• Bit 12--Pack is initialized as a read-only pack
• Bit 14--Pack is initialized as a private/system disk
All other bits are reserved.

3-260

FIRQB+FQNAM2

The pack ID in RAD50 format. The first three characters
are here and the last three characters are in the next word,
FIRQB+FQMODE.

FIRQB+FQFLAG

The size of the disk in DONs.

FIRQB+FQPFLG

The device cluster size.

.UUO-UU.ATR

Errors (Return Pack Attributes)

NOTMNT
NODEVC

Device specified is not a logically mounted device.
Device specified is not valid.

.UUO-UU.ATR

3-261

3.36.4

UU.ATT (Attach/Reattach Job/Swap Console)
Privileges Required

DEVICE is required to perform a REATTACH if the terminal is restricted.
GACNT or WACNT is required to ATTACH to a job outside the caller's account.
Data Passed -

Attach
FIRQ8
Octal MneOffset monic

Mne- Octal
monic Offset
/ / / / /I / / / / / / /I / / / / / /I

FQFUN 3

UU.ATT (= 6)

FQSIZM5

7
11

/1////////

bit mask

job number to attach

FQFIL

project number

programmer number

FQPPN

FQNAM1

password in RAD50 format

(2 words)

password in ASCII format

(7 words)

/ / / / /I / / / / / / /I / / / / / /I

/ / / / /I / / / / / / /I / / / / / II

/ / / / /I / / / / / / /I / / / / / /I

/ / / / /I / / / / / / /I / / / / / II

FIRQB+FQSIZM

Bit 0 must be clear for the attach subfunction. Bit 1 is clear for
the old password format (RAD50) and set for the new format
(ASCII). Bit 2 can be set on an attach to suppress the password
check. If clear, the password is checked if you attach to a job in
another account. All other bits are reserved.

FIRQB+FQPPN

Zero in both bytes means your PPN. You do not need to include a
password. If you do not have GACNT or WACNT privilege, you
can only specifY your own PPN.

FIRQB+FQNAMI

You must include a password if you specifY a PPN other than your
own unless bit 2 is set in FIRQB+FQSIZM. Note that this use of
the call requires GACNT or WACNT privilege.

Data Returned

Other than a possible error in byte 0 of the FIRQB, the attach function of the
UU.ATT directive does not return any data.

3-262

.UUO--UU.ATI

Errors
BADFUO

The system returns this error for one of the following reasons:
•
•
"
•
e

Data Passed -

Job executing the call has an open channel.
Job executing the call is detached.
Job number at FIRQB+FQFIL is not detached.
The PPN specified does not match PPN of job to attach.
Caller does not have GACNT or WACNT privilege, and the job to attach
to has a PPN different from that of the caller.
Password is not valid.

Reattach
FIRQB

Mne- Octal
monic Offset

Octal
Offset
/ /I / / /I / /I / / / /I / / / /I /

Mnemonic

FQFUN 3

UU.ATT (= 6)

//////////

FQSIZM5

KB no. to attach to

caller's job number

/I /I / /I / /I / / / /I / / /I /I

II /I / II / /I II / /I / / / / / /

II II / II / II / / / II / / II II

/ / II / /I / / / / / / II / / II II

/I / / / II II / / / / II / / / / / /

/ II / / / II / / / / / /I II II II

II II / II / /I / / / 1/ / / / / /I

/ / II II II II / / / / /I / /I /I

/I /I / /I / / / / /I /I / / / / / /

/I / / / /I / / / / / / /I / / / /I /

II /I / /I / / / / / / II / / / / /I

/I /I / /I /I /I / / II / / / /I /

/ II /I /I / /I / / / /I / / II / /

FQFIL

Data Returned

Other than a possible error in byte 0 of the FIRQB, the reattach function of the
UU.ATT directive does not return any data.

.UUO--UU.ATI

3-263

Errors
BADFUO

The system returns this error for one of the following reasons:
•
..
•
..
•

Data Passed -

Job number at FIRQB+FQFIL is out of range or no such job exists.
Caller is not detached.
KB number is out of range.
KB is currently allocated, opened, or the console keyboard of some job
other than the calling job.
The terminal is restricted and the caller does not have DEVICE privilege.

Swap Console
FIRQB

Mne- Octal
monic Offset

Octal
Offset
/ / / / / / / / / / / / / II / / / / / /

Mnemonic

FQFUN 3

UU.ATT (= 6)

/11111111/

FQSIZM5

bit mask

job no. to swap with

II II II II II / / II / / / / II /

/ / / / / / / / / / / / / II / / / / / /

II II / II / / / / / II II / / II /

/ / / / / / / / / / / / / II / / / / / /

/ / / II II / / / II II II II / II

/ I I / / I I / I I / I I II I I I / I /

/////1////////1/ ///11

I / I / I II I I I I I I II / I I I / /

I I / I / / I I / / I I I II I I I / / /

/ / I / / / I I / / I / / II I I / / I I

I I I / I I I I I / I I I II I I / / / I

/ / / / / II / / / / I I II / I I / / I

111/111111/1///// II //

FQFIL

FIRQB+FQSIZM

Bit 0 must be set for the swap console subfunction. All other bits
are reserved.

FIRQB+FQFIL

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.

Data Returned
Other than a possible error in byte 0 of the FIRQB, the swap console function of
the UU.ATT directive does not return any data.

3-264

.UUO-UU.ATT

Errors
BADFUO

The system returns this error for one of the following reasons:
•
•
•

Both the culling job and the job specified at FIRQB+FQFIl, are detached, or neither job is detached.
The job specified at FIRQB+FQFIL has a PPN different from the
caller's.
The value at FIRQB+FQSIZM is neither 0 nor 1.

.UU~UU.ATT 3-265

3.36.5

UU.BCK (Change File Statistics)
Privileges Required
DATES is required to change the last access date.
Data Passed
FIROB
Mne- Octal
monic Offset

Octal MneOffset monic

/ / / / /I / / / / / / /I / / / / / /I
FOFUN 3

UU.BCK (= -13)

FOSIZM5

/I//////I!

LSB of last access

channel no. (1-17)

FOFIL

LSB of creation date

MSB of last access

FOPPN

LSB of creation time

MSB of creation date

FONAM1

/1/1/1/1//

MSB of creation time

/ / / / 1/ / / / / / / /I / / / / / II

/ / / / /I / / / / / / /I / / / / / I!

/ / / / /I / / / / / / 1/ / / / / / I!

/ / / / I! / / / / / / / / / / / / / I!

/ / / / / / / / / / / / 1/ / / / / / I!

/ / / / I! / / / / / / / / / / / / / 1/

/ / / / 1/ / / / / / / 1/ / / / / / /I

/ / / / /I / / / / / / /I / / / / / /I

/ / / / 1/ / / / / / / 1/ / / / / / 1/

FIRQB+5,6
FIRQB+7,10

The system internal format for dates has the form:
[(year - 1970) * 1000J + day-within-year

FIRQB+ll,12

Time is specified in minutes until midnight, where 1440 equals
midnight. .

NOTE

See the .DATE directive for a discussion of these fonnats.
Data Returned
Other than a possible error in byte 0 of the FIRQB, the UU.BCK subfunction does
not return any meaningful data.
Errors

3-266

BADFUO

The file open on the channel specified is either not a disk file or is a user file
directory (UFD).

PRVIOL

The disk is write protected or you do not have write access to the file.

.UUO-UU.BCK

3.36.6

UU.BYE (Logout)
Privileges Required
EXQTA is required to log out without a quota check. WACNT is required to log
out without a self-kill.

Data Passed
FIROB
Mne- Octal
monic Offset

Octal
Offset
I /I I I I I I I /I I I I I I /I I I I

FOFUN 3

UU.BYE (= 5)

1/1/1/1/1/

type of logout

I /I I I I I I I /I I I I I I /I I I I

11/1111111/111111/111

I 1/ I I I I I I 1/ I I I I I 1/ I I I

I 1/ I I I I I I 1/ I I I I I /I I I I

FIRQB+FQFIL

Bits 0 and 1 specify:
Bit Setting Meaning

Mnemonic

FOFIL

Clear

Close I/O channels, deassign devices, remove receivers, and dismount disks mounted INOSHARE
before performing logout.

Set

Perform logout only; do not close channels,
deassign devices, remove receivers, or dismount
disks. This call requires WACNT privilege.

Clear

Check quotas on all mounted disks before performing logout.

Set

Perform logout without checking disk quotas.
This call requires EXQTA privilege.

If the caller does not have WACNT privilege, RSTSIE forces Bit 0
clear. If the caller does not have EXQTA privilege, RSTSIE forces
Bit 1 clear. Bits 2 through 7 are reserved.

.UUO-UU.BYE 3-267

Data Returned
FIROB
Mne- Octal
monic Offset

Octal MneOffset monic
/ / / / / / /I / / / / / / /I 1/ / / /

//////////////1/1//1/

logout status (0, -1, or -2)

/ / / / / / 1/ / / / / / / / 1/ / / / /

///1//1/111111/1/111/

1/11111/1111111/11111

I I I I I I 1/ I 1/ I I I 1/ I I I I I

FOFUN 3

1/11111111

quota code

FOSIZ

MSB of current usage

MSB of current quota

FONAM2

no. of det. jobs

FOMODE

no. of det. jobs all.

LSB of current disk quota (in blocks)

FOFLAG

LSB of current disk usage (in blocks)

FOPFLG

disk name (2 ASCII characters)

FOOEV

FOOEVN

<>0, unit no. real

disk unit number

111111111111111111111

1/11111/111111/11111/

FIRQB+FQFIL

Zero means neither disk quota nor detached job quota is exceeded.
If you have WACNT privilege, the system returns control to your
program. Otherwise, the system kills your job after performing
necessary clean-up functions. Minus one means a quota is exceeded; your job is still logged in. Minus two means a quota is
exceeded, but your job is logged out. If you have WACNT privilege, the system returns control to your program. Otherwise,
the system kills your job after performing necessary clean-up
functions.

FIRQB+FQSIZ

Indicates which quota is exceeded. (This value is valid only if
FIRQB+FQFIL equals -lor -2.) Zero means disk quota. One
means detached job quota.

FIRQB+FQMODE

Returned if detached job quota is exceeded. FIRQB+FQMODE
contains the number of detached jobs in the current account.
FIRQB+FQMODE+1 contains the number of detached jobs allowed.

FIRQB+FQDEV

Returned if disk quota is exceeded.

Errors
No errors are possible with the UU.BYE subfunction.

3-268

FOFIL

.UUO-UU.BYE

3.36.7

UU.CCl (Add/Delete CCl Command)
Privileges Required

INSTAL is required to add or delete a CCL command.
Data Passed -

Add
FIRQ8
Octal
Offset

Mne- Octal
monic Offset

Mnemonic

/ /I / / / / / / /I / / / / / /I / / /
FQFUN 3

UU.CCl (= -30)

/1/1/1/1/1

FQSIZM 5

abbrev. point, chars

must = 0 for add

FQFll

project number

programmer number

FQPPN

FQNAM1

7
11
13

file name in RAD50 format
of program to run
(2 words)

file type in RAD50 format (1 word)

FQEXT

CCl command
one to nine characters
padded with NUls (ASCII code 000)
to nine characters

FQSIZ

FQPROT 27

(must be 0)

device name (2 ASCII chars) must be disk

FQDEV

<>O,unit number real

FQDEVN
FQClUS

device unit number

line number to start execution

/ /I / / / / / / /I / / / / / /I / / /

FIRQB+FQSIZ

The name you give to the CCL command you are defining; from
one to nine characters, padded with nulls.

Example
MOVB
CLRB
MOVB
MOV
MOV
MOV
MOV
MOV
MOV
CLR
CLR
CLR
MOV
CLRB
MOVB
CLR
.UUO

#UU.CCL,FIRQB+FQFUN
FIRQB+FQFIL
#2,FIRQB+FQSIZM
#195.*256.+1,FIRQB+FQPPN;
#ARTES,FIRQB+FQNAM1
#ART , F IRQB+FQNAM1 +2
#ARTSK,FIRQB+FQEXT
#"XR,FIRQB+FQSIZ
#"UN,FIRQB+FQSIZ+2
FIRQB+FQSIZ+4
FIRQB+FQSIZ+6
FIRQB+FQSIZ+10
#"SY,FIRQB+FQDEV
FIRQB+FQDEVN
#-1,FIRQB+FQDEVN+1
FIRQB+FQCLUS

FUNCTION CODE ADD/DELETE CCL
ADD FUNCTION
ABBREV. POINT IN CHARACTERS
PPN [195,1]
FILE NAME IS TEST.TSK

COMMAND IS "XRUN"
PAD COMMAND WITH NULLS
HIGH BYTE MUST BE ZERO
DEVICE NAME IS SY
UNIT 0
AND UNIT NUMBER IS REAL
PROGRAM STARTS AT LINE 0
CREATE THE CCL

.UUO-UU.CCL 3-269

Data Passed -

Delete
FIRQ8
Octal
Offset

Mne- Octal
monic Offset

I I I I 1/ I I I I I 1/ I I I I I I 1/
FQFUN 3

UU.CCl (= -30)

1/1/11///1

FQSIZM5

abbrev. point, chars

= -2 for delete

o
2
4 FQFll

I I I I I I I I I I I I I I I I I I I /I

I I I I 1/ I I I I I 1/ I I I I I I II

I I I I I I I I I I I II I I I I I I II

I I I I 1/ I I I I I II I I I I I I II

CCl command
one to nine characters
padded with NUls (ASCII code 000)
to nine characters

16 FQSIZ

1111111111

Mnemonic

I I I I II I I I I I I I I I I I I I II

I I I I I I I I I I I I I I I I I I I II

I I I I I I I I I I I II I I I I I I II

I I I I II I I I I I II I I I I I I II

Data Returned

Except for a possible error in byte 0 of the FIRQB, the UU.CCL directive does not
return any meaningful data.
Errors

3-270

BADNAM

For add only. The CCL command either begins with a number or contains
an otherwise unacceptable character.

INUSE

For add only. The CCL command is already defined.

NODEVC

For delete only. The CCL command does not exist.

.UUO-UU.CCL

3.36.8

UU.CFG (Set Device/System Default Characteristics)
Privileges Required

HWCFG is required to:
•

Declare a device as restricted or unrestricted

•

Set magnetic tape default density

•

Set line printer characteristics

SWCFG is required to:
•

Set magnetic tape label defaults

•

Set power fail delay

•

Set date/time presentation formats

•

Set system flags

•

Set dynamic region limit

SWCTL is required to set or return system Answerback.
HWCTL is required to enable/disable a device.

.UUO-UU.CFG 3-271

Data Passed (Set DEVn: characteristics)
FIR08
Mne- Octal
monic Offset

Octal MneOffset monic
II I I I I I I II I I I I I II I I I I

FOFUN 3

UU.CFG (= 42)

1111111111

111111111/

subfunction code =0

FOFIL

parameter switches

par. change flags

FOPPN

II I I I I I I II I I I I I 1/ I I I I

1/ I I I I I I II I I I I I 1/ I I I I

1/11111/1/111111/1111

1/ I I I I I I II I I I I I 1/ I I I I

II I I I I I I 1/ I I I I I 1/ I I I I

1/1111/11/111111/1111

1/ I I I I I I II I I I I I 1/ I I I I

device name (2 ASCII chars) not a disk

FODEV

FODEVN

377

1/ I I I I I I 1/ I I I I I 1/ I I I I

FIRQB+FQPPN

device unit number

Parameter change flags:
Bit Setting Meaning

o
1

Clear

No change in enable/disable status

Set

Use value in FIRQB+FQPPN+l to change status

Clear

No change in device ownership

Set

Use value in FIRQB+FQPPN+l to change ownership

Clear

No change in modem control

Set

Use value in FIRQB+FQPPN+l to change modem control
All combinations of the bit values are legal.
FIRQB+FQPPN+ 1

If FIRQB+FQPPN is zero, then this byte should also be zero. If
FIRQB+FQPPN is not zero, then the fonowing values are used to
alter device parameters:
Bit Setting Meaning

3-272

.UUO-UU.CFG

Clear

Enable device

Set

Disable device

Clear

No privilege needed for device ownership

Set

DEVICE privilege needed for device ownership

Clear

Put device under LOCAL control

Set

Put device under MODEM control

Data Returned (Set DEVn: characteristics)

Except for a possible error in byte 0 of the FIRQB, the system returns the
following:
FIRQ8
Mne- Octal
monic Offset

Octal MneOffset monic
/ /I / / / / / /I / /I / /I /I / /I

/ /I / / /I /I / / /I /I / /I / / /

/ /I / / / / / /I /I /I / / /I / / /

device parameters

device status flags

/ /I / / / /I /I /I / /I / /I / /I

/ /I / / / / / /I /I / /I / /I / /I

/////////////////////

/ /I / / / /I /I / / /I /I /I / /I

/I / / / / /I II / /I /I / II / /I

/ /I / / / /I /I / /I /I / /I /I /

/ /I / / / /I /I / /I /I / /I / /I

/ /I / / / /I /I / / / / / / II 1/ /

1/ / / / / / /I / / 1/ / / / /I 1/ /

/////1////1///////1//

/ /I / / / 1/ /I / / / / / /I / /I /

/I / / / / / /I / /I /I 1/ /I 1/ /

FIRQB+FQPPN

FQPPN

Device status flags indicating:
Bit Setting Meaning
0

1
2

Clear

Device is enabled and free

Set

Device is disabled or in use

Clear

Device ownership does not require privilege

Set

Device ownership requires HWCFG privilege

Clear

Device is in LOCAL mode

Device is under MODEM control
Set
Note that Bit 2 is only valid if the device name passed in
FIRQB+FQDEV is KB.
FIRQB+FQPPN+ 1

Valid values are: O-If bit 0 in FIRQB+FQPPN is clear. 3-The
device was disabled by this call and can be enabled by this call.
Any even integer-Job number * 2 of the current device owner.
Any odd integer (other than 3}-The device was disabled by the
monitor and cannot be enabled.

.UUO-UU.CFG

3-273

Errors (Set DEVn: characteristics)

INUSE

An attempt was made to disable a device that was in use by another user or
one that had been previously disable.

NOTAVL

An attempt was made to enable a device which was not disabled through
use of this call.

PRVIOL

An attempt was made to alter device characteristic of a disk unit.

Data Passed (Set LPn: characteristics)
FIROB
Octal
Offset

Mne- Octal
monic Offset
/I I 1/ /I II I I /I I I /I I I I I

FOFUN 3

UU.CFG (= 42)

/11/1/1/11

/1/1/1/1/1

subfunction code =1

FOFIL

default form length

default page width

FOPPN
FONAM1

set characteristics flag bits mask

clear characteristics flag bits mask

3-274

Mnemonic

LPTSPC (ASCII value)

O=no chg/1 =chg LPTSPC

FOEXT

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

II I //////////////1///

/1//11//1//1//1/1/11/

/11//1//1///1/1/1/1/1

device name (2 ASCII chars) must be "LP"

FODEV

FODEVN

377

device unit number

111/1111/11111///11/1

/I I I I I I II I I /I I I II I I /I

FIRQB+FQPPN

Default Page Width; zero indicates no change, nonzero indicates the new value for the default page width.

FIRQB+FQPPN+l

Default Printer Form Length; zero indicates no change, a
nonzero value is the new default printer form length. The
maximum value is 377 octal.

.UUO-UU.CFG

FIRQB+FQNAMI

Set characteristics flag bits mask. Zero indicates no change. A
nonzero value represents the flag bits to be set in the characteristics flag word. The bit positions currently in use are:
Bit 0

Allow <BS> for backspace (LAI80)

Bit 1

Do not process <BS> as backspace

Bit 2

Allow 8-bit characters (LN01)

Bit 3

Allow nonprinting characters

Bit 4

No fill for <FF>

Bit 5

Allow <EOT>

Bit 6

No <CR> required before <LF>,<VT>,<FF> (LPll)

Bit 7

Ignore <CR> if next is <LF> (LPll)

Bit 8

No <TAB> expanded (LN01)

Bit 9

Reserved

Bit 10 Reserved
Bit 11 Allow lower case (LN01)
Note that a value of 3 (set both bits 0 and 1) is illegal. All
other combinations are permitted.
FIRQB+FQNAM1+2

Clear characteristics flag bits mask. Zero indicates no change.
A nonzero value represents the combination of flag bits to be
cleared. See the previous discussion for FIRQB+FQNAMI for
an explanation of the bit meanings.

FIRQB+FQEXT

Change special character flag. Zero indicates no change.
One indicates a change to the Lineprinter Special Character
(LPTSPC).

FIRQB+FQEXT+l

If FIRQB+FQEXT is equal to one, then this byte contains the
new Lineprinter Special Character.

FIRQB+FQDEV

The device name in two ASCII characters; must be LP.

FIRQB+ FQDEVN

The line printer unit number on which to perform the operation.

.UUO--UU.CFG

3-275

Data Returned (Set LPn: characteristics)

Except for a possible error in byte 0 of the FIRQB, the system returns the
following:
FIRQ8
Octal MneOffset monic

Mne- Octal
monic Offset

/ / / / // / / / / / / // / / / / / //

case flag

default page width

current characteristics flag word

/ / / / // / / / / / / // / / / / / //

FQPPN

10 FQNAM1
12

current special char.

//////////

14 FQEXT

//////////

current form length

16 FQSIZ

/ / / / / / / / / / / / / II / / / / / /

/ / / / // / / / / / / // / / / / / / /

/ / / / // / / / / / / // / / / / / //

/ / / / / / / / / / / / // / / / / / //

/ / / / // / / / / / / // / / / / / //

FIRQB+FQPPN

Current width of the LP unit specified in FIRQB+FQDEV and
FIRQB+FQDEVN.

FIRQB+FQPPN+l

Current value of the case flag.

FIRQB+FQNAMI

Current value of the characteristics flag word.

FIRQB+FQEXT+l

Current value of the special character.

FIRQB+FQSIZ

Current value of the default form length.

Errors (Set LPn: characteristics)

3-276

BDNERR

An attempt was made to set both bits 0 and 1 in the characteristics flag
word.

NODEVC

An attempt was made to set characteristics of a printer which is not supported by the monitor, or the device name specified in FIRQB+FQDEV was
not LP.

.UUO-UU.CFG

Data Passed (Set System Defaults)
FIRQB
Octal MneOffset monic

Mne- Octal
monic Offset

/I I I /I I I /I II I I I /I /I I I

FQFUN 3

UU.CFG (= 42)

111/111111

1111/11111

subfunction code =2

FQFIL

FQPPN

default date format

FQNAM1

default tape label

powerfail delay in seconds

default time forma!

1111/11111

default tape density

FQEXT

dynamic region limit

FQSIZ

/I I I /I I I II 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 I I I

/I I I I I I II I I I I I I /I I I I I

1/1/1/1/1/111111/1/11

/I I I /I I I /I II II I /I I I II

FQDEV

II I I /I /I /I II I /I /I I I I I

FQDEVN

/I I I I I I I /I I I I I I I II I I I

/I I I /I I I /I I I II I /I I II I

FIRQB+FQPPN

Default powerfail delay in seconds. Zero indicates no change.
A nonzero value represents the new default powerfail delay.
The maximum is 454 (octal) seconds.

FIRQB+FQNAM1

Default date format. Zero indicates no change. One indicates
NUMERIC date format. The ALPHA date format is indicated
by 377.

FIRQB+FQNAM1+1

Default time format. Zero indicates no change. One indicates
24 hour time format. The 12 hour (AMlPM) time format is
indicated by 377.

FIRQB+FQNAMl+2

Default magnetic tape label. Zero indicates no change. One
indicates DOS magnetic tape label. The ANSI magnetic tape
label is indicated by 377.

FIRQB+FQEXT

Default magnetic tape density in bits per inch (bpi).

FIRQB+FQSIZ

Nonprivileged user dynamic region limit. Zero indicates no
change, minus one (-1) sets the limit to 0 K words. A value
between 1 and 2048 sets the limit to that value in K words.
The sum of the dynamic region sizes owned by all nonprivileged users cannot exceed the limit value given here. If a user
without INSTAL privilege attempts to create a region whose
size, when added to all other nonprivleged region sizes, exceeds
thi.s limit, the system returns a NOROOM error message and
does not create the region.

.UUO-UU.CFG

3-271

Data Returned (Set System Defaults)
FIROB
Octal MneOffset monic

Mne- Octal
monic Offset
I I I I II I I I I I I II I I I I I II

111111111111111111111

I I I I II I I I I I I II I I I I I II

seconds to delay on powerfail restarts

default time format

1/11111111

6 FOPPN

default date format

10 FONAM1

default tape label

default tape density

14 FOEXT

dynamic region limit

16 FOSIZ

I I I I II I I I I I I II I I I I I II

111111111111111111/11

I I I I II I I I I I I II I I I I I II

FIRQB+FQPPN

The number of seconds to delay of powerfail restarts.

FIRQB+FQNAMI

Default date format. One indicates NUMERIC date format.
The ALPHA date format is indicated by 377.

FIRQB+FQNAM1+l

Default time format. One indicates 24 hour time format. The
12 hour (AMlPM) time format is indicated by 377.

FIRQB+FQNAM1+2

Default magnetic tape label. One indicates DOS magnetic tape
label. The ANSI magnetic tape label is indicated by 377.

FIRQB+FQEXT

Default magnetic tape density in bits per inch (bpi).

FIRQB+FQSIZ

Default region limit in K words.

Errors (Set System Defaults)
FIXERR

3-278 .UUO-UU.CFG

An attempt was made to specify a powerfail delay value greater than 454
(octal) seconds.

Data Passed (Load and Remove Monitor Overlay Code)
FIRQ8
Mne- Octal
monic Offset

Octal MneOffset monic
II I I I I I I II I I I I I II I I I I

FQFUN 3

UU.CFG (= 42)

////1////1

IUIIII//l

subfunction code =4

FQFIL

//11//1//1

0= load, 1 = unload

FQPPN

internal overlay name in RAD50 format

FQNAM1

II I I I I I I I I I I I I I II I I I I

II I I I I I I II I I I I I /I I / I /

/I I I I I I I II I I I I I II I I I I

II I I I I I I II I I I I I II I I I I

II I I I I I I II I / I I I II I I I I

II I I I I I I II I I I I I II I I I I

II I I I I I I II / I / I I II I I I I

II I I / / / I 1/ / / I / I 1/ / / / /

1/ I / I I I I II I / I / / II I I I I

II I I I I I I II I I I I I II I I I I

FIRQB+FQPPN

Operation flag. Zero indicates load the named overlay code. A one
indicates unload the named code.

FIRQB+FQNAMI

Internal overlay name in RAD50 format. These names are subject
to 'change in future releases of RSTSIE. Presently, the folloWing
names have been defined:
DIR Handles directory lookups
DLN Handles delete and rename
LIN Handles the UU.ATR SYS() call
PFB Handles several functions used by the DCL command file
processor
TRM Handles the set-terminal-characteristics (UU.TRM) SYS()
call.
UUO Handles UU.TBl, UU.TB2, UU.TB3, UU.FCB, UU.CNY,
UU.SYS, and UU.ERR
FUT Handles UU.FIL SYS( ) call

Data Returned (Load and Remove Monitor Overlay Code)

Except for a possible error in byte 0 of the FIRQB, for a load operation, the
system returns the amount of XBUF used (in bytes) in FIRQB+FQPPN. The
remove monitor overlay code operation does not return any data .

.UU~UU.CFG

3-279

Errors (Load and Remove Monitor Overlay Code)
lNUSE

The overlay code specified is already loaded. (Load)

NOBUFS

There is not enough XBUF available to load the named overlay code. (Load)

NODEVC

The named overlay code is not loadable. (Load)

NOSUCH

The overlay name is invalid. (either)

NOTMNT

The overlay name is not loaded. (Remove)

Data Passed (Set and Return System Answerback Message)
FIROB
Octal MneOffset monic

Mne- Octal
monic Offset

////11////1111111//11
FOFUN 3

UU.CFG (= 42)

111/1/1/11

FOSIZM5

Flag

subfunction code =7

FOFIL

FOPPN

Answerback

Message

Text

3-280

//1/11////111111/1/11

FIRQB+FQSIZM

Flag= -1 to return the Answerback text
Flag> 0 to set the Answerback text.

FIRQB+FQPPN

The ASCII string for the Answerback text.

.UUO--UU.CFG

Data Returned
FIRQB
Octal MneOffset monic

Mne- Octal
monic Offset

/ 1/ / / / / / 1/ / / / / / / 1/ / / /

/11//1/1/1

subfunction code =7

4 FQFIL

6 FQPPN

Answerback

Message

Text

FIRQB+FQPPN

/ 1/ / / / / / 1/ / / / / / / 1/ / / /

Answerback message text returned if Flag = -1.

Errors
PRVIOL

Current user does not have the SWCTL privilege.

NOTAVL

There is no Answerback text to return.

NOBUFS

There are no buffers available to store the text.

.UUO-UU.CFG

3-281

3.36.9

UU.CHE (Enable/Disable Disk Caching)
Privileges Required
TUNE is required to enable or disable disk caching.
Data Passed
FIRQ8
Octal MneOffset monic

Mne- Octal
monic Offset

11111/1111111/111111/
FQFUN 3

UU.CHE. (= 23)

1///1/1/1/

FQSIZM5

cache cluster size

subfunction code

FQFIL

limit on total number of cache clusters

FQPPN

limit on clusters for directory caching

FQNAM1

limit on clusters for user data caching

controls sm. buffers

I I I I 1/ I I I I I I 1/ I I I I I 1/

11111/11/1//1/111111/

111111111111111111111

1111111111111/111111/

I I I I 1/ I I I I I I 1/ I I I I I 1/

11111/1111111/1111111

FIRQB+FQFIL

o Enable directory and data caching
200

FIRQB+FQEXT

FIRQB+FQEXT+1

Disable all caching
Return current caching parameters

o Use current setting
1

Enable caching as specified in file open mode or UFD setting

100

Cache all data transfers regardless of the file open mode or
UFD setting

200

Disable all caching

o Use current setting
1
200

FIRQB+FQSIZ

FQEXT

The number of blocks used in a caching operation.
1

.UU~U.CHE

mode for enldisable

FIRQB+FQSIZM

3-282

Allow use of small buffer pool (ignored)
Do not use small buffer pool

The new value of the cache replacement time, in seconds. Specify
zero for no change.

Data Retu med
FIROB
Mne- Octal
monic Offset

Octal MneOffset monic

111111111111111111111

cache cluster size

FOSIZM5

Icurrent cache setting

FOFIL

limit on total number of cache clusters

FOPPN

limit on clusters for directory caching

FONAM1

limit on clusters for user data caching

controls sm. buffers

mode for enldisable

FOEXT

cache age

FOSIZ

monitor pool

FONAM2

XBUF pool

FOMODE

number of directory tags

FOFLAG

number of data tags

FOPFLG

number of invalid tags

FODEV

I I I I I 1/ /I 1/ /I 1/ /I I 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/ /I 1/ I /I I /I

FIRQB+FQFIL

Current cache settings and available options:
o All caching disabled.
1

Directory caching enabled, data caching is disabled.

200

Directory caching disabled, data caching is enabled.

201

Directory caching enabled, data caching is enabled.

FIRQB+FQSIZ

The time in seconds that an unused cache can be kept in memory.

FIRQB+FQNAM2

The amount of small buffers used for caching (in units of cache
clusters). Always zero.

FIRQB+FQMODE

The amount ofXBUF used for caching (in units of cache clusters).

FIRQB+FQFLAG

The number of cache clusters in XBUF used for directory caching.

FIRQB+FQPFLG

The number of cache clusters in XBUF used for data caching.

FIRQB+FQDEV

The number of invalid cache clusters in XBUF.

Errors
lNUSE

All of the clusters allot.ted to the cache are in use.

NOROOM

Not enough XBUF space t.o enable data caching. System manager must
allocat.e at least. 3K words.

NOTAVL

Tried t.o change cluster size while cached file disk t.ransfer in progress; retry.

PRVIOL

Current user does not have TUNE privilege.

.UUO-UU.CHE

3-283

3.36.10

UU.CHK (Check File Access/Privilege Name/Privilege Mask Handling)
The UU.CHK directive performs a variety of privilege checking functions. It
takes a subfunction code in FQFIL. The subfunction codes are:

Check file access rights. You can use this subfunction to check access rights to a
file of known protection code and PPN without performing the OPEN function. If
a file's access rights need to be checked but the protection code is not known, the
most straightforward method is to open the file. You can also use this subfunction to
define file-like access rules for objects other than files. For example, the PrintlBatch
Services programs use this subfunction to control access to jobs.

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. It scans the specified privilege mask looking for
a bit that is set. If none are found, the error NOSUCH is returned. Otherwise, the
first one found is cleared and the privilege name is returned in FIRQB+FQNAM2.

Privileges Required

None
Data Passed - Check File Access Rights
FIROB
Mne- Octal
monic Offset

Octal
Offset
////1////////1/1///1/

FOFUN 3

UU.CHK (= 40)

1/1/1/1/1/

1/1//1/1//

subfunction code=O

FOFIL

project number

programmer number

FOPPN

////1///////1//1//1//

1//1/1///1///1/1///1/

/1/1//1/////1//1//1//

/ / / / 1/ / / / / / / 1/ / / / / / 1/

////1////////1/1///1/

/1//1///1///1/1/1//1/

////1/1/////1/1////1/

FOPROT 27

3-284

Mnemonic

.UUO-UU.CHK

protection code

1/1/1//1//

/ / / / 1/ / / / / / / 1/ / / / / / 1/

////1///////1//////1/

/ / / / 1/ / / / / / / 1/ / / / / / 1/

////1///////1//////1/

Data Returned· Check File Access Rights
FIROB
Octal MneOffset monic

Mne- Octal
monic Offset
1/ I I I I I 1/ I I I I I 1/ I I I I I

I I I I I I I 1/ I I I I I 1/ I I I I I

access flags

I I I I I I I 1/ I I I I 1/ 1/ I I I I

I I I I I I I 1/ 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 I I I I I

I I I I I I I /I I I I I I /I I I I 1/

I I I I I I I 1/ I I I I I 1/ I I I I I

I I I I I I I 1/ I I I 1/ 1/ I I I I I

1/111111/1111/1/11111

/I I I I I I 1/ I I I I I 1/ I I I I I

I I I I I I I 1/ I I I I I /I I I I I I

I I I I I I I 1/ I I I I I 1/ I I I I I

I I I I I I I 1/ I I I I I /I I I I I I

I I I I I I I 1/ I I I I I 1/ I I I I I

FIRQB+FQERNO

4 FOERNO

The bits are set to indicate access rights as follows:
Bit 0
Owner rights are granted
Bit 1

Read access is not allowed

Bit 2

Write access is not allowed

Bit 5

Execute access is not allowed

Bit 6

Accounting rights are granted or the PPN is the same
as that of the caller.

Bit 7

Accounting rights are granted

Bits 3, 4, and 8 to 15 are reserved for use by Digital.

Errors
No errors are possible with this subfunction of UU.CHK.

.UUO-UU.CHK 3-285

Data Passed - COllvert Privilege Name to Mask
FIRQ8
Mne- Octal
monic Offset

Octal MneOffset monic
/ / / / / / / / / / / / / / / / / / 1/ /

3-286

FQFUN 3

UU.CHK (= 40)

//////////

///11/////

subfunction code =1

.UUO-UU.CHK

II /I / / / / II / / / / / / 1/ /I /

privilege name as a 6-character

uppercase ASCII string or "ALL"

padded with NULLs

/ / / / / / / / / / / / / / / II / / / /

II / /I / / / II / /I / / II / / / /

II / / / / / / II / / / / / II / / 1/

II / / / / / / II / / / / / II / 1/ /

II / II / / / II / / / / / II / / / /

II / / / / / / II / / / / / II / / / /

II / / / / / / II / 1/ / / II / / / /

II / / / / / / II / / / / / II / / / /

FQFIL

FQNAM1

Data Returned· Convert Privilege Name to Mask
FIRQB
Mne- Octal
monic Offset

3
5

Octal MneOffset monic
/ / / / / / / II / / / II /I / / / / /

/ / / / / / / II / / / / / II / / / / /

1111/1/1/1

error flag

/ / / / / / / /I / / / / / /I / / / / /

4 FQERNO
6
10 FQNAM1

privilege mask

12
(4 words)

/ / / / / / / /I / / / / / II / / / / /

/ / / / / / / II / / / / / /I / / / / /

/ / / / / / / /I / / / / / II / / / / /

/ / / / / / / II / / / / / / / / / / / /

/ / / / / / / /I / / / / / II / / / / /

/ / / / / / / II / / / / / 1/ / / / / /

/ / / / / / / /I / / / / / /I / / / / /

FIRQB+FQERNO

If the passed privilege name was not ALL:
Zero means the current job has the named privilege.
One means the current job does not.
If ALL was passed:
Zero means the current job has all privileges.
One means the current job does not.

FIRQB+FQNAMI

If the passed privilege name was not ALL, the bit corresponding
to the named privilege is set. All other bits are clear.
If ALL was passed, all privilege bits that currently have meaning
are set. All other bits are clear.

Errors
NOSUCH

The name passed in FIRQB+FQNAMI is not a valid privilege name.

.UUO-UU.CHK 3-287

Data Passed - Convert Privilege Mask to Name
FIROB
Octal MneOffset monic

Mne- Octal
monic Offset
II / / / / / / II / / / / / II / / / /
FOFUN 3

UU.CHK (= 40)

/111/1/1/1

//11111/1/

subfunction code =2

II / / / / / / II / / / / / II / / / /

privilege mask

(4 words)

.UUO-UU.CHK

FOFIL

6
10

3-288

II / / / / / / II / / / / / II / / / /

FONAM1

Data Returned· Convert Privilege Mask to Name
FIRQ8
Octal MneOffset monic

Mne- Octal
monic Offset
I I I I 1/ I I I I I I 1/ I I I I I 1/

I I I I 1/ I I I I I I 1/ I I I I I 1/

11111/1111111/111111/

6
10 FQNAM1

11
13

privilege mask

(4 words)

14
16

20 FQNAM2

21
6-character uppercase ASCII string

23
padded with NULLs

I I I I 1/ I I I I I I 1/ I I I I I 1/

FIRQB+FQNAMI

The privilege mask is the same as that passed except that any
undefined bits and the bit corresponding to the name in FQNAM2
is turned off. As a result, a subsequent call using the returned
mask would return the name of the next privilege. This makes it
easy to translate an entire mask by repeated calls to this function.

FIRQB+FQNAM2

The name of the privilege corresponding to the first set bit in the
mask.

Errors

NOSUCH

The privilege mask in FIRQB+FQNAMI is zero or specifies only unassigned
privilege bits.

.UUO-UU.CHK

3-289

3.36.11

UU.CHU (Set Password, Change Password/Quota/Expiration Date,
Disable Terminal,KiII Job)
This directive has five subfunct.ions:
•

Set Long Password

•

Change Quotas (updated format), Expiration Date, and Short Password

•

Change Quotas (pre-V9.0 format), Expiration Date, and Short Password

•

Disable Terminal

•

Kill Job

Privileges Required (Set Long Password)

GACNT or WACNT are required to set passwords.
Data Passed (Set Long Password)
FIRQB
Mne- Octal
monic Offset

Octal MneOffset monic
1/ I I I I I I 1/ I I I I I 1/ I I I I

FQFUN 3

UU.CHU (=10)

1/1/1/1/1/

FQFIL

project number

programmer number

FQPPN

FQNAM1

long password

(14 bytes, padded with NULLs)

1/ I I I I I I 1/ I I I I I 1/ I I I I

FIRQB+FQNAMl

3-290

.UUO-UU.CHU

(must be 0)

(must be 377)

1/ I I I I I I 1/ I I I I I 1/ I I I I

FQCLUS

If the first byte is zero, the password information is deleted (this
turns the account into a nonuser account). If password lookup
is enabled using CREATE/ACCOUNT or SET PASSWORD then
the password must consist of six uppercase letters or numbers.
Otherwise, it can contain any character except the question mark
(?). The monitor also enforces a minimum password length of six
characters.

NOTE

In this subfunction, the PPN is specified in a different place than in
the "Change Short Password/Quota" subfunctions where the PPN is
specified in FQNAMl.
Privileges Required (Change Short Password, Quotas V9.0 & Higher, or
Expiration Date)

GACNT or WACNT are required to set passwords, quotas, or expiration date.
Data Passed (Change Short Password, Quotas for V9.0 & Higher, or Expiration
Date)
FIRQB
Mne- Octal
monic Offset

Octal MneOffset monic
/ / / / / / II / / / / / / II / / / / /

FQFUN 3

UU.CHU (=10)
flag byte

11/111111/

detached job quota

/ / / / / / II / / / / / / II / / / / /

project number

11
13

programmer number

FQFIL

6
10

FQNAM1

new password in RAD50 format
(2 words)
(zero if no change)

logged-out quota (LSB)

FQSIZ

account expiration date

FQBUFL

logged-in quota (LSB)

FQMODE

logged-out quota(MSB)

logged-in quota(MSB)

FQFLAG

11/111111/

=377 to change quota

FQPFLG

FQDEV

FQDEVN
FQCLUS

device name (2 ASCII characters)

31
33

<>0, unit number real

device unit number

(must be zero)

/ / / / / / II / / / / / / II / / / / /

FIRQB+FQFIL

The number of detached jobs allowed under this account.

FIRQB+FQFIL+l

Flag byte. Zero means change the disk quotas using the pre-V9.0
format (see the next subfunction). Nonzero means the following:
Bit 0 Change logged-out quota
Bit 1 Change logged-in quota
Bit 2 Reserved
Bit 3 Change detached job quota
Bit 4 Reserved

FIRQB+FQSIZ

Bit 5

Reserved

Bit 6
Bit 7

Reserved
Change disk quotas using updated format

The LSB of the logged-out quota.

.UUO--UU.CHU

3-291

FIRQB+FQBUFL

Zero means no change. Nonzero means this value is the new
expiration date.

FIRQB+FQMODE

The LSB ofthe logged-in quota.

FIRQB+FQFLAG

The MSB of the logged-in quota.

FIRQB+FQFLAG+l

The MSB of the logged-out quota.

FIRQB+FQPFLG

To change disk quota, set this byte to 377.

FIRQB+FQDEV

The device name as two ASCII characters.

FIRQB+FQDEVN

The device unit number, passed as a binary value in byte
FIRQB+FQDEVN. A nonzero value in FIRQB+FQDEVN+l
indicates an explicit device unit number. A zero value in
FIRQB+FQDEVN+l indicates no device unit number.

Privileges Required (Change Short Password, Pre-V9.0 Quotas or Expiration
Date)

GACNT or WACNT are required to set passwords, quotas, or expiration date.
Data Passed (Change Short Password, Pre-V9.0 Quotas or Expiration Date)
FIROB
Mne- Octal
monic Offset

Octal MneOffset monic

/I I I I I I I /I I I I I I /I I I I I
11/1/1/1/1/

/I I I I I I I /I I I I I I I I I I I I

FOFUN 3

UU.CHU (=10)

project number

programmer number

FONAM1

new password in RAD50 format
(2 words)
(zero if no change)

number of blocks for quota; 0 = unlimited

FOSIZ

account expiration date

FOBUFL

/I I I I I I I /I I I I I I /I I I I I

FOPFLG

device name (2 ASCII characters)

FODEV

FODEVN
FOCLUS

1111111111

31
33

3-292

<>0, unit number real

=377 to change quota

device unit number

(must be zero)

/I I I I I I I /I I I I I I I I I I I I

FIRQB+FQBUFL

Zero means no change. Nonzero means this value is the new
expiration date.

FIRQB+FQPFLG

To change disk quota, set this byte to 377.

FIRQB+FQDEV

The device name as two ASCII characters.

.UUO--UU.CHU

FIRQB+FQDEVN

Privileges Required (Disable Terminal)

HWCTL is required to disable a terminal.
Data Passed (Disable Terminal)
FIR08
Octal MneOffset monic

Mne- Octal
monic Offset

/I I I I I I /I I I I I I /I I I I I I
FOFUN 3

UU.CHU (=10)

II/IIIII!I

/II! II I! I!

keyboard number

/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! 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! / / / / / /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 /I I I I I I

I! I I I I I I! I I I I I /I I I I I I

35
37

(must = 377)

I I I I I I I /I I I I I / /I I I I I I

FOFIL

FOCLUS

Privileges Required (Kill Job)

JOBCTL is required to kill a job.

.UUO-UU.CHU

3-293

Data Passed (Kill Job)
FIR08
Octal MneOffset monic

Mne- Octal
monic Offset

111111111111111111111

FOFUN 3

UU .CHU (= 10)

1111111111

job number to kill

111111111111111111111

II I II II I II I II I II I II I I

II I I I I I /I I I I I I I I I I I I I

111111111111111111111

II I I I II II II I I I /I /I I II

I I I I I I I I I I I I I I II I I I I I

II II I I I /I I II I I III I II I

/11111111111111111111

111111111111111111111

/I I I II I /I II I I I II II II I

I I I I I I I I I I I I I I /I I I I I I

(must = 377)

(must be zero)

I I I I I I I I I I I I I I II I I I I I

FIRQB+FQFIL

FOFIL

FOCLUS

Specify zero to kill current job.

Data Returned

Except for a possible error in byte 0 of the FIRQB, the UU.CHU subfunction does
not return any meaningful data.

Errors
BADFUO

The system returns this error for one of the following:
.,
..
It

3-294

Change password/quota. Device specified is not a disk.
Kill job. Job number is out of range or the job does not exist.
Disable tenninal. The keyboard number is:
Greater than number of keyboards on system
A pseudo keyboard
Currently opened or allocated by a job

BADNAM

For change password/quota. Password is too short, or too long, or contains
illegal characters.

NOSUCH

For change password/quota. Account not present on disk specified.

NODEVC

For change password/quota. Device specified is not on the system.

.UUO-UU.CHU

3.36.12

UU.CNV (Date and Time Conversion)
Privileges Required
None
Data Passed
FIRQB
Mne- Octal
monic Offset

Octal MneOffset monic

I II I I I I I I II I I I I I II I I I

UU.CNV (= 24)

FQFUN 3

1111111111

internal form date (see .DATE);O = current

FQFIL

date flag

FQPPN

I I I I I I I I I II I I I I I II I I I

I I I I I I I I I II I I I I I I I I I I

III II II IIIIIIIIIIIIII

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

internal form time (see .DATE);O = current

FQMODE

time flag

FQFLAG

III I IIII IIIIIIIIIIIII

IIIIIIIIIIIIIIIIIIIII

I I I I I I I I I I I I I I I I I I III

I II I I I I I I I I I I I I I I I I I I

IIIIIIIIIIIIIIIIIIIII

FIRQB+FQFIL

The date to be converted, or zero for the current date.

FIRQB+FQPPN

Zero means use system default format. A value less than zero
means use alphabetic date format. A value greater than zero
means use ISO numeric date format.

FIRQB+FQMODE

The time to be converted, or zero for the current time.

FIRQB+FQFLAG

Zero means use system default format. A value less than zero
means use 12-hour time format. A value greater than zero means
use 24-hour time format.

.UUO-UU.CNV

3-295

Data Returned
FIROB
Octal MneOffset monic

Mne- Octal
monic Offset

/ 1/ / / / / / / 1/ / / / / / 1/ / / /

FOJOB

/1/11//1/1

job number· 2

(same as data passed)

FOFIL

(same as data passed)

FOPPN

10 FONAM1

11
13

date string (padded

at end with NULLs)

dd-mmm-yy or yy.mm.dd

16
20

21
23

(same as data passed)

22 FOMODE

(same as data passed)

FOFLAG

FOPFLG

27
time string (padded

31
at end with NULLs)

32
hh:mm xm or hh:mm
34

35
37

/ 1/ / / / / / / 1/ / / / / / 1/ / / /

Errors
No errors are possible; however, if the date or time passed is illegal, random
output is generated.

3-296

.UUO-UU.CNV

3.36.13

UU.DAL (Deallocate All Devices and Deassign All User Logicals)
Privileges Required

None
Data Passed
FIR08
Octal
Offset

Mne- Octal
monic Offset

FOFUN 3

/ /I / / / / / / /I / / / / / /I / / /

UU.DAL (= 14)

1/1/1/1/1/

must be 0

/ /I / / / / / / /I / / / / / /I / / /

/1///////1//////1////

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

Mnemonic

FOFIL

FIRQB+FQFUN

The function code UU.DAL (octal value equals 14)

FIRQB+FQFIL

The deassign-only flag. Must be zero.

Data Returned

The UU.DAL subfunction does not return any data.
Errors

No errors are possible with the UU.DAL subfunction.

.UUO-UU.DAL 3-297

3.36.14

UU.DAT (Change System Date/Time)
Privileges Required
DATES is required to change system date or time.

Data Passed
FIRQB
Mne- Octal
monic Offset

FQFUN 3

Octal MneOffset monic
/I I I I I I I /I I I I I I /I I I I I

UU.DAT (= -16)

/1/1/1/1/1

new current date

FQFIL

new current time

FQPPN

/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 /I I I I I I 1/ I I I I

1/ I I I I I I 1/ I I I I I 1/ I I I I

1/ 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 I I I I I /I I I I I

/I I I I I I I 1/ I I I I I /I I I I I

/I I I I I I I 1/ I I I I I 1/ I I I I

/I I I I I I I /I I I I I I /I I I I I

FIRQB+FQFIL

The system internal fonnat for date is:
[(year - 1970) * 1000] + day-within-year

FIRQB+FQPPN

Time is expressed as minutes until midnight, where 1440 equals
midnight.

NOTE

A value of zero in either of these fields means no change is to be made.
See the .DATE directive for a discussion of these formats.

Data Returned
The UU.DAT subfunction does not return any data.

Errors
PRVIOL

3-298

.UUO-UU.DAT

Dates prior to 1-Jan-90 cannot be set.

3.36.15

UU.DEA (Deallocate Device)
Privileges Required
None

Data Passed
FIROB
Mne- Octal
monic Offset

Octal MneOffset monic

1/ / / / / / / 1/ / / / / / 1/ / / / /

UU.DEA (= 13)

FOFUN 3

//1/1///1/

1/ / / / / / / 1/ / / / / / 1/ / / / /

1///////1//////1///1/

/I / / / / / / /I / / / / / 1/ / / / /

/I / / / / / / /I / / / / / /I / / / /

/1///////1//////1////

1///1///1//////1/////

1/ / / / / / / 1/ / / / / / 1/ / / / /

1/ / / / / / / /I / / / / / /I / / / /

1/ / / / / / / 1/ / / / / / 1/ / / / /

/I / / / / / / /I / / / / / /I / / / /

device name (2 ASCII characters) or 0

FODEV

FODEVN

<>0, unit number real

device unit number

1////1///1/1///1/////

1///////1//////1/////

Data Returned
Except for a possible error in byte 0 of the FIRQB, the UU.DEA subfunction does
not return any meaningful data.

Errors
NODEVC

The device or device type in the two words at FIRQB+FQDEV is not on
the system.

.UUO--UU.DEA 3-299

3.36.16

UU.DET (Detach)
Privileges Required

None required to detach the caller's job (depending on quotas). JOBCTL is
required to detach another job. EXQTA is required to suppress the detached job
quota check.
Data Passed
FIROB
Octal
Offset

Mne- Octal
monic Offset
IIIIIIIIIIIIIIIIIIIII

FOFUN 3

UU.DET (~ 7)

1111111111

close flag & job no.

I I I I I I I I I II I I I I I II I I I

I I I I I I I I I I I I I I I I II I I I

IIII II 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 I I I I I I 1/ I I I

I I I I I I I I I I I I I I I I II I I I

I 1/ I I I I I I I I I I I I I II I I I

IIII 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 I I I I I I I I II I I I

IIII I I I I I I I I I I I I I I I I I

IIII IIIIIIIIIII IIIIII

111111111111111111111

I I I I I I I I I I I I I I I I /I I I I

/1/1/1/1/1111111/1111

FIRQB+FQFIL

Mnemonic

FOFIL

Flag byte as follows: Bits 0-6 equals the job number to detach. If
zero, detach calling job. Bit 7 clear means do not close terminal
channels or deallocate terminal. Bit 7 set means close all channels
on which terminal is open and deallocate terminal, if allocated.

NOTE

If a job running under control of an indirect command file is detached
using the UU.DET directive, 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 detached job retains its job number,
while the command file resumes under a different job number.
Data Returned

Except for a possible error in byte 0 of the FIRQB, the UU.DET subfunction does
not return any meaningful data.

3-300

.UUO-UU.DET

Errors
BADFUO

The current job is already detached.

QUOTA

The detached job quota for the account has been reached.

.UUO-UU.DET

3-301

3.36.17

UU.DIE (System Shutdown)
Privileges Required

SHUTUP privilege is required to shut down the system.
Data Passed
FIRQ8
Mne- Octal
monic Offset

Octal
Offset
11/111/111/111111/111

UU.DIE (= -20)

FQFUN 3

1/11111111

Flag word

I 1/ I I I I I I 1/ I I I I I 1/ I I I

I 1/ I I I I I I II I I I I I 1/ I I I

I 1/ I I I I I I 1/ I I I I I 1/ I I I

I 1/ I I I I I I /I I I I I I 1/ I I I

I 1/ I I I I I I 1/ I I I I I 1/ I I I

I 1/ I I I I I I 1/ I I I I I /I I I I

I /I I I I I I I 1/ I I I I I /I I I I

I /I I I I I I I /I I I I I I 1/ I I I

I 1/ I I I I I I 1/ I I I I I /I I I I

I 1/ I I I I I I II I I I I I /I I I I

FIRQB+FQPPN

Mnemonic

FQFIL

Flag word 0 means no automatic restart (stop in INIT.SYS).
Flag word = 1 means automatic restart.

Data Returned

Except for a possible error in byte 0 of the FIRQB, the UU.DIE subfunction does
not return any meaningful data.
Errors
BADFUO

One of these conditions has not been met:
•
•
•
•

3-302

.UUO-UU.DIE

Only one job can be running
Logins must be disabled
No disks except the system disk can be mounted
N~ files can be open on the system disk

3.36.18

UU.DIR (Directory lookup)
Privileges Required
If the device is restricted, DEVICE privilege is required to perform directory or
disk lookup on the caner's account. File read or execute access (by protection
code, GACNT or WACNT privileges) is required to perform disk directory lookup
on another account.

Data Passed -

Directory Lookup on Index
FIROB

Mne- Octal
monic Offset

Octal MneOffset monic
I 1/ I I I I I I I I I I I I I I I I I I

UU.DIR (= 17)

FOFUN 3

1/1/1/1/1/

index of file to read

project number

programmer number

4 FOFIL
6

/1//11/111/111/1/1/1/

1/ I /I I I I I 1/ 1/ / /I 1/ I I I

/I /I I! I I I I! I I I I I 1/ I I I

/ 1/ I! I I I! 1/ / I! I I 1/ I I!

1/ 1/ I I I! I 1/ I I I I 1/ I I I!

marked-for-delete flag

I! I! I! / I I I! I! I! /I I I I I

I 1/ 1/ /I I I I! I I I I 1/ 1/ I I

device name (2 ASCII characters)

<>0, unit number real

device unit number

22 FOMODE

FODEV

32 FODEVN

1/ 1/ I I! I 1/ I /I / I /I 1/ I I

I! I! 1/ / 1/ 1/ I I I I I! / I! I

FIRQB+FQFIL

FOPPN

The index for the file to read. If the index is zero, UU.DIR returns
the data for the first file in the directory. Ifthe index is n, UU.DIR
returns the the data for the n+lth file in the directory.
On magnetic tape, the index must be zero to rewind the tape
before reading the first file. On DECtape, the index must be
zero to read the directory blocks from the tape before reading the
first file. Subsequent calls, where the index is not zero, read the
directory from the BUFF.SYS file.

FIRQB+FQPPN

Specifies the PPN to look up. For disks, the PPN defaults to
the caller's PPN. For DOS format magnetic tape; a zero in
FIRQB+FQPPN means look up files regardless of PPN, a nonzero
means only files with that PPN are returned. For ANSI magnetic
tape and DECtape, RSTSIE ignores FIRQB+FQPPN.

FIRQB+FQMODE

Marked-for-delete flag. Bit 14 set causes UU.DIR to return information about marked-for-delete files.

.UUO-UU.DIR

3-303

Data Returned -

Directory Lookup on Index
FIRQB
Octal MneOffset monic

Mne- Octal
monic Offset
I /I I I I I I I /I I I I I I /I I I I

FQJOB

FQFll

11111/1111

current job no .• 2

(same as data passed)

project number

programmer number

file name in RAD50 format
(2 words)

6 FQPPN
10 FQNAM1
12

13
15

file type in RAD50 format (1 word)

14 FQEXT

lSB of file size

16 FQSIZ

MSB of file size

protection code

FQNAM2

date of last access

22 FQMODE

date of creation

24 FQFLAG

time of creation

26 FQPFlG

(same as data passed)

32 FQDEVN

file cluster size

USTAT byte

no. entries returned

FQDEV

FQClUS

36 FQNENT

FIRQB+FQMODE
FIRQB+FQFLAG

System internal format for date is:
[(year - 1970) * 1000] + day-within-year

FIRQB+FQPFLG

Time is returned as minutes before midnight, where 1440 equals
midnight. For look up on DOS format magnetic tape, this field
contains the PPN of the file.

NOTE

See the .DATE directive for a discussion of the date and time formats.
FIRQB+FQNENT+1

3-304 .UUO-UU.DIR

The USTAT byte from the UFD Name entry. This byte contains
the following internal flag information (for disk only):
Bit Meaning When Set
1

File is placed

Some job has write access now

File is open in update mode

File is contiguous; no extend allowed

No delete or rename allowed

File is marked for deletion

Errors
BADDIR

The directory structure is invalid. For magnetic tape, this error usually
indicates you are reading an ANSI format tape in DOS mode, or a DOS
format tape in ANSI mode.

DEVNFS

The device specified is non-file-structured.

NOSUCH

The account specified does not exist on the device or no more files exist on
the account.

xxxxxx

The call also returns device-dependent errors such as NOTMNT (disk pack
not mounted).

Data Passed - Special Magnetic Tape Directory Lookup
FIROB
Octal MneOffset monic

Mne- Octal
monic Offset

FOFUN 3

I II I I II I I I I I I II I I I I I I

UU.DIR (= 17)

1111111111

index of file to read

FOFIL

(= 177777 for magnetic tape lookup)

FOPPN

II I I I II I I I I I I /I I I I I I I

I I I I I II I I I I I I II I I I I I I

I I I I II I I I I I I I II I I I I I I

111111111111111111111

device name (2 ASCII characters)

FODEV

FOOEVN

<>0, unit number real

device unit number

111111111111111111111

.UUO-UU.DIR 3-305

Data Returned -

Special Magnetic Tape Directory Lookup
FIROB

Mne- Octal
monic Offset

Octal
Offset

Mnemonic

/ I /I / I / / I / /I / I I I I /I / /

FOJOB

11/1111/11

current job no .• 2

(same as data passed)

FOFIL

(same as data passed)

FOPPN

file name in RAD50 format
(2 words)

FONAM1

file type in RAD50 format (1 word)

/ / /I / / I / I / /I / I / I I /I / I

FONAM2

FOMODE

//1//11111

date of creation

23
25
FOP ROT 27

protection code

FOEXT

I / II / / I / / / 1/ I / I I / /I / I

FOPFLG

project number

programmer number

(same as data passed)

FODEV

(same as data passed)

FODEVN

I I /I I I / I / / /I / I I I I /I / I

1111//1/1/

FIRQB+FQMODE

no. entries returned

FONENT

System internal format for date is:
[(year - 1970) * 1000J + day-within-year

FIRQB+FQNENT

The number of entries returned: for disk, eight; for tape, six. (Not
returned for SYS 17.)

Errors
BADDIR

3-306

This error usually indicates you are reading an ANSI format tape in DOS
mode, or a DOS format tape in ANSI mode.

NOSUCH

No more files exist on the tape.

DEVNFS

The device specified in the two words at FIRQB+FQDEVN is either non-filestructured or not a magnetic tape.

.UUO-UU.DIR

3.36.19

UU.DLU (Delete User Account)
Privileges Required

GACNT or WACNT is required to delete a user account.
Data Passed
FIR08
Mne- Octal
monic Offset

Octal MneOffset monic
/1111111/111111/111//

UU.DLU (= 1)

FOFUN 3

///1//////

/I I I I I I I /I I I I I I /I I I I I

/1111111/111111/1//11

project number

programmer number

FONAM1

/I I I I I I I /I I I I I I /I I I I I

/1111111/111111/11111

/I I I I I I I /I I I I I I /I I I I I

/1111111/111111/111//

/11111111///111/111/1

device name (2 ASCII characters)

FODEV

FODEVN

<>0, unit number real

device unit number

/11111111/11111/111//

/11111111/11111/11111

Data Returned

Except for a possible error in byte 0 of the FIRQB, the UU.DLU subfunction does
not return any meaningful data.
Errors

DEVNFS

Device is not disk or is a disk open in non-file-structured mode.

FIEXST

The account contains files.

lNUSE
NOSUCH

A user is currently logged in to the system under the account.

PRVIOL

Account specified is either [0,0] or [0,1].

The specified account does not exist.

Discussion

U.DLU 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 UU.ZER or the DCL DELETE
command.

.UUO-UU.DLU 3-307

3.36.20

UU.DMP (Snap Shot Dump)
Privileges Required

SYSIO is required to perform a snap shot dmnp.
Data Passed
FIRQB
Octal
Offset

Mne- Octal
monic Offset

FQFUN 3

////1//////1/////////

UU.DMP (= -33)

//////////

/ / / / 1/ / / / / / // / / / / / / 1/

/ / / / 1/ / / / / / 1/ / / / / / / 1/

/ / / / 1/ / / / / / 1/ / / / / / / / /

/ / / / 1/ / / / / / 1/ / / / / / / 1/

/ / / / 1/ / / / / / 1/ / / / / / / / /

/ / / / 1/ / / / / / 1/ / / / / / / II

/ / / / 1/ / / / / / 1/ / / / / / / 1/

////1//////1///////1/

/ / / / /I / / / / / /I / / / / / / 1/

/////1/////////////1/

/ / / / // / / / / / / / / / / / / / 1/

Mnemonic

Data Returned

Except for a possible error in byte 0 of the FIRQB, the UU.DMP subfunction of
.UUO does not return any' meaningful data.
Errors
BADFUO

A user without SYSIO privilege attempted to execute this call.

NOSUCH

The call tried to write data to the file CRASH.8YS, but crash dump was
not enabled. This error occurs if RSTSIE tries to allocate a crash dump file
during system start-up but could not due to lack of disk space.

xxxxxx

The call also returns device-dependent errors such as HNGDEV or
NOTMNT.

Discussion

UU.DMP writes the current monitor image executing in memory and the contents
of the extended buffer pool (XBUF) to the crash dmnp file [O,l]CRASH.SYS.
XBUF contains monitor data structures, including DECnetIE 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).
3-308

.UUO-UU.DMP

3.36.21

UU.ERR (Return Error Messages)
Privileges Required

None
Data Passed
FIR08
Octal MneOffset monic

Mne- Octal
monic Offset

/ /I / / / / / /I / / / / / / /I / / /

FOFUN 3

UU.ERR (=11)

//1/1/1/1/

error number

4 FOERNO

/ /I / / / / / /I / / / / / / /I / / /

//1//////1///////1/1/

/ /I / / / / / /I / / / / / / /I / / /

//1//////1////1//1///

//1//////1///////1///

/ /I / / / / / /I / / / / / / /I / / /

/ / / / / / / / / / / / / /l / / / / / /

////1////////////////

.UUO-UU.ERR

3-309

Data Returned
FIRQS
Mnemonic

Octal
Offset

Octal MneOffset monic
///1/////////////////

FQJOS

FQERNO

FQFUN 3

KS*2;1 's comp=detach

current job no. * 2

error message - padded with NULLs

to 28. characters (ASCII format)

Errors
No errors are possible with the UU.ERR subfunction.

Discussion
UU.ERR 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 at FIRQB+FQERNO (usually FIRQB+FQFIL). The
number in FIRQB+FQFUN of the returned string is two times the number of the
keyboard on which the job is running.

3-310

.UUO-UU.ERR

3.36.22

UU.FCB (Get Open Channel Statistics: WCB/DDB/FCB)
The WCB is the Window Control Block for the file system. The DDB is the Device
Data Block for nondisk devices. The FCB is the File Control Block for the file
system. Note that the WCB, DDB, and FCB are internal RSTSIE structures that
are subject to change at any time.
Privileges Required

None
Data Passed
FIRQB
Mne- Octal
monic Offset

Octal
Offset

II / / / / / / II / / / / / II / / / /
FQFUN 3
FQSIZM5

UU.FCB (= -10)
subcode = 0 or 1

1111111111

WCB,DDB,or FCB ch.no.

II / / / / / / II / / / / / II / / / /

II / I I / / / II / I / / I II / I I I

II / / / / / / II / / / / / II / / / /

II / / / / / I II I I / / / II I / / /

II / / / / / / II I / / / / II / / / /

/I / / / / / / II / / / / / II I / / /

II I I I I I / II / / / / / II / / / /

II / / / / / / II / / / / / II / / / /

II / I / / / / II / / / / / II / / / /

II I I I I I I II I I I I I /I I I / /

II / / / / I / /I / / / / / II / / / /

II / / / / / / II / / / / / II / / / /

FIRQB+FQSIZM

Mnemonic

FQFIL

Zero returns WCB or DDB infonnation. One returns FCB information.

.UUO-UU.FCB 3-311

Data Returned (for subcode

=0)

For DDB or WeB.
FIROB
Mne- Octal
monic Offset

3-312

.UU~UU.FCB

Octal MneOffset monic
1//////////////1//1//

FOJOB

//1//////1

curren! job no. * 2

word 1 of either the WCB or DDB

FOFIL

word 2 of either the WCB or DDB

FOPPN

word 3 of either the WCB or DDB

FONAMI

word 4 of either the WCB or DDB

word 5 of either the WCB or DDB

FOEXT

word 6 of either the WCB or DDB

FOSIZ

word 7 of either the WCB or DDB

FOBUFL

word 8 of either the WCB or DDB

FOMODE

word 9 of either the WCB or DDB

FOFLAG

word 10 of either the WCB or DDB

FOPFLG

word t 1 of either the WCB or DDB

FODEV

word 12 of either the WCB or DDB

FODEVN

word 13 of either the WCB or DDB

FOCLUS

word 14 of either the WCB or DDB

FONENT

Data Returned (for subcode

=1)

For FeB.
FIROB
Mne- Octal
monic Offset

Octal MneOffset monic

I I I I II I I I I I I II I I I I I II

3
FOSIZM5

111111/1/1

users w/file open rr

current job no .• 2

FOJOB

users w/file open nrr

FOFIL

FOPPN
FONAM1

MSB of file size

Status byte

LSB of file size

PPN of file

FOEXT

FOSIZ
FOBUFL

name of file
17

type of file

I I I I II I I I I I I II I I I I I II

I I I I 1/ I I I I I I 1/ I I I I I 1/

I I I I II I I I I I I II I I I I I 1/

device file is opened on

FOOEV

FOOEVN

<>0, unit number

device unit number

/1111111111111111111/

11111/1111111/111111/

FIRQB+FQFIL

The number of user who have a file open in a mode other than
read regardless.

FIRQB+FQSIZM

The number of user who have a file open in read regardless mode.

FIRQB+FQPPN

This byte contains the following internal flag information:
Bit
Meaning When Set
1

Placed file

Some job has write access now

File is open in update mode

File is contiguous; no extend allowed

No delete or rename allowed

File is a UFD

File is marked for deletion

.UUO-UU.FCB

3-313

Errors
BADFUO

The subfunction code passed in FIRQB+FQSIZM is a value other than zero
or one.

BSERR

The channel number specified at FIRQB+FQFIL is outside the range 0
through 17.

NODEVC

You requested FCB information (FIRQB+FQSIZM=l), but the file open on
the I/O channel specified at FIRQB+FQFIL is not a disk file.

NOTOPN

The I/O channel specified at FIRQB+FQFIL is not open.

Discussion

UU.FCB returns information kept in the DDB, WCB or FCB data structures.
Note that these data structures are internal to RSTSIE and subject to change at
any time.
Specifying 0 in FIRQB+FQSIZM returns information kept in the DDB or WCB
data structures.
Specifying 1 in FIRQB+FQSIZM returns information kept in the FCB, including
open counts, status byte, and current file size. RMS uses this call to determine
file characteristics.

3-314

.UUO-UU.FCB

3.36.23

UU.Fll (File Placement and Modification)
Privileges Required
Read access (by protection code, GREAD or WREAD privilege) is required to read
file flags. Write access (by protection code, GWRITE, WWRITE, and/or SYSIO
privilege) is required to set file flags. DATES is required to change last access
date. SYSIO is required to set/clear the no-delete flag (P-bit). TUNE is required
to set/clear file caching bits.
'lb improve performance, use the DCL command LOAD/OVERLAY FILE_

UTILITY to move the code for this call into memory. To remove it from memory,
use the DCL command UNLOAD/OVERLAY FILE_UTILITY.
Data Passed
FIRQ8
Octal
Offset

Mne- Octal
monic Offset

II / II II / / II 1/ / / 1/ / / 1/

Mnemonic

FQFUN

UU.FIL (= -32)

1111/1111/

FQSIZM

function code

channel no. (1-17)

FQFIL

project number

programmer number

FQPPN

FQNAM1

file name in RAD50 format
(2 words)

13
15

file type in RAD50 format (1 word)

FQEXT

least significant bits of block number

FQSIZ

FQNAM2

MSB of block number

placed/cache/seq. fig

new date of last access

FQMODE

new date of creation

FQFlAG

new time of creation

FQPFLG

2-character(ASCII) device name (disk only)

FQDEV

<>0, unit number real

device unit number

FQDEVN

1//1/1/1//

subfunction code

FQCLUS

FIRQB+FQFIL

///1/111/1/1/1111111/

You can also place a zero in this byte and specify the file by
file specification (device, PPN, file name, and type). The system
ignores the values in bytes 6 through 15 and 30 through 33 if you
use a nonzero channel number.

.UUO-UU.FIL

3-315

FIRQB+FQSIZM

3-316

This byte contains the following internal flags:
Bit
Meaning When Set

Set or reset file's placed bit (cannot be used with bit 3).

Used with bit 4 to return zero as the device cluster number if file's placed bit is not set.

Change file's backup statistics.

Change file's run-time system name field.

Return file's retrieval information. (Cannot be used with
bit 3.)

Reset file's contiguous bit.

Enable/disable sequential mode caching if file is cached.
(Cannot be used with bit 3.)

Enable/disable data caching on the file. (Cannot be used
with bit 3.)

FIRQB+FQPPN

The programmer number of the file you want to modify.

FIRQB+FQPPN+l

The project number of the file you want to modify.

FIRQB+FQNAMI

The file name, in RAD50 format, of the file you want to modify. If
FiRQB+FQFIL is nonzero, UU.FIL ignores these words.

FIRQB+FQEXT

The file type, in RAD50 format, of the file you want to modify. If
FIRQB+FQFIL is nonzero, UU.FIL ignores this word.

FIRQB+FQSIZ

If bit 3 of FIRQB+FQSIZM is set, the two words beginning at
FIRQB+FQSIZ contain the new run-time system name in RAD50.
If bit 4 of FIRQB+FQSIZM is set, the two words beginning at
FIRQB+FQSIZ contain the file's retrieval information. The monitor maps the virtual block number (VBN) of the file into the disk
DCN.

FIRQB+FQNAM2

This byte contains the following flags:
Bit
Meaning When Set
1

New value for placed bit if bit 0 of FIRQB+FQSIZM is set.

New value for sequential bit if bit 6 of FIRQB+FQSIZM is
set.

New value for backup bit if bit 2 of FIRQB+FQCLUS is
set.

New value for P-bit (no delete/rename allowed) if bit 0 of
FIRQB+FQCLUS is set.

New value for ignore bit if bit 3 ofFIRQB+FQCLUS is set.

New value for cached bit if bit 7 of FIRQB+FQSIZM is set.

FIRQB+FQMODE

Contains the new date of last access if bit 2 of FIRQB+FQSIZM is
set.

FIRQB+FQFLAG

Contains the new date of creation if bit 2 of FIRQB+FQSIZM is
set.

FIRQB+FQPFLG

Contains the new time of creation if bit 2 of FIRQB+FQSIZM is
set.

.UUO-UU.FIL

FIRQB+FQCLUS

Two subfunction codes currently in use are:
Bit
Meaning When Set

Change the value of the file's P-bit (see FIRQB+FQNAM2),

Do not return protection violation. If clear, and any of
the requested functions cannot be executed, the monitor
returns a protection violation error, If set, the monitor
changes all valid requested functions and leaves the rest
unchanged.

Change the backup bit.

Change the ignore bit.

If file is opened CFQFIL not 0), use DLA in FIRQB+FQMODE
if bit 2 ofFIRQB+FQSIZM is set.

Data Returned
FIR08
Mne- Octal
monic Offset

Odal
Offset

Mnemonic

II / / / / / / / / / / / / / / / / / / /

FOJ08

FOFIL

FOPPN

FOFUN 3

file characteristics

current job no .• 2

device cluster number

file attribute data

(unused words are padded with NULLs)

35
37

run-time system name in RAD50 format
(2 words)

34 FOCLUS
36

.UU~UU.FIL

3-317

li'IRQB+FQFUN

File characteristics:
Bit
Meaning When Set
1

File is placed.

File will be cached sequentially, if at all.

File is set NOBACKUP.

File is contiguous.

Current setting of file's P-bit.

File is set IGNORE.

File will be cached when open.

Errors

3-318

BADFUO

File open is not a disk file or is a user file directory.

NOSUCH

File or account is not present on disk.

NOTOPN

Channel is not open.

PRVIOL

File open is not a disk file or job lacks necessary privilege (see FIRQB+FQCLUS
in data passed).

.UUO-UU.Fll

3.36.24

UU.HNG (Hang Up a Dataset)
Privileges Required
HWCTL is needed to hang up a dataset, except on a keyboard line owned by the
calling job.

Data Passed
FIROB
Mne- Octal
monic Offset

Octal
Offset
/////////////////////

FOFUN 3

UU.HNG ( 11)

//////////

FOSIZM5

seconds to wait

KB number of line

/////////////////////

/ / / / / // / / / / / / // / / / / / /

/////////////////////

////////////////1////

////1/1/1/////1/1////

//////1/1///////1////

//////1/1/////1//////

//1/11///////1///////

////1////////1///////

/ / / / / 1/ / / / / / / 1/ / / / / / /

/////1///////1//////1

////11//////11////1//

FIRQB+FQSIZM

Mnec
monic

FOFIL

Use one of the following values:
Sets "Data Tenninal Ready" to pennit a modem con377
nected to a RSTSIE system to dial out. If a connection
is not made in 127. seconds, perfonn an automatic
hang-up of the dataset.

Hang up in two seconds.

1-177

Hang up in 1 to 127. seconds.

Data Returned
The UU.HNG subfunction does not return any data.

Errors
BADFUO

Illegal KB number or insufficient privileges to hang up a line owned by
another job.

.UU~UU.HNG

3-319

3.36.25

UU.JOB (Create Job)
Privileges Required
Set account access is required (GACNT or WACNT privilege) to spawn to another
account. EXQTA is required to ignore job quota on spawn. JOBCTL is required
to spawn a job even if no logins is set. TUNE is required to specify a priority
when creating a job. WACNT is required to spawn a logged-out job.

Data Passed -

Logged-out job
FIROB

Mne- Octal
monic Offset

Octal MneOffset monic
/1///////1//////1////

FOFUN 3

UU.JOB (= 30)

///1//////

/11/11/11/

bit flags

FOFIL

project number

programmer number

FOPPN

FONAM1

file name in RAD50 format
(2 words)

11
13

file type in RAD50 format (1 word)

17
21

10 bytes of
information to be
placed in created job's
core common area

FOEXT

FOSIZ

20
22

31
33

device name (2 ASCII characters)
<>O,unit number real

device unit number

FODEV

FODEVN
FOCLUS

parameter word (see P.RUN)

/I / / / / / / /I / / / / / /I / / / /

FIRQB+FQFIL

The following bit flag is valid for a logged-out job:
Bit
Meaning When Set
7

3-320

Create a job even if logins are disabled (JOBCTL privilege
required). When this bit is not set, the job is created
only if logins are enabled. If you do not have JOBCTL
privilege, you must clear bit 7.

FIRQB+FQPPN

The project programmer number of the program to run.

FIRQB+FQNAMI

The file name of the program to run, in RAD50 format.

FIRQB+FQEXT

The file type of the program to run, in RAD50 format.

FIRQB+FQDEV

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.

FIRQB+FQDEVN

The device name and unit number of the program to run.

.UUO-UU.JOB

FIRQB+FQCLUS

Data Passed -

The parameter word to be passed to the program to run. The
parameter word has exactly the same format and functions as the
CCL 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.

Logged-in Job to Run a Program
FIROB

Mne- Octal
monic Offset

Octal MneOffset monic
111111111111111111111

FOFUN 3

UU.JOB (= 30)

1111111111

FOSIZM5

KB to attach to

bit flags

FOFIL

project number

programmer number

FOPPN

FONAM1

file name in RAD50 format
(2 words)

13
15

12
file type in RAD50 format (1 word)

FOEXT

project number

programmer number

FOSIZ

run burst

priority

FOBUFL

1111111111

FOMODE

maximum job size

I I I I I II I I I I I I II I I I I I I

11111111111111/111111

device name (2 ASCII characters)

FODEV

FODEVN
FOCLUS

<>O,unit number real

device unit number

parameter word (see P.RUN)

I I I I I /I I I I I I I /I I I I I I I

NOTE

When you create a logged-in job, the system gives the new job a copy of
the core common, the logicals, and the command line recall buffer.

.UUO-UU.JOB

3-321

FIRQB+FQFIL

The following bit flags are valid when you create a logged-in job to
run a program.
Bit
Meaning When Set
1

Do not pass the user logicals of the creating account to the
new job. (The contents of core common are still passed.)

Create the new job with no privileges.

Create the new job with the authorized privileges of the
new job equal to the authorized privileges of the job's
account that are also current privileges of the calling job.
If Bit 3 is clear, the new job is created with the authorized
privileges of the job's account.

Create a job to run under account specified at FIRQB+FQSIZ
(GACNT or WACNT privilege required).

Create a logged-in job. You must set this bit. The new job
runs under the caller's account unless you also set bit 5.

3-322

FIRQB+FQSIZM

Bits 0-6 indicate keyboard number to att,ach to. To specify KBO:,
set bit 7 to one. A zero byte indicates a detached job.

FIRQB+FQPPN

The PPN of the programto run.

FIRQB+FQNAMI

The file name of the program to run, in RAD50 format.

FIRQB+FQEX.T

The file type of the program to run, in RAD50 format.

FIRQB+FQSIZ

Account under which job runs (GACNT or WACNT privilege
required; bit 5 at FIRQB+FQFIL must be set). If you do not have
the necessary privileges, set both bytes to o.

FIRQB+FQBUFL

Priority of the new job (requires TUNE privilege). If you specify 0,
the system uses the caller's values. Use bit 8 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.

FIRQB+FQBUFL+l

Run burst of the new job (requires TUNE privilege). Use one to
explicitly specify priority zero. If you specify 0, the system uses
the caller's values. Users without TUNE privilege must set this
byte to o.

FIRQB+FQMODE

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.

FIRQB+FQDEV

Device name, as two ASCII characters, for the program to run.

FIRQB+FQDEVN

Device unit number for the program to run.

FIRQB+FQCLUS

.UUO-UU.JOB

Data Passed -

Logged-in Job to Enter a Keyboard Monitor at P.NEW
FIROB

Mne- Octal
monic Offset

Octal MneOffset monic

///////////////// / // /

FOFUN 3

UU.JOB (= 30)

1111111111

FOSIZM5

KB to attach to

bit flags

FOFIL

/ / / / / II / / / / / / / / / / / / / /

FOPPN

run-time system name in RAD50 format
(2 words)

FONAM1

13
15

/ / / / / / / / / / / / / II / / / / / /

FOEXT

project number

programmer number

FOSIZ

run burst

priority

FOBUFL

111111/11/

maximum job size

FQMODE

/ / / / / II / / / / / / II / / / / / /

/////////////////////

/ / / / / II / / / / / / / / / / / / / /

/ II / II II II / / II / / / / II /

//////////i////////I/

/11111111111111111111

NOTE

When you create a logged-in job, the system gives the new job a copy of
the core common, the logicals, and the command line recall buffer.

.UUO-UU.JOB

3-323

FIRQB+FQFIL

The following bit flags are valid when you create a logged-in job to
enter a keyboard monitor.
Bit
Meaning When Set
1

Do not pass the user logicals of the creating account to the
new job. (The contents of core common are still passed.)

Create the new job with no privileges.

Enter keyboard monitor instead of running a program.
(You must set this bit.)

Create a job to run under account specified at FIRQB+FQSIZ
(GACNT or WACNT privilege required).

Create a logged-in job. (You must set this bit.) The new
job runs under the caller's account unless you also set bit

5.
7

3-324

FIRQB+FQSIZM

Bits 0-6 indicate keyboard number to attach to. To specify KBO:,
set Bit 7 equal to one. The value of zero (detached job) is not
allowed.

FIRQB+FQNAMI

The run-time system you specify must be installed and must be a
keyboard monitor. Specify zero for the system's default keyboard
monitor (DCL).

FIRQB+FQSIZ

Account under which job runs (GACNT or WACNT privilege
required; bit 5 at FIRQB+FQFIL must be set). If you do not have
the necessary privileges, set both bytes to zero.

FIRQB+FQBUFL

Priority of the new job (requires TUNE privilege). If you specify 0,
the system uses the caller's values. Use bit 8 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.

FIRQB+FQBUFL+l

FIRQB+FQMODE

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.

FIRQB+FQDEV

Device name, as two ASCII characters, for the program to run.

.UUO-UU.JOB

Data Returned (all types of jobs)
FIROB

Octal MneOffset monic

Mne- Octal
monic Offset
11/111111////11/11///

/11111111/

current job no .• 2

FOJOB

""""" created job no .• 2
" ""
"
"
" "
" "
" "
" "
"
"
" "
" "
"
"
" "
" "

FOFIL

7
11
13
15

17
21
23
25

27
31

33
35
37

/ / / / / II / / / / / / II / / / / / /

/////

///

///// /

////

///////

//////

/////

//////

/////

//////

/////

///////

/////

//////

/////

//////

/////

//////

/////

// ////

// / / / /

/////

//////

/////

//////

/////

//////

Errors
BADFUO

You specified a keyboard monitor at FIRQB+FQNAMl, but did not supply a
keyboard number at FIRQB+FQSIZM.

NOBUFS

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.

NODEVC

The keyboard number at FIRQB+FQSIZM is invalid.

NOROOM

Job cannot be created. Probable causes:
•
•

Logins are disabled and bit 7 (value = 200) at FIRQB+FQFIL is clear.
The system's job or swap slots are currently full.

NOSUCH

You have the necessary privilege and are trying to create a logged-in job,
but the system cannot log the job in. Possible causes are that you specified
a nonexistent account or an expired account.

NOTAVL

The keyboard specified at FIRQB+FQSIZM is open, is in use, or is not
assigned to the calling job. A user without DEVICE privilege can also get
this error if the system manager has restricted the device .

.UUO-UU.JOB 3-325

PRVIOL

You do not have the required privileges and tried to:
..
..
..
•

Create a job when logins were disabled.
Create a logged-out job.
Create a job to run under an account other than the current account.
Create a detached job that would cause you to exceed your detached job
quota. (This quota is set by your system manager; its default value is
zero.)

Note that when you create a logged-in job, you can also get any error that can
occur for the UU.LIN (Login), .RUN, and .RTS directives, because the monitor
executes these directives for the new job. If an error occurs, the monitor kills the
new job and returns the error to your job instead.

3-326

.UUO-UU.JOB

3.36.26

UU.LlN (Login)
Privileges Required
Set account access (GACNT or WACNT) is required to check the password of any
account. Also, DEVICE is required if the device is restricted.

Data Passed-Login Function
FIROB
Mne- Octal
monic Offset

Octal MneOffset monic

I I I I /I I I I I I I /I I I I I I 1/

FOFUN 3

UU.LlN (= 4)

/11/1/11/1

FOSIZM5

function flag

/11/1/1//1

project number

programmer number

FOPPN

FONAM1

11
13

password in RAD50 format
(2 words)

password in ASCII format
(14 bytes)

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 I I I I /I I I I I I 1/

FIRQB+FQSIZM

The function flag bits are:
Bit
Setting
Meaning

Clear

Must be clear for the login function.

Clear

The monitor assumes the password is six
characters in RAD50 format. The password
is converted to ASCII before comparison.

Set

The monitor assumes the password is 14
bytes of ASCII data.

In either case, the password must not contain a question mark (1).
3

FIRQB+FQPPN

Clear

The monitor performs the password check.
No privileges are required.

Set

The monitor suppresses the password check.
However, GACNT or WACNT is required.

PPN for the account being logged into. It must not be in group
[0,*].

.UUO-UU.LlN

3-327

Data Returned
FIROB
Mne- Octal
monic Offset

Octal MneOffset monic

1/ / / / / / / 1/ / / / / / 1/ / / / /
status flags

FOFUN 3

I
I

current job no .• 2

0
2

FOJOB

FOFIL

FOPPN

FONAM1

total number of jobs under this account

detached job no. (2)

detached job no. (1)

14
zero byte marks end of list
of detached job numbers.

only the first 25. detached
job numbers are returned.

16
20

FIRQB+FQFUN

On successful return, indicates where the log-in operation has
been completed. Values are:
Value
Meaning
-1

Success--the job is logged in to the new account.

-2

Detached job quota exceeded. Job is not logged in and
remains in the old account; attach instead to some job
from the list starting at offset FQNAMl.

Total job quota exceeded. Job is not logged in and
remains in the old account; the value returned is the
actual job quota. If there are any detached jobs, you
can attach to one.

Errors

3-328

BADDIR

The account does not have all the necessary directory structures.

NOBUFS

No buffers are available to create the necessary internal structures.

.UUO-UU.LlN

NOSUCH

The monitor returns this error code if:
•
•
•

NOTAVL

The password specified at FIRQB+FQNAMl does not match the password of the account on the system or contains question marks.
The PPN specified at FIRQB+FQPPN does not exist or the project
number is zero.
System password validation is required for this type of job, and the account is marked "no-lookup," but the "verify system password" function
has not yet been successfully executed.

The monitor returns this error code if:
•
•

The PPN specified at FIRQB+FQPPN is expired or is marked as "nointeractive. "
The account is flagged as "no-dial-up" or "no-network" and the job is a
dial-up or network job.

Data Passed-Verify Password Function
FIRQB
Octal MneOffset monic

Mne- Octal
monic Offset

/ / / / II / / / / / / II / / / / / II

FQFUN 3

UU.LlN (= 4)

11/1/1/1//

FQSIZM5

function flag

111/1/1/11

project number

programmer number

FQPPN

FQNAM1

11
13

password in RAD50 format
(2 words)

password in ASCII format
(14 bytes)

/ / / / II / / / / / / II / / / / / II

device name (2 ASCII characters)

FQDEV

FQDEVN

<>O,unit number real

device unit number

/ / / / II / / / / / / II / / / / / II

.UUO-UU.L1N

3-329

FIRQB+FQSIZM

The function flag bits:

Bit

Setting

Meaning

Set

The verifY password function is performed.
The caller supplies the password to verifY in

FIRQB+FQNAM1.
1

Clear

The monitor assumes the password is six
characters in RAD50 format. The password is converted to ASCII data before
verification.

The monitor assumes the password is 14
bytes of ASCII data.
In either case, the password must not contain any question marks.
1

Set

FIRQB+FQPPN

A value of zero means use the caller's PPN.

FIRQB+FQDEV

Device name of the disk on which to check. You must

FIRQB+FQDEVN

have DEVICE privilege if the device is restricted.

Data Returned

Except for a possible error in byte 0 of the FIRQB, the UU.LIN subfunction does
not return any meaningful data.
Errors

3.36.26.1

BADNAM

Passwords do not match.

DEVNFS

Device specified is not a disk.

NOSUCH

Account specified is a nonuser account (no password data present) or does
not exist.

PRVIOL

Caller does not have required privilege.

Verify System Password Function

This function verifies the system access password, if any. If there is no system
access password, or if the password check has already been performed, the
function returns successfully. Otherwise, the monitor compares the password
supplied with the system password. A match sets a job flag which is tested by the
login function; a mismatch generates the NOSUCH error.
For compatibilty with old programs that perform a password lookup and then
login, the login function does not require a system password on accounts where
password lookup is allowed.

3-330

.UUO-UU.UN

Data Passed-Verify System Password Function
FIROB
Mne- Octal
monic Offset

Octal
Offset
I I I I I 1/ I I I I I I I I I I I I I I

FOFUN 3

UU.LlN (= 4)

1/11111111

FOSIZM 5

function flag = 6

1111111111

I I I I I II I I I I I I I I I I I I I I

Mnemonic

10 FONAM1

password in ASCII format
(14 bytes)

11111111111/111111111

I I I I I II II II i I 1/ I II II I

11111/1/1111111111111

I I I I I 1/ I I I I I I I I I I I I I I

II I 1/ 1/ II II II 1/ I II I I I

Data Returned
Except for a possible error in byte 0 of the FIRQB, the UU.LIN subfunction does
not return any meaningful data.

Errors

NOSUCH

Password did not match the system password.

.UUO-UU.UN

3-331

3.36.27

UU.LOG (Set Number of Logins)
Privileges Required
SWCTL is required to set the number of logins.

Data Passed
FIROB
Octal
Offset

Mne- Octal
monic Offset

I 1/ I I I I I I 1/ I I I I I 1/ I I I
FOFUN 3

3-332

.UUO-UU.LOG

UU.LOG (= -23)

111/111111

11111/1111

no. of allowed jobs

I 1/ I I I I I I 1/ I I I I I 1/ I I I

11/1111/11/111111/111

1/ I I I I I I I 1/ I I I I I 1/ I I I

I 1/ I I I I I I 1/ I I I I I 1/ I I I

11/1111111/111111/111

I 1/ I I I I I I 1/ I I I I I 1/ I I I

FIRQB+FQFIL

Mnemonic

FOFIL

A value of zero sets the number of allowed jobs to one. 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. In this case, no error is returned.

Data Returned
FIROB
Octal MneOffset monic

Mne- Octal
monic Offset

"'"'""""1111"'

1111111111

current job no .• 2

2 FOJOB

1111111111

actuallogins set

4 FOFIL

, , , , , , II , , , , , , II , , , , ,

, , , /I , , , , , , , , , , , / , , , ,

'""'""""""'"
'""'""""""'"

, , , , , , II , , , , , , II , , , , ,

"'"'"""""""'
"""""""""'"
"'"'"""""""'
"""""'"""""

15
17

27
31

33
35
37

""""""'""'"'

14
16

26
30
32

""'""""'"""'

""""'""'""'"

Errors
No errors are possible with the UU.LOG subfunction.

.UUO-UU.LOG

3-333

3.36.28

UU.LOK (Disk Directory Lookup by File Name/Wildcard Lookup)
Privileges Required

DEVICE is required to do a directory lookup on a restricted device. Read or
execute access (by protection code, GREAD or WREAD privilege) is required to
lookup another account.
Data Passed -

Look Up by File Name
FIROB

Mne- Octal
monic Offset

FOFUN 3

Octal MneOffset monic
/1///////1//////1/1//

UU.LOK (= 21)

(must = 177777)

FOFIL

FOPPN

FONAM1

project number

/1/11/1/1/

programmer number

file name in RAD50 format
(2 words)

file type in RAD50 format (1 word)

/I / / / / / / /I / / / / / /I / / / /

/1///////1//////11///

/I / / / / / / /I / / / / / /I / / / /

31
33

device name (disk) (2 ASCII characters)
<>0, unit number real

.UUO-UU.LOK

device unit number

FODEV

FODEVN

/1///////1//////11/1/

/1///////1//////1////

FIRQB+FQPPN

3-334

FOEXT

PPN of the file to look up. Zero in both bytes means the current
account is used.

Data Returned -

Look Up by File Name
FIRQB

Mne- Octal
monic Offset

Octal MneOffset monic
/ / / / / / / / / /I / / / / / /I / / /

FQJOB

(= 177777)

FQFIL

FQPPN

FQNAM1

1111111111

3
5

project number

7
11

current job no .• 2

programmer number

file name in RAD50 format
(2 words)

file type in RAD50 format (1 word)

14 FQEXT

LSB of file length in 512-byte blocks

16 FQSIZ

MSB of file length

protection code

FQNAM2

date of last access

FQMODE

date of creation

FQFLAG

time of creation

FQPFLG

device name (disk) (2 ASCII characters)

FQDEV

FQDEVN

<>0, unit number real

device unit number

file cluster size

FQCLUS

file identification index

FQNENT

System internal format for dates is:

FIRQB+FQMODE
FIRQB+FQFLAG

[(year - 1970.) * 1000.J + day-with in-year

FIRQB+FQPFLG

Time is in minutes until midnight, where 1440. equals midnight.
See the .DATE directive for a discussion of these formats.

Errors
BADNAM

The file name at FIRQB+FQNAM1 is missing or invalid.

NOSUCH

Device specified at FIRBQ+FQDEV is not a disk, or the file specified does
not exist on the disk. This error also occurs when a user does not have read
or execute access to the specified file.

PAKLCK

The disk is restricted and the account under which the call is executed does
not have DEVICE privilege.

.UUO-UU.LOK

3-335

Data Passed -

Disk Wildcard Directory Lookup
FIR08
Octal MneOffset monic

Mne- Octal
monic Offset

'"11"""""'"'"
UU.LOK (= 21)
I 111111111'

FOFUN 3

index:n means search for n+ 1 occurrences

project number

wildcard file name in RAD50 format
(2 words)

programmer number

2
4 FOFIL
6

FOPPN

10 FONAM1

15 wildcard file type in RAD50 format (1 word)

14 FOEXT

'"""'1"'1111111"
'""'"'"'1"'"'"

17
21

16
20

marked-for-delete flag

'"11"""""'1111'

, II , , , , , II , , , , , , " , , ,

device name (disk) (2 ASCII characters)

3-336

<>0, unit number real

device unit number

22 FOMODE

FODEV

32 FODEVN

, II , I I I , , II , , , , , II , I I

1111111"11""'11'"

FIRQB+FQFIL

The index number, telling the directive to return the first n+1
examples. If the value is zero, then the first file matching the
wildcard specification is returned; if the value is one, then the
second file. This continues until there are no more matching files
and the NOSUCH error returns.

FIRQB+FQPPN

Zero in both bytes means the current account.

FIRQB+FQNAM1

RAD50 representation of a wildcard file name specification, where
a question mark (?) can replace any character in the file name.
Used with the file type in FIRQB+FQEXT to create a wildcard
file specification. You can use .FSS to help construct the wildcard
name.

FIRQB+FQEX.T

RAD50 representation of a wildcard file type specification, where a
question mark (?) can replace any character in the file type. Used
with the file name in FIRQB+FQNAM1 to create a wildcard file
specification.

FIRQB+FQMODE

Bit 14 set causes the monitor to return information about markedfor-delete files.

.UUO-UU.LOK

Data Returned -

Disk Wildcard Directory Lookup
FIRQB

Mne- Octal
monic Offset

Octal MneOffset monic
0

FQJOB

(same as data passed)

FQFIL

FOPPN

FONAM1

1/1/1/1/1/

5
7

IIII I IIIIII IIIIIIIIII

project number

current job no .• 2

programmer number

file name in RAD50 format
(2 words)

11
13

file type in RAD50 format (1 word)

lSB of file length

FOSIZ

FONAM2

MSB of file length

14 FOEXT

protection code

date of last access (diSk only)

FOMODE

date of creation

FOFLAG

time of creation

FOPFLG

(same as data passed)

FODEV

(same as data passed)

FODEVN

file cluster size (disk only)

FOCLUS

USTAT byte

FONENT

FIRQB+FQNENT+1

//1/1//11/

This byte contains the following intern.al flag infonnation:
Bit
Meaning When Set
1

File is placed

Some job has write access now

File is open in update mode

File is contiguous; no extend allowed

No delete or rename allowed

File is marked for deletion

Errors
BADNAM

The file name at FIRQB+FQNAMI is missing or invalid.

NOSUCH

Device specified is not a disk or no file corresponds to the index given.

PAKLCK

The disk is restricted and the account under which the call is executed does
not have DEVICE privilege.

.UUO-UU.lOK

3-337

3.36.29

UU.MNT (Disk Pack Status)
Privileges Required

You need HWCFG privilege to declare a mounted disk as restricted or unrestricted. You need SWCTL privilege to load or unload the Storage Allocation
Table (SAT) of the specified disk into or out of memory. You need MOUNT
privilege to:
•

Mount or dismount a shared disk

•

Dismount a /NOSHARE disk owned by another job

•

Mount a disk /NOSHARE for a job running under another PPN

•

Mount a dirty disk

Data Passed
FIROB
Mne- Octal
monic Offset

Octal MneOffset monic
/ / I I I II / I / I I / II / I / / / /

FOFUN 3

UU.MNT (= 3)

/11111111/

FOSIZM5

job number

subfunction code

/ / / / / II / / / / / / II / / / / / /

pack identification label in RAD50 format
(2 words)

FONAM1

=177777, use logical; =0, use pack ID

FOEXT

logical name for disk in RAD50 format
(first 2 words)

FOSIZ

mode word

FOMODE

3rd word of logical name for disk (RAD50)

FOFLAG

I / / I I II I I I I I I II I I I I I I

device name (2 ASCII characters)

FODEV

FODEVN

.UUO-UU.MNT

FOFIL

3-338

<>0, unit number real

device unit number

11111111111/111/11/11

I / I I / II I I I I II II / I / / / I

FIRQB+FQFIL

The subfunction codes are:
Code Meaning

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 the SAT of a disk into memory

Unload the SAT of a disk from memory

Reserved for future use

Return disk drive status information

FIRQB+FQSIZM

Job number of the intended owner. Applies only if bit 11 is set in
FIRQB+FQMODE. Zero means the caller's job number. Ifbit 11
in FIRQB+FQMODE is clear, this byte should be zero.

FIRQB+FQNAMI

For mount function: pack ID of pack to mount. Must be supplied
unless bit 10 is set in FQMODE.

FIRQB+FQMODE

The bits in the mode word are:
Bit
Meaning
8

Mount Level 1.2 disk with INOQUOTA

Mount with lookup of pack ID

Mount disk for use by single user (INOSHARE)

Mount disk read/write, even if disk was initialized as
read-only

Mount disk read-only

Mount as a private disk (!PRIVATE)

Must be set if any of the above bits are set

You can set one bit or a combination of bits .

.UUO-UU.MNT 3-339

Data Returned
FIRQB
Octal MneOffset monic

Mne- Octal
monic Offset
I I I I I /I I I I I I 1/ I I I I I 1/

3-340

//////11/1

current job no .• 2

0
2 FQJOB

UNTCNTword

4 FQFIL

CSR value

6 FQPPN

Controller number

10 FQNAM1

UNTOPT number

MID value

17
21

size of SAT in bytes (first word) or
logical name for disk in RAD50 format
(2 words)

1////1111111//111111/

3rd word of logical name for disk (RAD50) .

////1/1111111/111111/

//111/1111111/111111/

I I I I 1/ I I I I I I 1/ I I I I I /I

I I I I /I I I I I I I /I I I I I I 1/

I I I /I I I I I I I I 1/ I I I I I 1/

16 FQSIZ

24 FQFLAG

FIRQB+FQFIL

The internal UNTCNT value for the specified disk, if the subfunction code is 16 in FIRQB+FQFIL of the data passed.

FIRQB+FQPPN

The CSR value for the specified disk, if the subfunction code is
16 in FIRQB+FQFIL of the data passed. The disk does not exist
if this value is 0. If a CSR is returned, the specified unit mayor
may not exist.

FIRQB+FQNAM1

The controller number if the specified disk is a DU type disk, and
if the subfunction code is 16 in FIRQB+FQFIL of the data passed.
Otherwise, this value is random.

FIRQB+FQNAM1+2

The internal UNTOPT value for the specified disk, if the subfunction code is 16 in FIRQB+FQFIL of the data passed.

FIRQB+FQEXT

The internal drive type identifier for the specified disk, if the
subfunction code is 16 in FIRQB+FQFIL of the data passed.

FIRQB+FQSIZ

For subfunction 10, RSTSIE returns the amount of memory in
bytes that was used to load the SAT in FIRQB+FQSIZ. For other
subfunctions, RSTSIE returns the first two words of the logical
name for the disk. The third word of the logical name is in
FIRQB+FQFLAG.

.UUO-UU.MNT

Errors
BADFUO

You tried to mount a disk that is already mounted or that resides in a
nondismounted drive, or drive specified is the system disk.

BADPAK

Disk directory structure is invalid. For example, the cluster size is larger
than 16 or the SAT is unreadable.

DEVNFS

You tried to restrict, unrestrict, or dismount a disk currently open in nonfile-structured mode. Or, you tried to load or unload the SAT of a disk
currently open in non-file-structured mode.

HNGDEV

You tried to mount a disk that is not write-enabled or you tried to load the
SAT of a read-only disk.

INTPAK

The SAT on the disk needs to be rebuilt because the disk was not properly
dismounted when it was last used. Before using the disk, use the ONLCLN
program to rebuild the SAT.

NOTE

The MOUNT command automatically performs the rebuild operation if it is needed.
Note that when this error occurs, the mount succeeds, but the disk is always
mounted read-only with the "dirty" bit set. (You can see if this bit is set by
looking at the output of the SHOW DISK command which reports that the
disk is "dirty.")
INUSE

You tried to dismount a disk with an open file.

NOBUFS

You tried to load the SAT and there is no memory available.

NODEVC

Device type or unit at FIRQB+FQDEV is not on the system.

NOTCLS

You tried to load the SAT more than once.

NOTMNT

You tried to lock, unlock, or dismount a disk that is not mounted. Or, you
tried to load or unload the SAT of a disk that is not mounted.

NOTOPN

You tried to unload the SAT of a disk that was not loaded.

PRVIOL

You tried to mount a disk that does not contain the RSTSIE file structure. Use the INITIALIZE command, the online DSKINT program, or the
DSKINT initialization option to initialize the disk. You do not have the
required privilege to load or unload the SAT.

WRGPAK

You tried to mount a disk with an incorrect pack label.

.UUO-UU.MNT 3-341

3.36.30

UU.NAM (Associate a Run-Time System with a File)
Privileges Required

File write access (by protection code or GWRITE, WWRITE, and/or SYSIO
privilege) is required to set the run-time system name for a file.
Data Passed
FIROB
Mnemonic

Octal
Offset

Octal
Offset
/I I I I I I I /I I I I I I /I I I I I

FOFUN

FOSIZM 5

UU.NAM (= -21)

//////////

run-time

channel number

FOFIL

FOPPN

system name in RAD50 format

1///////1/

Mnemonic

(2 words)

/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 1/ I I I I I // I I I I

1/1111111/1//111/1111

1/1111111/111//1/1111

1/11111////11////1111

/I I I I I I I /I I I I I I /I I I I I

1/ 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 I I I I I /I I I I I

1/1111111/1//111/1111

/I I I I I I I 1/ I I I I I 1/ I I I I

Data Returned

Other than a possible error in byte 0 of the FIRQB, the UU.NAM subfunction
does not return any meaningful data.
Errors

3-342

NOTOPN

Channel is not open.

PRVIOL

File open on channel is not a disk file or the job executing the call does not
have write access.

.UUO-UU.NAM

3.36.31

UU.NLG (Disable Further Logins)
Privileges Required
SWCTL is required to disables logins.

Data Passed
FIRQ8
Mnemonic

Octal
Offset

FQFUN 3

Octal
Offset
/ / / / / / /I / / / / / / /I / / / / /

UU.NLG (= -2)

//////1/1/

/ / / / / / /I / / / / / / /I / / / / /

/ / / / / / 1/ / / / / / / /I / / / / /

/ / / / / / /I / / / / / / /I / / / / /

/ / / / / / 1/ / / / / / / 1/ / / / / /

/ / / / / / 1/ / / / / / / II / / / / /

/ / / / / / II / / / / / / II / / / / /

/ / / / / / /I / / / / / / II / / / / /

/ / / / / / /I / / / / / / /I / / / / /

Mnemonic

Data Returned
The UU.NLG subfunction does not return any meaningful data.

Errors
No errors are possible with the UU.NLG subfunction.

.UUO-UU.NLG

3-343

3.36.32

UU.ONX (Open Next Disk File)
This call opens a disk file or a series of disk files matching a wildcard specification. UU.ONX requires an 1/0 channel to use and grants access to the
file.
When you attempt an open next on a closed channel, UU.ONX finds the first
file that matches the specification. When you attempt an open next on an open
channel, UU.ONX finds the next file that matches the specification. If there are
no more files that match the specification, UU.ONX closes the channel.

Privileges Required
DEVICE is required to perform an open next on a restricted disk. File read
access (by protection code, or GREAD or WREAD privilege) is required to perform
an open next for read access. File write access (by protection code, or GWRITE,
WWRITE, and/or SYSIO privilege) is required to perform an open next for write
access.

Data Passed
FIR08

FOFUN

Octal
Offset

Mnemonic

3
5
7
11

II I I I I I II I I I I I I I I I I I I

UU.ONX (= 41)

1111111111

channel number' 2

FOFIL

FOPPN

FONAM1

project number

programmer number

file name in RAD50 format
(2 words)

file type in RAD50 format (1 word)

II I I I I I II I I I I I II I I I I I

OPEN mode

II I I I I I II I I I I I II I I I I I

II I I I I I 1/ I I I I I 1/ I I I I I

device name (2 ASCII chars) must be disk

FODEV

FODEVN

3-344

Mnemonic

<>0, unit no. real

device unit number

II I I I I I 1/ I I I I I 1/ I I I I I

II I I I I I 1/ I I I I I II I I I I I

FOEXT

FOMODE

FIRQB+FQPPN

The file owner's PPN. Zero indicates the current account. Wildcards
are not permitted in the specification.

FIRQB+FQNAMI

The name of the file in RAD50 format. The name may contain
wildcard characters (question marks, ?).

.UUO-UU.ONX

FIRQB+FQEXT

The type of the file in RAD50 format. The type may contain wildcard characters (question marks, ?).

FIRQB+FQMODE

The OPEN modes currently defined are:
Decimal
Octal
Function

Normal read/write

Update

Append

Guarded update (4 + 1)

Special extend (RSTSIE updates file's
size and retrieval pointers during
extend operations)

16.

Do not update access dates to files;
do not grant write access (requires
DATES privilege)

32.

Do not grant any access to files (directory lookup only)

256.

400

User data caching

2048.

4000

Sequential data caching (with 400)

4096.

10000

Read normally regardless

8192.

20000

Open file read-only

16384.

40000

Include files marked-for-delete

32768.

100000

Mode bits are real; this must be specified for the other open bits to be
tested

FIRQB+FQDEV

The device name; must be a disk. Zero in both bytes indicates "SY",
the public disk.

FIRQB+FQDEVN

The device unit number. A nonzero value in the high byte
(FIRQB+FQDEVN+1) indicates an explicit device unit number
in the low byte. A zero value in FIRQB+FQDEVN+1 indicates no
unit number.

.UUO-UU.ONX

3-345

Data Returned
FIROB
Mnemonic

Octal
Offset

Octal MneOffset monic
I I II I I I I I II I I I I I I II I I

11//1////1

current job no • 2

2 FOJOB

FOSIZM 5

MSB of file size

channel no .• 2

4 FOFIL

project number

programmer number

6 FOPPN

file name in RAD50 format
(2 words)

11
13

10 FONAM1
12

file type in RAD50 format (1 word)

14 FOEXT

LSB of file size

16 FOSIZ

last access date

20 FOBUFL

creation date

22 FOMODE

creation time

24 FOFLAG

protection code

31
33

3-346

cluster size

26 FOPFLG

device name in two ASCII characters

30 FODEV

flag byte

device unit number

32 FODEVN

file identification index

34 FOCLUS

device description

36 FONENT

FIRQB+FQSIZM

FIRQB+FQPPN

The PPN under which the file is open.

FIRQB+FQNAMI

The file name; two words of RAD50 data.

FIRQB+FQEXT

The file type; one word of RAD50 data.

FIRQB+FQSIZ

The LSB of the file's size in 512-byte blocks. (See FIRQB+FQSIZM.)

FIRQB+FQBUFL

The date of last access to the file.

FIRQB+FQMODE

The date of creation of the file.

FIRQB+FQFLAG

The time of creation of the file.

FIRQB+FQPFLG

The file cluster size, modulo 256. That is, a file cluster size of 256
is indicated by a value of zero.

FIRQB+FQPROT

The protection code of the file.

FIRQB+FQDEV

The device name, as two ASCII characters.

FIRQB+FQDEVN

The device unit number.

FIRQB+FQCLUS

The file identification index of the file. This word can be used
instead of the file name in subsequent opens of the file. The file
identification index is provided for compatibility with RSX

.UUO-UU.ONX

FIRQB+FQNENT

The description of the device just opened. The low byte contains
the device's handler index. The high byte contains a set of status flags to allow for device-independent 1/0 routines. (See the
OPNFQ subfunction of CALFIP.)

Errors
BADFUO

The parameters passed in the call are inconsistent with the currently open
channel.

DEVNFS

You tried to open a device that is not a disk.

HNGDEV

Device is hung or write-locked.

NOSUCH

No more files match the specification. The channel is closed.

NOTMNT

The device is not mounted.

PAKLCK

The disk pack is restricted. You need DEVICE privilege to open a restricted
disk.

.UUO-UU.ONX 3-347

3.36.33

UU.PAS (Create User Account)
Privileges Required

Set account access (GACNT or WACNT) is required to create an account.
Data Passed (Updated Format)
FIROB
Mnemonic

Octal
Offset

Octal
Offset
/ / /I / / / / / / /I I / / / / /I / /

FOSIZM

Mnemonic

UU.PAS (=0)

//////////

flags

preextnd UFO clstrs

FOFIL

device cluster number for UFO or -1

FOPPN

FONAM1

project number

programmer number

13
password (2 words in RA050 format)

15
17

LSB of logged-out quota (blocks)

FOSIZ

expiration date

FOBUFL

LSB of logged-in quota (blocks)

FOMOOE

FOFLAG

MSB logged-out quota

/ / /I / / / / / / /I / / / / / /I / /

FOPFLG

device name (2 ASCII characters)

FOOEV

FOOEVN

3-348

MSB logged-in quota

<>0, unit no. real

device unit number

UFO cluster size (O=use pack cluster size)

FOCLUS

/ / /I / / / / / / /I / / / / / /I / /

FONENT

FIRQB+FQFIL

Zero means preextend one cluster. 1-7 means preextend specified
number of clusters.

FIRQB+FQSIZM

Flag byte. Bit 7 set means data passed in the FIRQB is in the
updated format. If bit 7 is clear, the data is in the VB.O format.
Other bits are reserved.

FIRQB+FQPPN

The device cluster number to place UFD. Minus one means place
UFD at the midpoint of the disk. If the cluster is not available,
the directive uses the next highest available cluster number.

FIRQB+FQNAM1

The PPN being created.

FIRQB+12

Optional password in RAD50 format, two words long. This is
provided for compatibility. Digital strongly recommends that you
use longer passwords for greater security. SpecifY zero here to
create a noninteractive account with no password. The account
can be made interactive later by setting a longer password using
UU.CHU.

FIRQB+FQSIZ

The logged-out quota in blocks.

.UUO-UU.PAS

FIRQB+FQFLAG+l

FIRQB+FQSIZ and the MSB are in FIRQB+FQFLAG+l. Use 377
in all three bytes for an unlimited quota. Zero in all three bytes
means no blocks can be allocated.

FIRQB+FQBUFL

The expirl'ltion dah~ in RSTS format: year - 70 + day of yl"ar.
Minus one means the account does not expire. This is the default.

FIRQB+FQMODE

The logged-in quota in blocks. The LSB are in

FIRQB+FQFLAG

FIRQB+FQMODE and the MSB are in FIRQB+FQFLAG. Use 377
in all three bytes for an unlimited quota. Zero in all three bytes
means no blocks can be allocated.

FIRQB+FQCLUS

The UFD cluster size. It must be greater than or equal to the
pack cluster size and a power of two from 1-16. Zero means the
account uses the pack cluster size.

Data Returned
FIRQB
Octal
Offset

Mnemonic

Octal
Offset
IIIIIIII IIII IIIIII II I

1111111111

job number * 2

Mnemonic

FQJOB

I I I I I I II I I I I I I II I I I I I

IIIIIIIIII II IIII IIIII

I I I I I I I I I I I I I I I I IIIII

IIIIIIIIIIIIIIIIIIIII

IIIIIIIIIII IIIII IIIII

I I I I I I I I I I I I I I I I IIIII

IIIIIIIIIII I IIIIIIIII

device cluster number for cluster 0 of UFO

FQMOOE

device cluster number for cluster 1 of UFO

FQFLAG

device cluster number for cluster 2 of UFO

FQPFLG

device cluster number for cluster 3 of UFO

FQOEV

device cluster number for cluster 4 of UFO

FQDEVN

device cluster number for cluster 5 of UFO

FQCLUS

device cluster number for cluster 6 of UFO

FQNENT

.UUO-UU.PAS

3-349

Data Passed (Pre-V9.0 Format)
FIRQB
Mnemonic

Octal
Offset

Octal
Offset
/ / II / / / / / / II / / / / / / / / /

FQSIZM

Mnemonic

UU.PAS (=0)

////11//11

flags

preextnd UFO clstrs

FQFIL

FQPPN

FQNAM1

device cluster number for UFO or -1

project number

programmer number

12
password (2 words in RA050 format)
14

15
17

number of blocks for quota; 0 = unlimited

FQSIZ

expiration date

FQBUFL

/ / / / / / / / / / II / / / / / / / / /

/ / II / / / / / / II / / / / / / / / /

device name (2 ASCII characters)

FQOEV

FQOEVN
FQCLUS

<>0. unit no. real

UFO cluster size (O=use pack cluster size)

/ / II / / / / / / II / / / / / / / / /

FIRQB+FQFIL

Zero means pre extend one cluster. 1-7 means pre extend specified
number of clusters.

FIRQB+FQSIZM

Flag byte. Bit 7 set means data passed in the FIRQB is in the
updated format. If bit 7 is clear, the data is in the VS.O format.
Other bits are reserved.

FIRQB+FQPPN

The device cluster number to place UFD. Minus one means place
UFD at the midpoint of the disk. If the cluster is not available,
the directive uses the next highest available cluster number.

FIRQB+FQNAMI

The PPN being created.

FIRQB+12

FIRQB+FQBUFL

The expiration date in RSTS format: year - 70 + day of year.
Minus one means the account does not expire. This is the default.

FIRQB+FQCLUS

The UFD cluster size. It must be greater than or equal to the
pack cluster size and a power of two from 1-16. Zero means the
account uses the pack cluster size.

Data Returned

Same as for the updated format.

3-350

device unit number

.UUO-UU.PAS

Errors
ABORT

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 if you get this
error, and include:
A copy of the disk.
A snap shot dump. (Use the DUMP/SYSTEM command to copy
the contents of memory to CRASH.SYS, then run the ANALYS
program to save the information. Submit a listing that contains
the ANALYS program's output.)
See the RSTS / E System Manager's Guide for more information on
ANALYS.
•
•

BADCLU

Cluster size is nonzero and is less than the pack cluster size.

BADCNT

The number of clusters specified at FIRQB+FQFIL:
•
•

Is out of range.
When added to the device cluster number specified at FIRQB+FQPPN
yields an effective address that is greater than the disk size. (See
Appendix B for disk size information.)

DEVNFS

Device is not a disk or the disk is open in non-file-structured mode.

FIEXST

Account specified already exists on device.

NOROOM

The monitor cannot allocate one cluster for the UFD you are creating
because the disk is full.

PRVIOL

PPN is [0,0], or either the project number or programmer number is
255.

.UUO-UU.PAS

3-351

3.36.34

UU.POK (Poke Memory)
Privileges Required

SYSMOD is required to write into kernel memory.
Data Passed
FIRQ8
Mnemonic

Octal
Offset

FQFUN

Octal
Offset

II / / / / / / II / / / / / II / / / /

UU.POK (= -6)

1111111111

Mnemonic

address of word to be changed

4 FQFIL

new contents of word

6 FQPPN

/ / / / / / / / II / / / / / II / / / /

II / / / / / / II / / / / / II / / / /

II / / / / / / / / / / / / / II / / / /

II / / / / / / II / / / / / II / / / /

II / / / / / I II / / I / / II / / / /

Data Returned

Except for a possible error in byte 0 of the FIRQB, the UU.POK subfunction does
not return any meaningful data.
Errors
PRVIOL

3-352

.UUO-UU.POK

The job executing the call does not have SYSMOD privilege or the address
specified is odd.

3.36.35

UU.PPN (Wildcard PPN lookup)
Privileges Required
DEVICE is required to perfonn a lookup on a restricted device.
Data Passed
FIRQ8
Mnemonic

Octal
Offset

Octal
Offset
I I I I I I I I I I I! I I I I I I I I I

FQFUN

Mnemonic

UU.PPN (=31)

1111 1111 I!

°2

index: n means search for n+ 1 occurrence

FQFIL

377 or proj. no.

FQPPN

377 or prog. no.

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

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

device name (2 ASCII chars)- must be disk

<>0, unit no. real

device unit number

FQOEV

32 FQOEVN

IIIIIIIIIIIIIIIIIIIII

I I I I I I I I I I I! I I I I I I I I I

FIRQB+FQFIL

The index. The directive returns the n+lth instance. If n is zero,
the directive returns the lowest PPN that matches the wildcard
specification; if n is one, it returns the next lowest, and so forth,
until there are no matching files.

FIRQB+FQPPN

377 represents a wildcard. Use 377 in both bytes to represent
any account, that is, [* ,*]. Use zero in both bytes to indicate the
current account, that is, [].

.UUO-UU.PPN

3-353

Data Returned
FIRQB
Mnemonic

Octal
Offset

5
7

Octal
Offset

/ II / / / / / II / / / / / / II / / /

111/1/1/1/

current job no .• 2

/ II / / / / / II / / / / / / 1/ / / /

project number

programmer number

Mnemonic

FQJOB

FQPPN

/ II / / / / / 1/ / / / / / / II / / /

/ II / / / / / 1/ / / / / / / /I / / /

/ /I / / / / / 1/ / / / / / / /I / / /

/ 1/ / / / / / 1/ / / / / / / /I / / /

////11//1///////1/11/

/ 1/ / / / / / 1/ / / / / / / 1/ / / /

/ II / / / / / II / / / / / / II / / /

/ II / / / / / II / / / / / / 1/ / / /

(same as data passed)

32 FQDEVN

/ 1/ / / / / / /I / / / / / / /I / / /

/ II / / / / / II / / / / / / II / / /

FQDEV

Errors

3-354

NOSUCH

Device is not a disk, or no match exists for the specified index.

PAKLCK

The disk is restricted and the caller does not have DEVICE privilege.

.UUO-UU.PPN

3.36.36

UU.PRI (Change Priority/Run Burst/Job Size)
Privileges Required

TUNE is required to change any job's priority, run burst, or size.
Data Passed
FIRQB
Octal
Offset

Octal
Offset

Mnemonic

I I /I I I I I I I /I I I I I I /I I I

Mnemonic

FQFUN

UU.PRI (= -15)

/1/1/1/1/1

FQSIZM

<>0, change priority

job no.;377 = caller

FQFIL

<>0, change burst

new run priority

FQPPN

<>0, change size

new run burst

FQNAM1

/1/1////1/

maximum size

11//1//1111/111111/11

I I /I I I I I I I 1/ I I I I I /I I I

I I 1/ I I I I I I 1/ I I I I I 1/ I I

111/1111111/111111/11

I I 1/ I I I I I I " I I I I I " I I

II" IIII II" IIIII" II

I I " I I I I I I " I I I I I 1/ I I

I I " I I I I I I /I I I I I I /I I I

111/1111111///1111/11

FIRQB+FQPPN

Run priority values range from -200 to 170 in steps of 10. The
value -200 suspends the job.

FIRQB+FQNAM1

The run burst should be a value from 1 to 177. If you use a value
outside this range, the monitor sets the run burst to 6.

FIRQB+FQNAM1+2

The maximum size can range from 1 to 377 (lK-word units), The
system uses SWAP MAX if you exceed that value.

Data Returned

Except for a possible error in byte 0 of the FIRQB, the UU.PRI subfunction does
not return any meaningful data.
Errors
BADFUO

The job number specified at FIRQB+FQFIL does not exist.

.UUO-UU.PRI

3-355

3.36.37

UU.PRV (Set/Clear/Read Current Privileges)
The UU.PRV directive lets you read the current privilege mask or selectively
set and/or clear bits in it. This function is distinct from the .SET or .CLEAR
directives, which apply only when running a privileged program and then update
the entire current mask at once.

Privileges Required
None

Data Passed
FIRQB
Mnemonic

FQFUN

Octal
Offset

Octal
Offset
111111111111111111111

UU.PRV (= 34)

1111111111

5
7

4
bits to be set in the
current privilege mask
(4 words)

111111111111111111111

3-356

20
bits to be cleared in the
current privilege mask
(4 words)

FQFIL

Mnemonic

FQNAM2

11/111111111111111111

111111111111111111111

FIRQB+FQFIL

The bits to be set in the current privilege mask. If you do not want
to set any privileges, use four words of zero. Before setting the
specified bits, the system performs an AND operation between the
bits the caller passes and the caller's authorized privilege mask
to prevent the caller from setting unauthorized bits. Note that
this applies even for temporary privileges. Thus, a temporarily
privileged program can use UU.PRV to drop any single privilege,
but it can regain only those that the caller is authorized to have.

FIRQB+FQNAM2

The bits to be cleared in the current privilege mask. If you do not
want to clear any privileges, use four words of zero.

.UUO-UU.PRV

NOTE

If all eight words are zero, no bits are set or cleared. Thus, the job's

privileges remain unchanged. This is the way to read your current
privileges.
Data Returned
FIROB
Octal MneOffset monic

Mne- Octal
monic Offset

/1/111/1/1111/1/11/11

/1/1/1/11/11/1/111/11

2
4 FOFIL

current privilege mask
(4 words)

1/111/11/1/1111/11111

1/1/11/11/111/11/1111

1111/1/111/1/1///11/1

/1/1/1////1//////1///

/1///1////1/////1////

//1/1/1/1//1//1/1////

/1/1/////////////1///

/1/1/1////1/////1//11

///1/1///1/1/////////

/11//1/////1/1///11/1

FIRQB+FQFIL

The bits set represent the privileges now in effect.

NOTE

A privileged program that wants to find out what privileges the user
has needs to do a drop temporary privileges function followed by a read
privileges function.
Conversely, a privileged program that wants to check whether the
program has the right privileges should issue the read privileges
function while temporary privileges are in effect.

.UUO-UU.PRV

3-357

3.36.38

UU.RAD (Read or Read-and-Reset Accounting Data)
Privileges Required

None required to read your own account. Set account access (GACNT or WACNT)
is required for all other accounts, or to reset accounting data.
Data Passed
FIROB
Mnemonic

Octal
Offset

Octal
Offset
IIIIIIIIIIIIIIIIIIIII

FOFUN

1/1/1/1/1/

0
2

index number of account

FOFIL

o = read; <>0 = read and reset

FOPPN
FONAM1

project number

programmer number

1/1/1/1/1/

flag

111/1/1/1/1/1/1111/1/

1111/1/1/1/1/11/1/1/1

111/11111/1/111111/11

1/1/111/1/1/1/111/111

1/1/1/1/11/1/1/111/11

111/111/1/1/111111/11

device name (disk) (2 ASCII characters)

FOOEV

FOOEVN

3-358

UU.RAO (= 16)

Mnemonic

<>0, unit no. real

device unit number

11/1/1/1/11/111111/1/

I I 1/ I I I I I I 1/ I I I I I I I I I

FIRQB+FQFIL

The index number of the account to read. If the index is zero, the
directive reads the account specified in bytes 7 and 8. If the index
is nonzero, the directives searches for an account based either on
this index entry or on a wildcard PPN search. The value of the
flag in FIRQB+FQNAM1+2 controls which function the directive
does.

FIRQB+FQPPN

The reset flag. If zero, the directive only reads accounting data.
If nonzero, the directive reads and resets accounting data. If the
caller does have account access privilege, the system performs a
read operation only.

FIRQB+FQNAM1

The programmer number. If this and the project number are zero,
the directive uses the current account. A -1 indicates a wildcard.

FIRQB+FQNAM1+1

The project number. If this and the programmer number are zero,
the directive uses the current account. A -1 indicates a wildcard.

.UUO-UU.RAD

FIRQB+FQNAM1+2

Flag byte.
Setting

Bit

Meaning

Clear

Implies the call returns the number of
blocks owned by the account.

Set

Implies do not return this data. Note that
setting this bit to one can save considerable
execution time (for Level 1.1 or older disk
structures) if you do not need the disk usage
information otherwise returned to the word
at FIRQB+FQPPN.

Clear

Means the PPN at FIRQB+FQNAM1 corresponds to a real account, if index value at
FIRQB+FQFIL is zero. If index value is not
zero, the system uses the index value and
ignores any PPN at FIRQB+FQNAM1.

Set

Means the PPN at FIRQB+FQNAMI contains a wildcard (377).

Clear

Means the call returns general accounting
information in the pre-V9.0 format.

Set

Means return disk quota information in the
updated format. Disk quota information is
not available in earlier formats.

Clear

Means the call is a read-only lookup on the
caller's own PPN if the caller does not have
GACNT or WACNT privileges.

Set

Means UU.RAD returns a protection violation error if a caller tries to perform
a restricted function without having the
required privileges.

.UUO-UU.RAD

3-359

Data Returned (Bit 2 Set in FIRQB+FQNAM1+2)
FIRQB
Mnemonic

Octal
Offset

Octal
Offset
111111111111111111111
1111111111

FQJOB
FQFIL

(same as data passed)

111111111111111111111

PPN of account read

LSB of logged-out quota

LSB of logged-in quota

14 FQEXT

MSB logged-out quota

MSB logged-in quota

MSB current usage

1111111111

FQNAM1

16 FQSIZ
20

FQBUFL

111111111111111111111

LSB of current usage

FQFLAG

count of open files and logged in jobs

FQPFLG

(same as data passed)

FQOEV

(same as data passed)

FQOEVN

111111111111111111111

FIRQB+FQPFLG

.UUO-UU.RAD

FQPROT 27

3-360

current job no .• 2

Mnemonic

Count of open files is in bits 0-9. The number of jobs is in bits
10-15.

Data Returned (Bit 2 Clear in FIRQB+FQNAM1+2)
FIRQB
Mnemonic

Octal
Offset

Octal
Offset
I I II I I I I I I I I I I I I I I I I I

1111111111

curren! job no .• 2

Mnemonic

FQJOB

4 FQFIL

(same as data passed)

number of blocks owned by account read

FQPPN

PPN of account read

FQNAM1

password of account read (2 words in
RA050 format) or zeros

FQEXT

LSB of CPU time (.1 seconds)

FQSIZ

connect time (minutes)

FQBUFL

LSB of KCTs

device time (minutes)

FQFLAG

FQPFLG

MSB of CPU time

FQPROT 27

MSB of KCTs

(same as data passed)

FQOEV

(same as data passed)

FQOEVN

disk quota in blocks; 0 = unlimited

UFO cluster size

FIRQB+FQPPN

If the byte at FIRQB+FQNAM1+2 in the data passed is 1, this
word is zero.

FIRQB+FQNAM1+2

If the caller has GACNT or WACNT privilege and the account
allows password look-up, the password is returned as 2 words
of RAD50. Otherwise, zeros are returned.

FIRQB+FQSIZ

The LSB of the CPU time in tenths of a second. See the byte
at FIRQB+FQPROT for the MSB.

FIRQB+FQMODE

The LSB of the Kilo-Core-Ticks (KCTs). See the byte at
FIRQB+FQPFLG for the MSB.

Errors
BADDIR

The account does not have all the necessary directory structures.

BADFUO

Device specified is not a disk.

NOSUCH

The PPN specified does not exist on the disk, or the index specified is greater
than the number of accounts on the disk.

PRVIOL

The caller does not have sufficient privilege to perform the indicated function.

.UUO-UU.RAD

3-361

3.36.39

UU.RTS (Add/Remove/Run-Time System or Resident Library, or
Create Dynamic Region)
Privileges Required

Read access (by protection code, GREAD, WREAD, and/or SYSIO privilege) is
required to install a run-time system or resident library. INSTALL is required to
install, remove, load, or unload a run-time system or resident library, or create a
dynamic region.
Data Passed-Add a Run-Time System
FIROB
Mnemonic

Octal
Offset

Octal
Offset
1/1/1/1/111//1111/11/

FOFUN

UU.RTS (= -22)

1/1///////

1/1/1/1/1/

flag

FOFIL

project number

programmer number

FOPPN
FONAM1

run-time system name

(2 words of RAD50)

start load address or zero

FOEXT

max. user job image size, K words (P.SIZE)

FOSIZ

min. user job image size, K words (P.MSIZ)

FOBUFL

FOMODE

flag word (P.FLAG)

FOFLAG

dflt. exec. file type (P. D EXT), RAD50

FOPFLG

device name (disk) where stored

FODEV

FODEVN

FOPROT 27
31
33

linked-list position

stay flag

3-362

Mnemonic

<>0, unit no. real

device unit number

1///11/111/////111///

11/////1/11/11111//11

FIRQB+FQFIL

All bits clear implies the values for P.SIZE, P.MSIZ, P.FLAG,
and P.DEXT symbols are in the call. Bit 7 set means the system
should obtain the values for these symbols from the .RTS file.

FIRQB+FQPPN

The programmer number of the run-time system to install.

FIRQB+FQFQPPN+1

The project number of the run-time system to install. If this and
FQPPN are both zero, the default PPN is [0,1]

FIRQB+FQNAMI

The file name ofthe run-time system to install, in RAD50 format.
The file extension must be ".RTS" and the file must be contiguous.

.UUO-UU.RTS

FIRQB+FQEXT

The 1K word section of memory where the run-time sustem will be
loaded. The numbering runs from 0 to n-1, where n is the number
of 1K word sections of memory in the system.
If t.he value i~ 0, the monitor picks the load address each time
the run-time system is loaded from the disk. (If the /LOCK or
/NOREAD_ONLY bits are set, the monitor picks the load address
once, as for the value -1.)
If the value is -1, the monitor picks the load address once, when
the run-time system is first installed, and loads it at that address
each time it is used.
The monitor takes other values as the specific address to load the
run-time system this time.

FIRQB+FQMODE

The position in the linked list of run-time system description
blocks at which to place the description block for this run-time
system.
If the value is 1, the directive places the description block immediately after that of the primary RTS.
If the value is nonzero and less than or equal to the number of
blocks currently in the list, the call places this new block in that
position following the primary RTS block.
If the value is zero 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.

FIRQB+FQMODE+1

All bits clear means the memory occupied by this run-time system
can be released when usage count goes to zero. Bit 7 set means
the run-time system is permanently resident and is loaded in
memory as part of the install.

FIRQB+FQPFLG

The default extension type for the run-time system to be installed,
in RAD50 format.

FIRQB+FQDEV

The name of the device (must be a disk) where the run-time
system is stored. If you do not specify a name, the default is SY:.

FIRQB+FQDEVN

The unit number of the disk where the run-time system is stored.

Data Returned

Except for a possible error in byte 0 of the FIRQB, the UU.RTS subfunction does
not return any meaningful data.

Errors
BADCNT

The range of memory starting at the load address at FIRQB+FQEXT is not
available. See the output of the SHOW MEMORY command to select an
available range of memory.

DEVNFS

The device was not a disk, or the disk was mounted NFS.

DTOOOF

The systemwide limit of open files has been reached.

FIEXST

A run-time system with the same name already exists.

NOBUFS

Adding a run-time system description block requires a small buffer and none
is currently available.

NOROOM

If loaded at address specified, memory is fragmented and a swapping
violation occurs. 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.

NOSUCH

No file with the name given and a type of .RTS can be found in the account
at FIRQB+FQPPN on the device specified.

.UUO-UU.RTS

3-363

The file to be added has a bad format. For example, it is not contiguous or
has illegal entries in the SIL index.

PRVIOL

Data Passed-Remove a Run-Time System
FIRQB
Mnemonic

Octal
Offset

/ / /I / / / / / / 1/ / / / / / 1/ / /
FQFUN

Mnemonic

UU.RTS (= -22)

/1///1/1/1

1/1/1///1/

subfunction code =4

/ / /I / / / / / / /I / / / / / /I / /

run-time system name

(2 words of RAD50)

/ / /I / / / / / / /I / / / / / /I / /

/ / /I / / / / / / 1/ / / / / / /I / /

/ / /I / / / / / / /I / / / / / /I / /

FQFIL

FQNAM1

Data Returned
Except for a possible error in byte 0 of the FIRQB, the UU.RTS subfunction does
not return any meaningful data.

Errors

3-364

INUSE

This run-time system is currently being loaded into memory or is resident
and in use. It cannot be removed until the usage count is zero.

NOSUCH

The run-time system is not currently defined.

PRVIOL

The run-time system is the primary run-time system or the system default
keyboard monitor and cannot be removed with this call. Use the DEFAULT
initialization option to change the primary run-time system before starting
timesharing. The system default keyboard monitor is always DCL.

.UUO-UU.RTS

Data Passed-Unload a Run-Time System
FIR08
Mnemonic

Octal
Offset

Octal
Offset
/ / /I / / / / / / /I / / / / / /I / /

FOFUN

Mnemonic

UU.RTS (= -22)

/1///////1

/////////1

subfunction code =6

/ / /I / / / / / / / / / / / / / / / / /

run-time system name

(2 words of RAD50)

/ / /I / / / / / / /I / / / / / / / / /

/ / /I / / / / / / II / / / / / /I / /

/ / /I / / / / / / /I / / / / / / / / /

/ / /I / / / / / / // / / / / / / / / /

/ / /I / / / / / / /I / / / / / / / / /

/ / /I / / / / / / / / / / / / / / / / /

/ / /I / / / / / / /I / / / / / / / / /

/ / /I / / / / / / / / / / / / / // / /

/ / / / / / / / / / / / / / / / / II / /

FOFIL

FONAM1

Data Returned
Except for a possible error in byte 0 of the FIRQB, the UU.RTS subfunction does
not return any meaningful data.

Errors
INUSE

The run-time system is currently being loaded or is resident and in use. It
cannot be unloaded until usage count is zero.

NOSUCH

The run-time system is not currently defined.

.UUO-UU.RTS

3-365

Data Passed-Add a Resident library
FIRQ8
Mnemonic

Octal
Offset

Octal
Offset
I I 1/ I I I I I I 1/ I I I I I 1/ I I

FQFUN

UU.RTS (= -22)

11/1111111

1111111111

subfunction code=20

FQFIL

project number

programmer number

FQPPN
FONAM1

run-time system name

(2 words of RAD50)

start load address or zero

I I 1/ I I I I I I 1/ I I I I I 1/ I I

I I 1/ I I I I I I I I I I I I I I I I I

stay flag

25
FQPROT 27

111/111111

flag word
protection code

3-366

Mnemonic

<>0, prot.code real

device name (disk) where stored
<>0, unit no. real

device unit number

FQEXT

FOMODE

FOFLAG

FOPFLG

FOOEV

FODEVN

I I 1/ I I I I I I 1/ I I I I I I I I I

I I I I I I I I I I 1/ I I I I I 1/ I I

FIRQB+FQPPN

The programmer number of the resident library to install.

FIRQB+FQFQPPN+1

The project number of the resident library to install. If this and
FQPPN are both zero, the default PPN is [0,1]

FIRQB+FQNAM1

The file name of the resident library to install, in RAD50 format.
The file extension must be ".LIB" and the file must be contiguous.

.UUO-UU.RTS

FIRQB+FQEX.T

The lK word section of memory where the resident library will
be loaded. The numbering begins at the first available lK word
section and ends at n-l, where n is the total number of lK word
sections of memory in the system.
If the value is 0, the monitor picks the load address each time
the resident library is loaded from the disk. The monitor picks
the highest available address. Libraries of this kind are called
small floating libraries. They must be entirely mapped within the
virtual address space. They are provided for compatibility with
older programs. This value is equivalent to the DCL qualifier
INOADDRESS=RESTRICTED.
If the value is -1, the monitor picks the load address once, when
the run-time system is first installed, and loads it at that address
each time it is used. The monitor picks the highest available
address. This value is equivalent to the DCL qualifier IADDRESS.
If the value is -2, the monitor picks a new load address each
time the library is loaded. Libraries of this kind are called
large floating libraries and can be larger than the virtual address space. This value is equivalent to the DCL qualifers
INOADDRESS=UNRESTRICTED or INOADDRESS.
The monitor takes other values as the specific address to load the
resident library specified. Libraries of this kind are called fixed
resident libraries. These values are equivalent to the DCL qualifer
IADDRESS=n.
If the value is 0 or -2 and the ISTAY or read/write bits are set, the
monitor picks the load address once, as for the value -l.

FIRQB+FQMODE+l

All bits clear means the resident library can be removed from
memory when usage count goes to zero. Bit 7 set means the resident library is permanently resident and is loaded into memory as
part of the install process.

FIRQB+FQFLAG

Bit settings indicate resident library characteristics:
Bit
Setting
Meaning
9

10
12

Set

The resident library is to be accessed by
only one user. That is, the library is not to
be shared.

Clear

The resident library can be shared by more
than one user.

Set

Read/write access is allowed.

Clear

Read-only access.

Set

Errors occurring within code in the resident
library are not to be recorded in the system
error log.

Clear

Errors may be recorded in the system error
log.

Set

The resident library is immediately removed
from memory when its usage count goes to
zero.

Clear

When the usage count for this library goes
to zero, the monitor will remove it from
memory when the space it takes is needed
for something else.
All other bits are reserved and should be zero.
FIRQB+FQPROT

The protection code. If no code is specified, the default is 42 .

.UUO-UU.RTS

3-367

Data Returned

Except for a possible error in byte 0 of the FIRQB, the UU.RTS subfunction does
not return any meaningful data.

Errors
BADCNT

You did not specifY a load address, or the one specified is not available. See
the output of the SHOW MEMORY command to find an available range of
memory.

DEVNFS

The device was not a disk, or the disk was mounted NFS.

DTOOOF

The systemwide limit of open files has been reached.

FIEXST

A resident library with the specified name already exists.

NOBUFS

Adding a resident library description block requires a small buffer and none
is currently available.

NO ROOM

NOSUCH

No file with the name given and a type of .LIB can be found for the given
account and device.

PRVIOL

The file to be added has a bad format. For example, it is not contiguous or
has illegal entries in the SIL index.

Data Passed-Remove a Resident Library
FIRQ8
Mnemonic

Octal

Octal
Offset

Offset
I I I I I I I I I I I! I I I I I I I I I

FQFUN

3-368

.UUO-UU.RTS

Mnemonic

UU.RTS (= -22)

II II II II I!

II!IIIIIII

subfunction code=24

I I I! I I I I I I I I I I I I I I I I I

resident library name

(2 words of RAD50)

I I II I I I I I I II I I I I I II / /

I I II I I I I I I II I I I I I I I I I

I I II I I I I I I I I I I I I I I I I I

I I II I I I I I / II I I I I I II I I

I I II I I I I / I II / I / I / / I I I

I / II / / / I / / II I I I / I II / I

/ / II / / / / / / / I / I I / / II I /

/ / II / / / / I / I / I I / / / II / /

/ I II I I / I / I I I I I I / I II / I

IIIIIIIIIIIIIIIIIIIII

FQFIL

FQNAM1

Data Returned

Except for a possible error in byte 0 of the FIRQB, the UU.RTS subfunction does
not return any meaningful data.
Errors
lNUSE

You tried to remove a library that is being loaded into memory or is in use.
A resident library cannot be removed while a job is attached to it.

NOSUCH

You specified a resident library that is not currently defined.

Data Passed-Unload a Resident library
FIROB
Mnemonic

Octal
Offset

Octal
Offset
I I I I I I I I I I I I I I I I I /I I I

FOFUN

Mnemonic

UU.RTS (= -22)

1/1/11/1/1

1/1/1/11/1

subfunc!ion code=26

I I I I I I I I I I /I I I I I I /I I I

resident library name

(2 words of RAD50)

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

IIIIIIIIIIIIIIIIIIIII

I I I I I I I I I I /I I I I I I 1/ 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 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 I I 1/ I I I I I 1/ 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 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 I I I I I I I I /I I I

FOFIL

FONAM1

Data Returned

Except for a possible error in byte 0 of the FIRQB, the UU.RTS subfunction does
not return any meaningful data.
Errors
lNUSE

You tried to unload a resident library that is now being loaded or is in use.
A library cannot be unloaded while a job is still attached to it.

NOSUCH

You specified a resident library that is not currently defined.

.UU~UU.RTS

3-369

Data Passed-Create Dynamic Region
FIRQ8
Mnemonic

Octal
Offset

Octal
Offset
/ / 1/ / / / / / / 1/ / / / / / / / / /

FQFUN

Mnemonic

UU.RTS (= -22)

1/1/111/1/

1/1/1/1/1/

subfunction code=30

FQFIL

/ / 1/ / / / / / / 1/ / / / / / 1/ / /

dynamic region name

(2 words of RAD50)

start dynamic region address

FQEXT

FQSIZ

dynamic region size

1111111111

FQNAM1

/ / 1/ / / / / / / 1/ / / / / / 1/ / /

creation flags

FQMODE

region flags

FQFLAG

FQPFLG

FQPROT 27

protection code

protection code flag

///////// /// / //// ////

/ / 1/ / / / / / / 1/ / / / / / / / / /

/ / 1/ / / / / / / / / / / / / / 1/ / /

FIRQB+FQNAMI

If zero, the monitor creates an unnamed dynamic region.

FIRQB+FQEXT

The starting address of the dynamic region is K times the value of
this word. If zero, the monitor computes the starting address for
the dynamic region.

FIRQB+FQSIZ

3-370

.UUO-UU.RTS

Bits

Meaning

0--7

Size region requested (maximum of 255) in K words of
memory.

Set to 1 if the directive can accept a smaller size region
than requested when not enough memory exists. Set to
o if the directive should return an error when there is
not enough memory to satisfy the request.

Set to 1 to use bits 0--7 for size. Set to 0 to use only
bits 0-6 for size.

FIRQB+FQMODE

Creation flags. The following bits are currently defined: Bit 7,
when set, means attach this job to the named region. Bit 15,
when set, means do not delete this region even if all users detach
from it; this is the fLOCK bit. All other bits are reserved and
should be zero.
You can create a dynamic region with or without a name.
However, if the job shares the dynamic region with another job,
or if the dynamic region was created with bit 15 of FQMODE
set so that it remains in memory, it must have a name in
FIRQB+FQNAMI.
Unless you have the TUNE privilege, the size of the region is
controlled by the dynamic region limit set for the system. See the
UU.CFG directive and the RSTS/E System Manager's Guide.

FIRQB+FQFLAG

Region flags. The following bit is currently defined: Bit 9, when
set, means this region cannot be shared. All other bits are reserved and should be zero.

FIRQB+FQPFLG

If nonzero, then the value in FIRQB+FQPROT is real.

FIRQB+FQPROT

The protection code of the region.

Data Returned-Create Dynamic Region
FIROB
Mnemonic

Octal
Offset

Octal
Offset
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 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 I I I I I I

dynamic region 10

I I I I I /I I I I I I /I I I I I I I I

/1/1111111

dynamic region size

Mnemonic

FOPPN

16 FOSIZ

11111/111111/11/11111

I I I I I /I I I I I I /I I I I I I I I

FIRQB+FQPPN

The ID of the created dynamic region. The .PLAS directives use
this ID.

FIRQB+FQSIZ

The size of the created dynamic region in K words. The value can
be in the range 1 to 255.

.UUO-UU.RTS

3-371

Errors
BADCNT

You tried to create a region with an illegal size specification or the load
address was not valid.

FIEXST

You specified the name of a dynamic region or resident library that already
exists.

NOBUFS

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.

NOROOM

If the dynamic region was loaded at the specified address, memory is
fragmented and a swapping violation occurs. If the monitor was choosing
the address, there is not enough free memory to create the region.

Data Passed (Create/Delete Virtual Disk)
FIR08
Mnemonic

Octal
Offset

Octal
Offset
1/111111/111111/11111

3-372

FOFUN 3

UU.RTS (= -22)

1/1/1/1/1/

subfunction code=32

Mnemonic

0
2
4 FOFIL

dynamic region ID

6 FOPPN

I I I I I I I 1/ I I 1/ I 1/ I I I I I

11111111/111/11/11111

Start Virtual Disk Address

14 FOEXT

Virtual disk size in K words

16 FOSIZ

I I I I I I I 1/ I I I I I 1/ I I I I I

I I I I I 1/ 1/ I I I I I 1/ I I I I I

I I I I I I I 1/ I 1/ I 1/ I I I I I I

11/11111/11111/111111

I I 1/ I I I 1/ I I I I I 1/ I I I I I

I I I 1/ I I 1/ I I I I I 1/ I I I I I

I I I I I I I 1/ I I I I I 1/ I I I I I

FIRQB+FQFUN

-22 (UU.RTS)

FIRQB+FQFIL

32 (Create/delete virtual disk)

FIRQB+FQEXT

K word address at which to place the virtual disk (from 0 to 2043),
or -1 to let RSTSIE select the best-fit address.

FIRQB+FQSIZ

Size of virtual disk to create, in K words (from 1 to 2044), or 0
to delete the current virtual disk. If you specify 0, the address
parameter in FQEXT is ignored.

.UUO-UU.RTS

Discussion

This call allocates memory for the virtual disk. Any memory so allocated is
not available for other use, nor can it be windowed or mapped using the .PLAS
directives. When the virtual disk is deleted, the memory is then made available
for ot.her uses.
When t.he monitor receives a request to create a virtual disk, the memory manager must sometimes "shuffle" things in memory (such as jobs and run-time
systems) to make enough contiguous memory space for it. This task may take
some time, particularly on very busy systems. Before the virtual disk driver
allows the first access to the newly-created virtual disk, it ensures that all the
memory that is supposed to be available for the virtual disk has really been allocated. If not, then the virtual disk driver returns a ?Device hung or write locked
error to the job requesting the access. If this happens, the requesting job should
sleep for a few seconds and then retry the operation, thus giving the memory
manager time to do its job.
When a virtual disk is created, it is not automatically initialized as a RSTS/E volume. As in the past, you must still initialize it (using the INITIALIZE command)
and mount it (using the MOUNT command) if necessary.
You must have HWCFG and INSTALL privileges to create or delete the virtual
disk.
Data Returned

Except for a possible error in byte 0 of the FIRQB, this subfunction does not
return any meaningful data.
Errors

When creating:
PRVIOL

User or program did not have the HWCFG privilege.

NOROOM

There was not enough contiguous memory available to create the
virtual disk at the requested size.

BADCNT

The specified size or address was invalid, or, if an address was
given, the virtual disk would not fit at that address.

NOBUFS

Not enough small buffers were available to build the memory
descriptor blocks.

FIEXST

A virtual disk already exists.

When deleting:
PRVIOL

User or program did not have the HWCFG privilege.

lNUSE

The virtual disk is mounted, has open files, or is open in non-filestructured mode.

NODEVC

There is no virtual disk to delete.

.UUO-UU.RTS

3-373

3.36.40

UU.SlN (System logical Names)
Privileges Required

INSTAL is required to add, remove, or change system logical names.
Data Passed -

Add New Name
FIRQB

Mnemonic

Octal
Offset

Octal
Offset
I I I I I I 1/ I I I I I I 1/ I I I I I

FQFUN

UU.SLN (= 25)

1/1/11/1/1

FQFIL+1 5

no-replace flag

subfunction code= 4

PPN for this name (if 0, none associated)

logical name in RAD50 formal
(5 words)

2
4 FQFIL
6 FQPPN

I I I I I I 1/ 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 /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 I

device name (2 ASCII characters)

must <>0

device unit number

30 FQDEV
32 FQDEVN

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

FIRQB+FQFIL

This code adds a new entry to the list of system logical names.

FIRQB+FQFIL+ 1

Set to 1 to replace an existing system logical with the new information.

FIRQB+FQNAM1

The new logical name, put on the general or disk logical list
according to the following conditions (checked in order by the
system):
1.
2.
3.
4.

3-374

10 FQNAM1

11
13

Mnemonic

.UUO-UU.SLN

If the device name specified at FIRQB+FQDEV is not a disk.
If the device name is a disk and you specified a PPN at
FIRQB+FQPPN.
If the logical name is longer than nine characters.
If the device name is a disk and you did not specify a PPN
at FIRQB+FQPPN, the system checks to see if the disk is
mounted. If the disk is not mounted, the system adds the
logical name to the general logical list. If the disk is mounted
and currently has no logical name assigned to it, the name is
put on the disk logical list and assigned to that disk. All other
cases are put on the general logical list.

Data Returned
Except for a possible error in byte 0 of the FIRQB, the UU.SLN subfunction does
not return any meaningful data.

Errors
BADNAM

No logical name was given or the name contains invalid characters.

lNUSE

The logical name given duplicates one already in use and FIRQB+FQFIL =

NOBUFS

An attempt was made to extend the logical name table and there was no
room in XBUF.

NODEVC

The device specification is illegal or is not on the system.

Data Passed - Remove Logical Name
FIROB
Mnemonic

Octal
Offset

111111111111111111111
FOFUN

UU.SLN (= 25)

1111111111

subfunction code= 0

I I I I I I II I I I I I I II I I I I I

Mnemonic

0
2
4 FOFIL
6
10 FONAM1

11
13

logical name in RAD50 format

(5 words)

111111111111111111111

I I I I I I II I I I I I I III I I I I

111111111111111111111

I I I I II II I I I I I I II I I I I I

111111111111111111111

Data Returned
Except for a possible error in byte 0 of the FIRQB, the UU.SLN subfunction does
not return any meaningful data.

Errors
BADNAM

No logical name was given or the name contains invalid characters.

NOSUCH

The name given is not currently defined as a logical name.

.UUO-UU.SLN 3-375

Data Passed - Change Disk Logical Name
FIROB
Mnemonic

Octal MneOffset monic

Octal
Offset

11111111//11//11/////
FOFUN

UU.SLN (= 25)

111111111/

1/1111111/

subfunction code

/////////////////////

2
1

4 FOFIL
6
10 FONAM1

11
13

logical name in RA050 format

(5 words)

1111/11111111/11///11

1111//111111111//11//

1111111///////1///11/

device name (2 ASCII characters)

must <>0

device unit number

30 FOOEV
32 FOOEVN

////11111111/11////11

11//111///111111/////

FIRQB+FQFIL

This code changes the logical name associated with a disk in the
list of disk logical names.

FIRQB+FQNAMI

The disk logical name in RAD50 format. The name can not be
more than nine characters.

Data Returned
Except for a possible error in byte 0 of the FIRQB, the UU.SLN subfunction does
not return any meaningful data.

Errors
BADNAM
lNUSE
NOSUCH
NODEVC

3-376 .UUO-UU.SLN

No logical name was given, or the name contains invalid characters.
The logical name given duplicates one already in use.
The disk specified is not on the system.
The device specified is illegally formatted or is not a disk.

Data Passed -

List Logical Name
FIR08

Mnemonic

Octal
Offset

Octal
Offset
/1//////1//1////1////

FOFUN

UU.SLN (= 25)

1//1/1/1//

1/1/1//1//

subfunction code= 2

0
2
4 FOFIL

index

1/ / / / / / / 1/ / / / / / / 1/ / / /

/1////1/1//1////1////

/ 1/ / / / / / 1/ / / / / / / 1/ / / /

1/////1/1/1/////1////

/1//////1//1////1////

/I//////lil/////I////

/1//////1///111/1////

/1///////1/1////1////

/1///////1//1///1////

/1///1//1///1/1/1////

/1////1/1///////1////

/1///1//1//1////1/1//

FIRQB+FQPPN

Mnemonic

6 FOPPN

Index. An integer representing the relative position of the specified logical name in the list of system logical names. You can list
all logicals by repeated calls with an index value starting at zero
and incremented by one each time.

.UUO-UU.SLN

3-377

Data Returned
FIRQ8
Mnemonic

Octal
Offset

Octal MneOffset monic

111111111111111111111

project number

programmer number

10 FQNAM1

11
13

logical name in RAD50 format

(5 words)

111111111111111111111

device name (2 ASCII characters)

must <>0

device unit number

32 FQDEVN

1111111111

mount flag

34 FQCLUS

111111111111111111111

FIRQB+FQCLUS

3-378

.UUO-UU.SLN

30 FQDEV

The value of this byte is 377 if the indexed logical is a disk and
the disk is not mounted.

Errors
NOSUCH

6 FQPPN

Index out of range.

3.36.41

UU.SPl (Spooling)
RSTS/E currently has two spooling packages: the PrintlBatch Services (PBS)
package and the OPSER-based package. When you execute the UU.SPL directive,
the system first looks at the spooled device name field (FIRQB+FQSIZ). The
monitor, by default, routes the request to PBS if it is running and the field is nun
or LP, or it is BA and the file type is .COM. Otherwise, the monitor routes the
request to the OPSER-based package.
Note that by setting a bit in FQFLAG, you can force the request to be sent to
whichever spooling package you want.
For requests routed to PBS, any request parameter that cannot be passed by
UU.SPL is assigned a default value.
Privileges Required
File read access (by protection code, or GREAD or WREAD privilege) is required
to queue a file. File write access (by protection code, or GWRITE or WWRITE
privilege) is also required to queue a file with the delete option flag. DEVICE
privilege is required if the file is on a restricted device.
Data Passed
FIRQ8
Mnemonic

FQFUN

Octal
Offset

3
5
7

Octal
Offset
I I /I I I I I I I /I I I I I I I I I I

UU.SPL (= -34)

/////////1

Mnemonic

I I /I I I I I I I /I I I I I I I I I I

FQPPN

FQNAM1

project number

programmer number

wildcard file name in RAD50 format
(2 words)

13
15

wildcard file type in RAD50 format (1 word)

FQEXT

device name to queue to (ASCII); 0 = "LPO"

FQSIZ

FQ8UFL

device unit real flag

device unit number

I I /I I I I I I I /I I I I I I I I I I

FQMOOE

flag word

FQFLAG

I I /I I I I I I I I I I I I I I I I I I

device name where file is (disk)

FQOEV

FQDEVN

<>0, unit number real

device unit number

IIIIIIIIIIIII III1I11I

I I /I I I I I I I I I I I I I I I I I I

FIRQB+FQSIZ

The requested device name. Permitted values are LP, BA, and
zero which translates to "LPO:."

.UUO--UU.SPL

3-379

FIRQB+FQBUFL

The device unit real flag. If zero, it means use the default print
or batch queue. If nonzero, it means use the queue with the same
name as the device name.

FIRQB+FQFLAG

You can set the following bits for PBS:
Bit
Meaning When Set
2

Delete after spooling; same as DCL command PRINT
!DELETE.

No header; same as DCL command PRINTINOFLAG_
PAGES. (Ignore for batch requests.)

Network Print/Batch request

Route request to OPSER spooler

Route request to PBS

If both bits 13 and 14 are set, then the request is routed to PBS.
If both bits are clear, then the following rules apply:
If the spooler device name is "LP" or null, or the device name
is "BA" and the file type is .COM, then the request is routed
to PBS if it is running; otherwise, it is routed to OPSER.
• If the spooler device name is not "LP" or null, then the request
is routed to OPSER.
You can set the following bits for OPSER:
Bit
Meaning When Set
•

The file is spooled with FORTRAN carriage control; same
effect as QUEtrYP:FTN.

Restart file; same effect as QUEIRE.

Delete file after spooling; same effect as QUE!DE.

Binary file; same effect as QUEIBI.

The end; same effect as QUEIEND.

No header; same effect as QUEINH.

Data Retu rned

Except for a possible error in byte 0 of the FIRQB, the UU.SPL subfunction does
not return any meaningful data.

Errors

3-380

DEVNFS

The device specified at FIRQB+FQDEV of the call is not a file-structured
device.

HNGDEV

This error is caused by a hardware condition. For example, the specified
disk could not be accessed.

NOBUFS

System buffers are not currently available to store this message. This may
be a transient condition; retry the operation.

NODEVC

An attempt was made to queue a file to a device that had a unit number
greater than seven, or the file to be queued is on an invalid device.

NOROOM

The number of messages pending for the queue manager program is at its
declared maximum. This may be a transient condition; retry the operation.

NOSUCH

The account specified at FIRQB+FQPPN does not exist on the device specified, the file name or type specified at FIRQB+FQNAM1 cannot be found.

.UU~U.SPL

NOTMNT

The specified disk device is not mounted.

PAKLCK

The specified disk is restricted, and the caller does not have DEVICE
privilege.

PRVIOL

An attempt was made to queue a file to which the user did not have read
access or to queue an executable file.

.UUO-UU.SPL

3-381

3.36.42

UU.STL (Stali/Unstall System)
Privileges Required
HWCTL is required to stall or unstall a system.

Data Passed
FIROB
Mnemonic

Octal
Offset

111111111111111111111

FOFUN 3

UU.STL (= 35)

1111111111

o or 1

0
2
4 FOFIL

111111111111111111111

FIRQB+FQFIL

Mnemonic

Zero means return the system to normal (unstalled) state. One
means Stall; suspend all currently active jobs except for the calling
job.

Data Returned
Except for a possible error in byte 0 of the FIRQB, the UU.STL subfunction does
not return any meaningful data.

Errors

3-382

BADFUO

You specified unstall, but the system is not stalled.

lNUSE

You tried to stall the system, but it is already stalled.

.UUO-UU.STL

3.36.43

UU.SWP (Add, Remove, and List System Files)
Privileges Required

INSTAL is required to add or remove system files. File read access (by protection
code, or GREAD or WREAD privilege) and file write access (by protection code,
or GWRITE, WWRITE, and/or SYSIO privilege) is required to add system files.
WRTNFS is required to add non-file-structured swap space.
Data Passed -

Add System File
FIROB

Mnemonic

Octal
Offset

""""""'"'1"1'

Mnemonic

FOFUN

UU.SWP (= 27)

1111111111

FQSIZM

= 1 for add

file to add

FQFIL

, , II , , , , , , II , , , , , II , ,

for [0,1] file with type of .SYS,
file name as 2 words RAD50. If both
words = 0, non-file-structured disk.

""""""'1"'""

, , II , I , , , , 1/ , , , , , II , ,

, , II , , , , , , " , , , , , " , ,

, , II , , , , , , II , , , , , " , ,

, , II , , , , , , II , , , , , 1/ , ,

, , II , , , , , , II , , , I , II , ,

device name (disk) (2 ASCII characters)

FODEV

FODEVN

13
15
17

<>0, unit number real

device unit number

, , II , , , , , , II , , , , , II , ,

I , II , , , , , , II , , I , , II , ,

FIRQB+FQFIL

FONAM1

The possible bit settings are:
Bit
Meaning

Swap file 0

Swap file 1

Illegal (generates an error; slot 2 is always added)

Swap file 3

Overlay file

Error message file

Data Returned

Except for a possible error in byte 0 of the FIRQB, the add option of the UU.SWP
subfunction does not return any meaningful data.

.uuo-uu.swP

3-383

Errors

3-384

BADFUO

The number specified at FIRQB+FQFIL is either two or is greater than six.
The swap 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, and 5.

BADNAM

No file name is specified when an overlay, an error message, or a DECnetiE
system file is being added, or the name specified contains nonalphanumeric
characters.

DEVNFS

The device specified is not a disk device.

FIEXST

The system file being added is already installed on the system.

INUSE

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

NODEVC

The device specified is a disk but is not on this system.

NOROOM

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 filestructured device, this error means that the file is not long enough to store
even one job.

NOSUCH

A system file is being added to a file-structured disk, but the file with the
name specified and with a .SYS file type does not exist in account [0,1].

NOTAVL

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.

NOTMNT

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.

PRVIOL

A system file is being added to a file-structured disk. Either the unit is
logically write locked, or the file specified is bad; that is, it is not contiguous
or is currently open.

.UU~U.SWP

Data Passed -

Remove System File
FIROB
Mnemonic

Octal
Offset

Octal
Offset
////1///1///1////1/1/

FIRQB+FQFIL

UU.SWP (= 27)

1/1//1/1//

FOSIZM 5

= 0 for remove

file to remove

FOFUN

Mnemonic

////1//1///1///////1/

////1///1/1/1//////1/

////1//1////1/////1//

/ / / / 1/ / / / / / / 1/ / / / / / 1/

////1/////1/1/////1//

/ / / / 1/ / / / / / / 1/ / / / / / 1/

////1/1/////1//////1/

/ / / / 1/ / / / / / / 1/ / / / / / 1/

/ / / / 1/ / / / / / / 1/ / / / / 1/ /

////1/1/1///1/1///1//

/ / / / 1/ / / / / / / 1/ / / / / / /I

/////1///////1//////1

FOFIL

The possible bit settings are:
Bit
Meaning

Swap file 0

Swap file 1

illegal (generates an error; slot 2 is never removed)

Swap file 3

Overlay file

Error message file

.uuo-uu.swp

3-385

Data Returned
FIR08
Mnemonic

Octal
Offset

Octal MneOffset monic
error code or 0

""11"""11""'"

""""""""""'
"""""""""'"
"'"'"'"'"""'"

7
11

6
10

, , , , II , , , , , , II , , , , , II

"""""""""'"
""""""""""'
"'"""'""""'"

, , , , II , , , , , , II , , , , , II

"""""""11"'"
""11""""""'"

33
35

o or-1

"""""""""'"

32
34 FOCLUS

FIRQB_O

Error code or zero.

FIRQB+FQCLUS

Zero means the system file was successfully removed; minus one
means the system file was not found and so could not be removed.
(If bit 4 1, the overlay file is removed.)

Errors

3-386

BADFUO

The number specified at FIRQB+FQFIL is either two or greater than six.
The swap file 2 must exist on the system disk and cannot be removed during
time sharing. System files to be removed are defined only by the values 0,
1, 3, 4, and 5.

lNUSE

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.

PRVIOL

A swap file is to be removed but its removal decreases 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 command or SYS call), wait until the
number of logged in jobs falls to the maximum, and try the removal operation again. This error also occurs if you attempt to remove the DECnetJE
system file when DECnet/E is still on.

.UUO-UU.SWP

Data Passed -

List System File
FIRQB

Mnemonic

Octal
Offset

, , , , , , II , , , , , , II , , , , ,
FQFUN

FQSIZM 5

UU.SWP (= 27)

1111111111

= -1 to list

file to list

, , , , , , II , , , , , , II , , , , ,

""""""""'1'"
, , , , , , II , , , , , , II , , , , ,

"11'""""'""'"

"'"'"'""'""'"
""""'""'""'"

16
20

, , , , , , II , , , , , , II , , , , ,

"""11"""""'"

""'""""'""'"

, , , , , , II , , , , , , II , , , , ,

""""""""1111'

FIRQB+FQFIL

, , , , , , II , , , , , , II , , , , ,

FQFIL

Mnemonic

The possible bit settings are:

Bit

~e~g

Swap file 0

Swap file 1

Swap file 2

Swap file 3

Overlay file

Error message file

DECnet/E system file

.UUO-UU.SWP 3-387

Data Returned -

List System File
FIROB

Mnemonic

Octal
Offset

Mnemonic

111111111111111111111

FOPPN

FONAM1

7
11

project number

programmer number

file name in RAD50 format
(2 words)

file type in RAD50 format (1 word)

111111111111111111111

device name (2 ASCII characters)

FODEV

FODEVN

<>0, unit number real

device unit number

111111111111111111111

FOEXT

Errors

3-388

BADFUO

The number specified at FIRQB+FQFIL is less than zero or greater than
six.

NOSUCH

The number specified at FIRQB+FQFIL refers to a file that is not currently
installed.

.UUO-UU.SWP

3.36.44

UU.SYS (Return Job Status Information)
Privileges Required

JOBCTL is required to read the status of another job, except a job running on a
pseudo keyboard controlled by the caller. TUNE is required to obtain priority or
run burst status.
Data Passed
FIROB
Mnemonic

Octal
Offset

Octal
Offset
111111111111111111111

FOFUN

FOSIZM 5

(

Mnemonic

UU.SYS (= 32)

1111111111

subcode= 0, 1, or 2

job number or 0

111111111111111111111

I I I I I I III I I I I I II I I I I I

I I I I I I II II I I I I II I I I I I

111111111111111111111

FOFIL

.UUO-UU.SYS

3-389

Data Returned (for subcode

=0)
FIRQB

Mnemonic

Octal
Offset

Octal
Offset
//1////1//1//////////

FQSIZM

1/111111/1

calling job no. * 2

FQJOB

job's console KB no.

status job no. * 2

FQFIL

swap slot location

(ctrlg job nO.*2)+1

FQPPN
FQNAM1

LSB of CPU time, in .1 seconds

job's current connect time, in minutes

LSB of KCTs

FQEXT

job's accumulated device time, minutes

FQSIZ

FQBUFL

FQMODE

21
23

MSB of CPU time

MSB of KCTs

job name in RAD50 format
(2 words)

25
FQPROT 27
31

24
project number

programmer number

job keyboard monitor in RAD50 format
(2 words)

33
35
37

3-390

Mnemonic

FQPFLG

FQDEV

32
current run-time system in RAD50 format
(2 words)

FQCLUS

FIRQB+FQSIZM

If this value is negative, the job is detached, and the value is the
one's complement of the keyboard number to which the job was
previously attached.

FIRQB+FQPPN

Returned only if job is attached to a pseudo keyboard.

.UUO-UU.SYS

Data Returned (for subcode

=1)
FIROB

Mnemonic

Octal
Offset

/////////////////////

FOSIZM

Mnemonic

//////////

calling job no .• 2

FOJOB

job's console KB no.

status job no .• 2

FOFIL

FOPPN

FONAM1

current flag word

curro info. posting

current IOSTS

current JBSTAT word

current JBWAIT word

FOEXT

size, in K words

FOSIZ

current physical addr., 32-word increments

FOBUFL

mem. ctrl sub-block

21
23

run burst,in .1 sec

priority

FOMODE

value at offset 6

max. memory size

FOFLAG

(depends on JBWAIT and JBSTAT)

FOPFLG

read or write state

FODEV

pointer to Job Data Block

FODEVN

pointer to second Job Data Block

FOCLUS

pointer to first Receiver 10 Block

FONENT

FIRQB+FQSIZM

If this value is negative, the job is detached, and the value is the
one's complement of the keyboard number to which the job was
previously attached.

FIRQB+FQMODE

Returned only if the caller has TUNE privilege.

.UUO-UU.SYS

3-391

Data Returned (for subcode

=2)
FIRQB

Mnemonic

Octal
Offset

Octal
Offset
/ 1/ / / / / / 1/ / / / / / / 1/ / / /

calling job no .• 2

2 FQJOB

job's console KB no.

status job no .• 2

4 FQFIL

job's current I-space

6 FQPPN

job's current D-space

10 FQNAM1

11
13

job's current privilege mask

(4 words)

12
14 FQEXT
16 FQSIZ

17
21

1/1/1/1/1/

3
FQSIZM 5

Mnemonic

job's access type

job's header size

20 FQBUFL
22

23
reserved

24
job's PPN

26 FQPFLG
30 FQDEV

31
33

job's saved privilege mask

(4 words)

34
36

FIRQB+FQSIZM

If this value is negative, the job is detached, and the value is the
one's complement of the keyboard number to which the job was
previously attached.

FIRQB+FQPPN

The monitor returns the job's current I-Space size in FIRQB+FQPPN
and the job's current D-Space size in FIRQB+FQPPN+1.

FIRQB+FQNAMI

The monitor returns the job's current privilege mask in four words
beginning at FIRQB+FQNAMI.

FIRQB+FQBUFL

The monitor returns the job's access type in this byte. The following values are defined:
Value
Meaning
0

Local

Dial-up

Batch

Network (SET HOST)

6
Network server
All other values are reserved.

3-392

FQBUFL+l

The monitor returns the job's header size in FIRQB+FQBUFL+1.

FIRQB+FQPFLG

The monitor returns the PPN of the job in the word beginning at
FQPFLG.

FIRQB+FQDEV

The monitor returns the job's saved privilege mask in the four
words beginning at FIRQB+FQDEV. This differs from the current
privilege mask if the job has temporary privileges.

.UUO-UU.SYS

Errors
BADFUO

The job number specified at FIRQB+FQFIL is less than zero or greater than
JOB MAX.

PRVIOL

The job specified at FIRQB+FQFIL does not exist.

.UUO-UU.SYS

3-393

3.36.45

UU.TB1 (Get Monitor Tables, Part I)
Privileges Required
None

Data Passed
FIROB
Mnemonic

Octal
Offset

FOFUN 3

3-394

.UUO-UU.TB1

Octal
Offset
111/111111/1111111111

UU.TB1 (= -3)

1/1/111/1/

I I I I I I I I I 1/ I I I I I I I I I I

IIIIIIIIIIIIIIIIIIIII

111/111111/1111111/11

I I 1/ I I I I I 1/ I I I I I I I I I I

1111111111/1111111111

I I 1/ I I I I I I I I I I I I I I I I I

IIIIIIIIIIIIIIIIIIIII

I I 1/ I I I I I 1/ I I I I I I I I I I

111/11111111111111111

IIIIIIIIIIIIIIIIIIIII

111/111111/1111111/11

IIIIIIIIIIIIIIIIIIIII

Mnemonic

Data Returned
FIRQB
Mnemonic

Octal
Offset

Octal
Offset
111111111111111111111

FQSIZM

Mnemonic

1111111111

current job no .• 2

FQJOB

MAXCNT(max. job no.)

CNT.KB-1 (max. KB no.)

FQFIL

(OEVCNT) address of max. unit no. table

FQPPN

(DEVPTR) address of pointers to dey. DDBs

FQNAM1

(MEMLST) root link word in 1st mem ctl sblk

(JOBTBL) address of the job table

FQEXT

(JBSTAT) address of job status table

FQSIZ

(JBWAIT) address of job wait flag table

FQBUFL

(UNTCLU) addr of unit ownerslpk cl sz tbl

FQMODE

(UNTCNT) address of disk status table

FQFLAG

(SATCTL) address of free-block table

FQPFLG

(JSBTBL) adr of job stat ordered by dry idx

FQOEV

(SATCTM) addr of free block count table

FQOEVN

current date in system internal format

FQCLUS

(UNTOPT) addr of unit option table

FQNENT

FIRQB+FQCLUS

System internal format for date is:
[(year - 1970) * 1000.] + day-within-year

Errors
No errors are possible with UU.TBl.

.UUO-UU.TB1

3-395

3.36.46

UU.TB2 (Get Monitor Tables, Part II)
Privileges Required
None

Data Passed
FIRQB

Mnemonic

Octal
Offset

FQFUN 3

3-396

.UUO-UU.TB2

Octal
Offset
111111111111111111111

UU.TB2 (= -14)

1111111111

111111111111111111111

Mnemonic

Data Returned
FIROB
Mnemonic

Octal
Offset

Mnemonic

1/ / / / / / 1/ / / / / / / /I / / / /

FOJOB

//////////

current job no. * 2

(FREES) addr of free buffer info table

FOFIL

(DEVNAM) addr of device name table

FOPPN

(CSRTBL) addr of CSR table

FONAM1

(DEVOKB) no. disks in DEVNAM * 2

(TTYHCT) no. hung term errs since startup

FOEXT

(JOBCNT) no. jobs now / no. log ins allowed

FOSIZ

(RTSLST) rt. Ink. word in RTS dsc.blk.list

FOBUFL

(ERLCTL) error logging control data

FOMODE

(SNDLST) list of eligible msg. rec. jobs

FOFLAG

(DSKLOG) disk logical table

FOPFLG

(DEVSYN) start of synonym names in DEVNAM

FODEV

(MEMSIZ) physical memory size, K-words*32

FODEVN

(CCLLST)root link word of CCL desc. blks.

FOCLUS

(FCBLST) addr of table of roots of FCBs

FONENT

Errors

No errors are possible with UU.TB2.

.UU~UU.TB2

3-397

3.36.47

UU.TB3 (Get Monitor Tables, Part III)
Privileges Required
None

Data Passed
FIROB
Mnemonic

FOFUN 3

3-398

.UU~UU.TB3

Octal
Offset

Octal
Offset
/ / /I / / / / / /I / / / / / / /I / /

UU.TB3 (= -29)

/1/1/1/11/

/ / /I / / / / / /I / / / / / / /I / /

/ / /I / / / / / /I / / / / / / II / /

/ / II / / / / / II / / / / / / 1/ / /

/ / /I / / / / / /I / / / / / / /I / /

/ / II / / / / / 1/ / / / / / / II / /

/ / /I / / / / / /I / / / / / / /I / /

///1/////1///////1/1/

/ / 1/ / / / I / II / / / / / / 1/ / /

/ / 1/ / / / / / 1/ / / / / / / II / /

/ / 1/ / / / / / /I / / / / / / 1/ / /

//1//////1//1////1///

/ / 1/ / / / / / 1/ / / / / / / 1/ / /

Mnemonic

Data Returned
FIROB
Mnemonic

Octal
Offset

Octal MneOffset monic

111111111111111111111

1111111111

current job no .• 2

2 FOJOB

(DDCTBL) addr of controllerldevice table

4 FOFIL

(UCTTBL) addr of unitlcontroller table

6 FOPPN

(SATEND) addr of disk size table

10 FONAM1

(UNTLVL) addr of disk structure level table

(MFDPTR) addr of MFD point table

14 FOEXT

(MAGLBL) addr of mag tape labeling default

16 FOSIZ

no. of single LOTs

20 FOBUFL

no. jobs on system

(LOTTBL) local object type table

(EMLCTL) EMT logger control table

24 FOFLAG

hardware configuration word

26 FOPFLG

(UNTERR) address of unit error count table

30 FODEV

(DEVCLU) addr of unit dev cI szlcl fac tbl

32 FODEVN

(NULRTS) address of NULL RTS block

34 FOCLUS

(DSTPTR) address of disk statistics table

36 FONENT

FIRQB+FQPFLG

Flag word bit settings indicate hardware configuration attributes:
Bit
Setting
Meaning
Clear

FIS not available

Set

FIS available

Clear

Unibus system

Set

QBUS system

Clear

FPP not available

Set

FPP available

10
13
FIRQB+FQNENT

Clear

CIS not available

Set

CIS available

Clear

System does not have I&D Space

Set

System has I&D Space

The Memory Management Unit (MMU) value for the disk statistics table, if unsupported disk statistics are turned on.

Errors

No errors are possible with UU.TB3.

.UUO-UU.TB3 3-399

3.36.48

UU.TRM (Set Terminal Characteristics)
Privileges Required

HWCFG is required to set a tenninal other than the caller's own, or to set
pennanent characteristics. A job owns a tenninal if the tenninal is the job's
console tenninal, or if the tenninal is opened or allocated by the job.
Data Passed (subfunction= 0)
FIROB
Mnemonic

Octal
Offset

Octal
Offset
11//111111////111//11

FOFUN

UU.TRM (= 20)

1////////1

FOSIZM

377(current) or KB no

subfunction code =0

FOFIL

200(tab)/377(no tab)

width: 0 or width+1

FOPPN

200(lwc out)/377(no)

200(no frm)/377(form)

FONAM1

200(fdplx)/377(local)

200(no XON)/377(XON)

200(no)/377(lwc in)

200(no scp)/377(scp)

FOEXT

rcv baud rate

FILL fctr+ 1;1 (noFILL)

FOSIZ

xmt baud rate

PARITY;1 (no)2(e)3(od)

FOBUFL

200(1I)/377(no II)

200(no stl)/377(stl)

FOMODE

parameters

1///1/1/1/

FOFLAG

FOPROT 27

200(no)/377(esc seq)

PERMANENT flag

FOPFLG

200(no esc)/377(esc)

private delimiter

FODEV

RSUM;200(IIC)/377(any)

200(no IIR/377(IIR)

FODEVN

200(no GAG)/377(GAG)

BRAK;200(nul)/377(IIC)

FOCLUS

FIRQB+FQEXT

3-400

Mnemonic

.UUO-UU.TRM

I I // I I I I I I 1/ I I I I I // I I

Setting No Scope automatically sets No Stall. Setting Scope
automatically sets Stall.

FIRQB+FQSIZ+l

Receiver baud rate is set as follows:
0
No change
The internal code to determine the baud rate
at which the terminal receives characters. If
FIRQB+FQBUFL+l is zero, this code also determines
the transmit (output) baud rate. (Requires HWCTL
privilege.) Note that you can set internal codes only for
DH11, DZ11IDZV11, and DHU11IDHV11 interface lines
as follows:

DHll

DZlllDZVll

DHUlllDHVll

Code

Speed

Code

Speed

Code

Speed
0

110

134.5

150

300

200

300

600

300

600

1200

600

1200

1800

1200

1800

2000

1800

2000

2400

4800

3600

Res.

9600

4800

9600

EXTA

7200

19200

EXTB

9600

FIRQB+FQBUFL

Parity and 8-bit mode values:
No parity
1
2
Even parity
3
Odd parity
4
Enable parity characteristic
20
8-bit characteristic off
30
8-bit characteristic on

FIRQB+FQBUFL+l

Transmitter baud rate is set as follows:
o
Both the receive (input) and transmit (output) speeds
are determined by the value n in FIRQB+FQSIZ+l.
n

The internal code to determine the baud rate at which
the terminal transmits characters when a split speed
setting is used. (HWCTL privilege required.) You can
use split speed settings only with the DH11, DHU11,
and DHV11 interface lines.

.UUO-UU.TRM 3-401

FIRQB+FQFLAG+l

Value=10+DATA+STOP+PARITY
where:
DATA is

o for 5-bit characters
1 for 6-bit characters
2 for 7 -bit characters
3 for 8-bit characters

STOP is

o for 1 stop bit per character
4 for 2 stop bits per character
or 1.5 bits if DATA = 0

PARITY is

0 for no parity bit
20 for even parity fonnat
60 for odd parity fonnat

This byte applies only to interfaces that support DATAISTOPIPARITY
features. When this byte is used with these interfaces, it overrides the setting of FIRQB+FQBUFL. In addition, when this
byte is used, FIRQB+FQSIZ+1 (receiver baud rate) must be
nonzero.
FIRQB+FQPFLG

FIRQB+FQDEV

The PERMANENT flag is as follows:
o
No change
200
Return pennanent characteristics
377
Set pennanent characteristics
Detennines the use of private delimiters as follows:
No change.

3-402

.UUO-UU.TRM

200

Disable (clear) the private delimiter.

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

Data Returned (Current Keyboard Characteristics)
FIROB
Mnemonic

Octal
Offset

Mnemonic

/ / 1/ / / / / / / 1/ / / / / / 1/ / /

//////////

current job no. * 2

FOJOB

255( current) or KB no

KB status

FOFIL

tab/no tab

width: 0 or width+ 1

FOPPN

Ie oulpt/no Ie oulpt

no form/form

FONAM1

full dplxllocal echo

no XON/XON

no Ie input/Ie input

no scope/scope

FOEXT

receive baud rate

no fill/fill

FOSIZ

transmit baud rate

no parity/even/odd

FOBUFL

up arrowlno up arrow

no stall/stall

FQMODE

//////11/1

interface for line

FOFLAG

no esc seq/esc seq

PERMANENT flag

FOPFLG

no esc/esc

delimiter/delim x

FODEV

resume CTRLlC or any

CTRLlR,CTRLlT flag

FODEVN

enable/dis broadcast

BREAK=null or CTRLlC

FOCLUS

///////1/1

8-bit characteristics

FONENT

FOSIZM

FOPROT 27

FIRQB+FQFIL

Bit 0 when set means the keyboard is disabled or is a pseudo
keyboard that is not in use.
When bits 1-6 are clear, it means no job owns the keyboard.
Otherwise, the value in bits 1-6 is equal to the job number times
two of the job that owns keyboard.
Bit 7 when set means the modem line is hung up or is a pseudo
keyboard that is not in use.

Errors
BADFUO

The system returns this error for one of two possibilities:
..
•

NOTAVL

Keyboard number is out of range of valid numbers.
Current keyboard is specified but is detached.

The system returns this error if you attempt t.o set. or retrieve information
on a terminal t.hat. is not. available, for example a t.erminal t.hat has been
disabled by INIT.SYS.

.UUO-UU.TRM

3-403

You do not have HWCFG privilege and tried to either:

PRVIOL

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. (FIRQB+FQSIZ+lor
FIRQB+FQBUFL+l is nonzero.)
Set the permanent characteristics for a dial-up terminal, pseudo keyboard, or local terminal. (FIRQB+FQPFLG is nonzero.)

•
•
•
•

Data Passed (Subfunction

=1)
FIROB

Mnemonic

Octal
Offset

Octal
Offset
111111111111111111111

FOFUN

UU.TRM (= 20)

1111111111

FOSIZM

377(current) or KB no

subfunction code=1

4 FOFIL

terminal type code

6 FOPPN

1111111111

I I I I I I I I I I I I II I I I I I I I

111111111111111111111

II 11111 11111 I I II I I I I I

I I I I I II I I I I I I I I I I I I I I

I I I I I II I I I I I II I I I I I I I

FOFLAG+125

clear chars flag

FOPROT 27

input buffer quota
clear control chars

set chars flag

24 FOFLAG

PERMANENT flag

26 FOPFLG

set control chars

30 FOOEV

set terminal capability flags

32 FOOEVN

clear terminal capability flags

34 FOCLUS

.UUO-UU.TRM

3-404

Mnemonic

I I I I I I I I I I I I II I I I I I I I

FIRQB+FQPPN

Tenninal type codes. The following decimal values are valid; zero
causes no change to occur:

Code

Type

Code

Type

Code

Type

0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

no change
Unknown
LA36
VT52
VT55
LA180S
VT100
LA120
LA12
LA100
LA34
LA38
LA50
VTI01
VT102
VT125

16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

VT131
VT132
VT220
VT240
VT241
VT105
VK100
RT02
LA30
VT50
VT50H
VT05
VT05B
LA30S
2741
ASR33

32
33
34
35
36-43
44
45
46
47
48
49
50
51
52-128
129-255

KSR33
ASR35
KSR35
LN03
Reserved
LA210
LQP03
LQP02
LA75
VT330
VT340
VT320
LA324
Reserved
Customer definable

FIRQB+FQFLAG

FIRQB+FQFLAG+1

The Set characteristics flag is as follows:
o
No change
1

Allow operator messages

Allow operator requests

Allow line editing

Allow command recall

200

Insert edit mode

The Clear characteristics flag is as follows:
o
No change
1

FIRQB+FQPFLG

Disable operator messages

Disable operator requests

Disable line editing

Disable command recall

200

Overstrike edit mode

The PERMANENT flag is as follows:
o
No change
200
Return pennanent characteristics
377
Set pennanent characteristics

.UUO-UU.TRM

3-405

FIRQB+FQPROT

The terminal's input buffer quota is as follows:
o
No change
6
to
255

The maximum number of input buffers. The default
value is 6. There are 28 characters per buffer. The
/BUFFER_QUOTA qualifier of the SET TERMINAL
command sets this characteristic. Users need HWCFG
privilege to use this feature.

NOTE

There is no guarantee that a
terminal can allocate its full buffer
quota.
Excessive use of this feature to
allocate large amounts of buffers
to several terminals could create a
shortage of small buffers.
FIRQB+FQDEV

Setting control character functions or auto-baud. The bits currently defined are:
o
Set CtrllC
1
Set CtrlfI'
2
Set CtrllR
3
Set CtrllX
4
Set autobaud
Bits can be combined; that is one or more bits can be set at any
time. If no bits are set, then the current setting is unchanged. All
other bits are reserved and should be zero.

FIRQB+FQDEV+1

Clearing control character functions or auto-baud. The bits currently defined are:
o
Clear CtrllC
1
Clear CtrlfI'
2
Clear CtrllR
3
Clear CtrllX
4
Clear autobaud
Bits can be combined; that is one or more bits can be cleared
at any time. If no bits are cleared, then the current setting is
unchanged. All other bits are reserved and should be zero.

FIRQB+FQDEVN

Set terminal capability flags. The following bits are currently
defined:
o
Set ANSI escape sequences
1
Set advanced video
2
Set width to 132 columns
Set printer port
3
4
Set ReGIS graphics
5
Set SIXEL graphics
6
Set Katakana character set
7
Set selectively erasable characters
Set dynamically redefinable character sets (DRCS)
8
Set user defined keys (UDKs)
9
10
Set local copy
Set Non-Interactive
11
Set Answerback mode
12
If no bits are set, the current capability status is unchanged. All
other bits are reserved and should be zero.

3-406

.UUO-UU.TRM

FIRQB+FQCLUS

Clear terminal capability flags. The following bits are currently
defined:
o
Clear ANSI escape sequences
1
Clear advanced video
2
Clear 132 column flag
3
Clear printer port
4
Clear ReGIS graphics
5
Clear SIXEL graphics
6
Clear Katakana character set
7
Clear selectively erasable characters
8
Clear dynamically redefinable character set (DRCS)
9
Clear user defined keys (UDKs)
10
Clear local copy
11
Clear Non-Interactive
12
Clear Answerback mode
If no bits are set, the current capability status is unchanged. All
other bits are reserved and should be zero.

Data Returned (Current Terminal Characteristics)
FIRQ8
Mnemonic

Octal
Offset

Octal
Offset
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 I I! I I I I I I I! I I

I! II I! II I!

current terminal type

I I I! I I I I I I! I I I I I I I! I I

Mnemonic

FQPPN

I! II II I! I!

PERMANENT flag

FQPFLG

I! II II III!

current ctrl settings

FQOEV

current terminal capability flag settings

I I I! I I I I I I! I I I I I I I! I I

32 FQOEVN

Errors
BADFUO

The system returns this error for one of three possibilities:
..
II

Keyboard number is out of range of valid numbers.
Current keyboard is specified but is detached.
The terminal's input buffer quota is out of range .

.UU~UU.TRM

3-407

PRVIOL

You do not have the required privileges and you tried to either:
•
•
•
•
•

3-408

.UUO-UU.TRM

Read the characteristics of a tenninal not opened or assigned to your
job.
Change the characteristics of a tenninal other than your job's console
tenninal (KB:).
Change the speed setting for your tenninal. (FIRQB+FQSIZ+l or
FIRQB+FQBUFL+l is nonzero.)
Set the pennanent characteristics for a dial-up tenninal, pseudo keyboard, or local tenninal. (FIRQB+FQPFLG is nonzero.)
Change the tenninal's input buffer quota.

3.36.49

UU. YLG (Enable Logins)
Privileges Required
SWCTL is required to enable logins.
Data Passed
FIROB
Mnemonic

FOFUN

Octal
Offset

Octal
Offset
//1//////1///////1///

UU.YLG (= -1)

1/1111//11

/11/////11/11////1///

111//////11//11/11///

111////11111111111/11

/11///11/1111////1///

//1//////1///////1/11

/ / /I / / / / / /I / / / / / / 1/ / /

//1///1111///11///11/

111////111/11////1///

111///111111/11/11///

111///11//1111///1///

//1/////11///////1///

/ / 1/ / / / / / /I / / / / / / /I / /

/ / /I / / / / / /I / / / / / / /I / /

Mnemonic

.UUO--UU.YLG 3-409

Data Returned
FIRQB
Mnemonic

Octal
Offset

Octal
Offset
111111111111111111111
11111/1111

current job no .• 2

2 FQJOB

11111/1111

no. logins allowed

4 FQFIL

1111111/1111111/11111

1111/11/1111111/11111

1111111/1111111/11111

I I I I I I 1/ I I I I I I 1/ I I I I I

1111111/1111111/11111

I I I I I I 1/ I I I I I I 1/ I I I I I

1111111/1111111/11111

No errors are possible with UU.YLG.

.UUO-UU.YLG

Errors

3-410

Mnemonic

3.36.50

UU.ZER (Zero Device)
Privileges Required

DEVICE is required to access a restricted device. Create/rename access (matching
PPN, or GWRITE, WWRITE andlor SYSIO privilege) required to zero an account
other than caller's. Set account access (GACNT or WACNT privilege) is required
to deallocate the UFD when zeroing an account.
Data Passed
FIROB
Mnemonic

Octal
Offset

Octal
Offset
I I 1/ I I I I I I 1/ I I I I I 1/ I I

FOFUN

Mnemonic

UU.ZER (= 15)

1/1/1/1/1/

1/1/11/1/1

flag (disk only)

FQFll

project number

programmer number

FOPPN

FQNAM1

volume 10 for label in RA050 format
(2 words)
(ANSI format mag tape only)

IIIII II I IIIIIIIII IIII

I I 1/ I I I I I I I I I I I I I I I I I

I I 1/ I I I I I I I I I I I I I 1/ I I

I I 1/ I I I I I I 1/ I I I I I 1/ I I

I I 1/ I I I I I I I I I I I I I 1/ I I

I I I I I I I I I I I I I I I I I 1/ I I

device name (disk, magtape, or DECtape)

FODEV

FOOEVN

<>0, unit number real

device unit number

I I 1/ I I I I I I I I I I I I I 1/ I I

I I 1/ I I I I I I 1/ I I I I I 1/ I I

FIRQB+FQFIL

Zero means delete all files except those write-protected against
owner; retain UFD clusters.
Minus one means delete an files regardless of protection code;
release UFD clusters (users with GACNT or WACNT privilege
only). Users without GACNT or WACNT privileges can use this
flag to delete all files regardless of their protection codes, but
cannot release UFD clusters.

FIRQB+FQPPN

Users without GACNT or WACNT privilege can specifY the current account only. Be sure to include the PPN; the system returns
an error if both bytes are zero.

Data Retu med

Except for a possible error in byte 0 of the FIRQB, the UU.ZER subfunction does
not return any meaningful data.

.UUO-UU.ZER

3-411

Errors
BADFUO

No PPN was specified.

BADNAM

The specified device is ANSI magnetic tape, and the volume ID is either
missing or invalid.

DEVNFS

The specified device does not allow access by file name.

NODEVC

The device specified is not on the system.

NOSUCH

The account specified does not exist on the device specified.

NOTAVL

The device specified exists on the system, but you cannot zero it for one of
the following reasons:
•
•
•

PRVIOL

3-412

.UUc>.-UU.ZER

A file is currently open on the device.
The device is currently reserved by another job.
The device or its controller is disabled.

The unit is write-locked, the unit is restricted and the caller does not have
DEVICE privilege, or the caller does not have accounting privileges and
FIRQB+FQPPN contains a PPN other than the current account.

3.36.51

UU.3PP (Third-Party Privilege Checking)
The UU.3PP directive enables or disables third-party privilege checking. This
directive is for the use of server programs that run as a separate job; for example,
spoolers.
Once issued, the directive remains in effect until cancelled by another UU.3PP
with zero in FIRQB+FQPPN, or by exit from the calling program. While in effect,
every privilege check done by the monitor is made twice: once for the job's PPN
and privilege mask, and once for the PPN and privilege mask specified in the call.
The function proceeds only when the check passes in both cases.
Privileges Required

None
Data Passed
FIRQ8
Mnemonic

Octal
Offset

FQFUN

Octal
Offset
1/1///////1//////1///

UU.3PP (= 37)

3
5

/ / 1/ / / / / / / 1/ / / / / / 1/ / /

FQPPN

FQNAM1

project number

1/1/1//1//

programmer number

11
13

privilege mask
(4 words)

/ / 1/ / / / / / / 1/ / / / / / 1/ / /

//1///////1//////1///

1/1///////1//////////

/ / /I / / / / / / /I / / / / / /I / /

1/1////1//1//////////

//1///////1//////1///

/ / 1/ / / / / / / 1/ / / / / / 1/ / /

FIRQB+FQPPN

Mnemonic

Specify zero to cancel third-party privilege checking.

Data Returned

None
Errors

NOBUFS

No small buffers available.

.UUO-UU.3PP

3-413

3.37 .WRITA -

Write Data to File or Device (Asynchronously)

Form

.WRITA
Function

The asynchronous write directive (.WRITA) performs the same basic functions
as the synchronous write directive (.WRITE): both move data between a device
and a user program. The difference lies in the completion of the request. While
synchronous write requests stall the job's execution until the request completes,
asynchronous write requests do not stall; the program continues to run while the
110 request completes in parallel with program execution. The mechanism that
the RSTS operating system uses to notify the user job upon 1/0 completion is an
asynchronous completion routine.
The .WRITA directive writes a specified number of bytes of data from a user
buffer (defined in the XRB) to a file or device currently open on a channel. Unless
an error occurs, the .WRITA always transfers the number of bytes specified.
The number of bytes specified must be less than or equal to the size of the buffer.
Table 3-11 gives specific details for each device (see the discussion for the .WRITE
directive). For comparison, Table 3-11 also shows the "best guess" buffer sizes
returned by the monitor at FIRQB+FQBUFL when the file or device is opened.
When you do 110 to or from a resident library mapped in D-Space, such as a
dynamic region, you can use 1/0 buffer sizes larger than the greatest size that
can be mapped into the program's virtual address space. You can get single 110
block sizes up to 65,534 bytes (177776 octal). Note that not all devices can use
such large block sizes.
You only need to map the first word of the 1/0 buffer into the the virtual address
space, so the monitor can locate the buffer in the resident library. However, the
entire buffer must reside in the resident library; otherwise, the monitor rejects
the 110 request. This feature is available only for resident libraries mapped in
D-Space.
Privileges Required

EXQTA is required to write in excess of disk quota. TUNE is required for multiple asynchronous 1/0 requests.

3-414

.WRITA

Data Passed
FIRQB
Mnemonic

Octal
Offset

Mnemonic

I I I I I /I I I I I I /I I I I I I I I

completion routine address

FQFIL

user-supplied parameter

FQPPN

I I I I I /I I I I I I /I I I I I I I I

FIRQB+FQFIL

The address in the user job where program flow should begin
when the asynchronous write completes.
If this value is zero, no AST completion is executed. In this event,
it is understood that the user is using some other mechanism to
determine whether the I/O successfully completed.

FIRQB+FQPPN

The user job uses this field to communicate information to the
AST completion routine. If FIRQB+FQFIL is zero, this value is
ignored.
XRB

Mnemonic

Octal
Offset

Mnemonic

length of output buffer, in bytes

o XRLEN

number of bytes to be written

XRBC

starting address of buffer

XRLOC

XRCI
XRBLK

XRBLKM 7

MSB of block number

channel number * 2

LSB of block number

I I I I I I /I I I I I I /I I I I I I I

optional modifier

XRMOD

.wRITA

3-415

3-416

.wRITA

XRB+XRLEN

Length of the output buffer, in bytes. The value of this word must
be nonzero.

XRB+XRBC

The number of bytes to be written. The value of this word must
be nonzero and less than or equal to the buffer size, as specified at
offset XRB+XRLEN. For disk, this must be a multiple of 512.

XRB+XRLOC

Starting address of the output buffer. For disk, flexible diskette,
and magnetic tape devices, this address must be on a word (even)
boundary. For all other devices, the buffer can begin on an odd
address. (See the section "XRB (Transfer Request Block)" in
Chapter 2 for more information.)

XRB+XRCI

Channel number times two; defines the channel on which the
data is to be written, as previously defined in an open (OPNFQ,
CREFQ, CRTFQ, CRBFQ functions of CALFIP).

XRB+XRBLKM

For disk files, this byte contains the most significant bits of the
starting block number where the write is to begin. This byte is
combined with the word at XRB+XRBLK to form a 24-bit field.

XRB+XRBLK

Starting block number where the write is to begin. Performs
the same action as the BLOCK option for disk or the RECORD
option for flexible diskette and non-file-structured DECtape (see
the RSTS/E Programming Manual). This parameter is ignored if
the device is not a random-access device. If the device is randomaccess, and this field is nonzero, it is interpreted as the block
number where the write is to start (1 to n, where n is the length
of the file in 512-byte blocks). If zero, the next sequential block is
written. For disk devices opened as non-file-structured in cluster
mode, this value is the starting device cluster number where the
write is to begin.

XRB+XRMOD

Output operation modifier; significant only for line printer, terminal, and DMCIDMR devices. (The monitor informs you with
the FLGMOD bit of the flag word whether or not the device accepts modifiers.) This parameter performs the same action as
the BASIC-PLUS RECORD modifier for these devices (see the
RSTS / E Programming Manual).

Data Returned to Completion Routine
FIRQB
Mnemonic

Octal
Offset

Octal
Offset
/11/111111

error code

/11111111/

job number· 2

Mnemonic

FQJOB

II / / / II / / / / / II / / / / / / /

user-supplied parameter

6 FQPPN

/ / / / / II / / / / / II / / / / / / /

/ / II / II / / / / / II / / / / / / /

/ / / / / II / / / / / II / / / / / / /

/ / II / II / / / / / II / / / / / / /

/ / / / / II / / / / / II / / / / / / /

/ / II / II / / / / / II / / / / / / /

/ / / / / II / / / / / II / / / / / / /

/11//11/////11///11//

/ / / / / II / / / / / II / / / / / / /

XRB
Mnemonic

Octal
Offset

/ / / / / / / II / / / / / II / / / / /

number of bytes not written

/ / / / / / / II / / / / / II / / / / /

XRBLKM 7

MSB of block number

/11111111/

block number where write began

/ / / / / / / II / / / / / II / / / / /

Mnemonic

XRBC

XRBLK

XRB+XRBC

The number of bytes not written in this .WRITE operation. This
value is usually zero.

XRB+XRBLKM

For disk files, the MSB of the block number of the block just
written. (Combined with XRB+XRBLK to form a 24-bit field.)

.wRITA

3-417

For random-access devices, this word contains the block number of
the block just written. Block numbers range from 1 to n, where n
is the length ofthe file, in 512-byte blocks. They define the order
in which the file is written. For disk devices opened as non-filestructured in cluster mode, this is the device cluster number of
the cluster just written.

XRB+XRBLK

Errors

BADCNT

The completion routine address is invalid or odd.

BSERR

The specified channel number is illegal; that is, it is not in the range 0 - 36
(since channel is specified as channel * 2), or it is an odd number.

EOF

A write was attempted to a block beyond the end of the disk when the disk
was opened non-file structured.

lNUSE

Too much outstanding 110 for the job or the job does not have the TUNE
privilege and has asynchronous 1/0 already outstanding.

NOBUFS

No small buffers were available for the request.

NOTOPN

No device is currently open on the specified channel.

PRVIOL

One of the following occurred:
•
•
•
•

The file or device currently open on the specified channel is read-only.
The open for this file or device did not specify write access. A write was
requested that would extend a UFD or a contiguous file.
A write was attempted that would extend a file in special update mode
and block 0 was not locked.
A write was attempted that would extend an executable file, increasing
its size to more than 65,535 blocks.

All other errors are device-dependent. Common errors are:
DATERR

Some data error occurred. This error is issued when a parity error occurs,
and so forth.

HNGDEV

Some hard device 1/0 error occurred. For example, the specified device is
off-line, is physically write-locked, and so forth.

NOROOM

No more room is available on the device. For example, the end-of-tape
marker has been encountered, no more available disk space, and so forth.

Example
See the description of .READA for an example using .WRITA.

3-418 .WRITA

3.38 .WRITE - Write Data to File or Device
Form
.WRITE

Function
The .WRITE directive writes a specified number of bytes of data from a user
buffer (defined in the XRB) to a file or device currently open on a channel. Unless
an error occurs, the .WRITE always transfers the number of bytes specified. The
number of bytes specified must be less than or equal to the size of the buffer.
Table 3-11 gives specific details for each device. For comparison, Table 3-11 also
shows the best guess buffer sizes returned by the monitor at FIRQB+FQBUFL
when the device is opened.
When you do 110 to or from a resident library mapped in D-Space, such as a .
dynamic region, you can use I/O buffer sizes larger than the greatest size that
can be mapped into the program's virtual address space. You can get single I/O
block sizes up to 65,534 bytes (177776 octal). Note that not all devices can use
such large block sizes.
You only need to map the first word of the 110 buffer into the the virtual address
space, so the monitor can locate the buffer in the resident library. However, the
entire buffer must reside in the resident library; otherwise, the monitor rejects
the I/O request. This feature is available only for resident libraries mapped in
D-Space.
Table 3-11 :

Data Output with. WRITE

Device

Block
Size,Bytes
(Decimal)

''Best Guess,"
Bytes
(Decimal)

Restrictions on Number of Bytes
Written

Byte-Oriented Devices (FLGFRC=l, FLGRND=O)

Keyboard (Tenninal)

N/A

128

None

Pseudo Keyboard

N/A

128

None

Paper Tape Punch

N/A

128

None

Line Printer

N/A

128

None

Block-Sequential Devices (FLGFRC=O, FLGRND=l)

Magnetic Tape

14 to 32,767

512

14 to 32,767 bytes

DECtape (filestructured)

510

Must be < 510 bytes; if < 510, automatically filled with NULLs to 510 bytes.

DMCIDMR

1 to 8000

512

None

Block-Random Devices (FLGFRC=O, FLGRND=O)

Disk

14 to 32,767

512

Must be multiple of 512 bytes. (Must be
512 if writing UFD.)

Flexible Diskette
(RXOI and RX02)

512

If not a multiple of block/sector size, zero
fill to end of block/sector.

t512 (block mode) or 128 (RX01 or RX02 single-density sector mode) or 256 (RX02 double-density sector mode)

(continued on next page)

.wRITE 3-419

Table 3-11 (Cont.):

Data Output with .WRITE
Block
Size,Bytes
(Decimal)

Device

''Best Guess,"
Bytes
(Decimal)

Restrictions on Number of Bytes
Written

Block-Random Devices (FLGFRC=O, FLGRND=O)
DECtape (non-filestructured)

512

Must be < 512 bytes; if < 512, automatically filled with NULLs to 512 bytes.

512

Privileges Required

EXQTA is required to write in excess of disk quota.
Data Passed

XRB
Mnemonic

.WRITE

Mnemonic

length of output buffer, in bytes

o XRLEN

number of bytes to be written

XRBC

starting address of buffer

XRLOC

XRCI
XRBLK

XRBLKM 7

3-420

Octal
Offset

MSB of block number

channel number· 2

LSB of block number

/ / / / / / II / / / / / II / / / / / /

optional modifier

XRMOD

XRB+XRLEN

Length of the output buffer, in bytes. The value of this word must
be nonzero.

XRB+XRBC

The number of bytes to be written. The value of this word must
be nonzero and less than or equal to the buffer size, as specified at
offset XRB+XRLEN. For disk, this must be some multiple of 512.

XRB+XRLOC

XRB+XRCI

Channel number times two; defines the channel on which the
data is to be written, as previously defined in an open (OPNFQ,
CREFQ, CRTFQ, CRBFQ functions of CALFIP).

XRB+XRBLKM

For disk files, this byte contains the MSB of the starting block
number where the write is to begin. This byte is combined with
the word at XRB+XRBLK to form a 24-bit field.

XRB+XRBLK

Starting block number where the write is to begin. Performs
the same action as the BLOCK option for disk or the RECORD
option for flexible diskette and non-file-structured DECtape (see
the RSTS / E Programming Manual). This parameter is ignored if
the device is not a random-access device. If the device is randomaccess, and this field is nonzero, it is interpreted as the block
number where the write is to start (1 to n, where n is the length
of the file in 512-byte blocks). If zero, the next sequential block is
written. For disk devices opened as non-file-structured in cluster
mode, this value is the starting device cluster number where the
write is to begin.

XRB+XRMOD

Output operation modifier; significant only for line printer, terminal, and DMCIDMR devices. (The monitor informs you with the
FLGMOD bit of the flag word whether or not the device accepts
modifiers.) Except for modifier 20000, which is useful to MACRO
programmers only, this parameter performs the same action as
the BASIC-PLUS RECORD modifier for these devices (see the
RSTS / E Programming Manual).
Modifier 20000 provides a no stall option for line printer or
terminal output. This modifier 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 XRB+XRBC.
Use this modifier for programs that must perform several different
functions with optimal performance, such as a line printer spooler
that performs 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. You may also find this modifier useful in
multiterminal service applications.
When you use the No Stall option on a line printer, you can
perform a special test to see whether the line printer is busy
without causing your program to stall. To perform the test, write
a null character and set modifier bits 2 and 13. When both bits
are set, the system returns control to your program instead of
stalling it. The value at XRB+XRBC tells you the status of the
line printer:
XRB+XRBC:::: 0
The line printer buffers are empty; that
is, there are no characters still to print.
XRB+XRBC <> 0

The line printer buffers still contain one
or more characters to print. Repeat the
test until the system returns zero at
XRB+XRBC.

For more information on modifier bit 2 for line printers, see
Appendix B and the RSTS / E Programming Manual. The
RSTS / E Programming Manual also contains more information on
special programming techniques for line printers .

.wRITE

3-421

Data Returned
XRB
Mnemonic

Octal
Offset

111111111111111111111

number of bytes not written

111111111111111111111

XRBLKM 7

MSB of block number

1111111111

block number where write began

111111111111111111111

Mnemonic

XRBC

XRBLK

XRB+XRBC

The number of bytes not written in this .WRITE operation. Except
for terminals and line printers, this value should be ignored.

XRB+XRBLKM

For disk files, the most significant bits of the block number of the
block just written. (Combined with XRB+XRBLK to form a 24-bit
field.)

XRB+XRBLK

For random-access devices, this word contains the block number of
the block just written. Block numbers range from 1 to n, where n
is the length of the file, in 512-byte blocks. They define the order
in which the file is written. For disk devices opened as non-filestructured in cluster mode, this is the device cluster number of
the cluster just written.

Errors
BADCNT

The first three words of the XRB that describe the output buffer are illegal
(an illegal byte count).

BSERR

The specified channel number is illegal; that is, it is not in the range 0 - 36
(since channel is specified as channel * 2), or it is an odd number.

EOF

A write was attempted to a block beyond the end of the disk when the disk
was opened non-file structured.

NOTOPN

No device is currently open on the specified channel.

PRVIOL

One of the following occurred:
•
•
•
•

All other errors are device-dependent. Common errors are:

3-422

.WRITE

DATERR

Some data error occurred. This error is issued when a parity error occurs,
and so forth.

HNGDEV

Some hard device 110 error occurred. For example, the specified device is
off-line, is physically write-locked, and so forth.

NOROOM

No more room is available on the device. For example, the end-of-tape
marker has been encountered, no more available disk space, and so forth.

Example

The following code writes the contents of a buffer to the file open on channel 5:
MOV
MOV
MOV
MOVB
. WRITE

#1024.,XRB+XRLEN
U024.,XRB+XRBC
#BUFFER,XRB+XRLOC
#5*2,XRB+XRCI

;SET BUFFER LENGTH
;SET BYTES TO WRITE
;SET BUFFER ADDRESS
;SET CHANNEL = 5

.WRITE 3-423

Part III
RSX and RT11 Emulator Directives

Chapter 4

RSX Run .. Time System Environment
Chapter 1 describes the RSX run-time system as emulating the RSX operating
system environment on RSTSIE. This is only partially true; the RSX emulator
does not provide a real-time, multiprocessing environment to users of a RSTSIE
time-sharing system. However, the RSX emulator does process directives that
are identical in form, and similar in objective, to a subset ofthe RSX-llM-PLUS
monitor directives that the RSX-llM 1M-PLUS Executive Reference Manual
describes.
If you use the RSX directives Chapter 5 describes, you must assemble your
program with the MAC assembler and link the modules with the Task Builder
(TKB). The program can then be run as a user job image under the control of the
RSX emulator (which is part of the RSTSIE monitor).

4.1

Advantage: Transportable Code
The RSX emulator directives are useful if you are coding a program to be run
under both the RSX-llM-PLUS and RSTSIE operating systems. However,
RSTSIE does not emulate all RSX-llM-PLUS executive directives, and the
meanings of those that are emulated are fitted to the RSTSIE environment.
To design a program to be run under both operating systems, you need to know
how the directives work under RSX-llM-PLUS and under RSTSIE. This manual
describes what the directives do under RSTSIE. Some comparison is made here
to RSX-llM-PLUS, but you must refer to the RSX-llM 1M-PLUS Executive
Reference Manual for a complete description of how these directives work in the
RSX-llM-PLUS environment.
Another benefit of using compatible directives is that you can execute such
programs directly on VAXJVMS under the VAX-ll RSX Application Migration
Executive (AME), which is similar in function to the RSX emulator. AME
emulates most RSX-llM-PLUS executive directives.

4.2 Genera.l Services
Besides transportable code, the RSX emulator directives also provide:
..

Non-file-structured I/O-The RSX emulator directives handle only non-filestructured 1/0 (for example, terminal I/O). For this type of 1/0, using the
directives takes less memory than using RMS. See the RSTS IE RMS-ll
MACRO Programmer's Guide for a description of the record management
service capabilities for MACRO programmers. RMS routines are available to
MACRO programmers through resident libraries or through linking to make
them part of the user job image. In either case, the RMS routines take space
RSX Run-lime System Environment

4-1

in the job area. The RSX emulator directives that do 110 take no extra space,
since the code to handle the processing is in the monitor.
•

Trap handling-The RSX emulator includes processing to handle synchronous
and asynchronous exceptions. Mainly, the emulator aborts the program when
such exceptions occur and prints an error message at the job's terminal. For
some directives, you can request that this processing be bypassed and handle
such exceptions in your program. For example, you can specify an address to
pass control to when a Floating-Point Processor (FPP) exception occurs.

4.3 RSX Directive Emulation Within RSTS/E Monitor
RSX emulation is a standard feature of the RSTSIE monitor. This allows task
images to execute without a run-time system, because the monitor handles the
RSX emulation directly. As a result, task images may expand to be as large as
64K-32 words; furthermore, a resident library (for example, RMS) may use the
address space which would otherwise be taken by the run-time system.
Since RSTSIE jobs are never without a run-time system, the monitor associates
the job with a zero-length, run-time system called "... RSX" for the duration of
the task's execution. When the task ends, the job exits to its default keyboard
monitor.

4.4 System Macro Library
The RSX emulator directives that you code into your program are macro; they
must be expanded into executable code at assembly time. The system macro
library (LB:RSXMAC.SML) contains the macro expansions for the RSX emulator
directives. This library file can be named in the input-file list when the assembly
is done. For example:
MAC OBJ,OBJ=SRC1,SRC2,LB:RSXMAC.SML/ML

However, the MAC assembler searches the library automatically to resolve
undefined symbols, so this is not really necessary.
In your code, though, you must use the MACRO-ll .MCALL directive to define
the directives you use as external macros needed to assemble the source program.
The .MCALL directive must appear before you call the first such directive. For
example:
.MCALL ALUN$,QIO$

ALUN$ 2,TT,5

Alternatively, you can use the .ENABL MCL assembler directive to enable
automatic macro library search. See the PDP-ll MACRO-ll Language Reference
Manual for details.

4-2

RSX Run-lime System Environment

4.5 Directive Processing
At assembly time, MAC expands the RSX directives to code. This creates a
Directive Parameter Block (DPB) that defines the action to be taken and the
parameters to be used.
Figure 4-1 shows the general form of a DPB.
Figure 4-1:

General Form of the Directive Parameter Block

DPB length (in words)

I Directive 10 Code (DIC)

(Parameters)

The Directive Identification Code (DIC) in the low byte of the first word of
the DPB defines the particular function to be performed. The RSX emulator
examines the DIC to determine what it is supposed to do. The high byte of the
first word of the DPB gives the length of the DPB in words (including the DIC
and length byte). The remaining words contain parameters; usually these are
values specified by the user in the directive call, expanded through MACRO-ll
data definition macros such as .BYTE, .WORD, .RAD50, and so forth.
The directive expansions also include executable code to tell the emulator where
the DPB is, an EMT 377 instruction to pass control to the emulator and, optionally, transfer control to an error processing routine specified by the user.
At execution time, RSTSIE pushes either the DPB address or the DPB itself on
the stack. The choice depends on the form of the directive. The EMT 377 instruction passes control to the RSTSIE monitor. The monitor recognizes the EMT
377 and passes control to the RSX emulation in the monitor. The RSX emulator
examines the DPB and processes the directive. It then pops the DPB address
or the entire DPB off the stack and either returns control to the program that
executed the directive or, if the directive was an exit of some kind, to whatever
location is appropriate to the exit.
When control returns in line, the carry condition code in the program status
word (PSW) indicates that the directive executed successfully (carry code = 0)
or failed (carry code = 1). The Directive Status Word gives more information
on the success or failure of the directive. You can refer to the Directive Status
Word in your program with the mnemonic $DSW; TKB defines this variable and
resolves its location automatically at link time. Other mnemonics are similarly
related to the possible values of $DSW, so the MACRO programmer can test for
error conditions using symbols such as IS.SUC for successful completion. See
"DSW Return Codes" in Chapter 5 for a listing of the symbols appropriate to each
directive.

RSX Run-lime System Environment 4-3

4.6 Directive Forms ($, $C, $S) and Their Expansions
The library file RSXMAC.SML contains three different expansions for each of
the RSX-llM directives (see Chapter 5). The form of the directive name you use
determines which expansion to be inserted in your code. Directive names consist
of one to four letters, followed by a dollar sign ($) and, optionally, a C or an S.
Table 4-1 shows an example of the three forms for the ALUN$ directive (Assign
Logical Unit).
Table 4-1:

Your Code

Form

Example of RSX Directive Forms

ALUN$ 5,TI',O

Expansion

Description

.BYTE 7,4
.WORD5
.ASCII fIT/
.WORDO

Create DPB in data section of
program (at assembly time)

MOV #A,-(SP)
EMT377
BCC .+6
JSRPC,ERR

DIR$#A,ERR

Push DPB address
Call RSX emulator
Branch if no error
Go to ERR on error
(same as above)

DIR$#A,ERR
(same as above)
.PSECT $DPB$$

ALUN$C 5,TI',O,PSECl,ERR

$$$=.
.BYTE 7,4
.WORD5
.ASCII fIT/
.WORDO
.PSECT PSECI
MOV #$$$,-(SP)
EMT377
BCC .+6
JSRPC,ERR
ALUN$S #5,#"TI',#O,ERR

4.6.1

Create DPB at assembly time
and automatically put in separate PSECT called $DPB$$

Reenter PSECT
Push DPB address
Call RSX emulator
Branch if no error
Go to ERR on error

MOV #O,-(SP)
MOV #"TI',-(SP)
MOV #5,-(SP)
MOV (PC)+,-(SP)

Create DPB at execution time
and push entire DPB on stack

.BYTE 7,4
EMT377
BCC .+6
JSRPC,ERR

Call RSX emulator
Branch if no error
Go to ERR on error

$ Form (and DIR$ Directive)
As Table 4-1 shows, the $ form of an RSX emulator directive generates a DPB
inline. The DIR$ directive expands to code that pushes the address of the DPB
on the stack and passes control to the RSX emulator. Use the $ formlDIR$
combination when you want to repeatedly execute the same directive. After one
directive defines a DPB, as many other DIR$ directives as need it, can use it.
This technique saves memory. Also, you can modify the individual parameters in
the DPB when you use the same directive many times with varying parameters.

4-4

RSX Run-lime System Environment

$ Form
The $ form of an RSX emulator directive expands to code that defines the DPB.
The expansions consist ofMACRO-ll data storage directives (for example, .BYTE,
.WORD, .RAD50); they are not executable. Therefore, use the $ form of an RSX
emulator directive only in a data section of your program.
Finally, use parameters that fit the MACRO-ll data storage directive in which
they will appear in the expanded code. For example, the ALUN$ directive
expands to the four instructions that follow:
ALUN$ 5,TT,O

Expansion:
.BYTE 7,4
.WORD 5

.ASCII

ITTI

.WORD 0

Although the example uses the two-character second parameter (TT) in a
MACRO-ll .ASCII directive, you do not need to specify the enclosing slashes;
the expansion does that for you.
Note that the first word of the expansion (the first word of the DPB) consists of
two bytes. The 7 in the low byte is the DIC byte for the ALUN$ directive. The 4
in the high byte indicates that the DPB is 4 words long.
DIR$ Directive

The general form of the DIR$ directive is:
new DIR$ [adr] [,err]
where:
adr

is the address of the first word of the DPB. As shown in the following expansion,
this address must be a valid source address for a MOV instruction. (The adr
parameter can be omitted. In this case, the entire DPB must be on the stack when
the DIR$ is executed.)

err

is an optional error address. Control passes to this address if the directive does not
execute successfully. If this parameter is omitted, control returns in line with the
C-bit set in the program status word (PSW).

For example, the DIR$ directive expands to the four instructions that follow:
DIR$ #DPB,ERROR

Expansion:
MOV
EMT
BCC
JSR

#DPB,-(SP)
377
.+6
PC, ERROR

RSTSIE pushes the address of the DPB on the stack, and the EMT transfers
control to the RSX emulator. The emulator processes the directive according to
the parameters specified in the DPB, pops the DPB address off the stack, and (for
ALUN$) returns control in line. The BCC instruction branches around the JSR to
ERROR if the C-bit is not set (no error occurred).

RSX Run-lime System Environment 4-5

Other Features of $ Form/DIR$ Combination

The $ fonD. of the RSX emulator directives generates local offsets that you can
use to refer to parameters in the DPB.
NOTE

The expansions use the MACRO-ll .NLIST directive so the code that
generates these offsets (which is not of interest to your program) does
not show up in your assembly listings.
For example, in the ALUN$ directive, you specify a logical unit number, physical
device name, and device unit number:
LN5DEF:

ALUN$ 5,TT,O

When this directive is expanded, it includes code that allows you to refer to the
parameters as:
LN5DEF+A.LULU
LN5DEF+A.LUNA
LN5DEF+A.LUNU

Logical unit number
Device name
Unit number

Chapter 5 lists these offset names under "Local Symbol Definitions" for each
directive. The number of bytes defined for each offset is given in parentheses
following a description of the area referenced by the offset. For example:
ALUNU - Logical unit number (2)
(You can also use offset names with the $C fonD. of directives. However, you
cannot use offset names with the $S fonD. because $S generates values that are
pushed on the stack.)
The $ fonD. expansions are also designed so you can use them to simply set up the
offset symbols to reference a DPB in another module. If you define the symbol
$$$GLB in your program (for example, $$$GLB = 0 will do), the $ fonD. of any
directive generates the symbolic offsets as global symbols and does not generate
the DPB itself. For example, suppose another module has the following code:
MYMY::

ALUN$ 5,TT,O

In the current module, define MYMY as a global symbol, define $$$GLB, specify
an ALUN$, and you will be able to reference MYMY+ALULU, and so forth.

4.6.2

$C Form
If you know the DPB parameters at assembly time and need to issue a directive
only once, the $C fonD. saves you the trouble of coding two directives: the $ fonD.
and DIR$. The $C fonD. also saves execution time over the $S fonD., which uses
MOV instructions to place the entire DPB on the stack and may save space as
well.

The $C fonD. of the directives expands to code that:

4-6

•

Defines the DPB in a separate PSECT (called $DPB$$).

•

Returns to a user-specified PSECT. If no PSECT name is given, returns to the
blank (unnamed) PSECT.

RSX Run-lime System Environment

•

Pushes the DPB address on the stack.

•

Passes control to the RSX emulator.

•

On return, passes control to a user-specified error routine if the directive did
not execute successfully. If you did not specify an error routine, no such code
is generated.

The directive descriptions in Chapter 5 show the form and expansion for the
$ form. To use the $C form, you must add the C to the directive name and,
optionally, add a PSECT name and error address to the parameter list. For
example, the ALUN$C directive expands to the 11 instructions that follow:
ALUN$C 5,TT,O,PART1,ERROR

Expansion:
.PSECT
$$$=.
• BYTE
• WORD
• ASCII
. WORD
.PSECT
MOV
EMT
BCC
JSR

$DPB$$

7,4
5

ITTI

PARTl
#$$$,-(SP)
377

.+6
PC, ERROR

MAC places the DPB in a separate PSECT called $DPB$$. The $$$ symbol
equates to the address of the DPB, which MAC uses in the MOV instruction that
pushes the DPB address on the stack before control passes to the emulator by the
EMT instruction. The last two instructions set up the test for error and transfer
control to the specified error routine. If you do not specify an error address in the
call, MAC does not generate those instructions.
Other Features of $C Form

The offset mnemonics that MAC generates for the $ form are also generated for
the $C form. Thus, you can save space by using the $$$ address to form the base
address for the offsets. The $$$GLB feature for the $ form also works for the $C
form of the directives.

4.6.3

$5 Form
The $S form is useful if your code is reentrant and the DPB parameters vary.
RSTSIE generates the DPB when it executes the directive at run time.
The $S form of the directives expands to code that:
•

Generates the DPB at execution time and pushes it on the stack.

•

Transfers control to the RSX emulator. The RSX emulator checks the low
byte of the first word on the stack to determine if it is a DPB address (even
low byte) or a DIC (odd low byte). If the low byte is odd, then the emulator
knows that the rest of the DPB is on the stack.

•

On return, passes control to a user-specified error routine if the directive
did not execute successfully. If no error routine is specified, no such code is
generated.

RSX Run-lime System Environment 4-7

To use the $8 fonn of the directives, add S to the directive names shown in
Chapter 5. You can also specify an error address as the last parameter in the
line. For example, the ALUN$S directive expands to the eight instructions that
follow:
ALUN$S

#5,DEV,UN,ERR

Expansion:
MOV
MOV
MOV
MOV
. BYTE
EMT
BCC
JSR

UN,-(SP)
DEV,-(SP)
#5,-(SP)
(PC)+,-(SP)
7,4
377
+.6
PC, ERR

RSTSIE generates the DPB at run time and pushes it on the stack. Control
passes to the RSX emulator, and if control returns with an error (the C-bit is set
on return), control transfers to the error routine. If you do not specify an error
address in the call, MAC does not generate the last two instructions.

4.7 Using Resident library Access Directives from FORTRAN
When programming resident library access in FORTRAN, you must create an
eight-word, single-precision integer array as the RDB to be supplied from the
following routines:
•

CALL ATRG (Attach Region directive)

•

CALL CRRG (Create Region directive)

•

CALL DTRG (Detach Region directive)

See the PDP-ll FORTRAN IV Language Reference Manual or the PDP-11
FORTRAN Lanugage Reference Manual for information on the creation of arrays.
An RDB array has the following format:
Word

Contents

irdb(l)

Region ID

irdb(2)

Size of the region in 32-word blocks

irdb(3)
irdb(4)

Region name--two words in RAD50 format

irdb(5)
irdb(6)

Name of the partition that contains the region- two words in RAD50
format

irdb(7)

Region status word. See the paragraph following this table.

irdb(8)

Region protection code.

You can modify the region status word irdb(7) by setting or clearing the
appropriate bits, listed with each directive.
Note that Hollerith text strings can be converted to RAD50 values by calls to the
FORTRAN library routine IRAD50.

4-8

RSX Run-Time System Environment

4.8 First 512. Bytes of Low Segment for RSX
As Chapter 2 notes, the first 512. bytes of virtual address space have special
meaning to the monitor. TKB, which links programs assembled or compiled
under the RSX run-time system and its derivatives, generates a header for
your executable program. When the RSX emulator loads your program, it uses
information from this header to load certain values into the low 512. bytes of
your program.
Table 4-2 shows the allocation of the first 512. bytes of the low segment for
RSX-type programs. Note that all locations are subject to change except for
$DSW, KEY, FIRQB, XRB, and CORCMN.

Table 4-2:

First 512. Bytes of Low Segment for RSX

Offset

Mnemonic

Description

R.TSKN

Task name in RAD50

R.PRTN

Partition Name in RAD50

R.CDSZ

Task Size (without extension, 32-word blocks)

R.ODTV

R.ODTL

ODT SST Vector Address
ODT SST Vector Length (low byte only)

R.SSTV

Task SST Vector Address

2
4
6

R.SSTL

Task SST Vector Length (low byte only)

R.FAST

FFP AST Service Address

R.CAST

CTRUC AST Service Address

R.TSKF

Task Flags

R.PARM

Run Parameter on Entry (from FIRQB+FQNENT)

R.CCLF

CCL Entry Flags, Run Size/Extension (XRB+O)

R.LDSZ

Load Size of Task in 32-word blocks

R.TKSZ

Current Size of Task in 32-word blocks

R.LUN

Number of LUNs

R.MONI

Monitor RSX Emulation Reserved Word 1

44
46

R.MON2
$DSW

Monitor RSX Emulation Reserved Word 2
Directive Status Word

.FSRPT

FCS Impure Area Pointer

$OTSV

OTS Impure Area Pointer

54
56

N.OVPT

Auto-Load Impure Area Pointer

$VEXT
CONTXT

Extended Impure Area Pointer
(Reserved for Monitor Context Use)

112

FPPTXT

(Reserved for Monitor FPP Context Use)

200

R.LUNS

LUN Table
(continued on next page)

RSX Run-Time System Environment 4-9

Table 4-2 (Cont.):

First 512. Bytes of Low Segment for RSX

Offset

Mnemonic

Description

400
402

KEY

Keyword

FIRQB

442

XRB

460

CORCMN

Core common area

660
662

PDMSP

SP saved here on a PM dump

PMDXRB

XRB saved here on a PM dump
FIRQB also saved on PM dump starting at PMDXRB

722

4-10

SP stack space for RSX Emulator

734
736
740

USRPPN

User's assignable project, programmer number

USRPRT

User's assignable protection code

USRLOG

User's logical device table

1000

NSTORG

Stack guard word (must =0)

RSX Run-Time System Environment

Chapter 5

RSX Emulator Directives
The RSX emulator directives:
•

Perform non-file-structured 1/0

•

Let you specify your own exception-handler routines

•

Control execution of the program

•

Return system information to the job

•

Provide access to resident libraries

Table 5-1 lists these directives by function. The remaining sections of this
chapter present the directives in alphabetical order.
Table 5-1 : Summary of the RSX Directives
Name

Description
Non-File-Structured 110

ALUN$

Assigns a logical unit number to a device and unit. The logical unit
number then serves to define the device in I/O requests.

GLUN$

Returns information about a logical unit.

GMCR$

Returns the command line typed by the user to invoke the program
currently running, if it was invoked by a RSTS/E CCL command.

QIO$
QIOW$

Open, read from, write to, and close logical units. 1/0 in RSX-emulation
mode is synchronous. That is, it is not asynchronous as in some systems,
such as RSX-llM where a user program can request I/O, do other processing, and get an interrupt when the I/O is complete. Thus, under the RSX
emulator, QIO$ (queue input/output) and QIOW$ (queue input/output and
wait) do the same thing. Control returns to the calling program when the
I/O is done.

WSIG$

Provides compatibility with RSX-llM, where some recoverable error
conditions require waiting for some significant event to occur before
retrying the operation that caused the error. In RSTSIE, such events are
transparent to the user program. WSIG$ simply causes the program to
sleep for one second.

WTSE$

Provides compatibility with RSX-llM, where RSX uses QIO$ and WTSE$
together to cause the program to wait until I/O is completed. Since I/O in
RSX-emulation mode is synchronous, the WTSE$ is implemented here as
a NOP instruction.

(continued on next page)

RSX Emulator Directives

5-1

Table 5-1 (Cont.):
Name

Summary of the RSX Directives
Description
Exception Handling

ASTX$

Exits from an FPP exception-handling routine, restoring the DSW, PC, and
PSW to the values they had before the exception occurred.

SCCA$

Defines an address to which control passes when a user at the job's
terminal types a CTRIlC combination. The SCCA$ directive is unique to
RSTSIE; it does not exist in the RSX-llM operating system.

SFPA$

Specifies an address to which control is to pass when an FPP exception
occurs. (The FPP is available on all PDP-ll processors that can run
RSTSIE, except the PDP-1l/35 and 40.)

SSTX$

Terminates routines that handle synchronous system traps with SVDB$ or
SVTK$. Required if the program uses supervisor mode libraries. Returns
control to where the program left of at the time of the trap. The SSTX$
directive is unique to RSTS!E; it does not exist in the RSX-llM operating
system.

SvnB$

Specifies a table of synchronous exception addresses that are to override
any specified with an SVTK$ directive. This is a useful capability for
a debugging routine, to divert breakpoint traps, for example, to the
debugging routine regardless of any SVTK$ directive in other modules of
the job.

SVTK$

Specifies a table of addresses to which control is to pass when synchronous
exceptions occur. The job can handle eight possible exceptions including
PDP-1l/35 and 40 FIS errors, TRAP instructions, BPT instructions, lOT
instructions, and T-bit traps.
PrograJP. Execution Control

ABRT$

Sets the job's exit status to "Severe Error" and returns control to the job's
keyboard monitor.

EXIT$

Returns control to the job's keyboard monitor (a normal exit).

EXST$

Sets the job's exit status to the specified value and returns control to the
job's keyboard monitor.

EXTK$

Increases or decreases the amount of memory allocated for execution of the
user job image.

EXTM$

Increases or decreases the amount of memory allocated for execution of the
user job image and allows manipulation of the D-Space APRs according to
a mask.

SPND$

Suspends execution of the program until the user types a delimiter on the
,keyboard (KB:).

(continued on next page)

5-2

RSX Emulator Directives

Table 5-1 (Cont.):

Summary of the RSX Directives

Name

Description
System Access Information

FEADF$

Defines system feature labels.

FEAT$

Tests for specified system features.

GPRT$

Returns partition parameters, which contain general information about
the job area and user job image area.

GTIM$

Returns the current day and time.

GTSK$

Returns task parameters: run priority, PPN, number of logical units
assigned, address of SST vector table (set up the SVTK$ or SVDB$), and
the system in which the job is running.

TFEA$

Tests for specified task features.
Resident Libraries Access

ATRG$

Attaches the job to a resident library, laying the groundwork for access to
the library. If necessary, the resident library is loaded from disk.

CRAW$

Creates a window of virtual addresses for reference to a library.
Optionally, you can map the window to actual locations in a resident
library.

CRRG$

Creates a dynamic region and optionally attaches to it.

DTRG$

Detaches the job from a resident library.

ELAW$

Eliminates an address window; it releases the virtual addresses for other
use, such as expanding the job image or creating another window.

Fast-map

Relates a created address window to actual memory locations in an
attached resident library. Fast-mapping is a simplified, high-speed alternative to MAP$.

MAP$

Relates a created address window to actual memory locations in an
attached resident library. The user program can then refer to locations in
the library using the virtual addresses defined in the window.

MSDS$

Specifies a 7-bit mask that determines which space each supervisor
D-space APR will use.

RDBBK$

Defines the offsets shown for the RDB areas for the ATRG$ and DTRG$
directives and, in addition, generates code to allocate space for the RDB
and fills it with values you specify in the call.

RDBDF$

Assigns literal values to the offsets and status bit mnemonics shown for
the RDB areas for the ATRG$ and DTRG$ directives.

UMAP$

Unmaps a window from a library; you can then map the window to
another portion of the library or to a different library.

WDBBK$

Defines the offsets shown for the WDB areas for the CRAW$, ELAW$,
MAP$, and UMAP$ directives and, in addition, generates code to allocate
space for the WDB and fills it with values you specify in the call.

WDBDF$

Assigns literal values to the offsets and status bit mnemonics shown for
the WDB areas for the CRAW$, ELAW$, MAP$, and UMAP$ directives.

RSX Emulator Directives 5-3

5.1

ABRT$ -

Abort

The ABRT$ directive tenninates execution of the calling program. Any open files
or devices are reset (that is, closed without the usual clean-up operations). On
a RSTSIE system, ABRT$ acts the same as the EXST$ directive with a severe
error.
Control passes to the job keyboard monitor at the keyboard monitor entry point
P.NEW (see Chapter 2). The job keyboard monitor is the default keyboard
monitor unless the job has issued the SET JOBIKEYBOARD_MONITOR
command or executed the .RTS directive to establish a specific job keyboard
monitor (see Chapter 3).
Privileges Required
None
Macro Call
ABRT$ name
RSTSIE ignores the name parameter; the calling program can abort only itself.
Macro Expansion
ABRT$
. BYTE
.RADSO

ALPHA
83.,3
/ALPHA/

;DIC=83., DPB SIZE = 3 WORDS
;IGNORED IN RSTS/E

Local Symbol Definitions
A.BTrN

name (4)

DSW Return Codes
IE.SDP

5-4 ABRT$

DIC or DPB size is invalid. This does not occur unless your program changes
the value of the first word of the DPB during execution. Control does not
otherwise return inline for the ABRT$ directive.

5.2 ALUN$ -

Assign Logical Unit Number

The ALUN$ directive assigns a logical unit number (LUN) to a physical device
unit. You can then use the logical unit number in QIO$ or QIOW$ directives to
do 110 (open, read, write, or close the associated device).
You can specify the device name as any 2-character logical name. The RSX
emulator checks the name specified in the call against the user logical names; if a
match is found, the monitor assigns the logical unit number to the corresponding
physical device. If the device name specified does not match any user logical
device names, the monitor performs a similar search for a match with a systemwide logical device name. If there is no match, the emulator checks the monitor's
physical device table, and, if a match is found, assigns the logical unit number
specified in the call to the actual physical device unit specified. Otherwise, the
directive returns an error.
Privileges Required

If the device is restricted, DEVICE is required.
Macro Call

ALUN$ lun,dev,unt
where:
lun

is the logical unit number; 1-14.

dev

is the device name; two ASCII characters.

unt

is the device unit number. Minus one indicates no unit number, as opposed to
a unit number of zero. The RSX emulator does not make a distinction between
SY (meaning the public disk structure) and SYO (meaning the disk from which
the system was booted). All uses of SY refer to the public structure. TI, TT, and
KB all refer to the job's terminal, whereas KBO and TTO both refer to the system
console terminal.

Macro Expansion
ALUN$
. BYTE
. WORD
. ASCII
. WORD

5,TT,O
7,4
5
/TT/

;ALUN$ MACRO DIC=7, DPB SIZE=4 WORDS
;LOGICAL UNIT NUMBER 5
;DEVICE NAME IS TT (TERMINAL)
;DEVICE UNIT NUMBER=O

Local Symbol Definitions
A LULU

Logical unit number (2)

A LUNA

Physical device name (2)

A LUNU

Physical device unit number (2)

DSW Return Codes
IS.SUC

Successful completion.

IE.IDU

Invalid device and/or unit.

IE.ILU

Invalid logical unit number.

IE.SDP

DIC or DPB size is invalid.

ALUN$

5-5

5.3 ASTX$ -

Asynchronous Exception Exit

In the RSTS/E environment, you can use the ASTX$ directive to terminate a
routine that handles an asynchronous FPP exception, only if the program has
indicated its intention to handle such traps with an SFPA$ directive. No other
condition in RSTS/E causes an asynchronous exception from which an ASTX$ exit
is useful. The CtrllC exception should use the SSTX$ macro to exit properly (see
SCCA$S).
When you execute an ASTX$, the stack must be in the state:
SP

(OSW) at the time exception occurred
(PC) at the time exception occurred
(PS) at the time exception occurred
word to which SP pointed before the exception

Your routine must pop the Floating-Point Exception Code (FEC) and FloatingPoint Address (FEA) pushed on the stack when the exception occurred (see
SFPA$).
When the ASTX$ directive executes, the RSX emulator restores the DSW value
to the DSW location and loads the PC and PS registers with their appropriate
values. Thus, these values pop from the stack, and control returns to the user
program at the point where it left off when the exception occurred.
You can change the contents of the PC address in the stack before you execute
ASTX$ so RSTS/E passes control to some point other than where it left off. Use
caution because it is hard to debug errors in an asynchronous exception routine.
Privileges Required

None
Macro Call

ASTX$ [err]
where:
err

is the error routine address

Macro Expansion
ASTX$S
MOV
. BYTE
EMT
JSR

ERR
(PC)+,-(SP)
115.,1

377
PC, ERR

;PUSH DPB ONTO THE STACK
;DIC = 115., DPB SIZE = 1 WORD
;TRAP TO RSX EMULATOR
;JUMP TO ERR IF DIRECTIVE UNSUCCESSFUL

NOTE

Digital recommends the $S form for this directive for two reasons:
first, only a one-word DPB is generated; second, no BCC instruction is
generated for the $S form (or the $C form). Thus, the $S form takes
less space than the $formlDIR$ combination. In addition, since the
one-word DPB requires only one MOV instruction, the $S form takes
less space and no more execution time than the $C form.
Local Symbol Definitions

None

5-6

ASTX$

DSW Return Codes
IE.SDP

DIe or DPB size invalid. This occurs only if your program changes the first
word of the DPB at execution time.

ASTX$

5-7

5.4 ATRG$ -

Attach Resident Library

The ATRG$ directive attaches the job to a resident library. The type of access
(read-only or read/write) is specified in the call. If the calling job can access the
library in that fashion, the monitor sets up its own internal tables that lay the
groundwork for the job to map windows to the library. Note, however, that the
resident library does not take up space in the job area (virtual memory) with an
attach. Virtual memory is assigned when a window is created (CRAW$).
NOTE

The job's ability to access the resident library depends upon the
protection assigned by the system manager when the resident library
was installed. The default protection grants read access to all users
and denies write access to all users.
If the attach is successful, a resident library ID is returned to the job. Other
directives use this ID to detach the job from the library (DTRG$) or to map and
unmap windows to and from the library (MAP$ and UMAP$). Once the monitor
attaches the job to a library, you can use the ATRG$ directive to determine the
library ID.

You can attach an unlimited number of resident libraries to a job at any given
time, provided the system has enough resources to keep track of the list of
attached libraries.
Privileges Required

None
Macro Call

ATRG$ adr
where:
adr

specifies the address of an 8-word area defining the library to be attached and
the type of access desired. The ATRG$ directive returns infonnation to this area.
Two supplementary directives are available to define (RDBDF$) or define and
fill (RDBBK$) such an 8-word area, called the resident library definition block
(RDB).

Macro Expansion
ATRG$
. BYTE
. WORD

5-8

ATRG$

RDBLK
57.,2
RDBLK

;DIC = 57., DPB SIZE
;ADDRESS OF RDB

2 WORDS

Data Passed in ROB
Mnemonic

Octal MneOffset monic

Octal
Offset
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 I /I I I I I I /I I I I I I

resident library name
(2 words in RAD50 format)

R.GNAM

7
11

I I I I I I I /I I I I I I /I I I I I I

access flags

I I I I I I I /I I I I I I /I I I /I /

R.GSTS

adr+R.GNAM

is the name of the resident library to which the job is to be attached,
as two words of RAD50 data. (The system manager makes resident
libraries known to the RSTSIE monitor with the INSTALLILIBRARY
command (see the RSTSjE System Manager's Guide). With this command, the system manager defines a file (filename.LIB) as a resident
library. The monitor regards "filename" as the resident library's name.)

adr+R.GSTS

is the low-order two bits in this word which defines the desired access
to the library.
RDBBK$,
RDBDF$

adr+R.GSTS

are the status bits that are currently defined as follows:

Bit

Definition

Read access desired on attach.

Write access desired on attach.

Delete access desired on attach.

Attach to region (forced if unnamed region).

Do not mark created region for deletion on last detach.

Delete region when all users detach (forced if unnamed
region).

At least one window was unmapped on a detach.

Region was successfully created.

Once RSTSIE attaches a job to a resident library, the access cannot be
changed without detaching (DTRG$) and reattaching. Also, an ATRG$
with the same resident library name specified at adr+R.GNAM returns
the assigned resident library ID.

ATRG$

5-9

Data Returned to ROB
Mne- Octal
monic Offset

Octal MneOffset monic
resident library ID

R.GID

size of library, in 32-word blocks

R.GSIZ

I I I 1/ 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 /I I I I I I /I

//111/111111//11111//

11/1//111111//11111//

I I I I /I I I I I I I /I I I I I I II

I I I I /I I I I I I I II I I I I I /I

adr+R.GID

is an identifier which must be used in subsequent calls to identify a
resident library, rather than the resident library name. Thus, you use
this identifier to detach (DTRG$) and to map and unmap windows
(MAP$ and UMAP$) to the library.

adr+R.GSIZ

is the size of the resident library, in 32-word blocks.

Local Symbol Definition
A.TRBA

Resident library definition block address (2)

DSW Return Codes

5-10

ATRG$

IS.SUC

Successful completion.

IE.UPN

Attaching a job to a resident library requires a small buffer; no small buffers
are currently available.

IE.PRI

The attach did not succeed because the caller's privileges do not allow the
access requested. This could happen either because the access code specified
is not compatible with the possible access defined when the library was
installed by the system manager or because the protection code associated
with the resident library file excludes the access requested by the user.

IE.PNS

The resident library name specified is not known to the monitor. The system
manager must install a resident library before the system can use it.

5.5 CRAW$ -

Create Address Window

You can use the CRAW$ directive either to create a window (a range of virtual
addresses) or to create a window and map it to a range of actual addresses in an
attached resident library. You define the range of addresses by naming a base
APR, which defines the starting virtual address for the window, and by specifying
the size of the window in 32-word blocks. Thus a window always begins on a 4Kword boundary in virtual memory. It may take more than 4K words, depending
on the size of the window.
The difference between creating a window and creating and mapping a window
is best illustrated by example. By using create without map, you can define
one window, which can be mapped to a library or portion of a library and then
remapped using MAP$ to another portion of the same library or another library,
as many times as desired. For example, suppose your program takes up 24K
words, and you want to access a 24K-word resident library of data values. You
can use create without map to set up a 4K-word window in APR 6. You can then
map the window to the first 4K words of the library, process the data, map to the
next 4K words of the library, and so forth.
If, on the other hand, you had a 4K-word program and still wanted to access a
24K-word library, you could use CRAW$ to create a 24K-word window and map it
to the entire library in APRs 1-6.
A job can create a maximum of 22 windows. A window takes at least one APR,
possibly more, depending on the size you specify for the window. Thus, the
maximum of 22 assumes 22 4K windows in both user I-Space and D-Space APRs
1 through 7 and eight 4K windows in supervisor I-Space APRs 0 through 7. You
can never use user lor D APR 0 to create a window, since the user program takes
at least this much space. As mentioned previously, a window cannot overlap
the user job image; thus, the size of the user job image determines the lowest
base APR that the job can use. If the program (user job image) is 4K words or
less, you can use APRs 1 and up (to the limit imposed by the run-time system
boundary) to create windows. If the user job image is between 4K words and 8K
words, you can use APRs 2 and up to create windows, and so forth.
If the virtual address range overlaps the user job image, the call fails with an
error. If the address range overlaps any existing windows, the overlap condition
is handled in a number of different ways, depending on the type of windows that
overlap:
•

If the job has nonseparate I&D Space or a Supervisor window is being
created, the new window eliminates all existing windows that it overlaps.

•

If the job has seperate 1- and D-Spaces and the new window request has the
same D-Space mapping bit value (WS.UDS) as any overlapping windows,
the new window eliminates the old overlapping windows. For example, if a
window exists in I-space (WS.UDS=O) and a new window request, also with
WS.UDS=O, overlaps it, then the new window eliminates the existing window.
The new window also eliminates the existing window if both windows have
WS.UDS=1.

•

If the new window being created is D-Space only (WS.UDS=I) and it overlaps
a window which is currently in both 1- and D-Spaces (WS.UDS=O), the new
window eliminates only the D-Space portion of the existing window, leaving
it in I-Space only. The new window then resides in the D-Space concurrently
with old window in I-Space. Note that the entire D-Space portion of the
existing window is eliminated even if only a portion of it overlaps with the
new window.

CRAW$

5-11

•

Likewise, if an I&D-Space window overlaps an existing D-Space-only
window, only the I-Space of the new window gets created and the existing
D-Space-only window remains.

Use caution when creating concurrent windows (one in I-Space only and one
in D-Space only). The default condition when creating I-Space windows is that
the equivalent D-Space accompanies it. The library being mapped through this
method must be writen as I-only code (such as RMS-ll) if the D-Space is to be
given to another window. If it is not I-only code, then you will get unpredicable
results if its D-Space is given away.
Privileges Required

None
Macro Call

CRAW$adr
where:
adr

is the address of an 8-word area defining the window and the resident library
to which the window is to be mapped, if mapping is requested. The CRAW$
directive also returns information to this area. Two supplementary directives are
available to define (WDBDF$) or define and fill (WDBBK$) such an area, called
the window definition block (WDB).

Macro Expansion
CRAW$
. BYTE
. WORD

WDB
117.,2
WDB

;DIC = 117., DPB SIZE
;ADDRESS OF WDB

2 WORDS

Data Passed in WDB
Mnemonic

Octal
Offset

Octal
Offset
base APR (1-7)

5-12

CRAW$

1111111111

Mnemonic
W.NAPR

I I I I I I I /I I I I I I /I I I I I I

size, in 32-word blocks, of window

W.NSIZ

resident library 10 (for map)

W.NRIO

offset, in 32-word blocks (for map)

W.NOFF

map length, in 32-word blocks

W.NLEN

access flags

W.NSTS

I I I I I I I /I I I I I I /I I I I I I

adr+W.NAPR

is the base APR of the window, 1-7 that implicitly defines the starting
address of the window. This byte cannot be zero, nor can it name
an APR already being used to map the user job image (see previous
discussion).

adr+W.NSIZ

Is the desired size of the window, in 32-word blocks. For example, a
value of 128 =4K words.

adr+W.NRID

is the identifier of the resident library to which the window is to be
mapped. (This is the value returned at adr+R.GID in the RDB for an
ATRG$ directive.) This word is ignored for calls requesting a create
without mapping (bit 7 at adr+W.NSTS is zero).

adr+W.NOFF

is the offset, in 32-word blocks, from the start of the library where the
mapping is to begin. This word is ignored if no mapping is requested
(bit 7 at adr+W.NSTS is zero.) A value of zero for this word indicates
the window is to be mapped beginning at the first byte of the library.
A value of one indicates the window is to be mapped beginning at the
33rd word of the library (starting address + 64), and so forth.

adr+W.NLEN

is the length, in 32-word blocks, of the area to be mapped (ignored if
bit 7 at adr+W.NSTS is zero). This value cannot be greater than the
length of the window specified at adr+W.NSIZ. In addition, this value,
combined with the offset specified at adr+W.NOFF, cannot indicate an
address beyond the end of the library. A value of zero defaults to either
the size of the window or the space remaining in the library, whichever
is smaller.

adr+W.NSTS

is the access-flags word. Two bits of this word define whether the
window is to be mapped and whether read-only access or read/write
access to the window is desired. Two additional bits define whether the
the window is to be mapped into supervisor I-Space or User D-Space.
If neither WS.SIS nor WS.UDS are set, then the CRAW$ directive uses
User I-Space.
WDBDF$,
WDBBK$
Mnemonic

Bit

WS.64B

WS.MAP
WS.SIS

7
5

Meaning

The task's permitted alignment boundaries defined as 32 words.

The task's permitted alignment boundaries defined as 256 words.

=1
=0
=1

The window is to be mapped.
The window is not to be mapped.
CRAW$ allocates this window in the
supervisor I-Space. Any mapping
occurs in the supervisor I-Space APRs
only.

This window is not a supervisor mode
window.

WS.UDS

CRAW$ allocates this window in the
User D-Space. Any mapping occurs in
User D-Space APRs only.

=0
=1
=0

This window is not a data-only window.

W8.WRT

Read/write access is desired.
Read-only access is desired.

If neither bit 4 nor bit 5 is set, then user Instruction Space is used. There is a
functional correspondence between bits 4 and 5 in the CRAW$ mode byte and the
region options available in TKB. This correspondence is as follows:
TKB Option

CRAW$ Mode Bit Setting

RESCOM & COMMON

bit 4 set to 1

RESSUP & SUPLIB

bit 5 set to 1

RESLIB & LIBR

neither, bit 4 & 5 set to 0

CRAW$

5-13

If bit 4 = 1, the window is created in the D APR space only; no mapping in the
I-Space is done. If another window is already created in both the 1- and D-Space
at this APR, the I-Space window remains as is, but the D-Space window moves
to this request. If a CRAW$ is done with bit 4 set and a second CRAW$ is done
to the same APR with neither bit 4 nor bit 5 set, the resulting mapping is such
that the D-Space APR is given to the CRAW with bit 4 set and the I-Space APR
is assigned to the region of the second CRAW$.
It is illegal to CRAW$ a region with both bits 4 and 5 set. In RSTSIE, supervisor
D-Space is always initially mapped the same as user D-Space. See the MSDS$
directive.

Data Returned in woe
Mnemonic

Octal
Offset

Mnemonic

window 10

W.NIO

starting virtual address of window

W.NBAS

1111111/111//1/1111/1

1////11/111111///1111

//11111//11/11///1111

length, in 32-word blocks, mapped

W.NLEN

status flags

W.NSTS

I I I I I I 1/ I I /I I 1/ I I I I I I

1///////1/

adr+W.NID

is the window ID, a value from 1-7. You can use this ID in later MAP$
calls to map the newly created window. You must use the ID in any
ELAW$ calls to eliminate the window.

adr+W.NBAS

is the starting virtual address of the new window.

adr+W.NLEN

is the length, in 32-word blocks, actually mapped by the window.

adr+W.NSTS

is the status-Hags word.
WDBDF$,
WDBBK$
Mnemonic

Bit

Meaning

WS.CRW

15 =1

The window was created successfully
The window was not created

WS.ELW

13 =1
=0

WS.UNM

14 = 1

An existing window was eliminated because it overlapped the newly created
window
No existing windows were eliminated by
this create
An existing window was unmapped because it overlapped the newly created
mapping
No existing windows were unmapped by
this mapping

Local Symbol Definitions
C.RABA

5-14

CRAW$

Window definition block address (2)

DSW Return Codes
IS.SUC

Successful completion.

IE.ALG

Either the base APR and window length specified were invalid or the offset
and mapping length values specified were invalid. For example, an offset
indicating a starting address for the mapping that was beyond the end of the
library returns this error.

IE.NVR

The library ID specified for mapping does not specify any library currently
attached to the job.

IE.PRI

The create was unsuccessful because the requested access is not allowed. At
this point, since the library has been attached successfully with some access
defined, this error means that the access requested in the CRAW$ is not
allowed by the access requested in the ATRG$.

IE.WOV

An attempt was made to create more than seven address windows.

IE.UPN

Creating a window requires a small buffer; a small buffer is not currently
available.

CRAW$

5-15

5.6 CRRG$ -

Create Dynamic Region

The CRRG$ directive creates dynamic regions similar to those created by
UU.RTS. This call operates in a slightly different manner than its counterpart. If
an attempt is made to create a region that already exists, CRRG$ returns with
bit 15 in R.GSTS clear. If attachment is specified and the region already exists,
the new region is attached to the already existing region.
Privileges Required

INSTAL
Macro Call

CRRG$adr
where:
adr

is the address of an 8-word Region Descriptor Block (RDB). The CRRG$ directive
also returns information to this area.

Macro Expansion
CRRG$
• BYTE
• WORD

RDBLK
55. ,2
RDBLK

;DIC = 55., DPB SIZE
;ADDRESS OF RDB

2 WORDS

Data Passed in ROB
Mnemonic

Octal
Offset

111111111111111111111

CRRG$

size in 32-word blocks of region to create

2 R.GSIZ

name of region, or 0 for unnamed
(2 words)

4 R.GNAM
6

5-16

Mnemonic

111111111111111111111

I I I III I I I I I II I I I I I I II

region status

14 R.GSTS

region protection in RSX format

16 R.GPRO

are the status bits that are currently defined as follows:

adr+R.GSTS

adr+R.GPRO

Bit

Definition

Read access desired on attach.

Write access desired on attach.

Delete access desired on attach.

Attach to region (forced if unnamed region).

Do not mark created region for deletion on last detach.

Delete region when all users detach (forced if unnamed
region).

At least one window was mapped on a detach.

Region was successfully created.

is the region protection code converted from RSX format to RSTSIE
format by the following algorithm:
The system field is ignored
Delete protection is ignored
Extend protection is ignored
Read protection is mapped to RSTSIE read protection
Write protection is mapped to RSTSIE write protection

•
•
•
•
•

(

Data Returned in ROB
Mnemonic

Octal
Offset

Mnemonic

region 10 of created region

0 R.GIO

size of the region in 32-word blocks

2 R.GSIZ

/ / 1/ / / / / / / 1/ / / / / / 1/ / /

//1///////1///1//1///

status flags

1/1///////1//////1///

adr+R.GSTS

R.GSTS

is the status-flags word. Bit 15 is clear if the region already exists.

DSW Return Codes
IS.SUC

Successful completion.

IE.PRI

User does not have INSTAL privilege.

IE.UPN

Creation failed, examine FIRQB for details.

CRRG$

5-17

5.7 DTRG$ -

Detach Resident Library

The DTRG$ directive detaches the job from a previously attached resident
library. Any windows mapped to the library by the calling job are unmapped and
eliminated. If the specified library is a dynamic region marked for deletion when
all users detach, the monitor checks if the region is no longer attached by any job.
If so, the monitor deletes the region and releases the memory allocated to it.
Privileges Required
None
Macro Call

DTRG$adr
where:
adr

is the address of an 8-word area defining the library to be detached. The DTRG$
directive also returns information to this area. Two supplementary directives are
available to define (RDBDF$) or define and fill (RDBBK$) such an 8-word area,
called the Resident-Library Definition Block (RDB).

Macro Expansion
DTRG$
. BYTE
. WORD

RDBLK
59.,2
RDBLK

;Dle = 59., DPB SIZE
;ADDRESS OF RDB

2 WORDS

Data Passed in ROB
Octal
Offset

Mnemonic

resident library 10

R.GID

/ / / / / / / / / / / / II / / / / / II

/ / / / II / / / / / / / / / / / / / II

/ / / / / / / / / / / / II / / / / / II

/ / / / II / / / / / / II / / / / / II

Mne- Octal
monic Offset

7
1---

adr+R.GID

5-18

DTRG$

is the library ID the ATRG$ directive returns (at the same position in
the RDB).

Data Returned in ROB
Mnemonic

Octal
Offset

11111111111/111111/11

111111111111111111111

I I II I I I I I I II I I I I I 1/ I I

111111111111111111111

status flags

111/11111111111111111

adr+R.GSTS

Mnemonic

R.GSTS

is the status flag, bit 14, that defines if any windows were unmapped
as a result of this detach.

Local Symbol Definitions
D.TRBA

Resident-Library Definition Block address (2)

DSW Return Codes
IS. sue

Successful completion.

IE.NVR

The library ID specified does not identify any library currently attached to the
job.

DTRG$

5-19

5.8 ELAW$ -

Eliminate Address Window

The ELAW$ directive eliminates an address window that was created by the job,
unmapping the window if necessary. ELAW$ frees the APRs used by the window
and makes them available for creating another window or for expanding the user
job image size.

Privileges Required
None

Macro Call
ELAW$adr
where:
is the address of an 8-word area defining the window to be eliminated. The
ELAW$ directive also returns information to this. Two supplementary directives
are available to define (WDBDF$) or define and fill (WDBBK$) such an area,
called the Window Definition Block (WDB).

adr

Macro Expansion
ELAW$
. BYTE
. WORD

WDBADR
119.,2
WDBADR

;DIC=119., DPB SIZE=2 WORDS
;ADDRESS OF WDB

Data Passed in woe
Mne- Octal
monic Offset
1/1//1/1//

ELAW$

window 10

Mnemonic

W.NIO

/ / / / /I / / / / / 1/ / / / / / / /I

/ / / / /I / / / / / / /I / / / / / /I

/ / / 1/ / / / / / / / /I / / / / / /I

//1/1///////1//////1/

/1//1///////1//////1/

/1//1/1////////////1/

adr+W.NID

5-20

Octal
Offset

is the ID of the window to be eliminated (returned at the same location
in the WDB by the CRAW$ directive).

Data Returned in WDB
Mnemonic

Octal
Offset

I I I I I I I I I II I I I I I I II I I

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

IIIIIIIII II IIIIIIIIII

I I I I I I I I I I I I I I I I / II I I

status flags

I I I I I I I I I I I I I I I I III II

adr+W.NSTS

Mnemonic

W.NSTS

is the status-flags word. Two bits in this word give the following
information:
WDBDF$,
WDBBK$
Mnemonic

Bit

Meaning

WS.ELW

13 = 1

The window was successfully eliminated
The window was not eliminated

WS.UNM

14 = 1

The window eliminated was mapped to a
resident library and has been unmapped
The window eliminated was not mapped;
no unmapping was done

Local Symbol Definitions
E.LABA

Window Definition Block address (2)

DSW Return Codes
IS. sue

Successful completion.

IE.NVW

Bad window ID. It is either outside the range 1 to 22 or it does not match any
window currently created for this job.

ELAW$

5-21

5.9 EXIT$ -

Task Exit

The EXIT$ directive stops execution of the calling job. Control passes to the job
keyboard monitor at the keyboard monitor entry point P.NEW (see Chapter 2).
Any devices still open are reset; that is, closed without performing the usual
clean-up operations.
NOTE

On exiting from the previously running program, the monitor drops
any temporary privileges still in effect.
The job keyboard monitor is the default keyboard monitor unless the job has
issued the 8ET JOBIKEYBOARD_MONITOR command or executed the .RT8
directive to establish a specific job keyboard monitor (see Chapter 3).
Privileges Required
None
Macro Call
EXIT$8 [err]
where:
is the error routine address.

err

Macro Expansion
EXIT$S
MOV
.BYTE
EMT
JSR

ERR
(PC)+,-(SP)
51.,1

377
PC, ERR

iPUSH DPB ONTO THE STACK
iDIC = 51., DPB SIZE = 1 WORD
;TRAP TO THE EMULATOR
iCALL ERROR ROUTINE

NOTE

Digital recommends the $8 form for this directive for two reasons:
first, only a one-word DPB is generated; second, no BCC instruction is
generated for the $8 form (or the $C form), since control never returns
inline unless an error occurs.
Thus, the $8 form takes less space than the $ formlDIR$ combination.
In addition, because the one-word DPB requires only one MOV instruction, the $8 form takes less space and no more execution time than the
$C form.
local Symbol Definitions
None
DSW Return Codes
IE.SDP

5-22

EXIT$

DIC or DPB size is invalid. This occurs only if your program changes the first
word of the DPB at execution time.

5.10 EXST$ -

Exit with Status

Like EXIT$, the EXST$ directive stops execution of the calling job. On exiting
from the previously running program, the monitor drops any temporary privileges
still in effect. In addition, EXST$ sets the job's exit status.
Control passes to the job keyboard monitor at the keyboard monitor entry point
P.NEW (see Chapter 2). Any devices still open are reset; that is, closed without
performing the usual clean-up operations. The monitor detaches any attached
resident libraries, and eliminates any created address windows.
NOTE

The job keyboard monitor is the default keyboard monitor unless the
job has issued the SET JOBIKEYBOARD_MONITOR command or
executed the .RTS directive to establish a specific job keyboard monitor
(see Chapter 3).
Privileges Required

None
Macro Call

EXST$ sts
where:
sts

is the status value. DCL copies this data into the $SEVERITY and $STATUS
variables (see the RSTS / E Guide To Writing Command Procedures).

Macro Expansion
EXST$
. BYTE
. WORD

STATS
29.,2
STATS

;DIC=29., DPB SIZE
;EXIT STATUS WORD

2 WORDS

Local Symbol Definitions
E.XSTS

Exit status word (2)

EX$WAR

Warning status code

EX$SUC

Success status code

EX$ERR

Error status code

EX$SEV

Severe error status code

DSW Return Codes

No errors are possible with EXST$.

EXST$

5-23

5.11

EXTK$ -

Extend Task

The EXTK$ directive lets you increase the amount of memory allocated to the
user job image. For compatibility with RSX-llM, the argument specified in the
call indicates a positive or negative increment of 32-word blocks. However, the
RSTSIE monitor actually allocates space for the user job image in lK-word units.
Thus, the RSX emulator keeps track of the user job image size as a number of
32-word blocks. When an EXTK$ directive is executed, the emulator checks to
see if the extension or reduction needs or frees one or more lK-word blocks of
memory. If so, the emulator directs the monitor to make the new allocation; if
not, the current allocation remains.
NOTE

Do not use the .CORE directive (see Chapter 3) before an EXTK$
directive in the same program. The monitor executes the .CORE
directive directly, without the intervention (or knowledge) of the RSX
emulator. If a .CORE executes before an EXTK$, the emulator has
incorrect information on the current size of the user job image when it
executed the EXTK$, and it bases the new allocation on the size before
the .CORE was executed.
You cannot extend the size beyond the least of the following:
•

The job's private maximum size-A private job maximum size can be set by
the system manager.

•

The system-wide maximum user job image size-Set by the system manager
(see SWAP MAX, RSTS / E System Installation and Update Guide).

•

32K-32 words-The maximum size allowed by the RSX emulator.

You also cannot extend the size of the image into virtual address space used by
an address window created for use with resident libraries (see CRAW$ directive).
NOTE

If I&D Space is in use, the size applies only to the D-Space of the task.
The size ofthe I-Space is fixed at task load time.
If there is not enough contiguous memory for the extension to be made where
the job currently is in memory, the monitor swaps the user job image to disk and
then returns it to memory at a location that can accomodate the new size. If no
increment is given in the call, the emulator allocates the amount of space the job
had initially, based on information built in at link time (with TKB); that is, before
any EXTK$ was executed.

Privileges Required

None
Macro Call

EXTK$ [inc]
where:
mc

5-24 EXTK$

is the number of 32-word blocks by which the task size is to be extended (positive
value for inc) or reduced (negative value for inc).

Macro Expansion
EXTK$
. BYTE
. WORD
. WORD

40
89.,3
40

;DIC = 89., DPB SIZE = 3 WORDS
;EXTEND 40(8) BLOCKS (lK WORDS)
;RESERVED WORD

Local Symbol Definitions
E.XTIN

Extend increment (2)

DSW Return Codes
IE.sue
IE.UPN

Successful completion.
The requested increment would have caused the user job image size to exceed
that allowed (see previous discussion). The user job image size stays at the
current size.

EXTK$ 5-25

5.12 EXTM$-Ex:tend Task by Mask
This directive is similar to the EXTK$ directive. Both directives extend the task's
virtual address Data Space. However, when doing I&D-Space tasks, the EXTM$
directive unmaps the D-Space APRs (only) from libraries and includes them
in the memory extension space, if allowed by the APR mask. This leaves the
resident library mapped in I-Space only. In tasks built without I&D space (TKB
I-ID option), the EXTM$ directive behaves exactly as the EXTK$ directive.
During task memory expansion, RSTS/E maps resident libraries with both I&D
Space APRs mapped identically; this is done by default. The EXTK$ directive
does not override this mapping. If an attempt is made to extend into an APR
used by the library, it will cause an error.
The APR mask provides a method of reserving one or more APRs in the D-Space
for resident library use. If, for example, a resident library is built with I-Space
using APRs 5, 6, and 7 but all the needed D-Space is contained in APR 7, then by
reserving APR 7 for the library, the task can extend its usable D-Space into APRs
5 and 6. The task does this reservation by setting the APR 7 bit in the APR mask
word in the EXTM$ call.
If an EXTM$ extension of memory requires the use of an APR whose bit is set in

the APR mask word, the system returns an error.
The Task Builder has automated the process of constructing the APR mask word
for the combination of libraries used in building the task. This data is available
to the program at execution time. See the RSTS / E Task Builder Reference
Manual for details.
NOTE

If I&D Space is not turned on (I-ID), then all EXTM$ requests behave

as though they are EXTK$ requests (that is, the APR mask word is
zero).
The lowest bit set above the current task D-Space determines the protection line
above which a request will fail. For example, if only bit 3 is set, then APRs 3
through 7 are protected even though bits 4 through 7 are not set.
CAUTION

Take care when using this call to remap D-Space away from a library.
If the library is not coded in an I -only manner, the program is likely to
behave unpredictably.
Use EXTM$ to pass information to RSTSIE gathered by the Task Builder about
the D-Space that the resident libraries associated with the task need. The task
builder makes this link time data available at run time.
If the program includes:
.PSECT $$TSKP, D
$TSKP: :
.PSECT [name of previous .PSECT]

then the Task Builder fills the address at $TSKP with the inclusive OR of all the
D-APR masks used by the program. At execution, the value of $TSKP can be
used directly as the mask in the EXTM$ call by allowing the program to expand
to the minimum size allowed for the particular library configuration in use. See
the RSTS / E Task Builder Reference Manual on building resident libraries for
details on the source values filled into $TSKP.

5-26

EXTM$

Privileges Required

None
Macro Call
EXTM$ [inc,mask]

where:
inc

is the number of 32-word blocks by which the task size is to be extended (positive
value for inc) or reduced (negative value for inc).

mask

is the APR mask word through which the caller passes information about those
user D-Space APR registers protected from being expanded into by the task DSpace. This mask specifies which D-Space APRs are still available for resident
library (or dynamic region) D-Space mapping.
In the EXTK$ directive, this APR mask word is zero; it tells RSTSIE not to
expand task D-Space beyond the base APR of the lowest mapped library or
dynamic region.
The APR mask word allows the user to control how the task extension is to work.
Extension uses fall into three general categories listed in the following table.

APR Mask
Word

Description

The EXTM$ behaves as an EXTK$ on RSTSIE; that is, extension
is only allowed up to the base of the first library APR.

The EXTM$ behaves as an EXTK$ on RSX-llMIM-PLUS; that
is, extension is allowed thru APR7 remapping the D-Space of any
libraries. However, extension is not allowed past the beginning
of a dynamic region or a window specifically mapped in D-Space.

any other

For all other values, the APR Mask Word acts like a memory
protection flag. An EXTM$ request is not allowed to extend task
D-Space into an APR that is above the current task D-Space and
that the bit representing the APR is set (see the following list).
It also is not allowed to extend past the beginning of a dynamic
region or a window specifically mapped in D-Space.
Bit 7

Represents APR 7

<200>

Bit 6

Represents APR 6

<100>

Bit 5

Represents APR 5

<40>

Bit 4

Represents APR 4

<20>

Bit 3

Represents APR 3

<10>

Bit 2

Represents APR 2

<4>

Bit 1

Represents APR 1

<2>

Bit 0

Must be set for EXTM$

<1>

Macro Expansion
EXTK$
. BYTE
. WORD
. WORD

40,30
89.,3
40
30

;DIC = 89., DPB SIZE = 3 WORDS
;EXTEND 40(8) BLOCKS (lK WORDS)
;MASK PROTECTS APRS 6 & 7 D-SPACE FOR LIBRARY

Local Symbol Definitions
E.XTIN

Extend increment (2)

EXTM$

5-27

DSW Return Codes

5-28

EXTM$

IE.SUC

Successful completion.

IE.UPN

The requested increment would have caused the user job image size to exceed
that allowed (see previous discussion). The user job image size stays at the
current size.

5.13 FEADF$ -

Define System Feature labels

The FEADF$ macro lets you define the system feature labels.

Privileges Required
None
Macro Call

FEADF$
This is purely a definition macro and therefore there are no results or errors.

FEADF$

5-29

5.14 FEAT$ -

Test for System Feature

The FEAT$ directive tests for the presence of a specific system software
or hardware option, such as floating point hardware or the presence of the
commercial instruction set.
Macro Call
FEAT$ sym
where:
is the symbol for the specified system feature.

8ym

The supported system feature symbols are:
Meaning

Symbol

Value

FE$EXT

22-Bit extended memory support

FE$PLA

PLAS calls supported

FE$LIB

18.

Supervisor mode library support

FE$UDS

37.

User data space supported

FE$FMP

59.

Fast mapping directive supported

HF$UBM

-1.

Processor has UNIBUS mapping registers

HF$EIS

-2.

Processor has Extended Instruction Set

HF$QB

-3.

Processor has a Q-BUS backplane

HF$DSP

-4.

Processor supports separate I & D spaces

HF$CIS

-8.

Processor supports Commercial Instruction Set

HF$FPP

-16.

Processor has NO floating point unit

Macro Expansion
FEAT$
. BYTE
. WORD

FE$FMP
177.,2

FE$FMP

;FEAT$ MACRO DIC, DPB size
;feature identifier

2 words

Locai Symbol Definitions
F.EAF

Feature identifier

DSW Return Codes
IS.CLR

Successful completion; feature not present (=0)

IS.SET

Successful completion; feature present (=2)

IE.ADP

Illegal DPB address

IE.SDP

Invalid DIC or feature identifier code

NOTE

The full list of RSX-ll/M-PLUS feature identifiers is not supported on
RSTSIE.

5-30

FEAT$

5.15 GLUN$ -

Get LUN Information

The GLUN$ directive fills a 6-word buffer with information about a physical
device unit to which a logical unit (LUN) is assigned.

Privileges Required
None

Macro Call
GLUN$ lun,buf
where:
lun

is the logical unit number.

buf

is the address of the 6-word buffer to receive the information.

Buffer Format
Mnemonic

Octal
Offset

Mnemonic

device name (2 ASCII characters)

o G.LUNA

device unit number

2 G.LUNU

first device characteristics word

4 G.LUCW

second device characteristics word

111111111111111111111

standard device buffer size

buf+O

is the name of the assigned device; two ASCII characters. This must be a
valid physical device name. Exceptions are the logical device names OV and
LB, which default to SY if they are not defined, and CL, which defaults to TT.

buf+2

is the unit number of the assigned device. If this word is minus one, it
indicates there is no unit number. If this word is zero or a positive number, it
is a real unit number.

buf+4

is the first device characteristics. The bit settings are:
Bit
Meaning When Set

Record-oriented device
1
Carriage-control device
Terminal device
2
3
Directory device
4
Single-directory device
5
Sequential device
6-15
Reserved
Settings for bits 0-5 are (in octal):
01 = Card reader
01 =Paper tape reader/punch
02 =Line printer
03 = Terminal
10 = Disk
40 = Magtape

GLUN$ 5-31

buf+6

is the privilege status. If this word is zero, it indicates the job is nonprivileged. If this word is eight, it indicates the job is privileged.

buf+12

is the standard device buffer size to use for input or output on this device.

Macro Expansion
GLUN$
. BYTE
. WORD
. WORD

7, LUNBUF
5,3
7

LUNBUF

;DIC = 5, DPB SIZE = 3 WORDS
;LOGICAL UNIT NUMBER 7
;ADDRESS of 6-WORD BUFFER

Local Symbol Definitions
G.LULU

Logical unit number (2)

G.LUBA

Buffer address (2)

The monitor assigns the following offsets relative to the start of the LUN information buffer:
G.LUNA

Device name (2)

G.LUNU

Device unit number (1)

G.LUFB

Flags byte (not used in RSTSIE) (1)

G.Luew

Four device characteristics words (8)

DSW Return Codes

5-32

GLUN$

Is.sue

Successful completion.

IE.ULN

Unassigned LUN.

IE.ILU

Invalid logical unit number (must be in range 1-14).

IE.SDP

DIC or DPB size is invalid.

5.16 GMCR$ -

Get MCR (CCl) Command Line

The GMCR$ directive transfers an 80-byte CCL command line to the job. The
program that processes an installed CCL command must contain code to analyze
what you typed to invoke the file. The GMCR$ directive returns the command
line you typed in an 80-byte buffer in the DPB.
If the CCL command line is longer than 80 bytes, the first 79 bytes followed by

a hyphen in position 80 is returned on the first call to GMCR$. A subsequent
call returns the remaining portion of the command line. The maximum CCL
command line length that can be retrieved via the GMCR$ call is 127. characters.
This directive has no $8 form. Because the DPB receives the CCL command line,
the space must be allocated in read/write memory.
Privileges Required

None
Macro Call

GMCR$
Macro Expansion
GMCR$
. BYTE
.BLKW

127.,41.
40.

;DIC = 127., DPB SIZE = 41. WORDS
;80-CHARACTER CCL COMMAND BUFFER

Local Symbol Definitions
G.MCRB

CCL command buffer (80)

DSW Return Codes
+n

Successful completion. The value n is the number of data bytes transferred
(excluding the termination character).

IE.AST

Task was not run as a CCL command or the GMCR$ directive has already
been executed.

IE.SDP

DIC or DPB size is invalid.

GMCR$

5-33

5.17 GPRT$ -

Get Partition (Job) Para.meters

The GPRT$ directive fills a 3-word buffer with partition parameters. For RSTSIE,
a partition corresponds to the job area.
Privileges Required

None
Macro Call

GPRT$ [namej,buf
where:
nante

is the partition name. Omit this parameter to get the actual job image size in
buf+2.

buf

is the address of the 3-word buffer where information is to be returned.

Buffer Format

Mnemonic

Octal
Offset

Mnemonic

virtual base address (always 0 in RSTS/E)

0 G.PRPB

user job image size in 32-word blocks

2 G.PRPS

flags word (always 0 in RSTS/E)

4 G.PRFW

nante

is the partition name. Omit name to get the actual job image size in buf+2.

buf+2

is the partition size (user job image size in RSTSIE), expressed as a multiple
of 32 words. If I&D Space is enabled, this reflects only the size of the D-Space
of the task. If you give a partition name, the system SWAP MAX is returned,
in 32-word units.

buf+4

is the partition flags word. Always returned as zero, since all jobs are systemcontrolled in RSTSIE. (RSX-llM returns one for a user-controlled partition.)

Macro Expansion
GPRT$
. BYTE
. WORD
. WORD

,DATBUF
65.,4
0,0

DATBUF

;DIC=65., DPB SIZE = 4
;GENERATE 0 WORDS IF NO NAME
;ADDRESS OF 3-WORD BUFFER

Local Symbol Definitions
G.PRPN

Partition name (4)

G.PRBA

Buffer address (2)

The monitor assigns the following offsets relative to the start of the buffer:

5-34

GPRT$

G.PRPB

Partition virtual base address (2)

G.PRPS

Partition size (2)

G.PRF

Partition flags word (2)

DSW Return Codes

Successful completion is indicated by carry clear, and the starting address of
the partition is returned in the DSW (always zero in RSTSIE). Unsuccessful
completion is indicated by carry set and the following code in the DSW:
ID.SDP

DIC or DPB size is invalid.

GPRT$

5-35

5.18 GTIM$ -

Get Time Parameters

The GTIM$ directive fills an 8-word buffer with the current day and time of day.
All time values are stored as one-word binary integers. The value ranges (in
decimal) are shown in the following diagram.
Privileges Required

None
Macro Call

GTIM$ buf
where:
buf

is the address of an 8-word buffer.

Buffer Format
Mnemonic

Octal
Offset

Mnemonic

year (since 1900); such as 78 =1978

0 G.TIYR

month (1-12); such as 1 = January

2 G.TIMO

day of month (1-31)

4 G.TIDA

hour (0-23); such as 0 = midnight

6 G.TIHR

minute (0-59)

10 G.TIMI

second (0-59)

12 G.TISC

tick of second

14 G.TICT

ticks per second

16 G.TlCP

G.TIBA+G.TICT

Indicates a tick which is either 1I60th or 1/50th of a second, depending on the clock in use and/or the line frequency. Systems
running with the KWllP clock at crystal speeds, rather than at line
frequency, or 11173, 11/83, 11/84, 11/93, or 11194 systems with 800
Hertz clocks, have a tick of 1/50th of a second. Otherwise, if the
system is operating with a 60 Hz power line, a tick is 1/60th of a
second.

Macro Expansion
GTIM$
. BYTE
. WORD

DATBUF
61. ,2

DATBUF

Local Symbol Definitions
G.TIBA

5-36

GTIM$

Buffer address (2)

;DIC = 61., DPB SIZE = 2 WORDS
;ADDRESS OF a-WORD BUFFER

The monitor assigns the following offsets relative to the start of the buffer:
G.TIYR

Year (2)

G.TIMO

Month (2)

G.TIDA

Day (2)

G.TIHR

Hour (2)

G.TIMI

Minute (2)

G.TISC

Second (2)

G.TICT

Clock tick of second (2)

G.TICP

Clock ticks per second (2)

DSW Return Codes
IS.SUC

Successful completion.

IE.SDP

DIe or DPB size is invalid.

GTIM$

5-37

5.19 GTSK$ -

Get Task (Job) Parameters

The GTSK$ directive fiUs a i6-word buffer with parameters for the task. As with
partition in GPRT$, a task in the RSTS/E environment is equivalent to the job.
Privileges Required

None
Macro Call
GTSK$ but
where:
buf

is the address of the 16-word buffer to receive the parameters.

Buffer Format
Mnemonic

Octal
Offset

Octal
Offset
task name
(2 words in RAD50 format)
partition name
(2 words in RAD50 format)

GTSK$

4 G.TSPN
6

I I I II I I I I I II I I I I I I II I

IIIIIIIIIIIIII IIIIIII

run priority (0-255)

14 G.TSPR

16 G.TSGC

G.TSPC 17

5-38

0 G.TSTN
2

Mnemonic

project number

programmer number

number of LUNs assigned

I I I II I I I I I II I I I I I I II I

I I I I I I I I I I I I I I I I I I II I

address of SST vector table

26 G.TSVA

length of SST vector table in words

size (in bytes) of memory for job image

system where job is running (4 = RSTS/E)

G.TSNL

G.TSVL

32 G.TSTS
34

G.TSSY

buf+O

is the task name. The name supplied for the TASK = name option at the
time the task was built (linked) with TKB; otherwise, the file name of the
file being run.

buf+4

is the partition name specified for the PAR = name option at the time the
task was built (linked) with TKB. If no such name was specified, the characters "GEN
" (GEN followed by three blanks), to indicate the general
partition, the default system-controlled partition in RSX-llM.

buf+14

is the run priority; may range from 0 to 255. This is the RSTS/E job priority
plus 128.

buf+16

is the programmer number of the user currently running the program.

buf+18

is the project number of the user currently running the program.

buf+20

is the number oflogical unit numbers (LUNs) currently assigned.

buf+26

is the address of the SST vector table. If buf+30 = 0, this word is meaningless.

buf+30

is the length of the SST vector table, in words. If there is no SST vector
table, this word is set to O.

buf+32

is the job size, in bytes. If I&D Space is enabled, this size reflects only the
D portion of the task.

buf+34

is the system in which the program/job/task is running:
0= RSX-llD
1 RSX-llM

2 =RSX-llS
3 =lAS
4 =RSTSIE
5 =VAXlVMS
6 = RSX-llM-PLUS
7 = RT-ll
This value is always 4 on RSTSIE systems.

Macro Expansion
GTSK$
• BYTE
• WORD

DATBUF
63. ,2
DATBUF

;DIC=63., DPB SIZE = 2 WORDS
;ADDRESS OF 16-WORD BUFFER

Local Symbol Definitions
G.TSBA

Buffer Address

The monitor assigns the following offsets relative to the buffer:
G.TSTN

Task name (4)

G.TSPN

Partition name (4)

G.TSPR

Priority (2)

G.TSGC

Programmer number (1)

G.TSPC

Project number (1)

G.TSNL

Number of logical units (2)

G.TSVA

SST vector address (2)

G.TSVL

Length of SST vector table (2)

G.TSTS

Size of space for user job image (2)

G.TSSY

System being run under (2)

DSW Return Codes
IS.SUC

Successful completion.

IE.SDP

DIC or DPB size is invalid.

GTSK$

5-39

5.20 MAP$ -

Map Address Window

The MAP$ directive maps a previously created address window to an attached
resident library. In other words, MAP$ relates the virtual address range defined
by a CRAW$ directive to actual locations in memory within a resident library
that has been attached to the job by an ATRG$ directive.
If the window specified is already mapped, it is unmapped from its previous

actual memory locations and remapped to the new area. A job may map a
maximum of seven address windows at any given time.
Privileges Required

None
Macro Call

MAP$adr
where:
adr

is the address of an 8-word area defining the window to be mapped. The MAP$
directive also returns information to this area. Two supplementary directives are
available to define (WDBDF$) or define and fill (WDBBK$) such an area, called
the Window Definition Block (WDB).

Macro Expansion
MAP $
. BYTE

WDBADR
121.,2

;DIC=121., DPB SIZE=2 WORDS

Data Passed in WOB
Mnemonic

Octal
Offset

//////////

5-40

MAP$

window 10

Mnemonic

0 W.NID

////1//////1///////1/

/ / / / 1/ / / / / / 1/ / / / / / / 1/

resident library 10

6 W.NRIO

offset, in 32-word blocks

10 W.NOFF

length, in 32-word blocks

12 W.NLEN

access flags

14 W.NSTS

////1//////1///////1/

adr+W.NID

is the ID of the window to be mapped (returned at the same location in
the WDB by the CRAW$ directive).

adr+W.NRID

is the ID of the resident library to which the window is to be mapped
(returned at offset R.GID in the RDB by the ATRG$ or CRRG$ directive that attached the job to the resident library).

adr+W.NOFF

is the offset, in 32-word blocks, from the start of the library where the
mapping is to begin. A value of zero for this word indicates that the
window is to be mapped beginning at the first byte of the library. A
value of one indicates that the window is to be mapped beginning at
the 33rd word of the library (starting address +64), and so forth. The
offset cannot indicate a starting address past the end of a library.

adr+W.NLEN

is the length, in 32-word blocks, to be mapped to the library. This value
cannot be greater than the size of the window defined in the CRAW$
directive with which the window was created. In addition, this value,
combined with the offset value at adr+ W.NOFF, cannot indicate an
address beyond the end of the library. A value of zero for this word
defaults to the size of the window or the space remaining in the library,
whichever is smaller.

adr+W.NSTS

is the access flag. When bit 1 (WS.WRT) is set, read/write access is
allowed. A separate setting for access in MAP$ and in ATRG$ lets
you attach to a library read/write and map a portion of the library
read-only. You cannot, however, attach to a library read-only and then
map to the library read/write.
WDBDF$,
WDBBK$
Mnemonic

Bit

WS.64B

WS.WRT

Meaning

The task's permitted alignment boundaries defined as 32 words.

The task's permitted alignment boundaries defined as 256 words.

Read/write access is desired

Read-only access is desired

Data Returned in WDB
Mnemonic

Octal
Offset

Mnemonic

111111111111111111111

I I I I I II I I I I I II I I I I II I

111111111111111111111

length actually mapped

12 W.NLEN

status flags

14 W.NSTS

I I I I II I I I I I I II I I I I I I I

adr+W.NLEN

is the length, in 32-word blocks, mapped by the call.

adr+W.NSTS

are the status flags. Bit 14 (WS.UNM) indicates, when set, if the
window specified was unmapped before the new map.

Local Symbol Definitions
M.APBA

Window Definition Block address (2)

MAP$

5-41

DSW Return Codes

5.20.0.1

Is.sue

Successful completion.

IE.ALG

The offset and length specified are inconsistent; either the mapping att.empted
to go beyond the end of the library, or the length is greater than the created
window.

IE.PRI

The mapping did not succeed because user privileges did not allow the access
desired.

IE.NVW

Either the resident library ID or the address window ID is incorrect. (That is,
the job is not currently attached to the specified resident library, or no address
window has been created with the specified window ID.)

Fast-Mapping Facility

You may want to use the fast-mapping facility instead of the MAP$ directive.
It enhances performance and is compatible with the fast-mapping facility of
RSX-llM-PLUS. The RSTS/E RSX emulator also provides the following features:
•

The Task Builder IFM switch.

4!J

The TFEA$ RSX monitor call can ten a program if fast-mapping is enabled.

•

The .SET and .CLEAR monitor calls allow a task to enable and disable
fast-ma pping.

parameter 1
parameter 2
parameter 3

lOT

see table of APR parameter values
offset field, 32 decimal words from library base
optional length specification (if used, bit 15
in RO must =1)
calls the monitor to execute mapping

Returned Data
RO

Status

length mapped
Rl & R3

IS.SUC if successful
IE.TIS or IE.ALG if unsuccessful
if successful length actually mapped in slivers
indeterminate

Table of Parameter Values

5-42

MAP$

If No Length
Given

If
Length
Given

Space

Base
APR

User-I

000010

100010

User-I

000020

100020

APR 1-0 cannot
be changed

User-I

000030

100030

User-I

000040

100040

User-I

000050

100050

User-I

000060

100060

If
Length
Given

100070

Space

APR

If No Length
Given

User-I

000070

User-D

User-D
User-D

1
2

000110
000120

User-D

000130

User-D

4
5

000140

100140

User-D

000150

100150

User-D

000160

100160

User-D

000170

100170

Base

APR D-O cannot
be changed

100110
100120
100130

The fast-mapping facility has the following requirements:
•

The fast-mapping facility can modify only the map field (FQSIZE) and,
optionally, the length to the map field (FQBUFL).

•

The interface uses the lOT instruction. Tasks that use fast-mapping cannot
use the lOT instruction for any other purpose.

•

The interface uses registers to pass parameters instead of using a FIRQB.
This means that the MACRO-ll programmer must be careful about register
use when fast-mapping.

Examples

Change the window offset in an I-Space library:
MOV
MOV

#60,RO
#200,R1

lOT
TST
BMl

RO
ERROR

;l-Space window in APR 6
;offset 4K words from the beginning of library
;R2 not used
;do the re-map
;any errors?
;if minus yes, otherwise ok

Change the D-Space window offset and the actual window length:
MOV
MOV
MOV
lOT
TST
BMl

#100150,RO
#400,Rl
#500,R2
RO
ERROR

;O-Space window in APR 5, length to be given
;offset 8K words from library base
;length to be 10K words (use APR 5,6 &7)
;issue instruction
;any errors?
;if minus yes, otherwise ok

MAP$ 5-43

5.21

MSDS$-Map Supervisor Mode D-Space
The MSDS$ directive allows a task to change the mapping of its supervisor mode
D-Space APRs. This directive can also provide information about the current
mapping of the task's supervisor mode D-Space APRs, or about a library's current
mode.
Normally, when supervisor mode library code is executing, the supervisor mode
I-Space APRs map supervisor mode instruction space, and the supervisor mode
D-Space APRs map the User mode D-Space. However, code that resides in a
supervisor mode library may need to use its instruction space as data space for
such items as error messages or other text. The Map supervisor Data Space
directive allows such code to overmap the supervisor D-Space and the supervisor
I-Space on an APR by APR basis. This overmapping can be used with tasks built
using separate I-Space and D-Space mapping.
The Map Supervisor D-Space directive allows the task to specify a 7-bit mask that
determines which space each supervisor D-Space APR will use. The mask value
contains one bit for each APR beginning at APRl. Supervisor mode D-APRO must
overmap user mode D-APRO at all times and therefore is not included in the
mask value.
On the return from the MSDS$ call, the current supervisor mode D-Space
mapping mask is returned along with the high byte (mode bits) of the PSw. If
bit 15 of the mask value is set to 1 on the call, no change occurs to supervisor
mapping but existing mapping is returned.
The MSDS$ call is designed to be executed from within the library whose
mapping it alters. This allows a library to determine its current mode from the
PSW mode bits returned. Further, if the MSDS$ call is issued from user mode
rather than supervisor mode, no mapping change occurs. The call simply returns
the mapping data and PSW contents. Note that the MSDS$ call returns only
the supervisor mode mapping status. If the library is in user mode, no useful
mapping data is returned. Normally, a library in user mode will have its D-Space
already mapped to user mode D-Space unless the task builder or the program has
taken some overt action to re-map the D-Space.
Digital recommends that you place all required data at the highest addresses in
the library. Not only does this remove it from the APRO restriction in supervisor
mode, but also allows the library to make proper use of the EXTM$ directive (see
the RSTS / E Task Builder Reference Manual) when used in user mode.

Privileges Required
None

5-44

MSDS$

Macro Call
MSDS$

mask

where:
mask

is a 7-bit APR mask plus an action flag, formatted as follows:

Bit

~e~g

0-7

Set to 0 on input. Set to PSW high-order byte on return.

APR 1 mapping switch. If 1, then supervisor mode D-Space equals
supervisor mode I-Space.

APR 2 mapping switch. If 1, then supervisor mode D-Space equals
supervisor mode I-Space.

APR 3 mapping switch. If 1, then supervisor mode D-Space equals
supervisor mode I-Space.

APR 4 mapping switch. If 1, then supervisor mode D-Space equals
supervisor mode I-Space.

APR 5 mapping switch. If 1, then supervisor mode D-Space equals
User mode D-Space.

APR 6 mapping switch. If 1, then supervisor mode D-Space equals
supervisor mode I-Space.

APR 7 mapping switch. If 1, then supervisor mode D-Space equals
supervisor mode I-Space.

Action flag. If 0, then set mapping. If 1, then report current supervisor mode D-Space mapping (no changes). If issued from user mode,
flag is forced to 1.

Macro Expansion
.MACRO
.BYTE
. WORD
.ENDM

MSDS$
201.,2
mask

mask
;MSDS$ DIC code, DPB size= 2 words

Error codes
IE.SDP

DIe or DPB size is invalid

MSDS$ 5-45

Example
;+
; This is sample code that might exist in a supervisor library
; for the purpose of printing error messages.
;-

TST
BPL

(RO)
DATAOK

;test some piece of user data
;skip next if data ok

MSDS$S
MOV
MOV

4/:100000
$DSW,RO
RO,-(SP)

;get current mapping state

BIS
MSDS$S

#400,RO
RO

;update mask to map APRI to super I
;change the mapping

MOV
CALL

#MESSAG,Rl
OUTMSG

MOV
MSDS$S

(SP) +, RO
RO

;pointer to error message which is data
;call a routine in super mode to output
;text data message
;get back the original mapping state
;now back to the original state

;save for future restoration

;+
Somewhere in APR 1 of supervisor library:
MESSAG: .ASCIZ

5-46

MSDS$

IError in datal

5.22 QIO$ and QIOW$ -

Queue I/O Request (and Wait)

The QIO$ and QIOW$ directives do non-file-structured I/O. In the RSX emulation
mode environment, QIO$ and QIOW$ do the same thing. I/O is synchronous in
this environment. That is, you cannot request I/O, do other processing, and get
an interrupt when the I/O completes. In RSX emulation mode, control returns to
the program only when the 110 is complete.
As non-file-structured implies, the QIO$ and QIOW$ directives are useful for I/O
on a terminal, card reader, or line printer.
Privileges Required

See discussion
Macro Call
{

QIO$

}
fnc,lun,[efnj,[prij,[isb],[astj['parj

QIOW$

where:
is the 110 function code:
IO.AIT
Attach. In RSTSIE, opens the device specified by the logical unit
number (lun).

fnc

IO.DET

Detach. In RSTSIE, closes the device specified by the logical unit
number (lun).

ro.RAL

For terminals only, performs a read in ODT mode (see .ITDDT in
Chapter 3).

IO.RLB
IO.RVB

Read. IO.RLB and IO.RVB do the same thing in RSTSIE. The
actions performed depend on the device (see the section "Format and
Description by Function Code").

IO.WAL

For terminals only, performs a write in binary mode (see RECORD
4096% for terminal output, RSTS / E Programming Manual).

IO.WLB

Write. IO.WLB and IO.WVB do the same thing in

IO.WVB

RSTSIE. The actions performed depend on the device (see the section
"Format and Description by Function Code").

lun

is the logical unit number; defines the device for which the 110 operation is to be
performed. Must have been previously defined with an ALUN$ directive.

efn

is the event flag. (The RSX emulator ignores this parameter.)

pri

is the priority. (The RSX emulator ignores this parameter.)

isb

is the 110 status block. Address of a 2-word buffer to which information is
returned about the outcome of the 110 operation. The contents vary according to
the function code and device, as the following describes.

ast

is the asynchronous exception address. (The RSX emulator ignores this parameter.)

par

is the parameter list. Of the form <pl,p2[""p3]> for RSTSIE users. Form and
meaning varies according to function code and device, as the following describes.

Format and Description by Function Code
{

QIO$
QIOW$

}
IO.AIT,lun[",isb]

010$ and OIOW$

5-47

Opens the device specified by the logical unit number (lun). Status information
is returned to the 2-word buffer at address isb. If the device is restricted, this
function requires DEVICE privilege.
{

QIO$

}
IO.DET,lun[",isb]

QIOW$

Closes the device specified by the logical unit number (lun). Status information is
returned to the 2-word buffer at address isb. This function does not require any
privileges.
{

QIO$

}

{

QIOW$

IO.RLB }
IO.RVB

,lun",[isb],,<stadd,size [",block]>

For record-oriented devices in the RSX-llM environment (see GLUN$), 10.RLB
and 10.RVB return a record (a line on a terminal, card on a card reader, record
on a paper tape reader). The data is read into the buffer whose starting address
is defined by stadd and whose length in bytes is defined by size. The amount
of data read never exceeds the buffer size. If the buffer size is smaller than the
record, the next 10.RLB or 10.RVB for that lun reads another buffer-full. The
block parameter is omitted for these devices.
For disk, 10.RLB and 10.RVB fill the buffer whose starting address is defined
by stadd and whose length in bytes is defined by size. The read begins with the
device cluster number specified by the block parameter. If block is omitted or 0,
sequential reads are performed and the next read begins with the next device
cluster. The buffer size should be a multiple of the device cluster size for the disk
(see Appendix B).
NOTE

Only jobs with the necessary privileges can do non-file-structured disk
I/O. RDNFS privilege is required for read-only and WRTNFS privilege
is required for read/write non-file-structured disk I/O.
For all devices, the isb parameter is the address of a 2-word buffer to which
status information on the read is returned. If isb is omitted, no such status is
returned.
{

QIO
QIOW$

}

{

IO.WLB }
IO.WVB

,lun",[isb],,<stadd, size[,vfcJ>

For record-oriented devices in the RSX-llM environment (see GLUN$), 10.WLB
and 10.WVB write the contents of the buffer to the device specified by the logical
unit number (lun). The starting address for the buffer is defined by stadd, and
the length in bytes is defined by size. For record-oriented and carriage-controlled
devices, the ute parameter specifies an action to be performed after the buffer
contents are written. (The ufc parameter is a vertical format control character for
terminals and line printers.)

5-48

010$ and OIOW$

Table 5-2 lists the values for ufc and the actions taken. The ufc parameter is
omitted for non-carnage-controlled devices.
Table 5-2:

Vertical Format Control Characters

Octal
Value

Character

Meaning

040

blank

Single space--Output a line feed, print the contents of the
buffer, and output a carriage return. Normally, printing
immediately follows the previously printed line.

060

Double space--Output two line feeds, print the contents
of the buffer, and output a carriage return. Normally, the
buffer contents are printed two lines below the previously
printed line.

061

Page eject-Output a form feed, print the contents of the
buffer, and output a carriage return.

053

Overprint-Print the contents of the buffer and output a
carriage return. Normally overprints the previous line.

044

Prompting output-Output a line feed and print the contents of the buffer. This mode of output is intended for use
with a terminal on which a prompt message is output and
input is then read on the same line.

000

null

Internal vertical format-Print the buffer contents without
adding vertical format control characters. In this mode,
more than one line of guaranteed contiguous output can be
printed for each I/O request.

For disk, IO.WLB and IO.WVB write the contents of the buffer to disk, beginning
at the device cluster number specified by the block parameter. If block is omitted,
sequential writes are performed. The next write (for sequential writes) begins
with the next device cluster. The buffer size must be a multiple of the device
cluster size.
NOTE

No job can write to disk in non-file-structured mode while any other
user is accessing the disk.
For all devices, the isb parameter defines the starting address of a 2-word buffer
to which status information on the write is to be returned. If you omit isb, no
such status information is returned.
Contents of 1/0 Status Buffer

The general format of the information returned to the 2-word status buffer
defined by isb is:

(terminal I/O code)

general I/O code

number of bytes read or written

The first word contains information on the success or failure of the I/O operation
requested. As with $DSW, you can use mnemonic codes to test this word. The
Task Builder resolves the mnemonics automatically.

010$ and OIOW$

5-49

For all devices and operations except terminal reads, you test the low-order byte
of the first word to determine the 1/0 status code. Successful terminal reads
provide additional information on what character terminated the line typed at the
terminal. For terminal reads, you test the low-order byte first to see if the read
was successful (IS.SUC). If it was, you can then test the entire first word to find
out if the line was terminated with a carriage return (IS.CR) or an ESC character
(IS.ESC), which is called ALTMODE on some terminals.
The second word of the block contains the number of bytes read or written, if the
read or write was successful. No information is returned in this word for 10.ATT
and 10.DET operations.
The following section describes the 110 return codes. IS.CR and IS.ESC are
full-word values; the others are tested by the low-order byte only.
NOTE

The RSX emulator does the requested 110 operation using the non-filestructured OPNFQ subfunction of CALFlp, the CLSFQ subfunction
of CALFlp, .READ, and .WRITE. It does not clear the FIRQB or XRB
when it returns control to the user program. The codes given in square
brackets [] are the RSTSIE errors that are returned to the emulator.
You can do further checking in the case of IE.BAD, for example, by
checking byte 0 of the FIRQB.
Return Codes
IS.SUC

Successful completion of I/O operation. For terminal reads, you can determine
the terminating character of the line by testing the full first word of the I/O
status buffer for:
The terminal line was terminated with a carriage return/line
IS.CR
feed combination. (The terminating characters are not included
in the character count in the second word. They do appear in the
input buffer.)
IS.ESC

5-50

The terminal line was terminated with an ESC (called
ALTMODE on some terminals). (The terminating character
is not included in the character count in the second word. It does
appear in the input buffer.)

IE.BAD

This code is returned by the RSX emulator when an error occurs on the
I/O operation that did not fit into any of the error categories diagnosed. To
determine the RSTSIE error, examine byte 0 of the FIRQB.

IE.DAA

An open (iO.ATT) was attempted for a device that this job has already opened.
The device must be closed (IO.DET) before it can be opened again. [NOTCLS]

IE.DNR

Some hard device I/O error occurred (a read for an off-line device, a write for
a physically write-locked device, and so forth). [HNGDEV]

IE.EOF

An end-of-file (EOF) mark, record, or control character (CtrllZ for terminals)
was recognized on a read operation. [EOF]

IE.EOT

No more room is available on the device for a write operation (end of paper tape, end of magtape, not enough disk space available, and so forth).
[NOROOM]

IE.PRI

Privilege violation. A job with insufficient privileges attempted to read or
write to disk while the disk was in use. [PRVIOL]

IE.NLN

A close (IO.DET) was attempted for a device that was not open. [NOTOPN]

IE.RSU

Shareable resource in use. The device is not available; it is assigned to
another user. [NOTAVL]

010$ and OIOW$

IE.VER

Unrecoverable error, such as parity error, bad card column, and so forth.
[DATERR]

Macro Expansion
QIO$
. BYTE
. WORD
. WORD
. BYTE
. WORD
. WORD
. WORD
. WORD
. WORD
. WORD
. WORD
. WORD

IO.RVB,7",IOSTAT,,<IOBUFR,80.>
1,12.
;DIC=1, DPB SIZE = 12. WORDS
IO.RVB
;FUNCTION CODE FOR READ
7
;LOGICAL UNIT NUMBER 7
0,0
;EFN,PRI IGNORED IN RSTS/E
;1/0 STATUS BUFFER
IOSTAT
o
;AST IGNORED IN RSTS/E
IOBUFR
: BUFFER ADDRESS
80.
;BYTE COUNT = 80 .
o
;NO VFC NEEDED FOR READ
o
;THIS PARAM. IGNORED IN RSTS/E
o
;THIS PARAM. IGNORED IN RSTS/E
o
;NO BLOCK FOR THIS INVOCATION

The expansion for QIOW$ is the same except that the DIe = 3.
Local Symbol Definitions
Q.IOFN

1/0 function code (2)

Q.IOLU

Logical unit number (2)

Q.IOEF

Event flag number (1)

Q.IOPR

Priority (1)

Q.IOSB

Address of I/O status block (2)

Q.IOAE

AST address (2)

Q.IOPL

Parameter list (6 words) (12)

DSW Return Codes

Is.sue

Successful completion.

IE.LUN

Unassigned logical unit number (lun). Use ALUN$.

IE.ILU

Invalid logical unit number (lun). Must be in the range 0 to 14.

IE.SDP

DIC or DPB size is invalid.

010$ and OIOW$ 5-51

5.23 RDBBK$ and RDBDF$-Define and Fill RDBs
Two directives are available for use with resident library definition blocks (RDBs):
RDBDF$ and RDBBK$.
The RDBDF$ directive assigns literal values to the offsets and status bit
mnemonics shown for the RDB areas for the ATRG$ and DTRG$ directives. You
can use these mnemonics to reference offsets and bit values in an RDB you have
allocated space for in your program.
The RDBBK$ directive defines these offsets and, in addition, generates code to
allocate space for the RDB and fills it with values you specify in the call.
Privileges Required
[Not applicable]
Macro Call
RDBBK$
or

size,libnam"status, pricde (for read/write access)

RDBBK$

size,libnam"status,prtcde (for read-only access)

where:
slze

is the size of the dynamic region to create, if defining a RDB to create a
dynamic region.

libnam

is the name of the resident library to be attached or the dynamic region to
be created.

status

is the region status to be placed in the RDB. The following are defined
status bits:
RS.ATT
When creating a dynamic region, setting this bit indicates
that the user wants the region attached on creation. Note
that RSTS/E forces this bit to be set when creating an unnamed dynamic region.

pricde

RS.MDL

When creating a dynamic region, setting this bit indicates
that the region is automatically removed on the last detach.
Note that RSTS/E forces this bit to be set when creating an
unnamed dynamic region.

RS.NDL

When creating a dynamic region, setting this bit indicates
that the region is not automatically removed on the last
detach. Note that RSTS/E forces this bit to be set when
creating an unnamed dynamic region.

RS.RED

Map with read-only access to library. (for ATRG$)

RS.WRT

Map with read/write access to library. (for ATRG$)

is the protection code (in RSX format) of the dynamic region to be created.

Macro Expansion
RDBBK$
. WORD
. WORD
.RADSO
. WORD
. WORD
. WORD
. WORD

SIZE,DATLIB,,<RS.WRT>,167000
0
SIZE
/DATLIB/
0
0
RS.WRT
167000

(RS.WRT is assigned to a literal value of two, so bit 1 is set in the seventh word
of the RDB, requesting read/write access.)
5-52

RDBBK$ and RDBDF$

In addition, all the offsets necessary to reference the data returned in the RDB
by ATRG$ or DTRG$ are generated. For example, you can use the mnemonic
RS.UNM to test bit 14 of the word at offset R.GSTS in the RDB after execution of
a DTRG$ directive. RS.UNM is assigned to a literal value of 40000 (octal) by the
RDBBK$ directive.

RDBBK$ and RDBDF$

5-53

5.24 SCCA$S -

Specify Control/e AST

The SCCA$S directive (actually, a macro) lets you specify an address to which
control is to be transferred if the user types a CtrllC while the program is
executing. Only the $S form is allowed, because no DPB is ever generated. The
SCCA$S directive is unique to the RSTSIE environment; no similar directive
exists for the RSX-llM operating system.
The SCCA$S expands to code that takes the address specified and stores it in
location 24 (part of the first 512 bytes of memory used by the run-time system;
see Chapter 4). The RSX run-time system checks this location when a CtrllC
asynchronous exception occurs, and if it is nonzero, clears the word and transfers
control to the location that was specified. If this word is zero, the RSX run-time
system falls back to its own processing of CtrllC exceptions. Thus, SCCA$S is a
one-time operation; you must reset the handler as part of the exception-processing
routine, if desired.
Your routine can handle the CtrllC in any way it sees fit. The CtrllC routine
should be exited with the use of the SSTX$ macro. This will return control back
to the point where it left off at the time of the exception. If the task is going to
use a library in supervisor mode, the SSTX$ exit is required.
The trap service routine for SCCA$S may be in either user space or supervisor
space. This is determined in bit 0 of the service vector. If bit 0 is set, the service
routine is in supervisor space; if bit 0 is clear, the service routine is in user space.
Privileges Required

None
Macro Call

SCCA$S [arg]
where:
arg

contains the address (usually specified in the form "#addr") to which control
passes if the user enters a CtrllC combination at the job's terminal. Word 24 is
cleared, indicating that the RSX run-time system is to handle such traps.

Macro Expansion
SCCA$S
MOV

#CTRAP
#CTRAP,@#24

If you omit the address, the expansion is:
SCCA$S
CLR

@#24

Local Symbol Definitions

None
DSW Return Codes

None. (SCCA$S does not execute an EMT; control does not pass to the RSX
emulator when SCCA$S is executed.)

5-54

SCCA$S

5.25 SFPA$ - Specify Floating-Point-Processor Exception
Address
The. SFPA$ directive tells the RSX emulator one of two things:
•

The job wants to handle FPP exceptions itself. The RSX emulator passes
control to the address specified in the directive when such an asynchronous
exception occurs.
The FPP available on all PDP-ll processors that can run RSTSIE, except the
PDP-1l/35 and 40. The FPP executes concurrently with the PDP-ll central
processor. Thus, an error in the FPP unit occurs asynchronously with the
execution of the PDP-ll CPU.

•

The job does not want to handle FPP exceptions. The address is omitted in
the directive. In this case, if an FPP exception occurs, the RSX emulator
aborts the job, and displays the error message ??Reserved instruction trap on
the job's terminal (TI:).

If you specify an address in the SFPA$ directive, control passes to the address
when an FPP exception occurs. The stack has the following information:
SP->

FEA
FEC
(DSW) at the time the exception occurred
(PC) at the time the exception occurred
(PS) at the time the exception occurred
word to which SP pointed before the exception

Your routine can process the exception in any way it sees fit. 'lb exit from the
exception-handling routine, pop the FEA and FEC from the stack and issue an
ASTX$ directive.
Privileges Required

None
Macro Call

SFPA$ [add]
where:
add

is the address to which control passes when an FPP exception occurs.

Macro Expansion
SFPA$
. BYTE
. WORD

FLTAST
111.,2
FLTAST

;DIC = 111., DPB SIZE = 2 WORDS
;ADDRESS OF FLOATING POINT AST

Local Symbol Definitions

S.FPAE Exception handler entry address (2)
DSW Return Codes
IS.SUC

Successful completion.

IE.SDP

DIC or DPB size is invalid.

SFPA$ 5-55

5.26 SPND$S -

Suspend

The SPND$S directive instructs the system to suspend the execution of the
issuing program. A program can only suspend itself; it cannot suspend any other
program. The program is restarted when the user types anything terminated by
a RETURN or other delimiter (for example, LINE FEED).
NOTE

RSTS/E implements this directive using the .READ directive to the
job's terminal (channel 0). Thus, if you are using special terminal
modes (binary input, echo control, and so forth), the SPND$S directive
clears these modes.
Because this directive requires only a l-word DPB, Digital recommends the $S
form of the macro. It requires less space and runs with the same speed as the
DIR$ macro.
Privileges Required

None
Macro Call

SPND$S [err]
where:
err

is the error routine address.

Macro Expansion
SPND$S
MOV
. BYTE
EMT
BCC
JSR

ERR
(PC)+,-(SP)
45.,1
377
.+6
PC, ERR

;PUSH DPB ONTO THE STACK
;SPND$S MACRO DIC, DPB SIZE=l WORD
; TRAP TO THE EMULATOR
;BRANCH IF DIRECTIVE SUCCESSFUL
;OTHERWISE, CALL ROUTINE "ERR"

Local Symbol Definitions

None
DSW Return Codes
IS.SPO

5-56

SPND$S

Successful completion; that is, the task was suspended.

IE.ADP

Part of the OPB is out of the issuing task's address space.

IE.SOP

OIC or OPB size is invalid.

5.27 SSTX$ -

System Synchronous Trap Exit

You can use the SSTX.$ directive to tenninate a routine that handles a synchronous system trap such as BPT and CtrllC exceptions, only if the program has
indicated its intention to handle such traps with a SVTK$ or SVDB$ directive.
When the SSTX$ is issued, control is returned to the point where the program
left off at the time of the trap.
If the task also uses supervisor mode libraries, then the SSTX$ is the required
exit from any synchronous trap service routine. There is no equivalent directive
in RSX-lllM-PLUS.
If the trap was a memory protection violation, the service routine must remove
the additional memory register infonnation from the stack before issuing the
SSTX$ directive.

Privileges Required
None

Macro Call
SSTX$

Macro Expansion

10$:

TST
BPL
RTI

2(SP)
10$

;Is this a user or super return?
;Super!
;User

CSM

;So, return to supervision mode via Digital Standard.

Local Symbol Definitions
None

DSW Return Codes
None. (SSTX.$ does not execute an EMT; control does not pass to the RSX
emulator when SSTX.$ is executed.)
NOTE

The SSTX$ call, when used with supervisor mode, is supported only
when the Digital-supplied Supervision Linkage modules are used.

SSTX$ 5-57

5.28 SVDB$ -

Specify SST Vector Table for Debugging Aid

The SVDB$ directive, like the SVTK$ directive, defines a table of addresses to
which control is to pass when certain synchronous exceptions occur. When a
synchronous exception occurs, the RSX emulator first checks the table defined
with SVDB$ to see if an address has been specified for that trap. If so, control is
passed to that address. If not, the emulator then checks the table defined with
SVTK$ (if any).
In other words, the SVDB$ sets up an SST vector table whose entries, if
nonzero, override (but do not destroy) any SST vector table entries defined with
SVTK$. The SVDB$ directive is useful within a debugging routine that uses
BPT instructions (for example, to set breakpoints). With SVDB$, the debugging
routine can divert breakpoint traps to itself, regardless of SVTK$ directives in
other modules of the job.
For example, the Octal Debugging Tool (ODT) object module uses the SVDB$
directive to divert exceptions to itself, regardless of what may have been
requested with SVTK$ in other modules. This makes it possible to debug
without changing your source code; you can link with ODT, use ODT to insert
breakpoints, test and debug, and when finished, relink without ODT. Note that
it is not necessary to change source code to debug, only to relink: the SVDB$
directive makes this possible.
NOTE

The ODT object module (the file ODT.OBJ) can be linked to user
modules with the RSTSIE Task Builder (TKB) using the IDA switch, as
described in the RSTS/E Task Builder Reference Manual. ODT.OBJ is
different from ODT.BAC, which is a BASIC-PLUS utility in RSTSIE.
The commands and syntax for ODT.OBJ are described in the RSX/IAS
ODT Reference Manual.
To avoid interfering \vith ODT, do not use the SVDB$ directive in a
user program.
See also Chapter 3, the section "Trap Handling with Supervisor Mode," which is
the last section in the chapter.
Privileges Required

None
Macro Call

SVDB$ [adr,lenJ
where:

5-58

SVDB$

adr

is the address of the SST vector table. If adr and len are both omitted, any SST
vector table previously defined with an SVDB$ directive will be deassigned; that
is, the emulator will not check for SVDB$ addresses. (A previously executed
SVTK$ remains in effect.)

len

is the length of the SST vector table, in words. You can specifY up to eight
addresses. If you want to use only the third, you could save space by using a len
of three, rather than a len of eight and filling the last five words of the buffer
with zeros. SpecifYing a length greater than eight has the same effect as a length
of eight.

Vector Table Format

A nonzero value for a word is the address to which control passes when that
particular exception occurs. A zero value for a word indicates that you have no
interest in handling that exception. Should such a exception occur, the emulator
checks the vector table assigned by SVTK$, if any. If there is no SVTK$ vector
table, the emulator aborts the job and displays an error message at the job's
terminal.
Octal
Offset

Octal
Offset
odd address or nonexistent memory error

memory protection violation

T -bit trap or execution of a BPT instr.

execution of an lOT instruction

execution of a reserved instruction

13 execution of a non-RSX. non-RSTS EMT instr.

execution of a TRAP instruction

PDP-11/40 FPP exception

Macro Expansion
SvnB$
. BYTE
. WORD
. WORD

SSTTBL,3
103. ,3
SSTTBL
3

;DIC=103. ,DPB SIZE = 3 WORDS
;ADDRESS OF SST TABLE
;SST TABLE LENGTH = 3 WORDS

Local Symbol Definitions
S.VDTA

Table address (2)

S.VDTL

Table length (2)

DSW Return Codes
IS.SUC

Successful completion.

IE.SDP

DIC or DPB size is invalid.

SVDB$

5-59

5.29 SVTK$ -

Specify SST Vector Table for Task

The SVTK$ directive, like the SVDB$ directive, defines a table of addresses
to which control passes when certain synchronous exceptions occur. When a
synchronous exception occurs, the RSX emulator first checks to see if a similar
table has been defined for this job with an SVDB$ directive. If so, any nonzero
entries in that table override those defined with an SVTK$ directive.
See also Chapter 3, the section "Trap Handling with Supervisor Mode," which is
the last section in in the chapter.
Privileges Required

None
Macro Call

SVTK$ [adr,lenl
where:
adr

is the address of the SST vector table. If you omit both adr and len, any SST vector table previously defined with an SVTK$ directive is deassigned. (A previously
executed SVDB$ remains in effect.)

len

is the length of the SST vector table, in words. You can specify up to eight
addresses. If you want to use only the first five, you could save space by using a
len of five, rather than a len of eight and filling the last three words of the buffer
with zeros. Specifying a length greater than eight has the same effect as a length
of eight.

Vector Table Format

A nonzero value for a word is the address to which control passes when that
particular trap occurs. A zero value for a word indicates that you have no interest
in handling that exception.
Octal
Offset

5-60 SVTK$

Octal
Offset
odd address or nonexistent memory error

memory protection violation

T -bit trap or execution of a BPT instr.

execution of an lOT instruction

execution of a reserved instruction

13 execution of a non-RSX, non-RSTS EMT instr.

execution of a TRAP instruction

PDP-11/40 FPP exception

The contents of the program status register and the program counter CPS and PC)
at the time of the exception have been pushed on the stack when the exceptionhandling routine is entered. Certain other values may have been pushed on
the stack. The values depend on the exception. If the exception was a memory
protect violation, the stack contains:
(SP) ->

Instruction backup register (SRI)
Virtual PC of the faulting instruction (SR2)
Memory protect status register (SRO)
(PC) at time of exception
(PS) at time of exception
NOTE

The RSX emulator returns zero for SRO and SRI; SR2 contains the PC
at the time of the exception.
If the exception was a TRAP instruction or EMT other than 377, the stack
contains:

(SP) ->

Instruction operand (low-order byte) times 2, high-order bits cleared
(PC) at time of exception
(PS) at time of exception

An items except the (PS) and (PC) must be popped from the stack before the
exception-handling routine exits. You can then return control to the point where
execution left off with an RTI or RTT instruction.
Macro Expansion
SVTK$
. BYTE
. WORD
. WORD

SSTTBL,4
105.,3
SSTTBL
4

;Dle = 105., DPB LENGTH = 3 WORDS
;ADDRESS OF SST TABLE
;SET TABLE LENGTH = 4 WORDS

Local Symbol Definitions
S.V'ITA
S.V'ITL

Table address (2)
Table length (2)

DSW Return Codes
IS.SUC
IE.SDP

Successful completion.
DIe or DPB size is invalid.

SVTK$

5~1

5.30 TFEA$ -

Test for Task Feature

The TFEA$ directive tests for the presence of a task specific software option,
such as fast-mapping turned on by the IFM switch in the TKB when the task was
built.
Macro Call

TFEA$ sym
where:
is the symbol for the specified task feature.

sym

The supported task feature symbols are:
Symbol

Value

Meaning

T2$DST

15.

AST recognition disabled (IS.SET=disabled)

T4$DSP

34.

Task was built lID or has turned I&D on

T4$FMP

40.

Task has fast mapping turned on

Macro Expansion
TFEA$
. BYTE
. WORD

T4$FMP
177.,2

T4$FMP

;TFEA$ MACRO DIC, DPB size
;feature identifier

2 words

Local Symbol Definitions
F.TEAF

Feature identifier

DSW Return Codes
IS.CLR

Successful completion; feature not present (=0)

IS.SET

Successful completion; feature present (=2)

IE.ADP

Illegal DPB address

IE.SDP

Invalid DIC or feature identifier code

NOTE

The fun list of RSX-ll/M-PLUS feature identifiers is not supported on
RSTSIE.

5-62

TFEA$

5.31

UMAP$ -

Unmap an Address Window

The UMAP$ unmaps a specified address window from a resident library. The
unmapping does not eliminate the window (created with a CRAW$ directive) or
release the APRs used by the window. The virtual address window can now be
remapped to new actual memory locations with the MAP$ directive.
Privileges Required

None
Macro Call

UMAP$adr
where:
adr

is the address of an 8-word area defining the window to be unmapped. The
UMAP$ directive also returns information to this area. Two supplementary
directives are available to define (WDBDF$) or define and fill (WDBBK$) such an
area, called the window definition block, or WDB.

Macro Expansion
WDBADR
123.,2
WDBADR

UMAP$
• BYTE
. WORD

;DIC=123., DPB SIZE=2 WORDS

Data Passed in WDe
Mnemonic

Octal
Offset

1111111111

window 10

0 W.NIO

111111111111111111111

adr+W.NID

Mnemonic

is the ID of the window to be unmapped (returned at the same location
in the WDB by the CRAW$ directive).

UMAP$ 5--63

Data Returned in WDB
Mnemonic

Octal
Offset

/ / / / / II / / / / / / / / / / / / / /

/ / / / / II / / / / / II / / / / / / /

/ / / / / II / / / / / / / / / / / / / /

/ / / / / II / / / / / II / / / / / / /

status flag

/ / / / / II / / / / / / / / / / / / / /

adr+W.NSTS

Mnemonic

14 W.NSTS
16

is the status flag. Bit 14 = 1 (WS.UNM) if the window specified was
successfully unmapped.

Local Symbol Definitions
U.MABA

Window definition block address (2)

DSW Return Codes

5-64

UMAP$

Is.sue

Successful completion.

IE.ITS

The window ID specified is either invalid (outside the range 1 to 7) or not
currently mapped.

5.32 WDBBK$ and WDBDF$-Define and Fill WDBs
Two directives are available for use with Window Definition Blocks (WDBs):
WDBDF$ and WDBBK$.
The WDBDF$ directive assigns literal values to the offsets and status bit
mnemonics shown for the WDB areas for the CRAW$, ELAW$, MAP$, and
UMAP$ directives. You can use these mnemonics to reference offsets and bit
values in a WDB you have allocated space for in your program.
The WDBBK$ directive defines these offsets and, in addition, generates code to
allocate space for the WDB and fills it with values you specify in the call.
Privileges Required

[Not applicable]
Macro Call

WDBBK$ apr, siz, rid,off, len, <bitl ![bit2!bit3]>
where:
apr

is the base APR.

SlZ

is the size of the window.

rid

is the resident library ID.

off

is the offset into the library, in 32-word blocks.

len

is the length to be mapped.

bit...

are the mnemonic values for bit settings, separated by exclamation points. The
following mnemonics are defined for CRAW$:
WS.64B
Means allow 32 word alignment, rather than requiring 256 word
alignment.
WS.MAP

Indicates the window is to be mapped

WS.RED

Means map with read-only access

WS.SIS

Means map in supervisor mode I-Space

WS.UDS

Means map in user mode D-Space

WS.WRT

Means map with read/write/access

Macro Expansion
WDBBK$ 7,128.,0,0,0,<WS.MAP!WS.RED>
. BYTE
0,7
. WORD
. WORD
128 .
. WORD
. WORD
. WORD
. WORD
WS.MAP!WS.RED

°
°
°
°

When used in a CRAW$ directive, this WDB creates a window 4K words long (128
by 32-word blocks) in APR 7. The call also specifies an offset and map length of
zero and read-only mapping. Note that to use this WDB, you have to supply the
resident library ID, which you get from the RDB returned by an ATRG$ call. To
fill in the library ID, move the word at offset R.GID in the RDB to offset W.NRID
in the WDB.
The WDBBK$ directive also defines the offsets and bit settings that the ELAW$,
MAP$, and VMAP$ descriptions refer to.

WDBBK$ and WDBDF$

5-t55

5.33 WSIG$ - Wait for Significant Event Flag
The WSIG$ directive is included for compatibility with RSX-llM. In RSX-llM,
some recoverable error conditions require waiting for a significant event to
happen, at which time a retry of the operation that failed may succeed. On a
RSTSIE system, any events that may be termed significant within the RSTSIE
monitor are transparent to user jobs. Hence, the WSIG$ directive in RSTSIE
merely causes the calling job to sleep for one second. The job can then retry
whatever operation failed previously.
Privileges Required

None
Macro Call

WSIG$
Macro Expansion
WSIG$
. BYTE

49. , 1

;DIC=49., DPB SIZE=l WORD

local Symbol Definitions

None
DSW Return Codes

5-66

WSIG$

Is.sue

Successful completion.

IE.SDP

DIe or DPB size is invalid.

5.34 WTSE$ -

Wait for Single Event Flag

The WTSE$ directive is included for compatibility with RSX-llM, in which some
programs are written with a QIO$ followed by a WTSE$, to cause the program
to wait until the 110 is complete. This has the same effect as a QIOW$ directive.
Since all I/O is synchronous in RSX-emulation mode, QIO$ performs the same
as QIOW$. Thus, the WTSE$ directive returns immediately; it performs no
operation in RSTSIE.
Privileges Required

None
Macro Call

WTSE$ efn
where:
efn

is the event flag number. (The RSX emulator ignores this parameter.)

Macro Expansion
WTSE$
. BYTE
. WORD

0
41.,2

;DIC=41., DPB SIZE = 2 WORDS
;FLAG IGNORED IN RSTS/E

Local Symbol Definition
W.TSEF

Event flag number (2)

DSW Return Codes

IS. sue
IE.SDP

Successful completion.
Drc or DPB size is invalid.

WTSE$ 5-67

Chapter 6

RT-11 Run-Time System Environment
The RT-ll run-time system emulates the single-job monitor of the RT-ll
operating system on RSTSIE systems. You can use many of the programmed
requests available to MACRO programmers on RT-ll systems. In addition,
the RT-ll run-time system provides some directives, suited to the RSTSIE
environment, that are not available for the RT-ll operating system.
The size limit for programs running under the RT-ll run-time system is 27K
words, slightly less than the 28K words allowed by the RT-ll operating system.
The run-time system itself takes a 4K-word high segment. It also uses lK
words in the user job image area as a scratch pad. As Chapter 2 notes, run-time
systems are usually mapped read-only, so they can be shared by more than one
user on a RSTSIE time-sharing system. However, the RT-ll operating system lets
you access certain areas within the resident monitor. Thus, to allow a similar
capability under RSTSIE, these areas must be located in the user job image area,
which is mapped read/write.
If you use the RT-ll directives (see Chapter 7), you must assemble your program
with the MACRO assembler and link the modules with the LINK linker. The
RSTS/E RT-ll Utilities Manual describes how to run MACRO and LINK to
assemble and link your program.

6.1 Advantage: Transportable Code
The RT-ll directives are useful if you are coding a program to be run under both
the RT-ll and RSTSIE operating systems. RSTSIE emulates the majority of the
RT-ll single-job programmed requests. Of those which are not, most are ignored
on RSTSIE systems, including the foregroundlbackground (FB) and extended
memory CXM) calls. That is, most RT-ll directives do not cause errors on RSTSIE
systems (see Chapter 7 for a list of exceptions).
Those RT-ll requests that are emulated are fitted to the RSTSIE environment.
For example, under the RT-ll operating system, there are three types of read:
..

.READ-Initiates a read operation and transfers control back to the user
program; the read mayor may not be complete.

.READW-Initiates a read operation and transfers control back to the user
program only after the read operation is completed.

.READC-Initiates a read operation and transfers control to the user
program; then, when the read is complete, transfers control to a user-specified
completion routine.

RT-11 Run-Time System Environment

6-1

Under RT-ll emulation, all 110 is synchronous; that is, control is returned
to the user program only when the I/O is complete. So, .READ and .READW
are implemented the same under RSTSIE as a "read and wait." The .READC
transfers control to the completion routine when the read operation finishes.
The significance of the differences depends on what you want to do. If you are
transporting an existing program from RT-ll to RSTSIE, you can generally be
confident that the program works as it should.
If you are developing a program for RSTSIE only, you do not have to be concerned
with how the directives work on RT-ll. You can choose .READ or .READW: both
work the same. You can also choose .READC if, for example, you wanted to code
one completion routine to be used after different read operations.
If you are developing a program on RSTSIE to be run under RT-ll, or both
RSTSIE and RT-ll, you need to know how the directives work under RT-ll and
under RSTSIE. You can choose between .READ, .READW, and .READC according
to what they do on both systems.

Chapters 6 and 7 describe what RT-ll directives are available, as well as what
they do under RSTSIE. See the RT-ll Programmer's Reference Manual for a
complete description of how these directives work in the RT-ll operating system
environment.
You can also transport assembled (binary) programs from RT-ll systems to
RSTSIE systems, if you keep in mind the limitations of the emulated RT-ll
run-time system environment. You must change the run-time system name that
RSTSIE maintains in the file directory entry for each runnable file. The easiest
way to do this is with the /RUNTIME_SYSTEM qualifier in COPY. For example:
COPY MTO:*.* *.*/RUNTIME_SYSTEM=RT-ll

This command transfers all files on magnetic tape unit 0 to your account on the
public disk structure as files to be run under the RT-ll run-time system.
For binary files that have already been transferred to your system, type:
SET FILE file.typ/RUNTIME_SYSTEM=RT-ll

6.2 General Services
Besides transportable code, the RT-ll emulator provides:

6-2

•

Simple input/output. The 110 operations under the RT-ll run-time system
are simple to code and include file-structured input/output operations.

•

Fast program development. The LINK linker executes faster than its RSX
emulator counterpart TKB. However, LINK does not provide as many
features.

RT-11 Run-Time System Environment

6.3 System Macro library
The RT-ll emulator directives that you code into your program are macros;
MACRO-ll expands them into executable code at assembly time. The macro
expansions for the RT-ll emulator directives are contained in the system macro
library ($SYSMAC.SML). You can name this library file in the input-file list when
you assemble your program. For example:
MACRO OBJ,OBJ=$SYSMAC.SML/M,SRC1,SRC2

(MACRO-ll searches the library automatically to resolve undefined symbols, so
this is not really necessary.)
However, you must use the MACRO-ll .MCALL directive in your code to define
the directives you use as external macros needed to assemble the source program.
The .MCALL must appear before the first directive is called. For example:
.MCALL .READ, .DATE, ....

. DATE

Alternatively, you can enable automatic macro library search using the .ENABL
MCL macro directive. See the PDP-ll MACRO-ll Language Reference Manual
for details.
Note that some RT-ll emulator directives have the same form as general monitor
directives (.DATE, for example). If you want to use the RT-ll .DATE, specify it in
an .MCALL directive. Then, regardless of whether you assemble with the prefix
file COMMON.MAC, the .DATE is expanded from the system library as a call to
the RT-ll run-time system.
If you want the general monitor .DATE , do not specify .DATE in an .MCALL
directive. Instead, use the special prefix emulator trap (EMT) instruction (EMT
377) immediately before the .DATE call, and assemble with COMMON.MAC.
NOTE

You must precede all general monitor directives that you use with an
EMT 377. RT-ll uses EMTs in the range to 100, the same range
used by the RSTSIE general monitor directives. To bypass the general
monitor calls, the RT-ll run-time system defines a special prefix EMT
for the monitor (see Chapter 2), so all EMTs except those preceded by
an EMT 377 are processed by the RT-ll run-time system.

You should not use the general monitor calls .CHAIN, .EXIT, .CORE,
.RTS, .FSS, .RUN, or .CCL from a program running under control of
the RT-ll run-time system. Results from using these directives under
RT-ll emulation are unpredictable.

RT-11 Run-Time System Environment

6-3

6.4 Directive Processing
It is easier to understand how you specify RT-ll directives and their arguments if
you first understand how the directives are expanded at assembly time, and how
they are processed by the RT-ll run-time system at execution time.

Generally, the expansions end with an EMT instruction passing control to the
RSTSIE monitor. The monitor then passes control to the RT-ll run-time system
for processing.
NOTE

The RT-ll run-time system has the PF.EMT bit set in the P.FLAG
word in the pseudovector region (see Chapter 2). Thus, the RT-ll
run-time system can use all possible values in the low byte of the EMT
instruction, just as the RT-ll operating system does. The low-byte of
the P.FLAG word is set to 377, which, in combination with the setting
of the PF.EMT bit, defines the special prefix EMT 377.
The RT-ll run-time system examines the low byte of the EMT instruction to
determine either the action to be performed or the place to look for information
that defines the action to be performed.
For example, if the call translates to code ending in an EMT in the range 340 to
357, the RT-ll run-time system determines the action to be performed from the
EMT and looks in general register RO and/or on the stack for other arguments
used in the call.
If, on the other hand, the call translates to an EMT 374 instruction, the RT-ll
run-time system looks in RO for a one-byte function code and, if necessary, a
one-byte argument. For an EMT 375 instruction, the RT-ll run-time system
looks in RO for the address of an argument block. It then examines the argument
block to find the function code defining the action and whatever other arguments
it expects, depending on the function.
Table 6-1 summarizes the EMTs that the RT-ll run-time system processes.
Unless you want to bypass the directive expansions and load RO and other
arguments yourself, Table 6-1 is important to you because:
•

All the directives use general register RO. You must preserve the contents of
RO, if necessary, by saving and restoring the contents before and after issuing
a directive. Some directives return information to RO; otherwise, the contents
of RO are unpredictable upon completion of a call. All other general registers
are preserved as you left them.

•

Some of the directives require that you allocate space in your program for
arguments. The expansions for such directives fill the argument block you
specify in the call with the values you specify as other arguments in the call
(see the next section "Call Forms").

If an error occurs when a directive is processed, control returns to the user
program with the carry bit set in the PSW and an error code in byte 52 of the low
512. bytes of memory.

6-4

RT-11 Run-Time System Environment

Table 6-1:

EMT Instructions Recognized by the RT-11 Run-Time System

EMT Low-Byte

Meaning

EMT377

Reserved; this is the special prefix EMT. You must code this EMT
immediately before any of the general monitor calls in Chapter 3.

EMT 376

Used internally by the RT-ll run-time system. Never execute this
EMT from a user program; the program aborts with an error. The
error message displayed is:
?M -OVLY error at user PC nnnnnn."

EMT 375

Indicates a call that has several arguments: RO contains the address of the first byte of an argument block.

(RO)

EMT 374

address of argument block

Indicates a call with one argument. RO contains a function code in
the high-order byte and the argument in the low-order byte.

(RO)

function code

argument

EMTs 372-373

Ignored by the RT-ll run-time system. Do not use these EMTs; they
are reserved for future use by Digital.

EMTs 360-371

EMTs specific to the RT-ll run-time system under RSTS/E; not
available under the RT-ll operating system.

EMTs 340-357

Indicates a directive that expects arguments either on the stack, in
RO, or both.

EMTs 0-337

Indicates a directive used by Version 1.0 of the RT-ll operating
system. These EMTs are also recognized by the RT-ll run-time
system.

6.5 Call Forms
Chapter 7 shows RT-ll directive calls in two basic fonnats: those with an area
argument and those without. The area argument indicates that the call uses an
argument block. You must allocate space for the argument block.

6.5.1

Format for Calls Using Argument Blocks
The previous section describes how directives with an area argument use an
argument block. Chapter 7 shows the fonnat for these directives as:
.RTCALL area, argl, arg2, .... , argn

RT-11 Run-lime System Environment

6-5

The area argument is the address of the first byte of the area you have set aside
for the argument block. The remaining arguments (argl, arg2, and so forth) are
the values needed for the call. The RT-ll emulator places them in the argwnent
block at execution time.
In general, the argwnent block format is:

function code

I channel number

~(RO)

argument 1

(RO) + 2

argument 2

(RO) + 4

argument n

(RO) + n"2

RO points to location x. The high byte (location x+l) contains the function code
defining the action to be perlormed. The low byte defines a channel nwnber, if
one is needed for the call. Remaining arguments, if any, are stored in subsequent
words.
Consider t.he hypothetical directive .HYPOT, using four argwnents including the
area argwnent:
.HYPOT area, argl, arg2, arg3
If you were to specify all four argwnents in the call, at assembly time MACRO-ll
expands the call to a code that:

•

Moves the area argwnent (an address) to RO.

•

Moves the function code for .HYPOT to the address specified by (RO)+l,
and, if a channel nwnber is used, moves that channel nwnber to (RO). (The
notation (x) means the contents of x - thus the channel number is moved to
the address specified by the contents of RO.)

•

Moves remaining argwnents to subsequent words in the argument block.

•

Executes an EMT 375.

Thus, all of the arguments for this form should be appropriate as operands in
MOV instructions. For example:
AREA:

. WORD

0,0,0

.HYPOT

*AREA, *4, NUMNUM, *300

Under certain conditions, you can leave out argwnents in directives using an
argwnent block. If you leave out area, for example, you must load RO with
the address of the argument block yourself, before executing the directive. For
example:
MOV
. HYPOT

6-6

*AREA,RO
,*4,NUMNUM,*300

RT-11 Run-Time System Environment

If you leave out any of the other arguments, the expansion does not load any new
values into those positions in the argument block; those words are left untouched.
For example:
AREA:

. WORD

0,0,0

. HYPOT

*AREA"NUMNUM,*300

The execution of .HYPOT uses the value 0, the contents of location NUMNUM,
and 300 as arguments. Suppose that the following directive is executed next:
. HYPOT

#AREA,#3,,#200

When the directive is executed, the argument block contains the value 3, the
contents of location NUMNUM, and 200.

6.5.2

Format for Calls Not Using Argument Blocks
For those calls that do not use an argument block, Chapter 7 shows the format
as:
.RTCALL arg1, arg2, ... , argn
These directives expand to code that stores the arguments, if any, in RO and/or
the stack. (The RT-ll emulator removes any values pushed on the stack before
control returns to the user program.)
Again, the arguments should be appropriate as operands in MOV instructions.
You can omit certain arguments for this form; Chapter 7 indicates these possible
omissions with brackets when it describes the directive calls. For example, if the
macro call format was as follows, you could leave out the last argument:
.HYPOT arg1, arg2[, arg3]

6.6 Channel Number and Device Block Arguments
Many RT-ll directives use arguments that define a channel number and device
block. A device block is a 4-word area containing the device and file specification.
The following general comments apply to these arguments.

6.6.1

Channel Number Arguments
Like the general monitor calls, RT-ll directives which handle 1/0 use a channel
number to refer to a device. Allowable RT-ll channel numbers range from 0
to 15. When you open a file or device using the RT-ll directives .LOOKUP or
.ENTER, you give a channel number in this range. The RT-ll emulator relates
the number specified in the call to the first free RSTSIE channel number, with
the following considerations:
..

The job's terminal (RSTSIE channel 0) is never free for the emulator to relate
to an RT-ll channel number. In RT-ll, you do I/O to the job's terminal with
specific directives, such as .PRINT and .GTLINE. Thus, since RSTSIE channel
numbers range from 0 to 15 but RSTSIE channel 0 is always busy as far as
the RT-ll run-time system is concerned, you can open up to 15 channels using
any 15 of the 16 possible RT-ll channel numbers (ranging from 0 to 15).

RT-11 Run-lime System Environment

6-7

•

The RT-ll emulator always attempts to allocate RT-ll channel number 15
to RSTSIE channel 15. Channel 15 is the channel on which the monitor
opens the user job image file when RSTSIE executes a .RUN directive (see
Chapter 3). The run-time system loads the file and begins its execution. If
the program is overlaid, the run-time system keeps channel 15 open. If not,
the run-time loads the file and then closes channel 15.
Thus, if your program is not overlaid and you open RT-ll channel 15, the
call succeeds (unless you already have channel 15 open). If your program is
overlaid, you cannot open channel 15; any attempt to do so results in an error
indicating the channel is in use.

Other than channel 15, there is no correspondence between the RT-ll channel
number and the RSTSIE channel number. They mayor may not be the same.

6.6.2

Device Block Arguments
Several RT-ll directives use a device and file specification. The argument in
these cases is an address pointing to the first word of a 4-word device block
that you allocate in your program. The format of the device block is 12 RAD50
characters:
device and unit number

. . - (devblk)

filename
(2 words)
file type

You can use any valid RSTSIE device and unit number (0-7) for the first word of
the device block. You can also define user logical names up to three characters
long. If you need device numbers that have more than one digit (for example,
KB27 or TT12), you must use the following steps to form the algorithm:
1. Form the RAD50 representation of unit zero of the device you want. For
example:
BASEKB="RKBO

2. Add the decimal value of the unit number wanted. For example, to get the
proper representation of KB36:
KBN36=BASEKB+36.

3. Use this value as the first word of the device block. For keyboards, there is
no file name and type, so you can construct the device block as:
DEVBLK:
. WORD

. WORD

KBN36

0,0,0

NOTE

If you assign a logical name with the same RAD50 bit pattern as
some device/unit-number that you construct, the logical name takes
precedence. The previous example, for instance, forms the RAD50 bit
pattern equal to the ASCII characters KCZ. Thus, if you assign the
logical name KCZ to the line printer, any call referring to DEVBLK in
the previous example would use the line printer not KB36.

6-8

RT-11 Run-Time System Environment

6.7 Low 512. Bytes for RT-11 Run-Time System
Table 6--2 summarizes the locations in the low 512. bytes of virtual address space
that the RT-ll run-time system uses.
Table 6-2:

Locations in First 512. Bytes That RT-11 Uses

Locations

Contents

30,31

Contains the contents ofFIRQB+FQNENT at the time the .RUN was
executed. (See the .RUN description in Chapter 3, and P.RUN description
in Chapter 2.)

32,33

Contains the contents ofXRB+O when the run-time system was entered at
P.RUN (see Chapter 2).

40,41

Contains the starting address of the job.

42,43

Contains the initial value of the stack pointer. If this value is not set
by the user program in an .ASECT or through a LINK option, the LINK
linker defaults this word to 1000.

44,45

Contains the Job Status Word (JSW). RSTSIE uses JSW as a flag word for
the run-time system. Certain bits are maintained by the RT-ll run-time
system exclusively, while others can be set or cleared by the user program.
The bits you can set are marked with an asterisk in the following list.
Do not use currently unassigned bits for your own purposes; future RT-ll
run-time system releases may use them.
Bit
Meaning

46,47

*15

Core common bit. If set with .ASECT, preserves core common
when the user program is executed.

*14

Lowercase bit. When set, disables automatic conversion of
lowercase to uppercase.

*13

Reenter bit. When set, indicates that you can restart the program from the terminal with the REENTER command.

*12

Special mode TT bit. When set, indicates that the job is in a
special keyboard input mode. See .TTYIN/.TTINR directive
descriptions, Chapter 7.

Overlay bit. When set, indicates that the job uses the LINK
overlay structure.

CHAIN bit. If set, virtual addresses 500-776 are loaded from
the memory image file when the job is started. (These words are
normally used to pass parameters between programs.) the RT-ll
run-time system sets the bit if you entered the job with the RT-ll
.CHAIN directive.

Inhibit TT wait bit. When set, indicates that the job can accept
input from the job's terminal in ODT mode with .TTYIN/.TTINR;
that is, one character at a time, as you type the characters rather
than one character at a time after you type a whole line.

Points to the first word of the RT-ll read/write scratch pad area in the
user job image area.

(continued on next page)

RT-11 Run-lime System Environment

6-9

Table 6-2 (Cant.):

Locations in First 512. Bytes That RT11 Uses

Locations

Contents

50,51

Contains the high memory address. The run-time system maintains the
highest virtual address the user program can use in this word. It is
initially set to the address of the last word of the user program. You can
change it with the .SETI'OP directive (see Chapter 7) to any address up to
the start of the scratch pad area. That is, the maximum value this word
can be is the contents of the word at location 46,47 minus 2.

Contains the EMT error code. If the directive results in an error, the code
number of the error is always returned in byte 52 and the carry bit is set.
Always refer to location 52 as a byte, not a word.

54,55

Contains the beginning address of the scratch pad area.

6.8 Scratch Pad Area in User Job Image
The RT-ll run-time system uses part of the user job image space as a scratch
pad. Some of the information in this scratch pad is the same as the information
in the RT-ll operating system, as the RT-ll Programmer's Reference Manual
describes. Other information is unique to RSTSIE. For example, you can set a
word in this area with a PPN to be used when opening a file. RT-ll does not
allow a PPN in its file specification; RSTSIE does.
In any case, the RT-ll emulator adds the scratch pad area to the end (high
virtual addresses) of the user job image at execution time. If you do not use
RT-ll SIZE command (see the RSTS / E System User's Guide), the emulator
determines the highest address of the program from the .SAV file, an item which
the LINK linker calculates, and rounds the address up to the next multiple of
1024 (lK words) to determine the starting address of the scratch pad. If you use
the RT-ll SIZE command, the emulator places the scratch pad in the top 1K
words of the address space that SIZE requests.
Thus, the maximum size of MACRO programs running under the RT-ll run-time
system is 27K words. Any program larger than this causes the ??Maximum
memory exceeded error message when the file is run.
You can determine the start of the scratch pad area from word 54 in the low 512.
bytes of memory.

6-10

RT-11 Run-Time System Environment

Table 6-3 lists the offsets to locations in the scratch pad area that may be of use
to you.
Table 6-3:

Offsets to important Scratch Pad Area Locations

Octal
Offset

Mnemonic
Offset

PPN

Contents
If nonzero, used as a PPN for all of the calls named in this
section except .READ and .WRITE. (Note that for .SETFQB,
this value is loaded into FIRQB+FQPPN and overrides any PPN
resulting from examination of the string by the corresponding
.OSISPO directive.)

For .READ and .WRITE, this word forms the modifier word (at
XRB+XRMOD) in the corresponding RSTSIE .READ or .WRITE
directive.
2

PROTEO

If nonzero, this word is the protection code to be used for all of
the calls named in this section except .READ and .WRITE. (Note
that for .SETFQB, this value is loaded into FIRQB+FQPROT and
overrides any protection code resulting from examination of the
string by the corresponding .OSISPO directive.)
For .READ and .WRITE, this word forms the most significant
bits of the block number in the corresponding RSTSIE .READ or
.WRITE (at XRB+XRBLKM). This value supplements the block
number argument from the RT-ll .READ or .WRITE call.

MODE

For RT-ll calls .LOOKUP, .ENTER, and .REOPEN, this word
forms the mode word at FIRQB+FQMODE in the corresponding
RSTSIE OALFIP call. For .SETFQB, this word is loaded into
FIRQB+FQMODE and overrides any !MODE qualifier that the
.OSISPO directive finds.

OLUSTR

For RT-ll directives that create files, such as .ENTER, this word
forms the cluster size (at FIRQB+FQOLUS) for the corresponding
RSTSIE OALFIP call. For .SETFQB, this word is loaded into
FIRQB+FQOLUS, and overrides any IOLUSTERSIZE qualifier
that the .OSISPO directive finds.

POSITN

For RT-ll directives that create files, such as .ENTER, this
word forms the device cluster number for file placement (at
FIRQB+FQNENT) in the corresponding RSTSIE OALFIP call.
For .SETFQB, this word is loaded into FIRQB+FQNENT and
overrides any !POSITION qualifier that the .OSISPO directive
finds.

ORMSBS

For RT-ll calls that preallocate space for a file on its creation
(.ENTER), this word forms the most significant bits (MSBs) of
the file size (at FIRQB+FQSIZM) in the corresponding CALFIP
call. For .SETFQB, this byte is loaded into FIRQB+FQSIZM.

(continued on next page)

RT-11 Run-lime System Environment

6-11

Table 6-3 (Cont.):
Octal
Offset

Mnemonic
Offset

NOCTLC

Offsets to Important Scratch Pad Area Locations
Contents
This word is used by the RT-ll run-time system to stop userentered CtrllCs from interrupting program execution during
certain crucial sequences (.SRESET, .HRESET, .LOOKUP,
.ENTER, .REOPEN, .CLOSE, and .SAVESTATUS).
When set to 177777, user-entered Ctrl/Cs interrupt execution.
A zero or positive value inhibits CtrllC interrupts. While this
word is zero or positive, any user-entered CtrllC increments the
contents of this word by one.
When the emulator reenables Ctrl/Cs, it processes any pending
CtrllC by either:
•
"

Passing control to a user routine specified with .SETCC
(Chapter 7)
If no .sETCC is in effect, passing control to the job keyboard
monitor. If the job keyboard monitor is RT-ll, the keyboard
monitor commands CONTINUE or CCONTlNUE resume
execution of the program at the point where the interrupt
occurred. Your program can clear this word to inhibit
CtrllCs, process them later in whatever manner you see
fit, and reenable CtrllC interrupts by setting this word
to 177777. However, note that the RT-ll emulator clears
the word and then reenables interrupts when .SRESET,
.HRESET, .LOOKUP, .ENTER, .REOPEN, .CLOSE, or
.SAVESTATUS is executed.

276

Emulator version number. The same as the RT-ll operating
system version number that the current RT-ll run-time system
emulates.

277

Emulator release number. The same as the RT-ll operating
system release number that the current RT-ll run-time system
emulates.

300

Configuration word. Set for RSTSIE environment, as follows:
If FPll floating-point hardware exists, bit 6 is set to one. Bit
9 is always set to one, and all other bits are set to zero.
(If your program tests these bits on an RT-ll system, the
code also works on RSTSIE.)

6-12

370

Extension configuration word. Under RSTSIE, bits 0-3 are
always zero, bit 8 is always one (indicating the EIS option is
present), and bits 9, 14, and 15 are always zero. (The conditions
they indicate on RT-ll systems are not determinable by the
RT-ll run-time system under RSTSIE.)

372

SYSGEN options word. This word is always zero on RSTSIE
systems.

374

User job image size. This word is always zero on RSTS/E
systems.

RT-11 Run-Time System Environment

The first six words in the scratch pad are of special significance; the following
general comments apply:
•

The directives .LOOKUP, .ENTER, .RENAME , .REOPEN, .DELETE, and
.SETFQB examine the first six words, use any values there as described, and
clear the first six words before returning control to the user program.

•

The directives .READ and .WRITE examine, use, and clear only the first two
words.

•

The .CSIGEN directive clears the first six words before performing any of the
.LOOKUP and .ENTER calls resulting from its examination of the command
string.

RT-11 Run-Time System Environment 6-13

Chapter 7

RT-11 Emulator Directives

RSTSIE does not emulate some of the RT-ll operating system's single-job monitor
calls. RSTSIE ignores the following: .CMKT, .HERR, .LOCK, .QSET, .MRKT,
.RELEASE , .SERR, and .UNLOCK. The .CDFN call always returns an error 0
on RSTSIE systems. The following single-job monitor calls are not expanded to
include EMTs, and their results on RSTSIE systems are unpredictable: .INTEN,
.MFPS, .MTPS, and .SYNCH.
The RT-ll foregroundlbackground (FB) and extended monitor (XM) calls are not
supported; they are essentially ignored on RSTSIE systems. They do not return
errors.
Table 7-1 lists the directives that are not processed by the RT-ll run-time system
on RSTSIE systems.
Table 7-1:

RT·11 Calls Not Functional on RSTS/E
Return

Ignored

Error 0

Unpredictable

.CMKT

.CDFN

.INTEN

.HERR

.MFPS

.LOCK

.MTPS

.QSET

.SYNCH

.MRKT
.RELEASE
.SERR
.UNLOCK

All FB calls
All XM calls

Table 7-2 lists the directives that are processed by the RT-ll run-time system on
RSTSIE systems.

RT-11 Emulator Directives

7-1

Table 7-2:

RT-ll Run-Time System Directives

Mnemonic

EMT

Function
Code

Description
Lets you assemble directives as they would
be expanded under Version 1 or Version 2 of
RT-11.

..Vl ..
..V2 ..

Input/Output and File Operations
.WRITE
.WRITW
.WRITC

375

Transfers data from a memory buffer to a file
or device on an open channel. As with the
.READ/w/C directives, .WRITE and .WRITEW
operate identically on RSTSIE; .WRITC transfers control to a completion routine after the
transfer is complete.

.READ
.READW
.READC

375

Transfers data from a file or device on an open
channel to a memory buffer. I/O is synchronous
under RT-11 emulation on RSTSIE systems, so
for all three reads, control returns to the user
program only when the transfer is complete .
.READ and .READW are identical on RSTSIE
systems. .READC transfers control to a userspecified completion routine when the transfer
is complete.

.REOPEN

375

Opens a file closed with .SAVESTATUS. Using
the .SAVESTATUSI.REOPEN combination is
easier than using standard opens and closes;
the device, file name and type, and projectprogrammer number are saved automatically
with .SAVESTATUS. You only need to keep
track of the address in which you stored the
file information to reopen it.

.SAVESTATUS

375

Closes a file, keeping the information needed to
.REOPEN the file later.

.RENAME

375

Changes a file's name on disk or DECtape .

.ENTER

375

Creates a file and opens it on a channel.

.LOOKUP

375

Opens an already existing file on a channel. .LOOKUP can also be used for non-filestructured 110 operations.

. DELETE

375

Deletes a disk or DECtape file .

.CLOSE

374

Terminates 110 operations on a channel,
performing clean-up operations (positioning
tape, and so forth) and releasing the channel
for other use.

.PURGE

374

Releases a channel without performing the
normal clean-up operations. In particular, a
file opened with .ENTER and not yet closed is
not made a permanent file.

.HRESET

357

Closes all open channels, without performing
normal clean-up operations. In particular, files
opened with .ENTER and not yet closed are not
made permanent.

(continued on next page)

7-2

RT-11 Emulator Directives

Table 7-2 (Cont.):
Mnemonic

RT-11 Run-Time System Directives

EMT

Function
Code

Description

Input/Output and File Operations

.sRESET
.PRINT
.GTLIN
.TTYOUT
.TTOUTR

.TTYIN
.TTINR

352
351
345
341

Functions the same as .HRESET on RSTSIE .
Displays an ASCII string on the job's tenninal.
Accepts a line of input from the job's tenninal.
Transfers one character from RO to the job's
tenninal.

340

Transfers one character from the job's tenninal
to RO .
Special Functions Related to I/O

.SPFUN

375

Perfonns special functions for disk, terminal,
magnetic tape, and flexible diskette.

.SCCA

374

Causes a Ctr1JZ entered by the user to be
passed on to the user program.

.WAIT

374
371

Checks to see if channel is open.

.CLRXRB
(RSTSIE only)

Clears the XRB (see Chapter 2) .

.CLRFQB
(RSTSIE only)

370

Clears the FIRQB (see Chapter 2) .

.DOFSS
(RSTSIE only)

365

Analyzes an ASCII string in memory for a
RSTSIE file name and returns infonnation
as for .FSS (general monitor directive). Use
instead of.FSS for programs running under
RT-ll run-time system.

.ERRPRT
(RSTSIE only)

364

Prints text corresponding to RSTSIE error code
on the job's terminal.

.SETCC
(RSTSIE only)

362

Defines an entry point for Ctr]JC traps; allows
the user program to handle its own Ctr]JCs.

.SETFQB
(RSTSIE only)

360

Sets the FIRQB (see Chapter 2) from infonnation returned by the .CSISPC directive.

.RCTRLO

355

Restarts programmed output to job's tenninal
that was stopped by user-entered CtrllC or
Ctr]JO.

.CSISPC

345

Analyzes an ASCII string (in memory or
from the job's tenninal) for a standard RT-ll
command, and sets up device blocks for later
opens.

.CSIGEN

344

Analyzes an ASCII string (in memory or
from the job's tenninal) for a standard RT-ll
command, and opens files accordingly.

.FETCH

343

Checks to see if device is available on the
system.

(continued on next page)

RT-11 Emulator Directives

7-3

Table 7-2 (Cont.):
Mnemonic

RT-11 Run-Time System Directives

EMT

Function
Code

Description

Special Functions Related to I/O
.DSTATUS

342

Returns information about a device to an area
in the user program.
System/Job Information

.GVAL

375

Returns the contents of a word in the scratch
pad area.

.GTIM

375
375
374
361

Returns the time of day.

Returns the current job number.

Returns the current date.

.GTJB
.DATE
.DATTIM
(RSTSIE only)
.SETTOP

Converts date or time from RSTSIE internal
format to ASCII string.

354

Sets location 40 (indicating top of user job
image area) to the address specified.
Execution Control

.SFPA

375

Sets address to be entered for floating point
errors.

.TWAIT

375

Timed wait. Suspends job execution for specified number of clock ticks.

.TRPSET

375

Sets address to be entered for reserved instruction and odd address errors; normally trapped
to kernel mode addresses 4 and 10.

.CHAIN

374

Transfers control to another program (file) to
be run under the RT-ll run-time system.

.DOCCL
(RSTSIE only)

367

Examines a string for valid RSTSIE CCL
command. If valid, transfers control to new
program. Use instead of .CCL (general monitor
directive) for programs running under RT-ll
run-time system.

.GETCOR
(RSTSIE only)

366

Expands size of user job image. Use when
.CHAIN is used to transfer control to a program larger than the current program. In
addition, use instead of .CORE (general monitor directive) for programs running under
RT-ll run-time system.

.DORUN
(RSTSIE only)

363

Transfers control to another program (file) that
runs under a non-RT-ll run-time system. Use
instead of .RUN (general monitor directive)
for programs running under RT-ll run-time
system.

(continued on next page)

7-4

RT-11 Emulator Directives

Table 7-2 (Cant.):
Mnemonic

RT-11 Run-Time System Directives

EMT

Function
Code

Description

Execution Control
.EXIT

350

Tenninates execution of the calling job. Note
that you should not use the RSTS/E .RTS or
.EXIT directives from a program running under
the RT-ll run-time system.

The remaining sections of this chapter describe the directives in detail, in
alphabetical order. Note that for all calls, you need only specify the first
six characters. For example, the abbreviation .sAVES works as well as
.SAVESTATUS.
All the examples in this chapter show Version 2 expansions. Note that Version
1 expansions require different arguments in the calls. See RT-ll system
documentation if you need to use Version 1 expansions.

RT-11 Emulator Directives

7-5

7.1

.CHAIN -

Pass Control to Another Program Under RT-11

The .CHAIN directive transfers control to another program without altering
the run-time system. The .CHAIN leaves 110 channels from the old program
still open for the new program. Thus, you can get around the 27K word limit
for programs to be run under the RT-ll run-time system. If the program you
are chaining to takes more space than the current program, use the .GETCOR
directive to expand the space allocated for the user job image area before
executing the .CHAIN.
Virtual addresses 500-507 are expected to contain the device and file name of
the program to chain to, in the RT-ll device block format (see Chapter 6). The
area from locations 510-777 can be used to pass information between the chained
programs. Make sure, though, that the program you are chaining to does not
inadvertently destroy the data in locations 510-777 by pushing data on the stack.
Note that the linker defaults the initial stack setting to 1000.
An executing program can tell whether it was chained to or run by some other
means by examining bit 8 of the Job Status Word (JSW) (see Chapter 6). If bit 8
= 1, the program was invoked with .CHAIN, and locations 500-777 are preserved
from the program that issued the .CHAIN. If bit 8 = 0, the program was not
entered with an RT-ll .CHAIN.
The .CHAIN directive works only for RT-ll-to-RT-ll transfers. If you want to
chain to a program to be run under some run-time system other than RT-ll,
use the .DORUN directive (see Chapter 6). (The description of .DORUN also
describes what happens for RT-ll programs receiving control from non-RT-ll
programs.)
Privileges Required

Read or execute access to the file.
Macro Call

.CHAIN
Request Format

RO =

Errors

Since .CHAIN is intended to pass control to another program, no errors are
returned to the calling program. If the new program cannot be chained to, the
.CHAIN is abandoned, and the keyboard monitor is entered. (Control passes
to the P.NEW entry point of the RT-ll run-time system, which is the keyboard
monitor's entry point for RT-11.)

7-6

.CHAIN

Example

The following code requests an expansion to 20K words and chains to a sample
file named MYFILE.SAV in the user's account:
FILE:

.RADSO

/MYFILESAV/

;Define text passed in chain

MOV
.GETCOR
CLR
MOV
MOV
MOV
. CHAIN

#20. ,RO

;Indicate 20.K now needed

SOO
#FILE, S02
#FILE+2,S04
#FILE+4,S06

;Default for the device
; Move
the
file name
;Invoke the new program

.CHAIN

7-7

7.2 .CLOSE -

Close a Channel

Use the .CLOSE directive to terminate I/O on a particular channel. The .CLOSE
directive:
•

Performs whatever action is appropriate to the device (such as updating a
disk directory to indicate a new file, repositioning a magnetic tape, and so
forth)

•

Frees the RT-ll channel number for use with another device

•

Frees the RSTSIE channel from its association with the RT-ll channel
number (effectively making another channel available).

A .CLOSE on a file opened with .ENTER makes the file permanent; the file is
tentative until that time. Note that, unlike the RT-ll operating system, RSTSIE
does not deallocate unused space. Thus, if you preallocated space when you
opened the file with .ENTER, the file contains all this space after the .CLOSE.
Privileges Required

None
Macro Call

.CLOSE chanum
where:
chanum

is a channel number in the range 0 to 17 (octal). See Chapter 6 for rules on
channel numbers.

RO Format

(RD) =

chanum

Errors

No errors are possible with the .CLOSE directive. RSTSIE ignores a .CLOSE for
a channel that is not currently open.
Example

The following statement closes channel 5:
.CLOSE *5

7-8

.CLOSE

7.3 .CLRFQ8 -

Clear the FIRQ8

This directive clears the FIRQB area in the low 512. bytes of virtual memory (see
Chapter 2). No data is passed or returned for this directive.
Privileges Required

None
Macro Call

.CLRFQB
Note that .CLRFQB, like all RSTSIE-specific directives under RT-ll, is not
expanded at assembly time. (It is not defined in the SYSMAC.SML file as a
directive.) You can code a definition of the directive in a data section of your
program or use .MACRO to define it. See the following example.
Errors

No errors are possible with the .CLRFQB directive.
Example

The following example clears the FIRQB area in the low 512. bytes of virtual
memory:
.CLRFQB = EMT+370

.CLRFQB

7-9

7.4 .CLRXRB -

Clear the XRB

This directive clears the XRB area in the low 512. bytes of virtual memory (see
Chapter 2). No data is passed or returned with .CLRXRB.
Privileges Required
None
Macro Call
.CLRXRB
Note that .CLRXRB, like all RSTSIE-specific directives under RT-ll, is not
expanded at assembly time. (It is not defined in the SYSMAC.SML file as a
directive.) You can code a definition of the directive in a data section of your
program or use .MACRO to define it. See the following example.
Errors
No errors are possible with the .CLRXRB directive.
Example

The following example clears the XRB area in the low 512. bytes of virtual
memory:
.CLRXRB = EMT+371

.CLRXRB

7-10

CLRXRB

7.5 .CSIGEN -

Examine String for RT Command, Open Files

The .CSIGEN directive examines a string (either in memory or from the job's
keyboard) to process a standard RT-ll command string. If the string is to be
accepted from the job's keyboard, the .CSIGEN first prints an asterisk (*) prompt
on the keyboard and then waits for you to type a line.
If the string is in the correct form, any files or devices open on RT-ll channels

0- 10 (octal) are closed and then either reopened or left inactive, depending on
whether or not a file is given for that slot. For example:
objfile,listfile,crefile=srcfile1,srcfile2, ... srcfile6
channel

Any valid RSTS/E file specification can appear in the string, including file
specifications with PPNs, and logical names. However, the file specifications
cannot contain wildcards. Files on the left side of the equal sign are opened
with .ENTER, and the files on the right side of the equal sign are opened with
.LOOKUP. If the equal sign is missing, RSTS/E assumes an equal sign at the
beginning of the string. For example, consider the string:
NOW.OBJ,NOW.LST,NOW.CRF=THEN.MAC

The file NOW.OBJ would be opened with .ENTER on channel 0; NOW.LST, on
channell; NOW.CRF, on channel 2. The file THEN.MAC would be opened with
.LOOKUP on channel 3. Two more examples are:
NOW.OBJ"NOW.CRF=

The file NOW.OBJ would be opened with .ENTER on channel 0 and NOW.CRF on
channel 2. Channels 1 and 3-10 would be inactive.
LP:

The line printer would be opened with .LOOKUP on channel 3.
RSTS/E Options

The file specifications can include any of the standard RSTS/E qualifiers processed by the monitor itself (see the .FSS directive, Chapter 3). These include:
ICLUSTERSIZE, IRONLY, !MODE, !PROTECTION, IFILESIZE or ISIZE, and
!POSITION. The RT-ll Emulator can handle any of these optional qualifiers that
.CSIGEN finds in the command string.
RT-11 Options

The .CSIGEN directive under RSTS/E also does RT-ll-type analysis of options.
One or more options can appear after any of the file specifications. The general
form of an option is:
la:val1:va12: ... :valn
The slash (/) indicates an option; it must be followed by a one-character option
code. (The character does not have to be printable.) The slash-character pair can
be followed by one or more values. A colon (:) indicates that a value follows. If
given, the colon must be followed by:
•

An octal number in the range 0 to 177777.

CSIGEN

7-11

•

A decimal integer in the range -32768. to 32767. (the terminating period
must appear).

•

From one to three alphanumeric characters, with the first character alphabetic.

The .CSIGEN directive examines any options in the string to ensure that they are
in the correct form, reformats them, and pushes them on the stack for the user
program to examine. The information pushed on the stack is ordered by channel;
if an option is given for the file specification for channel 0 (assuming there is
a file specification in the first slot), it is pushed on the stack first, followed by
option information for the file specification for channel 1 (if any), and so forth.
The last word pushed on the stack is an integer value indicating the total number
of options in the string. An option having two values is formatted as two options.
The format is:

number of options in string
value-flag/channel

option code (ASCII)

value (integer or RAD50) or next option

Bit 15 of a value-flag/channel byte is set to one if the option had an associated
value, to zero if it did not. Thus, if bit 15 is set, the next word is the value
associated with the option. (The option code itself is in the low byte of this
word.) If bit 15 is zero, the next word is the next option (if any). Bits 8 to 14 of
a value-flag/channel byte indicate the RT-ll channel number with which the file
specification having the option is associated.
Privileges Required

Read or write access to the files specified. DEVICE privilege is required to access
a restricted device.
Macro Call

.CSIGEN devspc,defext, [cstrng ][,linbutJ
where:
devspc

is ignored on RSTSIE systems.

defext

is the address of a four-word area containing default file types, in RAD50
format. The format of the area is:

default for files open on channels 3-10
default for file open on channel 0
default for file open on channel 1
default for file open on channel 2

7-12

CSIGEN

These values are then used when no corresponding file type is given in the
examined string. For example, in the MACRO assembler, the first word
would contain MAC in RAD50 format; the second, OBJ; the third, LST; and
the fourth, CRF.
cstrng

is the address of the ASCIZ string to be examined or a #0 if input is to
come from the job's terminal. If this argument is not specified, input is
automatically taken from the job's terminal.

linbuf

is the address where the original string (if accepted from the job's terminal) is to be stored. This area should be 81. bytes long. The string
will be terminated with a zero byte, instead of a carriage-returnlline-feed
combination.
If this argument is omitted, the original string is not kept.

Errors

If an error occurs when input is accepted from the job's terminal, the user gets
another try. A_Tl error message is printed on the terminal, along with another *
prompt, and the directive waits for you to type another line.
If the string being examined is in memory and an error occurs, the carry bit is
set, and one of the following error codes is returned in byte 52. The options and
option-count are removed from the stack.
Code

Meaning

Illegal command (bad separators, illegal file name, command too long, and so
forth).

A device specification was not recognizable or the device is not available on the
system.

Unused.

An attempt to open a file with .ENTER failed because of a full directory.

An input file (to the right of the equal sign) was not found in a .LOOKUP.

Example
The following example includes option switches and shows more clearly how
options and values are pushed on the stack:
DEFEXT:

.RADSO

/MACOP10P20P3/

.CSIGEN

#O,#DEFEXT,#O

Assume that the line typed at the job's terminal is:
OUTFIL/M:32."ODDFIL=[2,200]HISFIL,DTO:HERFIL/G:NRD:20

When control returns to the user program following the .CSIGEN, the file
OUTFIL.OPI on the public structure has been opened with the .ENTER directive
on channel 0, and the file ODDFIL.OP3 on channel 3. The file HISFIL.MAC on
the public structure, under account [2,200], has been opened with the .LOOKUP
directive. (If the calling job did not have the necessary privilege, an error message would have been displayed on the terminal, and another line accepted.) The
file HERFIL.MAC on DECtape unit 0 has also been opened with .LOOKUP.

CSIGEN

7-13

The stack contains:
Word

Explanation

000003

Three options were found in the string.
(The G option has two values.)

102107

Last option has a value, and the option is
associated with channel 4. The option code
is G.

000020

The value of the option is 20 (octal).

102107

Next-to-Iast option has a value, and the
option is associated with channel 4. The
option code is G.

055124

Value of option is NRD in RAD50 format.

100115

The first option has a value, and the
option is associated with channel o.
The option code is M.

000040

The value of the option is 40 (octal).

(SP)~

7-14 CSIGEN

Octal
Value

7.6 .CSISPC -

Examine String for RT Command, Create Devblk

Like .CSIGEN, the .CSISPC directive parses a string (either in memory or from
the job's terminal) to see if it is a valid RT-ll-type command string. If the string
is to be accepted from the job's terminal, .CSISPC first displays an * prompt on
the screen and then waits for you to type a line. Instead of closing and opening
files, however, .CSISPC simply returns a 39-word block of information about
the files named in the string. The user program can later use this information
to open the files. See the previous discussion of .CSIGEN for command string
format and option processing.
Note that .CSISPC, like .CSIGEN, stores RSTSIE-specific file information
(PPN, and so on) within the scratch pad area. Furthermore, you can issue a
.SAVESTATUS or .SETFQB referencing the device-block information returned by
.CSISPC (although .SAVESTATUS works only for input files to the right of the
equal sign when opened with .LOOKUP).
If you use .CSISPC in this way, be sure that you reference addresses in the

outspec area returned by .CSISPC. If you move the information in the outspec
area and then refer to the new area in .SAVESTATUS or .SETFQB, the RSTSIEspecific information, such as PPN, is not used. (The emulator keeps a pointer in
the impure area relating the PPN and other RSTSIE-specific information to the
area returned by .CSISPC.)
Privileges Required

None

.CSISPC 7-15

Macro Call

.CSISPC outspc,defext,cstrng[,linbufj
where:
outspc

is the address of a 39-word area to contain the file descriptors produced by
.CSISPC. This area can overlay the space allocated to cstrng, if desired. The
format of the information returned is:
Offset

Contents

0
devblk for

devblk for

channel 0

channel 4
54

size

devblk for
devblk for
channel 1

20
22

channel 5
64
66

size

devblk for

channel 6
devblk for

channel 2

32
34

Contents

6
10

Offset

devblk for
size

channel 7
104

devblk for

106

channel 3

devblk for

channel 10
114

Information for the files for channels 0, 1, and 2 is stored in 5-word blocks.
The first four words are RAD50 information in the standard RT.ll device
block format (see Chapter 6). The last word is the file size indicated by
a IFILESIZE or /SIZE option, if any was encountered for these files in the
string. Since files on the left side of the equal sign are opened with .ENTER,
they can have a size for preallocation. Information for the files for channels
3 to 10 is stored in 4-word blocks, in the standard RT-ll device block format.
If any files are omitted in the string, the corresponding 4- or 5-word block is
filled with zeros.
defext

7-16

.CSISPC

is the address of a four-word block containing the RAD50 default file types.
(See the discussion of .CSIGEN for the format of this area.) These defaults
are returned to the outspec area if no types are given in the examined string.

cstrng

is the address of the ASCIZ string to be examined or a #0 if input is to
come from the job's terminal. If this argument is not specified, input is
automatically taken for the job's terminal. The string must follow the rules
for an RT-ll command string, as described for .CSIGEN.

linbuf

is the address where the original string (if accepted from the job's terminal)
is to be stored. This area should be at least 81 bytes long. The string is terminated with a zero byte instead of a carriage-returnlline-feed combination.
If this argument is omitted, the original string is not kept.

Errors
If an error occurs when input is accepted from the job's terminal, the user gets
another try. An error message is printed on the terminal, along with another *
prompt, and the directive waits for you to type another line.
If the string being examined is in memory and an error occurs, the carry bit is
set, and one of the following error codes is returned in byte 52. The options and
option-count are pushed from the stack.
Code

Meaning

Illegal command line (bad separators, illegal file name, command too long, and so
forth).

A device specification was not recognizable or is not available on the system.

Example
The following code accepts a line of input from the terminal, checks it for RT-ll
command format, and stores the resulting device block information in a 39-word
area called OUTSPC:
DEFEXT:
OUTSPC:

. WORD
. BLKW

39 •

0,0,0,0

.CSISPC

#OUTSPC,#DEFEXT,#0

;No default file types
;Device block area

.CSISPC

7-17

7.7 .DATE -

Return Current Date to RO

The .DATE directive returns the current month, day, and year to RO in the
following format:

bit

9
day (1-31)

year-72(O-31 )

The year value in bits 4-0 is the current year minus 72.
Note that this directive gets its date information from the RSTSIE clock. Unlike
the RT-ll operating system, you do not set the values returned with the DATE
keyboard monitor command.
Privileges Required

None
Macro Call

.DATE
RD Format

(RO) =

Errors

No errors are returned with the .DATE directive.
Example

The following subroutine can be assembled separately and linked to a user
program:
. TITLE

DATE.MAC

;CALLING SEQUENCE:
JSR
; INPUT:

NONE

; OUTPUT:

RO = DAY (1-31)
R1 = MONTH (1-12)
R2 = YEAR - 72
. MCALL

7-18

.DATE

PC,DATE

. DATE

DATE: :

. DATE
MOV
BIC
ASR
ASR
MOV
SWAB
BIC
ASR
ASR
ASR
BIC
CLC
RTS

RO,R2
*"C37,R2
RO
RO
RO,Rl
Rl
*"C37,Rl
RO
RO
RO
*"C37,RO

;Get the system date
;Copy the date
;Put month on a byte boundary
;Copy the date
;Put month in the low byte
;Isolate the month
;Shift day to a byte boundary

; Isolate the day
;Indicate no error

.END

.DATE

7-19

7.8 .DATTIM -

Return Date or Time

The .DATTIM directive is available only to RT-ll emulator users under RSTSIE;
it is not available under the RT-ll operating system..DATTIM converts a date
or time from the RSTSIE system internal format (as returned by the .DATE
directive, see Chapter 3) to an ASCII string suitable for printing. The format of
the string is the same as that returned by the BASIC-PLUS DATE$ and TIME$
functions. That is, a date is in the form "27-Jun-84"; or, if the system uses the
numeric date option, in the form "84.06.27". Similarly, a time is in the form
"02:30 PM" or "14:30".
The .DATTIM directive assumes that RO contains the address of the area to
which the string is to be returned. It also expects to find the date or time in
RSTSIE system internal format in the XRB. If a date is desired, it should be
in XRB+O. If a time is desired, the word at XRB+O should be cleared and the
time stored in XRB+2. Note that these are the locations returned by the RSTSIE
.DATE directive.
You can request a specific format for date or time rather than accepting the
format selected at system generation. If you set bit 15 ofXRB+O (date) or XRB+2
(time), you request a specific format rather than the default selected at system
generation. Bit 15 = 0 indicates the default. If bit 15 = 1, then bit 14 = 0 implies
numeric format; bit 14 = 1 indicates alphanumeric format.
Upon return from the call, RO contains the address of the first byte after the time
or date string.
Privileges Required

None
Macro Call

.DATTIM
Note that .DATTIM, like all RSTSIE-specific directives under RT-ll, is not expanded at assembly time. (It is not defined in the SYSMAC.SML file as a
directive.) You can code a definition of the directive in a data section of your
program or use .MACRO to define it. See the following example.
Errors

No errors are possible with the .DATTIM directive.
Example

The following program prints the current date and time at the job's terminal:
. MCALL
.EXIT, .PRINT
.PRIV = EMT+377
.DATTIM = EMT+361
.CSECT

7-20

.DATTIM

;Prefix EMT to RSTS/E
;Date/time EMT to RT-ll

START:

• PRIV, • DATE
MOV
XRB+2,-(SP)
MOV
DATE$,RO
.DATTIM
CLRB
(RO)+
.PRINT
:/tDATMSG
CLR
XRB
MOV
(SP)+,XRB+2
MOV
TIME$,RO
.DATTIM
(RO) +
CLRB
.PRINT
:/tTIMMSG
.EXIT

DATMSG:
DATE$:
TIMMSG:
TIME$:

. ASCII
.BLKW
. ASCII
.BLKW

. END

; Get date from RSTS/E
;Save time
;Set addr for ret. string
; Get date string
;Clear last byte for ASCIZ
;Print date message
;Clear date from XRB
; Set time in XRB
;Set addr for time string
;Get time string
; Make string ASCIZ
;Print time message
;End program

/The date is /
12
/The time is /
12

START

.DATIIM

7-21

7.9 .DELETE -

Delete File from Disk or DECtape

The .DELETE directive deletes a file from a disk or DECtape, deleting it from the
device directory and releasing the space for other use. The file description given
in the call includes a device, file name, and type. Set the PPN offset to include a
PPN for the file, if desired (see Chapter 6). Otherwise, the PPN of the calling job
is used.
Note that on RSTSIE systems, unlike the RT-ll operating system, it is possible to
delete files which are open; no error is returned.
Privileges Required

Write access to the file being deleted (if disk). DEVICE privilege is required if the
device is restricted.
Macro Call

.DELETE area,chanum,devblk,seqnum
where:
area

is the address of a three-word argument block.

chanum

is ignored on RSTSIE systems.

devblk

is the address of a four-word device block containing the device and file
specification. See Chapter 6 for the format of this area. See also the PPN
offset description for specifying a PPN.

seqnum

is ignored on RSTSIE systems.

Argument Block Format

I chanum

~(RO)

devblk
seqnum

Errors
Code

Meaning

The file named cannot be found.

The device specified is not a disk or DECtape.

Example

The following code deletes the file name FILNAM.TYP in the user's account on
disk unit 1:
AREA:

DEVBLK:

7-22

.DELETE

.BLKW
.RADSO

3
!DKIFILNAMTYP!

.DELETE

#AREA,#l,#DEVBLK

7.10 .DOCCl -

Do a RSTS/E .CCl

This directive lets a program running under control of the RT-ll run-time system
examine a string to see if it is a valid RSTSIE Concise Command Language (CCL)
command.
NOTE

.DOCCL must be used by programs running under the RT-ll run-time
system, rather than the general monitor .CCL command.
If the string is a valid CCL command, the RT-ll run-time system restores the low
512. bytes of memory to what the monitor expects and issues a general monitor
.CCL command. (See Chapter 3 for a description of .CCL.)
The starting address of the string to be examined is passed in RO. The string
itself must be in ASCIZ format (terminated with a zero byte).
Privileges Required

Execute access to the program that the CCL command executes.
Macro Call

.DOCCL
Note that .DOCCL, like all RSTSIE-specific directives under RT-ll, is not expanded at assembly time. (It is not defined in the SYSMAC.SML file as a
directive.) You can code a definition of the directive in a data section of your
program or use .MACRO to define it. See the following example.
Errors

The errors returned for .DOCCL are the same (and in the same format) as for
.CCL.
Example

The following code executes the CCL command PIP:
. DOCCL
STG:

EMT+367

.ASCIZ

/PIP/

MOV
. DOCCL

#STG,RO

.DOCCL

7-23

7.11

.DOFSS -

Do a RSTS/E .FSS

The .DOFSS directive examines a string to see if it is a valid RSTSIE file
specification. The RT-ll emulator restores the low 512. bytes of memory to what
the monitor expects and executes a .FSS directive.
NOTE

You must use .DOFSS rather than .FSS for a program running under
the RT-ll run-time system.
The .DOFSS directive assumes that RO contains the starting address of the
string and that the string itself is in ASCIZ format (terminated with a zero byte).
See the discussion of .FSS in Chapter 3 for an explanation of how the string is
processed. The data returned on completion of .DOFSS is the same as for .FSS.
Note that .DOFSS, like all RSTSIE-specific directives under RT-ll, is not
expanded at assembly time. (It is not defined in the SYSMAC.SML file as a
directive.) You can code a definition of the directive in a data section of your
program or use .MACRO to define it. See the following example.
Privileges Required

None
Macro Call

.DOFSS
Errors

The errors for .DOFSS are the same (and in the same format) as for .FSS.
Example

The following code checks the string FILE.NAM to see if it is a valid RSTSIE file
specification:
.DOFSS
STG:

EMT+365
.ASCIZ
/FILE.NAM/

MOV
.DOFSS

7-24

.DOFSS

#STG,RO

7.12 .DORUN -

Chain to Non-RT-11 RTS Program

Use the .DORUN directive to transfer control to programs that run under a
non-RT-ll run-time system.
NOTE

The .DORUN directive must be used from programs running under the
RT-ll run-time system, rather than the .RUN directive, since RT-ll
keeps user logical information in a different area in low-core than the
monitor expects.
The .DORUN directive causes the emulator to restore the user logical information
to its normal place in the low 512. bytes of memory and translates an RT-ll file
specification to the proper form in the FIRQB for a .RUN.
The .DORUN assumes that RO contains the address of a five-word file definition.
The first four words contain a normal RT-ll "device block" specification (see
Chapter 6); the last word contains a parameter to be passed to the run-time
system at FIRQB+FQNENT. If the address passed in RO points to a device
block within an outspec area returned by a previous .CSISPC directive, all of
the RSTSIE-specific information from the file specification (PPN, and so forth)
is loaded into the proper area in the FIRQB. Values in the first six words of the
scratch pad area take precedence over the values found in the string examined by
.CSISPC.
Privileges Required
Execute access to the specified program.
Macro Call
.DORUN
Note that .DORUN, like all RSTSIE-specific directives under RT-ll, is not expanded at assembly time. (It is not defined in the SYSMAC.SML file as a
directive.) You can code a definition of the directive in a data section of your
program or use .MACRO to define it. See the following example.
Errors
Errors are returned as for a .RUN directive.
Example
The following program uses .CSISPC to scan a user-entered file specification,
ensures that the program is entered with a zero parameter passed to the runtime system, and then attempts to execute the file with .DORUN. If an error
occurs for either the .CSISPC or the .DORUN, an error message is printed at the
job's terminal. The code follows:
.SETFQB = EMT+360
.DORUN = EMT+363

ERROR:
ERRMES:

.CSISPC
BCS
MOV
CLR
. DORUN
.PRINT
.EXIT

;Define EMT for SETFQB
,Define EMT for .DORUN
OUTSPC,DEFEXT,O
ERROR
OUTSPC,RO
4*2(RO)
#ERRMES

;Read, scan command string
;Command string in error
;Get devblk for first file
;Pass 0 at FIRQB+FQNENT
;Try to run the file
;An error occurred

.ASCIZ /?Can't run that file/
.DORUN

7-25

7.13 .DSTATUS -

Return Device Status

The .DSTATUS directive returns information about a device to a four-word area
defined in the user program.
Privileges Required

None
Macro Call

.DSTATUS stablk,devnam
where:
stablk

is the address of a four-word area to contain the returned status information.

devnam

is the address of one word containing a device and unit number, in RAD50
format. The word can also be a three-character user logical name in RAD50
format.

Information Returned to Statblk

status word (see format)
handler size (= 0 for RSTS/E)
load address (=160000 for RSTS/E)
device size (= 0 for RSTS/E)

Status Word Format

flags

handler index

The low byte contains the RT-ll handler index for the device:
Octal
Value

o
1
3

4
7
10
11

7-26

.DSTATUS

Device
(disk)
DT (DECtape)
LP (line printer)
KB (keyboard)
PR (paper tape reader)
PP (paper tape punch)
MT (magnetic tape)
CR (card reader)

The high byte describes the device characteristics. Note that you can combine the
device-characteristics flags. For example, a value of 140000 for the entire word
would indicate a file-structured, read-only disk. The word values are:
Device Characteristics
(Octal Word Value)

Meaning

100000
040000
020000

Device is file-structured
Device is read-only
Device is write-only

Errors
Code

Meaning

The device named in the devnam argument is not known on the system.

Example

The following code checks for status information for MTO:
STAT:
DEVNAM:

.BLKW
.RADSO

.DSTATUS

iSTAT,iDEVNAM

/MTO/

.DSTATUS 7-27

7.14 .ENTER -

Open File for Output

The .ENTER directive creates a new file and associates the file with a channel
number. You then use the channel number to refer to the file for other 110
operations.
A RSTSIE "tentative open" is done; that is, the file is not permanent until a
.CLOSE is executed with the same channel number as specified in the .ENTER
directive. Then, the tentative file is made permanent, and any already existing
file of the same name on the same device is deleted. A .PURGE, .HRESET, or
.8RESET directive deletes the tentative file; any already existing file of the same
name on the same device is left intact.
You can preallocate space for disk files by setting an argument in the call. Note
that you can also set a PPN, protection code, mode, and other RSTSIE parameters
applicable to opening a file for output by setting words in the scratch pad area
(see Chapter 6).
Privileges Required

Write access to the file.
Macro Call

.ENTER area,chanum,devblk,len,seqnum
where:
area

is the address of a four-word argument block.

chanum

is a channel number in the range 0 to 17 (octal). See Chapter 6 for rules on
channel numbers.

devblk

is the address of a four-word device-block containing the device and file
specifications. See Chapter 6 for the format of this area.

len

is the file size to be preallocated for the file, in 512-byte blocks (for disk files
only). Values can range from 1 to 32767. For large disk files on RSTSIE, you
must set the Most Significant Bits (MSB) byte in the scratch pad area (see
Chapter 6). RSTSIE ignores a zero or negative value.

seqnum

is ignored on RSTSIE systems.

Argument Block Format

chan urn

.... (RO)

devblk
len
seqnurn

Errors
Code

7-28

.ENTER

Meaning

Channel is already in use.

The file cannot be preallocated to the specified size, or the device is full.

Example
The following code opens the file·NEWFIL.SAV on MTO for output:
AREA:
DEVBLK:

.BLKW
.RADSO

4
/MTONEWFILSAV/

• ENTER

#AREA, #1, #DEVBLK, #0, #0

.ENTER 7-29

7.15 .ERRPRT -

Print RSTS/E Error Message

The .ERRPRT directive prints the RSTSIE error message text corresponding to
an error code on the user terminal. The call assumes that the error code is in RO.
The text is printed without a carriage-returnlline-feed combination.
Privileges Required

None
Macro Call

.ERRPRT
Note that .ERRPRT, like all RSTSIE-specific directives under RT-ll, is not expanded at assembly time. (It is not defined in the SYSMAC.SML file as a
directive.) You can code a definition of the directive in a data section of your
program or use .MACRO to define it. See the following example.
Errors

No errors are possible with the .ERRPRT directive.
Example
. MCALL
.REGDEF
.ERRPRT

.EXIT, .PRINT,.REGDEF

EMT+364

.CSECT
START:
10$:

CRLF:
.END

7-30

.ERRPRT

MOV
CLR
.ERRPRT
MOV
.PRINT
MOV
INC
SOB
.EXIT
. BYTE
START

256.,R1
RO
RO,-(SP)
*CRLF
(SP) +,RO
RO
R1,10$
0

;Number of errors to print
;Start with error zero
;Print error text
;Save RO
;Print a CRLF
;Restore RO
;Inc RO for next message
;Loop until all are printed

7.16 .EXIT -

Program Exit

The .EXIT directive terminates execution of the calling program. On exiting from
the calling job, the RSTSIE monitor drops any temporary privileges still in effect.
Then, control passes to the job keyboard monitor at the keyboard monitor entry
point (see P.NEW in Chapter 2).
NOTE

The job keyboard monitor is the default keyboard monitor unless the
job has issued the SET JOBIKEYBOARD_MONITOR command or has
issued a general monitor .RTS directive (see Chapter 3) to specify a job
keyboard monitor.
If RO = 0 when the .EXIT is executed, any channels still open will be released,
without the usual clean-up operations. In particular, any temporary files (opened
with .ENTER and not yet closed) will be deleted.
NOTE

Programs running under the RT-ll run-time system must use the
RT-ll .EXIT directive, not the general monitor .EXIT or .RTS directive.
Privileges Required
None
Macro Call
.EXIT
Errors
No errors are possible with the .EXIT directive.
Example
The following code exits such that files opened with .ENTER and not yet closed
will be deleted:
SAVOLD:

MOV

#O,RO

.EXIT

.EXIT 7-31

7.17 .FETCH -

Check Whether Device Exists

On RSTSIE systems, the .FETCH directive checks to see if a specified device
exists on the system.
Privileges Required

None
Macro Call

.FETCH addr,devnam
where:
addr

is ignored on RSTSIE.

devnam

is the address of a one-word, RAD50 device name. The format of this
word is the same as that described for the first word of a device block (see
Chapter 6).

Errors
Code

Meaning

The device specified does not exist on the system.

Example

The following code checks to see if LPO exists on the system:
DEVNAM:

7-32

.FETCH

.RADSO

/LPO/

.FETCH

to,tDEVNAM

7.18 .GETCOR -

Changes Job Image Size

This directive changes the amount of space currently allocated for the user job
image. The RT-ll emulator checks to ensure that the requested expansion will
not destroy the scratch pad area, moves the scratch pad area if necessary, and
then expands the job image size using the .CORE directive (see Chapter 3). Thus,
the same rules concerning size changes for .CORE also apply to .GETCOR.
The .GETCOR directive assumes that the new job image size, in K words, is in
RO. If the required expansion is not possible, the carry bit will be set on return
from the call. Otherwise, the size change succeeds, and word 44 now points to
the new location for the start of the scratch pad area.
NOTE

Programs running under the RT-ll run-time system must use
.GETCOR, not the general monitor .CORE directive.
You must use .GETCOR to expand the job image size before you use
.CHAIN to transfer control to a program that requires more memory
than the current program.
Privileges Required

EXQTA privilege is required to exceed the job's memory limit.
Macro Call

.GETCOR
Note that .GETCOR, like all RSTSIE-specific directives under RT-ll, is not
expanded at assembly time. (It is not defined in the SYSMAC.SML file as a
directive.) You can code a definition of the directive in a data section of your
program or use .MACRO to define it. See the following example.
Errors

If the requested change cannot be made, the carry bit is set on return from the
call.
Example

The following code uses .GETCOR to expand the user job image area to 24K
words before doing a .CHAIN:
.GETCOR = EMT+366

MOV
.GETCOR
BCS
. CHAIN

#24.,RO

ERRTN

.GETCOR

7-33

7.19 .GTIM -

Return Time-af-Day

The .GTIM directive returns the current time of day to a two-word area defined
by the user program. The current time is given in units of 1I60th second since
midnight.
Privileges Required

None
Macro Call

.GTIM area,timblk
where:
area

is the address of a two-word argument block.

timblk

is the address of a two-word block where the time is to be returned. The
first word will contain the Most Significant Bits (MSB) of the current time,
and the second word the Least Significant Bits (LSB).

Argument Block Format
o

~(RO)

timeblk

Errors

No errors are possible with the .GTIM directive.
Example

The following code returns the current time to a two-word area named TIME:
AREA:
TIME:

.BLKW
.BLKW

.GTIM

7-34

.GTIM

2
2

7.20 .GTJB -

Return Job High Limit

The .GTJB directive on RT-ll systems returns job parameters to an eight-word
area in memory. On RSTSIE systems, the only relevant parameter is the job's
high memory limit. All other words are set to zero.
Privileges Required

None
Macro Call

.GTJB area,addr
where:
area

is the address of a two-word argument block.

addr

is the address of an eight-word block to which the job parameters are
returned. On RSTSIE systems, only the second word is relevant: it is set to
the high memory limit of the user job image. All other words are set to zero.

Argument Block Format

0
addr

Errors

No errors are possible with the .GTJB directive.
Example

The following code stores job information in an area called JOBINF:
AREA:
JOBINF:

.BLKW
. BLKW

2
8•

.GTJB

4tAREA,4tJOBINF

.GTJB

7-35

7.21

.GTlIN -

Get line from Job's Terminal

The .GTLIN directive accepts a line of input from either the job's terminal or core
common and stores it in a buffer for later examination by the user program. You
can also specify an ASCIZ string to be displayed at the terminal before the line is
accepted .
.GTLIN reads the line from core common instead of the job's terminal if the
program is invoked with a parameter word of 8192. For example, the parameter
word normally has this value when a program is run by a CCL command. A
second .GTLIN causes the program to exit.
By default, .GTLIN returns a string in uppercase. To obtain lowercase letters, set
bit 14 in the Job Status Word (JSW) before you issue the .GTLIN.
Privileges Required
None
Macro Call
.GTLIN linbuf [,prompt]
where:
linbuf

is the address of an area to receive the input line. Up to 81 bytes can be
accepted from a terminal, so the buffer should be at least that long. The
line is stored in memory and terminated with a zero byte instead of with a
carriage-returnlline-feed combination.

prompt

is the address of a string to be printed on the job's terminal before input
is accepted. The string itself must be terminated with a zero byte or a 200
(octal) byte. If the string is terminated with a zero byte, the display ends
with a carriage-returnlline feed. If terminated with a 200 (octal) byte, the
display ends after the prompt string.

Errors

No errors are possible with the .GTLIN request.
Example
The following example prompts the job's terminal and accepts a line of input:
PROMPT:
LINBUF:

7-36

.GTUN

.ASCIZ
.BLKB

/YES OR NO?/
81.

.GTLIN

#LINBUF,#PROMPT

7.22 .GVAL -

Get Value from Scratch Pad

The .GVAL directive returns the contents of a word in the scratch pad area to RO.
You specify an offset from the beginning of the scratch pad.
Privileges Required

None
Macro Call

.GVAL area,of{set
where:
area

is the address of a two-word argument block.

offset

is the offset, in bytes, from the beginning of the scratch pad area of the
word desired. The offset value must be even. An odd offset causes a trap to
kernel mode vector at four.

Argument Block Format
o

.... (RO)

offset

Errors
Code

Meaning

The offset given is beyond the limits of the scratch pad area.

Example

The following example returns the contents of the PROTEC offset in the scratch
pad area to RO:
AREA:

.BLKW

.GVAL

:ftAREA,:ft2

.GVAL 7-37

7.23 .H RESET -

Hardware Reset

The .HRESET (hardware reset) directive closes all open channels for the program
without performing any of the normal clean-up operations (except to disassociate
the RT-ll channel numbers from their RSTSIE counterparts). For example, no
trailer labels are written to magnetic tape, no form feed is given for the line
printer, and so forth. Temporary files (created with .ENTER but not yet closed)
are deleted.
Privileges Required

None
Macro Call

.HRESET
Errors

No errors are possible with the .HRESET directive.
Example
.HRESET

7-38

.HRESET

7.24 .LOOKUP -

Open File for Input

The .LOOKUP directive opens an existing file and associates it with a channel
number; in RSTS/E terms, an OPEN FOR INPUT statement. The channel used
is then busy until one of the following directives is executed:
.CLOSE
.SAVESTATUS
.SRESET
.HRESET
.PURGE
.CSIGEN (if the channel number is in the range 0 to 8)
Note that you can set a PPN applicable to a RSTS/E OPEN FOR INPUT
statement by setting the appropriate words in the scratch pad area before
executing the .LOOKUP (see Chapter 6).
Privileges Required

For disk files, you need read access. If the device is restricted, you need DEVICE
privilege. You need RDNFS privilege to access disks in non-file-structured mode.
Macro Call

.LOOKUP area,chanum,devblk,seqnum
where:
area

is the address of a three-word argument block.

chanum

is a channel number in the range 0 to 17 (octal). See Chapter 6 for rules on
channel numbers.

devblk

is the address of a four-word device block containing the device and file
specifications. See Chapter 6 for general rules on the format of device
blocks.
The file name portion of the device block is ignored for non-file-structured
devices, such as a paper tape. If you want to do non-file-structured 110 on
a file-structured device, clear the first word of the file name portion of the
device block.

seqnum

is ignored on RSTSIE systems.

Argument Block Format

chanum

~(RO)

devblk
seqnum

Errors
Code

Meaning

Channel already open.

The file requested (in the device block) was not found.

.LOOKUP 7-39

Example
ERRBYT=42
ARGBLK: .BLKW
DEVBLK: .RAD50
.RAD50

NFD:
CAMSG:
NFMSG:

7-40

.LOOKUP

. LOOKUP
BCC
TSTB
BNE
.PRINT
.EXIT
.PRINT
.EXIT
.ASCIZ
.ASCIZ

/DT3/
/DATA

001/

;Leave space for arg block
;Define device,
iFilename and type

#ARGBLK,#7,#DEVBLK ;Open on channel 7
LDONE
;File was found
@#ERRBYT
iError--test further below
NFD
iFile not found
#CAMSG
;Print 'Channel Active'
#NFMSG

;PRINT 'File not found'

/Channel active/
/File not found/

7.25 .PRINT -

Display String on Job's Terminal

The .PRINT directive displays a specified ASCII string on the job's terminal. The
line can be terminated with or without a carriage-returnlline-feed combination.
Note that on RSTS/E systems, if the terminal is detached when a .PRINT is
issued, the job hibernates. That is, execution of the job is suspended until the
terminal is reattached to the job.

Privileges Required
None

Macro Call
.PRINT stradd
where:
stradd

is the starting address of the string to be printed. The string itself must be
terminated with either a zero byte or a byte value of 200. If the string is
terminated with a zero byte, the display ends with a carriage-returnllinefeed combination. If the string is terminated with a 200 byte, the display
ends with the string.

Errors
No errors are possible with the .PRINT directive.

Example
81:
82: .

.A8CIZ
.A8CII
.BYTE

/8tring will have CR-LF following/
/String will have no CR-LF following/
200

• EVEN

.PRINT
.PRINT

#81
#82

.PRINT

7-41

7.26 .PURGE -

Release Channel

The .PURGE directive can be used to release a channel when it is not desirable to
close the file normally. Any temporary file created by a .ENTER is discarded. A
.PURGE on a file that was opened with .LOOKUP will cause no action other than
to free the channel; any data written to the file will still be there. If the specified
channel is not open, the .PURGE is simply ignored; no error is returned.
Privileges Required
None
Macro Call
.PURGE chanum
where:
chanum

is a channel number in the range 0 to 17 (octal). See Chapter 6 for rules on
channel numbers.

RO Format
(RO) =

chanum

Errors
No errors are possible with the .PURGE directive.
Example
The following example verifies that channels 0 to 7 are free:
.TITLE

.PURGE.MAC
. MCALL
.PURGE, .EXIT

START:
1$

7-42

.PURGE

CLR
. PURGE
INC
CMF
BLO
.EXIT
.END

R1
R1
R1
R1,#8.
1$
START

;Start with channel 0
;Purge a channel
;Bump to next channel
;Is it at channel 8 yet

7.27 .RCTRLO -

Reset Ctri/O

The .RCTRLO directive restarts any progTammed output to the user's terminal
after such output has been stopped by the user-entered CtrllO or CtrllC.
Terminal service on RSTS/E maintains a "discard all program output" indicator
for each terminal on the system. When this indicator is set, the driver ignores
any output requests for that terminal. When the indicator is clear, output to the
terminal proceeds normally. The .RCTRLO directive clears this indicator.
The driver sets the indicator when the user enters a CtrllC or CtrllO combination
and reverses it when the user enters a CtrllO again.
Thus, when it is important that a message get through to the terminal, use a
.RCTRLO directive before the .PRINT or other request for output to make sure
that the message is displayed regardless of any user-entered Ctrl/O or CtrllC.

Privileges Required
None

Macro Call
.RCTRLO

Errors
No errors are possible with the .RCTRLO directive.

Example
The following example forces the message to be displayed on the user's terminal:
EOW:

.ASCIZ

/The end of the world is nigh/

. RCTRLO
.PRINT

#EOW

.RCTRLO 7-43

7.28 .READ/.READW/.READC -

Read Data

On RSTS/E systems, .READ, .READW, and .READC transfer data from a file
or device previously opened on a channel to a user buffer. Once the transfer is
complete, control returns to the user program inline, for .READ and .READW,
or to a user-specified completion routine, for .READC. You specify the maximum
number of words to be transferred; the actual number of words transferred is
returned in RO.
Note that you can set a modifier word in the scratch pad area for devices that use
this information. See the .READ directive in Chapter 3 for possible values of the
modifier word.

Privileges Required
None
Macro Call

{

.READ

}
area, chanum, bufadd,wrdcnt, blknum

.READW

or
.READC area,chanum,bufadd, wrdcnt,cmprtn, blknum
where:
area

is the address of a five-word argument block.

chanum

is a channel number in the range 0 to 17 (octal), previously defined in an
open (.LOOKUP).

bufadd

is the address of a buffer to contain the data to be read.

wrdcnt

is the maximum number of words to be read. The actual number of words
read may be less than wrdcnt; it is never more. The actual number of words
transferred is returned in RO.

cmprtn

is the address of a completion routine to which control is transferred when
the read is complete. (For .READC only.)

blknum

is the block number relative to the start of the file where the read is to
begin (for files opened with file-structured .LOOKUP). To access large files
on RSTS/E systems, you must set the word at offset 2 in the scratch pad
area; see Chapter 6. For devices opened with non-file-structured .LOOKUP,
blknum is the absolute block number or device cluster number where the
read is to begin.

For successive reads, your program must increment blknum.

7-44 .READ/.READW/.READC

Argument Block Format

I chanum

blknum
bufadd
wrdcnt
cmprtn*
• (The last word = 0 for .READW, or 1 for .READ.)

Errors
Code

Meaning

Attempt to read past end-of-file (EO F).

Hard error occurred on channel.

Channel is not open.

Example
The following code reads data from the device open on channel 7 to a 512. byte
user buffer:
AREA:
BUF:

.BLKW
.BLKW

5
512.

. READ

#AREA,#7,#BUF,#512.,#O

.READ/.READW/.READC 7-45

7.29 .RENAME -

Rename a File

The .RENAME directive changes the name of a file on disk or DECtape and
gives that file the current date in its directory entry. If a file with the new name
already exists on the specified device, it is deleted.
Privileges Required
If the device is restricted, you need DEVICE privilege. For disk files, you need

create/rename access to the file.
Macro Call
.RENAME area,chanum,namblk
where:
area

is the address of a two-word argument block.

chanum

is ignored on RSTSIE systems.

namblk

is the address of an eight-word area containing two four-word device and
file descriptor blocks (see Chapter 6). The first four-word block is the old
file name and the device where it is stored. The second four-word block
is the new file name; the device descriptor must be specified, and must be
the same as the device descriptor in the first four-word block. If a PPN is
specified in the first six words of the scratch pad, it is used for both the old
and the new file. If a protection code is given in the first six words of the
scratch pad, it is used for the new file. Other values in the first six words of
the scratch pad are ignored.

Argument Block Format

I chanum

~(RO)

devblk

Errors
Code

Meaning

No file with the "old" name was found on the device.

The device specified is not a disk or DECtape.

Example
The following code renames file OLDFIL.MAC to NEWFIL.MAC:
AREA:
NAMBLK:

7-46

.RENAME

.BLKW
.RADSO
.RADSO
.RADSO
.RADSO
.RADSO
.RADSO

.RENAME

*AREA,*O,*NAMBLK

/DT3/
/OLDFIL/
/MAC/
/DT3/
/NEWFIL/
/MAC/

7.30 .REOPEN -

Reopen File Closed with .SAVESTATUS

The .REOPEN directive reopens a file that was closed with a .SAVESTATUS
directive. You can use a different channel number than was used in the original
.LOOKUP and .SAVESTATUS, as long as the new channel is not already open.
The .SAVESTATUS and .REOPEN directives are easier to use than .CLOSE and
.LOOKUp, if your program needs to open more than 15 files during its execution.
The .SAVESTATUS directive retains the information necessary to reopen a file,
including the PPN. Thus, you do not need to reset the PPN offset in the scratch
pad area.
Privileges Required
If the device is restricted, you need DEVICE privilege. You need RDNFS privilege

to access a non-file-structured disk. You need read access to the file.
Macro Call

.REOPEN area,chanum,chnblk
where:
area

is the address of a two-word argument block.

chanum

is a free channel number in the range 0 to 17 (octal). See Chapter 6 for
rules on channel numbers.

chnblk

is the address of the five-word block where the channel status information
was stored (see .SAVESTATUS).

Argument Block Format

chanum

~ (RO)

chnblk

Errors
Code

Meaning

The specified channel is in use. The .REOPEN has not been done.

Example

The following code reopens a file closed with .SAVESTATUS using the device
block area named SAVBLK:
AREA:
SAVBLK:

.BLKW
.BLKW

2
5

.REOPEN

#AREA,#6,#SAVBLK

.REOPEN

7-47

7.31

.SAVESTATUS -

Save Status of File for later .REOPEN

The .SAVE STATUS directive closes a disk or DECtape file, saving all the
information needed to reopen the file later in execution of the program (see
.REOPEN). The information saved is stored in a five-word area in the user
program and includes the PPN for the file. Thus, the .SAVESTATUS/.REOPEN
combination is easier to use on RSTSIE systems than .CLOSE/.LOOKUP in this
case; you do not have to set the PPN offset in the scratch pad area.
The .SAVE STATUS directive can be used only if the file was opened with
.LOOKUP. If the file was opened with .ENTER, a .SAVESTATUS on that channel
returns an error.
Privileges Required

None
Macro Call

.SAVESTATUS area,chanum,chnblk
where:
area

is the address of a two-word argument block.

chanum

is a channel number in the range 0 to 17 (octa!), previously used in a
.LOOKUP directive for disk or DECtape.

chnblk

is the address of a five-word area to store the current information for the
file. On RSTSIE systems, the first four words of this area are set to the
device, file name, and type, in the standard RT-ll device-block format (see
Chapter 6). The last word of this area is set to the PPN of the file.

Argument Block Format

chanum

chnblk

Errors
Code

Meaning

The channel specified is not currently open; that is, a previous .LOOKUP on the
channel was never done.

The file was opened with .ENTER, or else the file is not on a disk or DECtape
device. The .SAVESTATUS is illegal.

Example

The following code saves the status of the file open on channel 12 for a later
reopen:
AREA:
SAVBLK:

7-48 .SAVESTATUS

.BLKW
.BLKW

2
5

.SAVEST

#AREA,#12.,#SAVBLK

7.32 .SCCA -

Pass Ctrl/Z to User Program

The .sCCA directive lets a user program recognize and process a CtrllZ combination entered on the job's terminal. When called with any nonzero value for the
addr argument, subsequent CtrllZs entered at the job's terminal are translated
to an ASCII 3 and passed like any other character to the program when it issues
a .TTYIN or .GTLIN. (Normally, a CtrllZ causes the RT-ll emulator to exit the
running program when a .READ or .TTYIN is done.)
NOTE

The operation of the .sCCA directive is quite different under RSTSIE
than under the RT-ll operating system, where it lets a user program
trap CtrllC combinations.
The .SETCC directive must be used for this function under the RT-ll
run-time system under RSTSIE. The intent is to let you code an
.SCCA directive to trap the delimiter equivalent in function on the two
systems.
On RSTSIE systems, CtrllZ is the "type-ahead terminator." You can, for example,
type RUN $MACRO, type the command line for the assembly, enter a CtrllZ, and
then type RUN $LINK You do not have to wait for the assembly to finish before
typing the command to link.
On RT-ll systems, CtrllC is the "type-ahead terminator." Hence, the .SCCA
directive processes the character appropriate to the system on both RSTSIE and
RT-ll systems.
Privileges Required

None
Macro Call

.SCCA area,addr
where:
area

is the address of a two-word argument block.

addr

is a switch. Any nonzero value for this argument causes CtrllZs to be passed
to the user program, as described previously. A zero value returns Ctrl/Z
processing to the emulator.

Argument Block Format
35

addr

Errors

No errors are possible with the .SCCA directive.

.SCCA

7-49

Example
The following code causes CtrllZs to be passed to the program:
AREA:

7-50 .SCCA

.BLKW

.SCCA

#AREA,U

7.33 .SETCC -

Process Ctri/C

The .SETCC directive defines a routine to be entered when the user enters one
CtrllC on the job's terminal. (Two consecutive CtrllCs still aborts the running
program.) The address of the routine to be entered is assumed to be in RO when
the .SETCC is executed.
The .SETCC is only effective until the first CtrllC; you must reissue the .SETCC
from the trap routine if you want it to remain in effect. You must also reenable
CtrllO processing with .RCTRLO. Use an RTI instruction to exit from the trap
routine. See the discussion of offset 66 in the scratch pad area in Chapter 6 for
further information on Ctrl/C processing under the RT-ll run-time system.
Privileges Required

None
Macro Call

.SETCC
Note that .SETCC, like all RSTSIE-specific directives under RT-ll, is not expanded at assembly time. (It is not defined in the SYSMAC.SML file as a
directive.) You can code a definition of the directive in a data section of your
program or use .MACRO to define it. See the following example.
Errors

No errors are possible with the .SETCC directive.
Example

The following code defines a routine to be entered when the user enters a CtrllC
on the job's terminal:
.SETCC = EMT+362
MESAGE:
.ASCIZ

MOV
.SETCC

CTLC:

. RCTRLO
.PRINT
MOV
.SETCC
RTI

"You typed a Ctrl/C!"

:fI:CTLC,RO

:fI:MESAGE
:fI:CTLC,RO

.SETCC

7-51

7.34 .SETFQ8 -

Set Up FIRQ8

The .SETFQB directive can be used after a .CSISPC; the two calls combined
return information to the FIRQB and XRB as if the file specification string had
been examined by .FSS.
The call assumes that RO contains the address of the first word of a device block
returned by .CSISPC. As noted in the discussion of .CSISPC, the device-block
information must not have been moved; thus, the address in RO must be the
address of the first word of a device block within the "outspc" area returned by
the last .CSISPC.
Note that any information in the first six words of the scratch pad area overrides
any RSTSIE-specific information returned by the .CSISPC. In addition, the
.SETFQB clears the first six words of the scratch pad after using the information.
Privileges Required

None
Macro Call

.SETFQB
Note that .SETFQB, like all RSTSIE-specific directives under RT-ll, is not
expanded at assembly time. (It is not defined in the SYSMAC.SML file as a
directive.) You can code a definition of the directive in a data section of your
program or use .MACRO to define it. See the following example.
Errors

No errors are possible with the .SETFQB directive.
Example

The following code returns information to the FIRQB and XRB about the file
following the equal sign (=) in an RT command:
.SETFQB = EMT+360

.CSISPC
MOV
.SETFQB

7-52

.SETFQB

iOUT,iEXT,icMD
iOUT+<3*5*2>,RO

7.35 .SETTOP -

Expand to Start of Scratch Pad

On RSTSIE systems, the .SETTOP directive sets the contents of the word at
location 50 in the low 512 bytes of memory to the value specified in .SETTOP.
The value itself cannot equal or exceed the starting address of the scratch pad
area (see Chapter 6). If such a value is specified, .SETTOP simply sets the
contents oflocation 50 to the address of the first word after the starting address
of the scratch pad. The value actually set in word 50 is also returned to RO on
completion of the call.
Privileges Required

None
Macro Call

.SETTOP adrval
where:
adrval

is a value specifying the address to which location 40 is to be changed.

Errors

No errors are possible with the .SETTOP directive.
Example

The following code sets the contents of location 50 to the address of the word after
the start of the scratch pad:
.SETTOP *-2

.SETTOP 7-53

7.36 .SFPA -

Set Floating-Point Error Address

The .SFPA directive indicates that you want to handle floating-point errors
yourself. You specify the address of a routine to be entered if such errors occur.
The .SFPA works for errors on both the FIS (floating-point instruction set on
the PDP-11135 and 11/40) and the FPP or FPU (hardware floating-point units
compatible with the PDP-11/45 and 11170 asynchronous unit) and its equivalents.
In the case of FPP or FPU hardware, two words have been pushed on the stack:
the Floating-Point Exception Code (FE C) at the top of the stack and the Floating
Error Address (FEA) one word down. Your routine can process these words in
any way it sees fit and should pop them from the stack before issuing an RTI
instruction to return control to the program where it left off when the errors
occurred.
The .SFPA directive works only for one floating-point error trap. You must
reexecute the .SFPA from your error-processing routine to ensure that successive
errors are handled in the same way. You can disable traps to your error routine
by issuing the .SFPA directive with a zero address argument.
NOTE

You should not use .SFPA in a routine called by a FORTRAN program,
because programs compiled under FORTRAN have their own FPPIFIS
exception handling routines and expect to find the FPU status as they
have set it.
Privileges Required
None
Macro Call
.SFPA area,addr
where:
area

is the address of a two-word argument block.

addr

is the address of the routine to be entered when a floating-point error occurs.

Argument Block Format
30

addr

Errors
No errors are possible with the .SFPA directive.
Example
The following code defines ERRTN as the address of the error routine to be
entered when a floating-point error occurs:
AREA:

7-54 .SFPA

.BLKW

.SFPA

#AREA,#ERRTN

7.37 .SPFUN -

Special Functions for I/O

The .sPFUN directive handles special functions for disk, tenninal, magnetic tape,
and flexible diskette.
Privileges Required

None
Macro Call

.SPFUN area,chanum,func,buf [,wcnt] [,blk][,crtn]
where:
area

is the address of a six-word argument block.

ehanum

is a channel number in the range 0 to 17 (octal), defining the device on
which the special function is to be performed. The channel must have been
previously opened with .LOOKUP.

rune

is a special function code. To request magnetic tape special functions
emulating RT-U's .SPFUN, set this argument to one of the following values:
377
Write end-of-file
376
Forward 1 record
375
Backspace 1 record
373
Rewind to load point
372
Offline rewind
Any other value for this argument is used as the function code (at
XRB+XRLEN) in a RSTSIE .SPEC directive (see Chapter 3).

bur

is used as the value of the word at XRB+XRLOC in a RSTSIE .sPEC
directive. It must be set to zero if the fune argument is 377, 376, 375, 373,
or 372.

went

is used as the value of the word at XRB+XRBC in a RSTS/E .SPEC directive.
It is ignored (and can be omitted) if the fune argument is 377,376,375,373,
or 372.

blk

is used as the value of the word at XRB+XRBLK in a RSTSIE .sPEC
directive. It is ignored (and can be omitted) if the fune argument is 377,
376, 375, 373, or 372.

ertn

is the address of a completion routine to which control is to be transferred
when the operation is complete. If this argument is omitted, control returns
to the instruction following the .SPFUN when the operation is completed.

Note that if you are using .SPFUN to do a RSTSIE .SPEC, the RT-ll emulator
fills in the RSTSIE channel number and device handler values in the XRB for
you.
Argument Block Format
32

I ehanum
blk
buf
went

fune

I 377
ertn

,SPFUN

7-55

Errors
Code

Meaning

Tried to read past end-of-file.

Hard error occurred on channel.

Channel is not open.

Example

The following code rewinds a magnetic tape (open on channel 4):
AREA:

7-56

.SPFUN

.BLKW

.SPFUN

tAREA,t4,t373,tO

7.38 .SRESET -

Software Reset

On RSTSIE systems, the .8RESET directive does the same thing as a hardware
reset (.HRESET). It closes all open channels for the program without performing
any of the normal clean-up operations (except to disassociate the RT-U channel
numbers from their RSTS/E counterparts). For example, no trailer labels are
written to magnetic tape, no form feed is given for the line printer, and so forth.
Tentative files (created with .ENTER but not yet closed) are deleted.

Privileges Required
None

Macro Call
.8RESET

Errors
No errors are possible with the .8RESET directive.

Example
.SRESET

.SRESET 7-57

7.39 .TRPSET -

Intercept Traps to 4 and 10

The .TRPSET directive allows the user program to trap to a user routine on
errors that normally cause the program to abort execution. Control passes to the
address specified in the call when the job tries to execute a reserved instruction
(normally trapped to kernel mode address 10) or issues an instruction with an
odd address (normally trapped to kernel mode address 4).
The carry bit indicates which error occurred. When control is passed to the
error-handling routine, the carry bit is zero if the error was an odd-address
error. If the carry bit is one, the error was a reserved-instruction error. An RTI
instruction will return control to the user program from the trap routine.
Note that the .TRPSET directive affects only the next error causing such a trap.
You must reissue the .TRPSET from your error-handling routine if you want to
handle such errors consistently.
Privileges Required

None
Macro Call

.TRPSET area,addr
where:
area

is the address of a two-word argument block.

addr

is the address to which control is to be passed when a reserved-instruction
or odd-address error occurs.

Argument Block Format
3

addr

Errors

No errors are possible with the .TRPSET directive.
Example

The following code defines TRPRTN as the address of the routine to be entered
when a reserved-instruction or odd-address error occurs:
AREA:

7-58

.TRPSET

.BLKW

.TRPSET

iAREA,iTRPRTN

TRPRTN:

Bee

ODDADR:

(code for odd address)

ODDADR
(code for reserved instruction)

7.40 .TTVIN/.TTINR -

One-Character Read From Terminal

The .TTYIN and .TTINR directives both accept input from the job's terminal and
transfer one character to the low byte of RO.
Bits 6 and 12 of the job status word (JSW) affect how the transfer is done.
If bit 12 of the JSW = 0, the .TTYIN/.TTINR waits until a whole line has been

typed at the job's terminal and then transfers one character to the low byte of
RO. Succeeding .TTYIN/.TTINR requests win then transfer remaining characters,
including carriage return and line feed. In addition, the usual monitor processing
for terminal input occurs: all characters typed are echoed at the terminal, and
CtrllU and DELETE delete a line or a character, respectively.
If bit 12 of the JSW = 1, ODT-mode input is done. That is, characters are

transferred when they are available, rather than waiting for a whole line to
be typed before passing a character to the user program. One .TTYIN/.TTINR
transfers one character. Furthermore, characters typed are not echoed at the
terminal, and CtrllU and DELETE are simply passed on to the user program.
(CtrllC and CtrllO are processed as usual, however. CtrllS and CtrllQ are
processed, if that option was requested for your terminal with TTYSET.) No
ALTMODE conversion is done.
If bit 6 = 1, control returns to the user program with the carry bit set if no

character can be returned to the program. Note that this should only be used
with .TTINR, and only when the program needs to perform other processing
while waiting for terminal input. If bit 6 = 0, control does not return to the user
program until a character can be passed to the program.
If used, bits 6 and 12 in the JSW must be set by the user program; they are

cleared automatically when a program terminates.
NOTE

Single character I/O places heavy demand on RSTSIE system resources
and can degrade system performance. These calls are provided only for
compatibility with RT-U.
Privileges Required

None
Macro Calls

.TTYIN [addr]
or
.TTINR
where:
addr

is the address of a location where the character is to be stored, in addition
to being stored in RO. If the address is omitted, the character is stored only
in RO.

Errors
Code

Meaning

No character or characters are available in the monitor buffer for terminal I/O
(only applies to .TI'INR).

.TTYIN/.TTINR 7-59

Example
The following code transfers one character from the job's terminal to the low byte
ofRO:
.TTYIN

7-60

.TTYIN/.TTINR

7.41

.TTYOUT/.TTOUTR - Transfer One Character to Job's
Terminal
The .TTYOUT and .TTOUTR directives both transfer one character from the low
byte of RO to the job's terminal. Using .TTYOUT or .TTOUTR is slower than
using .PRINT because they require more system overhead. Use .PRINT whenever
possible.
Note that on RSTSIE systems, if the terminal is detached when a .TTYOUT
or .TTOUTR is executed, the job hibernates. That is, execution of the job is
suspended until the terminal is reattached to the job.
Privileges Required

None
Macro Call

.TTYOUT [addr]
or
.TTOUTR
where:
addr

is the address of a memory location containing the character to be printed.
The character is loaded into RO first. When control returns from the call,
RO still contains the character. If you omit this address, RSTSIE prints the
character in the low byte of RO at the job's terminal.

Errors

No errors are possible with the .TTYOUT and the .TTOUTR directives under
RSTSIE.
Example

The following example transfers one character from the low byte of RO to the job's
terminal:
PROMPT:

.ASCII

/*/

MOV
.TTYOUT

#PROMPT,RO

.TTYOUT/.TIOUTR 7-61

7.42 .TWAIT -

Timed Wait

The .TWAIT directive suspends execution of the job for a specified number of
clock ticks: a sleep, in RSTS/E terms.

Privileges Required
None

Macro Call
.TWAIT area,addr
where:
area

is the address of a two-word argument block.

addr

is the address of a two-word block specifying the length of time to sleep
in units of 1I60th second. The first word contains the high-order bits; the
second word contains the low-order bits.

Argument Block Format
24

0
addr

Errors
No errors are possible with the .TWAIT directive.

Example
The following code suspends program execution for 5 seconds:
AREA:
ADDR:

7-62

.TWAIT

.BLKW
.BLKW

CLW
MOV
. TWAIT

#ADDR
#300.,#ADDR+2
#AREA,#ADDR

7.43 .WAIT -

Check for Channel Open

On RSTSIE systems, the .WAIT directive checks to make sure that the specified
channel is open. If not, the call returns with an error.
Privileges Required

None
Macro Call

.WAIT chanum
where:
is the channel number to be tested. The number can be in the range 0 to 17
(octal).

chanum

RO Format

RO =

chanum

Error
Code

Meaning

The specified channel is not open.

Example

The following code checks to see if channel 7 is open and branches if it is not:
. WAIT
BCS

#7 .
#NOTOPN

.WAIT 7-63

7.44 .WRITE/.WRITW/.WRITC -

Write Data

On RSTSIE systems, .WRITE, .WRITW, and .WRITC transfer data from a user
buffer to a file or device previously opened on a channel. After the transfer is
complete, control is passed to the user program inline, for .WRITE and .WRITW,
or to a user-specified completion routine, for .WRITC. The number of words
actually written is returned in RO when the call completes.

Privileges Required
EXTQA privilege suppresses disk quota checks when extending a disk file.

Macro Call
{

.WRITE

}
area,chanum,bufadd,wrdcnt, blknum

.WRITW

or
.WRITC area,chanum, bufadd, wrdcnt,cmprtn,blknum
where:
area

is the address of a five-word argument block.

chanum

is a channel number in the range 0 to 17 (octal), previously defined in an
open (.ENTER or .LOOKUP).

bufadd

is the address of the buffer containing the data to be written.

wrdcnt

is the number of words to be written.

cmprtn

is the address of a completion routine to which control is transferred when
the write is complete. (For .WRITe only.) For .WRITE and .WRITW, control
is returned to the instruction following the directive when the write is
complete.

blknum

is the block number relative to the start of the file where the write is to
begin. (For files opened with file-structured .ENTER or .LOOKUP.) For
devices opened with non-file-structured .ENTER or .LOOKUP, the blknum
argument is used as the absolute block number or device cluster number
where the write is to begin.

NOTE

To access large files on RSTSIE systems,
you must set the word at offset 2 in the
scratch pad area (see Chapter 6). To do
successive writes, your program must
increment blknum.

7-64

WRITElWRITW/WRITC

Argument Block Format

I chanum

blknum
bufadd
wrdcnt
cmprtn*
• The last word is set to 1 for .WRITE or to 0 for .WRITW.

Errors
Code

Meaning

No more room is available on the device. For example, the end-of-tape (EOT)
marker has been encountered, no more available disk space, and so forth.

Some hard I/O device error occurred. For example, the specified device is offline,
is physically write-locked, and so forth.

The channel specified is not open.

Example
The following code writes a 256-word block to the device open on channel 12:
AREA:
BUF:

.BLKW
.BLKB

512.

.WRITE

#AREA,#12.,#BUF,#256.,#O

.wRITEI.wRITW/.wRITC 7-65

7.45 .. V1 .. / .. V2 .. -

Use Version 1/Version 2 Expansion

If you have a source program that was coded for Version 1 or Version 2 of the RT-

11 operating system and you want to assemble on RSTSIE using the expansions
that were used for these versions, you must use either the ..Vl.. directive (for
Version 1 expansions) or the ..V2 .. directive (for Version 2 expansions).
You cannot use both the ..Vl.. and ..V2.. directives. You can use directives
from more than one version by specifying the ..Vl.. directive and simply using
the directives from later versions. If the same directive exists in two or three
versions, though, you get the expansion from the earliest version.
These directives generate code that defines and sets a variable called ...Vl to
either 1 or 2, which the MACRO assembler uses to determine the expansions to
use. So, if the .. Vl.. or ..V2 .. directive is used, it must appear before any other
RT-11 directives in your program.
NOTE

All the examples in this chapter show Version 2 expansions. Version 1
expansions require different arguments in the calls. See RT-11 system
documentation if you need to use version 1 expansions.

Privileges Required
None

Macro Call
. .vl..
or
..V2 ..

7-66

.. V1 ..!..V2 ..

Appendixes

Appendix A

Fu II List of Errors

This appendix lists the error messages that you may encounter when using
RSTSIE. The question mark (?) and percent sign (%) characters preceding the full
error text indicate the error's severity:

•

A single question mark precedes nonfatal errors; the command failed but you
can continue

•

A double question mark precedes severe errors; the command failed and you
cannot continue

•

A percent sign precedes a warning message; the command may not have
performed as you intended but execution continues

Informational messages have neither character; they provide extra detail about
the effects of a command.
Table A-l summarizes the RSTSIE error messages.
Table A-1 : RSTS/E Errors
ERR.STB
Mnemonic

Decimal
Value

Octal
Value

BADDIR
BADNAM
INUSE
NOROOM
NOSUCH
NODEVC
NOTCLS
NOTAVL
NOTOPN
PRVIOL
EOF
ABORT
DATERR

1
2
3
4
5
6
7
8

1
2
3
4
5
6
7
10

HNGDEV
HNGTTY

14
15

12
13
14
15
16
17

12
13

Full Error Text
??Bad directory for device
?Illegal file name
?Account or device in use
?No room for user on device
?Can't find file or account
?Not a valid device
?IIO channel already open
?Device not available
?IIO channel not open
?Protection violation
?End of file on device
??Fatal system 110 failure
?Data error on device
?Device hung or write locked
?Keyboard wait exhausted
(continued on next page)

Full List of Errors

A-1

Table A-1 (Cant.):

RSTS/E Errors

ERR.STB
Mnemonic

Decimal
Value

Octal
Value

Full Error Text

FIEXST

?Name or account now exists

DTOOOF

?Too many open files on unit

BADFUO

?Illegal SYS ( ) usage

INTLCK

?Disk block is interlocked

WRGPAK

?Pack IDs don't match

NOTMNT

?Disk pack is not mounted

PAKLCK

?Device is restricted

BADCLU

?Illegal cluster size

PRIVAT

?Account does not exist

INTPAK

%Disk pack needs REBUILDing

BADPAK

??Disk pack mount error

DETKEY

?I/O to detached keyboard

CTRLCE

Programmable AC trap

SATTBD

??Corrupted file structure

DEVNFS

?Device not file-structured

BADCNT

?Illegal byte count for I/O

NOBUFS

?No buffer space available

B.4

??Odd address trap

B.I0

??Reserved instruction trap

B.250

??Memory management trap

B.STAK

??SP stack overflow

B.SWAP

??Disk error during swap

B.PRTY

??Memory parity failure

MAGSEL

?Maptape select error

MAGRLE

?Maptape record length error

NRRTS

??Non-res run-time system

VCSERR

?Virtual buffer too large

VCAERR

?Virtual array not on disk

SIZERR

?Matrix or array too big

VCOERR

?Virtual array not yet open

BSERR

?Illegal I/O channel

LINERR

?Line too long

FLTERR

%Floating point error

EXPERR

%Argument too large in EXP

FMTERR

%Data format error

FIXERR

%Integer error

BDNERR

?Illegal number

LOGERR

%Illegal argument
(continued on next page)

A-2

Full List of Errors

Table A-1 (Cont.):

RSTS/E Errors

ERR.8TB
Mnemonic

Decimal
Value

Octal
Value

SQRERR

66
67
70

?Subscript out of range

?Out of data

72
73
74
75
76

?ON statement out of range

NORTS

54
55
56
57
58
59
60
61
62

FIELDE

63
64

NOTMTA

65
66

77
100
101
102

?FIELD overflows buffer

NORACS

SUBERR
MINVER
ODD
ONBAD
NEDERR
IOLERR
DIVBYO

ERRERR
BADSWT
EOV
QUOTA

67
68
69
70

STMERR

EXITTM

72
73
74

EXITNR
UNDFNI

TLMFND

75
76
77
78
79
80
81
82
83

TLRNNM

MODERR

85
86
87
88
89

COSERR
TLOPNV
TLNZSP
TLNOIT
TLIFFE
TLCONI
TLNOTF
TLQDUM

OUTOAS
FUNERR
TLTMAF
TLINCD
CPNSDF

90
91

103
104
105
106
107
110
111
112

Full Error Text
%Imaginary square roots
?Can't invert matrix

?Not enough data in record
?Integer overflow, FOR loop
%Division by 0
?No run-time system
?Not a random access device
?Illegal MAGTAPE( ) usage
?Missing special feature
?Illegal switch usage
?End of volume
?Quota exceeded
??Unused ERROR message 70
?Statement not found
?RETURN without GOSUB
?FNEND without function call
?Undefined function called

113
114
115
116
117
120
121
122
123
124
125
126
127
130
131
132

?Illegal symbol

133

?Illegal DEF nesting

?Illegal verb
?Illegal expression
?Illegal mode mixing
?Illegal IF statement
?Illegal conditional clause
?illegal function name
?Illegal dummy variable
?Illegal FN redefinition
?Illegalline number(s)
?Modifier error
?Can't compile statement
?Expression too complicated
?Arguments don't match
?Too many arguments
%Inconsistent function usage

(continued on next page)

Full List of Errors

A-3

Table A-1 (Cont.):

RSTS/E Errors

ERR.STB
Mnemonic

Decimal
Value

Octal
Value

Full Error Text

CPUPFR

134

?FOR without NEXT

CPUFNX

135

?NEXT without FOR

CPUPDF

136

?DEF without FNEND

CPUPED

137

?FNEND without DEF

TLJNKY

140

?Literal string needed

TLNOFN

141

?Too few arguments

SASYNE

142

?Syntax error

SAFNOS

143

?String is needed

SASNOI

100

144

?Number is needed

TLURTP

101

145

?Data type error

TLXDIM

102

146

?1 or 2 dimensions only

FUCORE

103

147

??Program lost-sorry

RESERR

104

150

?RESUME and no error

DIMED2

105

151

?Redimensioned array

TLIDIM

106

152

%Inconsistent subscript use

NOGOTO

107

153

?ON statement needs GOTO

EOSERR

108

154

?End of statement not seen

TLCNTD

109

155

?What?

TLPRNM

110

156

?Bad line number pair

EDBMCE

111

157

?Not enough available memory

EDEXON

112

160

?Execute only file

NRNERR

113

161

?Please use the RUN command

EDCONE

114

162

?Can't CONTinue

EDARSV
PRERRS

115
116

163
164

?PRINT-USING format error

UDMERR

117

165

?Matrix or array without DIM

PRNER1

118

166

?Bad number in PRINT-USING

?File exists-RENAMEIREPLACE

NONOIM

119

167

?Illegal in immediate mode

PRNER2

120

170

?PRINT-USING buffer overflow

BAD ERR

121

171

?Illegal statement

DISERR

122

172

?Illegal FIELD variable

STPERR

123

173

Stop

DIMERR

124

174

?Matrix dimension error

NOMATH

125

175

?Wrong math package

XCDCOR

126

176

??Maximum memory exceeded

SCAERR

127

177

%SCALE factor interlock

128

200

?Tape records not ANSI

129

201

?Tape BOT detected

(continued on next page)

A-4

Full List of Errors

Table A-1 (Cont.):
ERR. 8TH
Mnemonic

RSTS/E Errors

Decimal
Value

Octal
Value

130
131

202
203

132
133
134
135

204
205
206
207

?Illegal usage

136
137

210

?Illegal or illogical access
?Illegal key attributes

138

211
212

139
140

213
214

?Invalid file options

141
142
143
144
145
146

215
216

?Illegal operation

217
220

?Bad record identifier

221
222

?Key size too large

147

223
224

?RECORD number exceeds max

148
149
150

Full Error Text
?Key not changeable
?No current record
?Record has been deleted
?Illegal usage for device
?Duplicate key detected

?File is locked
?Index not initialized
?Illegal record on file
?Invalid key of reference
?Tape not ANSI labeled
?Bad RECORDSIZE on OPEN

225
226

?Not at end offile

151
152
153
154

227
230
231

?Key field beyond record end

232

?Recordlbucket locked

155
156
157

233
234
235

?Record not found

158
159
160

236
237
240

?Primary key out of sequence

161
162
163

241
242
243

?Move overflows buffer

164
165

244
245

?Terminal fmt file required

166
167

246
247

?Negative fill or string len

?No primary key specified
?Illogical record accessing
?Record already exists

?Size of record invalid
?Record on file too big
?Key larger than record
?File attributes not matched
?Cannot open file
?No file name
?Cannot position to EOF
?Illegal record format
(continued on next page)

Full List of Errors

A-5

Table A-1 (Cont.):
ERR.STB
Mnemonic

RSTS/E Errors

Decimal
Value

Octal
Value

Full Error Text

168

250

?Illegal ALLOW clause

169

251

??Unused ERROR message 169

170

252

?Indexed not fully optimized

171

253

?RRV not fully updated

172

254

?Record LOCK failed

173

255

?Invalid RFA field

174

256

?Unexpired file date

175

257

?Node name error

176

260

?Negative TAB not allowed

177

261

?Too much data in record

178

262

?OPEN error - file corrupted

179

263

??Unused ERROR message 179

180

264

?No support for op in task

181

265

?Decimal overflow

182

266

?Network operation rejected

183

267

?REMAP overflows buffer

184

270

?Unaligned REMAP variable

185

271

%RECORDSIZE overflows MAP

186

272

?Improper error handling

187

273

?Illegal record lock clause

188

274

??Unused ERROR message 188

189

275

??Unused ERROR message 189

190

276

??Unused ERROR message 190

191

277

??Unused ERROR message 191

192

300

??Unused ERROR message 192

193

301

??Unused ERROR message 193

194

302

??Unused ERROR message 194

195

303

??Unused ERROR message 195

196

304

??Unused ERROR message 196

197

305

??Unused ERROR message 197

198

306

??Unused ERROR message 198

199

307

??Unused ERROR message 199

200

310

??Unused ERROR message 200

201

311

??Unused ERROR message 201

202

312

??Unused ERROR message 202

203

313

??Unused ERROR message 203

204

314

??U nused ERROR message 204

205

315

??Unused ERROR message 205
(continued on next page)

A-6

Full List of Errors

Table A-1 (Cont.):
ERR.STB
Mnemonic

RSTS/E Errors

Decimal
Value

Octal
Value

Full Error Text

206

316

??Unused ERROR message 206

207

317

??Unused ERROR message 207

208

320

??Unused ERROR message 208

209

321

??Unused ERROR message 209

210

322

??Unused ERROR message 210

211

323

??Unused ERROR message 211

212

324

??Unused ERROR message 212

213

325

??Unused ERROR message 213

214

326

??Unused ERROR message 214

215

327

??Unused ERROR message 215

216

330

??Unused ERROR message 216

217

331

??Unused ERROR message 217

218

332

??Unused ERROR message 218

219

333

??Unused ERROR message 219

220

334

??Unused ERROR message 220

221

335

??Unused ERROR message 221

222

336

??Unused ERROR message 222

223

337

??Unused ERROR message 223

224

340

??Unused ERROR message 224

225

341

??Unused ERROR message 225

226

342

??Unused ERROR message 226

227

343

?String too long

228

344

?RECORDTYPES not matched

229

345

??Unused ERROR message 229

230

346

?No fields in image

231

347

?TIlegal string image

232

350

?Null image

233

351

?TIlegal numeric image

234

352

?Numeric image for string

235

353

?String image for numeric

236

354

?TIME limit exceeded

237

355

?1st arg to SEQ$ > 2nd

238

356

?Arrays must be same DIM

239

357

?Arrays must be square

240

360

?Cannot change array DIMs

241

361

?Floating overflow

242

362

?Floating underflow

243

363

?CHAIN to nonexistent line
(continued on next page)

Full List of Errors

A-7

Table A-1 (Cent.):
ERR.STB
Mnemonic

A-8

Full List of Errors

RSTS/E Errors

Decimal
Value

Octal
Value

Full Error Text

244

364

?Exponentiation error

245

365

?Illegal exit from DEF*

246

366

?Error trap needs RESUME

247

367

?Illegal RESUME to SUBR

248

370

?Illegal subroutine return

249

371

?Argument out of bounds

250

372

?Not implemented

251

373

?Recursive subroutine call

252

374

?FILE ACP failure

253

375

?Directive error

254

376

??Unused ERROR message 254

255

377

??Unused ERROR message 255

Appendix B

Device Information

This appendix summarizes MODE and RECORD values and other useful
information for:

• Disks
• Flexible diskettes

•
•
•

Magnetic tape
Line printers
Terminals

• Pseudo keyboards
For your convenience, the tables show both decimal and octal values, and list the
FIRQB and XRB offsets. All decimal values have a decimal point; values without
a decimal point are in octal.
This appendix is a quick reference. See the RSTS / E Programming Manual
(except where otherwise noted) if you need more detail on any topic.

B.1

Disks
This section summarizes disk MODE values and lists the device cluster size and
total size for each disk that RSTSIE supports.
Table B-1 summarizes disk MODE values for file-structured access.
Table B-1:

MODE Values for File-Structured Disk Access (FIRQB+FQMODE)

Decimal

Octal

Function

Normal read/write

Update

Append

Guarded update (4 + 1)

Special extend (RSTSIE updates file's size and retrieval pointers
during extend operations)

16.

Create contiguous file

32.

Create tentative file

(continued on next page)

Device Information

B-1

Table B-1 (Cont.):

MODE Values for File-Structured Disk Access (FIRQB+FQMODE)

Decimal

Octal

Function

64.

100

Create contiguous file conditionally

128.

200

No supersede

256.

400

Random data caching (requires TUNE privilege)

512.

1000

Create file and place at beginning of directory (with 2000)

1024.

2000

Create file and place at end of directory

2048.

4000

Sequential data caching (with 400)

4096.

10000

Read normally regardless

8192.

20000

Open file read-only

16384.

40000

Write UFD (requires WRTNFS privilege)

Table B-2 summarizes disk MODE values for non-file-structured access.
Table B-2:

MODE Values for Non-File-Structured Disk Access (FIRQB+FQMODE)

Decimal Octal

Function

Access device clusters.

128.

200

Access disk blocks.

512.

1000

Read beyond last writable portion of disk; suppress error logging.
(Reserved for use by Digital.)

Table B-3 lists the device cluster size and device size (in 512-byte blocks) for each
disk that RSTS/E supports. All values are decimal.
Table B-3:

Disk Device Sizes

Disk

Minimum Device
Cluster Size

Device Size

RX50

800

RK05

4800

RK05F

4800 per unit; 2 units for each drive

RL01

10,220

RL02

20,460

RD51

21,600

RK06

27,104

RK07

53,768

RD52

60,479

RC25

50,902 per unit; 2 units per spindle

RM02

131,648

RM03

131,648

RD53

138,668

RP04

171,796

(continued on next page)

8-2

Device Information

Table 8-3 (Cant.):

Disk Device Sizes

Disk

Minimum Device
Cluster Size

Device Size

RP05

171,796

RA80

237,208

RM80

242,575

RD54

311,200

RP06

340,664

RA60

400,175

RM05

500,352

RA70

547,040

RA81

888,012

RA82

1,216,640

RA90

2,376,128

8.2 Flexible Diskettes
This section summarizes MODE and RECORD values for RXOl and RX02 flexible
diskettes. Table B-4 lists MODE values for flexible diskettes.
Table 8-4:

Flexible Diskette MODE Values (FIRQ8+FQMODE)
Octal

Function

Block mode

16384.

40000

Sector mode

Decimal

Table B-5 lists RECORD values for flexible diskettes.
Table 8-5:

Flexible Diskette RECORD Values (XR8+XR8LK)

Decimal

Octal

Function

8192.

20000

Access logical record 0

16384.

40000

Write deleted data mark

32767.+1.

100000

Perlorm Uris I/O operation in block mode

Device Information

B-3

B.3 Magnetic Tape
This section summarizes MODE and CLUSTERSIZE values for magnetic tape.
Table B--6 lists MODE values for file-structured magnetic tape.
Table 8-6:

MODE Values for File-Structured Magnetic Tape (FIRQ8+FQMODE)
Function

Decimal

Octal

O.
2.

Read file label at current tape position

Do not rewind tape when searching for file

16.

Write over existing file

32.

Rewind tape before searching for file

64.

100

Rewind on CLOSE

128.

200

Open for append

512.

1000

Write new file label without searching

1024.

2000

Use block length field as specified in IFILESIZE in place of
record length field in /CLUSTERSIZE. Only meaningful on
ANSI tape, when the record length field is zero.

16384.

40000

Search for DOS-formatted file label

24576.

60000

Search for ANSI-formatted file label

Table B-7lists CLUSTERSIZE values for file-structured magnetic tape. The
value in FIRQB+FQCLUS is the sum ofthe values chosen from Table B-7. The
default value is zero.
NOTE

The CLUSTERSIZE option is only effective when processing ANSIformatted magnetic tape.
Table 8-7:

CLUSTERSIZE Values for File-Structured Magnetic Tape Files
(FIRQ8+FQCLUS)

Label Field
Name

Decimal

Octal

Label Result

Record format

U = undefined. t

16384.

40000

F = fixed-length.

32767.+1.

100000

D = variable length.

Record length (in
bytes)

-16384.

140000

S = spanned. :I:

Between O.
and 4095.

Between 0
and 7777

For U, always O.
For F, fixed record length.
For D, maximum record length.
For S, not used. :I:
If this value is 0% and mode 1024%
is used, then the record length field
is set equal to the block length
value specified in IFILESIZE=.

tRSTS/E undefined record formats cannot be processed directly by most of the other operating
systems.
*RSTS/E does not support ANSI format S records.

(continued on next page)
8-4

Device Information

Table B-7 (Cont.):
Label Field
Name
System
Dependent (File
characteristics)

CLUSTERSIZE Values for File-Structured Magnetic Tape
Files (FIRQB+FQCLUS)
Decimal

Octal

Label Result

4096.

10000

A = FORTRAN carriage control.

8192.

20000

(space) = implied carriage control.
When printed, line feed precedes
and carriage return follows each
record.

=carriage control embedded.

MODE values in non-file-structured magnetic tape processing have the form:
MODE(FIRQB+FQMODE) = D + P + S
where:
D (density)

12.(14) for 800 bpi
256.(400) for 1600 bpi, phase-encoded

P (parity)

0.(0) for odd
1.(1) for even (800 bpi only)

S (stay)

0.(0) to clear MODE value after CLOSE
8192.(20000) to retain MODE value after CLOSE

Note that Digital recommends the use of odd parity. When you use even parity,
you cannot write binary data. In addition, many operating systems and tape
drives do not support even parity.
For information on magnetic tape special functions, the magnetic tape status
word, and the file characteristics word, see the description of .SPEC for magnetic
tape (see Chapter 3).

(

Device Information

8-5

8.4 line Printers
This section summarizes line printer MODE and RECORD values. Table B-8
lists the MODE values for line printers.
Table 8-8:

line Printer MODE Values (FIRQ8+FQMODE)

Decimal

Octal

Function

1. to 127.

1 to 177

Sets form length to number of lines per page for software
formatting (512., 1000) and automatic page skip (2048., 4000).

128.

200

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

256.

400

Truncates lines that are longer than unit was configured for
instead of printing the rest of the line on the next physical line
on the page.

512.

1000

Enables software formatting. Forms control characters are ;::
200(8).

1024.

2000

Translates lowercase characters to uppercase characters. Applies
only to uppercase and lowercase line printers.

2048.

4000

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

4096.

10000

Moves paper to top of hardware form.

8192.

20000

Suppresses form feed on CLOSE.

Table B-9lists the RECORD values for line printers.

8-6

Table 8-9:

line Printer RECORD Values (XRB+XRMOD)

Decimal

Octal

Function

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

Do not return control to program until output is complete or an
error occurs.

Clear pending output buffers before buffering characters for the
request.

8192.

20000

Return control to program if output stall is to occur. (See the
.WRITE directive for more information.)

Device Information

B.5 Terminals
This section summarizes MODE and RECORD values for terminals. It also
includes information about echo control mode and VT100 ANSI-compatible escape
sequences.
Table B-IO lists MODE values for terminal input.
Table 8-10:

Terminal MODE Values (FIRQ8+FQMODE)

Decimal

Octal

Function

Enable binary input from a terminal

Reserved for TECO

Suppress automatic CRILF at right margin

Enable echo control (turns off other modes and automatically
enables MODE 4)

16.

Guard program against CtrllC interruption and dial-up line
hibernation

32.

Enable incoming XONIXOFF processing

64.

100

Reserved

128.

200

Enable use of RUBOUT as a delimiter on video terminals

256.

400

Set escape sequence mode

16384.

40000

Transparent control character mode

Table B-ll lists RECORD values for terminal input.
Table 8-11:

RECORD Values for Terminal Input (XR8+XRMOD)

Decimal

Octal

Function

256.

400

Force interactive read (always obtain data from the
user's terminal, never from a command file)

8192.

20000

Perform conditional input (execute input request
without waiting for data to be available).

32767.+1.+K

100000+K

Perform multiterminal service input from assigned
keyboard number K

32767.+1.+
16384.+S

140000+S

Perform multiterminal service input from any assigned keyboard:
S=0
Wait until input is available from
any terminal. The error ?Data
error on device may occur due to a
race condition with CtrllC.

1. < S < 255.
1 < S < 377

Wait up to S seconds for input
from any terminal and then return
?Data error on device if no input is
available.

S = 8192.
S = 20000

Request input immediately; return
?Data error on device if no input is
pending.

Device Information

B-7

Table B-12 lists RECORD values for terminal output.
Table B-12:

RECORD Values for Terminal Output (XRB+XRMOD)

Decimal

Octal

Function

256.

400

Declare echo control field (use with MODE 10).

4096.

10000

Output binary data to tenninal.

8192.

20000

Return control to program if output stall is to occur.
(See the .WRITE directive for more infonnation.)

16384.

40000

Transparent control character mode.

32767.+1.+K

100000+K

Perfonn multitenninal service output to assigned
keyboard K.

In echo control mode, the system strips the parity bit from all characters. All
characters returned to your program have ASCII values in the range 1 to 255.
The system does not pass synchronization or editing characters to your program.
Delimiters are passed to your program but are never echoed. Table B-13 lists the
echo control mode character set.
Table B-13:

Echo Control Mode Character Set
Code
Returned
to User

Type of
Character

ASCII Code
(Octal)

Ignored

Delimiters

Private

Private delimiter.

"C (CtrlJC).

"D (CtrlJD).

Line feed.

Fonn feed.

15,12

Carriage return (with line feed
appended).

"Z (CtrlJZ); generates error 11(10).

If the Escape_Sequence characteristic is not in effect and escape
character is received, 33 is returned to user and is treated
as a delimiter. If the Escape_
Sequence characteristic is in effect, escape character triggers an
escape sequence. The escape sequence is returned to user and the
whole sequence is considered the
delimiter.

175

33 or 175

If the Alt_Mode characteristic is in
effect, 175 is translated to escape
(33). If the Alt_Mode characteristic
is not in effect, 175 is data.

Comments

Used as filler for timing

(continued on next page)

8-8

Device Information

Table 8-13 (Cont.):
Type of
Character

Editing

Echo Control Mode Character Set

ASCII Code
(Octal)

Code
Returned
to User

176

33 or 176

177

Comments

If the Alt_Mode characteristic is in
effect, 176 is translated to escape
(33). If the Alt_Mode characteristic
is not in effect, 176 is data.

RUB OUT (DEL character); on video
terminals, generates a backspace
followed by the paint character
and another backspace; on hardcopy terminals, echoes deleted
characters between backslashes
(\ \).

"U (CtrllU); repeatedly simulates
RUB OUT until no characters
remain in field.

Data

Synchro- nization

Other

40-137
241-337

Normal 64-character graphic set.

140-176
340-376

100-136
300-336

If the Lowercase=input characteristic is not set, lowercase letters are
translated to uppercase.

140-176
340-376

If the Lowercase=input characteristic is set, lowercase letters are
returned to user.

XON (CtrllQ). Resume suspended
output (if the TTSync characteristic
is set).

XOFF (CtrllS). Suspend output (if
the TTSync characteristic is set).

1,2,5,6
7,10,11,
13,16-20,
22,24,
26-31,
34-37

Echoed as BEL (7) but otherwise
ignored.

21,23

If the terminal is set No TTSync,
synchronization characters are also
echoed as BEL (7) and ignored.

Device Information

8-9

Use .WRITE to declare a field. The .WRITE must include the value 400 at
XRB+XRMOD and the value N at XRB+XRBC. N, which must be between 1 and
the size of the buffer, describes how many bytes in the buffer represent the field
declaration:
N= 1

The byte contains field size and overflow handling information. The field size
must be in the range 1 to 177. Adding 200 to the field size specifies keypunch
overflow handling instead of normal overflow handling.

N= 2

The first byte contains field size and overflow handling as described for N = 1.
The second byte contains the ASCII value of the paint character. If this byte is
o or N = 1, a space is the paint character.
The first (N-2) bytes contain a prompt to display on the terminal before the
field. Byte (N-l) is the field size declaration as described for N = 1. The last
byte is the paint character as described for N = 2.

B.6 Pseudo Keyboards
This section summarizes MODE and RECORD values for pseudo keyboards. It
also lists errors your program can receive on a pseudo keyboard output request.
Table B-14 lists MODE values for pseudo keyboards.
Table B-14:

Pseudo Keyboard MODE Values (FIROB+FOMODE)

Decim.al

Octal

Function

System kills controlled job when the pseudo keyboard is closed

System detaches controlled job when the pseudo keyboard is
closed

Table B-15 lists RECORD values for pseudo keyboards.
Table 8-15:

8-10

RECORD Option Bit Values for Pseudo Keyboard Output
(XRB+XRMOD)

Bit

Decimal

Octal

Result

If set, the system does not check job status before sending
data to the pseudo keyboard.

If set, the system tests whether pseudo keyboard is
waiting for a system command (CtrllC state) or is waiting
for program input (KB wait state).

If set, the system does not send data to the pseudo
keyboard but instead returns control to the controlling
job.

If set, and there are no small buffers for keyboard
input, the system waits until small buffers are available.
However, your program receives the NOROOM error if
the output buffer chain is full.

16.

If set, the system kills the job currently running at the
pseudo keyboard.

Device Information

Table B-16 lists errors that your program can receive on a pseudo keyboard
output request.

Table 8-16:

Possible Errors on Pseudo Keyboard Output Request

Error

Meaning

INUSE

Job at pseudo keyboard is not ready for input

NOROOM No buffer space is available
NOSUCH No controlled job exists at pseudo keyboard
CTRLCE

Job at pseudo keyboard is not in CtrllC state

Device Information

8-11

Index
A

Abbreviation point (CCL) , 3--64
ABRT$, 5--4
Account
creating, 3-348
deleting, 3-307
reading data for, 3-358
resetting data for, 3-358
Accounting information dump, 3-251
Account number
1,3-83
#, 3-83
$, 3-83
%, 3-83
&, 3-83
@, 3-83, 3-238
file specification, 3-83
wildcard, 3-84
Active Page Register
See APR
Addressing, 2-1, 2-2
Allocating a device, 3-13
ALUN$, 5--5
AME (Application Migration Executive), RSX emulator,
4-1
ANALYS program, 3-351
ANSI magnetic tape
CLUSTERSIZE values, 8-4
Application Migration Executive
SeeAME
APR (Active Page Register), 2-1, 2-2, 2-5, 2-20,
2-21
kernel mode, 2-4,3-137
used to map windows, 3-144
user mode, 2-4
Argument block, RT-11 directives, 6-5
Assembler, 1-3
ASSFO, 3-13 to 3-15
Assign LAT port, 3-117
.AST, 3-10
AST (Asynchronous Trap), 2-16,5--54
ASTX$, 5--6
Asynchronous exception, 5--6, 5--54
handler, 2-23
Asynchronous Trap
SeeAST
ATRFO, 3-140 to 3-143
ATRG$, 5--8
Attach to job, 3-262
Attribute, 3-254,3-317

B.10, kernel mode vector, 2-22
B.250, kernel mode vector, 2-22
B.4, kernel mode vector, 2-22
B.PRTY, 2-25
B.STAK, 2-25
B.SWAP, 2-25
Back spacing magnetic tape, 3-209
BASIC-PLUS
run-time system, 1-1,2-5,2-21
SYS calls, 3-248 to 3-413
Binary file
creating, 3-18
opening, 3-18
Binary mode, 3-219
.BLKBO, 3-5
.BLKWO, 3-5
BLOCK option, 3-167,3-172,3-416,3-421
Block-random devices, 3-165
Block-sequential devices, 3-165
BPT instruction, 2-16
Broadcast to terminal, 3-216
.BSECT,3-5
Buffering, disabling full line, 3-230
Buffer size
reads, 3-165,3-166
writes, 3-419
Byte-oriented devices, 3-165

c
Caching
disabling disk, 3-282
enabling disk, 3-282
CALFIP, 3-12 to 3--63
summary of subfunctions, 3-12
CALL, 3-5
Call formats, RT-11 directives, 6-5
CALLR, 3-6
CALLRX, 3--6
CALLX, 3--6
Card reader
reads, 3-165
Carry bit, 7-58
CCL command, 3--64
adding, 3-269
deleting, 3-269
IDETACH switch, 3-65
getting command line, 5--33
RT-11 .DOCCL, 7-23
ISIZE switch, 3--65

Index-1

CCL command (Cont.)
string passed in CORCMN, 2-15
.CCL directive, 2-15,3-64 to 3-67
/DETACH switch, 2-28
/SIZE switch, 2-28
CCLLST, 3-397
.CHAIN, 3-68
RT-11 , 7-6 to 7-7
Channel
checking for open, 7-63
closing, 3-16, 7-38
closing under RT-11 , 7-8,7-57
releasing, 7-42
reset, 3-61
Channel number, 3-7
under RT-11 , 6-7
Circuit counters, 3-195, 3-197
.CLEAR, 3-69 to 3-70
.CLEAR directive, 2-10
.CLOSE, 7-8
CLOSE, negative channel number (reset), 3-61
Close flag, 3-300
Closing a channel, 3-16
.CLRFOB, 7-9
CLRFOB routine, 3-7
CLRFOX routine, 3-7
.CLRXRB, 7-10
CLRXRB routine, 3-7
CLSFO, 3-16 to 3-17
CLUSTERSIZE option, 3-25, 3-32, 3-55
ANSI magnetic tape, B-4
/CLUSTERSIZE switch, 3-81,7-11
CLUSTR offset, 6-12
.CMDLN, 3-71 to 3-72
Command, CCL, 3-64
COMMON.MAC, 2-9, 3-2 to 3-6, 3-248, 6-3
how to assemble with, 3-3
macros provided with, 3-3
mnemonics assigned to FIROB, 2-12
mnemonics for pseudovectors, 2-16
Concise Command Language
See CCL
Context, job, 2-11
Control characters, vertical format, 5-49t
Conversion, date and time, 3-295
CORCMN
definition, 2-14
format, 2-15f
low 512 bytes, 2-9f
.CORE, 3-76
Core common, definition, 2-14
.CORE directive, 2-11,2-21
CRAFO, 3-144 to 3-148
CRASH.SYS, DUMP/SYSTEM command, 3-351
CRAW$, 5-11
CRBFO, 3-18 to 3-22
Create
binary file, 3-18
file, 3-23
logged-in job to enter keyboard monitor, 3-323
logged-in job to run program, 3-321
logged-out job, 3-320
temporary file, 3-30
Create LAT port, 3-113
CREFO, 3-23 to 3-29
CRMSBS offset, 6-12
CRRG$, 5-16

Index-2

CRTFO, 3-30 to 3-33
.CSIGEN, 7-11 to 7-14
.CSISPC, 7-15 to 7-17
CSRTBL, 3-397
Ctrl/C, 2-16,2-24
asynchronous exception, 5-54
processing, 7-51
restarting output stopped by, 3-233
stopping action of, 6-12
Ctrl/O
canceling, 3-216
effect, 2-24
restarting output stopped by, 3-233
reversing, 7-43
Ctrl/Z, 7-49

D
DALFO, 3-34
Data caching
See Caching
Dataset, hanging up, 3-319
Data Space (D-Space), 2-5
Date
changing system, 3-298
conversion, 3-295
current, 5-36
returning under RT-11, 7-20
return to RO, 7-18
.DATE, 3-77 to 3-78
RT-11 , 7-18 to 7-19
.DATTIM, 7-20, 7-21
DCL (Digital Command Language)
run-time system, 1-1
DCL run-time system, 2-26
DDB (Device Data Block), 3-311
DDCTBL, 3-399
DDNFS, 3-27, 3-56, 3-95
DDRLO, 3-27, 3-56, 3-95
DDWLO, 3-27, 3-56, 3-95
DEAFO, 3-35 to 3-36
Deallocate
all devices, 3-34
device, 3-35
Deassign LAT port, 3-120
Declare receiver, 3-100
DECnetlE, 3-100
DECtape
deleting file from, 3-42
get directory for, 3-37
reads, 3-165,3-166
rename file, 3-59
writing data, 3-419
Default keyboard monitor, 2-25,3-80,3-178, 7-31
See also Primary run-time system
Default runnable file type, 2-20
Default system keyboard monitor, 3-179
DEFORG,3-3
.DELETE, 7-22
Delete LAT port, 3-115
Deleting
account, 3-307
file, 3-42
Delimiters
line, 3-165
multiple private, 3-218 to 3-224

Delimiters (Cont.)
private, 3-218
Density, setting magnetic tape, 3-209
Detach
resident library, 3-149
Detached job quota, 3-268
Detaching job, 3-300
IDETACH switch, in CCL command, 3-65
DEVCLU, 3--399
DEVCNT, 3--395
Device
allocating, 3-13,3-234,3-252
block-random, 3-166,3-419
block-sequential, 3-165, 3-419
byte-oriented, 3-165,3-419
checking availability, 7--32
deallocating, 3--35, 3-234, 3-245, 3-299
deallocating all, 3--34, 3-243, 3-297
disk sizes, B-2
handler index, 3-96
logical name, 3-82, 3-92
open (non-file-structured), 3-53
physical name, 3-82
reading, 3-165
reallocating, 3-234,3-252
record-oriented, 5-48
return status, 7-26
seize operation, 3-237
writing data to, 3-414, 3-419
zeroing, 3-411
Device block, 6-7, 6-8
creating, 7-15
Device Data Block
See DDB

Device handler index, 3-28, 3-57
Device-type flags, 3-27,3-56,3-95
DEVNAM, 3--397
DEVOKB, 3--397
DEVPTR, 3--395
DEVSYN, 3--397
DIC (Directive Identification Code), 4-3
byte, DPB, 4-5
DIGITAL Command Language
See DCL

DIR$, 4-4
general form, 4-5
other features, 4-6
Directive
expansions for RSX, 4-2
expansions for RT-11 , 6-4
monitor, 1-4
RSX, 1-4
RT-11 , 1-4
Directive Identification Code
See DIC

Directive Parameter Block
See DPB

Directives
emulator, 1-4
Directive Status Word
See DSW

Directory
get information, 3--37
lookup, 3-38
lookup by file name, 3--334
lookup on index, 3-303

Directory (Con!.)
magnetic tape lookup, 3-305, 3--306
privileged and non privileged access, 3-37
wildcard lookup, 3-336
DIRFO, 3--37 to 3-41
Disable terminal, 3-290
Disk
changing logical name of, 3-375
changing quota, 3-290
deleting file from, 3-42
device cluster sizes, B-2
device sizes, B-2
directory lookup by file name, 3-334
dirty bit, 3--341
disabling caching, 3-282
enabling caching, 3-282
file lookup by name, 3-46
get directory for, 3--37
locking blocks, 3-190
MODE values, B-1
mounting, 3--338
reads, 3-166
rename file, 3-59
swapping to, 3-69,3-186
wildcard directory lookup, 3-336
writing data, 3-419
Disk quota, 3-268
DLNFO, 3-42 to 3-43
DMC11/DMR11
number of receive buffers, 3-54, 3-55
reads, 3-165
receive buffer size, 3-54
writing data, 3-419
.DOCCL, 7-23
.DOFSS, 7-24
.DORUN, 7-25
$DPB$$, 4-7
DPB (Directive Parameter Block), 4--3
$C form, 4-6
DIC byte, 4-5
$ form, 4-4
general form, 4--3
$S form, 4-7
.DSECT, 3-4
DSKLOG, 3--397
.DSTATUS, 7-26, 7-27
DSTPTR, 3--399
DSW (Directive Status Word)
return codes, 4--3
$DSW mnemonic
DSW (Directive Status Word), 4-3
DTRFO, 3-149 to 3-150
DTRG$, 5-18
Dump, snap shot, 3-308, 3-351
DUMP/SYSTEM command, CRASH.SYS, 3--351
Dynamic region, creating, 3-362,3--370, 5-16
Dynamic region, 1/0, 3-165,3-170
Dynamic region, limit, 3-277

E
Echo
disabling, 3-214,3-216
enabling, 3-214,3-216
stopping, 3-232
Echo control mode
character set, B-St

Index-3

Echo control mode (Cont.)
declaring a field, B-1 0
ELAFO, 3-151 to 3-153
ELAW$, 5-20
EMT, 2-41
instruction, 2-18, 2-23, 6-4
special prefix, 1-4, 2-19, 2-23, 6-3
EMT 377, 4-3
EMT logging, 3-101,3-109
Emulator, 1-2
directives, 1-4
RSX directives, 5-1
RT-11 directives, 7-1 to 7-66
trap, 2-18
End-of-file (EOF), magnetic tape, 3-209
.ENTER, 7-28
Entry points, 2-25
.EOUATE, 3-5
ERLCTL, 3-397
.ERLOG, 3-79
ERR.STB
symbol table file, 3-6
ERRFO, 3-44 to 3-45
Error log, 2-20
Error message
printing text, 7-30
returning text, 3-44,3-309
RSTS/E set, A-1 to A-8
Error mnemonics, 3-6, A-1 to A-8
Errors
logging, 3-79
pseudo keyboard output request, B-11
.ERRPRT, 7-30
Escape sequences, 3-218
mode, 3-219
Ethernet, 3-193
circuit counters, 3-195,3-197
line counters, 3-196,3-199
multicast addresses, 3-194
physical address, 3-193
Exception
asynchronous, 2-23
synchronous, 2-21, 5-58, 5-60
.EXIT, 3-80
RT-11 , 7-31
EXIT$, 5-22
Expand
memory allocation, 3-73
memory size, 2-11
Expiration date, changing, 3-290
EXOTA privilege, 2-11
EXST$, 5-23
Extended Buffer Pool
SeeXBUF
Extended logical area of job header, 2-15, 3-85,
3-235
.FSS causes check of, 3-82
Extended-memory calls (RT-11), 6-1
Extended Record Block
See XRB
Extend memory allocation, 3-73
Extend task by mask, 5-26
EXTK$, 3-75, 5-24
EXTM$ Directive, 5-26

Index-4

F
Fast-mapping, 3-70, 3-186
Fast-mapping facility, 3-159 to 3-160, 5-42 to 5-43
FCB (File Control Block), 3-311
FCBLST, 3-397
FEA (Floating-point Error Address), 2-23, 5-6, 7-54
FEADF$, 5-29
FEAT$, 5-30
FEC (Floating-point Exception Code), 2-23, 5-6, 7-54
.FETCH, 7-32
File
adding system, 3-383
associating with run-time system, 3-342
changing statistics, 3-266
creating, 3-23
creating binary, 3-18
creating temporary, 3-30
deleting, 3-42
deleting from DECtape, 7-22
deleting from disk, 7-22
listing system, 3-383, 3-386
lookup by name (disk), 3-46
open existing, 3-53, 7-39
open for input, 3-53, 7-39
open for output, 7-28
opening binary, 3-18
opening file-structured, 3-23
opening temporary, 3-30
placement and modification, 3-315
processor, 3-248
read attributes, 3-254
reading, 3-165
read under RT-11 , 7-44
removing system, 3-383, 3-384
renaming, 3-59, 7-46
reopen, 7-47
returning attribute, 3-317
saving status of, 7-48
specification, 3-82, 7-24
spooling, 3-379
tentative, 3-61
wildcard lookup, 3-46
write attributes, 3-254
writing data to, 3-414, 3-419
File access
checking, 3-284
File characteristics word, magnetic tape, 3-212
File Control Block
See FeB
File name
file specification, 3-84
string scan, 2-15
File name string scan, 3-8, 3-81
under RT-11 , 7-24
File Processor
See FIP
File request queue block, 2-12
FILESIZE option, 3-24
IFILESIZE switch, 3-81, 7-11
File specification, 3-81
order of elements, 3-84
File-structured, open, 3-23
File type
default runnable, 2-20
file specification, 3-84
FIP (File Processor), 3-63, 3-248

FIP (File Processor) (Cont.)
calls, 3-63
FIRQB
clearing under RT-11 , 7-9
data returned to, 3-7
definition, 2-12
general format, 2-13f
low 512 bytes, 2-9f
mnemonics assigned to, 2-12
P.RUN entry, 2-28
presetting to zero, 3-6
routine to clear, 3-7
setting up under RT-11 , 7-52
size of, 2-12
translating string to, 3-81
Fixed monitor locations, 3-137t
Flag
close, 3-300
device-type, 3-27, 3-56, 3-95
Flag word 1 (.FSS), 3-88
Flag word 2 (.FSS), 3-86
Flexible diskette
changing density, 3-204
MODE values, B-3
obtaining density, 3-204
reads, 3-166
RECORD option, B-3
special functions for, 3-204
writing data, 3-419
FLGFRC, 3-27, 3-56, 3-95
FLGKB, 3-27,3-56,3-95
FLGMOD, 3-27,3-56,3-95
FLGPOS, 3-27, 3-56, 3-95
FLGRND, 3-27, 3-56, 3-95
Floating-point
errors, 7-54
processor, 2-16
processor exception address, 5-55
processor exceptions, 5-6
unit, 2-11,2-23,3-186,7-54
Floating-point Error Address
See FEA
Floating-point Exception Code

SeeFEC
Force to keyboard, 3-216
Foreground/background, 6-1
FORTRAN, resident library access directives, 4-8
FREES, 3-397
.FSS, 3-81 to 3-91
110 support, 3-8
.FSS directive, 2-15

G
General monitor directives, 3-1 to 3-9
not used under RT-11 , 3-1
summary, 3-1
General Register RO, 6-4
.GETCOR, 7-33
Get monitor tables
Part I, 3-394
Part II, 3-396
Part III, 3-398
GLOBAL,3-5
Global symbols, 3-6
GLUN$, 5-31

GMCR$, 5-33
GPRT$, 5-34
.GTIM, 7-34
GTIM$, 5-36
.GTJB, 7-35
.GTLlN, 7-36
GTSK$, 3-75, 5-38
.GVAL directive, 7-37

H
Handler index, device, 3-28, 3-57, 3-96, 7-26
Hanging up a dataset, 3-319
High segment, 2-5, 2-8f, 2-16 to 2-30
Horizontal position, 3-163
.HRESET, 7-38

I&D Space (Instruction and Data Space), 1--4, 2-5,
5-24
memory management, 2-2

110
general directives for, 3-8
non-file-structured, 5-47
page, 2--4f
RSX emulation environment, 5-47
special functions for, 3-189
special functions under RT-11 , 7-55
synchronous, 5--47
I/O Status Buffer (ISB), 5-49
.IDENT, 3-3
INCLUDE, 3-4
Infinite-wait read, 2-26, 3-168
INIT, 2-5
INSTALURUNTIME_SYSTEM command, 2-18
Instruction and Data Space
See I&D Space
Instruction Space (I-Space), 2-5

J
JBSTAT, 3-395
JBWAIT, 3-395
JDFSTM, 3-69,3-70,3-186
JFBIG,3-69,3-186
bit in KEY, 2-11
JFFPP, 3-69,3-70,3-186
bit in KEY, 2-11
JFLOCK, 3-69
bit in KEY, 2-11
JFNOPR, 3-69,3-186
bit in KEY, 2-11
JFPRIV, 3-69,3-70,3-186
bit in KEY, 2-11
JFSPRI, 3-69,3-70,3-186
bit in KEY, 2-11
JFSYS, 3-69,3-186
bit in KEY, 2-11
JMPX, 3-5
Job
aborting, 5-4
attaching to, 3-262
context information, 2-11, 3-186
creating logged-in, 3-321, 3-323
creating logged-out, 3-320

Index-5

Job (Cont.)
definition, 2--8f
detaching, 3-300
general discussion, 1-5
getting high limit, 7-35
indication of login, 2-11
killing, 3-268, 3-290
new on system, 2-26
parameters, 5-34, 5-38
preallocate memory for, 2-19
private maximum size, 5-24
reattaching to, 3-263
returning statistics on, 3-225
returning status information on, 3-389
suspending with .SLEEP, 3-187
suspending with .TWAIT, 7-62
suspending with SPND$S, 5-56
suspending with UU.STL, 3-382
swap console with, 3-264
swapping to disk, 2-11,3-69,3-186
timing information on, 3-227
Job area, 1-2, 2--8f
JOBCNT, 3-397
Job context information, 2-11, 2-26, 3-178
Job header
extended logical area, 2-15, 3--85, 3-235
Job image
changing size, 3-73, 7-33
maximum size, 2-21
minimum size, 2-21
Job keyboard monitor, 2-25, 3--80, 3-178, 3-179,
5-22, 7-31
JOB MAX, 3-332
Job space, 2-5
JOBTBL, 3-395
JSBTBL, 3-395
JSR PC, substitute for, 3-5

K
Kernel mode
Active Page Register (APR), 2-4,3-137
Kernel mode vector
B.10, 2-22
B.250, 2-22
B.4, 2-22
Kernel mode vector 244, 2-23
Kernel mode vector 34, 2-23
KEY, 2-25,2-26
clearing bits in, 3-69
definition, 2-10
low 512 bytes, 2-9f
setting bits in JFLOCK, 3-185
Keyboard
disabling echo, 3-214
enabling echo, 3-214
forcing output, 3-216
getting line from, 7-36
ODT-mode input, 3-230
reads, 3-165
setting private delimiters for, 3-218
special functions, 3-216
writing data, 3-419
Keyboard monitor, 1-1,2-5,2-16,2-25,3-233
default, 1-5,2-25,5-22,7-31
entry, 2-25
job, 2-25,3-80,3-178,5-22,7-31

Index-6

Keyboard monitor (Cont.)
prompts, 2-26
system default, 3--80
Keyboard monitor wait, 2-26,3-168
Keyword
clearing bits in, 3-69
setting bits, 3-185
when refreshed, 2-10
Killing a job, 3-268, 3-290

L
LAT, assign port, 3-117
LAT, create port, 3-113
LAT, deassign port, 3-120
LAT, delete port, 3-115
LAT, return port characteristics, 3-125
LAT, return port status, 3-122
LAT, show sessions, 3-131
LB:, 3-235
LBR, 1-3
LlBR, 1-3
Librarians, 1-3
Library
cluster, 1-3
macro, 1-3
object, 1-3
resident, 1-3
save image, 1-4
universal, 1-3
Line
getting from terminal, 7-36
width, 3-163
Line counters, 3-196,3-199
Line delimiters, 3-165
Line printer
MODE values, 8-6
"no stall" option, 3-421
RECORD values, 8-6
writing data, 3-419
LINK, 1-3, 1-4, 3-6
Linker, 1-3
RT-11 , 2-9
List
logical names, 3-376
Loader, 1-2
Local data message
receive, 3-108
send, 3-104
Locking disk blocks, 3-190
Log, error, 2-20, 3-79
Logged-in job
create, 3-321, 3-323
entry to keyboard monitor, 2-26
Logged-out job
create, 3-320
entry to keyboard monitor, 2-26
Logical names, 3--82, 3-92
adding system-wide, 3-374
assigning, 3-235
deassigning, 3-245
deassigning all, 3-243
removing system-wide, 3-375
Logical unit number
assigning, 5-5
getting information on, 5-31
LOGIN, 1-5

Login, indication of, 2-11
Logins, 3~27
disabling further, 3-343
enabling, 3-409
set number allowed, 3~32
Logout, 3-267
shutup, ~02
LOGOUT utility, 3-30
.LOGS, 3-92 to 3-99
LOGT8L offset, 6--12
LOKFO, 3-46 to 3-52
disk directory lookup, 3-47
disk wildcard directory lookup, 3-50
1/0 support, 3--8
Lookup
directory, 3-38, 3~03
special magnetic tape, ~9
.LOOKUP, 7~9
Low segment, 2-5, 2-8f
first 512 bytes, 2-9,2-9f
first 512 bytes for RSX, 4-9,4-9t
first 512 bytes for RT-11 , 6--9

M
MAC assembler, 1~, 4-1
using general directives with, 3-1
MACRO assembler, 1~, 6--1
using general directives with, 3-1
Macro library, 1~
MAGL8L, 3~99
Magnetic tape
back spacing, 3-209
CLUSTERSIZE values, B-4
file characteristics word, 3-212
get directory for, 3-37
MODE values, B-4, B-5
reads, 3-165
setting density, 3-209, 8-5
setting parity, 3-209, 8-5
skipping record, 3-209
special directory lookup, 3-39, ~05, ~06
special functions for, 3-209
status word, 3-211
writing data, 3-419
writing end-of-file, 3-209
MAKSIL, 1-4
MAP$, 5-40
MAPFO, 3-154 to 3-159
Mapping, 2-2
address windows, 5-40
physical memory, 3-157
RDMEM privilege, 3-157
resident library, 3-144, 3-154
SYSMOD privilege, 3-157
Masks
private delimiter, 3-22ot
MAXCNT, ~95
.MCALL,4-2
MEMLST, ~95
Memory
changing allocation, 3-73
changing size, 3~55
expansion, 2-11
increasing allocation, 5-24
mapping, 2-2, 2-4f
page, 2-1, 2-2

Memory (Cont.)
poking, ~52
Memory management, 2-1
1&0 Space, 2-2
MEMSIZ, 3~97
.MESAG, 3-100 to 3-134
.MESAG subfunction, send privileges, 3-110
Message
EMT logger, 3-109
receive local data, 3-108
send/receive, 3-100
send local data, 3-104
MFDPTR, 3~99
Mnemonics, 3-6
Mode
ODT (one-character) input, 3-230
tape, 3-229
MODE modifier, OPEN FOR INPUT, 3-54
MODE offset, 6--12
MODE option, 3-24, ~1
disk, B-1
flexible diskette, ~
line printer, B-6
magnetic tape, 8-4, B-5
pseudo keyboard, B-1 0
terminal, B-7
IMODE switch, 3-81,7-11
Monitor
fixed locations for .PEEK, 3-137t
general RSTS/E directives, 1-4,3-1 to 3-9
RSX emUlation, 4-2
tables, 3~94, 3~96, 3-398
Multicast addressing, 3-194
Multiple private delimiters, 3-217 to 3-224
Multiterminal service, 3-421

N
.NAME, 3-77,3-135 to 3-136
Name program, 3-135
NOCTLC offset, 6--12
Non-file-structured 1/0
RSTS/E monitor, 4-2
NRRTS, 2-25
NULRTS, 3~99

o
Object library, 1-3
Octal Debugging Tool
See ODT
ODT (Octal Debugging Tool), 2-18,2-20,3-230,
5-58
ODT mode, 3-216,3-230
ODT-mode input, 7-59
Offline, taking magnetic tape, 3-209
ONLCLN, ~41
Open
binary file, 3-18
existing file, 3-53
file, 3-23
file or device, 3-53
file-structured, 3-53
LAT keyboard, 3-53
non-file-structured, 3-53
OPEN FOR INPUT, 3-53
MODE modifier, 3-54

Index-7

OPEN FOR OUTPUT, 3-23, 3-24, 3-31
Open next disk file, 3-344
OPNFQ, 3-53 to 3-58
OPSER-based
spooling package, 3-379
ORG, 3-3
requirement for, 3-4

p
P.2CC, 2-16f
definition, 2-24
P.BAD, 2-16f
definition for asynchronous exceptions, 2-24
definition for synchronous exceptions, 2-21
P.BPT, 2-16f
definition, 2-22
P.CC, 2-16f
definition, 2-24
P.CRAS, 2-16f
P.DEXT, 2-16f, 3-362
definition, 2-20
P.EMT, 2-16f
definition, 2-23
P.FIS
definition, 2-21
P.FlAG, 2-16f, 2-19, 2-23, 6-4
combinations, 2-20
definition, 2-18
P.FPP, 2-16f
definition, 2-23
P.IOT, 2-16f
definition, 2-22
P.MSIZ, 2-16f, 2-21, 3-73, 3--362
P.NEW, 2-16f, 3-179, 3-181, &-22
definition, 2-25
P.OFF, 2-16f
definition, 2-18
P.RUN, 2-16f
.CCl passes control to, 3--64
channel 17 open, 3-7
definition, 2-27
entry at, 2-10
passing control, 3-182
P.SIZE, 2-16f, 2-21, 3-73, 3--362
P.STRT, 2-16f
P.TRAP, 2-16f
definition, 2-23
Page, 2-1, 2-2
Page Address Register
See PAR
Page Descriptor Register
See PDR
Paper tape punch, 3-419
Paper tape reader
reads, 3-165
PAR (Page Address Register), 2-1, 2-2
Parameter word, 3-320, 3--321
Parity, setting magnetic tape, 3-209
Password, changing, 3-290
Password, set long, 3-290
PAT (Patch Utility), 1--3
object module, 1--3
Patch Utility
See PAT

Index-8

PBS (Print/Batch Services)
spooling package, 3--379
PC (Program Counter), 2-5
PDR (Page Descriptor Register), 2-1, 2-20
.PEEK, 3-137 to 3-138
fixed monitor locations, 3-137
PF.1US
bit within P.FlAG, 2-18f
definition, 2-20
PF.CSZ
bit within P.FlAG, 2-18f
definition, 2-19
PF.EMT, 2-23, 6-4
bit within P.FlAG, 2-18f
definition, 2-18
PF.KBM
bit within P. FLAG , 2-18f
definition, 2-20
PF.NER, 2-20
bit within P.FLAG, 2-18f
PF.REM, 2-20
bit within P.FLAG, 2-18f
PF.RW, 2-20
bit within P.FLAG, 2-18f
Physical addressing, 2-1,2-2,3-193
Physical device name, 3-92
Physical memory
mapping, 3-157
.PlAS, 3-139 to 3-162
subfunction summary, 3-139
.PlAS directive, 1--3
.PlAS subfunctions, 3-139t
Poking memory, 3-352
{POSITION switch, 3-81,7-11
POSITN offset, 6-12
.POSTN, 3-163 to 3-164
PPN (Project-Programmer Number)
assignable, 3-83
entering user logical for, 3-235
file specification, 3-83
offset, 6-12
wildcard lookup, 3-353
Preallocate memory, 2-19
Prefix EMT, 1-4,2-18,2-23
.PRINT, 7-41
Print/Batch Services
See PBS
Priority, 2-11
changing, 3-355
run, 3-186
Private delimiters
and binary mode, 3-218
characteristics, 3-218
definition, 3-218
keypad applications, 3-218
masks, 3-22Ot
system processing, 3-218
Private memory maximum, 2-11
Privilege
permanent, 2-11, 3-70
temporary, 2-11,3--69,3-186
Privilege checking
third-party, 3-413
Privilege mask
checking, 3-284
Privilege name
checking, 3-284

Privileges
clear current, 3-356
read current, 3~56
set current, 3-356
Program
maximum size under RSX, 5-24
maximum size under RT-11 , 6-10
running, 3-182
suspending, 3-187,5-56,7-62
Program Counter
See PC
Program name, 3-135
returned by .DATE, 3-77
Program Status Word
See PSW
Project-Programmer Number
SeePPN
Prompts
keyboard monitor, 2-26
PROTEC offset, 6-12
Protection code
default, 2-15
file specification, 3-84
IPROTECTION switch, 3-81,7-11
.PSECT, requirement for, 3-4
Pseudo keyboard
errors on output request, B-11
MODE values, 8-10
reads, 3-165
RECORD values, 8-10
special functions for, 3-214
state change, 3-187
writing data, 3-419
Pseudovectors, 2-8,2-16 to 2~0
format with high segment, 2-16
PSW (Program Status Word), 2-5, 6-4
.PURGE, 7-42

Q
010$, 5-47
010W$,5-47
~uota

changing, 3-290
detached job, 3-268
disk, 3-268

R
.RCTRLO, 7-43
RDBBK$, 5-52
RDBDF$, 5-52
RDMEM privilege
mapping, 3-157
Read
device, 3-165
file, 3-165
ODT-mode, 3-230, 7-59
.READ, 3-165 to 3-169
RT-11 , 7-44
Read/write run-time system, 2-20
.READC, 7-44
Read-only run-time system, 2-20
.READW, 7-44
Reattach to job, 3-263
Receive, 3-107

Receive (Cont.)
local data message, 3-108
Receiver ID Block
See RIB
Record Management Services
SeeRMS
RECORD option, 3-167,3-172,3-416,3-421
flexible diskette, ~
line printer, B-6
pseudo keyboard, 8-10
terminal, 8-7
RECORDSIZE option, 3-54
Remove receiver, 3-1 03
.RENAME, 7-46
Rename file, 3-59, 7-46
RENFO, 3-59 to 3-60
.REOPEN, 7-47
REORDR, 3-29, 3~3, 3-58
Reset channel, 3-61
Resident libraries, 1/0, 3-419
Resident library, 1-3
accessing, 3-139
adding, 3~62, 3~66
attaching to, 3-140,5-8
creating window, 3-144
creating window to, 5-11
detaching from, 3-149, 5-18
eliminating window to, 3-151
mapping windows to, 5-40
maximum number, 5-8
maximum number of, 3-140
removing, 3~68
special RSX directives, 5-52
unloading, 3-369
un mapping window from, 5-63
Resident library, VO, 3-414
Return LAT port characteristics, 3-125
Return LAT port status, 3-122
RETURN macro, 3-5
Rewind tape, 3-209
RIB (Receiver ID Block), 3-101,3-102,3-107,3-109
RMS (Record Management Services), 4-2
IRONLY switch, 7-11
RSTFO, 3-61 to 3-62
RSX
emulation in the monitor, 3-144,4-2
environment, 4-1 to 4-10
run-time system, 1-1, 1-2, 2-21, 4-2
RSX directives, 1-4
$C form, 4-6, 4-7
expansions, 4-2 to 4-8
$ form, 4-5,4-6
$S form, 4-7
summary, 5-11
summary of, 5-1
RSXMAC.SML, 4-2, 4-4
RT-11
environment, 6-1 to 6-13
low 512. bytes for, 6-9
run-time system, 1-1,2-21
scratch pad area, 6-1 0
use of special prefix EMT, 2-19
RT-11 directives, 1-4
call formats, 6-5
expansions, 6-4
not processed on RSTS/E, 7-1
summary of, 7-1

Index-9

RT-11 run-time system
illegal general monitor calls, 3-1
.RTS, 3-178 to 3-181, 3-326
RTSlST, 3-397
.RUN, 3-182 to 3-184,3-326
hard errors, 3-183
soft errors, 3-183
Run-burst, changing, 3-355
.RUN directive, 2-20
Running a program, 3-182
Run priority, 2-11,3-186
Run-time system, 2-8f
adding, 3-362
associating file with, 3-342
capability defined, 2-18
choosing, 1-2, 1-3
default definitions, 2-18
exit processing, 3-178
general discussion, 1-1 to 1-5
modifying, 2-12
name returned, 3-77
passing control to, 3-178
removing, 3-364
space taken by, 2-5
top address, 1-4
unloading, 3-364
when removed, 2-20
writing or modifying, 1-4

5
SATCTl, 3-395
SATCTM, 3-395
SATEND, 3-399
Save Image Library
See SIL
.SAVESTATUS, 7-48
.SCCA, 7-49
SCCA$S, 5-54
Scratch pad, 6-10, 7-53
getting value from, 7-37
Seize operation, 3-237
Send local data message, 3-104
Send privileges, .MESAG subfunction, 3-110
.SET, 3-185
.SETCC, 7-51
Set device characteristics, 3-271
.SET directive, 2-10
.SETFQB, 7-52
SET JOB/KEYBOARD_MONITOR command, 3-178,
7-31
Set system default characteristics, 3-271
Set terminal characteristics, 3-400
.SETTOP, 7-53
.SFPA, 7-54
SFPA$, 5-55
SHOW DISK command, 3-341
Show LAT sessions, 3-131
SHOW RUNTIME_SYSTEM command, 2-21
Shut down system, 3-302
Shutup logout, 3-302
Significant event flag, 5-66
Sil (Save Image Library), 1-4
SllUS, 1-4
Single event flag, 5-67
Single-job monitor, 6-1

Index-10

/SIZE switch, 3-81, 7-11
CCl command, 3-65
.SlEEP, 3-187 to 3-188
conditional, 3-187,3-188
Small buffers, 2-5
Snap shot dump, 3-308,3-351
SNDlST, 3-397
SP (Stack Pointer), 2-11,2-22,2-23,2-24,2-26
.SPEC, 3-189 to 3-215
circuit counters, 3-195,3-197
disk, 3-190
flexible diskette, 3-204
line counters, 3-196,3-199
magnetic tape, 3-209
multicast addresses, 3-194
physical address, 3-193
pseudo keyboard, 3-214
terminal, 3-216
Special prefix EMT, 1-4,2-19,2-23,6-3
.SPFUN, 7-55
SPND$S, 5-56
Spooling, 3-379
Spooling package
OPSER-based, 3-379
PBS (Print/Batch Services), 3-379
.SRESET, 7-57
SST (Synchronous System Traps), 2-16
SSTX$, 5-57
Stack overflow, 2-11,2-24
Stack Pointer
SeeSP
Stack Pointer Register
SeeSP
Stall system, 3-382
.STAT, 3-225 to 3-226
Statistics
changing file, 3-266
returning for job, 3-225
Status, exit with, 5-23
Status byte, 3-313
STATUS variable, 2-28,3-27,3-33,3-89
Status word, magnetic tape, 3-211
String
display at terminal, 7-41
scan for file name, 7-24
Suspend
job (with .SlEEP), 3-187
job (with .TWAIT), 7-62
job (with SPND$S), 5-56
jobs on system (with UU.STL), 3-382
SVDB$, 5-58
SVTK$, 5-60
Swap console function, 3-264
Swap file, 3-384,3-386
SWAP MAX, 3-355, 5-24
Swapping, 2-11,3-69,3-186
Symbol table file
ERR.STB, 3-6
Synchronous exception, 2-21, 5-58, 5-60
Synchronous System Traps
See SST
$SYSMAC.SMl
system macro library, 6-3
SYSMOD privilege
mapping, 3-157
SYSTAT, 3-135

System default run-time system.
See Default keyboard monitor
System error log, 2-20
System feature
test, 5-30
System feature labels, 5-29
System macro library, 4-2
$SYSMAC.SML, 6-3
System-wide logical names
adding, 3-374
removing, 3-375

T
Tape
See Magnetic Tape or DECtape
Tape mode, 3-216, 3-229
Task
exit, 5-22
Task Builder
See TKB
Temporary file, 3-30
Temporary privilege, 3-186
Tentative file, 3-61
Terminal
disabling, 3-290
disabling echo, 3-214
enabling echo, 3-214
escape sequences mode, 3-219
forcing output, 3-216
getting line from, 7-36
MODE values, B-7
"no stall" option, 3-421
ODT-mode input, 3-230
reading low-speed tape on, 3-229
reads, 3-165
RECORD values, B-7
setting characteristics, 3-400
setting private delimiters for, 3-218
special functions, 3-216
TTSYNC characteristic, 3-219
writing data, 3-419
TFEA$, 5-62
Time
changing system, 3-298
conversion, 3-295
current, 5-36
returning under RT-11 , 7-20, 7-34
slice, 2-4
.TIME, 3-227 to 3-228
Timing, returning for job, 3-227
TITLE, 3-3
TKB (Task Builder), 1-3,1-4,3-6,4-1,4-3,4-9
TKB.TSK, 5-26
TMPORG, 3-4
Transfer request block, 2-12
Transportable code
RSX-11M-PLUS, 4-1
RT-11 , 6-1
VAX/VMS under AME, 4-1
Trap, 2-16
asynchronous CtrVC, 3-8 to 3-9, 5-54
emulator, 2-18
kernel mode address 10, 7-58
kernel mode address 4, 7-58
supervisor mode, 3-8 to 3-9

TRAP instruction, 2-23
.TRPSET, 7-58
.TTAPE, 3-229
undoing, 3-231
.TTDDT, 3-230
.TTECH, 3-231
.TTINR, 7-59
.TTNCH, 3-232
undoing, 3-231
.TTOUTR, 7-61
.TTRST, 3-233
TTSYNC characteristic, 3-219
TTYHCT, 3-397
.TTYIN, 7-59
.TTYOUT, 7-61
.TWAIT, 7-62
Type-ahead
canceling, 3-216

u
UCTTBL, 3-399
UFD (User File Directory), 3-25
deleting, 3-411
positioning on disk, 3-348, 3-350
preextending, 3-348, 3-350
.ULOG, 3-234 to 3-247
subfunction summary, 3-234
.ULOG directive, 2-15
UMAP$, 5-63
UMPFQ, 3-161 to 3-162
Universal library, 1-3
Unmapping address window, 3-161,5-63
UNORG, 3-4
Unstall system, 3-382
UNTCLU, 3-395
UNTCNT, 3-395
UNTERR, 3-399
UNTLVL, 3-399
UNTOPT, 3-395
User File Directory
See UFO
User job area, 1-2, 2-8f
User job image, 2-8f
changing size, 3-73
definition, 2-5
expanding, 5-24
maximum size, 2-21
minimum size, 2-21
preallocate memory for, 2-19
User logical, 3-85
assigning, 3-234
deassigning, 3-234,3-245
deassigning all, 3-243
destroyed, 2-25
entering, 3-234
listing, 3-234
User mode
Active Page Register (APR), 2-4
User stack area, 2-11
USRLOG
within low 512 bytes, 2-10f
USRPPN, 3-83, 3-85, 3-235
within low 512 bytes, 2-10f
USRPRT, 3-85, 3-235
within low 512 bytes, 2-10f

Index-11

USRSP, 2-25
definition, 2-11
low 512 bytes, 2-9f
USTAT byte, 3-304
UU.3PP, 3-413
UU.ACT, 3-251
UU.ASS, 3-235 to 3-242,3-252
UU.ATR, 3-254
UU.ATT, 3-262
UU.BCK, 3-266
UU.BYE, 3-267
UU.CCL, 3-269
UU.CFG, 3-271
UU.CHE, 3-282
UU.CHK, 3-284
UU.CHU, 3-290
UU.CNV, 3-295
UU.DAL, 3-243 to 3-245,3-297
UU.DAT, 3-298
UU.DEA, 3-245 to 3-247, 3-299
UU.DET, 3-300
UU.DIE, 3-302
UU.DIR, 3-303
UU.DLU, 3-307
UU.DMP, 3-308
UU.ERR, 2-22,2-25,3-309
UU.FCB, 3-311
UU.FIL, 3-315
UU.HNG, 3-319
UU.JOB, 3-320 to 3-326
UU.LlN, 3-326, 3-327
UU.LOG, 3-332
UU.LOK, 3-334
UU.MNT, 3-338
UU.NAM, 3-342
UU.NLG, 3-343
UU.ONX, 3-344
UU.PAS, 3-348
UU.POK, 3-352
UU.PPN, 3-353
UU.PRI, 3-355
UU.PRV, 3-356
UU.RAD, 3-358
UU.RTS, 3-362 to 3-373
UU.SLN, 3-374
UU.SPL, 3-379
UU .STL, 3-382
UU.SWP, 3-383
UU.SYS, 3-389
UU.TB1, 3-394
UU.TB2, 3-396
UU.TB3, 3-398
UU.TRM, 3-400
UU.YLG, 3-409
UU.ZER, 3-411
.UUO, 3-248 to 3-413
subfunction summary, 3-248t
UUOFO,3-63

v
.. V1 .. , 7-66
.. V2 .. , 7-66
Version 1 RT-11 , 7-66
Version 2 RT-11 , 7-66
Vertical format, control characters, 5-49t
Virtual addressing, 2-1, 2-2

Index-12

Virtual disk, creating/deleting, 3-372

w
.wAIT, 7-63
WCB (Window Control Block), 3-311
WDB (Window Definition Block), 5-65
WDBBK$, 5-65
WDBDF$, 5-65
Wildcard
account read and reset, 3-358
file lookup, 3-46, 3-336
PPN (Project-Programmer Number) lookup, 3-353
Window
creating, 5-11
eliminating, 3-151,5-20
mapping, 3-154
mapping to, 5-40
maximum number of, 3-144
resident library, 3-144
unmapping from, 3-161,5-63
Window Control Block
See weB
Window Definition Block
See WDB
Window 10
returned by CRAFO, 3-148
returned by CRAW$, 5-14
used by ELAFO, 3-151
used by ELAW$, 5-20
used by MAPFO, 3-155,3-158
used by UMAP$, 5-63
used by UMPFO, 3-161
.wRITA, 3-414 to 3-418
.WRITC, 7-64
.WRITE, 3-419 to 3-423
RT-11 , 7-64
Writing, 3-414,3-419
one character, 7-61
.WRITW, 7-64
WSIG$, 5-66
WTSE$, 5-67

x
XBUF (Extended Buffer Pool), 2-4f
XRB, 2-12
clearing under RT-11 , 7-10
data returned to, 3-7
low 512 bytes, 2-9f
mnemonics assigned to, 2-13
P.NEWentry, 2-26
P.RUN entry, 2-28
presetting to zero, 3-6
routine to clear, 3-7
size of, 2-13
XRB format, 2-14f

z
Zero device, 3-411

How to Order Additional Documentation

Technical Support
If you need help deciding which documentation best meets your needs, call 800-343-4040 before placing
your electronic, telephone, or direct mail order.

Electronic Orders
To place an order at the Electronic Store, dial 800-DEC-DEMO (800-332-3366) using a 1200- or 2400-baud
modem. If you need assistance using the Electronic Store, call 800-DIGITAL (800-344-4825).

Telephone and Direct Mail Orders
Your Location

Call

Contact

Continental USA,
Alaska, or Hawaii

800-DIGITAL

Digital Equipment Corporation
P.O. Box CS2008
Nashua, New Hampshire 03061

Puerto Rico

809-754-7575

Local Digital subsidiary

Canada

800-267-6215

Digital Equipment of Canada
Attn: DECdirect Operations KA02/2
P.O. Box 13000
100 Herzberg Road
Kanata, Ontario, Canada K2K 2A6

International
Internall

Local Digital subsidiary or
approved distributor
USASSB Order Processing - WMOlE15
or

U.S. Area Software Supply Business
Digital Equipment Corporation
Westminster, Massachusetts 01473

lFor internal orders, you must submit an Internal Software Order Form (EN-01740-07).

Reader's Comments

RSTS/E System Directives Manual
M-EZ10B-TC

Please use this postage-paid form to comment on this manual. If you require a written reply to a software
problem and are eligible to receive one under Software Performance Report (SPR) service, submit your
comments on an SPR form.
Thank you for your assistance.

I rate this manual's:
Accuracy (software works as manual says)
Completeness (enough information)
Clarity (easy to understand)
Organization (structure of subject matter)
Figures (useful)
Examples (useful)
Index (ability to find topic)
Page layout (easy to find information)

Excellent

0
0
0
0
0
0
0
0

Good
0
0
0
0
0
0
0
0

Fair

Poor

0
0
0
0
0
0
0
0

I would like to see more/less

What I like best about this manual is

What I like least about this manual is

I found the following errors in this manual:
Page

Description

Additional comments or suggestions to improve this manual:

I am using Version _ _ _ of the software this manual describes.

Nametritle

Dept.
Date

Company
Mailing Address
Phone

Do Not Tear - Fold Here and Tape - - - - - - - - - - - - - - - - - - - - - ---,
NO POSTAGE
NECESSARY
IF MAILED
IN THE
UNITED STATES

~DmDDmDTM

BUSINESS REPLY MAIL
FIRST- CLASS MAIL PERMIT NO.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

DIGITAL EQUIPMENT CORPORATION
CORPORATE USER PUBLICATIONS
CONTINENTAL BOULEVARD MK01-2/E12
PO BOX 9501
MERRIMACK NH 03054-9982

111 ••••• 11.11 •••• 1.1 •• 1•• 11.1111.1111 •• 1••• 1.111 ••• 1
_ _ _ _ _ _ _ _ DoNotTear-FoldHere _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ ,

I
I
I
I
I
I
I'
I
III
IS
I~
~

o
~

Reader's Comments

RSTS/E System Directives Manual
AA-EZ1 OB-TC

Please use this postage-paid form to comment on this manual. If you require a written reply to a software
problem and are eligible to receive one under Software Perl"ormance Report (SPR) service, submit your
comments on an SPR form.
Thank. you for your assistance.

Excellent

Good

Fair

Poor

0
0
0
0
0
0
0
0

I would like to see more/less

What I like best about this manual is

What I like least about this manual is

I found the following errors in this manual:
Page

Description

Additional comments or suggestions to improve this manual:

I am using Version ___ of the software this manual describes.

Nametritle

Dept.
Date

Company
Mailing Address
Phone

Do Not Tear - Fold Here and Tape - - - - - - - - - - - - - - - - - - - - - - ,
NO POSTAGE
NECESSARY
IF MAILED
IN THE
UNITED STATES

~DmDDmDTM

BUSINESS REPLY MAIL
FIRST- CLASS MAIL PERMIT NO.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

DIGITAL EQUIPMENT CORPORATION
CORPORATE USER PUBLICATIONS
CONTINENTAL BOULEVARD MK01-2/E12
PO BOX 9501
MERRIMACK NH 03054-9982

111 ••••• 11.11 •••• 1.1 •• 1•• 11.1 •• 1.1 •• 1•• 1••• 1.111 ••• 1
_ _ _ _ _ _ _ _ DONotTear-FoldHere _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ ,

Printed in U.S.A.