Digital PDFs

AA-D020B-TE

March 1983

159 pages

Original

7.6MB

Document:	VAX-11/RSX-11M Programmer’s Reference Manual
Order Number:	AA-D020B-TE
Revision:	000
Pages:	159
Original Filename:

OCR Text

VAX-11/RSX-11 M
Programmer's Reference Manual
Order No. AA-00208-TE

March 1980

This document describes VAX/VMS support of the RSX-11 M Executive directives. It contains the information needed by an RSX-11 M programmer responsible for making RSX-11 M Version 3.2 task images run under VAX/VMS.

VAX-11/RSX-11 M
Programmer's Reference Manual
Order No. AA-00208-TE

SUPERSESSION/UPDATE INFORMATION:

This revised document supersedes
the VAX-11 /RSX-11 M Programmer's
Reference Manual (Order No.
AA-D020A-TE).

OPERATING SYSTEM AND VERSION:

VAX/VMS V02

SOFTWARE VERSION:

VAX/VMS V02

To order additional copies of this document, contact the Software Distribution
Center, Digital Equipment Corporation, Maynard, Massachusetts 01754

digital equipment corporation . maynard, massachusetts

First Printing, August 1978
Second Printing, March 1980
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 ar reliability of software on
equipment that is not supplied by DIGITAL or its affiliated companies.

@) 1978, 1980 by Digital Equipment Corporation

The postage prepaid READER'S COMMENTS form on the last page of this
document requests the user's critical evaluation to assist us in
preparing future documentation.
The following are trademarks of Digital Equipment Corporation:

DIGITAL
DEC
PDP
DEC US
UNIBUS
COMPUTER LABS
CO MT EX
DDT
DECCOM.M
ASSIST-11
VAX
DECnet
DATATRIEVE

DECsystem-10
DECtape
DIBOL
EDU SYSTEM
FLIP CHIP
FOCAL
INDAC
LAB-8
DECSYSTEM-20
RTS-8
VMS
IAS
TRAX

MASSBUS
OMNIBUS
OS/8
PHA
RSTS
RSX
TYPESF.T-8
TYPESET-11
TMS-11
ITPS-10
SBI
PDT

CONTENTS

Page
PREFACE

vii

SUMMARY OF TECHNICAL CHANGES

CHAP'l'ER

INTRODUCTION

1-1

1.1
1.2
1.3
1.4

VAX-11 COMPATIBILITY WITH PDP-lls
VAX/VMS COMPATIBILITY WITH RSX-llM VERSION 3.2
RSX-llM DIRECTIVE REQUESTS
OVERLAYS, SHAREABLE REGIONS, MULTIUSER TASK
IMAGES, AND PLAS
EMULATION OF FLOATING-POINT INSTRUCTIONS
VAX/VMS SYSTEM CONCEPTS
DISTINCTION BETWEEN PROGRAMMING AND SYSTEM
ENVIRONMENTS

1-2
1-3
1-3

THE VAX/VMS SYSTEM ENVIRONMENT

2-1

2.1
2.2
2.3
2.4
2.5

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

2.7
2.7.1
2.7.2
2.8
2.9
2.10
2 .11
2.12
2.13
2.13.l
2.13.2
2.14
2.15

PRIVILEGES
UIC-BASED PROTECTION
RESOURCE USAGE LIMITS
PROCESS NAMES
EVENT FLAG CLUSTERS
SYSTEM STATUS CODES
MEMORY MANAGEMENT
Swapping
Paging
SYSTEM EVENTS
SYSTEM CLOCK
SOFTWARE PRIORITIES
GLOBAL SECTIONS
HIBERNATION
IMAGE TERMINATION
Normal Termination
Abnormal Termination
PARSING OF FILE SPECIFICATIONS
VAX/VMS I/O SYSTEM

VAX/VMS I/O SYSTEM

3-1

3.1
3.2
3.2.1
3.2.2
3.2.3

VAX-11 RMS
VAX/VMS I/O SYSTEM SERVICES
Assign I/O Channel System Service
Queue I/O Request System Service
Create Mailbox and Assign I/O Channel System
Service
Additional I/O System Services
I/O DRIVERS AND ACPs
RSX-llM IMAGE INTERFACE TO THE VAX/VMS I/O
SYSTEM

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

1.5
1.6
1.7
CHAPTER

2.n

CHAPTER

3.2.4
3.3
3.4

iii

1-4
1-4
1-5
1-~

2-n

2-6
2-7
2-7
?.-8
2-8
2-8
2-9
2-10
2-10
2-10
2-12
2-13

3-3
3-4
3-4
3-4

CONTENTS

Page

CHAPTER

3-n

3.5
3.6
3.7
3.8
3.8.1
3.8.2
3.9
3.10
3.10.1

DEVICE ASSIGNMENT
DEVICE MAPPING
HANDLING OF QUEUE I/O FUNCTION CODES
MAILBOXES
Mailboxes for Send/Receive Directives
I/O to Mailboxes
ACP FUNCTIONS
SPOOLED DEVICES
FCS Spooling

3-7
3-8
3-9
3-9
3-10
3-11
3-11
3-11

DIRECTIVE DESCRIPTIONS

4-1

4.1
4.2
4.2.1
4.2.2
4.2.3
4.2.4
4.2.5
4.2.6
4.2.7
4.2.8
4.2.9
4.2.10

VAX/VMS HANDLING OF DIRECTIVES
SYSTEM DIRECTIVE DESCRIPTIONS
ABRT$ ABORT TASK
ALTP$ ALTER PRIORITY
ALUN$ ASSIGN LUN
ASTX$S AST SERVICE EXIT
CLEF$ CLEAR EVENT FLAG
CMKT$ CANCEL MARK TIME REQUESTS
CRGF$ CREATE GROUP GLOBAL EVENT FLAGS
CSRQ$ CANCEL TIME BASED INITIATION REQUESTS
DECL$S DECLARE SIGNIFICANT EVENT
DSAR$S or IHAR$S DISABLE (or INHIBIT) AST
RECOGNITION
DSCP$S DISABLE CHECKPOINTING
ELGFS ELIMINATE GROUP GLOBAL EVENT FLAGS
ENAR$S ENABLE AST RECOGNITION
ENCP$S ENABLE CHECKPOINTING
EXIF$ EXIT IF
EXITSS TASK EXIT
EXST$ EXIT WITH STATUS
EXTK$ EXTEND TASK
GLUN$ GET LUN INFORMATION
GMCR$ GET MCR COMMAND LINE
GPRT$ GET PARTITION PARAMETERS
GTIM$ GET TIME PARAMETERS
GTSK$ GET TASK PARAMETERS
MRKT$ MARK TIME
QIO$ QUEUE I/O REQUEST
QIOW$ QUEUE I/O REQUEST AND WAIT
RCST$ RECEIVE DATA OR STOP
RCVD$ RECEIVE DATA
RCVX$ RECEIVE· DATA OR EXIT
RDAF$ READ ALL EVENT FLAGS
RDXF$ READ EXTENDED EVENT FLAGS
RQST$ REQUEST TASK
RSUM$ RESUME TASK
RUN$ RUN TASK
SDAT$ SEND DATA
SETF$ SET EVENT FLAG
SFPA$ SPECIFY FLOATING-POINT PROCESSOR
EXCEPTION AST
SPND$S SUSPEND
SPRA$ SPECIFY POWER RECOVERY AST
SPWN$ SPAWN

4-1
4-7
4-8
4-9
4-10
4-11
4-12
4-13
4-14
4-15
4-16

4.2.11
4.2.12
4.2.13
4.2.14
4.2.15
4.2.16
4.2.17
4.2.18
4.2.19
4.2.20
4.2.21
4.2.22
4.2.23
4.2.24
4.2.25
4.2.20
4.2.27
4.2.28
4.2.29
4.2.30
4.2.31
4.2.32
4.2.33
4.2.34
4.2.35
4.2.36
4.2.37
4.2.38
4.2.39
4.2.40

4-17
4-18
4-19
4-20
4-21
4-22
4-23
4-24
4-25
4-26
4-28
4-30
4-31
4-32
4-33
4-35
4-37
4-38
4-40
4-41
4-42
4-43
4-44
4-45
4-46
4-48
4-49
4-50
4-51
4-52
4-53

CONTENTS

Page

4.2.41
4.2.42
4.2.43
4.2.44
4.2.45
4.2.46
4.2.47
4.2.48
4.2.49
4.2.50
CHAPTER

SRDA$ SPECIFY RECEIVE DATA AST
STLO$ STOP FOR LOGICAL OR OF EVENT FLAGS
STOP$S STOP
STSE$ STOP FOR SINGLE EVENT FLAG
SVDB$ SPECIFY SST VECTOR TABLE FOR DEBUGGING

4-54
4-56
4-57
4-58

AID

4-59
4-60
4-61
4-63
4-n4
4-65

SVTK$ SPECIFY SST VECTOR TABLE FOR TASK
USTP$ UNSTOP TASK
WSIG$S WAIT FOR SIGNIFICANT EVENT
WTLO$ WAIT FOR LOGICAL OR OF EVENT FLAGS
WTSE$ WAIT FOR SINGLE EVENT FLAG

I/O DRIVERS

5-1

5.1
5.2
5.3
5.3.1

SUPPORTED DEVICES
GET LUN INFORMATION DIRECTIVE
STANDARD I/O FUNCTIONS
Attach and Detach I/O Device (IO.ATT
and IO.DET)
Cancel I/O Requests (IO.KIL)
I/O STATUS BLOCK AND STATUS RETURNS
DISK DRIVER
MAGNETIC TAPE DRIVER
LINE PRINTER DRIVER
TERMINAL DRIVER
IO.ATT Function
IO.ATT!TF.AST and IO.ATA Functions
IO.ATT!TF.ESQ Function
IO.DET Function
IO.KIL Function
IO.RLB, IO.RAL, IO.RNE, IO.RST, and IO.RTT
Functions
IO.RLB!TF.RAL and IO.RAL Functions
IO.RLB!TF.RNE and IO.RNE Functions
IO.RLB!TF.RST and IO.RST Functions
IO.RLB!TF.RTT and IO.RTT Functions
IO.RPR Function
IO.RPR!TF.XOF Function
IO.RVB Function
IO.RPB Function
IO.WLB, IO.Ceo, and IO.WBT Functions
IO.WLB!TF.CCO and IO.CCO Functions
IO.WLB!WBT and IO.WBT Functions
IO.WVB Function
IO.WLB!TF.WAL, IO.WAL, and IO.CCO!TF.WAL
Functions
IO. WPB F'unct ion
IO.GTS Function
SF.GMC Function
SF.SMC Function
Terminal Read Status Returns
CARD READER DRIVER
NULL DEVICE
DISK AND MAGNETIC TAPE ACPs
General Correspondence of Parameters
IO.CRE Function
IO.DEL with EX.ENA=O

5-2
5-2
5-2

5.3.2
5.4
5.5
5.6
5.7
5.8
5.8.1
5.8.1.1
5.8.1.2
5.8.2
5.8.3
5.8.4
5.8.4.1
5.8.4.2
5.8.4.3
5.8.4.4
5.8.5
5.8.5.1
5.8.6
5.8.7
5.8.8
5.8.8.1
5.8.8.2
5.8.9
5.8.9.l
5.8.10
5.8.11
5.8.12
5.8.13
5.8.14
5.9
5.10
5.11
5.11.1
5.11.2
5.11.3

5-2
5-3
5-3
5-8
5-9
5-10
5-12
5-15
5-15
5-15
5-15
5-16
5-16
5-16
5-17
5-17
5-17
5-17
5-17
5-18
5-18
5-18
5-18
5-18
5-18

5-18
5-19
5-19
5-20
5-20
5-21
5-22
5-23
5-23
5-25
5-26
5-2(,

CONTENTS

Page

5.11.4
5.11.5
5.11.6
5.11.7
5.11.8
5.11.9
5.11.10
5.11.11
5.11.12
5.11.13
5.11.14

5-2n
5-27
5-27
5-27
5-28
5-28
5-28
5-28
5-29
5-30
5-30

IO.DEL with EX.ENA=l
IO.ACR Function
IO.ACW and IO.ACE Functions
IO.DAC Function
IO.EXT Function
IO.WAT Function
IO.RAT Function
IO.FNA Function
IO.RNA Function
IO.ENA Function
IO.APC Function

APPENDIX

VAX-11 COMPATIBILITY MODE INSTRUCTION SET

A-1

APPENDIX

PARSE DIRECTIVE

B-1

B.l
B.2
B.3
B.4
B.5

NORMAL MODE PARSING
DEVICE-ONLY PARSING
DEFAULT FILENAME BLOCK PARSING
RMS-11 PARSING
DIRECTIVE CALL AND DPB FORMATS

B-1
B-2
B-2
B-2
B-2

INDEX

Index-1
FIGURES

FIGURE

1-1
2-1
3-1
3-2
3-3
5-1

5-2

Process Virtual Address Space
Format of VAX/VMS UICs
Components of VAX/VMS I/O System
RSX-llM Image Interface to VAX/VMS I/O System
Use of Mailboxes for Send/Receive Directives
Format of RSX-llM I/O Status Block under
VAX/VMS
File Identification Block Format

1-n
2-1
3-2
3-5
3-10
5-3
5-24

TABLES
TABLE

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

Reasons for RSX-llM Image Termination
Device Name Mapping
VAX/VMS Handling of Directives
I/O Status Return Codes
Disk Function Code Correspondence
Disk Parameter Correspondence
Magnetic Tape Function Code Correspondence
Magnetic Tape Parameter Correspondence
Line Printer Function Code Correspondence
Line Printer Parameter Correspondence
Terminal Function Code Correspondence
Terminal Parameter Correspondence
Subfunction Bit Correspondence
Information Returned by Get Terminal Support

2-11
3-8
4-1
5-4
5-8
5-9
5-9
5-10
5-11
5-11
5-12
5-13
5-14

(IO .GTS)

5-19

5-12

Terminal Characteristics for SF.GMC and
SF.FMC Requests
Card Reader Function Code Correspondence
ACP Parameter Correspondence
VAX-11 Compatibility Mode Instruction Set

5-21
5-22
5-25
A-1

5-13
5-14
A-1

PREFACE

MANUAL OBJECTIVES

The VAX-11/RSX-llM Programmer's Reference Manual describes VAX/VMS
support of RSX-llM directives. Thls document bridges the gaps between
the RSX-llM/M-PLUS Executive Reference Manual and the VAX/VMS System
Services Reference Manual;
and between the RSX-llM I/O Drivers
Reference Manual and the VAX/VMS I/O User's Guide.

INTENDED AUDIENCE

This manual contains information needed by an RSX-llM programmer who
is responsible for making RSX-llM Version 3.2 task images run under
VAX/VMS.
This document has two prerequisites:
•

Understanding of the RSX-llM operating
directives

system

•

Understanding of the material presented in the
User's Guide

and

executive

VAX-11/RSX-llM

STRUCTURE OF THIS DOCUMENT

Information in this document is organized as follows.
•

Chapter 1
contains
a
general
definition
of
VAX-11
compatibility mode and VAX/VMS support of RSX-llM Version 3.2
images. It also contains a general description of basic
VAX/VMS concepts, such as process and image, and their
relationship to an RSX-llM task.

•

Chapters 2 and 3 discuss certain VAX/VMS system components and
explain the implications of their use for RSX-llM task images.
Chapter 3 focuses on the use of the VAX/VMS I/O system for
RSX-llM image I/O.

•

Chapter 4 describes each RSX-llM directive as it is
under VAX/VMS.

vii

supported

•

Chapter 5 discusses QUEUE I/O REQUEST directive function codes
and function-dependent parameters for devices supported by
VAX/VMS.

•

Appendix A contains the VAX-11 compatibility mode instruction
set. Appendix B describes the VAX-11 RMS parse directive.

ASSOCIATED DOCUMENTS
The following documents may also be useful.
•

VAX-11 I nfo__!'."m§l_t_~on Di r~~-~_()t:_y__~n~ I n~e>,e_

•

VAX/VMS Primer

•

VAX/VMS ___~~-f3--~~lll _§~-~~-~ce~_~eference Manual

•

VAX/VMS I/O- -------User's
Guide
---·-------------· __ .,.
--~---·------~<'

·--~--

§_~_r-~~~EX__ Descrip~ion

•

VAX/VMS

and Glossa

•

VAX/VMS System Manager's Guide

•

VAX-11

•

RSX-llM Version 3.2 document set

Rec?E_~ __ Ma_l'!~g~ment S~rvic~-~-~~f ~_rence__~_~nual

CONVENTIONS USED IN THIS DOCUMENT
This manual uses the same conventions as the RSX-llM/M-PLUS Executive
Reference
Ma_!:!.!:!<?J, for example, brackets ( [])
ind i ca t-e opt ion a 1
parameters. In addition, the directive descriptions in Chapter 4 use
shading to highlight differences in VAX/VMS support of the directives.

viii

SUMMARY OF TECHNICAL CHANGES

The changes in VAX/VMS support of
general areas:

RSX-llM

directives

•

The addition of STOP and associated directives

•

The addition of group global event flag features

•

The addition of the SPAWN directive

are

three

The new STOP and associated directives are:
•

The STOP directive, which places the calling image into
hibernation.
This hibernation can end only on an UNSTOP TASK
directive from another image or on an asynchronous system trap
(AST) in the calling image.

•

The UNSTOP TASK dir~ctive, which activates a given
is hibernating because it issued a STOP directive.

•

The STOP FOR LOGICAL OR OF EVENT FLAGS and STOP FOR SINGLE
EVENT FLAG directives, which behave exactly as their wait
counterparts (WAIT FOR LOGICAL OR OF EVENT FLAGS and WAIT FOR
SINGLE EVENT FLAG), except that the resulting hibernation can
end only on an UNSTOP TASK or an AST.

•

The RECEIVE DATA OR STOP directive, which behaves exactly as
its exit counterpart (RECEIVE DATA OR EXIT), except that the
resulting hibernation can end only on an UNSTOP TASK or an
AST.

task

th~t

The new group global event flags features are:
e

The CREATE GROUP GLOBAL EVENT
FLAGS
directive,
which
associates an image with given group global event flags.

The ELIMINATE GROUP GLOBAL EVENT FLAGS directive, which
disassociates an image from its group global event flags.

The READ EXTENDED EVENT FLAGS directive, which retrieves
values of all flags, including group global event flags.

the

The new facility for creating subprocesses is:
•

The SPAWN directive, which creates a subprocess
executing a given image in that subprocess.

an<l

begins

These nine directives are described in detail in
Chapter
4.
Stop-driven hibernation, group global event flags, and subprocesses
are described in detail throughout Chapters 2 and 3.
NOTE
The CONNECT directive is not
under VAX/VMS Version 2.0.

supported

CHAPTER 1
INTRODUCTION

Compatibility mode is a processor state that allows PDP-11 programs to
execute under the VAX-11 processor. For compatibility mode execution
to occur, the needs of the program must be satisfied on two levels:
•

At the hardware instruction set level

•

At the level of program interface to the operating system

At the hardware level, the VAX-11 processor includes an instruction
set that is a compatible subset of the PDP-11 instruction set. This
compatibility mode instruction set provides a general basis that
potentially allows any PDP-11 user mode program to execute using the
VAX-11 hardware.
In addition, VAX/VMS supplements the subset of PDP-11 instructions
that can be used in compatibility mode through software emulation of
the FPP floating-point instructions; FIS floating-point instructions
are not emulated.
Because of the two instruction sets, the VAX-11 processor has two
basic modes of operation: native and compatibility. The processor is
in native mode to execute native
mode
instructions
and
in
compatibility
mode
to execute compatibility mode instructions.
Software controls the processor mode.
Thus, when a compatibility
program has been prepared for execution, VAX/VMS places the processor
in compatibility mode just before passing control to the program.
VAX/VMS accomplishes this in a manner that is transparent to the user.
When an RSX-llM task image executing in VAX-11 compatibility mode
attempts to interface with the operating system, a hardware-generated
trap occurs. Hardware-generated traps are the mechanism by which the
processor notifies VAX/VMS that emulation of the RSX-llM operating
system's environment is required. The occurrence of a compatibility
mode trap automatically places the processor in native mode.
Executing in native mode, VAX/VMS duplicates the RSX-llM task/system
interface. VAX/VMS returns to the task in compatibility mode to allow
the task to continue execution.
For example, RSX-llM tasks use EMT377 instructions to interface with
the operating system. An attempt to execute an EMT377 instruction on
VAX-11 hardware causes a trap to VAX/VMS. VAX/VMS then emulates the
requested
service
in
native
mode,
places the processor in
compatibility mode, and returns to the task.
The task continues
execution in compatibility mode.

1-1

INTRODUCTION

The VAX-11 system provides compatibility mode capabilities to support
the migration of task images from RSX-llM operating systems to
VAX/VMS. Compatibility mode provides a framework in which users can
run existing task images while upgrading to take full advantage of
VAX/VMS native capabilities.
The VAX-11 system also provides facilities
tasks. See the VAX-11/RSX-llM Us_~ ~~--~~_Q_':liQ~-.

for

developing

RSX-llM

Compatibility mode programs requiring floating-point
instruction
emulation
do not run as fast under VAX/VMS as on a PDP-11.
Compatibility mode programs not requiring floating-point emulation and
written for a PDP-11/70 run under VAX/VMS at approximately the same
speed as they do under the system for which they were written.
Programs not requ1r1ng floating-point emulation and written for
smaller PDP-11 processors run faster under VAX/VMS.
For Version 2.0, VAX/VMS supports execution of RSX-llM Version 3.2
nonprivileged task images in compatibility mode. The majority of
nonprivileged, user mode RSX-llM Version 3.2 task images run under
VAX/VMS without program modification or rebuilding. Others require
modification.
VAX/VMS provides the RSX-llM components {for example, MACR0-11 and
RSX-llM task builder) needed to make required modifications using the
VAX/VMS system as host. Modifications also can be made using an
RSX-llM system.
For an RSX-llM task image to execute successfully under VAX/VMS, it
must adhere to the requirements for compatibility mode operation.
Both the VAX-11 and VAX/VMS define specific requirements.
These
requirements are detailed in Sections 1.1 and 1.2.

1.1

VAX-11 COMPATIBILITY WITH PDP-llS

VAX-11 compatibility mode supports PDP-11 user mode operations.
That
is, any PDP-11 program that operates only in user mode {not in PDP-11
supervisor or kernel mode) potentially can run in VAX-11 compatibility
mode.
Any instruction or operation denied to a user mode program executing
on a PDP-11 is not allowed in VAX-11 compatibility mode. For example,
use of privileged instructions such as HALT and RESET is not
permitted;
an attempt to use a privileged instruction causes a trap
to VAX/VMS, and a subsequent error message.
The VAX-11 compatibility mode instruction set also does not support
the FIS or FPP floating-point instructions; however, VAX/VMS emulates
the FPP instructions. Appendix A of this document lists the VAX-11
compatibility mode instruction set.
VAX/VMS places further conditions on the use of the hardware by
RSX-llM task images running in compatibility mode. These conditions
are detailed in Section 1.2.

1-2

INTRODUCTION
1.2

VAX/VMS COMPATIBILITY WITH RSX-llM VERSION 3.2

VAX/VMS supports the capabilities of RSX-llM Version 3.2 to allow the
execution of RSX-llM task images. However, to run in compatibility
mode, a task image must meet the following requirements.
•

It must adhere to the hardware requirements for
mode.

compatibility

•

It must have been built by the RSX-llM task builder, Version
3.1 or later, or by the VAX/VMS task builder, Version 1.0 or
later.

•

It must be executable in a mapped RSX-llM system.

•

It must not depend on environmental features of RSX-llM that
are not available in VAX/VMS, such as partitions, PLAS, or
significant events. Environmental differences between RSX-llM
and VAX/VMS are discussed further in Chapters 2 and 3 of this
document.

•

It must execute within the limitations of task/executive
interaction described in the RSX-llM Executive Reference
Manual.
It
must not be privileged ---To-r-the~-pl.i'rpose-Of
overmapping the RSX-llM executive. The RSX-llM executive is
not present in a VAX/VMS system.

•

It must not overmap the I/O page.
present in VAX-11 hardware.

•

It must not depend on the 32-word memory
KTll memory management unit.

The PDP-11 I/O page is
granularity

not
the

RSX-llM task images must not depend on special memory management
features available to RSX-llM privileged tasks. Tasks can, however,
perform privileged functions that do not involve mapping of the
executive.
For example, a task executing in compatibility mode can
use the QIO$ function codes IO.RLB and IO.WLB to read directly from
and write directly to a mounted volume if the system manager has not
restricted the user from so doing.
Task images that are developed under RSX-llD or !AS and that are
compatible with RSX-llM can execute under VAX/VMS if they meet the
requirements listed above. However, such task images must be rebuilt
using the RSX-llM Version 3.2 task builder. RSX-llM task images do
not have to be rebuilt to run under VAX/VMS
unless
program
modification or different task builder options are required.

1.3

RSX-llM DIRECTIVE REQUESTS

In RSX-llM, a task image interfaces with the operating system by
issuing directive requests.
As a result of a directive request,
RSX-llM performs the desired function and returns control to the task.

1-3

INTRODUCTION

VAX/VMS duplicates this task/system interaction. When an RSX-llM task
image issues a directive, the hardware traps to VAX/VMS. With the
exception of the RSX-llM memory management {PLAS) directives described
in Section 1.4, VAX/VMS duplicates the requested RSX-llM function with
either of the following results.
•

The RSX-llM directive function is duplicated in
the image continues execution.

VAX/VMS,

and

•

VAX/VMS cannot duplicate the requested function but does take
whatever action is necessary to allow the task to continue
execution.

VAX/VMS duplicates the functions of most RSX-llM directives.
When
VAX/VMS cannot duplicate an RSX-llM directive, it is because of
differences in the basic concepts of the two systems, that is,
differences in the environments of the two systems.
For example, the RSX-llM capability to declare a significant event
does not exist in VAX/VMS; therefore, VAX/VMS cannot declare one upon
directive request. Rather, it performs no operation and returns a
success status to the requesting task image, which continues execution
normally.
Subsequent chapters of this document describe
implications of directive handlng in VAX/VMS·.

1.4

the

details

and

OVERLAYS, SHAREABLE REGIONS, MULTIUSER TASK IMAGES, AND PLAS

VAX/VMS supports the use of overlays produced using the overlay
descriptor language of the RSX-llM task builder by RSX-llM images.
VAX/VMS loads overlays from the image file at the appropriate point in
image execution.
VAX/VMS also supports use of shared regions by RSX-llM images.
RSX-llM
images
can access both shared commons and libraries.
Permanently available shared regions are identified to VAX/VMS by the
system manager, as described in the VAX/VMS System Manager's Guide.
Temporary regions are dynamically loaded when an image requiring them
executes.
In addition, VAX/VMS supports multiuser (shareable) task images. That
is, when a task image is specified at task build time as consisting of
a shareable and nonshareable portion, VAX/VMS allows multiple users to
access the shareable portion simultaneously. Each user has a private
copy of the nonshareable portion.
VAX/VMS does not support the RSX-llM memory management directives that
extend the program logical address space {PLAS) of an RSX-llM task.
Any task image issuing a memory management directive under VAX/VMS
receives an error status return.

1.5

EMULATION OF FLOATING-POINT INSTRUCTIONS

VAX/VMS provides software emulation of the PDP-11 FPP floating-point
instructions for images running in compatibility mode. The time
required for emulation of an ADDF {register to register) or ADDF
{memory to register)
is approximately 25 times that required on a
PDP-11/70. This timing is typical of most FPP instructions emulated.

1-4

INTRODUCTION
Results produced during emulation are the same as those
PDP-11 processors with the following two exceptions:
The result of
emulation.

On overflow, the emulator generates a reserved operand with a
value of zero, rather than providing the residue.

1.6

set

MOD

instruction

detailed

the

accurate

The FPP instruction
Handbook.

produced

PDP-11/70

under

Processor

VAX/VMS SYSTEM CONCEPTS

In VAX/VMS, the concept of an RSX-llM task is separated into its two
basic components:
the program image that executes, and the control
information and virtual address space required for image execution.
These two components correspond to the VAX/VMS concepts of image and
process, respectively. The concepts of image and process are basic to
VAX/VMS.
A process is the basic schedulable program entity that the VAX-11
processor executes. A process consists of a virtual address space and
control information that both the hardware and software require, such
as saved register contents and status information. This control
information is called the process context.
An image is the result of linking one or more object modules together.
An image can be linked by the VAX-11 linker to execute in native mode
or by the RSX-llM task builder to run in compatibility mode. An image
executes in the virtual address space provided by a process and under
control of the process.
A process's virtual address space is divided into two areas:
the
program region and the control region as illustrated in Figure 1-1.
Essentially, the program region provides virtual memory for an image.
The control region contains information required by the system to
control the process.
The concept of a process with an image is similar to the RSX-llM
concept of a task. The main difference is that a task is a form of
process that executes a specific image while a process can execute any
image.
Furthermore, a process remains to execute subsequent images
when the current image exits.
In RSX-llM, a reference to a specific task also implies a specific
reference to an image. This is not the case with VAX/VMS; therefore,
it is useful to state explicitly whether an operation affects a
process or its image. For this reason, the terms process and image
are used throughout this document instead of the term task.
The VAX-11 Technical Summary further explains the concepts of
and image.

1-5

process

INTRODUCTION
0

Program Region
RSX-11 M images run in this region.

Control Region

231

Figure 1-1

1.7

Proccess Virtual Address Space

DISTINCTION BETWEEN PROGRAMMING AND SYSTEM ENVIRONMENTS

VAX/VMS provides RSX-llM images with an environment similar to that
provided by RSX-llM. That is, when an RSX-llM image is loaded, it has
a virtual address space starting at location O. It has access to a
copy of its task header in the usual place, and RO through R7 are
initialized as they are under RSX-llM. This environment allows the
creation, assembly or compilation, linking, execution, and debugging
of RSX-llM images. VAX/VMS does not, however, attempt to duplicate
the total environment of the RSX-llM operating system.
For information about developing RSX-llM tasks
VAX-11/RSX-llM ----User's
Guide.
·--· --- ----""
·-·~-

VAX/VMS,

see

the

--~--~~---------··· ·-···-~-

Certain aspects of the RSX-llM environment have direct equivalents in
the VAX/VMS environment.
An RSX-llM task name, for example, can be
considered a VAX/VMS process name; and RSX-llM event flags can be
translated to VAX/VMS event flags.
When a VAX/VMS process executes an RSX-llM image, VAX/VMS receives the
traps and exceptions caused by that image and interprets them as
RSX-llM would. VAX/VMS then makes a response that is appropriate for
the VAX/VMS environment.
For example, I/O and send/receive data
operations become appropriate VAX/VMS functions.
Other aspects of RSX-llM equate to similar VAX/VMS functions.
For
example, both systems use user identification codes (UICs). In
RSX-llM, UICs are account (login) identifiers, provide a default user
file directory (UFO), and are used for file protection. In VAX/VMS,

1-fi

INTRODUCTION

the concept of UIC is separated from those of accoun~ identifier and
default directory name.
Rather, the UIC concept 1s expanded in the
direction of additional protection, as described in Section 2.2.
Finally, some aspects of RSX-llM have no counterpart in VAX/VMS.
Because no parallel function exists in VAX/VMS, VAX/VMS cannot
translate functions associated with those concepts
to
VAX/VMS
functions.
Examples of RSX-llM system environment aspects not
emulated under VAX/VMS are partitions, significant events, and a range
of priorities from 1 through 250. Although VAX/VMS does not duplicate
these RSX-llM features, it does accept image requests related to them
and takes an appropriate action to allow image execution to continue.

1-7

CHAPTER 2
THE VAX/VMS SYSTEM ENVIRONMENT

The environment that VAX/VMS
determined by two factors:

2.1

provides

for

RSX-llM
limits

image

allotted

The privileges, UIC, and resource usage
the user who initiates the image

The VAX/VMS system components and conventions used to support
RSX-llM directives requested by the image

PRIVILEGES

The system manager maintains a user authorization file that contains
an entry for each user. That entry includes a list of the privileges
allowed that user's process.
All of the privileges that can be
associated with a process are described in the VAX-11/RSX-llM User's
Guide.
VAX/VMS returns the RSX-llM DSW return code IE.PRI to an RSX-llM image
requesting a function for which it does not have the appropriate
privilege.
The individual directive descriptions in Chapter
4
indicate the DSW codes returned for each directive.

2.2

UIC-BASED PROTECTION

In VAX/VMS, each process has an associated UIC. The UIC consists of
32 bits (1 longword). The member code is in bits 0 through 15 and the
group code is in bits 16 through 31, as illustrated in Figure 2-1.

1..-31

16 15

-Group-

Figure 2-1

[

Member

Format of VAX/VMS UICs

VAX/VMS uses a process's UIC, with the privileges assigned to it by
the system manager, to control access to the system services that
affect other processes in the system.
When an RSX-llM image issues a directive, VAX/VMS executes the
corresponding system service.
If this service is restricted by
VIC-based protection in VAX/VMS, the group number and privileges of

2-1

THE VAX/VMS SYSTEM ENVIRONMENT

the process executing the RSX-llM image are checked before the service
is completed. An error status is returned if the issuing process is
not in the appropriate group or does not have the appropriate
privilege to affect the target process. ABORT TASK is an example of
an RSX-llM directive restricted by UIC-based protection in VAX/VMS.
VAX/VMS ignores the UIC specified when an RSX-llM image is built.
An RSX-llM image can gain access to the UIC of its process by issuing
a GET TASK PARAMETERS directive. The UIC is returned in two words of
the GET TASK PARAMETERS buffer:
•

The low-order byte of the group code and the low-order byte of
the member code are returned in word 7, as under RSX-llM:
15

throug.~-;j.7

Bits 0 through 7
of group code

•

Bits 0
of member co~~--J

The high-order byte of the group code and the high-order
of the member code are returned in word 15:
8 7

15
Bits 8 through 15
of group code

byte

0
Bits 8 through 15
of member code

The UIC returned is for informational purposes only.
The RSX-llM
image cannot use it to affect group protection or file protection.
An RSX-llM image cannot assume that its default account name is
related to its UIC. VAX/VMS provides a special directive that is used
by File Control Services (FCS) and RMS-11 to access the actual account
name.

2.3

RESOURCE USAGE LIMITS

VAX/VMS controls a process's use of system resources by enforcing
usage limits defined in the user's authorization file entry. All of
the limits that can be defined for a process are described in the
VAX-11/RSX-llM User's Guide. The following lists the quotas that may
berele-vcin{___ to --cin___ Rsx..,.TIM Image running in VAX/VMS.
•

Number of active buffered I/O requests

•

Number of bytes of system dynamic memory used for buffered I/O

•

Number of active direct I/O requests

2-2

THE VAX/VMS SYSTEM ENVIRONMENT
•

Number of files open simultaneously

•

Disk quotas

By default, VAX/VMS places an RSX-llM or native image that attempts to
exceed a resource limit in a wait state until the function can be
accomplished without exceeding the limit
(for example, until other
active I/O requests have completed). Native images can disable and
enable resource waiting. The DCL and MCR RUN commands provide an
option for controlling resource wait mode for subprocesses and
detached processes.
If an RSX-llM image attempts to exceed a limit when resource waiting
is disabled, the image receives a DSW code of IE.UPN (insufficient
dynamic memory).

2.4

PROCESS NAMES

Each process in a VAX/VMS system
identification and a process name.
UIC is unique within a system.

has a unique 32-bit process
A process name qualified by its

When a user initiates an RSX-llM image that has a task name in its
image label block (that is, a task name specified at build time),
VAX/VMS assigns the task name as the process's name during image
initialization.
That name remains in effect until the image exits.
Then, VAX/VMS restores the process name used prior to execution of the
RSX-llM image. Because VAX/VMS does not incorporate the concept of an
installed task, an RSX-llM image cannot acquire a task name by any
means other than task building.
An RSX-llM image must have a task name in its label block to provide a
name for its process if any of the following is to occur:
e

The image is to receive data using the RECEIVE DATA,
DATA OR EXIT, or RECEIVE DATA OR STOP directives

•

The image is to cooperate with other images using event flags

•

The process containing the image is to be the target of
directive action, for example, is to be requested or resumed

Each of the following RSX-llM directives accepts a
argument.
e

ABORT TASK

•

CANCEL TIME BASED INITIATION REQUESTS

REQUEST TASK

•

RESUME TASK

•

RUN TASK

•

SEND DATA

task

name

RECEIVE

VAX/VMS supports the RSX-llM convention of naming multiuser MCR tasks
with a string that starts with three periods, for example, ••• PIP.
When VAX/VMS encounters an image with a task name of this type,
it
recognizes
that the image can be run by more than one user
simultaneously. For such images, VAX/VMS does not create a process

2-3

THE VAX/VMS SYSTEM ENVIRONMENT

name from the task name or set up the mechanisms for it to receive
data from other processes and to synchronize with other processes
using event flags.
If an RSX-llM image is to issue directives that specify a process
executing a native ~mage as the target, the user must be aware of the
difference in the allowable lengths of task names and process names.
A task name has a maximum length of six characters.
A process name
has a maximum length of 15 characters. Therefore, if an RSX-11M image
is to refer to a process running a native image, that process's name
must not exceed six characters. An RSX-llM image cannot express a
process name that exceeds six characters.
A process running a native image can create a subprocess or a detached
process, assign it a process name, and designate an image that the
process is to execute. Thus, a process can create a named subprocess
or detached process that executes an RSX-llM image. Once the process
is created, other processes can issue system service requests in
native mode or directive requests in compatibility mode that designate
the process as the target. The creator of a subprocess always is
allowed to affect the subprocess. Other processes and subprocesses
must have either group or world privilege to affect the subprocess.
Subprocess and detached process creation are described in the
Sys t e ~___§_~~-Y.l~-~~---~~-~-~- re n c e Man u a 1 •

2.5

VAX/VMS

EVENT FLAG CLUSTERS

An RSX-llM task can have up to three event flag clusters of 32 bits
each.
VAX/VMS
emulation
of these event flags is completely
transparent to RSX-llM task images. The event flag clusters are:
•

Local event flags, numbered 1 through 32

•

Common event flags, numbered 33 through n4

•

Group global event flags, numbered n5 through 9n

Although event flag emulation is transparent to RSX-llM task images,
the handling of these flags is important to interactions between
native VAX/VMS processes and RSX-llM task images.
A native VAX/VMS
process cannot associate with any common or group global event flag
cluster outside its UIC group.
Local event flags (flags 1 through 32) are visible only to the local
task image. A task image can both read and set its local event flags.
Every task image is associated with its local event flag cluster.
A
native VAX/VMS process cannot associate with the local event flag
cluster for an RSX-llM task image.
Common event flags (flags 33 through 64) are visible to all processes
associated with the flag cluster. Any process can read and set flags
in its associated common event flag cluster.
VAX/VMS
The name of a common event flag cluster is RSXCOMEFN.
qualifies this name with a UIC group number to protect the flags from
processes with different UIC group numbers. Only processes with the
correct UIC group number can associate with the common event flag
cluster RSXCOMEFN for that UIC group.

2-4

THE VAX/VMS SYSTEM ENVIRONMENT
An RSX-llM task image is associated with a common event flag cluster
only if its task image label block has a task name. Otherwise, the
task image has no common event flags.
A native VAX/VMS process can associate with the common event flags for
an RSX-llM task image.
To do this, the process must issue the
Associate Common Event Flag Cluster system service, giving an event
flag number in the range 64 to 95 and giving the cluster name
RSXCOMEFN. Note that the native process sees the common event flags
as flags 64 through 95; an RSX-llM task image sees them as flags 33
through 64.
Group global event flags (flags 65 through 96) are visible to all task
images associated with the flag cluster.
Any process that is
associated with a group global event flag cluster can read and set
flags in that cluster.
The name of a group global event flag cluster is RSXGROUPEFN. VAX/VMS
qualifies this name with a UIC group number to protect the flags from
processes with different UIC group numbers. Only processes with the
correct UIC group number can associate with the group global event
flag cluster RSXGROUPEFN for that UIC group.
An RSX-llM task image is associated with a group global event flag
cluster only if it has issued a CREATE GROUP GLOBAL EVENT FLAGS
directive for the cluster. Otherwise, the task image has no group
global event flags.
A native VAX/VMS process can associate with a group global event flag
cluster for an RSX-llM task image. To do this, the process must issue
the Associate Common Event Flag Cluster system service, giving an
event flag number in the range 9h to 127 and giving the cluster name
RSXGROUPEFN. Note that the native process sees the common event flags
as flags 96 through 127; an RSX-llM task image sees them as flags n5
through 96.
In summary, event flag conversion for a VAX/VMS process is as follows:
Cluster
Local
Common
Group global

2.6

RSX-llM

VAX/VMS

1 through 32
33 through n4
65 through 96

32 through n3
64 through 95
96 through 127

SYSTEM STATUS CODES

In VAX/VMS, the symbolic name for a system service status
the following format.

return

has

SS$ name
When an image issues an RSX-llM directive, VAX/VMS attempts to emulate
the desired function and then returns a DSW code to indicate success
or failure to the image. In most cases, VAX/VMS calls the system
service that performs the equivalent of the requested RSX-llM function
and converts the status code returned by the service to the equivalent
RSX-llM DSW code.
For example, the VAX/VMS code SS$ NORMAL becomes
nsw code rs.sue.
-

2-5

THE VAX/VMS SYSTEM ENVIRONMENT
In some cases, however, a directive request results in a VAX/VMS error
for which no exact RSX-llM equivalent exists. This situation occurs
when an image attempts to violate a VAX/VMS concept that has no
RSX-llM equivalent.
VAX/VMS handles the situation in one of the
following ways.
•

By returning a default DSW code

•

By returning a DSW code that is meaningful for the error but
that could not be returned for the directive if the image
were running under RSX-llM

Default return codes are used when no clear one-to-one relationship
exists between VAX/VMS and RSX-llM codes; for example, a VAX/VMS code
that is equally related to two DSW codes.
A new DSW code is returned when a VAX/VMS error has no counterpart in
RSX-llM.
An example is IE.PR! which indicates that the image
attempted to issue a directive for which its process does not have the
appropriate privilege.
For example, the image attempted to resume
another process in its group but does not have group privilege.
In some cases after a directive failure, VAX/VMS returns an error code
in the DSW that is more meaningful to I/O operations. In these cases,
the high-order byte of the DSW contains o. The DSW codes IE.PR! and
IE.DUN (for ASSIGN LUN) are examples of codes that are returned as
bytes rather than words. RSX-llM images can determine whether a DSW
code is returned as a byte or word by testing the high-order byte of
the DSW for 0.
DSW codes that can be returned for each directive
Chapter 4 with the individual directive descriptions.

2.7

are

listed

MEMORY MANAGEMENT

VAX/VMS memory management facilities control the use of physical
memory and virtual memory.
VAX/VMS controls the use of physical
memory by processes through implementation of two system concepts:
•

Balance sets and swapping

•

Working sets and paging

The VAX/VMS Summary DeSCJ'."!B!Jon __~Qd Glossary details these concepts.

2.7.1

Swapping

The swapper determines which processes reside in main memory. All the
resident processes are referred to as the balance set. Processes in
the balance set compete for access to the central processor.
VAX/VMS swaps processes from and t0 main memory to ensure that the
highest
priority processes are always available in mernary for
execution. The VAX/VMS swapper is more sophisticated than the RSX-llM
checkpointing function.
It does, however, provide an equivalent
mechanism to allow emulation of the RSX-llM ENABLE CHECKPOINTING and
DISABLE CHECKPOINTING directives.

2-6

THE VAX/VMS SYSTEM ENVIRONMENT
The initial state of an RSX-llM image in a process is to have swapping
(checkpointing) enabled. This state is identical to the initial state
of an image under RSX-llM.
To use the DISABLE
CHECKPOINTING
directive, an RSX-llM image must have the VAX/VMS privilege to set its
swapping mode.
Because VAX/VMS controls the use of physical memory by swapping
processes out of and into a balance set, it does not support
partitioning of physical memory. As a result, when an RSX-llM image
issues a GET PARTITION PARAMETERS directive, VAX/VMS returns a
standard response for a system-controlled partition named GEN.
See
Chapter 4 for a description of the GET PARTITION PARAMETERS directive.
VAX/VMS ignores the partition name in the image label block.

2.7.2

Paging

The virtual address space for a process consists of a number of
512-byte pages. VAX/VMS, under control of the system manager, assigns
each process a limited number of pages of physical memory that the
process can use when it is in the balance set. That limit is referred
to as the process's working set. Normally, a process is allowed a
greater number of virtual pages than physical pages. The VAX/VMS
pager determines the pages of a process's virtual address space that
are in physical memory (that is, in the working set) at any time
during process execution.
VAX/VMS facilities for control of a process's virtual address space
differ significantly from the RSX-llM approach to a task's virtual
memory. As a result, VAX/VMS does not support the RSX-llM memory
management (PLAS) directives.
Every RSX-llM image has 65K bytes of virtual memory available to it.
Because the address space is virtual rather than physical, RSX-llM
images can avoid overlaying; an image executes more efficiently by
depending on VAX/VMS memory management to determine which pages are
needed in physical memory and when they are needed.
Further
efficiency can be gained by building RSX-llM images as shareable
(/MU). So doing results in RSX-llM images that can be partially
shared under VAX/VMS.

2.8

SYSTEM EVENTS

A system event in VAX/VMS is an occurrence that affects the ability of
one or more processes in the system to execute. For example, an
executing process can put itself in a wait state, or it can set an
event flag that makes another process a candidate for execution.
System events are similar in concept to RSX-llM significant events.
In VAX/VMS, however, an image cannot request the declaration of a
system event. No VAX/VMS equivalents for the DECLARE SIGNIFICANT
EVENT and WAIT FOR SIGNIFICANT EVENT directives exist. Issuing either
of these directives has no effect on VAX/VMS;
success status is
returned to the issuing image.
Therefore task images that run under VAX/VMS must use only event flags
and mailboxes for intertask communication; they cannot meaningfully
use significant events.

2-7

THE VAX/VMS SYSTEM ENVIRONMENT
2.9

SYSTEM CLOCK

On PDP-11 systems, the number of ticks per second varies depending on
the type of clock used and its frequency. For the time-related
directives, VAX/VMS emulates a 100-tick-per-second clock.
This
difference may affect emulation of the following directives, which
have time-oriented arguments.
e

MARK TIME

•

RUN

•

GET TIME PARAMETERS

2.10

SOFTWARE PRIORITIES

VAX/VMS priorities range from 0 through 15 for normal processes and
from 16 through 31 for real-time processes. For further details on
VAX/VMS handling of priorities, see the VAX/VMS Summary Description
and __QJ_~~-~~EX •
Because RSX-llM process priorities do not correspond to VAX/VMS
priorities in a meaningful fashion, VAX/VMS does not attempt to
convert a task's priority, as specified in the image's task header, to
a VAX/VMS priority.
An RSX-llM image runs at a priority that is determined by the default
priority in the user authorization file entry for the user initiating
the process. When an image issues an ALTER PRIORITY directive,
VAX/VMS performs no operation, and image execution continues at the
original process priority. An image requiring high priority must
execute in a process that has sufficiently high priority to meet the
image's needs.

2.11

GLOBAL SECTIONS

In VAX/VMS, global sections are disk files containing data or code
that can be brought into memory and made available to processes for
manipulation and execution. Global sections are created by executing
images and by the system manager.
When a global section is
characteristics to it.
characteristics:

created, its creator assigns a set of
A global section can have the following

•

Read-only or read/write

•

Temporary or permanent

•

Group or system wide

A temporary global section remains in the system only as long as
processes are mapped to it;
when no processes are mapped to it,
VAX/VMS deletes it automatically. A permanent global section remains
in the system until it is explicitly deleted.
VAX/VMS provides group protection for group global sections.
Any
process can gain access to a system global section. A process must be
privileged to create a permanent or system global section.

2-8

THE VAX/VMS SYSTEM ENVIRONMENT
VAX/VMS imposes no limit on the number of global sections to
process can map.

which

When VAX/VMS loads an RSX-llM task image that was built specifying one
of the options COMMON, LIBR, RESCOM, or RESLIB,
it sets up the
specified library or common for the image.
When VAX/VMS loads the
RSX-llM image,
it determines whether the global section for the
library or common already exists.
If the global section exists, it is one of the following:
•

A permanent global section created by the system manager

•

A temporary global section created by VAX/VMS as a
previous RSX-llM image execution

result

In either case, VAX/VMS maps the RSX-llM image to the global section.
If the global section does not exist, VAX/VMS creates a temporary
group global section for the library or common specified in the
COMMON, LIBR, RESCOM, or RESLIB option to the task b~ilder. The image
file for either the library or common must be located on logical
device and directory SYS$LIBRARY.
When VAX/VMS creates a global section for use by RSX-llM
section has the following characteristics:

images,

the

•

Global sections are accessed
as
either
read-only
or
read/write,
and
either
position dependent or position
independent, according to the task builder specification.

•

Global sections are group and temporary.

•

The global section name is either the library name specified
in a COMMON or LIBR option or the file name specified in a
RESCOM or RESLIB option.

The disk file for a read/write global section is
data manipulation by processes that map to it.

updated

reflect

VAX/VMS does not incorporate the concept of an installed global
section that can be reinstalled to obtain a fresh copy. The disk file
for a read/write global section is updated to reflect data written in
the global section.
Therefore,
if it is necessary to maintain the
original state of a read/write (common) global section, the user must
keep a protected copy of the common file in a place other than
SYS$LIBRARY.
If the library or common area referred to is not found, VAX/VMS prints
an error message on SYS$ERROR specifying the name of the library or
common.

2.12

HIBERNATION

A hibernating process is in the system, but is inactive.
Suspending
or stopping a task image causes the task image to hibernate.
A suspended task image can be reactivated by an asynchronous system
trap (AST), or by a REQUEST TASK, RESUME TASK, or RUN TASK directive.

2-9

THE VAX/VMS SYSTEM ENVIRONMENT

A stopped task image can be reactivated only by an UNSTOP TASK
directive located in an AST service routine or in another process, or
by the setting of a specified event flag.
In both DCL and MCR, the RUN command offers options which allow
creation of a subprocess or detached process that is initially
hibernating (rather than active). Before placing the process into
hibernation, VAX/VMS loads the image, assigns any needed devices, and
loads any needed libraries and common areas.

2.13

IMAGE TERMINATION

An image running in VAX/VMS can terminate normally or abnormally.
Normal termination occurs when the image terminates of its own accord.
Abnormal termination occurs when the system or another process forces
the image to exit.

2.13.1

Normal Termination

When an RSX-llM image terminates normally, VAX/VMS performs the same
image cleanup operations as it does for a native image. If an RSX-llM
image issues a TASK EXIT directive, VAX/VMS executes an Exit system
service and returns the termination status of SS$ NORMAL.
RSX-llM images also can issue an EXIT WITH STATUS directive to specify
the appropriate status.
For both VAX/VMS and RSX-llM images, the
termination status is available to the command interpreter.
Both the DCL and MCR command interpreters use the termination status
when processing indirect command files.
DCL uses the termination
status with the ON command for error handling. MCR uses the status
with .ONERR handling. The VAX-11/RSX-llM User's Guide describes the
use of indirect command files with the MCR command interpreter.
The
VAX/V!i8- __9_!!!9_~--~~ ____ _y_sing Cornman~ Procedures describes the use of DCL
command procedures (indirect command files).

2.13.2

Abnormal Termination

When a VAX/VMS image incurs a potentially
either of the following can occur:
•

The image can handle the condition

•

VAX/VMS forces the image to terminate

fatal

error

condition,

VAX/VMS images can react to fatal errors using the VAX/VMS condition
handling mechanism. Through that mechanism, an image can provide one
or more condition handling routines that are to be executed to handle
an exception (error) condition.
The condition handling mechanism
provides a function that is comparable to, but more flexible than, the
RSX-llM synchronous system trap (SST) mechanism. VAX/VMS condition
handling is described in the VAX/_YMS --~~!:-~!!!. ~ervic~~ __R~J~I~r.:ice Manual.
If an image incurring an exception handles it, the image can continue
execution or exit normally, as described above. If the image does not
handle the exception, the system terminates the image by issuing an
Exit system service. The Exit system service initiates image-related
cleanup operations and saves the termination status. That status is

2-10

THE VAX/VMS SYSTEM ENVIRONMENT

available to
the process.

the command interpreter or the next image to execute in

Abnormal termination of an RSX-llM image can occur as a result of
of the following:
•

Violation of the hardware conventions for
compatibility mode

images

•

Issuance of an instruction, other than EMT377, that
trap

•

Use of an illegal JMP or JSR instruction format

•

Occurrence of an odd address error

•

Violation of memory protection

•

Request for an abort from another process

•

Attempt to exceed virtual memory usage limits

any

running

causes

An RSX-llM image can supply a synchronous system trap (SST)
service
routine to handle some of the errors listed above. If the address of
an SST service routine for an error is supplied in the SST vector
table and that error occurs, VAX/VMS continues image execut~on in the
SST routine. The routine determines whether the image is to exit or
continue.
If no SST address is supplied, VAX/VMS terminates the
image.
If the error is one that·cannot be handled by an SST service routine
or if no valid SST routine address is supplied, VAX/VMS issues a
termination message on the device assigned
to
SYSSERROR
and
SYS$0UTPUT.
VAX/VMS causes the image to exit with a termination
status that is available to the command interpreter.
Table 2-1 lists the reasons for image termination and indicates which
errors can be handled by an SST service routine. The status codes in
parentheses following the termination messages are defined by $RSXDEF
macro.
Table 2-1
Reasons for RSX-llM Image Termination
Status Code

Message and Explanation
-""-~·~

RSX$ !OT

.....-..........

_.~------~

!OT EXECUTION
The image executed an !OT instruction.

RSX$ BREAK

BPT EXECUTION
The image executed a BPT instruction.

RSX$ TBIT

T-BIT EXECUTION
The image executed an
T-bit trap.

instruction

requiring

---

(continued on next page)

2-11

THE VAX/VMS SYSTEM ENVIRONMENT
Table 2-1 (Cont.)
Reasons for RSX-llM Image Termination
Message and Explanation

Status Code
RSX$ TRAP

TRAP EXECUTION
The image executed a trap instruction.

RSX$ NONRSXEMT

NON-RSX EMT EXECUTION
The image executed an invalid EMT instruction.

RSX$ ILLINST

ILLEGAL INSTRUCTION
The image executed a JMP or JSR instruction with
a register as the destination.l

RSX$ ACCVIO

MEMORY PROTECTION VIOLATION
The image addressed a
virtual address space.l

RSX$ ODDADDR

odd

address

that
is not
(HALT,
MARK,

BAD STACK
The stack pointer contains an address
the image's virtual address space.2

RSX$ INSFDYNMEM

its

RESERVED INSTRUCTION
The image executed an instruction
allowed
in co~patibility mode
RESET, SPL, or WAIT) .1

RSX$ BADSTACK

outside

ODD ADDRESS ERROR
The image addressed a word
(nonword boundary).l

RSX$ RESERVED

location

outside

NO DYNAMIC SPACE
A requested service needs more
than the process is allowed.2

dynamic

space

____________ ____ _____ _______________________

.__

..___

__,

1. The returned PC is the address of the bad instruction, not the
address following it.
2. This error cannot be trapped to the SST vector table.

2.14

PARSING OF FILE SPECIFICATIONS

Because of the VAX/VMS logical name capability,
VAX/VMS
file
specifications can differ from those used in RSX-llM.
The normal
RSX-llM parsing routines cannot provide defaults for such VAX/VMS file
specifications.
VAX/VMS provides a special directive that is issued
by FCS and RMS-11 running under VAX/VMS so that they provide proper
defaults
in a manner that is transparent to the RSX-llM image.
Any
RSX-llM image that performs its own parsing also must call
this
special directive, which is described in Appendix B.

2-12

THE VAX/VMS SYSTEM ENVIRONMENT

An RSX-llM image issuing such a directive uses the same sources for
default information as it does under RSX-llM (for example, the default
file name block and directory string). When the directive is issued,
VAX/VMS builds the necessary data structures and calls VAX-11 RMS.
When VAX-11 RMS returns the expanded file specification, VAX/VMS
returns it to the image in the format used by FCS and RMS-11 (for
example, in the resultant file name block and directory string).

VAX/VMS I/O SYSTEM

2.15

VAX/VMS uses its own I/O system in duplicating RSX-llM I/O operations.
Components at all levels of the VAX/VMS I/O system provide functions
that are similar to equivalent functions in RSX-llM.
For example,
VAX/VMS I/O system services provide functions similar to those
provided by RSX-llM I/O directives. Differences between the two I/O
systems arise in the following cases:
•

VAX/VMS implementation of a function varies from RSX-llM
implementation to provide more flexibility or efficiency (for
example, certain Queue I/O Request function codes)

•

VAX/VMS implementation of a function or concept not provided
in RSX-llM and use of that function in emulating RSX-llM I/O

Such differences
directives.

affect

emulation

•

ASSIGN LUN

•

GET LUN INFORMATION

•

QUEUE I/O RF.QUEST

•

QUEUE I/O REQUEST AND WAIT

•

SEND DATA

•

RECEIVE DATA

•

RECEIVE DATA OR EXIT

•

RECEIVE DATA OR STOP

the

following

Chapter 3 presents an overview of the VAX/VMS I/O system
aspects of it to an RSX-llM image.

2-13

I/0-related

and

relates

CHAPTER 3
VAX/VMS I/O SYSTEM

The I/O VAX/VMS system comprises the following components:
•

VAX-11 Record Management Services (VAX-11 RMS) for user-level,
device-independent I/O

•

I/O system services that provide the means for
assign devices and issue I/O requests directly

•

Ancillary
control
processes
(ACPs)
for
performing
file-oriented functions on disk and magnetic tape volumes

•

I/O drivers

image

Figure 3-1 illustrates the relationships among these components.

3.1

VAX-11 RMS

VAX/VMS Record Management Services (VAX-11 RMS) provide native VAX/VMS
images with the capability to perform device-independent I/O. Images
issue commands to open a file, get and put records or read and write
blocks, and close the file.
VAX-11 RMS, in turn, issues the I/O
system services that cause the driver or ancillary control process
(ACP) to perform the function requested by the user.
VAX-11 RMS is the VAX/VMS equivalent of FCS and RMS-11.
It has no
direct effect on and is inaccessible to an RSX-llM image executing in
compatibility mode. VAX/VMS does, however, call VAX-11 RMS to perform
some I/O services on behalf of an RSX-llM image.
VAX-11 RMS is described
Reference Manual.

the

VAX-11

3-1

Record

Management

Services

VAX/VMS I/O SYSTEM

VAX/VMS

image

VAX-11
RMS

1/0 system services

_____...,

or ....__

ACPs

1/0 drivers

Figure 3-1

3.2

Components of VAX/VMS I/O System

VAX/VMS I/O SYSTEM SERVICES

A native image can call VAX/VMS I/O system services to describe its
I/O requirements directly,
that
is, without using VAX-11 RMS.
The
request can be issued by a user image or by VAX-11 RMS on behalf of a
user
image.
I/O services allow suitably privileged processes to
request the following functions:
•

Assign and deassign channels

•

Queue an I/O request and {optionally) wait for its completion

•

Create and delete mailboxes

•

Allocate and deallocate devices

•

Get device information

•

Cancel I/O on a channel

3-2

VAX/VMS I/O SYSTEM

3.2.1

Assign I/O Channel System Service

Before a VAX/VMS image can request an I/O operation, it must establish
a path of reference from the process in which it is executing to the
device on which the operation is to be performed.
In VAX/VMS, this
path of reference is obtained by calling the Assign I/O Channel system
service. This service returns a channel number (path designator)
for
the assigned device. The channel number remains valid until the image
deassigns the channel or terminates.
In addition to the channels assigned by an image, a process has
channels assigned by the system. These channels are permanent for the
duration of the process. They provide the path of reference for the
process-permanent
files
used
for system input (SYS$INPUT and
SYS$COMMAND), system output (SYS$0UTPUT), error messages
(SYS$ERROR),
and any user-created process-permanent files.
For RSX-llM images
under VAX/VMS, user-created process-permanent
files
appear
as
record-oriented terminal devices.
An image can request I/O operations on channels that it assigns and on
those that the system assigns to process-permanent files. However,
VAX-11 RMS must be used for I/O operations to process-permanent files
except those mapping to terminal devices. The Assign I/O Channel
system service is the VAX/VMS equivalent of the ASSIGN LUN directive.

3.2.2

Queue I/O Request System Service

Once the image has assigned a channel to a device, the image can
request I/O operations by calling the Queue I/O Request system service
and specifying the channel number returned by the Assign I/O Channel
system
service
as
an argument.
Additional arguments provide
function-dependent and function-independent data required for the I/O
operation.
When called, the Queue I/O Request system service allocates and builds
an I/O request packet that describes the operation to be performed as
indicated by the arguments passed to it by the image. Once the packet
is built, the Queue I/O Request system service places the packet in a
queue of requests for the designated device.
Requests are queued
according to the priority of the process from which the image issued
the request. The driver for the device unit dequeues requests by
priority and performs them.

3.2.3

Create Mailbox and Assign I/O Channel System Service

The Create Mailbox and Assign I/O Channel system service lets an image
create a virtual device, called a mailbox, and assign an I/O channel
to it. Mailboxes provide the mechanism for protected interprocess
communication in VAX/VMS. Normally, an image creates a mailbox from
which it reads and to which other images in cooperating processes
write. Access to the mailbox is restricted using the normal VIC-based
protection according to system, owner, group, and world.
An image
performs I/O operations on a mailbox using VAX-11 RMS $GET and $PUT
commands or the Queue I/O Request system service.
A mailbox has no RSX-llM equivalent.
However, VAX/VMS does use
mailboxes in duplicating RSX-llM send/receive directives.
If a
logical name is assigned to an existing mailbox, an RSX-llM image can
issue I/O requests to the mailbox using the mailbox's logical name.
An RSX-llM image cannot create a mailbox directly. Use of mailboxes
for send/receive directives is detailed in Section 3.8.1.
3-3

VAX/VMS I/O SYSTEM
3.2.4

Additional I/O System Services

The Allocate Device system service lets an image reserve a device for
exclusive use by the process in which the image is executing. The
device remains allocated until it is explicitly deallocated or until
the
process
terminates.
VAX/VMS
automatically allocates any
nonshareable device (for example, terminal or card reader) assigned by
a process. It does not automatically allocate a shareable device (for
example, disk). The concept of device allocation is the VAX/VMS
equivalent of the RSX-llM concept of attaching a device.
The Get Device Information system service lets an image obtain the
name and characteristics of the device assigned to a particular
channel. It is equivalent to the GET LUN INFORMATION directive in
RSX-llM.
The Cancel I/O Request system service lets an image cancel all I/O
requests pending on the specified channel. It is equivalent to the
RSX-llM QUEUE I/O REQUEST directive with a function code of IO.KIL.
I/O system services are
Reference Manual.

3.3

described

the

VAX/VMS

system

Services

I/O DRIVERS AND ACPs

Using information in the I/O request packet, the I/O driver for the
unit to which the request was queued initiates the actual hardware
operation that performs the requested function. Once the transfer is
initiated, the driver returns control to the Queue I/O Request system
service. The service returns the request status to its caller.
When
the hardware operation completes, the hardware generates an interrupt
that causes the driver to be reentered to complete processing of the
I/O request.
When the driver completes the I/O request, it issues a software
interrupt for the I/O post routine. The I/O post routine sets up the
mechanism that causes user-requested I/O completion information to be
passed to the image. For example, it fills in the I/O status block
and passes information needed to set an event flag or queue an AST, if
either is requested.
If the driver cannot perform the request because it requires handling
of file-structured volumes, ACP intervention is needed. In that case,
the driver queues the request for the appropriate ACP to perform.

3.4

RSX-llM IMAGE INTERFACE TO THE VAX/VMS I/O SYSTEM

RSX-llM images perform I/O by issuing requests to FCS/RMS-11 level or
by using the QIO$ directive level. The number of steps required to
perform each I/O operation varies depending on the level of the
request.
Figure 3-2 illustrates the interface between an RSX-llM
image and the VAX/VMS I/O system.

l-4

VAX/VMS I/O SYSTEM

RSX·11M Image issues
FCS or RMS·11 request

RSX-11M image Issues 010$

Request goes to FCS or
RMS-11 running in
compatibility mode

FCS or RMS-11 issues
the appropriate 010$

010$ traps to VAX/VMS

VAX/VMS issues
VAX-11 RMS$GETor$PUT

VAX-11 RMS issues
appropriate $010

VAX/VMS issues
appropriate $QIO

VAX/VMS converts status
code returned to
appropriate DSW code

VAX/VMS returns DSW code
to image issuing 010$

Driver notifies VAX/VMS
of 1/0 completion

VAX/VMS converts IOSB
status and returns status,
if IOSB is defined

VAX/VMS Issues 1/0 done
AST for lmlQ8 and/or sets
event flag, If requested

Figure 3-2

RSX-llM Image Interface to VAX/VMS I/O System

3-5

VAX/VMS I/O SYSTEM

Images issuing FCS and RMS-11 requests use the same FCS and RMS-11
routines available in RSX-llM.l Some of these routines have been
modified to take advantage of VAX/VMS features, such as directory
naming and file specification parsing.
To take advantage of the
modifications, the RSX-llM image must be rebuilt under VAX/VMS.
The
VAX/VMS modifications are compatible with RSX-llM versions of FCS and
RMS-11.
Both FCS and RMS-11 run in compatibility mode under VAX/VMS. When an
RSX-llM image issues either an FCS or RMS-11 request, FCS or RMS-11
receives the request and reacts to it in the same mannner as it does
when running in RSX-llM. That is, FCS/RMS-11 issues the appropriate
RSX-llM QIO$ directive.
From this point, the steps are identical
RSX-llM image issues a QIO$ directive:

those

taken

when

any

•

The QIO$ directive traps to VAX/VMS.

•

VAX/VMS determines whether the QIO$ was to a process-permanent
file, such as TI or SYS$0UTPUT. If it is and that device is
not a terminal, VAX/VMS issues a VAX-11 RMS $GET or $PUT
request.
Otherwise, VAX/VMS issues the VAX/VMS $QIO system
service request that corresponds to the RSX-llM QIOS.

•

Upon completion of the QIO request, VAX/VMS
appropriate DSW code to the issuing image.

•

Upon completion of the I/O operation, VAX/VMS returns status
information in the I/O status block and sets an event flag or
declares an AST, if requested.

returns

the

If the routine to which the DSW code is returned is either FCS or
RMS-11, that component in turn makes the appropriate status return to
the calling image.

3.5

DEVICE ASSIGNMENT

VAX/VMS performs device assignment for RSX-llM images as part of image
initialization when the image is loaded. It also performs device
assignment during image execution as a result of an ASSIGN LUN
directive.
In making a device assignment for an RSX-llM image, VAX/VMS proceeds
with the following steps, which result in the device unit's physical
name.
•

VAX/VMS forms an ASCII string using the device name and unit
number supplied by the image. VAX/VMS uses the two characters
plus the binary unit number supplied.
The unit number is
converted to ASCII base 8. No editing is performed on the
name; for example, if TTl is supplied, that name is used
rather than TTOl.

1. Because the VAX/VMS Files-11 ACP does not support block locking,
RMS-11 block locking across processes is not supported. As a result,
RMS-11 does not allow file sharing for write-accessed files of
relative and indexed organization under VAX/VMS.

3-6

VAX/VMS I/O SYSTEM

•

VAX/VMS attempts to translate the ASCII string as a logical
name using the Translate Logical Name system service. If the
attempt to translate fails, VAX/VMS assumes that the image
supplied an RSX-llM physical device name. It converts the
unit number to decimal. It builds a VAX/VMS physical device
name using the image's original input and issues an Assign I/O
Channel system service using the VAX/VMS device name. VAX/VMS
maps RSX-llM physical device names to VAX/VMS physical device
names, as described in Section 3.n.
If the name translates, VAX/VMS attempts up to two more
translations.
If the maximum number of translations (three)
is performed or if one of the attempts results in no
translation,
VAX/VMS assigns a channel using the final
equivalence name.

For example, if !NO is defined as a process's logical name for TTB3
and that process runs an RSX-llM image which subsequently issues an
ASSIGN LUN directive for !NO, VAX/VMS forms an ASCII string for INO,
translates the string to TTB3, and assigns a channel to TTB3.

3.6

DEVICE MAPPING

If the user does not assign the RSX-llM device name as the logical
name for a VAX/VMS physical device unit, VAX/VMS automatically
pe~forms the translation to a
physical device.
(A mailbox is an
exception;
its device name is MBAn, where n is its unit number.) This
conversion is done by converting the RSX-llM unit number to decimal
and dividing it by 16 (decimal). The quotient is added to the ASCII
value representing the character A.
The result is the controller
letter.
The remainder becomes the VAX/VMS unit number. For example,
RSX-llM devices TTO and DB18 become VAX/VMS devices TTAO and DBB2,
respectively.
TTO to TTAO:
Controller and unit='A'+(0/16)='A'+O with a remainder of 0
'A'+O='A'=controller
O=unit number
DB18 to DBB2:
Controller and unit='A'+(l8/16)='A'+l with a remainder of 2
'A'+l='B'=controller
2=unit number
VAX/VMS performs this conversion when assigning an I/O device
RSX-llM image.

3-7

for

VAX/VMS I/O SYSTEM
To convert back from a VAX/VMS device name to the RSX-llM form,
VAX/VMS performs the reverse operation.
It subtracts the value
representing the ASCII character A (65) from the controller letter and
multiplies the result by 16 (decimal). It then adds the VAX/VMS unit
number. The result is an RSX-llM unit number that is appended to the
2-character device name.
For example, the VAX/VMS device name LPBl
converts to the RSX-llM device name LP17.
LPBl to LP17:
Unit =(('B' - 'A')

* 16) + 1 = (1 * 16) + 1 = 17

VAX/VMS performs this conversion and stores it in the RSX-llM logical
name list for the image. This device information is returned as a
result of a GET LUN INFORMATION directive.
The logical names TI, CL, CO, SY, and OV are exceptions to the rules
for device name mapping.
Table 3-1 shows device name mapping for
VAX/VMS logical names.
Table 3-1
Device Name Mapping
RSX-llM
Name

GLUN$ Name

VAX/VMS Name

------ ----------------·---TIO

$In
$On

SYS$INPUT
SYS$0UTPUT

CLO

$En

SYS$ERROR

coo

$Cn

SYS$COMMAND

SYO

Mapped name

SYS$DISK

SPn

Mapped name

Name assigned by system manager

WKn

Mapped name

Name assigned by system manager

LBn

Mapped name

Name assigned by system manager

ovo

3.7

For the LUN used by
the
overlay
run-time
system, OVO translates to
provide access to the task image file.
Any other LUNs assigned to OVO cause
VAX/VMS to assign the device on which
the image resides.

HANDLING OF QUEUE I/O FUNCTION CODES

VAX/VMS provides
both
device-independent
and
device-dependent
functions at the Queue I/O Request service level. Device-independent
functions include read and write virtual block, read and write logical
block, and read and write physical block. Device-dependent functions
include operations such as the handling of control and escape
sequences for terminal I/O and positioning functions for magnetic
tape. For most RSX-llM function codes, VAX/VMS has a corresponding
function code or system service.
All disk and most magnetic tape
function codes have corresponding functions in VAX/VMS. However, two

3-8

VAX/VMS I/O SYSTEM

areas exist where discrepancies
handling may appear:

between RSX-llM and VAX/VMS device

•

Handling of terminal devices

•

Handling of spooled devices

Details concerning VAX/VMS handling of all RSX-llM device function
codes are provided in Chapter 5. The implications of spooling for
RSX-llM images is described in Section 3.10.

3.8

MAILBOXES

A mailbox is a record-oriented virtual device used in VAX/VMS for
generalized communication among processes. VAX/VMS uses a mailbox to
duplicate the RSX-llM RECEIVE DATA, RECEIVE DATA OR EXIT, RECEIVE DATA
OR STOP, and SEND DATA directives. These directives are the normal
means of intertask communication in the RSX-llM environment.
A mailbox has VIC-based protection associated with it. The creator of
the mailbox can specify read and write privileges for system, owner,
group, and world. Because the concepts of execute and delete are not
meadingful for mailboxes, the creator does not specify privileges for
these functions.
When VAX/VMS creates a mailbox for emulating the
send/receive
directives, it specifies read access for the owner and write access
for the group. The owner is the image issuing the receive directives
and the group comprises the images issuing the send directives. Owner
and group are identified by the UIC under which they execute.

3.8.1

Mailboxes for Send/Receive Directives

When VAX/VMS loads a compatibility mode image, it determines whether
the image has a task name by examining the image's task label block.
The presence of a task name in the label block is an indication that
the image can issue RECEIVE DATA, RECEIVE DATA OR EXIT, and RECEIVE
DATA OR STOP directives to obtain data sent to it by other images.
The system defines a process name that is identical to the task name
in the label block. If the name is unique, just prior to actual image
execution, the system creates a mailbox and associates it with the
process. The mailbox is named as follows:
RCVDtaskname
The name is qualified by group number. Other images that send data to
the mailbox must be within the same group and have group or world
privilege.
VAX/VMS does not create a mailbox for an image having a task
the form ••• xxx, for example, ••• MAC.

name

Figure 3-3 illustrates the use of mailboxes for the send
functions.

receive

3-9

and

VAX/VMS I/O SYSTEM

[group] ABC
[group] RCVDABC
RECEIVE
SEND TO

[group]

MAILBOX

RSX-11M
Image ABC

DATA

ABC

RSX-11M
Image
(no name)

Figure 3-3

3.8.2

Use of Mailboxes for Send/Receive Directives

I/O to Mailboxes

A mailbox has a device name of MBAn. The value of n is the unit
number.
VAX/VMS unit numbers are 5-digit numbers in the range 0 to
65535. When an image creates a mailbox, VAX/VMS assigns a unit number
to it.
Each time an image executes, the unit number assigned by
VAX/VMS to any mailboxes that the image creates can vary.
Because mailboxes are treated as devices under VAX/VMS, any RSX-llM
image can assign a channel to a mailbox using its logical name and
perform record I/O to it. The RSX-llM image must use the logical name
rather than the device name (MBAn) to refer to the mailbox because
RSX-llM images can accept only a unit number in the range O to 255.
Either an RSX-llM image or a native VAX/VMS image can assign a
mailbox; only a native VAX/VMS image can create a mailbox. A mailbox
assigned by an RSX-llM image must be either permanently available in
the system or created by a native image. Assignment of a mailbox is
treated the same as the assignment of other VAX/VMS devices for
RSX-llM images.
A mailbox can be shared by native images and RSX-llM images.
As a
result, mailboxes provide a convenient means for native images to
communicate with RSX-llM images.
The mailbox
used
for
such
communication can be created by a native image or created by VAX/VMS
for emulating the send and receive directives.
A native image can send messages to a mailbox created for directive
emulation by issuing write requests to it. The image can use either
VAX-11 RMS or the Queue I/O Request system service for the I/O
operations.

3-10

VAX/VMS I/O SYSTEM
3.9

ACP FUNCTIONS

RSX-llM Files-11 ACP functions correspond directly to VAX/VMS Files-11
ACP functions.
The mapping is transparent to the RSX-llM image, as
described in Chapter 5.

3.10

SPOOLED DEVICES

Under VAX/VMS, spooling occurs as a result of cooperation among the
I/O related system services:
Files-11 ACP, VAX-11 RMS, and output
symbionts. Spooling in RSX-llM requires interaction with the RSX-llM
spooler.
Use of VAX/VMS spooled devices is transparent to RSX-llM
images.
If an image assigns a device that is spooled (for example, a line
printer) the resulting assignment is actually to an intermediate
device (for example, a disk).
If the image issues a GET LUN
INFORMATION directive, the system returns characteristics that are
consistent with the intermediate device containing the spooled files.
Characteristics of the final output device (the line printer) are not
returned to the RSX-llM image.
If an image uses RMS-11 or FCS to access a spooled device, the file is
spooled when it is deaccessed.
Use of the QUEUE I/O REQUEST directive to a VAX/VMS spooled device
without preceding the request with an OPEN$ macro or appropriate ACP
functions results in a privilege violation status return. Because the
device to which the QUEUE I/O REQUEST directive actually is directed
is a file-structured device, the appropriate ACP functions
(for
example, access file) must occur before I/O to the device can he
performed. Use of RMS-11 or FCS PUT$ requests ensures that the ACP
functions occur.

3.10.1

FCS Spooling

The FCS spooling macro PRINT$ and the services associated with it
under RSX-llM are supported in VAX/VMS.
Spooling in RSX-llM is
accomplished by a task named PRT...
When VAX/VMS detects a SEND
DATA directive with PRT ••• as the target, it executes a Send Message
to Symbiont Manager system service to spool the file.

3-11

CHAPTER 4
DIRECTIVE DESCRIPTIONS

This chapter describes how VAX/VMS handles
VAX/VMS
handling
that
is different from
gray-shaded.

RSX-llM
RSX-llM

directives.
handling is

Section 4.1 summarizes differences between VAX/VMS and
RSX-llM
handling of directives.
All directives supported under VAX/VMS are
described in Section 4.2. These directives are alphabetized by macro
name.

4.1

VAX/VMS HANDLING OF DIRECTIVES

Table 4-1 outlines the differences between RSX-llM and VAX/VMS
handling -0f directives. For each directive, the table gives the macro
name and the principal differences in handling.
The numbers in
parentheses refer to sections (other than the directive description in
this chapter) that further clarify the VAX/VMS handling.
Table 4-1
VAX/VMS Handling of Directives
Macro

Directive Name, Di ff erences, and Section References

-----·--------------------!
ABRT$

ABORT TASK
Process protected by group (2.2);
privilege required
( 2. 1) ;
process
target image (2.4).

ALTP$

group
or
world
name required for

ALTER PRIORITY
No operation (2.10).

----

ALUN$

ASSIGN LUN
Logical name translated (3.5);
(3.5); devices mapped ( 3. n) •

ASTX$S

device assignment required

AST SERVICE EXIT
No differences.
-~-··-

(continued on next page)

4-1

DIRECTIVE DESCRIPTIONS
Table 4-1 (Cont.)
VAX/VMS Handling of Directives
Macro

Directive Name, Differences, a nd Section References
-

ATRG$

ATTACH REGION
Not supported.
-

CINT$

CONNECT TO INTERRUPT VECTOR
Not supported.

CLEF$

"CLEAR EVENT FLAG
No differences.
·~----- M•--~-·

CMKT$

_._...-

CANCEL MARK TIME REQUESTS
Process protected by group
privilege required (2.1).

(2. 2) ;
...............

CNCT$

world

--·-··--·--"-----------!

CONNECT
Not supported.

_ _ _ _ _ _ _ _ .. _ , _ _ _ _ _ _ _ _ _-.!

CRAW$

group

CREATE ADDRESS WINDOW
Not supported.
---

·-------"'"-·--~---"--~·

CRFG$

CREATE GROUP GLOBAL EVENT FLAGS
Group global event flags protected by group (2.5).

CRRG$

CREATE REGION
Not supported.

CSRQ$

CANCEL TIME BASED INITIATION REQUE STS
( 2. 2);
Process protected by group
proc ess
privilege required
(2.1);
target image (2.4).

- - - · - - - - - - ·---~---i

-·--~----·--.,-·~---··

DECL$S

group
or
world
name required for

DECLARE SIGNIFICANT EVENT
No operation performed (2.8).
---·-------~---------·-----~-

DSAR$S

DISABLE AST RECOGNITION
No differences.

DSCP$S

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

DISABLE CHECKPOINTING
Set swap mode privilege required ( 2.1, 2.7.1).

----·------------"
(continued on next page)

4-2

DIRECTIVE DESCRIPTIONS
Table 4-1 (Cont.)
VAX/VMS Handling of Directives
Macro

Directive Name, Differences, and Section References

DTRG$

DETACH REGION
Not supported.

ELAW$

ELIMINATE ADDRESS WINDOW
Not supported.

ELGF$

ELIMINATE GROUP GLOBAL EVENT FLAGS
Group global event flags protected by group (2.5).

ENAR$S

ENABLE AST RECOGNITION
No differences.

ENCP$S

ENABLE CHECKPOINTING
Set swap mode privilege required ( 2 .1 I 2.7.1).

EXIF$

EXIT IF
Image termination (2.13).

EXIT$S

TASK EXIT
Image termination (2.13).

EXST$

EXIT WITH STATUS
Image termination (2.13).

EXTK$

EXTEND TASK
No differences.

GLUN$

GET LUN INFORMATION
Intermediate device information given for

spooled

device

(3.10, 5. 2) •

GMCR$

GET MCR COMMAND LINE
No differences.

GMCX$

GET MAPP ING CONTEXT
Not supported.

GPRT$

GET PARTITION PARAMETERS
Parameters given for GEN partition (2.7.1).
(continued on next page)

4-3

DIRECTIVE DESCRIPTIONS
Table 4-1 (Cont.)
VAX/VMS Handling of Directives
Macro

Directive Name, Differences, and Section References

GREG$

GET REGION PARAMETERS
Not supported.

GSSW$S

GET SENSE SWITCHES
Not supported.

GTIM$

GET TIME PARAMETERS
100 tick-per-second clock used (2.9).

GTSK$

GET TASK PARAMETERS
Parameters given for GEN partition (2.7.1).

MAP$

MAP ADDRESS WINDOW
Not supported.

MRKT$

MARK TIME
100 tick-per-second clock used (2.9).
_, _. .

QIO$

--···••H-----~-.-·--

QUEUE I/O REQUEST
Function codes mapped to VAX/VMS function

codes

(Chapter

codes

(Chapter

5) •

QIOW$

QUEUE I/O REQUEST AND WAIT

Function codes mapped to VAX/VMS function
5) •

RCST$

RECEIVE DATA OR STOP
protected
Mailbox used
(3.8.1);
(2.1);
process
privilege required
target image (2.4).

RCVD$

RECEIVE DATA
Mailbox used
protected
(3.8.1);
process
privilege required
(2.1);
target image (2.4).

RCVX$

group
by
(2.2);
name required for

RECEIVE DATA OR EXIT
protected
Mailbox used
(3.8.1);
process
privilege required
(2.1);
target image (2.4).

ROAF$

by
group
(2.2);
name required for

READ ALL EVENT FLAGS
No differences.
(continued on next page)

4-4

DIRECTIVE DESCRIPTIONS
Table 4-1 (Cont.)
VAX/VMS Handling of Directives
Macro

Directive Name, Differences, and Section References
.......,

RDXF$

___

.,,

READ EXTENDED EVENT FLAGS
No differences.

RQST$

REQUEST TASK
image required
(2.12);
Active or hibernating target
privilege required
(2.1);
protected by group
(2.2);
process name required for target image (2.4).
-·

RREF$

RECEIVE BY REFERENCE
Not supported.

RSUM$

RESUME TASK
Protected by group
privilege required
(2.2);
process name required for target image (2.4).

(2.1);

RUN$

RUN TASK
Active or hibernating target
image required
(2.12);
protected by group
privilege required
(2.1);
(2.2);
process name required for target image (2.4).
-·

SDAT$

SEND DATA
Mailbox used
protected
(3.8.1);
privilege required
process
(2.1);
target image (2.4).
...

SETF$

(2.2);
by
group
name required for
~

SET EVENT FLAG
No differences.

SFPA$

SPECIFY FLOATING-POINT PROCESSOR EXCEPTION AST
No differences.
-

SPND$S

SUSPEND
Process name required for caller (2.4).

SPRA$

SPECIFY POWER RECOVERY AST
No differences.

SPWN$

--·---

SPAWN
For command line
mailbox
used
(3.8.1);
handling,
protected by group (2.2);
privilege required (2.1).

(continued on next page)

4-5

__,

DIRECTIVE DESCRIPTIONS
Table 4-1 (Cont.)
VAX/VMS Handling of Directives
Macro

Directive Name, Differences, and Section References

SRDA$

SPECIFY RECEIVE DATA AST
No differences.

i-------+-------····--·-----------···-·- . .··-----·---~-------------- - - - - - - - f

SREF$

SEND BY REFERENCE
Not supported.

---------------------!

i-------1-------------------------··

SRRA$

SPECIFY RECEIVE-BY-REFERENCE AST
Not supported.

i------+-----·--·---~------------------·

STLO$

STOP FOR LOGICAL OR OF EVENT FLAGS
No differences.

i------1------------~.-·--····---···-

STOP$S

. . -·- . ---· •'<··-·-- ---------------------------!

STOP
No differences.

1-----+--------·-····----· ........... ·- ··-·······---·

STSE$

STOP FOR SINGLE EVENT FLAG
No differences.

. --. . --.----·--·---·· -· ----· ........ ----------------·-· . .- - - - - - - - · - - - - - - - - - - f
SPECIFY SST VECTOR TABLE FOR DEBUGGING AID

·-----+----~-----

SVDB$

No differences.
SVTK$

SPECIFY SST VECTOR TABLE FOR TASK
No differences.

UMAP$

UNMAP ADDRESS WINDOW
Not supported.

1---------------------------···-USTP$

UNSTOP TASK
Active or hibernating target image required
(2.12);
protected by group
(2.2);
privilege required
(2.1);
process name required for target image (2.4).
-----·-· - - -

WSIG$S

WAIT FOR SIGNIFICANT EVENT
No operation performed (2.8).

WTLO$

WAIT FOR LOGICAL OR OF EVENT FLAGS
No differences.

WTSE$

WAIT FOR SINGLE EVENT FLAG
No differences.

4-6

DIRECTIVE DESCRIPTIONS
4.2

SYSTEM DIRECTIVE DESCRIPTIONS

Each directive description includes
elements, as appropriate:

all

most

the

following

Name:
The function of the directive in VAX/VMS is described.
Macro Call:
The macro call is shown, each parameter is defined, and the
defaults
for optional parameters are given in parentheses
following the definition of the parameter.
Since zero is
supplied for most defaulted param~ters, only nonzero default
values are shown. Parameters ignored by VAX/VMS and RSX-llM are
required for compatibility with RSX-llD and !AS.
DSW Return Code:
All return codes that are valid under VAX/VMS are listed and
defined.
In some cases, a VAX/VMS return status code in
parentheses follows an RSX-llM status code. For example:
IE.RSU -- Device allocated to another image (SS$_DEVALLOC)
The VAX/VMS code indicates the VAX/VMS error
corresponding RSX-llM code to be returned.

that

caused

the

Some RSX-llM codes reflect several VAX/VMS codes. In this case,
VAX/VMS returns the RSX-llM code that it uses by default. Such
codes are followed by the phrase "default error" in parentheses.
For example:
IE.IDU -- Device or unit unknown (default error)
In some cases after a directive failure, VAX/VMS returns an error
code that is more meaningful for an I/O operation. In these
cases, the high-order byte of the DSW contains o.
Notes:
The notes presented with some directive descriptions further
explain
the
function,
use, and/or consequences of these
directives under VAX/VMS. Users should read the notes carefully
to ensure proper use of directives.

4-7

DIRECTIVE DESCRIPTIONS

ABRT$
ABRT$ - ABORT TASK

4.2.1

The ABORT TASK directive instructs the system to terminate the
execution of the indicated process's image. The requester can abort
itself or an image executing in another process.
ABORT TASK is
intended for use as an emergency or fault exit.
Macro Call:
ABRT$

tsk

DSW Return Codes:
Successful completion
Process name unknown {default error)
User not r,!,~J,~"~''~";',~"''"''(weS$ NOPRIV)
.o,~~l;ll

IE .ADP
IE.SDP

,,,_.,,;:;,,f:r~rl
Part of the DPB is
o.f ···the
address space
DIC or DPB size is invalid
y,;;t;

;'__

issuing

image's

Notes:
•

VAX/VMS executes a Force Exit system service to terminate the
specified process's image on behalf of the image issuing the
ABORT TASK directive.

•

The image issuing the ABORT TASK directive must be executing
in a process that meets either of the following requirements:
It is in the same group as the process to be
has group privilege.

aborted

and

It has world privilege.
•

The exit status is supplied by an exit handling routine {exit
handler).
It is assumed that the status returns a severe
error.

4-8

DIRECTIVE DESCRIPTIONS

ALTP$
4.2.2

ALTP$ - ALTER PRIORITY

Macro Call:
ALTP$
tsk
pri

[tsk] [,pri]
Active task name
New priority, a number from 1 to 250 (decimal)

DSW Return Codes:

Is.sue
IE.ADP
IE.SDP

Successful completion
Part of the DPB is out of the issuing image's address
space
DIC or DPB size is invalid

4-9

DIRECTIVE DESCRIPTIONS

ALUN$
4.2.3

ALUN$ - ASSIGN LUN

The ASSIGN LUN directive instructs the system to assign a physical
device unit to a logical unit number. An I/O channel is the VAX/VMS
equivalent of an RSX-llM logical unit number.

Macro Call:
ALUN$
lun
dev
unt

lun,dev,unt
Logical unit number
Device name (two characters)
Device unit number

DSW Return Codes:
Successful completion
Device or unit unknown (default error)
Invalid lo ical unit number

IE .ADP
IE. SDP

the issuing image's
Part of the DPB is
address space
DIC or DPB size is invalid

Notes:
•

VAX/VMS executes an Assign I/O Channel system service
behalf of the image issuing the ASSIGN LUN directive.

•

The assignment 0£ RSX-llM device names
devices is described in Section ·3.5.

•

If the RSX-llM device name and logical unit number are not
assigned as the logical name of a VAX/VMS device, VAX/VMS maps
the RSX-llM device name and unit number to an appropriate
VAX/VMS device name, controller, and unit number. To perform
the mapping, VAX/VMS divides the RSX-llM unit number by ln
(decimal).
The
quotient is added to the ASCII value
representing the character A. The result is the controller
designation.
The remainder becomes the VAX/VMS unit number.
The following is an example of the conversion.
RSX-llM device name and unit number
'A'+(2/16)

VAX/VMS

physical

= DB2

'A'+O with a remainder of 2

The corresponding VAX/VMS device name, controller letter,
unit number
DBA2.
•

and

If a LUN is reassigned, its previous assignment is deassigned.
The deassignment causes I/O to be canceled on the old
assignment. If the attempt to make a new assignment fails,
the LUN remains deassigned.

4-10

DIRECTIVE DESCRIPTIONS

ASTX$S
ASTX$S - AST SERVICE EXIT

4.2.4

The AST SERVICE EXIT directive instructs
execution of an AST service routine.

the

system

terminate

If another AST is queued and ASTs are not disabled,
VAX/VMS
immediately effects the next AST. Otherwise, the system restores the
image's state prior to the AST.
Macro Call:
ASTX$S
err

[err]
Error routine address

DSW Return Codes:

Is.sue
IE .AST
IE.ADP
IE.SOP

Successful completion
Directive not issued from an AST service routine
Part of the DPB or stack is out of the issuing
image's address space
DIC or DPB size is invalid

Note:
•

When an AST occurs, VAX/VMS pushes, at minimum, the
information onto the stack:
SP+06,012
SP+04
SP+02
SP+OO

following

PS of process prior to AST
PC of process prior to AST
DSW of process prior to AST

The stack must be in this state
directive is executed.

4-11

when

the

AST

SERVICE

EXIT

DIRECTIVE DESCRIPTIONS

CLEF$
4.2.5

CLEF$ - CLEAR EVENT FLAG

The CLEAR EVENT FLAG direct·ive instructs the system to clear an
indicated event flag and report the flag's polarity before clearing.
Macro Call:
CLEF$

ef n

Event flag number

DSW Return Codes:
IS. CLR
IS.SET

IE.SOP

already clear
set

Part
address space
DIC or DPB size is invalid

Notes:
•

VAX/VMS executes a Clear Event Flag system service on
of the image issuing the CLEAR EVENT FLAG directive.

•

A task image must be associated with common or group global
event flags to access flags in the common or group global
clusters {see Section 2.5).

•

Event flag conversion is as follows:
Cluster

Local
Common
Group global

RSX-llM

l through 32
33 through 64
65 through 96

4-12

VAX/VMS
32 through

n4 through 95
9n through 127

behalf

DIRECTIVE DESCRIPTIONS

CMKT$
CMKT$ - CANCEL MARK TIME REQUESTS

4.2.6

The CANCEL MARK TIME REQUESTS directive instructs the system to cancel
all mark time requests that were made by the issuing image.
Macro Call:
CMKT$
err

[,,err]
Error routine address

DSW Return Codes:

rs.sue

IE.ADP
IE.SOP

Successful completion
Part of the DPB is out of the issuing image's
address space
DIC or DPB size is invalid

Note:
•

VAX/VMS executes a Cancel Timer Request system
service
specifying that all timer requests be canceled for the image
issuing the CANCEL MARK TIME REQUESTS directive.

4-13

DIRECTIVE DESCRIPTIONS

CRGF$
4.2.7

CRGF$ - CREATE GROUP GLOBAL EVENT FLAGS

The CREATE GROUP GLOBAL EVENT FLAGS directive instructs the system to
associate a named common event flag cluster with the process that
issued the directive. If the named cluster does not exist, this
directive instructs the system first to create the named cluster (with
all flags initialized to 0) and then to associate it with the process
that issued the directive.
If a CREATE GROUP GLOBAL EVENT FLAGS directive is issued for an event
flag cluster that has been marked for deletion (by the ELIMINATE GROUP
GLOBAL EVENT FLAGS directive) but has not yet been deleted, the order
for deletion is canceled.
Macro Call:
CRGF$
group

[group]
Group number for the flags to be created

DSW Return Codes:

rs.sue

Successful

IE.DIC

space
DIC or DPB size is invalid

Notes:
•

VAX/VMS issues the Associate Common Event Flag Cluster system
service on behalf of the image issuing the CREATE GROUP GLOBAL
EVENT FLAGS directive.

•

A task image must be associated with common or group global
event flags to access flags in the common or group global
clusters (see Section 2.5).

•

Event flag conversion is as follows:
Cluster
Local
Common
Group global

•

RSX-llM

VAX/VMS

l through 32
33 through 64
n5 through 96

32 through 63
64 through 95
9n through 127

If a group number is specified in the macro call, it must
match the group number specified in the task header of the
image that issued the call; processes with the same group
number then have access to the event flags that are created.
If the group number is omitted from the macro call, the group
number specified in the task header (H.CUIC) is used.

4-14

DIRECTIVE DESCRIPTIONS

CSRQ$
CSRQ$ - CANCEL TIME BASED INITIATION REQUESTS

4.2.8

Macro Call:
CSRQ$

tsk

DSW Return Codes:

rs.sue
IE.INS
IE.PR!
IE.ADP
IE.SDP

Successful completion
Specified process name unknown (default error)
Privilege violation (SS$ NOPRIV)
Part of the DPB is out of the issuing image's
address space
DIC or DPB size is invalid

Notes:
•

VAX/VMS executes a Cancel Wakeup system service on behalf of
the
image
issuing the CANCEL TIME BASED INITIATION REQUESTS
directive.

The image issuing the CANCEL TIME BASED INITIATION REQUESTS
directive must be executing in a process that meets either of
the following requirements:
It is in the same group as the process for which
are to be canceled and has group privilege.
It has world privilege.

4-15

requests

DIRECTIVE DESCRIPTIONS

DECL$S
4.2.9

DECL$S - DECLARE SIGNIFICANT EVENT
SIGNIFICANT

EVENT

si nificant event.

Macro Call:
DECL$S
err

[,err]
Error routine address

DSW Return Codes:

rs. sue
IE.ADP
IE.SOP

Successful completion
Part of the DPB is out of the issuing image's
address space
DIC or DPB size is invalid

Note:
•

No operation is performed and a success status is returned.

4-Hi

DIRECTIVE DESCRIPTIONS

DSAR$S

IHAR$S
4.2.10

DSAR$S (or IHAR$S) - DISABLE (or INHIBIT) AST RECOGNITION

The DISABLE AST RECOGNITION directive instructs the system to disable
recognition of user-level ASTs for the issuing image. The ASTs are
queued as they occur and are effected when the image enables AST
recognition.
When
an
AST service routine is executing, AST
recognition also is disabled. The initial state of an image is to
have recognition enabled.
Macro Call:
DSAR$S
or
IHAR$S
err

[err]
[err]
Error routine address

DSW Return Codes:

rs.sue
IE. ITS
IE .ADP
IE.SOP

Successful completion
AST recognition is already disabled
Part of the DPB is out of the issuing image's
address space
DIC or DPB size is invalid

Note:
•

While disabled, ASTs are queued in a first-in/first-out list.

4-17

DIRECTIVE DESCRIPTIONS

DSCP$S
4.2.11

DSCP$S - DISABLE CHECKPOINTING

Macro Call:
DSCP$S
err

[err]
Error routine address

DSW Return Codes:

ssuing image's
IE.SOP

address space
DIC or DPB size is invalid

Notes:
•

VAX/VMS executes a Set Swap Mode system service on behalf
the image issuing the DISABLE CHECKPOINTING directive.

•

The image's initial state has swapping enabled.

•

The requesting image must have the privilege to set
mode.

4-18

its

swap

DIRECTIVE DESCRIPTIONS

ELGF$
4.2.12

ELGF$ - ELIMINATE GROUP GLOBAL EVENT FLAGS

The ELIMINATE GROUP GLOBAL EVENT FLAGS directive instructs the system
to dissociate the calling process from a named common event flag
cluster.
If no other processes are associated with a cluster thus marked for
deletion, the cluster is deleted immediately.
If, however, the
cluster is still associated with other processes, it is not deleted
until all of these processes are disassociated from the cluster.
Macro Call:
ELGF$

[group]

group

Group number of flags to be eliminated

DSW Return Codes:

IE .ADP
IE.DIC

Part of the DPB is out of the issuing image's address
space
DIC or DPB size is invalid

Notes:
•

VAX/VMS issues the Disassociate Common Event Flag Cluster
system service on behalf of the image issuing the ELIMINATE
GROUP GLOBAL EVENT FLAGS directive.

•

A task image must be associated with common or group global
event flags to access flags in the common or group global
clusters (see Section 2.5).

•

Event flag conversion is as follows:
Cluster

Local
Common
Group global
•

RSX-llM

VAX/VMS

1 through 32
33 through fi4
65 through 96

fi3
95
96 through 127

32 through

n4 through

If a group number is specified in the macro call, it must
match the group number specified in the task header of the
image that issued the call. If the group number is omitted
from the macro call, the group number specified in the task
header (H.CUIC) is used.

4-19

DIRECTIVE DESCRIPTIONS

ENAR$S
4.2.13

ENAR$S - ENABLE AST RECOGNITION

The ENABLE AST RECOGNITION directive instructs the system to recognize
user-level ASTs for the issuing image;
that 1s, the directive
nullifies a DISABLE AST RECOGNITION directive. ASTs that were queued
while recognition was disabled are effected when the ENABLE AST
RECOGNITION directive is issued. The initial state of an image is to
have AST recognition enabled.
Macro Call:
ENAR$S
err

[err]
Error routine address

DSW Return Codes:

Is.sue
IE.ITS
IE.ADP
IE.SDP

Successful completion
AST recognition is not disabled
Part of the DPB is out of the issuing image's
address space
DIC or DPB size is invalid

4-20

DIRECTIVE DESCRIPTIONS

ENCP$S
4.2.14

ENCP$S - ENABLE CHECKPOINTING

Macro Call:
ENCP$S
err

[err ]
Error routine address

DSW Return Codes:

rs. sue
IE. ITS
IE.ADP
IE.SDP

Part of the DPB is out of the issuing image's
address space
DIC or DPB size is invalid

Notes:
•

VAX/VMS executes a Set Swap Mode system service on behalf
the image issuing the ENABLE CHECKPOINTING directive.

•

The image's initial state has swapping enabled.

•

The requesting image's process must have the PSWAPM
to set its swap mode.

4-21

privilege

DIRECTIVE DESCRIPTIONS

EXIF$
4.2.15

EXIF$ - EXIT IF

The EXIT IF directive instructs the system to terminate execution of
the issuing image if the specified event flag is not set. VAX/VMS
returns control to the issuing image if the specified event flag is
set.
Macro Call:
EXIF$

ef n

Event flag number

DSW Return Codes:
IS.SET

Indicated event

IE.SOP

Part of the DPB
address space
DIC or DPB size is invalid

did not exit

Notes:
•

A task image must be associated with common or group global
event flags to access flags in the common or group global
clusters (see Section 2.5).

•

Event flag conversion is as follows:

Cluster
Local
Common
Group global

RSX-llM

VAX/VMS

1 through 32
33 through 64
65 through 96

32 through 63
64 through 95
96 through 127

4-22

DIRECTIVE DESCRIPTIONS

EXIT$S
4.2.16

EXIT$S - TASK EXIT

The TASK EXIT directive instructs the system to terminate execution of
the issuing image.
Macro Call:
EXIT$S
err

[err]
Error routine address

DSW Return Codes:
IE.ADP
IE.SOP

Part of the DPB is out of the issuing image's
address space
DIC or DPB size is invalid

Notes:
•

A return to
rejected.

the

image

occurs

•

VAX/VMS executes an Exit system service on behalf
issuing image. The success status is returned.

4-23

only

the

directive
of

is
the

DIRECTIVE DESCRIPTIONS

EXST$
4.2.17

EXST$ - EXIT WITH STATUS

The EXIT WITH STATUS directive instructs the system to terminate
execution of the issuing image and to accept from the image a status
code indicating whether the termination is normal or abnormal.
Macro Call:
EXST$
sts

sts[,err]
exit status
EX$SUC
EX$WAR
EX$ERR
EX$SEV

err

Normal termination (RSX$ EXITSTATUS)
Warning (RSX$ EXITSTATUS)
Abnormal termTnation (RSX$ EXITSTATUS)
Severe error termination (RSX$_EXITSTATUS)

= Error routine address

DSW Return Codes:
IE.ADP
IE.SDP

Part of the DPB is out of the issuing image's
address space
DIC or DPB size is invalid

Notes:
return to
• Arejected.

the

image

occurs

only

executes an Exit system service
• VAX/VMS
status of the image.

4-24

the

directive

specifying

the

is
exit

DIRECTIVE DESCRIPTIONS

EXTK$
4.2.18

EXTK$ - EXTEND TASK

The EXTEND TASK directive instructs the system to modify the size of
the issuing task by a positive or negative increment of 32-word
blocks. If the directive does not specify an increment value, VAX/VMS
makes the issuing image's size equal to its initial size.
Macro Call:
EXTK$
inc

[inc]
=

A positive or negative number equal to
32-word blocks by which the image
extended or reduced

the number of
size is to be

DSW Return Codes:

rs.sue

IE.ALG

IE.ADP
IE.SOP

Successful completion
The issuing image attempted to reduce its size
to less than the size of its header; or the
image tried to increase its size beyond 32K
words or beyond the base of the lowest mapped
library or common block
Part of the DPB is out of the issuing image's
address space
DIC or DPB size is invalid

Notes:
•

An image cannot extend itself past its 65K byte address space
or, if libraries or common areas are present, past the base of
the lowest mapped library or common block.

•

An image can extend
section.

itself

4-25

the

base

its

read-only

DIRECTIVE DESCRIPTIONS

GLUN$
4.2.19

GLUN$ - GET LUN INFORMATION

The GET LUN INFORMATION directive instructs the system to fill a
6-word buffer with information about a physical device unit to which a
LUN is assigned.
Macro Call:
GLUN$

lun,buf

lun
buf

Logical unit number
Address of 6-word buff er that is to receive the LUN
information

Buffer Format:
WD.

WD.

Name of assigned device

First device characteristics word:
Record-oriented device (l=yes) [FD.REC] 1
Carriage-control device (l=yes) [FD.CCL]
Terminal device (l=yes) [FD.TTY]
Directory device (l=yes) [FD.DIR]
Single directory device (l=yes) [FD.SDI]
Se uential device (l= es) [FD.SQD)

Bit 15
WD.

03 I

WD.

Device
(l=yes)
Device mountable (l=yes)

device

Standard device buffer size

1. Bits with associated symbols have the symbols shown in square
brackets.
These symbols can be defined for use by an image by means
of the FCSBT$ macro. See the IAS/RSX-1_1__ !fQ ___9_p~rat_ions Reference
Manual.

4-26

DIRECTIVE DESCRIPTIONS
DSW Return Codes:

rs.sue
IE.ULN
IE. ILU
IE.ADP
IE.SDP

Successful completion
Unassigned LUN
Invalid logical unit number
Part of the DPB or buff er is out of the issuing
image's address space
DIC or DPB size is invalid

Notes:
•

VAX/VMS executes a Get Channel Information system service on
behalf of the image issuing the GET LUN INFORMATION directive.

•

VAX/VMS converts the name and unit number of the VAX/VMS
device to which the LUN is assigned to an RSX-llM device name
and unit number before returning the LUN information.
To convert from a VAX/VMS device name to the RSX-llM form,
VAX/VMS subtracts the value representing the ASCII character A
(65) from the value of the ASCII character representing the
controller letter and multiplies the result by 16 (decimal).
It then adds the VAX/VMS unit number. The final result is an
RSX-llM unit number that is appended to the 2-character device
name. For example, the VAX/VMS device name TTA2 converts to
the RSX-llM device name TT2.
TTA2 to TT2:
Unit= ('A'-'A')*l6+2 = 0*16+2 = 2

•

If the device to which the LUN is assigned is a spooled device
(for
example,
a
line
printer),
VAX/VMS returns the
characteristics of the intermediate device (for example,
disk) •

•

Mailboxes have 16-bit unit numbers. The low-order 8 bits are
returned by GET LUN INFORMATION in word 1. Mailboxes must be
referred to using a logical name rather than using the unit
number returned.

4-27

DIRECTIVE DESCRIPTIONS

GMCR$
4.2.20

GMCR$ - GET MCR COMMAND LINE

The GET MCR COMMAND LINE directive instructs the system to transfer an
80-byte command line to the issuing image. It is the command line
used to invoke the image. As a result, it can be in either MCR or DCL
format.
Macro Call:
GMCR$
DSW Return Codes:
+n

IE .AST

IE.ADP
IE.SOP

Successful completion; n is the number of data
bytes transferred, excluding the termination
character.
The
termination
character
is,
however, in the buffer
No command line exists for the issuing image;
that is, the image was not requested by a
command other than RUN or the image has already
issued the GET MCR COMMAND LINE directive
Part of the DPB is out of the issuing process's
address space
DIC or DPB size is invalid

Notes:

• The system processes all lines to:
Convert tabs to a single space
Convert multiple spaces to a single space
Convert lowercase characters to uppercase
Remove all trailing blanks
The terminator <CR> is the last character in the line.
•

The command line can be the result of the following
usar-issued DCL commands:
Format

•

types

Example

$ MCR name command-string

$ MCR PIP LP:=MYFILE

$ MCR
MCR> name command-string

$ MCR
MCR>PIP LP:=MYFILE

The command line can be the result of he
MCR commands:

following

Example

Format

>name command-string

>PIP LP:=MYFILE

>name
followed by prompt

>PIP
PIP>

4-28

DIRECTIVE DESCRIPTIONS
•

The command line received as a result of the GET MCR COMMAND
LINE directive varies depending on the format of the command
typed. If the command contains a command string, for example,
LP:=MYFILE, that string and its length are available to the
image. If no string is supplied, VAX/VMS returns a command
string length of zero.

•

When an image executes as a result of a RUN command
DCL or MCR), the command line length is zero.

4-29

(either

DIRECTIVE DESCRIPTIONS

GPRT$
4.2.21

GPRT$ - GET PARTITION PARAMETERS

The GET PARTITION PARAMETERS
indicated 3-word buffer with

instructs

Macro Call:
GPRT$
prt
buf

[prt],buf
Partition name
Address of a 3-word buffer

The buffer has the following format:

DSW Return Codes:
Successful completion is indicated by carry clear and $DSW equal to
indicating a mapped system.
IE.ADP
IE.SDP

Part of the DPB or buffer is out of the issuing
image's address space
DIC or DPB size is invalid

4-30

DIRECTIVE DESCRIPTIONS

GTIM$
4.2.22

GTIM$ - GET TIME PARAMETERS

The GET TIME PARAMETERS directive instructs the system to fill an
indicated 8-word buffer with the current time parameters. All time
parameters are delivered as binary numbers.
The value ranges are
shown in decimal below.
Macro Call:
GTIM$
buf

buf
Address of 8-word buff er

The buffer has the following format:
WO. 0

WD.
WD.
WD.
WD.
WD.

1
2
3
4

Year (since 1900)
Month (1-12)
Day (1-31)
Hour (0-23)
Minute (0-59)
Second (0-59)

DSW Return Codes:

IS.sue
IE.ADP
IE. SDP

Successful completion
Part of the DPB or buff er is out of the issuing
image's address space
DIC or DPB size is invalid

Notes:
•

VAX/VMS executes a Get Time system service
issuing the GET TIME PARAMETERS directive.

•

VAX/VMS provides a 100 tick-per-second clock.

4-31

for

the

image

DIRECTIVE DESCRIPTIONS

GTSK$
GTSK$ - GET TASK PARAMETERS

4.2.23

The GET TASK PARAMETERS directive instructs the system to fill an
indicated 16-word buffer with parameters relating to the issuing
process.
Macro Call:
GTSK$
buf

buf
Address of a 16-word buff er

The buffer has the following format:

WD. 04
WD. 05

Undefined
Undefined

08
09
10
11
12
WD. 13

Number of logical I/O units (LUNs)
Undefined
Undefined
Address of task SST vector tables
Size of task SST vector table in words
Size in bytes of image's address window excluding

, , ..

~~,~i~f~~~a:~.~~·~!:~~·~~~ ~.~~·
WD.
WD.
WD.
WD.
WD.

DSW Return Codes:

rs.sue
IE.ADP
IE.SOP

Successful completion
Part of the DPB or buffer is out of the issuing
image's address space
DIC or DPB is invalid

'1-32

DIRECTIVE DESCRIPTIONS

MRKT$
4.2.24

MRKT$ - MARK TIME

The MARK TIME directive instructs the system to set an event flag
and/or declare an AST after an indicated time interval. The interval
begins when the image issues the directive.
If an event flag is
specified, the flag is cleared when the directive is issued and set
when the interval elapses.
If an AST entry point address is
specified, an AST occurs when the interval elapses.
Macro Call:
MRKT$
ef n
tmg
tnt
ast

[efn] ,tmg,tnt[,ast]
Event flag number
Time interval magnitude
Time interval unit
AST entry point address

DSW Return Codes:

rs.sue
IE. ITI

Successful completion
Invalid time parameter

Insu

ic1ent

ynam1c memory (SS

IN~FMEM}

r';ttt;?f.;; 5i1;·•:1:m:~9·~: • ~::1rnrgJP'<?~~iL.~l<·q·~:i~i:~:,·mr;~.~.·~JgK\1l1C5ffii:J

IE.SDP

Part of the DPB is out of the
address space
DIC or DPB size is invalid

issuing

image's

Notes:
•

VAX/VMS executes a Set Timer system service on behalf
process issuing the MARK TIME directive.

•

If an AST entry point address is specified, the AST service
routine is entered with the stack in the following state:
SP+08,14
SP+06
SP+04
SP+02
SP+OO

the

0
PS of process prior to AST
PC of process prior to AST
DSW of process prior to AST
Event flag number or 0 (if none was
specified in the MARK TIME directive)

The event flag number must be removed from the stack before an
AST SERVICE EXIT directive is executed.

4-33

DIRECTIVE DESCRIPTIONS

•

VAX/VMS returns the DSW code IE.IT! if the directive specifies
an invalid time parameter. The time parameter consists of two
components: the time interval magnitude (tmg) and the time
interval unit (tnt).
A legal magnitude value (tmg) is related to the value assigned
to the time interval unit (tnt). The unit values are encoded
as follows:
1

Ticks (1/100 of a second per tick)

Seconds

3 = Minutes
4

Hours

The magnitude (tmg) is the number of units to be clocked. The
following list describes the magnitude values that are valid
for each type of unit. In no case can the value of tmg exceed
24 hours.
If tnt = O, 1, or 2, tmg can be any positive value with
maximum of 15 bits.
I f tnt

3, tmg can have a maximum value of 1440(10).

I f tnt

4, tmg can have a maximum value of 24(10).

•

A task image must be associated with common or group global
event flags to access flags in the common or group global
clusters (see Section 2.5).

•

Event flag conversion is as follows:
Cluster

Local
Common
Group global
•

RSX-UM

VAX/VMS

1 through 32
33 through 64
65 through 96

32 through 113
64 through 95
96 through 127

VAX/VMS enforces a quota on the number of ASTs that a
can have pending.

4-34

process

DIRECTIVE DESCRIPTIONS

Ql0$
4.2.25

QIO$ - QUEUE I/O REQUEST

The QUEUE I/O REQUEST directive instructs the system to place an I/O
request for an indicated physical device unit into a queue of
priority-ordered requests for that device unit. The physical device
unit is specified as a logical unit number (LUN).
If the directive call specifies an event flag, VAX/VMS clears the flag
when the request is queued and sets the flag upon request completion.
The I/O status block is also cleared when the request is queued, and
set to the final I/O status when the I/O request is complete. If an
AST service routine entry point address is specified, the AST occurs
upon I/O completion, and the process's WAITFOR mask word, PS, PC, DSW
(directive status), and the address of the I/O status block are pushed
onto the stack.
Macro Call:
QIO$
f nc
lun
ef n
pri
isb
ast
prl

fnc,lun, [efn], [pri], [isb], [ast] [,prl]
I/O function code
Logical unit number
Event flag number
Priority; ignored, but must be present
Address of I/O status block
Address of AST service routine entry point
Parameter list of the form <Pl, ••• ,Pn>

DSW Return Codes:

IS.sue
IE.ULN
IE. !LU

IE .ADP
IE.SOP

Successful completion
Unassigned LUN
Invalid LUN

Part of the DPB or I/O status block is out of the
issuing image's address space
DIC or DPB size is invalid

Notes:
•

VAX/VMS executes a Queue I/O Request system service on
of the image issuing the QUEUE I/O REQUEST directive.

•

Chapter 5 explains function codes, parameter meanings, and I/O
status block return values.

4-35

behalf

DIRECTIVE DESCRIPTIONS

•

If the directive call specifies an AST entry point address,
the process enters the AST service routine with the stack in
the following state:
SP+l6 SP+06 SP+04 SP+02 SP+OO -

SP+lO - 0
PS of process prior to AST
PC of process prior to AST
DSW of process prior to AST
Address of I/O status block, or zero
was specified in the QIO directive.

none

The address of the I/O status block, which is a trap-dependent
parameter, must be removed from the stack before an AST
SERVICE EX~T directive is executed.
•

VAX/VMS pushes four words of zeros in SP+l6 through SP+lO.
RSX-llM pushes three words with undefined contents and a
1-word event flag mask.

•

If the directive is rejected, the specified event flag is not
guaranteed to be cleared or set. Therefore a process that
waits for a rejected QUEUE I/O REQUEST AND WAIT directive may
wait forever.

•

A task image must be associated with common or group global
event flags to access flags in the common or group global
clusters (see Section 2.5).

•

Event flag conversion is as follows:
Cluster

Local
Common
Group global
•

RSX-llM

VAX/VMS

1 through 32
33 through 64
n5 through 96

32 through n3
64 through 95
96 through 127

VAX/VMS enforces a quota on the number of ASTs that a
can have pending.

4-36

process

DIRECTIVE DESCRIPTIONS

QIOW$
4.2.26

QIOW$ - QUEUE I/O REQUEST AND WAIT

The QUEUE I/O REQUEST AND WAIT directive is identical to QUEUE I/0
REQUEST with one exception: if the wait variation of the directive
specifies an event flag, VAX/VMS automatically effects a WAIT FOR
SINGLE EVENT FLAG directive.
If an event flag is not specified,
however, VAX/VMS treats the directive as if it were a QUEUE I/O
REQUEST.
Macro Call:
QIOW$
f nc

lun
ef n
pri
isb
ast
prl

fnc,lun,efn, [pri], [isb], [ast] [,prll
I/O function code
Logical unit number
Event flag number
Priority; ignored, but must be present
Address of I/O status block
Address of AST service routine entry point
Parameter list of the form <Pl, ••• ,Pn>

DSW Return Codes:

rs.sue
IE.ULN
IE.ILU

Successful completion
Unassigned LUN
Invalid LUN

IE.SOP

Part of the DPB or I O status
issuing image's address space
DIC or DPB size is invalid

Note:
•

VAX/VMS executes a Queue I/O Request and Wait for Event Flag
system service on behalf of the image issuing the QUEUE I/O
REQUEST AND ,WAIT directive.

•

See the notes for the QUEUE I/O REQUEST directive.

4-37

DIRECTIVE DESCRIPTIONS

RCST$
4.2.27

RCST$ - RECEIVE DATA OR STOP

A 2-word sending process name in Radix-50 form and
block are returned in a 15-word buffer.

the

13-word

data

Macro Call:
RCST$

[tname] ,buf

DSW Return Codes:

rs. sue

IE.AST
IE.ADP
IE. SDP

o
mailbox exists;
process stopped
Diractive was issued from an AST service routine and
no data obtained from mailbox or no mailbox exists
Part of the DPB is out of the issuing image's address
space
DIC or DPB size is invalid

Notes:
executes a Queue I/O Request system
• VAX/VMS
appropriate, a Hibernate system service

if
service and,
on behalf of the
process issuing the RECEIVE DATA OR STOP directive.
The I/0
operation reads data from a mailbox associated with the
process by VAX/VMS when it loaded the image.

•

The name of the mailbox is RCVD followed by the process
that is, RCVDname.

•

The mailbox is not created until the image actually begins
execute.

•

The image issuing the receive directive must have a name
specified at task-build time;
that is, the image label block
must contain a task name. VAX/VMS uses the presence of the
task name as a indication that the image may receive data and
sets up the necessary machanism.

•

Because the protection of the mailbox is specified as read
access for the owner {receiving process) and write access for
the group (sending processes), this directive is useful only
for passing data between processes within the same group.

4-38

name,
to

DIRECTIVE DESCRIPTIONS
•

If no data is obtained from the mailbox or if no mailbox
exists, VAX/VMS executes a Hibernate system service for the
process that issued the RECEIVE DATA OR STOP directive, and a
status code of IS.SET is returned. Note that the status code
IS.SET cannot be seen by the process that issues the directive
until the process is restarted by an UNSTOP TASK directive (a
Wake system service).

•

If a process issued the RECEIVE DATA OR STOP directive and
stops because no data is available in the mailbox, the process
is not automatically awakened later when data is placed into
the mailbox. A task sending data should also wake the stopped
task using the UNSTOP TASK directive; to receive the data,
the awakened task must issue another receive-data directive
(RECEIVE DATA, RECEIVE DATA OR EXIT, or RECEIVE DATA OR STOP).

4-39

DIRECTIVE DESCRIPTIONS

RCVD$
4.2.28

RCVD$ - RECEIVE DATA

A 2-word sending process name in Radix-SO form and
block are returned in a 15-word buffer.

the

13-word

data

Macro Call:
RCVD$ [tsk] ,buf

DSW Return Codes:

, ..,... ~. ~.Q.,,g,_..

IE.ITS
IE.ADP
IE.SOP

No data currently available in mailbox or no
mailbox (default error)
Part of the DPB or buffer is out of the issuing
image's address space
DIC or DPB size is invalid

Notes:
executes a read Queue I/O Request system service on
• VAX/VMS
behalf of the process issuing the RECEIVE DATA directive. The
I/O operation reads data from a mailbox associated
process by VAX/VMS when it loads the image.

with

the

•

The name of the mailbox is RCVD followed by the process
that is, RCVDname.

•

The mailbox is not created until the image actually begins
execute.

•

Because protection is specified as read access for the owner
(receiving process) and write access for the group (sending
processes), this directive is useful only for passing data
between processes within the same group.

•

The image issuing the receive directives must have a name
specified at task-build time; that is, the image label block
must contain a task name. VAX/VMS uses the presence of the
task name as an indication that the image may receive data and
sets up the necessary mechanism.

4-40

name,
to

DIRECTIVE DESCRIPTIONS

RCVX$
4.2.29

RCVX$ - RECEIVE DATA OR EXIT

A 2-word sending process name in Radix-50 form and
block are returned in a 15-word buffer.

the

13-word

data

Macro Call:
RCVX$
buf

[ tsk] , buf
Address of 15-word buff er

DSW Return Codes:

Is.sue

Successful completion

IE.SOP

Part of the DPB
image's address space
DIC or DPB size is invalid

issuing

Notes:
•

VAX/VMS executes a Queue I/O Request system service and, if
appropriate, an Exit system service on behalf of the process
issuing the RECEIVE DATA OR EXIT directive. The I/O operation
reads data from a mailbox associated with the process by
VAX/VMS when it loaded the image.

•

The name of the mailbox is RCVD followed by the process
that is, RCVDname.

•

The mailbox is not created until the image actually begins
execute.

•

If no data is obtained from the mailbox, VAX/VMS executes an
Exit system service for the image.
The exit status is
SS$ NORMAL.

•

This directive does not provide the same interlock between the
sender and the receiver as it does in RSX-llM.

•

If no mailbox exists, the image exits with a success status.

4-41

name,
to

DIRECTIVE DESCRIPTIONS

ROAF$
4.2.30

ROAF$ - READ ALL EVENT FLAGS

The READ ALL EVENT FLAGS directive instructs the system to read local
and common event flags for the issuing process and record their values
in a 64-bit (4-word) buffer.
Macro Call:
ROAF$

buf

The buffer has the following format:
WD.
WD.
WD.
WD.

00
01
02
03

Local flags 1 through 16
Local flags 17 through 32
Common flags 33 through 48
Common flags 49 through 64

DSW Return Codes:

rs.sue
IE .ADP

IE.SOP

Successful completion
Part of the DPB or buffer is out of the issuing
image's address space
DIC or DPB size is invalid

Notes:
•

VAX/VMS issues a Read Event Flags system service on behalf
the image issuing the READ ALL EVENT FLAGS directive.

•

The READ ALL EVENT FLAGS directive does not read group global
flags.
The READ EXTENDED EVENT FLAGS directive reads all 9n
flags.

•

A task image must be associated with common flags
flags in the common cluster (see Section 2.5).

•

Event flag conversion is as follows:

Cluster

RSX-llM

VAX/VMS

Local
Common

1 through 32
33 through n4

32 through 63
114 through 95

4-42

access

DIRECTIVE DESCRIPTIONS

RDXF$
4.2.31

RDXF$ - READ EXTENDED EVENT FLAGS

The READ EXTENDED EVENT FLAGS directive instructs the system to read
all local, common, and group global event flags for the issuing
process and to record their values in a 96-bit (6-word) buffer.
Macro Call:
RDXF$

buf

Address of 6-word buff er

The buffer has the following format:
WD.
WO.
WD.
WD.
WD.
WD.

00
01
02
03
04
05

Lo ca 1 flags l through 16
Local flags 17 through 32
Common flags 33 through 48
Common flags 49 through 64
Group global flags 65 through 80
Group global flags 81 through 96

DSW Return Codes:

rs.sue
IS.CLR
IE .ADP

IE.SOP

Successful completion
Group global event flags do not exist. Words 4 and 5
of the buffer contain zeros
Part of the DPB or buffer is out of the issuing
image's address space
DIC or DPB size is invalid

Notes:
•

VAX/VMS issues the Read Event Flags system service on behalf
of the image issuing the READ EXTENDED EVENT FLAGS directive.

•

A task image must be associated with common or group global
event flags to access flags in the common or group global
clusters (see Section 2.5).

•

Event flag conversion is as follows:

•

Cluster

RSX-llM

VAX/VMS

Local
Common
Group global

l through 32
33 through 64

32 through n3
64 through 95
90 through 127

o5 through 96

If no group global event flag cluster is associated with the
process, the group global event flags are returned as all
zeros and IS.CLR is returned.

4-43

DIRECTIVE DESCRIPTIONS

RQST$
4.2.32

RQST$ - REQUEST TASK

Chapter 2 describes the
Wake system services for real-time images.
REQUEST TASK is a frequently used subset of the RUN directive.
Macro Call:
RQST$

tsk, [prt], [pri] [,ugc,umc]

DSW Return Codes:

rs.sue
IE. INS

IE .ADP
IE.SOP

Successful completion
Process name not known

Part of the DPB is out of the issuing image's
address space
DIC or DPB size is invalid

Notes:
•

VAX/VMS executes a Wake system service on
process issuing the REQUEST TASK directive.

behalf

•

The requested process must currently be present in the system;
that is, either hibernating or active.

•

The image issuing the REQUEST TASK directive must be executing
in a process that meets either of the following requirements:
It is in the same group as the requested process
group privilege.

and

the

has

It has world privilege.
•

VAX/VMS maintains an indicator to determine whether any wake
requests have been issued for an active process. If the
pending wake indicator is set and the process issues a
hibernate request, the process remains active, and the pending
wake indicator is cleared.
A subsequent hibernate request
causes the process to hibernate.

•

Hibernations that are caused by STOP directives (RECEIVE DATA
OR STOP, STOP, STOP FOR LOGICAL OR OF EVENT FLAGS, and STOP
FOR SINGLE EVENT FLAG) cannot be reactivated by the REQUEST
TASK directive.

4-44

DIRECTIVE DESCRIPTIONS

RSUM$
4.2.33

RSUM$ - RESUME TASK

Macro Call:
RSUM$

tsk

DSW Return Codes:

rs.sue
IE.INS

Successful completion
Process name unknown (default error)

IE.SDP

Part of the DPB
address space
DIC or DPB size is invalid

Notes:
•

VAX/VMS executes a Wake system service on
process issuing the RESUME TASK directive.

behalf

•

The image issuing the RESUME TASK directive must be executing
in a process that meets either of the following requirements:
It is in the same group as the process to be
has group privilege.

resumed

the

and

It has world privilege.
•

VAX/VMS maintains an indicator to determine whether any wake
requests have been issued for an active process. If the
indicator is set and the process issues a hibernate request,
the process remains active, and the indicator is cleared. A
subsequent hibernate (SUSPEND) request causes the process to
hibernate.

If a RESUME TASK directive is issued for
• active,
the status returned is success.

an image that is
The process remains

active.
•

Hibernations that are caused by STOP directives (RECEIVE DATA
OR STOP, STOP, STOP FOR LOGICAL OR OF EVENT FLAGS, and STOP
FOR SINGLE EVENT FLAG) cannot be reactivated by the RESUME
TASK directive.

4-45

DIRECTIVE DESCRIPTIONS

RUN$
4.2.34

,pf,()

RUN$ - RUN TASK

time
If the smg, rmg, and
are
omitted, RUN
is the same as REQUEST TASK except that RUN TASK
causes the process to become active one clock tick after the directive
is issued.
< .·•····

d~ita

ti~~

Macro Call:
RUN$

pri

tsk, [prt], [pri], [ugc], [umc], [smg] ,snt[,rmg,rnt]

PartiET~n name; ignored
Priority; ~gnored
·~·'']:~: ~.

9~8.,,

um¢

smg
snt
rmg
rnt

~h·ih• , g

Schedule delta
Schedule delta unit
Reschedule interval magnitude
Reschedule interval unit

DSW Return Codes:

rs.sue

Successful completion

IE. INS

fij.i>Jf .
I

f
IE. ITI
IE.ADP

IE.SOP

Invalid time parameter
Part of the DPB is out of the issuing image's
address space
DIC or DPB size is invalid

Notes:
•

VAX/VMS executes a Schedule Wakeup system service on behalf of
the process issuing the RUN TASK directive.

•

The target process must be present in the system.

•

The image issuing the RUN TASK directive must be executing
a process that meets either of the following requirements:

It is in the same group as the process to be run
group privilege.

has

and

It has world privilege.
•

VAX/VMS maintains an indicator to determine whether any wake
requests have been issued for an active process. If the wake
pending indicator is set and the process issues a hibernate
request, the process remains active, and the wake pending
indicator is cleared.
A subsequent hibernate
(SUSPEND)
request causes the process to hibernate.

4-4fi

DIRECTIVE DESCRIPTIONS
•

VAX/VMS returns the DSW code IE.IT! if the directive specifies
an invalid time parameter. A time parameter consists of two
components: the time interval magnitude (smg or rmg) and the
time interval unit (snt or rnt).
A legal magnitude value (smg or rmg) is related to the value
assigned to the time interval unit snt or rnt. The unit
values are encoded as follows:
1 = Ticks (1/100 of a second per tick)
2

Seconds

Minutes

Hours

The magnitude is the number of units to be clocked.
The
following list describes the magnitude values that are valid
for each type of unit. In no case can the magnitude exceed 24
hours.
I f unit = 0,1, or 2, the magnitude
value with a maximum of 15 bits.

can

If unit = 3, the magnitude can have
1440(10).

maximum

value

I f unit

maximum

value

4, the magnitude can have

any

positive

24 (10).
•

The schedule delta time is the difference in time from the
issuance of the RUN TASK directive to the time the process is
to be run. This time can be specified in the range from one
clock tick to 24 hours.

•

Hibernations that are caused by STOP directives (RECEIVE DATA
OR STOP, STOP, STOP FOR LOGICAL OR OF EVENT FLAGS, and STOP
FOR SINGLE EVENT FLAG) cannot be reactivated by the RUN TASK
directive.

4-47

DIRECTIVE DESCRIPTIONS

SDAT$
4.2.35

SDAT$ - SEND DATA

When an event flag is specified in the SEND
indicated flag is set for the sending process.

DATA

directive,

the

Macro Call:
SDAT$
buf
efn

tsk, buf [, ef n]
=

Address of 13-word data buffer
Event flag number

DSW Return Codes:
completion

IE.ADP
IE. SOP

DPB or data block is out of
Part
image's address space
DIC or DPB size is invalid

the

issuing

Notes:
executes a write Queue I/O Request system service on
• VAX/VMS
behalf of the process issuing the SEND DATA directive. The
I/O operation writes to a mailbox named RCVD followed
specified process name, that is, RCVDname.

the

•

The sending process must be in the same group as the receiving
process because protection allows the group write access to
the mailbox and denies access to the world.

•

The target process must be executing an image that had a name
specified at task-build time; that is, the image label block
must contain a task name. VAX/VMS uses the presence of the
task name as an indication that the image may receive data and
sets up the necessary mechanism.

•

A task image must be associated with common or group global
event flags to access flags in the common or group global
clusters (see Section 2.5).

•

Event flag conversion is as follows:
Cluster
Local
Common
Group global

VAX/VMS

RSX-llM
1 through 32
33 through 64
fi 5 th rough 90

4-48

32 through ~3
64 through 95
96 through 127

DIRECTIVE DESCRIPTIONS

SETF$
4.2.36

SETF$ -

SET EVENT FLAG

The SET EVENT FLAG directive instructs the system to set an
event flag and report the flag's previous value.

indicated

Macro Call:
SETF$

ef n

efn
Event flag number
DSW Return Codes:
IS.CLR
Flag was clear
IS. SET
Flag was already set

IE .ADP

IE. SDP

Part of the DPB is out of
address space
DIC or DPB size is invalid

the

issuing

image's

Note:
•

VAX/VMS executes a Set Event Flag system service on behalf
the image issuing the SET EVENT FLAG directive.

•

A task image must be associated with common or group global
event flags to access flags in the common or group global
clusters (see Section 2.5).

•

Event flag conversion is as follows:
Cluster

Local
Common
Group global

RSX-UM

VAX/VMS

1 through 32
33 through 64
65 through 96

4-49

32 through
n3
64 through 95
% th rough 127

DIRECTIVE DESCRIPTIONS

SFPA$
4.2.37

SFPA$ - SPECIFY FLOATING-POINT PROCESSOR EXCEPTION AST

The SPECIFY FLOATING-POINT PROCESSOR EXCEPTION AST directive instructs
the system either to enable or disable delivery of floating-point
processor exception ASTs.
When an AST service routine entry point address is specified,
future
floating-point proces$or exception ASTs occur for the issuing process,
and control is transferred to the indicated location at the time of
the AST's occurrence. When an AST service entry point address is not
specified, future floating-point processor exception ASTs do not occur
until the image issues a directive that specifies an AST entry point.
Macro Call:
SFPA$
ast

[ast]
AST service routine entry point address

DSW Return Codes:

rs.sue
IE.VPN
IE.ITS
IE.AST
IE.ADP
IE.SOP

Successful completion
Insufficient dynamic memory (SS$ INSFMEM)
AST entry point address is alrea~y unspecified
Directive was issued from an AST service routine
or ASTs are disabled
Part of the DPB is out of the
issuing image's
address space
DIC or DPB size is invalid

Notes:
•

The SPECIFY FLOATING-POINT PROCESSOR
dynamic memory.

•

VAX/VMS queues floating-point processor exception ASTs when a
floating-point processor exception trap occurs for the task.
No future floating-point processor exception ASTs are queued
for
the process until the first one queued has actually been
effected.

•

The floating-point processor exception AST service routine
entered with the task stack in the following state:
SP+l2
SP+lO
SP+06
SP+04
SP+02
SP+OO

EXCEPTION

AST

requires

Event flag mask word
PS of task prior to AST
PC of task prior to AST
DSW of task prior to AST
Floating exception code
Floating exception address

The image must remove the floating-point exception code and
address from the stack before an AST SERVICE EXIT directive is
executed.
•

This directive cannot be issued from an AST service routine or
when ASTs are disabled.

4-50

DIRECTIVE DESCRIPTIONS

SPND$S
4.2.38

SPND$S - SUSPEND

An image can suspend only the process
it is executing. The suspended process can be restarted by
process that issues a RESUME directive for it.
Macro Call:
SPND$ S
err

[err]
Error routine address

DSW Return Codes:

rs. sue

~il)l}:llI[1l111&~1itll!lt'li~i

IE .ADP

IE. SDP

Part of the DPB is out of the issuing image's
address space
DIC or DPB size is invalid

Notes:
•

VAX/VMS executes a Hibernate system service on behalf
process issuing the SUSPEND directive.

the

suspended process retains control of the system resources
• Aallocated
to it.
VAX/VMS makes no attempt to free these
resources.
•

•

If a SUSPEND directive is issued by an image that has
resume requests, the following occurs.

pending

The status returned is success.
The process remains active.
The wake-pending indicator is cleared.
•

A process can be resumed only by specifying its process name;
therefore, a process is not allowed to suspend itself unless
it has a process name.

•

A process that is hibernating because of a SUSPEND
cannot be reactivated by the UNSTOP TASK directive.

4-51

directive

DIRECTIVE DESCRIPTIONS

SPRA$
4.2.39

SPRA$ - SPECIFY POWER RECOVERY AST

The SPF.CIFY POWER RECOVERY AST
record either of the following:

directive

instructs

the

system

•

That power-recovery ASTs for the issuing process are required,
and the address to which to transfer control when a powerfail
recovery AST occurs

•

That power-recovery ASTs for the issuing process are no longer
required

When an AST service routine entry point address is specified, future
power-recovery ASTs occur for the issuing process. VAX/VMS transfers
control to the specified address whenever a powerfail recovery occurs.
When an AST service entry point address is not specified, future
power-recovery ASTs do not occur until an AST entry point is again
specified.
Macro Call:
SPRA$
ast

[ast]

= AST service routine entry point address

DSW Return Codes:

rs.sue
IE.ITS
IE.AST
IE.ADP
IE.SOP

Successful completion
AST entry point address is already unspecified
Directive was issued from an AST service routine
or ASTs are disabled
Part of the DPB is out of the issuing image's
address space
DIC or DPB size is invalid

Notes:
•

VAX/VMS executes a Set Power Recovery AST system service for
the image issuing the SPECIFY POWER RECOVERY AST directive.

•

ASTs are disabled while the AST service routine executes.
They remain disabled until the service routine issues an AST
SERVICE EXIT directive.

•

The process enters the powerfail AST service routine with
task stack in the following state:
SP+06,12 SP+04
SP+02
SP+OO
-

the

0
PS of process prior to AST
PC of process prior to AST
DSW of process prior to AST

No trap-dependent parameters accompany a power-recovery AST;
therefore, the AST SERVICE EXIT directive can be executed with
the stack in the same state as when the AST was effected.
•

This directive cannot be issued from an AST service routine or
when ASTs are disabled.

4-52

DIRECTIVE DESCRIPTIONS

SPWN$
4.2.40

SPWN$ - SPAWN

If the command line is not specified, the specified image is invoked
and executed by the subprocess;
its TI device is the TI of the parent
process.

Macro Call:
SPWN$

tnarne,,, [ugc], [ur~c], [efn], [east], [esb], [cmdlin],
[cmdlen], [unum], [dnam]

ef n
east
esb
cmdlin
cmdlen
unum
dnam

Event flag to be set when subprocess terminates
Address of termination AST routine
Address of exit status block, an
8-word
buffer
containing the exit status in the first word; the
other words are unused
Address of command line to be executed;
overrides
image name specified in tname
Length of command line
Unit number of TI device for process;
if omitted,
parent's TI is used
Device name of TI device for process;
if omitted,
parent's TI is used

DSW Return Codes:

IE.SOP

Part of the DPB, exit status block, or command,
is out of the issuing image's address space
DIC or DPB size is invalid

4-53

DIRECTIVE DESCRIPTIONS

SRDA$
4.2.41

SRDA$ - SPECIFY RECEIVE DATA AST

The SPECIFY RECEIVE DATA AST directive instructs the system to
either of the following conditions:

record

•

That receive-data ASTs for the issuing image are required, and
the address to which to transfer control when data has been
placed in the image's mailbox (RCVDprocessname)

•

That receive-data ASTs for the
required

issuing

task

are

longer

When the directive specifies an AST service routine entry point
address, receive-data ASTs for the image occur whenever data has been
placed in the image's mailbox (RCVDprocessname).
VAX/VMS transfers
control to the specified address.
When the directive omits an entry point address, VAX/VMS disables
receive-data ASTs for the issuing image. Receive-data ASTs do not
occur until the image issues another SPECIFY RECEIVE DATA AST
directive that specifies an entry point address.
Macro Call:
SRDA$
ast

[ast]
AST service routine entry point address

DSW Return Codes:

rs.sue
IE.ITS
IE.AST
IE.ADP
IE.SDP

Notes:
•

The task enters the receive-data AST service routine with
task stack in the following state:
SP+On,12 SP+04
SP+02
SP+OO
-

the

0
PS 0£ process prior to AST
PC of process prior to AST
DSW of process prior to AST

No trap-dependent parameters accompany a receive-data AST;
therefore, the AST SERVICE EXIT directive must be executed
with the stack in the same state as when the AST was effected.
•

This directive cannot be issued from an AST service routine or
when ASTs are disabled.

4-54

DIRECTIVE DESCRIPTIONS

implements the SPECIFY RECEIVE DATA AST through the
• VAX/VMS
use of the set AST enable QIO I/O function for an unsolicited
message to the mailbox.
When a message is sent to the
mailbox, an AST is given to the image. The AST is re-enabled
by a subsequent AST SERVICE EXIT directive.
•

Also ref er to the section in this chapter on the RECEIVE
directive.

4-55

DATA

DIRECTIVE DESCRIPTIONS

STLO$
4.2.42

STLO$ - STOP FOR LOGICAL OR OF EVENT FLAGS

The STOP FOR LOGICAL OR OF EVENT FLAGS directive instructs the system
to stop the execution of the issuing image until VAX/VMS sets one or
more of the indicated local event flags from one of the following
groups.
GRO
GRl

Flags 1 through 16
Flags 17 through 32

The process does not stop if any of the indicated flags is already set
when it issues the directive.
This directive cannot be issued from an AST service routine.
A process that is stopped because none of the indicated event flags is
set can be restarted only when one or more of the specified event
flags is set. Such a stopped process cannot become unstopped by means
of an UNSTOP TASK directive.
Macro Call:
STLO$

grp,msk

grp
msk

Event flag group
A 16-bit mask word

DSW Return Codes:

rs.sue
IE.AST

Successful completion
Directive was issued from an AST service routine

IE.ADP
IE.SOP

Part of the DPB is out of the issuing image's address
space
DIC or DPB size is invalid

Notes:
•

VAX/VMS executes a Wait for Logical OR of Event Flags system
service on behalf of the image issuing the STOP FOR LOGICAL OR
OF EVENT FLAGS directive.

•

A task image must be associated with common or group global
event flags to access flags in the common or group global
clusters (see Section 2.5).

•

Event flag conversion is as follows:
VAX/VMS

Cluster

RSX-llM

Local

1 through 32

4-56

32 through

DIRECTIVE DESCRIPTIONS

STOP$S
4.2.43

STOP$S - STOP

A process stopped by the STOP directive can be restarted only by an
UNSTOP TASK directive issued by one of its own ASTs or by another
process.
Macro Call:
STOP$S
DSW Return Codes:
IE.SET
IE.AST
IE.ADP
IE.SDP

Directive was issued from an AST service routine
Part of the DPB is out of the issuing image's address
space
DIC or DPB size is invalid

Notes:
•

VAX/VMS executes a Hibernate system service on behalf
process issuing the STOP directive.

the

stopped process retains control of the system resources
• Aallocated
to it.
VAX/VMS makes no attempt to free these
resources.
•

VAX/VMS maintains an indicator to determine whether any wake
requests have been issued for an active process. If the wake
pending indicator is set and the process issues a hibernate
request, the process remains active, and the wake pending
indicator is cleared. A subsequent hibernate request causes
the process to hibernate.
Thus, if a STOP directive is issued by a process
pending unstop requests, the following occurs:

that

has

The status returned is success.
The process remains active.
The wake pending indicator is cleared.
•

A process stopped by use of the STOP directive can be
restarted (by use of the UNSTOP TASK directive) only if its
process name is specified;
therefore, a process is not
allowed to stop itself unless it has a process name.

4-57

DIRECTIVE DESCRIPTIONS

STS.E$
4.2.44

STSE$ - STOP FOR SINGLE EVENT FLAG

The STOP FOR SINGLE EVENT FLAG directive instructs the system to stop
the execution of the issuing image until the specified local event
flag is set. If the flag is set when the directive is issued, image
execution continues.
This directive cannot be issued from an AST
service routine.
A process that is stopped because a specified event flag is not set
can be restarted only when that event flag is set. Such a stopped
process cannot be restarted by means of an UNSTOP TASK directive.
Macro Call:
STSE$

ef n

Event flag number

DSW Return Codes:

IE .ADP
IE.SDP

Part of the DPB is out of the issuing image's address
space
DIC or DPB size invalid

Notes:
•

VAX/VMS executes a Wait for Logical OR of Event Flags system
service in behalf of the image issuing the STOP FOR SINGLE
EVENT FLAG directive.

•

A task image must be associated with common or group global
event flags to access flags in the common or group global
clusters (see Section 2.5}.

•

Event flag conversion is as follows:
Cluster

Local
Common
Group global

RSX-llM

VAX/VMS

1 through 32
33 through 64
65 through 96

32 through n3
64 through 95
96 through 127

4-58

DIRECTIVE DESCRIPTIONS

SVOB$
4.2.45

SVOB$ - SPECIFY SST VECTOR TABLE FOR DEBUGGING AID

The SPECIFY SST VECTOR TABLE FOR DEBUGGING AID directive instructs the
system to record the address of a table of SST service routine entry
points for use by an intra-image debugging aid (ODT, for example).
To deassign the vector table, the parameters adr and len
from the macro call.

are

omitted

When an SST service routine entry is specified in both the table used
by the image and the table used by a debugging aid, the trap occurs
for the debugging aid, not for the image.
Macro Call:
SVDB$

[adr][,len]

adr
len

Address of SST vector table
Length of (that is, number of entries in) the table in
words

The vector table has the following format:
WD.
WD.
WD.
WD.
WD.
WD.
WD.
WD.

00
01

02
03

04
05
06
07

Odd address or nonexistent memory error
Memory protection violation
T-bit trap or execution of a BPT instruction
Execution of an IOT instruction
Execution of an illegal or reserved instruction
Execution of a non-RSX EMT instruction
Execution of a TRAP instruction
Not used

A table entry with a value of O indicates
process the corresponding SST.

that

the

image

will

DSW Return Codes:

rs.sue
IE.ADP
IE.SDP

Successful completion
Part of the DPB or table is out of the issuing
image's address space
DIC or DPB size is invalid

4-59

not

DIRECTIVE DESCRIPTIONS

SVTK$
4.2.46

SVTK$ - SPECIFY SST VECTOR TABLE FOR TASK

The SPECIFY SST VECTOR TABLE FOR TASK directive instructs the system
to record the address of a table of SST service routine entry points
for use by the issuing image.
To deassign the vector table, the parameters adr and len
from the macro call.

are

omitted

When an SST service routine entry is specified in both the table used
by the image and the table used by a debugging aid, the trap occurs
for the debugging aid, not for the image.
Macro Call:
SVTK$
adr
len

[adr] [, len]
Address of SST vector table
Length of (that is, number of entries in) the table in
words

The vector table has the following format:
WD.00
WD.01
WD.02
WD.03
WD.04

WD.05
WD.06

WD.07

Odd address or nonexistent memory error
Memory protection violation
T-bit trap or execution of a BPT instruction
Execution of an !OT instruction
Execution of an illegal or reserved instruction
Execution of a non-RSX EMT instructi-0n
Execution of a TRAP instruction
Not used

A table entry with a value of O indicates
process the corresponding SST.

that

the

image

will

DSW Return Codes:

rs .sue
IE.ADP
IE.SDP

Successful completion
Part of the DPB or table is out of the issuing
image's address space
DIC or DPB size is invalid

4-fiO

not

DIRECTIVE DESCRIPTIONS

USTP$
4.2.47

USTP$ - UNSTOP TASK

irect1ve restarts
a specified process that has stopped itself by means of either a STOP
directive or a RECEIVE DATA OR STOP directive. The UNSTOP TASK
directive does not restart processes stopped for an event flag.
If the UNSTOP TASK directive is issued to a process that is executing
an AST service routine and if that process was previously stopped by
either a STOP directive or by a RECEIVE DATA OR STOP directive, the
process becomes unstopped only when the execution of the AST service
routine has been completed.
Macro Call:
USTP$
tname

tname
VAX/VMS process name

DSW Return Codes:

IE.ADP
IE.SDP

Part of the DPB is out of the issuing image's address
space
DIC or DPB size is invalid

Notes:
•

VAX/VMS executes a Wake system service on
process issuing the UNSTOP TASK directive.

behalf

the

•

The process issuing an UNSTOP TASK directive must meet one
the following requirements:

It must have the same UIC as the process to be unstopped.
It must be in the same group as the process
unstopped, and it must have the group privilege.

Otherwise, a process needs no privileges to issue an UNSTOP
TASK directive.
It is the responsibility of the unstopped
process to determine whether it has been validly awakened.
•

VAX/VMS maintains an indicator to determine whether any wake
requests have been issued for an active process. If the
indicator is set and the process issues a hibernate request,
the process remains active and the indicator is cleared. A
subsequent hibernate request causes the process to hibernate.

4-61

DIRECTIVE DESCRIPTIONS

Thus, if a STOP directive is issued by a process
pending unstop requests, the following occurs:

that

has

The status returned is success.
The process remains active.
The wake-pending indicator is cleared.
•

If an UNSTOP TASK directive is issued for
active, the status returned is a success.
active.

4-02

an image that is
The process remains

DIRECTIVE DESCRIPTIONS

WSIG$S
4.2.48

WSIG$S - WAIT FOR SIGNIFICANT EVENT

Macro Call:
WS I G $ S

err

[e r r ]

Error routine address

DSW Return Codes:

rs. sue
IE.ADP
IE.SOP

Successful completion
Part of the DPB is out of the issuing image's
address space
DIC or DPB size is invalid

4-n3

DIRECTIVE DESCRIPTIONS

WTLO$
4.2.49

WTLO$ - WAIT FOR LOGICAL OR OF EVENT FLAGS

THE WAIT FOR LOGICAL OR OF EVENT FLAGS directive instructs the system
to block the execution of the issuing image until VAX/VMS sets an
indicated event flag from one of the following groups.
GR 0
GR 1
GR 2
GR 3
GR 4
GR 5

Flags
Flags
Flags
Flags
Flags
Flags

1 through
17 through
33 through
49 through
65 through
81 through

16
32
48
64
80
96

The process does not wait if any of the indicated flags is already set
when it issues the directive.
Macro Call:
W'l'LO$
grp
msk

grp,msk
=

Event flag group
A ln-bit flag mask word

DSW Return Codes:

IE.SDP

Part of the DPB
address space
DIC or DPB size is invalid

Notes:
•

VAX/VMS executes a Wait for Logical OR of Event Flags system
service on behalf of the image issuing the WAIT FOR LOGICAL OR
OF EVENT FLAGS directive.

•

A task image must be associated with common or group global
event flags to access flags in the common or group global
clusters (see Section 2.5).

•

Event flag conversion is as follows:
Cluster

Local
Common
Group global
•

VAX/VMS

RSX-llM

1 through 32
33 through n4
n5 through 96

3'2 through fl3
n4 through 95
96 th rough 127

The DSW status IE.IEF is returned if an image that does not
have a common event flag cluster associated with it attempts
to wait for flags 33 through n4.

4-64

DIRECTIVE DESCRIPTIONS

WTSE$
4.2.50

WTSE$ - WAIT FOR SINGLE EVENT FLAG

The WAIT FOR SINGLE EVENT FLAG directive instructs the system to block
the execution of the issuing image until the indicated event flag is
set. If the flag is set when the directive is issued, image execution
continues.
Macro Call:
WTSE$

ef n

Event flag number

DSW Return Codes:

Is.sue

Successful completion

IE. SDP

address space
DIC or DPB size is invalid

Notes:
•

VAX/VMS executes a Wait for Logical OR of Event Flags system
service in behalf of the image issuing the WAIT FOR SINGLE
EVENT FLAG directive.

•

A task image must be associated with common or group global
event flags to access flags in the common or group global
clusters (see Section 2.5).

•

Event flag conversion is as follows:

Cluster
Local
Common
Group global

RSX-llM

VAX/VMS

1 through 32
33 through n4
n5 through 96

32 through n3
64 th rough 95
96 through 127

4-115

CHAPTER 5
I/O DRIVERS

VAX/VMS images request services directly from I/O drivers and ACPs by
issuing Queue I/O Request macro instructions. Each macro instruction
consists of the following types of arguments:
•

An I/O function code

•

Function-independent parameters, for example, I/O channel
event flag number

•

Function-dependent parameters Pl through P6

and

VAX/VMS I/O function code names have the following format:
IO$ function
Many function codes have subfunction modifiers that can be associated
with them. Subfunction modifier names have the following format:
IO$M subfunction
The following are examples of VAX/VMS function codes
modifiers.

and

subfunction

IO$ WRITELBLK
IO$-READPROMPT!IO$M NOFILTR
IO$-READVBLK
IO$-DELETE!IO$M DELETE
When an RSX-llM image running under VAX/VMS issues a QUEUE I/O REQUEST
directive, VAX/VMS determines the equivalent native function and
executes a Queue I/O Request system service on behalf of the image.
The I/O request is processed by the VAX/VMS I/O system and the
function is performed by a standard VAX/VMS device driver or ACP.
Usually, RSX-llM I/O requests correspond to similar VAX/VMS requests.
As a result, the ~SX-llM image is not aware of any differences in the
I/O systems. However, if an image issues an I/O request that depends
on characteristics of the RSX-llM I/O system that are not present in
the VAX/VMS I/O system, the requested I/O operation may not occur
exactly as expected. In that event, the user should consult this
chapter.
Each
RSX-llM
I/O
request
consists
of
a
function
code,
function-independent parameters, and function-dependent parameters.
When VAX/VMS receives a QUEUE I/O REQUEST directive, it forms the
equivalent VAX/VMS arguments for each RSX-llM parameter specified in
the directive. Because VAX/VMS issues queue I/O requests using the
VAX/VMS I/O system, it must convert RSX-llM queue I/O requests to the
native format for processing by the appropriate driver or ACP.

5-1

I/O DRIVERS
VAX/VMS handling of RSX-llM function-independent parameters, for
example, efn, lun, and ast, is described in Chapters 2 and 3 and in
the description of the QUEUE I/O REQUEST directive in Chapter 4. This
chapter describes how VAX/VMS handles I/O function codes and I/O
function-dependent parameters.

5.1

SUPPORTED DEVICES

VAX/VMS supports RSX-llM I/O functions for devices supported by both
RSX-llM and VAX/VMS;
that is, for disks, terminals, line printers,
card readers, magnetic tapes, and the null device.
The VAX/VMS I/O
User's Guide lists the devices supported by VAX/VMS.
If an RSX-llM image performs I/O to a device that VAX/VMS does not
support and that does not require special-case software, the I/O
request is handled as if it specified a disk device. The I/O function
code and parameters (Pl through P6) are handled just as they are for
disk. No subfunction bits are used.

5.2

GET LUN INFORMATION DIRECTIVE

The GET LUN INFORMATION directive returns the same device-independent
information under VAX/VMS as it does under RSX-llM Version 3.2. The
format of the information returned for all devices is presented in the
description of the GET LUN INFORMATION directive in Chapter 4. The
VAX/VMS I/O User's Guide describes the format of the device-dependent
information returned.

5.3

STANDARD I/O FUNCTIONS

The standard RSX-llM I/O functions -- attach, detach, and cancel I/O;
read and write virtual block; and read and write logical block -- are
supported for all devices in VAX/VMS.
The sections that follow
provide additional information about attach, detach, and cancel I/O.

5.3.1

Attach and Detach I/O Device (IO.ATT and IO.DET)

VAX/VMS categorizes devices as shareable and
nonshareable.
A
shareable device, for example, a disk, can be accessed by many users
without affecting the integrity of the data.
Nonshareable devices,
for example, terminals, allow access from only one process at a time.
When an image assigns a channel to a nonshareable device, VAX/VMS
implicitly allocates the device for exclusive use by the process. In
the RSX-llM sense, the system attaches the device for the process.
Because VAX/VMS performs implicit allocation, images do not have to
explicitly allocate and deallocate nonshareable
devices
during
execution.
If an image must have exclusive access to a shareable
device can be allocated in either of two ways:

device,

the

By an image issuing an Allocate Device system service

By a user typing an ALLOCATE command to a command interpreter

5-2

I/O DRIVERS
Use of the ALLOCATE command has an advantage over use of the Allocate
Device system service. It eliminates the need for error recovery by
the image if the device is not available for allocation.
Tasks
running in RSX-llM frequently attach terminals and other devices to
prevent another task from using them. These devices are shareable in
an RSX-llM system. When an RSX-llM image running under VAX/VMS issues
a QUEUE I/O REQUEST to attach a device, VAX/VMS performs no operation
and returns a success status to the image. If the target device is
nonshareable, VAX/VMS allocates the device when the image assigns a
LUN to it.
In effect, therefore, the device is attached. If the
device is shareable, it remains unallocated after the directive status
is returned. When an RSX-llM image requires allocation of a shareable
device, the device must be allocated from a terminal or an indirect
command file by using an ALLOCATE command.
The RSX-llM function code IO.ATT and IO.DET have meaning for terminals
under VAX/VMS, as described in Section 5.8, uTerminal Driver." For
example, issuing an attach or detach request causes a cancel CTRL/O
function.

5.3.2

Cancel I/O Requests (IO.KIL)

When an RSX-llM image issues a kill I/O request for a VAX/VMS device,
VAX/VMS executes a Cancel I/O on Channel system service. This system
service cancels all I/O issued from the designated channel.
This
differs from the RSX-llM approach in that RSX-llM causes all I/O from
the issuing task to the device to be canceled.
When a cancel I/O
request is issued for a disk device, no operation is performed.
VAX/VMS returns a success status to the image.
When the Cancel I/O on Channel system service executes, it notifies
the driver immediately. Queued I/O requests are canceled immediately;
however, I/O that the driver is currently processing
is
not
necessarily canceled.

5.4

I/O STATUS BLOCK AND STATUS RETURNS

When VAX/VMS completes an I/O operation, it returns a code indicating
the status of the request in an I/O status block. When an RSX-llM
image issues a request, VAX/VMS returns status information in an I/O
status block that has the standard RSX-llM format, as illustrated in
Figure 5-1.

Word 0

Word 1

Figure 5-1

Byte 1

Byte 0

0 except for
terminal read

Status code

Number of bytes transferred

Format of RSX-llM I/O Status Block under VAX/VMS

The return code can be rs.sue or any of the error status codes listed
in Table 5-1.
The status code rs.sue corresponds to the VAX/VMS
status code SS$ NORMAL. VAX/VMS equivalents for RSX-llM error codes
also are provided in Table 5-1. The high-order byte of word O always

5-3

I/O DRIVERS

contains a zero except in the case of terminal I/O read requests. For
a terminal read request, that byte indicates the line terminator, as
described in Section 5.8.14.
The second word of the I/O status block contains the number
read or written.

bytes

Table 5-1
I/O Status Return Codes
DSW Code

VAX/VMS Code

IE.ABO

SS$ ABORT

An I/O request was canceled before the
operation was completed, or a network
link was broken.

SS$ CANCEL

An I/O request was canceled before
operation was completed.

IE.ALN

SS$ FILALRACC

A DECnet logical link
or was pending.

IE. BAD

SS$ BADFILENAME

A filename contained illegal characters
or was longer than nine characters.

SS$ BADPARAM

A call to a network or file
contained invalid parameters.

IE.BCC

SS$ DATACHECK

A data check found a mismatch
disk data and memory data.

IE.BDR

SS$ BADIRECTORY

A file specified as a directory either
was
not
a directory or contained
invalid data.

IE. BHD

SS$ BADFILEHDR

A file header contained invalid data;
for example, the structure was not
consistent or the storage map indicated
free blocks.

SS$ FILESTRUCT

The file structure on an
accessed
volume was invalid for the called ACP.

IE. BLK

SS$ ILLBLKNUM

The logical block number specified
a file did not exist on disk.

for

IE. BVR

SS$ BADFILEVER

A file version number was greater

than

Meaning

already

the

existed

ACP

between

327 27.

SS$ TOOMANYVER

The maximum number of versions for a
file
already
existed and all had
greater version
numbers
than
the
specified version number.

IE.CKS

SS$ BADCHKSUM

The checksum
invalid.

IE .CLO

SS$ FILELOCKED

A process attempted to access a
file.

file

header

was

locked

(continued on next page)

5-4

I/O DRIVERS

Table 5-1 (Cont.)
I/O Status Return Codes
Meaning

DSW Code

VAX/VMS Code

IE .CNR

SS$ REJECT

A request to connect to an object at
remote network node failed.

IE.DAA

SS$ DEVALLOC

An allocate request specified a device
already allocated to another user.

IE.DAO

SS$ BUFFEROVF

A buffer was not large enough for a
string output by a system service; the
string was truncated.

SS$ DATAOVERUN

A buff er was not large enough for
output by a system service.

data

SS$ MBTOOSML

A mailbox was too small for
to it.

sent

IE .DFU

SS$ DEVICEFULL

A device was full or did not have
enough contiguous blocks to fill a
request.

IE.DNA

SS$ DEVNOTALLOC

A deallocate request specified a device
that was not allocated.

SS$ VOLINV

The volume-valid bit
volume was not set.

IE.DNR

SS$ DEVNOTMOUNT

A dismount request specified
that was not mounted.

IE.DSQ

SS$_ EXDISKQUOTA

A process exceeded its disk quota.

IE.DUN

SS$ NOTFILEDEV

A
file
specification
contained
references to a directory or a file on
a device that was not file-structured.

IE.DUP

SS$ DUPFILENAME

A specified file already existed in the
specified directory.

IE .EOF

SS$ ENDOFFILE

The end of a file was reached.
This
was an EOF mark on a tape, an EOF card
in a card reader, an empty mailbox, or
the end of virtual memory.

IE .EOT

SS$ BEGOFFILE

A backspace operation
beginning of a file.

SS$ ENDOFTAPE

The end-of-tape mark was encountered on
a tape.

IE.EOV

SS$ ENDOFVOLUME

The end of a volume was encountered.

IE.EXP

SS$ FILNOTEXP

A file could not be written or deleted
because
it
had
not
reached its
expiration date.

for

data

requested
a

device

reached

the

(continued on next page)

5-5

I/O DRIVERS
Table 5-1 (Cont.)
I/O Status Return Codes
DSW Code

VAX/VMS Code

IE. FHE

SS$ CRTLERR

A hardware controller failed during
I/O operation.

SS$ DRVERR

A device driver failed
operation.

I/O

SS$ UNSAFE

A device driver was unusable.

IE.HFU

SS$ HEADERFULL

A file header map was full
extension was inhibited.

and

its

IE. !ES

SS$ BADESCAPE

A terminal escape sequence was invalid.

IE. IFC

SS$ ILLCNTRFUNC

The control function specified
ACP was invalid.

for

SS$ ILLIOFUNC

The function code specified for
explicit I/O request was invalid.

IE.LCK

SS$ ACCONFLICT

The access protection for a file
not allow a requested access.

did

IE.NBK

SS$ DIRFULL

A file could not be created because the
specified directory was full.

IE .NDR

SS$ NOLINKS

A logical network link could not be
created because no more slots were
available.

IE .NLN

SS$ FILNOTACC

No file had been accessed on a channel
that
was
specified
for
an
I/O
operation.

IE.NNL

SS$ NOTNETDEV

A device specified for a network I/O
operation was not a network device.

IE.NNN

SS$ NOSUCHNODE

A specified network node did not exist.

IE .NOD

SS$ ACPVAFUL

A file ACP could not access a volume
because it had no more virtual memory
for volume service.

SS$_EXQUOTA

A process attempted to exceed its limit
or quota for a resource.

SS$ INSFMEM

More system dynamic memory was required
than was avail~ble. ·

SS$ INSFWSL

A process required more pages in
working set than it was allowed.

Meaning

'--------------·---····--....._ ___

.~-------

during

its

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

(continued on next page)

5-fi

I/O DRIVERS

Table 5-1 (Cont.)
I/O Status Return Codes
DSW Code

VAX/VMS Code

Meaning

IE.NSF

SS$ NOMOREFILES

No more files matching a
wildcard
specification existed;
at least one
matching file was previously found.

SS$ NOSUCHFILE

A specified file did not exist.

SS$ DEVOFFLINE

A device went offline.

SS$ MEDOFL

A requested device had
mounted on it (such as
disk).

IE.PES

SS$ PARTESCAPE

A
terminal
escape
sequence
was
truncated at the end of its buffer;
the remainder of the sequence
was
written in the type-ahead buffer.

IE. PR!

SS$ NOPRIV

A process requested initialization of a
volume
that
it did not have the
privilege to write.

IE.RER

SS$ FCPREADERR

An error occurred in reading
file
control data (such as a directory).

SS$ FCPREWNDERR

An error
volume.

SS$ MBFULL

A mailbox could not accept
message because it was full.

SS$ VECINUSE

The control-C vector for a process was
already
in
use
by a controlling
process.

IE.SNC

SS$ FILENUMCHK

The index file for a
invalid data.

IE. SPC

SS$ ACCVIO

A process attempted to access memory
outside its virtual address space. The
PC contains the address of the invalid
instruction.

IE .SQC

SS$ _FILESEQCHK

The file sequence number in a file
header
was invalid;
the directory
entry pointed to an obsolete or deleted
file.

IE.TMM

SS$ TOOMUCHDATA

A network interrupt message
more than.16 bytes of data.

IE.TMO

SS$ TIMEOUT

An input operation was not completed
within the specified timeout period.

IE.VER

SS$ PARITY

A device-dependent error occurred.

IE.OFL

IE.RSU

occurred

no
medium
a tape or a

rewinding

volume

another

contained

(continued on next page)

5-7

I/O DRIVERS
Table 5-1 (Cont.)
I/O Status Return Codes

·--DSW Code

VAX/VMS Code

IE.WAT

SS$ BADATTRIB

An invalid attribute was specified
a read or write using a file ACP.

IE.WER

SS$ FCPSPACERR

An I/O error occurred while a file
co ntrol primitive was skipping spaces
wi thin or among files.

SS$ FCPWRITERR

An I/O error occurred while
co ntrol primitive was writing.

file

IE.WLR

SS$ WRITLCK

Th e hardware write-lock switch was
on a requested disk.

set

IS.PND

None

An I/O request is pending.

rs.sue

SS$ NORMAL

An operation succeeded.

5.5

Meaning

for

DISK DRIVER

Table 5-2 provides the correspondence between
codes and VAX/VMS disk function codes.

RSX-llM

disk

function

Table 5-2
Disk Function Code Correspondence
Function

RSX-llM Code

VAX/VMS Code or Action

Attach Device

IO.ATT

No operation

Detach Device

IO.DET

No operation

Cancel I/O Requests

IO.KIL

No operation

Read Logical Block

IO.RLB

IO$ READLBLK

Write Logical Block

IO. WLB

IO$ WRITELBLK

Read Virtual Block

IO.RVB

IO$ READVBLK

Write Virtual Block

IO.WVB

IO$ WRITEVBLK

Read Physical Block

IO.RPB

IO$ READPBLK

Write Physical Block

IO.WPB

IO$ WRITEPBLK

Write Physical Block
(delete data mark)

IO.WDD

Not supported

Load Overlay

IO. LOV

Special form of IO.RLB
performed only on OV
(overlay device); An
IO.RVS is performed
on LUNs not assigned
to OV.

IO.STC

IO$ PACKACK

Pack Acknowledge
---------------·--·---

-~····--··---·-·-··--·"·- _ _ _. . & . . . - . _ ._ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ ,

5-8

I/O DRIVERS

Table 5-3 provides the correspondence
parameters to VAX/VMS arguments.

RSX-llM

function-dependent

Table 5-3
Disk Parameter Correspondence
Parameter Function

RSX-llM Pn

VAX/VMS Pn

Starting buffer address
(stadd)

Buffer size (size)

High block number
(bklh)

P3 (high half of longword)

Low block number (blkl)

P3 (low half of longword)

5.6

MAGNETIC TAPE DRIVER

Table 5-4 provides the correspondence between RSX-llM magnetic
function codes and VAX/VMS magnetic tape function codes.

tape

Table 5-4
Magnetic Tape Function Code Correspondence
Function

RSX-llM Code

VAX/VMS Code or Action

-Attach Device

IO .ATT

No operation

Detach Device

IO.DET

No operation

Cancel I/O Requests

IO.KIL

Cancel I/O on Channel
system service

Read Logical Block

IO.RLB

IO$ READLBLK

Write Logical Block

IO .WLB

IO$ WRITELBLK

Read Virtual Block

IO.RVB

IO$ READVBLK
-

Write Virtual Block

IO.WVB

IO$ ViJRITEVBLK

Write End-of-File Mark

IO. EOF

IO$ WRITEOF

Read Logical Block
Reverse

IO.RLV

IO$ READPBLK!IO$M REVERSE

Rewind Unit

IO.RWD

IQ$ REWIND

Rewind and Turn Unit
Off Line

IO.RWU

IO$ REWINDOFF

(continued on next page)

5-9

I/O DRIVERS
Table 5-4 (Cont.)
Magnetic Tape Function Code Correspondence
Function

RXS-llM Code

VAX/VMS Code or Action

Mount Tape and Set
Characteristics

IO.SMO

IO$ SETMODE (only parity
and-density can be set)

Sense Tape Characteristics

IO.SEC

IO$ SENSEMODE

Space Blocks

IO .SPB

IO$ SPACERECORD

Space Files

IO.SPF

Set Tape Characteristics

IO.STC

IO$ SPACEFILE
IO$ SETMODE (only parity
and - density can be set)

~-·-·-·

Table 5-5 provides the correspondence
parameters to VAX/VMS arguments.

.....

RSX-llM

function-dependent

Table 5-5
Magnetic Tape Parameter Correspondence

RSX-llM Pn

Parameter Function
"------~-··

VAX/VMS Pn

,. .......,.,.,. ··--·-·--1!---·" ~·----

Starting buff er address
(stadd)

Buff er size (size)

Characteristic bits ( cb)
of IO.SMO and IO.STC

Number of blocks to space
past (nbs) of IO. SPB

Number of EOFs to space
past (nes) of IO.SPF

5.7

LINE PRINTER DRIVER

Table 5-6 provides the correspondence between RSX-llM line printer
function codes and VAX/VMS function codes or resultant action.

5-10

I/O DRIVERS
Table 5-6
Line Printer Function Code Correspondence
Function

RSX-llM Code

VAX/VMS Code or Action

Attach Device

IO.ATT

No operation

Detach Device

IO.DET

No operation

Cancel I/O Requests

IO.KIL

Cancel I/O on Channel system
service

Write Logical Block

IO.WLB

IO$ WRITELBLK

Write Virtual Block

IO.WVB

IO$ WRITEVBLK

Write Physical Block

IO.WPB

IO$_WRITEPBLK

Table 5-7 provides the correspondence
parameters to VAX/VMS arguments.

RSX-llM

function-dependent

Table 5-7
Line Printer Parameter Correspondence
Parameter Function

RSX-UM Pn

VAX/VMS Pn

Starting buff er address
(stadd)

Buffer size (size)

P2.

Vertical format control
character (vf c)

When using VAX/VMS line printers, keep in mind the following points:
•

VAX/VMS line printers are not shareable.
VAX/VMS implicitly
allocates a line printer when a channel is assigned.

•

VAX/VMS line printers normally are spooled. A spooled printer
is allocated to the print symbiont. VAX/VMS does not allow a
process to allocate a spooled device unless it has the
privilege to do so. An RSX-llM image is not allowed exclusive
use of a spooled device (for example, printer) unless the
~rocess in which it is running has the necessary privilege and
the ALLOCATE command has been issued to reserve the device
prior to image execution.

•

If a printer is allocated or not spooled, the RSX-llM image's
IO.WLB and IO.WVB requests for it produce exactly the same
results as in the RSX-llM operating system.

5-11

I/O DRIVERS

5.8

•

See Section 3.10, "Spooled Devices," for a discussion of the
requirements for issuing IO.WLB and IO.WVB requests to a
spooled device.

•

If an RSX-llM image issues a GET LUN INFORMATION directive for
a spooled device, the information returned is that for the
intermediate device.

TERMINAL DRIVER

Table 5-8 provides the correspondence of RSX-llM function codes to
VAX/VMS functions.
Table 5-9 provides the correspondence of the
RSX-llM function-dependent parameters Pl through P6 to their VAX/VMS
equivalents for terminal devices. Table 5-10 lists the subfunction
bits applicable for each RSX-llM function code and provides notes
describing VAX/VMS handling of these subfunctions for terminals.
VAX/VMS places restrictions on the I/O functions that can be performed
on TI, CO, and CL because they are mapped to process-permanent files.
It
places
the
same
restrictions
on
I/O
to
user-created
process-permanent
files.
Section
5.8.15, "Programming Hints,"
describes these restrictions.
Table 5-8
Terminal Function Code Correspondence
Function

RSX-llM Code

VAX/VMS Code or Action

Attach Device

IO.ATT

Terminal not attached;
forces cancel CTRL/O
on next write

Detach Device

IO. DET

Terminal not detached;
forces cancel CTRL/O
on next write

Cancel I/O Requests

IO.KIL

Cancel I/O on Channel
system service

Read Logical Block

IO.RLB

IO$ READLBLK

Write Logical Block

IO. WLB

IO$ WRITELBLK

Read Virtual Block

IO. RVB

IO$ READVBLK

Write Virtual Block

IO.WVB

IO$ WRITEVBLK

Read Physical Block

IO. RPB

Write Pass All

IO. WAL

IO$ WRITEPBLK

Read Logical Block
after Prompt

IO .RPR

IO$ READPROMPT

Get Multiple Characteristics

SF .GMC

Get I/O Channel Device
Information
system
service

Set Multiple Characteristics

SF.SMC

IQ$

Get Terminal Support

IO .GTS

Standard data returned
-· --

·-~-·

5-12

IO$ READPBLK
-

- SETMODE

I/O DRIVERS
Table 5-9
Terminal Parameter Correspondence
Parameter Function

RSX-llM Pn

VAX/VMS Pn

Starting buffer address
(stadd)

Buffer size (size)

Vertical format control
character (vfc) on write

p4l

Timeout count (tmo) on
read with prompt

Prompt address (pradd) for
read with prompt

Prompt size (prsize) for
read with prompt

Vertical format control
character (vfc) for read
with ,prompt

none

1. For all read functions except IO.RPB and IO.RST, the VAX/VMS P4
parameter specifies RETURN, ESCAPE, and CTRL/Z as terminators.
For IO.RPS, no characters are terminators. For IO.RST, P4 is O
specifying that all characters with a value less than an ASCII
space are terminators except form feed, vertical tab, backspace,
delete, and horizontal tab.
NOTE
The remaining device-specific function
codes are the equivalent of the logical
OR of a subfunction bit and one of the
standard function codes IO.ATT, IO.RLB,
or IO.WLB. See Table 5-10, "Subfunction
Bit Correspondence."

5-13

I/O DRIVERS
Table 5-10
Subfunction Bit Correspondence

APPLICABLE SUBFUNCTION BITS

x = Corresponds directly to VAX/VMS function.
n • Indicates correspondingly-numbered note.
EQUIVALENT WITH
SUBFUNCTION BIT

FUNCTION

TF.AST TF.BIN TF.CCO TF.ESQ TF.RAL TF.RNE TF.RST TF.WAL TF.WBT TF.XOF

STANDARD FUNCTIONS:
IO.ATT

IO.DET
IO.KIL
IO.RLB

IO.RVB

4·

IO.RPB
IO.WLB

IO.WVB

IO.WPB
DEVICE-SPECIFIC FUNCTIONS:
IO.ATA

IO.ATT!TF.AST
(see Note 1)

IO.cco

IO.WLB!TF.CCO

SF.GMC

IO.GTS

...

IO.RAL

IO.RLB!TF.RAL
(see Note 3)

IO.RNE

IO.RLB!TF.RNE

IO.RPR

x
3

.•
...---j

--·--

IO.RLB!TF.RST

IO.RST

x
x

SF.SMC
IO.WAL

IO.WLB!TF.WAL

IO.WBT

IO.WLB!TF.WBT
(See Note 2)

--- ----········-·- .

NOTES:

No attach performed.

Subfunction bit ignored for one of the following reasons.

Enables for CTRL/C ASTs only.

See Section 5.8.1.

Function

TF.ESQ, TF.XON

These are characteristics of the terminal line and cannot be
controlled on a per-request basis.

TF.WBT

The write breakthrough function is not supported in VAX/VMS.
See Section 5.8.8.

TF.BIN

Function is not supported in VAX/VMS.

Sets the VAX/VMS function modifier IO$M_NOFILTR.

RSX-llM virtual functions do not accept these subfunction bits.

5-14

See Section 5.8.4.1.

I/O DRIVERS
5.8.1

IO.ATT Function

When an RSX-llM image uses the IO.ATT function for a terminal, VAX/VMS
performs no operation to alter the attached/detached status of the
terminal, as described in Section 5.3.1. VAX/VMS does, however, issue
a request to the terminal driver to cancel CTRL/O on the next
operation to the terminal if that operation is a write.
The VAX/VMS
terminal
driver
subfunction
modifier
to
cancel
CTRL/O
is
IO$M CANCTRLO. The RSX-llM terminal driver also forces a cancel
CTRL7o (TF.CCO) on a write operation that follows an attach operation.
An IO.ATT function issued for TI, co, or CL becomes a no-op.

5.8.1.1 IO.ATT!TF.AST and IO.ATA Functions - ~n VAX/VMS, an image can
enable itself to receive an AST unsolicited characters and CTRL/Cs
from the terminal. When the AST occurs, the image can respond to the
unsolicited character or CTRL/C.
The'RSX-llM function codes IO.ATT!TF.AST and IO.ATA are equivalent.
When an RSX-llM image executing in VAX/VMS issues either of these
codes, VAX/VMS issues a request to the terminal driver to enable the
image for an unsolicited character or CTRL/C AST, depending on the
values of parameters Pl and P3, respectively.

5.8.1.2 IO.ATT!TF.ESQ Function - In VAX/VMS, certain features that
are characteristic of a terminal line are set by issuing a set
terminal mode request (IO$ SETMODE) to
the
driver.
Terminal
characteristics cannot be altered for the duration of an I/O request
by specifying a modifier to the request; nor can they be modified as
a function of terminal allocation. The ability to recognize escape
sequences on a terminal line is a characteristic of the terminal and
must be set using IO$_SETMODE or a set command.
In RSX-llM, the subfunction bit TF.ESQ is used with either of the
attach function codes (IO.ATT or IO.ATA) to indicate that the image
recognizes any escape sequences generated at the designated terminal.
When VAX/VMS receives an I/O request containing the TF.ESQ subfunction
from an RSX-llM image, it ignores tha~ subfunction bit. The terminal
characteristics remain unaltered.
To enable for escape sequences, an RSX-llM image should
multiple characteristics request (SF.SMC).

5.8.2

issue

set

IO.DET Function

When an RSX-llM image uses the IO.DET function for a terminal, VAX/VMS
performs no operation to alter the attached/detached status of the
terminal, as described in Section 5.3.1. VAX/VMS does, however, issue
a request to the terminal driver to cancel CTRL/O on the next
operation to the terminal if that operation is a write.
The VAX/VMS
terminal
driver
subfunction
modifier
to
cancel
CTRL/O
is
IO$M CANCTRLO. The RSX-llM terminal driver also forces a cancel
CTRL7o (TF.CCO) on a write operation that follows a detach operation.
An IO.DET function issued for TI, co, or CL becomes a no-op.

5-15

I/O DRIVERS
5.8.3

IO.KIL Function

An IO.KIL function issued for TI, CO, or CL becomes a no-op.

5.8.4

IO.RLB, IO.RAL, IO.RNE, IO.RST, and IO.RTT Functions

The function codes IO.RLB, IO.RAL, IO.RNE, and
IO.RST all
allow an
image
to read a logical block from a terminal.
When VAX/VMS receives
a read-logical-block request from an RSX-llM
image,
it
issues
an
IO$ READLBLK
request on behalf of
the
image.
There is a direct
correspondence between IO.RLB and IO$ READLBLK.
The RSX-llM function
codes IO.RAL, IO.RNE, and IO.RST are the equivalents of the logical OR
of IO.RLB and a subfunction bit.
The
following
sections describe
VAX/VMS handling of subfunction bits
used with read-logical-block
requests.

5.8.4.1
IO.RLB!TF.RAL and IO.RAL - In VAX/VMS, the default
terminal
driver operation on a
read
request
is to intercept and interpret
control characters, for example,
TAB,
CTRL/R,
CTRL/U,
and DELETE.
However,
a
native
image has
two options for
restricting
the
interception of control characters by the driver.
•

It can specify the subfunction modifier IO$M NOFILTR on a read
function
(either
IO$ READLBLK,
I3$ READVBLK,
or
IO$ READPROMPT)
to prevent- the driver
froi
intercepting
CTRL/U, CTRL/R, or DELETE.

•

It can issue a read-physical-block (IO$ READPBLK)
request
prevent the driver from interpreting any characters.

Normally, an RSX-llM image that issues a read-passing-all-data request
actually wants
to
receive only a
subset of the possible control
characters;
that is, it wants to receive CTRL/U, CTRL/R, and DELETE.
As a result, when VAX/VMS receives an IO.RLB!TF.RAL or IO.RAL request
from
an
RSX-llM
image,
it
issues
a
request
specifying
IO$ READLBLK!IO$M NOFILTR on behalf of the image.
The VAX/VMS equivalent of the RSX-llM
read-passing-all-data
function
is
read physical block
(IO$ READPBLK).
IO$ READPBLK corresponds
directly to the RSX-llM function code IO.RPB.
IO.RPB has been added
to
the function codes that can be issued by an RSX-llM image to allow
execution of the read-passing-all-data
function
under VAX/VMS.
An
RSX-llM image that a read-passing-all-data function under VAX/VMS must
be modified to issue an IO.RPB.
An image
issuing
IO.RPB under
the
RSX-llM operating system runs without receiving an error;
that is,
IO.RPB is a legal function.
NOTE
In RSX-llM,
an
IO.RPB
request
is
equivalent to an IO.RLB request with a
subfunction bit set.
IO.RAL or
IO.RPB
work
on
both
VAX/VMS and RSX-llM
systems.
VAX/VMS requires the image to have the appropriate privilege to read a
physical block.

s-10

I/O DRIVERS

5.8.4.2 IO.RLB!TF.RNE and IO.RNE Functions - The RSX-llM function
codes IO.RLB!TF.RNE and IO.RNE are equivalent. Either one corresponds
directly to the VAX/VMS function code IO$ READLBLK or IO$ READVBLK
with a no echo function modifier {IO$M_NOECHO).

5.8.4.3 IO.RLB!TF.RST and IO.RST Functions - The RSX-llM function
codes IO.RLB!TF.RST and IO.RST are equivalent. Either one corresponds
directly to the VAX/VMS function code IO$ READLBLK with a function
modifier of IO$M TRMNOECHO and a record-termination parameter {P4) of
O. IO$M TRMNOECHO prevents echoing of the line terminator. A record
terminatTon parameter of 0 causes all characters with a value less
than an ASCII space to be terminators except form feed, vertical tab,
backspace, and horizontal tab.

5.8.4.4 IO.RLB!TF.RTT and IO.RTT Functions - The RSX-llM function
codes IO.RLB!TF.RTT and IO.RTT are equivalent. Either one corresponds
directly to the VAX/VMS function code IO$ READVBLK with a function
modifier of IO$M TRMNOECHO and a record-termination parameter P4.

5.8.5

IO.RPR Function

The IO.RPR function code corresponds directly to
the
VAX/VMS
IO$ READPROMPT function code.
However, the RSX-llM P6 parameter
{vertical control character) is ignored.
VAX/VMS handling of the
subfunction bits TF.RAL, TF.RNE, and TF.RST with IO.RPR is exactly the
same as it is for IO.RLB.
VAX/VMS does not support use of the
subfunction b~t TF.BIN.
VAX/VMS also ignores the subfunction bit
TF.XOF if it is specified.
If an IO. R~ 1~,.,.' ;function is issued for TI, CO, or CL and these
correspond to process permanent files, the prompt is ignored.

devices

5.8.5.1 IO.RPlUTF.XOF Function - In VAX/VMS, certain features that
are
characteristic
of a terminal line are set by issuing a
set-terminal-mode request {IO$ SETMODE) to the driver. A subfunction
modifier
indi~ates
the characteristic to be changed.
Terminal
characteristics cannot be altered for the duration of an I/O request
by specifying a modifier to the request; nor can they be modified as
a function of terminal allocation. The ability to control XON/XOFF on
a terminal line is a characteristic of the terminal and must be set
using IO$_SETMODE.
In RSX-llM, the subfunction bit TF.XOF is used with IO.RPR to control
XON/XOFF at the designated terminal. When VAX/VMS receives an I/O
request containing the TF.XOF subfunction from an RSX-llM image, it
ignores that subfunction bit.
The terminal characteristics remain
unaltered.
To control XON/XOFF, an RSX-llM image
characteristics request {SF.SMC).

5-17

should

issue

set

multiple

I/O DRIVERS
5.8.6

IO.RVB Function

The IO.RVB function code corresponds directly to
the
VAX/VMS
IO$ READVBLK.
No subfunction bits are supported in RSX-llM for
IO.~VB.

5.8.7

IO.RPB Function

See the discussion of IO.RAL in Section 5.8.4.1.

5.8.8

IO.WLB, IO.CCO, and IO.WBT Functions

The function codes IO.WLB, IO.CCO, and IO.WBT all allow an image to
write a logical block to a terminal.
When VAX/VMS receives a
write-logical-block request from an RSX-llM image, it issues an
IO$ WRITELBLK request.
There is a direct correspondence between
IO.WLB and IO$ WRITELBLK. The RSX-llM function codes ro.cco, and
IO.WBT are the equivalents of the logical OR of IO.WLB and a
subfunction bit. The sections that follow describe VAX/VMS handling
of subfunction bits on write-logical-block requests.

5.8.8.l IO.WLB!TF.CCO and IO.CCO Functions - The RSX-llM function
codes IO.WLB!TF.CCO and IO.CCO are equivalent. Either one corresponds
directly to the VAX/VMS !0$ WRITELBLK function with a function·
modifier of IO$M CANCTRLO.

5.8.8.2 IO.WLB!WBT
and
IO.WBT
Functions - In
VAX/VMS,
the
write-break-through function is implemented using the Broadcast system
service.
As a result, neither of the RSX-llM function
codes
IO.WLB!WBT
or IO.WBT corresponds directly to a VAX/VMS driver
function. When an RSX-llM image requests write-break-through, VAX/VMS
issues
a
IO$ WRITELBLK
function
to
the
driver.
A normal
write-logical-block function occurs.

5.8.9

IO.WVB Function

The RSX-llM function code IO.WVB corresponds directly to the VAX/VMS
function code IO$ WRITEVBLK.
VAX/VMS handles the subfunction bits
allowed with IO.WVB-in the same manner as it handles the subfunction
bits for IO.WLB.
The resulting I/O operation is a write virtual
block, however.

5.8.9.1 IO.WLB!TF.WAL, IO.WAL, and IO.CCO!TF.WAL
Functions - The
RSX-llM function codes IO.WLB!TF.WAL and IO.WAL are equivalent. The
RSX-llM function IO.CCO!TF.WAL adds the cancel CTRL/O subfunction to
an IO.WAL request.
When an RSX-llM image issues a write-all-data
request, VAX/VMS issues an !0$ WRITELBLK!IO$M NOFORMAT request to
cause the data block to be transferred without-interpretation to the
specified buffer.

5-18

I/O DRIVERS
VAX/VMS requires an image to have the appropriate privilege to write a
physical block.
An RSX-llM image must have this privilege to
successfully issue an IO.WAL request.

5.8.10

IO.WPS Function

The RSX-llM function code IO.WPB corresponds directly to the VAX/VMS
function code IO$ WRITEPBLK. No subfunction bits are applicable.

5.8.11

IO.GTS Function

VAX/VMS has no system generation options
included in the terminal driver.

that

control

the

features

When an RSX-llM image issues an IO.GTS request, VAX/VMS returns a
4-word buffer of information that describes the VAX/VMS terminal
driver features. Because these features cannot be altered, the same
information always is returned. Table 5-11 lists the terminal support
information returned under VAX/VMS.
That information includes all of the features that can be returned
under RSX-llM with the following exceptions, which are always zero:
Word

bit 1
bit 2
bit 14

F'l .BTW
Fl.BUF
Fl. UTP

bit 15

Fl.VBF

Write-break-through
Checkpointing during terminal input
Input characters buffered in task's
address space
Variable-length terminal buffers

Table 5-11
Information Returned by Get Terminal Support (IO.GTS)
Word

Bit

Mnemonic

Meaning

Fl.ACR

Automa tic CRLF on long lines

Fl. UIA

Unsoli cited-character-input AST

Fl.CCC

Cance 1 CTRL/O before writing

Fl.ESQ

Recog nize
input

Fl.HLD

Hold screen mode

Fl.LWC

Lower -to-uppercase conversion

Fl.RNE

Read with no echo

Fl.RPR

Read after prompting

Fl.RST

Read with special terminators

escape

sequences

solicited

(continued on next page)

5-19

I/O DRIVERS
Table 5-11 (Cont.)
Information Returned by Get Terminal Support (IO.GTS)
Word

Bit

Mnemonic

Me aning
--'--··

·--II·····

·--

. ---~---......... --·-··--~···..

Fl.RUB

CRT rubout

Fl.SYN

CTRL/R terminal syn chronization

Fl.TRW

Read all and write all

F2.SCH

Set characteristics QUI (SF.SMC)

F2.GCH

Get characteristics QUI (SF.GMC)

Not used in RSX-llM

Not used in RSX-llM
...

"""'"""'"""'""'"""·~-·--·-·····~- "'«~·--··

···--·-·-------

NOTE
An IO.GTS function issued for TI, CO, or
CL returns no information.

5.8.12

SF.GMC Function

When an RSX-llM image issues an SF.GMC request, VAX/VMS executes a Get
I/O
Channel Device Information system service and returns the
appropriate information to the RSX-llM image in the standard format.
Table 5-12 lists the terminal characteristics that can be returned for
SF.GMC requests. The RSX-llM characteristic TC.PR! is never returned
by VAX/VMS because VAX/VMS does not incorporate the concept of a
privileged terminal.
An SF.GMC function issued for TI, CO, or CL when
corresponds to a process permanent file becomes a no-op.

5.8.13

the

device

SF.SMC Function

When an RSX-llM image issues an SF.SMC function, VAX/VMS issues an
IO$ SETMODE request.
Table 5-12 provides the correspondence among
Rsx=11M terminal characteristics bit names and VAX/VMS subfunction
modifiers used with the function code IO$ SETMODE.
An RSX-llM image cannot set terminal type (TC.TTP) using a SF.SMC
function.
A DCL or MCR SET command can be used to set the terminal
type. The TC.TBF characteristic for the SF.FMC request clears the
type-ahead buffer.
An SF.SMC function issued for TI, co, or CL when
corresponds to a process-permanent file becomes a no-op.

5-20

the

device

I/O DRIVERS

Table 5-12
Terminal Characteristics for SF.GMC and SF.SMC Requests

.----------.....--------------.- '------------------------.
RSX-llM
Bit Name

VAX/VMS Code

TC.ESQ

TM$M ESCAPE

Escape-sequence generation

TC.HLD

TM$M HOLDSCREEN

Hold screen mode

TC.NEC

TM$M NOECHO

No-echo mode

TC.SCP

TM$M SCOPE

Scope device

TC.SLV

TM$M NOTYPAHEAD

Slave device

TC.SMR

TM$M LOWER

Lowercase allowed

TC.TBF

Number of characters
in type-ahead buff er

TC.TTP

5.8.14

Meaning

Terminal type; see
the VAX-11/RSX-llM
User's Guide

Terminal type

Terminal Read Status Returns

The contents of an I/O status block used for terminal requests is the
same as that used for all QIO operations except for terminal read
operations. For terminal read operations, the high-order byte of the
first word contains a code that indicates the character or sequence
that terminated the read operation. Any one of the following codes
can be returned.
Code

Meaning

IS.CR

Read terminated by RETURN

IS. ESC

Read terminated by ALTMODE

IS.ESQ

Read terminated by an escape sequence
Other terminator character

Read terminated by full buffer

When using VAX/VMS terminal function codes
mind the following points:

and

parameters,

keep

•

VAX/VMS terminals can be spooled.

•

See Section 3.10, "Spooled Devices," for a discussion of the
requirements for issuing IO.WLB and IO.WVB requests to a
spooled device.

•

If an RSX-llM image issues a GET LUN INFORMATION directive for
a
spooled device, the information returned is for the
intermediate device, that is, for a disk.

5-21

I/O DRIVERS

•

TI, co, and CL
follows:

map

VAX/VMS

RSX-llM Pseudo-Device

process-permanent

files

VAX/VMS Process-Permanent Files

SYS$INPUT and SYS$0UTPUT
SYS$COMMAND
SYS$ERROR

co
CL
•

Process-permanent files are controlled using VAX-11 RMS unless
they map to terminals.
VAX/VMS, therefore, limits the I/O
function codes that can be used to access these files to read
and write functions only. All subfunction bits are ignored.
Functions other than read and write are illegal and result in
the I/O status code IE.IFC (illegal function for this device)
being returned.

•

For RSX-llM images, user-created process-permanent
appear as record-oriented terminal devices.

•

When process-permanent files
requests can be issued.

•

The device characteristics for TI, CO, and CL are as follows:

map

terminals,

files

queue

I/O

unit record device
terminal
132-byte buffer
carriage control
no lowercase

5.9

CARD READER DRIVER

Table 5-13 provides the correspondence between RSX-llM card
functions and VAX/VMS function codes or resultant actions.

reader

Table 5-13
Card Reader Function Code Correspondence
-------~-----··-·-·-·-·--·····

Function

RSX-llM Code

VAX/VMS Code or Action

Attach Device

IO .ATT

No operation

Detach Device

IO. DET

No operation

Cancel I/O Request

IO.KIL

Cancel I/O on Channel system
service

Read Virtual Block

IO.RVB

IO$ READVBLK

Read Logical Block

IO.RLB

IO$ READLBLK

Read Logical Block

IO.RBD

IO$ READLBLK!IO$M BINARY

· - - - - ---·--·-·--···..--·-----

The two function-dependent parameters (Pl and P2)
for RSX-llM card
reader functions correspond directly to Pl and P2 of VAX/VMS card
reader functions.

5-22

I/O DRIVERS
5.10

NULL DEVICE

VAX/VMS supports the use of a null device by RSX-llM images. As under
RSX-llM, a read request to the null device results in an end-of-file
status return (IE.EOF), and a write request results in success status
return (IE.SUC).
I/O to the null device is treated like I/O to an unsupported device as
described in Section 5.1, "Supported Devices."

5.11

DISK AND MAGNETIC TAPE ACPs

I/O operations involving file-structured devices (disk and magnetic
tape) often require ACP intervention.
Normally, RSX-llM images
perform I/O using RMS-11 or FCS; they do not issue QUEUE I/O REQUEST
directives directly to an ACP.
Any ACP intervention needed is
requested by RMS-11 or FCS and occurs transparently from the image's
point of view.
It is possible, however, for images to request ACP
functions directly by issuing a QUEUE I/O REQUEST directive and
specifying an ACP function code.
The information in this section is relevant only to RSX-llM images
that issue ACP functions directly, for example, create file and enter
file name. Other RSX-llM images running under VAX/VMS can rely on
RMS-11 or FCS to request appropriate RSX-llM ACP functions during
image execution.
VAX/VMS ACP functions are expressed using six function codes and three
function modifiers. The six function codes follow.

• !0$- CREATE

Create file

• !0$- ACCESS

Access file

•
•
•
•

!0$ DEACCESS -- Deaccess file

!0$ MODIFY

Modify file

!0$ DELETE

Delete file

IO$ ACPCONTROL -- ACP control

The three function modifiers, which can
access, and delete functions, follow.

applied

IO$M ACCESS

Open file on user's channel

IO$M CREATE

Create a file identification

•

IO$M DELETE

Delete file

the

create,

By using a function code and a function modifier together, an image
can request multiple ACP operations in one I/O request. For example,
IO$ CREATE!IO$M ACCESS requests the ACP to create a file and to access
the- file on the specified channel. IO$ DELETE!IO$M DELETE causes a
file's directory entry and file header to be deleted;
that is, the
file is deleted.
IO$ DELETE with no function modifier causes the
file's directory entry to be deleted.

5-23

I/O DRIVERS
In addition to function codes and modifiers, VAX/VMS ACPs use a file
identification block (FIB) for communication between the requester and
the ACP. The function-dependent parameter Pl for all ACP requests is
the address of a descriptor for the associated FIB. The FIB contains
much of the information passed to an ACP by an RSX-llM image in Pl
through P6.
Figure 5-2 illustrates a FIB. The VAX/VMS I/O User's
Guide provides a detailed description of the contents of a FIB anJ
describes the ACP functions supported by VAX/VMS.

24 23

8 7

16 15

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

FIB$B_WSIZE

FIB$L_ACCTL
I
FIB$W_FID
---I

1---

FIB$W_DID
I
···-···--···--·-------------------------------- ------~
I

FIB$L_WCC
I
FIB$W_EXCTL

t--·------~···-···-

FIB$W_NMCTL
I
FIB$L_EXSZ
I

·-···-······-------------------

FIB$L_EXVBN
1----------···---------·····-·--······· ···-·--··

1- F~B$B_-A_-~_A_L_1G_N
I

_____
F_1B_$_B-_A_L_o_Pr_s---I

I
I

I
FIB$W_ALLOC

t--

Figure 5-2
RSX-llM ACP functions
codes:

•

IO.CRE

File Identification Block Format
are

expressed

Create file

• IO .ACR

Access for read

•
•
•

IO.ACW

Access for write

IO.ACE

Access for extend

IO.EXT

Extend file

• IO. WAT

Write attributes

5-24

using

the

following

function

I/O DRIVERS
e

IO.RAT

Read attributes

IO.DAC

Deaccess file

•

IO.DEL

Delete file

IO.FNA

Find file name

IO.RNA

Remove file name

•

IO.ENA

Enter file name

•

IO.APC

ACP control

When an RSX-llM image issues an ACP request under VAX/VMS, VAX/VMS
issues a Queue I/O Request system service to the ACP. It obtains the
data to fill in the FIB and function-dependent parameters for the
request from two sources:
•

Function-dependent parameters supplied by
QUEUE I/O REQUEST directive

the

image

•

Data structures pointed to by function-dependent
for example, the file name block

the

parameters,

Once the requested function is performed, VAX/VMS fills in the RSX-llM
image's data structures with the same information that is returned to
the image when executing under the RSX-llM operating system.

5.11.1

General Correspondence of Parameters

Table 5-14 identifies the relationship of RSX-llM function-dependent
parameters to VAX/VMS function-dependent parameters and FIB fields.
Table 5-14
ACP Parameter Correspondence
Parameter Function

RSX-llM Pn

VAX/VMS Equivalent

File identification
pointer

Pl {pointer)

FIB$W FID {value)

Attribute list pointer

PS {reformatted)

Extend control

P3 {high byte)

FIB$W EXCTL

Delta size in blocks

P3 {low byte) and P4

FIB$L EXVBN for
truncate only;
FIB$ L EXSZ for
extend

Window size

PS {low byte)

FIB$B WSI ZE

Access control

PS {high byte)

FIB$L ACCTL

File name block pointer

P2 {name string)
and P4 {result
string)

S-25

I/O DRIVERS
5.11.2

IO.CRE Function

Equivalent Function Code:

IO$_CREATE!IO$M_CREATE

Notes:
•

If the extend size is supplied in the low-order byte of P3 and
in P4, it is stored in FIB$L EXSZ.

•

The high-order byte of P3 (extend control) is used to set bits
in FIB$W EXCTL:
FIB$V EXTEND
FIBSV-ALCON
FIBSV-ALCONB
FIB$V-FILCON
FIB$V-ALDEF

= EX.ENA
= EX.ACl

EX.AC2
= EX.FCO

EX.ADF

•

The file identification is copied from FIBSW FID and
in the address pointed to by Pl (FID pointer).

•

Information in the VAX/VMS attribute list is derived from
RSX-llM attribute list, if one is supplied.

the

•

The extend size in blocks is returned in bytes 1, 2, and 3
the I/O status block.

5.11.3

returned

IO.DEL with EX.ENA=O

Equivalent Function Code:

IO$ DELETE!IO$M DELETE

Note:
•

5.11.4

The file identification
FIBSW FID.

pointed

copied

into

copied

into

IO.DEL with EX.ENA=l

Equivalent Function Code:

IO$ MODIFY

Notes:
•

The file identification
FIB$W FID.

pointed

•

FIB$V TRUNC is set in field FIBSW EXCTL.

•

The extend size supplied in the low byte of P3 and
incremented by 1 and stored in FIB$L EXVBN.

•

The file round-up in blocks is returned in bytes 2 and 3 of
the I/O status block. File round-up is the number of blocks
added to the specified file size to reach the next cluster
boundary.

s-2n

I/O DRIVERS
S.11.S

IO.ACR Function

Equivalent Function Code:

IO$_ACCESS!IO$M_ACCESS

Notes:
•

The file identification
FIB$W FID.

•

The high-order byte of PS (access control)
in FIB$L ACCTL:
FIB$V NOWRITE
FIB$V-REWIND
FIB$V-CURPOS
FIB$V=UPDATE

pointed

copied

into

is used to set bits

AC.LCK
AC.RWD
AC.POS
= AC.UPD

•

The window size provided by the low-order byte of PS is stored
in FIB$B WSIZE.

•

Information in the VAX/VMS attribute list is derived from
RSX-llM attribute list, if one is supplied.

S.11.6

the

IO.ACW and IO.ACE Functions

Equivalent Function Code:

IO$_ACCESS!IO$M_ACCESS

Notes:
•

The file identification
FIB$W FID.

pointed

•

The high-order byte of PS (access control)
in FIB$L ACCTL:

copied

into

is used to set bits

FIB$V DLOCK
AC.DLK
FIB$V-NOWRITE
AC.LCK
FIB$V-REWIND
AC.RWD
FIB$V-CURPOS
AC.POS
FIB$V-UPDATE = AC.UPD
In addition, VAX/VMS sets FIB$V WRITE.
•

The window size provided by the low-order byte of PS is stored
in FIB$B WSIZE.

•

Information in the VAX/VMS attribute list is derived from
RSX-llM attribute list, if one is supplied.

5.11.7

the

IO.DAC Function

Equivalent Function Code:

IO$ DEACCESS

Notes:
•

The file identification
FIB$W FID.

pointed

copied

into

•

Information in the VAX/VMS attribute list is derived from
RSX-llM attribute list, if one is supplied.

the

5-27

I/O DRIVERS

5.11.8

IO.EXT Function

Equivalent Function Code:

IO$ MODIFY

Notes:
•

The file identification
FIB$W FID.

•

The high-order byte of P3 {extend control)
in FIB$W EXCTL:
FIB$V EXTEND
FIB$V-ALCON
FIB$V-ALCONB
FIB$V-FILCON
FIB$V-ALDEF

pointed

copied

into

is used to set bits

EX.ENA
EX.ACl
= EX.AC2
EX.FCO
EX.ADF

•

The extend size supplied in the low-order byte of P3 and in P4
is stored in FIB$L EXSZ.

•

The amount by which the file is extended is returned in
1, 2, and 3 of the I/O status block.

5.11.9

bytes

IO.WAT Function

Equivalent Function Code:

IO$ MODIFY

Notes:
•

The file identification
FIBSW FID.

copied

into

•

Information in the VAX/VMS attribute list is derived from
RSX-llM attribute list, if one is supplied.

the

5.11.10

pointed

IO.RAT Function

Equivalent Function Code:

IO$ ACCESS

Notes:
•

The file identification
FIB$W FID.

copied

into

•

Information in the VAX/VMS attribute list is derived from
RSX-llM attribute list, if one is supplied.

the

5.11.11

pointed

IO.FNA Function

Equivalent Function Code:

IO$ ACCESS

Notes:
•

The file identification is copied from FIB$W FID and
in the address pointed to by Pl.
-

•

The directory identification is
block into FIB$W DID.

5-28

copied

from

the

returned
file

name

I/O DRIVERS
•

The file name string supplied in the
request
is constructed
from the Radix-50 file name in the file name block.

•

If the bit
resultant
type.
The
block, and

NB.WLV is set in N.STAT of the file name block,
a
string is constructed from the Radix-50 name and
version number is stored in N.FID+4 of the name
is supplied as input to the IO$_ACCESS call.

If NB.WLV is not set, a resultant string
supplied.

zero

length

•

The file name string returned is the resultant string returned
by the Queue I/O Request system service.
It is converted back
to Radix-50 and returned to the file name block.

•

Control bits in field N.STAT of the file name block
to set bits of FIB$W NMCTL:
FIB$V ALLNAM
FIB$V-ALLTYP
FIB$V-ALLVER
FIB$V-WILD

•

5.11.12

are

used

NB.SNM
NB.STP
NB.SVR
NB.SNM!NB.STP!NB.SVR

The file name block field N.NEXT is used to set FIB$L wee.
The resulting value of FIB$L wee is returned in N.NEXT. -

IO.RNA Function

Equivalent Function Code:

IO$ DELETE

Notes:
•

The file identification is copied from FIB$W FID and
in the address pointed to by Pl.
-

•

The directory identification is
block into FIB$W DID.

•

If the bit
resultant
type.
The
block, and

copied

from

the

returned
file

name

NB.WLV is set in N.STAT of the file name block,
a
string is constructed from the Radix-50 name and
version number is stored in N.FID+4 of the name
is supplied as input to the IO$_ACCESS call.

If NB.WLV is not set, a resultant string
supplied.

zero

length

•

The file name string supplied in the
request
is constructed
from the Radix-50 file name in the file name block.

•

The file name returned is the resultant string returned by the
Queue I/O Request system service.
It is converted back to
Radix-50 and returned to the file name block.

•

Control bits in field N.STAT of the file name block
to set bits of FIB$W NMCTL:
FIB$V ALLNAM
FIB$V-ALLTYP
FIB$V-ALLVER
FIB$V-WILD

•

are

used

NB.SNM
NB.STP
NB.SVR
NB.SNM!NB.STP!NB.SVR

The file name block field N.NEXT is used to set FIB$L wee.
The resulting value of FIB$L wee is returned in N.NEXT. -

5-29

I/O DRIVERS
5.11.13

IO.ENA Function

Equivalent Function Code:

IO$ CREATE

Notes:
•

The file identification is copied from
into FIB$W FID.

the

•

The directory identification is
block into FIB$W DID.

from

•

The file name string supplied in the
request
is constructed
from the Radix-SO file name in the file name block.

•

The file name returned is the resultant string returned by the
Queue I/O Request system service.
It is converted back to
Radix-SO and returned to the file name block.

5.11.14

copied

file

name

block

the

file

name

IO.APC Function

Equivalent Function Code:

IO$ ACPCONTROL

Notes:
•

•

P3 contains the subfunction identification.
The low-order
byte of P3
is zero-extended and stored at FIB$W CNTRLFUNC,
which overlays FIB$W EXCTL.
The RSX-llM ACP subfunction codes
have direct equivalents in VAX/VMS, as follows.

RSX-llM Subfunction

VAX/VMS Subfunction

FF.NV
FF.POE
FF.RWD
FF.RWF
FF.SPC

FIB$C NEXTVOL
FIB$C-POSEND
FIB$C-REWINDVOL
FIB$C-REWINDFIL
FIB$C-SPACE

For the FF.SPC subfunction, P4 is sign-extended and stored at
FIB$L CNTRLVAL, which overlays FIB$L EXSZ. A negative value
for P4 specifies the number of blocks to space backward.
A
positive value indicates the number of blocks to space
forward.

5-30

APPENDIX A

VAX-11 COMPATIBILITY MODE INSTRUCTION SET

Table A-1 lists the VAX-11 compatibility mode instruction set.
Table A-1
VAX-11 Compatibility Mode Instruction Set
.-------------··----- ····-----------------Opcode
Mnemonic
(octal)
000002
000006
OOOlDD
00020R
000240-000277
0003DD
000400-003777
100000-103777
004RDD
.050DD
• 051DD
.052DD
.053DD
.054DD
.055DD
.056DD
.057DD
.060DD
.061DD
.062DD
.063DD
006588
0066DD
106588
106nDD
0067DD
070RSS
071RSS
072RSS
073RSS
074RSS
077RNN
.lSSDD
.2SSDD
.3SSDD
.4SSDD
.5SSDD
06SSDD
16SSDD

RTI
RTT
JMP
RTS
Condition codes
SWAB
Branches
Branches
JSR
CLR(B)
COM(B)
INC (B)

DEC(B)
NEG(B)
ADC(B)
SBC(B)
TST(B)
RCR(B)
ROL(B)
ASR(B)
ASL(B)
MFPI (See
MTPI (See
MFPD (See
MTPD (See
SXT
MUL
DIV
ASH
ASHC
XOR
SOB
MOV(B)
CMP(B)
BIT(B)
BIC(B)
BIS(B)
ADD
SUB

A-1

note
note
note
note

below.)
below.)
below.)
below.)

VAX-11 COMPATIBILITY MODE INSTRUCTION SET
NOTE
The MFPI,
MTPI,
MFPD,
and
MTPD,
instructions execute exactly as they
would on a PDP-11 in user mode with
Instruction and Data space overmapped.
More specifically, they
ignore
the
previous access level and act like PUSH
and POP instructions ref erring to the
current stack.
VAX/VMS provides emulation of the FPP floating-point instructions.

A-2

APPENDIX B
PARSE DIRECTIVE

The parse directive allows an RSX-llM image to use VAX/VMS file
specifications that are not fully qualified because of the use of
logical names. Use of this directive replaces the operation of the
FCS .PARSE, .PRSDR, and .PRSDV routines and the RMS-11 $PARSE routine
for RSX-llM images running in VAX/VMS.
An RSX-llM image requests the parsing of a file specification by
issuing a parse directive that supplies the addresses of a file name
block and data structures containing default information.
VAX/VMS
uses the information supplied by the image and information contained
in the RSX-llM logical name table and the system logical name table to
build the primary and default strings that VAX-11 RMS requires to
perform the actual parsing. VAX-11 RMS returns the expanded name to
VAX/VMS.
VAX/VMS,
in turn, uses the expanded name to fill in the
appropriate RSX-llM data structures, for example, returned directory
string and file name block. The result is that the image receives the
information in the normal RSX-llM formats.
The image can request four different types of parsing:

B.l

•

Parsing of the full file specification (normal mode)

•

Parsing of the device name only (device-only mode)

•

Parsing of the file name using the default file name block
the major source of input (dfnb mode)

•

RMS-11 mode of parsing

NORMAL MODE PARSING

When the mode parameter is equal to o, VAX-11 RMS parses the full file
specification. VAX/VMS builds the primary string required as input to
VAX-11 RMS by concatenating fields of the dataset descriptor, as
follows:
•

Device

•