Digital PDFs

AA-H265A-TC

May 1979

286 pages

Original

19MB

Document:	RSX-11M/M-PLUS Executive Reference Manual
Order Number:	AA-H265A-TC
Revision:	0
Pages:	286
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsx11m_s/RSX11M_V3.2_Jun79/3B_ProgramDevelopment/AA-H265A-TC_RSX-11M_V3.2_Executive_Reference_Man_197905.pdf

OCR Text

RSX-11 M/M-PLUS
ExecU'tive
Reference Manual
Order No. AA-H265A-TC

RSX-11M Version 3.2
RSX-11M-PLUS Version 1.0

•

r-:;::rder additional copies of this document, contact the Software Distribution
~r, Digital Equipment Corporation, Maynard, Massachusetts 01754

digital equipment corporation · maynard, massachusetts

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

@ 1979 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
COMTEX
DDT
DECCOMM
ASSIST-11
VAX
DECnet
DATATRIEVE

DECsystem-lo
DECtape
DIBOL
EDUSYSTEM
FLIP CHIP
FOCAL
INDAC
LAB-8
DECSYSTEM-20
RTS-8
VMS
IAS
TRAX

5/80-14

MASS BUS
OMNIBUS
OS/8
PHA
RSTS
RSX
TYPESET-8
TYPESET-11
TMS-11
ITPS-10
SBI
PDT

•

CONTENTS
Page
SUMMARY OF

~rECHNICAL

CHANGES

vii

PREFACE
..,

CHAPTER

ix
1

USING SYSTEM DIRECTIVES

1.1
1.2
1. :3
1. 4
1. 4 .1
1.4.1.1
1.4.1.2
1.4.1.3
l.'4.2
1. 4. 3
1. 4. 4
1. 4. 5
1. 5
1. 5.1
1.5.1.1
1.5.1.2
1.5.1.3
1.5.1.4
1. 5. 2
1. 5. 3
1. 6
1. 6 .1
1. 6. 2
1. 7
1. 8
1. 9

INTRODUCTION
1-1
DIRECTIVE PROCESSING
1-2
ERROR RETURNS
1-3
USING THE DIRECTIVE MACROS
1-4
Macro Name Conventions
1-5
$ Form
1-6
$C Form
1-6
$S Form
1-7
DIR$ Macro
1-7
Optional Error Routine Address
1-7
Symbolic Off sets
1-8
Examples of Macro Calls
1-8
FORTRAN SUBROUTINES
1-9
Subroutine Usage
1-10
Optional Arguments
1-10
Task Names
1-10
Integer Arguments
1-ll
GETADR Subroutine
1-ll
The Subroutine Calls
1-12
Error Conditions
1-15
TASK STATES
1-16
Task State Transitions
1-17
Removing an Installed Task
1-18
THE GENERAL INFORMATION DIRECTIVE
1-18
DIRECTIVE RESTRICTIONS FOR NONPRIVILEGED TASKS 1-18
RSX-llM-PLUS
1-19

SIGNIFICANT EVENTS, SYSTEM TRAPS, AND STOP-BIT
SYNCHRONIZATION
2-1

2.1
2.2
2.3
2.3.1
2.3.2
2.3.3
2.3.4
2.4

SIGNIFICANT EVENTS
EVENT FLAGS
SYSTEM TRAPS
Synchronous System Traps (SSTs)
SST Service Routines
Asynchronous System Traps (ASTs)
AST Service Routines
STOP-BIT SYNCHRONIZATION

2-1
2-1
2-3
2-4
2-4
2-6
2-7
2-ll

MEMORY MANAGEMENT DIRECTIVES

3-1

3.1
3.1.1
3 .1. 2
3 .1. 3
3.2
3.3
3.3.l

ADDRESSING CAPABil~ITIES OF AN RSX-llM TASK
Address Mapping
Virtual and Logical Address Space
Supervisor Mode Addressing
VIRTUAL ADDRESS WINDOWS
REGIONS
Shared Regions

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

iii

1-1

CONTEN'l~S

Page

CHAPTER

3.3.2
3.3.3
3.4
3.4.1
3.4.2
3.4.3
3.4.4
3.4.5
3.4.6
3.4.7
3.4.8
3.4.9
3.4.10
3.4.H
3.5
3.5.l
3.5.1.1
3.5.1.2
3.5.2
3.5.2.1
3.5.2.2
3.5.3
3.6

Attaching to Regions
Region Protection
DIRECTIVE SUMMARY
Create Region Directive (CRRG$)
Attach Region Directive (ATRG$)
Detach Region Directive (DTRG$)
Create Address Window Directive (CRAW$)
Eliminate Address Window Directive (ELAW$)
Map Address Window Directive (MAP$)
Unmap Address Window Directive (UM.AP$)
Send By Reference Directive (SREF$)
Receive By Reference Directive (RREF$)
Get Mapping Context Directive (GMCX$}
Get Region Parameters Directive (GREG$)
USER DATA STRUCTURES
Region Definition Block (RDB)
Using Macros to Generate an RDB
Using FORTRAN to Generate an RDB
Window Definition Block (WDB)
Using Macros to Generate a WDB
Using FORTRAN to Generate a WDB
Assigned Values or Settings
PRIVILEGED TASKS

3-5
3-8
3-9
3-9
3-9
3-9
3-9
3-9
3-9
3-9
3-10
3-10
3-10
3-10
3-10
3-H
3-12
3-14
3-14
3-16
3-17
3-18
3-18

PARENT/OFFSPRING TASKING

4-1

4.1
4.2
4.2.1
4.2.2
4.3

PARENT/OFFSPRING Tl~SKING SUPPORT OVERVIEW
DIRECTIVE SUMMARY
Parent/Off spring Tasking Directives
Task Communication Directives
CONNECTING AND PASSING STATUS

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

RSX-HM-PLUS EXECU'rIVE DIRECTIVES AND
FUNCTIONS

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

5.3
5.4
5.5
5.6
5.7

RSX-HM-PLUS DIREC~~IVES -- OVERVIEW
VIRTUAL TERMINAL SUPPORT
Virtual Terminal Functions
Virtual Terminal Support -- Directive
Summary
SUPERVISOR MODE LIBRARY SUPPORT
TASK CPU/UNIBUS AFFINITY
EXIT AST ROUTINE SUPPORT
PARITY ERROR AST ROUTINE SUPPORT
EXECUTIVE-LEVEL DISPATCHING

DIRECTIVE DESCRIPTIONS

6-1

6.1
6 .1.1
6.1. 2
6 .1. 3
6 .1. 4
6 .1. 5
6 .1. 6

DIRECTIVE CATEGORIES
Task Execution Control Directives
Task Status Control Directives
Informational Directives
Event-Associated Directives
Trap-Associated Directives
I/0- and Intertask Communications-Related
Directives
Memory Management Directives
Parent/Off spring Tasking Directives

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

5.1
5.2
5.2.1
5.2.2

CHAPTER

6 .1. 7
6 .1. 8

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

6-3
6-3
6-4

•

CONTENTS
Page
6 .1. 9

6.2
6.3
6.3.1
6.3.2
6.3.3
6.3.4
6.3.5
6.3.6
6.3.7
6.3.8
6.3.9
6.3.10
6 . .3.11
6 . .3.12
6.3.13
6.3.14
6.3.15
6.3.16

6.3.17
6.3.18
6.3.19
6.3.20
6.3.21
6.3.22
6.3.23
6.3.24
6.3.25
6.3.26
6.3.27
6.3.28
6.3.29
6.3.30
6.3.31
6.3.32
6.3.33
6.3.34
6.3.35
6.3.36
6.3.37
6.3.38
6.3.39
6.3.40
6.3.41
6.3.42
6.3.43
6.3.44
6.3.45
6.3.46
6.3.47
6.3.48
6.3.49
6.3.50
6.3.51
6.3.52
6.3.53

RSX-llM-PLUS Directives
DIRECTIVE CONVENTIONS
SYSTEM DIRECTIVE DESCRIPTIONS
Abort Task (ABRT$)
Alter Priority (ALTP$)
Assign LON (ALON$)
AST Service Exit (ASTX$S)
Attach Region (ATRG$)
Connect To Interrupt Vector (CINT$)
Clear Event Flag (CLEF$}
Cancel Mark Time Requests (CMKT$)
Connect (CNCT$)
Create Address Window (CRAW$)
Create Group Global Event Flags (CRGF$)
Create Region (CRRG$)
Create Virtual 'l?erminal (CRVT$)
Cancel Time Based Initiation Requests
(CSRQ$)
Declare Significant Event (DECL$S)
Disable (or Inhibit) AST Recognition
(DSAR$S or IHAR$S)
Disable Checkpointing (DSCP$S)
Detach Region (DTRG$)
Eliminate Address Window (ELAW$)
Eliminate Group Global Event Flags (ELGF$)
Eliminate Virtual Terminal (ELVT$)
Emit Status (EMST$)
Enable AST Recognition (ENAR$S)
Enable Checkpointing (ENCP$S)
Exit I f (EXIF$)
Task Exit (EXIT$S)
Exit With Status (EXST$)
Extend Task (EXTK$)
Get LON Information (GLUN$)
Get MCR Command Line (GMCR$)
Get Mapping Context (GMCX$)
Get Partition Parameters (GPRT$)
Get Region Parameters (GREG$)
Get Sense Switches (GSSW$S)
Get Time Parameters (GTIM$)
Get Task Parameters (GTSK$)
Map Address Window (MAP$)
Mark Time (MRKT$)
Queue I/O Reque~t (QIO$)
Queue I/O Request and Wait (QIOW$)
Receive Data or Stop (RCST$)
Receive Data (RCVD$)
Receive Data or Exit (RCVX$)
Read All Event Flags (RDAF$)
Read Extended Event Flags (RDXF$)
Remove Affinity (RMAF$S)
Request Task (RQST$)
Receive By Reference (RREF$)
Resume Task (RSUM$)
Run Task (RUN$)
Supervisor Call (SCAL$S)
Send Data (SDAT$)
Send, Request and Connect (SDRC$)

6-4
6-5
6-5
6-7
6-9
6-11
6-13
6-15
6-17
6-26
6-27
6-29
6-31
6-35
6-36
6-39
6-44
6-45
6-46

6-48
6-49
6-51
6-53
6-54
6-56
6-57
6-58
6-59
6-61
6-63
6-64
6-66
6-69
6-71

6-74
6-76
6-78
6-79
6-81
6-83
6-86
6-90
6-93
6-95
6-97
6-99
6-102
6-103
6-104
6-105
6-108
6-111
6-112
6-117
6-119
6-121

CONTENTS
Page
6.3.54
6.3.55
6.3.56
6.3.57
6.3.58
6.3.59
6.3.60
6.3.61
6.3.62
6.3.63
6.3.64
6.3.65
6.3.66
6.3.67
6.3.68
6.3.69
6.3.70
6.3.71
6.3.72
6.3.73
6.3.74
6.3.75
6.3.76
6.3.77
6.3.78
APPENDIX A

Set Event Flag (SETF$)
Specify Floating Point Processor Exception
AST (SFPA$)
Specify Parity Error AST (SPEA$)
Suspend (SPND$S)
Specify Power Recovery AST (SPRA$)
Spawn (SPWN$)
Specify Receive Data AST (SRDA$)
Specify Requested Exit AST (SREA$)
Send by Reference (SREF$)
Specify Receive-by-Reference AST (SRRA$)
Set Affinity (STAF$)
Stop for Logical OR of Event Flags (STLO$)
Stop (STOP$S)
Stop for Single Event Flag {STSE$)
Specify SST Vector Table for Debugging Aid
(SVDB$)
Specify SST Vector Table for Task {SVTK$)
Unmap Address Window {UMAP$)
Unstop Task (USTP$)
Variable Receive Data (VRCD$)
Variable Receive Data or Stop {VRCS$)
Variable Receive Data or Exit {VRCX$)
Variable Send Data {VSDA$)
Wait for Significant Event (WSIG$S)
Wait for Logical OR of Event Flags (WTLO$)
Wait for Single Event Flag {WTSE$)

6-123
6-124
6-126
6-128
6-129
6-131
6-135
6-137
6-138
6-141
6-143
6-145
6-147
6-148
6-149
6-151
6-153
6-155
6-156
6-158
6-160
6-162
6-164
6-166
6-168

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY
MACRO CALL

A-1

APPENDIX B

STANDARD ERROR CODES

B-1

APPENDIX C

DIRECTIVE IDENTIFICATION CODES

C-1

APPENDIX D

RSX-11 SYSGEN SELECTION OF EXECUTIVE
DIRECTIVES

D-1

INDEX

•

Index-!
FIGURES

FIGURE

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

Directive Parameter Block (DPB) Pointer
on the Stack
Directive Parameter Block (DPB) on the
Stack
Virtual Address Windows
Regions
Mapping Windows to Regions
Region Definition Block
Window Definition Block

1-4
1-5
3-4
3-6
3-7
3-12
3-15

TABLES
TABLE

1-1
5-1

FORTRAN Subroutines and Corresponding Macro
Calls
RSX-llM-PLUS Executive Directives

1-12
5-1

•.

SUMMARY OF TECHNICAL CHANGES

This revision of the Executive Reference Manual contains changes
additions
to document two operating systems:
RSX-llM V3.2
RSX-llM-PLUS Vl.O •

and
and

•
TECHNICAL CHANGES COMMON TO RSX-llM AND RSX-llM-PLUS SYSTEMS
The following list contains a brief summary of technical
both operating systems (RSX-llM/M-PLUS):

•

Parent/offspring tasking support has
the following new directives:

been

changes

added,

for

including

Spawn
Connect
Exit With Status

Stop-bit synchronization of tasks is now supported using
following.new directives:

the

Stop
Receive Data Or Stop
Stop For Logical 'OR' Of Event Flags
Stop For Single Event Flag
Unstop
3.

Group global event flags have been added,
including a new
data structure containing
32 event flags and the following
directives:
Create Group Global Event Flags
Eliminate Group Global Event Flags
Read Extended Event Flags

Task images built on RSX-llM V3.l and V3.2 will
run
in
compatibility mode under VAX/VMS Vl.O, Vl.01, and Vl.5 with
certain restrictions.
The
restrictions,
including those
involving
RSX-llM Executive services described
in this
manual, are described
in detail
in the
VAX-11/RSX-llM
Programmer's Reference Manual.
With the next major
release of VAX/VMS,
some of
the
restrictions currently imposed for RSX-llM tasks are expected
to change.
Therefore,
refer
to
the
current
VAX/VMS
documentation for the specific system in use •

•

vii

TECHNICAL CHANGES FOR RSX-llM-PLUS SYSTEMS
Executive support added
for
RSX-llM-PLUS operating
systems
is
described
in Chapter
5.
The
following list is a brief summary of
technical changes for this support:
1.

In addition to
the
parent/offspring
tasking
support
previously listed
for both operating systems, the following
new directives are added:

,~-i'J'.•

•

Send, Request And Connect
Emit Status
2.

Virtual terminal support is added, allowing parent tasks
to
execute
terminal
I/O with offspring
tasks via terminals
implemented in software.
New directives added
for virtual
terminal support include:
Create Virtual Terminal
Eliminate Virtual Terminal

New CPU/UNIBUS affinity support directives have been added,
allowing
task selection of CPU
(in multiprocessor system
environments) and UNIBUS run, as follows:
Set Affinity
Remove Affinity

A Supervisor mode library support directive has been added,
allowing user tasks to map Supervisor I-space (in addition to
user D-space), as follows:
Supervisor Call

variable-length send/receive data buffers are
via the following new directives:
variable
Variable
variable
variable

now

supported

Receive Data
Receive Data Or Stop
Receive Data Or Exit
Send Data

Support of the exit Asynchronous System Trap
(AST)
routine
for
tasks that abort via directive or MCR is provided by the
following new directive:
Specify Requested Exit AST

Support of the parity error AST routine is now provided
diagnostic purposes via the following new directive:

for

Specify Parity Error AST

•

viii

PREFACE

•
MANUAL OBJECTIVES

•

The RSX-llM/M-PLUS Executive Reference Manual describes the system
directives that allow experienced MACR0-11 and FORTRAN programmers to
use Executive services to control the execution and interaction of
tasks.

INTENDED AUDIENCE
The intended audience for this manual are software developers who are
experienced users of MACR0-11 or FORTRAN for user task generation.
Information contained in this manual is intended for reference only;
no attempt is made to describe the procedures involved in developing
user tasks beyond the detailed reference information normally required
for directive use.
However, Chapters 1 through 5 do contain much
information that will aid in better understanding how directives can
be effectively used in the RSX-llM/M-PLUS multitasking environment.
Convenient quick-reference material is included in appendixes at the
end of the manual for use by the more advanced RSX-llM/M-PLUS
pro9rammer.

STRUCTURE OF THIS DOCUMENT
A Summary Of Technical Changes provides the experienced RSX-llM user
with a quick summary of changes to system software since the previous
version of this manual. Comments are general and serve only as a
guide to areas of change.
Chapter 1 defines system directives and describes their
MACR0-11 and FORTRAN programs.

use

both

Chapter 2 defines significant events, event flags, system traps, and
stop-bit synchronization and describes their relationship to system
dir4=ctives.
Chapter 3 introduces the concept of extended logical
within the framework of memory management directives.

address

space

parent/offspring
tasking,
Chapter 4 introduces the concept of
including associated directives, generated data structures, and task
communications.

·-

Chapter 5 introduces the additional Executive support provided in
RSX-llM-PLUS.
This includes system directives for Supervisor mode
library support, additional parent/offspring
tasking
and
task
communications support, task CPU and UNIBUS affinity support, virtual
terminal support for offspring tasks, and additional AST routine
support.

Chapter 6 contains a short summary of all directives, arranged
according to their functional categories. The summary is followed by
detailed descriptions of each system directive arranged alphabetically
according to macro call.

~
'f~"

'"""1

Appendix A contains directives arranged alphabetically according to
macro
call.
Abbreviated specifications include directive name,
FORTRAN call, macro call, and parameters only.
Appendix B lists the standard error codes returned by the
RSX-llM-PLUS Executive.

RSX-llM

•

Appendix C lists Directive Identification Codes for all directives in
the exact octal values as they appear in the Directive Parameter
Block. A description of how the values are obtained is included.
Appendix D lists all directives, the operating systems where the
individual
directives
are
available
(RSX-118,
RSX-llM,
or
RSX-llM-PLUS), and the SYSGEN option required
(if applicable)
to
obtain that directive support.

ASSOCIATED DOCUMENTS
Manuals that are prerequisite sources of information for readers of
this manual are:
RSX-llM/M-PLUS Task Builder Manual and either
IAS/RSX-11 MACR0-11 Reference Manual, or IAS/RSX-11 FORTRAN IV User's
Guide, or FORTRAN IV-PLUS User's Guide.
Other documents related to the contents of this manual are described
briefly in the appropriate Documentation Directory supplied with the
software kit.

CONVENTIONS USED IN THIS DOCUMENT
Whenever necessary, information that is applicable to a specific
operating system {RSX-llM or RSX-llM-PLUS) is clearly indicated. In
addition, for ease of reference, those portiqns of text that apply to
RSX-llM-PLUS only are indicated by;'·p~9·~~z::o-·liq(j"··:S,'~;iiq]~'if$i on the printed
page.

•

CHAPTER 1
USING SYSTEM DIRECTIVES

•

This chapter describes the use of system directives and the ways
in
which they are processed.
Some of the Executive services described in
this manual are optional RSX-llS, RSX-llM,
or RSX-llM-PLUS features
and may not be present in the system you are currently using.
The
discussion of the system directives assumes that all possible features
are present in your system.
See the appropriate system generation
manual for a list of optional features.

1.1

INTRODUCTION

When a task requests the Executive to perform an indicated operation,
this process is called a system directive. The programmer uses the
directives to control the execution and
interaction of tasks.
The
MACR0-11 programmer usually issues directives in the form of macros
defined in the system macro library. The FORTRAN programmer
issues
system directives in the form of calls to subroutines contained in the
system object module library.
System directives enable tasks to:
•

Obtain task and system information

•

Measure time intervals

•

Perform I/O functions

•

Communicate with other tasks

•

Manipulate a task's logical and virtual address space

•

Suspend and resume execution

Exit

Directives are implemented via the EMT 377 instruction.
EMT 0 through
EMT 376
(or 375 for unmapped tasks and mapped privileged tasks) are
considered to be non-RSX EMT synchronous system traps.
They cause the
Executive to abort the
task unless the task has specified that it
wants to receive control when such traps occur.
Note that RSX-llM
reserves EMT 370 and above for use as special system traps in case of
future expansion of system capabilities.
A MACR0-11 programmer should use the system directives supplied in the
system macro library for directive calls, rather than hand-coding
calls to directives.
The programmer then need only reassemble the
program to incorporate any changes in the directive specifications.

1-1

USING SYSTEM DIRECTIVES
Sections 1.2, 1.3, and 1.6 are directed to all
users.
Section 1.4
specifically describes the use of macros, while Section 1.5 describes
the use of FORTRAN subroutine calls.
Programmers using
other
supported languages should refer to the appropriate language reference
manual supplied by DIGITAL.

1.2

DIRECTIVE PROCESSING

•

Processing a system directive involves four steps:
1.

The user task issues a directive with arguments that are only
used by the Executive.
The directive code and parameters
that the task supplies to the system are known as the
Directive Parameter Block
(DPB). The DPB can be either on
the user task's stack or in a user task's data section.

The Executive receives an EMT 377 generated by the
macro (or a DIR$ macro).

The Executive processes the d:Lrective.

The Executive returns directive status
task's Directive Status Word {DSW).

Note that the Executive preserves
issues a directive.

all

task

directive
~.

information

registers

when

the

task

The user task issues an EMT 377 (generated by the directive)
together
with the address of a DPB, or a DPB itself, on the top of the issuing
task's stack. When the stack contains a DPB address,
the Executive
removes the address after processing the directive, and the DPB itself
remains unchanged. When the stack contains the actual DPB,
rather
than a DPB address, the Executive removes the DPB from the stack after
processing the directive.
The first word of each DPB contains a Directive Identification Code
(DIC) byte, and a DPB size byte.
The DIC indicates which directive is
to be performed;
the size byte indicates the DPB length in words.
The DIC
is in the low-order byte of the word, and the size is in the
high-order byte.
The DIC is always odd.
This allows the Executive to determine whether
the word on the top of the stack (before EMT 377 was issued) was the
address of the DPB (even-numbered value) or the first word of the DPB
(odd-numbered value).
The Executive normally returns control to the
instruction following
the
EMT.
Exceptions to
this are directives that result in an exit
from the task that issued them and Asynchronous System Trap
(AST)
exit.
The Executive also clears or sets the Carry bit in the
Processor Status word
(PS)
to
indicate acceptance or
rejection,
respectively, of the directive. The DSW, addressed symbolically as
$Dswl, is set to indicate a more specific cause
for
acceptance or
rejection of the directive.
The DSW usually has a value of +l for
acceptance and a range of negative values for
rejection
(exceptions
are success return codes for the directives CLEF$, SETF$, and GPRT$,
1 The Task Builder resolves the address of $DSW.
Users addressing
the DSW with a physical address are not guaranteed compatibility with
IAS and may experience incompatibilitie?s with future RSX-llM releases.

1-2

USING SYSTEM DIRECTIVES
among others).
RSX-llM/M-PLUS associate DSW values with symbols,
using mnemonics that report either successful completion or the cause
of an error (see Section 1.3).
(The ISA FORTRAN calls CALL START and
CALL WAIT are exceptions;
ISA requires positive numeric error codes.
See Sections 6.3.49 and 6.3.38 for details, the detailed return values
are listed there with each directive.)

•

In the case of successful Exit directives, the Executive does not, of
course,
return control
to
the task.
If an Exit directive fails,
however, control is returned to the task with an error status
in the
DSW ..
On Exit, the Executive frees task resources as follows:

•

....,.

attach~d

Detaches all

devices

Flushes the AST queue (ASTs are described
this manual.)

Flushes the clock queues for outstanding Mark
for the task (see Section 6.3.38)

Flushes the receive-data and receive-by-reference queues

Closes all open files
left locked.)

Cancels all outstanding I/O

Detaches all attached regions, except in the case of a
fixed
task
in a system that supports the memory management
directives, where no detaching
takes place
(see Section
3.3 .. 2)

Frees the task's memory if the task is not fixed

10.

Transmits exit status to and disconnects from
tasks

(Files open for

write

Chapter
Time

access

all

requests

may

connected

If the Executive rejects a directive, it usually does not clear or set
any specified event flag.
Thus, the task may wait indefinitely if it
indiscriminately executes a Wait For directive corresponding
to a
previously issued Mark Time directive that the Executive has rejected.
Care should always be taken
to ensure that a directive has been
completed successfully.

1.3

ERROR RETURNS

As stated above,
RSX-llM/M-PLUS associate the error codes with
mnemonics that report the cause of the error.
In the text of the
manual, the mnemonics are used exclusively.
The macro DRERR$, which
is expanded
in Appendix B,
provides a correspondence between each
mnemonic and its numeric value.
Appendix B also gives the meaning of each error code.
In
each
directive
description
in
Chapter
6 contains
directive-related interpretations of the error codes.

1-3

addition,
specific,

USING SYSTEM DIRECTIVES
1.4

USING THE DIRECTIVE MACROS

Before issuing a directive, the Macro-11 programmer has to decide how
to create the DPB. The method depends on whether it is a question of
reentrant code or non-reentrant code. With reentrant code, the DPB is
created on the stack at run time (see Section 1.4.1.3, which dBscribes
the $S form of directive).
With non-reentrant code,
the DPB is
created
in a data section at assembly time (see Sections 1.4.1.1 and
1.4.1.2, which describe the $ form and $C form respectively).
Figures 1-1 and 1-2 illustrate the alternative directives and
show the relationship between the stack pointer and the DPB.

•

also

•
# ADDR,-(SP)

MOV
EMT

DPB

377

DPB
ITEMS
SP----

ADDRESS OF DPB

SIZE

DIC

INCREASING
MEMORY
ADDRESSES

STACK
GROWTH

l
Figure 1-1

Directive Parameter Block (DPB) Pointer on the Stack

1-4

USING SYSTEM DIRECTIVES

MOV

'-"''

•

XX,-(SP)
PUSH REQUIRED
DPB ITEMS ON THE
STACK IN
REVERSE ORDER

MOV
.BYTE
EMT

(PC)+,-(SP)
DIC,SIZE
377

DPB
ITEMS

•
SP

SIZE

DIC

INCREASING
MEMORY
ADDRESSES

STACK
GROWTH

!
Figure~

1.4.l

1-2

Directive Parameter Block (DPB) on the Stack

Macro Name Conventions

To use system directives, a MACR0-11 programmer
includes directive
macro calls in programs.
The macros for the RSX-llM directives are
contained in the System Macro Library (LB:[l,l]RSXMAC.SML).
To make
the macros available to a program, the programmer issues the .MCALL
assembler directive.
The .MCALL arguments are the names of all the
macros used in the program.
For example:
CALLING DIRECTIVES FROM THE SYSTEM MACRO LIBRARY
AND ISSUING THEM •
• MCALL

MRKT$S,WTSE$S

Additional .MCALLs or code

MRKT$S
WTSE$S

#1,#1,#2,,ERR
#1

;MARK TIME FOR 1 SECOND
;WAIT FOR MARK TIME TO COMPLETE

Macro names consist of up to four letters, followed by a dollar sign
($)
and, optionally, a C or an s. The optional letter or its absence
specifies which of three possible macro expansions the programmer
wants to use.

1-5

USING SYSTEM DIRECTIVES
1.4.1.1 $ Form - The $ form is useful for a directive operation that
is
to be
issued several
times from different locations
in a
non-reentrant program segment.
This
form
produces
only
the
directive's DPB,
and must be
issued
from a data section of the
program.
The code for actually executing a directive that is in the $
form
is produced by a
special macro,
DIR$ (discussed in Section
1.4.2).
Because execution of the directive is separate from
the directive's DPB:

the

creation

issued

only

once

A $ form of a given directive needs to be
(to produce its DPB).

A DIR$ macro associated with a given directive can be
issued
several
times without incurring the cost of generating a DPB
each time it is issued~

It is easy to access and change the directive's parameters by
labeling
the
start of the DPB and using the offsets defined
by the directive.

•
•

When a program issues the
$ form of macro call,
the
parameters
required
for DPB construction must be valid expressions for MACR0-11
data storage instructions (such as .BYTE,
.WORD,
and
.RADSO).
The
programmer can alter individual parameters in the DPB.
This might be
done, for example, if the directive is to be used many times with
varying parameters.

1.4.1.2 $C Form - Programmers should use the $C form when a directive
is to be issued only once, and the program segment does not need to be
reentrant.
The $C form eliminates the need to push the DPB
(created
at assembly time)
onto
the
stack at run time.
Other parts of the
program, however, cannot access the DPB because
the DPB address
is
unknown.
(Note, in the $C form macro expansion of Section 1.4.5, that
the DPB address $$$ is redefined by the new value of the assembler's
location counter each time an additional $C directive is issued.)
The $C form generates a DPB in a separate
p-sectionl called $DPB$$.
The DPB is first followed by a return to the user-specified p-section,
then by an instruction to push the DPB address onto
the stack,
and
finally by an EMT 377.
To ensure that the program reenters the
correct p-section, the user must specify the p-section name
in the
argument list
immediately following
the DPB parameters.
If the
argument is not specified, the program reenters the blank
(unnamed)
p-section.
This form also accepts an optional final argument that specifies the
address of a routine to be called (by a JSR instruction) if an error
occurs during the execution of the directive (see Section 1.4.2).
When a program issues the $C form of a macro call,
the
parameters
required
for DPB construction must be valid expressions for MACR0-11
data storage instructions (such as .BYTE, .WORD, and
.RADSO).
(This
is not true for the p-section argument or the error routine argument,
which are not part of the DPB.)

1 Refer to the IAS/RSX-11 MACR0-11 Programmer's Reference Manual
a description of p-sections (program sections).

1-6

for

•

USING SYSTEM DIRECTIVES
1.4.1.3 $S Form - Program segments that need to be reentrant should
use
the $S form.
Only the $S form produces the DPB at run time. The
other two forms produce the DPB at assembly time.
In this form, the macro produces code to push a DPB onto
the stack,
followed
by an EMT 377.
In this case, the parameters must be valid
source operands for MOV-type instructions.
For a 2-word Radix-50 name
parameter,
the argument must be the address of a 2-word block of
memory containing the name.
Note
that the Stack Pointer
{or any
reference to the Stack Pointer)
should not be used
to address
directive parameters when the $S form is used.l {In the example
in
Section 1.4.1, the error routine argument ERR is a target address for
a JSR instruction;
see Section 1.4.3.)

•
1.4.2

DIR$ Macro

The DIR$ macro allows the programmer to execute a directive with a DPB
predefined
by the $ form of a directive macro.
This macro pushes the
DPB address onto the stack and issues an EMT 377 instruction.
The DIR$ macro generates an RSX-llM Executive trap using a
DPB:
Macro Call:

DIR$

predefined

adr,err

adr and err are optional
adr

is the address of the DPB.
{The address,
if specified,
must be a valid source address for a MOV instruction.) If
this address is not specified, the DPB or
its address
must be on the stack.

err

is the address of the error return {see Section 1.4.3).
If this error
return is not specified, an error simply
sets the carry bit in the Processor Status word.
NOTE
DIR$ is not a $ form macro, and does not
behave as one.
There are no variations
in the spelling of this macro.

1.4.3

Optional Error Routine Address

The $C and $S forms of macro calls and the DIR$ macro can accept an
optional final argument;
note that the DIR$ macro is not an Executive
Directive {DIR$C and DIR$S are not valid macro calls).
The argument
must be a valid assembler destination operand that specifies the
address of a user error routine.
For example, the DIR$ macro
DIR$

#DPB,ERROR

1 Subroutine or macro calls can use the stack for temporary storage,
thereby destroying
the positional
relationship between SP and the
parameters.

1-7

USING SYSTEM DIRECTIVES
generates the following code:
MOV
EMT
BCC
JSR

#DPB,-(SP)
377
.+6
PC,ERROR

Since the $ form of a directive macro does not generate any executable
code, it does not accept an error address argument.

Symbolic Offsets

1.4.4

Most system directive macro calls generate local
symbolic offsets
describing
the
format of the DPB.
The symbols are unique to each
directive, and each is assigned an index value corresponding to the
number of bytes offset
into the DPB that a given DPB element is
located.
Because the offsets are defined symbolically, the programmer who must
refer
to or modify DPB elements can do so without knowing the offset
values.
Symbolic offsets also eliminate the need to rewrite programs
if a future release of RSX-llM changes a DPB specification.
All $ and $C forms of macros that generate DBPs longer than one word
generate local
offsets.
All
informational directives (see Section
6.1.3), including the $S form, generate local symbolic offsets for the
parameter block returned as well.
If the program uses either the $ or $C form and has defined the symbol
$$$GLB
(for example $$$GLB=O),
the macro generates the symbolic
offsets as global symbols and does not generate the DPB
itself.
The
purpose of this facility is to enable the use of a DPB defined in a
different module.
The symbol $$$GLB has no effect on the expansion of
$S macros.
When symbolic offsets are used, the use of the $ form of directives is
recommended.

Examples of Macro Calls

1.4.5

The examples below show the expansions of
forms.
1.

the

different

macro

call

The $ form generates a DPB only, in the current p-section.
MRKT$

1,5,2,MTRAP

generates the following code:
.BYTE
.WORD
.WORD
.WORD
.WORD
2.

23 • t 5
1

5
2

MT RAP

"MARK-TIME" DIC & DPB SIZE
EVENT FLAG NUMBER
TIME: INTERVAL MAGNITUDE
TIME INTERVAL UNIT (SECONDS)
AST ENTRY POINT

The $C form generates in p-section $DPB$$ a DPB, and
specified section, the code to issue the directive.
MRKT$C

1,5,2,MTRAP,PROGl,ERR

1-8

the

USING SYSTEM DIRECTIVES
generates the following code:
.PSECT
$$$=:.
• BY'I'E
.WORD
.WORD
.WORD
.WORD
.PSE:CT
MOV
EMT
BCC
JSR

"-".

$DPB$$
23.,5
.1
5
2
MT RAP
PROGl
#$$$,-(SP)
377
.+6
PC,ERR

DEFINE TEMPORARY SYMBOL
"MARK-TIME" DIC & DPB SIZE
EVENT FLAG NUMBER
TIME INTERVAL MAGNITUDE
TIME INTERVAL UNIT (SECONDS)
AST ENTRY POINT ADDRESS
RETURN TO THE ORIGINAL PSECT
PUSH DPB ADDRESS ON STACK
TRAP TO THE EXECUTIVE
BRANCH ON DIRECTIVE ACCEPTANCE
ELSE, CALL ERROR SERVICE ROUTINE

The $S form generates code to push the DPB onto the stack and
to issue the directive.
MRK'I'$S

#l,#5,#2,R2,ERR

generates the following code:
MOV
MOV
MOV
MOV
MOV
• BY'I'E
EMT
BCC
JSR
4.

R2,-(SP)
#2,-(SP)
#5,-(SP)
#1,- (SP)
(PC)+,-(SP)
23.,5
377
.+6
PC,ERR

PUSH AST ENTRY POINT
TIME INTERVAL UNIT (SECONDS)
TIME INTERVAL MAGNITUDE
EVENT FLAG NUMBER
AND "MARK-TIME" DIC & DPB SIZE
ON THE STACK
TRAP TO THE EXECUTIVE
BRANCH ON DIRECTIVE ACCEPTANCE
ELSE, CALL ERROR SERVICE ROUTINE

The DIR$ macro issues a directive that has a predefined DPB.
Rl,(R3)

; DPB ALREADY DEFINED.

DPB ADDRESS IN Rl.

generates the following code:
MOV
EMT
BCC
JSR

1.5

Rl,-(SP)
377
.+4
PC,(R3)

PUSH DPB ADDRESS ON STACK
TRAP TO THE EXECUTIVE
BRANCH ON DIRECTIVE ACCEPTANCE
ELSE, CALL ERROR SERVICE ROUTINE

FORTRAN SUBROUTINES

RSX-llM/M-PLUS provide an extensive set
perform system directive operations.

FORTRAN

The directive descriptions in Chapter 6 describe
subroutine calls, as well as the macro calls.

subroutines
the

FORTRAN

The FORTRAN subroutines fall into three basic groups:
1.

Subroutines based on the Instrument Standard of America (ISA)
Standard ISA 62~1
These subroutines are included in the
subroutine descriptions associated with the macro calls
(see
Chapter 6).

Subroutines designed to use and control specific process
control
interface devices supplied by DIGITAL and supported
by the RSX-llM/M-PLUS operating systems.

1-9

USING SYSTEM DIRECTIVES
3.

Subroutines for performing RSX-llM/M-PLUS system directive
operations
In general,
one subroutine is available for
each directive.
(Exceptions are the Mark Time and Run
directives.
The description of Mark Time includes both CALL
MARK and CALL WAIT.
The description of Run
includes both
CALL RUN and CALL START.)

All the subroutines described in this manual can be called by
programs compiled by either
the FORTRAN
IV or FORTRAN
compiler.

FORTRAN
IV-PLUS

These subroutines can also be called
from
programs written
in the
MACR0-11 assembly language by using PDP-11 FORTRAN calling sequence
conventions.
These conventions are described
in the
IAS/RSX-11
FORTRAN IV User's Guide and in the FORTRAN IV-PLUS user's Guide.

Subroutine Usage

1.5.1

All the subroutines described in this manual are added to the RSX-llM
system object module library when either FORTRAN compiler is generated
for RSX-llM.
To use one of these subroutines, the programmer includes
the appropriate CALL statement in the FORTRAN program. When the
program is linked to form a task, the Task Builder first checks to see
whether each specified subroutine is user-defined.
If a subroutine is
not user-defined, the Task Builder automatically searches for
it
in
the
system object module library.
If the subroutine is found, it is
included in the linked task.

1.5.1.1 Optional Arguments - Many of the subroutines described
in
this manual
have optional arguments.
In the subroutine descriptions
associated with the directives, optional arguments are designated as
such by being enclosed in square brackets ([]).
An argument of this
kind can be omitted if the comma that immediately follows
it is
retained.
If the argument (or string of optional arguments) is last,
it can simply be omitted, and no comma need end
the argument list.
For example, the format of a call to SUB could be the following~
CALL SUB (AA,[BB],[CC],DD[,[EE][,FF]])
In that event, programmers may omit the arguments BB, CC, EE,
in one of the following ways:
•

CALL SUB (AA,,,DD,,)

•

CALL SUB (AA,,,DD)

and

In some cases,
a
subroutine will
use a default value
for
an
unspecified optional argument.
Such default values are noted in each
subroutine description in Chapter 6.

1.5.1.2 Task Names - In FORTRAN subroutines, task names may be up to
six characters long.
Characters permitted
in a task name are the
letters A through
Z,
the numerals O through 9 and. the special
characters dollar sign ($) and period (.).
Task names are stored as
Radix-50 code, which permits up to three characters from the set above
to be encoded in one PDP-11 word.
(Radix-50 is described in detail in
the IAS/RSX-11 FORTRAN IV User's Guide and the FORTRAN IV-PLUS User's
Guide.)
-

1-10

•

USING SYSTEM DIRECTIVES
FORTRAN subroutine calls require that a task name be defined as a
variable of type REAL that represents the task name as Radix-50 code.
This variable may be defined at program compilation time by a DATA
statement,
which gives the real variable an initial value (a Radix-50
constant).
For example, if a task name CCMFl is to be used in a system
c~ll, the task name could be defined and used as follows:

directive

DATA CCMF1/5RCCMF1/

•

CALL REQUES

(CCMFl)

Task names may also be defined during execution by using
the
IRAD50
subroutine or the RAD50
function as described
in the IAS/RSX-11
FORTRAN IV user's Guide or the FORTRAN IV-PLUS User's Guide.

1.5.1.3 Integer Arguments - All the
subroutines described
in this
manual
assume
that integer
arguments are INTEGER*2 type arguments.
Both the FORTRAN IV and FORTRAN
IV-PLUS systems normally treat an
integer variable as one PDP-11 storage word, provided that its value
is within the range -32768 to +32767.
However,
if the
programmer
specifies the /I4 option switch when compiling a program, particular
care must be taken to ensure that all integer arguments used in these
subroutines are explicitly specified as type INTEGER*2.

1.5.1.4 GETADR Subroutine - Some subroutine calls include an argument
described as an integer array.
The integer array contains some values
Since the
that are the addresses of other variables or arrays.
FORTRAN language does not provide a means of assigning such an address
as a value, programmers should use
the GETADR subroutine described
below.
Calling Sequence:

c ALL GET AD R ( i pm , [ a r g 1 ] ' [ a r g 2 ] ' ••• [ a r g n] )
ipm

is an array of dimension n.

argl, ••• argn

be
are arguments whose addresses are
to
inserted in ipm.
Arguments are inserted in the
is
order
specified.
If a
null
argument
specified,
then the corresponding entry in ipm
is left unchanged.

Example:
DIMENSION IBUF(80) ,IOSB(2) ,IPARAM(6)

...
CALL GETADR (IPARAM(l) ,IBUF(l))
IPARAM(2)=80
CALL QIO (IREAD,LUN,IEFLAG,IOSB,IPARAM,IDSW)

1-11

USING SYSTEM DIRECTIVES
In this example, CALL GETADR enables the programmer to specify
buffer address in the CALL QIO directive (see Section 6.3.39).

1.5.2

The Subroutine Calls

Table 1-1 is a list of the FORTRAN subroutine calls (and corresponding
macro calls)
associated with system directives (see Chapter 6 for
detailed descriptions).
For some directives, notably Mark Time (CALL MARK), both the. standard
FORTRAN-IV subroutine call
and
the ISA standard call are provided.
Other directives, however, are not available to FORTRAN tasks
(for
example, Specify Floating Point Exception AST [SFPA$] and Specify SST
Vector Table For Task [SVTK$]).

•

Table 1-1
FORTRAN Subroutines and Corresponding Macro Calls
Directive

Macro Call

FORTRAN Subroutine

Abort Task

ABRT$

CALL ABORT

Alter Priority

ALTP$

CALL ALTPRI

Assign LUN

ALUN$

CALL ASNLUN

Attach Region

ATRG$

CALL ATRG

Cancel Time Based
Initiation Requests

CRSQ$

CALL CAN ALL

Cancel Mark
Time Requests

CMKT$

CALL CANMT

Clear Event Flag

CLEF$

CALL CL REF

Connect

CNCT$

CALL CNCT

Create Address Window

CRAW$

CALL CRAW

Create Group Global
Event Flags

CRGF$

CALL CRGF

Create Region

CRRG$

CALL CRRG

Declare Significant Event

DECL$S

CALL DE CLAR

Disable AST Recognition

DSAR$S

CALL DSASTR

Disable Checkpointing

DSCP$S

CALL DISCKP

Detach Region

DTRG$

CALL DTRG

Eliminate Address Window

ELAW$

CALL ELAW
(continued on next pag1e)

1-12

USING SYSTEM DIRECTIVES
Table 1-1 (Cont.)
FORTRAN Subroutines and Corresponding Macro Calls
Directive

Macro Call

FORTRAN Subroutine

Eliminate Group Global
E:vent Flags

ELGF$

CALL ELGF

Enable AST Recognition

ENAR$S

CALL ENASTR

Enable Checkpointing

ENCP$S

CALL ENACKP

Exit If

EXIF$

CALL EXITIF

Exit With Status

EXST$

CALL EXST

Extend •rask

EXTK$

CALL EXTTSK

Get LUN Information

GLUN$

CALL GETLUN

Get Mapping Context

GMCX$

CALL GMCX

Get MCR Command Line

GMCR$

CALL GETMCR

Get Partition Parameters

GPRT$

CALL GETPAR

GREG$

CALL GETREG

Get Sense Switches

GSSW$S

CALL READSW
CALL SSWTCH

Get Task Parameters

GTSK$

CALL GETTSK

Get Time Parameters

GTIM$

Several subroutines
available (see the
appropriate FORTRAN
User's Guide)

Inhibit AST Recognition

IHAR$S

CALL INASTR

Map Address Window

MAP$

CALL MAP

Mark Time

MRKT$

CALL MARK
CALL WAIT (ISA Standard
call)

Queue I/O Request

QIO$

CALL QIO

Queue I/O Request And Wait

QIOW$

CALL WTQIO

Read All Event Flags

RDAF$
RDXF$

CALL
READEF
(Only
a
single, local, common, or
group-global
event flag
can be read by a
FORTRAN
task)

Get Region

Paramete~s

(continued on next page)

1-13

USING SYSTEM DIRECTIVES

FORTRAN

Table 1-1 (Cont.)
and Corresponding Macro Calls

Su~routines

Directive

Macro Call

FORTRAN Subroutine

Receive By Reference

RREF$

CALL RREF

Receive Data

RCVD$

CALL RECEIV

Receive Data Or Exit

RCVX$

CALL RECOEX

Receive Data Or Stop

RCST$

CALL RCST

Request

RQST$

CALL REQUES

Resume

RSUM$

CALL RESUME

Run

RUN$

CALL RUN
CALL START (ISA Standard
call)

Send By Reference

$REF$

CALL $REF

Send Data

SDAT$

CALL SEND

SDRC$

·STAF$
Set Event Flag

SETF$

CALL SETEF

Spawn

SPWN$

CALL SPAWN

Specify Power Recovery AST

SFPA$

EXTERNAL SUBNAM
CALL PWRUP (SUBNAM)
(to establish an AST)
CALL PWRUP
(to remove an AST)

Stop

STOP$S

CALL STOP

Stop For Logical OR Of
Event Flags

STLO$

CALL STLOR

Stop For Single Event Flag

STSE$

CALL STOPFR

Suspend

SPND$S

CALL SUSPEND

Task Exit

EXIT$S

CALL EXIT

Unmap Address Window

UMAP$

CALL UNMAP

Unstop

USTP$

CALL USTP

VRCD$

VRCX$
(continued on next page)

1-14

USING SYSTEM DIRECTIVES
Table 1-1 (Cont.)
FORTRAN Subroutines and Corresponding Macro Calls
Directive

Macro Call

FORTRAN Subroutine

CALL WAITFR
For Logical OR Of
Flags

WTLO$

CALL WFLOR

For Significant Event

WSIG$S

CALL WFSNE

NOTE
The
following
directives
are
available as FORTRAN subroutines:
Directive

1.5.3

not

Macro Call

AST Service Exit

ASTX$S

Connect To Interrupt Vector

CINT$

Specify Floating Point
Exception AST

SFPA$

Specify Receive By Reference AST

SRRA$

Specify Receive Data AST

SRDA$

Specify SST Vector Table For
Debugging Aid

SVDB$

Specify SST vector Table
For Tasks

SVTK$

Error Conditions

Each subroutine call includes an optional argument that specifies the
integer to receive the Directive Status Word (ids). When a programmer
specifies this argument, the subroutine returns a value that indicates
whether the directive operation succeeded or failed.
If the directive
failed, the value indicates the reason for the failure.
The possible
values are the same as those returned to the' Directive Status Word
(DSW) in MACR0-11 programs (see Appendix B), except for
the
two
ISA
calls,
CALL WAIT and CALL START.
The ISA calls have positive numeric
error codes (see Sections 6.3.38 and 6.3.50).

1-15

USING SYSTEM DIRECTIVES
In addition, two types of error are reported by means of the FORTRAN
Object Time System (OTS) diagnostic messages. Both of these errors
result in the termination of the task. The error conditions ar~:

1.6

SYSTEM DIRECTIVE: MISSING AHGUMENT(S)
This message indicates that at least one necessary argument
was missing from a call to a system directive subroutine (OTS
error number 100).

SYSTEM DIRECTIVE: INVALID EVENT FLAG NUMBER
This message indicates that an event flag number in a call to
WFLOR (Wait For Logical OR Of Event Flags) was not in the
range l to 96 (OTS error number 101).

TASK STATES

Many system directives cause a task to change from one state to
another. There are two basic task states in RSX-llM/M-PLUS -- dormant
and active. The active state has three substates
ready-to-run,
blocked, and stopped.
The Executive recognizes the existence of a task on~y after it has
been successfully installed and has an entry in the System Task
Directory (STD).
(Task installation is the process whereby a task is
made known to the system;
see the RSX-llM/M-PLUS MCR Operations
Manual.) Once a task has been installed, it is either dormant or
active. These states are defined as follows:
1.

Dormant -- Immediately following the processing of an Install
command by the Monitor Console Routine, a task is known to
the system, but is dormant. A dormant task has an entry in
the STD, but no request has been made to activate it.

Active -- A task is active from the time it is requested
until the time it exits. Requesting a task means issuing the
RQST$, RUN$, SPWN$, or SJ.?BC$: macro, or an MCR Run command.
An active task is eligible for scheduling, whereas a dormant
task is not.
The three substates of an active task are as follows:
a. Ready-to-run -- A ready-to-run task competes with other
tasks for CPU time on the basis of priority. The highest
priority ready-to-run task obtains CPU time and thus
becomes the current task.
b. Blocked -- A blocked task is unable
time for synchronization reasons
resource is not available.
Task
remains unchanged, allowing the task
space.

to compete for CPU
or because a needed
priority effectively
to compete for memory

c. Stopped -- A stopped task is unable to compete for CPU
time because of pending 1/0 completion, event flag(s) not
set, or because the task stopped itself. When stopped, a
task's priority effectively drops to zero and the task can
be checkpointed by any other task, regardless of that
task's priority.
If an AST occurs for the stopped task,
its normal task priority is restored only for the duration
of the AST routine execution; once the AST is completed,
task priority returns to zero.

1-16

USING SYSTEM DIRECTIVES
Task State Transitions

1.6.1

Dormant to Active - The following commands
Executive to activate a dormant task:
•

A RUN$ directive

•

A RQST$ directive

•

A SPWN$ directive·

•

An MCR Run command

Ready-to-Run to Blocked
The following
ready-to-run task to become blocked:

directives

events

cause

active,

•

A SPND$ directive

•

An unsatisfied Wait For condition

•

Checkpointing of a task out of memory by the Executive

Ready-to-Run to Stopped
The
following
ready-to-run task to become stopped:

events

cause

the

active,

•

A STOP$S directive is executed, or an RCST$
is issued when no data packet is available

directive

•

Specified conditions for directive event flag STLO$
are not met

•

A checkpointable task issues a terminal input requestl

Blocked to Ready-to-Run - The following events return a
to the ready-to-run state:

blocked

•

A RSUM$ directive issued by another task

•

An MCR Resume command

•

A Wait For condition is satisfied

•

The Executive reads a checkpointed task into memory

STSE$

task

Stopped to Ready-to-Run - The following events return a
stopped task
to the ready-to-run state, depending upon how the task became stopped:

•

directive

•

A task stopped via
the STOP$S,
RCST$,
or
becomes unstopped via USTP$ directive execution •

•

A task stopped
for
buffered . I/O becomes
completion of the requested I/O transaction.

•

A task stopped for an event flag (or flags) becomes unstopped
when the specified event flag (or flags) becomes (or become)
set.

unstopped

1 Only in systems that support the checkpointing of tasks during
terminal
input.
A task can be stopped for buffered I/O only when not
at AST state, the task is checkpointable, and the region in which I/O
is being done to/from is checkpointable.

1-17

USING SYSTEM DIRECTIVES
•

An MCR Unstop command is issued.

•

Terminal input for a checkpointable task completes.l

Active to Dormant - The following
become dormant:

events

cause

active

•

An EXIT$S, EXIF$,
RCVX$,
or .·VRQX'S:'\directive,
directive that specifies the exit option

•

An ABRT$ directive

•

An MCR Abort command

•

A Synchronous System Trap (SST)
specified a service routine

task

RREF$

not

To remove an installed task from the system, the user issues the
Remove
command
from
a
privileged
terminal.
Refer
to
RSX-llM/llM-PLUS MCR Operations Manual.

MCR
the

1.7

which

has

1.6.2

for

task

Removing an Installed Task

THE GENERAL INFORMATION DIRECTIVE

The General
Information Directive
is used by some of DIGITAL's
software modules to obtain information from Executive data structures
without being directly mapped to the Executive.
Since this directive
may
change
from
release
to
release of RSX-llM/M-PLUS,
it
is
specifically not documented in this manual.
However,
advanced
users
desiring to use this directive can refer to module DRGIN.MAC and macro
GIN$ in the Executive macro
library.
Although the directive may
operate
in the
same manner
in
future
releases, its operation is
specifically not guaranteed, and users are cautioned accordingly.

1.8

DIRECTIVE RESTRICTIONS FOR NONPRIVILEGED TASKS

Certain Executive directives cannot be issued by nonprivileged
except as listed below:
Directive
Abort Task

Macro Call

Comments

ABRT$

1 Only in systems that support
terminal input.

tasks,

In systems
that
support
multiuser
protection,
a
nonprivileged task can only
abort tasks with
the same
TI:
as the task issuing the
directive.

the

1-18

checkpointing

tasks

during

USING SYSTEM DIRECTIVES
Directive

Macro Call

Comments

Alter Priority

ALTP$

In systems
that
support
multiuser
protection,
a
nonprivileged task can only
alter
its own priority to
values less than or equal to
the
task's
installed
priority.

Cancel Time Based
Initiation Requests

CSRQ$

Cannot
be
issued
by a
nonprivileged
task
in
systems
that
support
multiuser protection except
for
tasks with the same TI:
as the issuing task.

Connect To interrupt
Vector

CINT$

Cannot
be
issued
by a
nonprivileged task in mapped
systems.

1-19

CHAPTER 2

SIGNIFICANT EVENTS, SYSTEM TRAPS, AND STOP-BIT SYNCHRONIZATION

This chapter
introduces the concept of significant events
and
describes the ways in which a programmer can make use of event flags,
synchronous
and
asynchronous
system
traps,
and
stop-bit
synchronization.

2.1

SIGNIFICANT EVENTS

A significant event is a change
in system status that causes the
Executive to reevaluate the eligibility of all active tasks to run.
A
significant event is usually caused (either directly or indirectly) by
a
system directive
issued
from within a task.
Significant events
include the following:

•

An I/O completion

•

A task exit

•

The execution of a Send Data directive (see Section 6.3.52)

•

The execution of a Send By Reference or a Receive By Reference
directive (see Sections 6.3.62 and 6.3.48)

•

The execution of an
6.3.2)

•

The removal of an entry from the clock queue
(for
instance,
resulting
from
the execution of a Mark Time directive or the
issuance of a rescheduling request)

•

The execution of a Declare Significant
Section 6.3.15)

•

The execution of the round-robin scheduling algorithm
end of a round-robin scheduling interval

The execution of an Exit, an Exit
v directive

•

2.2

Alter

Priority

_tit'

directive

With

Event

(see

Section

directive

Status,

(see
the

EVENT FLAGS

Event flag~ are a means by which tasks
recognize specific events.
(Tasks also use Asynchronous System Traps (ASTs) to recognize specific
events.
See Section 2.3.3.) In requesting a system operation (such as
an I/O transfer),
a
task may associate an event flag with the
completion of the operation. When the event occurs,
the Executive

2-1

SIGNIFICANT EVENTS, SYSTEM TRAPS, AND STOP-BIT SYNCHRONIZATION
sets the specified flag.
Several examples later in this section
describe how t~sks can use event flags to coordinate task execution.
Ninety-six event flags are available to enable tasks to distinguish
one event from another.
Each event flag has a corresponding unique
Event Flag Number (EFN). Numbers 1 through 32 form a group of flags
that are unique to each task and are set or cleared as a result of
that task's operation. Numbers 33 through 64 form a second group of
flags
that are common to all tasks, hence their name "common flags."
Common flags may be set or cleared as a
result of any task's
operation.
The last eight flags in each group, local flags (25-32)
and common flags (57-64), are reserved for use by the system. Numbers
65 through 96 form the third group of flags, known as "group-global
event flags." These flags can be used in any application where common
event flags can be used;
however, they can only be used by tasks
running under UICs containing the 9roup code specified when the
group-global event flags were created. Three directives (Create Group
Global Event Flags,
Eliminate Group Global Event Flags and Read
Extended Event Flags) provide the Executive support for implementing
group-global event flags.
Tasks can use the common flags for intertask communication or their
own local event flags internally.
The setting, clearing, and testing
of event flags can be performed by using Set Event Flag (SETF$), Cleat
Event Flag (CLEF$), and Read All Event Flags (RDAF$) directives.
(The
Read All Event Flags directive will not return the group-global event
flags.
When these flags are in use, read all event flags usin9 the
Read Extended Event Flags (RDXF$) directive.)
Programmers must take great care when setting or clearing event flags,
especially common flags.
Erroneous or multiple setting and clearing
of event flags can result
in obscure software faults.
A typical
application program can be written without explicitly accessing or
modifying event flags, since many of the directives can
implicitly
perform these functions.
The Send Data (SDAT$), Mark Time (MRKT$),
and the I/O operations directives can all implicitly alter an event
flag.
Examples 1 and 2 below illustrate the use of common event flags
(33-64)
to synchronize task execution.
Examples 3 and 4 illustrate
the use of local flags (1-32).
Example 1
Task B clears common event flag 35 and then blocks itself by
issuing a Wait For directive that specifies common event flag 35.
Subsequently another task, Task A, specifies event flag 35 in a
Set Event Flag directive to inform Task B that it may proceed.
Task A then issues a Declare Significant Event directive to
ensure that the Executive will sche~ule Task B.

•

Example 2
In order to synchronize the transmission of data between Tasks A
and B, Task A specifies Task B and common event flag 42 in a Send
Data directive.
Task B has specified flag 42 in a Wait For directive. When Task
A's Send Data directive has caused the Executive to set flag 42
and to cause a significant event, Task B proceeds and
issues a
Receive Data directive because its Wait For condition has been
satisfied.

2-2

SIGNIFICANT EVENTS, SYSTEM TRAPS, AND STOP-BIT SYNCHRONIZATION
Example 3
A task contains a Queue I/O Request directive and an associated
Wait For directive;
both directives specify the same local event
flag.
When the task queues its I/O request, the Executive clears
the local flag.
If the requested I/O is incomplete when the task
issues the Wait For directive, the Exec~tive blocks the task.
When the requested I/O has been completed, the Executive sets the
local flag and causes a significant event.
The task then resumes
its execution at the
instruction that follows
the Wait For
directive.
Using
the local
event flag in this manner ensures
that the
task does not manipulate
incoming data
until
the
transfer is complete.
Example 4
A task specifies the same local event flag in a Mark Time and an
associated Wait For directive.
When the Mark Time directive is
issued,
the Executive
first clears
the
local
flag
and
subsequently sets it when
the
indicated
time
interval has
elapsed.
~·

If the task issues the Wait For directive before the local
flag
has been set, the Executive blocks the task, which resumes when
the flag is set at the end of the proper time interval.
Specifying an event flag does not mean that a Wait For directive must
be
issued.
Event flag
testing can be performed at any time.
The
purpose of a Wait For directive is to stop task execution until
an
indicated event occurs.
Hence, it is not necessary to issue a Wait
For directive immediately following a Queue I/O Request directive or a
Mark Time directive.
If a task issues a Wait For directive that specifies an event flag
that
is already set, the blocking condition is immediately satisfied
and the Executive immediately returns control to the task.
Tasks can issue Stop For Logical OR Of Event Flags directives
instead
of Wait For directives.
When this is done, an event flag condition
not satisfied will result in the task being stopped instead of being
blocked until the event flag(s) is/are set.
The simplest way to test a single event flag is to issue the directive
CLEF$ or SETF$.
Both these directives can cause the following return
codes:
IS.CLR -

Flag was previously clear

IS.SET - Flag was previously set

...

For example, if a set common event flag indicates the completion of an
operation, a task can issue the CLEF$ directive both to read the event
flag and simu1taneously to reset it for the next operation.
If the
event
flag
was
previously
clear
(the current operation was
incomplete), the flag remains clear.

2.3

SYSTEM TRAPS

System traps are
transfers of control
(also
called
software
interrupts) that provide tasks with a means of monitoring and reacting
to events.
The Executive initiates system traps when certain events

2-3

SIGNIFICANT EVENTS, SYSTEM TRAPS, AND STOP-BIT SYNCHRONIZATION
occur.
The trap transfers control to the task associated with the
event and gives the task the opportunity to service the event by
entering a user-written routine.
There are two kinds of system traps:
•

Synchronous System Traps iSSTs) -- SSTs detect events directly
associated with the execution of program instructions. They
are synchronous because they always recur at the same point in
the
program
when trap-causing
instructions occur.
For
example, an illegal instruction causes an SST.

•

Asynchronous System Traps (ASTs) -- ASTs detect events that
occur asynchronously to the task's .execution. That is, the
task has no direct control over
the precise time that the
event,
hence,
the trap, may occur. The completion of an I/O
transfer may cause an AST to occur, for example.

A task that uses the system trap facility issues system directives
that establish entry points for user-written service routines.
Entry
points for SSTs are specified in a single table.
AST entry points are
set by individual directives for
each kind of AST. When a trap
condition occurs,
the task automatically enters the appropriate
routine (if its entry point has been specified).

Synchronous System Traps (SSTs)

2.3.1

SSTs can detect the execution of:
•

Illegal instructions

•

Instructions with invalid addresses

•

Trap instructions (TRAP, EMT, !OT, BPT)

•

FIS floating-point exceptions (PDP-11/40 only)

The user can set up an SST vector table, containing one entry per SST
type.
Each entry is the address of an SST routine that services a
particular type of SST (a routine that services illegal
instructions,
for example). When an SST occurs, the Executive transfers control to
the routine for that type of SST.
If a corresponding routine
is not
specified in the table, the task is aborted. The SST routine enables
the user to process the failure and then return to the
interrupte~
code.
Note that if a debugging aid and the user's task both have an
SST vector enabled for a given condition, the debugging aid vector
is
referenced first to determine the service routine address.
SST routines must always be reentrant because an SST can occur within
the SST routine itself.
Although the E~ecutive initiates SSTs, the
execution of the related service routines is indistinguishable from
the task's normal execution.
An AST or another SST can therefore
interrupt an SST routine.

2.3.2

SST Service Routines

The Executive initiates SST service routines by pushing the task's
Processor
Status
(PS),
Program Counter
(PC),
and trap-specific
parameters onto the task's stack. After removing
the trap-specific
parameters, the service routine returns control to the task by issuing

2-4

SIGNIFICANT EVENTS, SYSTEM TRAPS, AND STOP-BIT SYNCHRONIZATION
an RTI or RTT instruction.
Note that the task's general purpose
registers RO-R6 are not saved.
If the SST routine makes use of them,
it must save and restore them itself.
To the Executive, SST routine execution is indistinguishable from
normal task execution, so that all directive services are available to
an SST routine.
An SST routine can remove the interrupted PS and PC
from the stack and transfer control anywhere in the task;
the routine
does not have to
return control
to the point of
interruption.
However,
programmers should remember that any operations performed by
the routine (such as the modification of registers or the DSW, or the
setting or clearing of event flags) remain in effect when the routine
eventually returns control to the task.

A trap vector table within the task contains all the service routine
entry pointso
The user specifies the SST vector table by means of the
Specify SST vector Table For Task directive or the Specify SST vector
For Debugging Aid directive. The trap vector table has the following
format:
word O

Odd or nonexistent memory address error
(Also,
on
some PDP-11 processors for
example,
PDP-11/45 an
illegal instruction traps here rather
than through
WO rd 04.)

WO rd

Memory protect violation

WO rd

T-bit trap or execution of a BPT instruction

word 3

Execution of an IOT instruction

word 4

Execution of a reserved instruction

word 5

Execution of a non-RSX EMT instruction

word 6

Execution of a TRAP instruction

word 7

Synchronous floating-point exception (PDP-11/40 only)

A zero appearing in the table means that no entry point is specified.
An odd address
in the table causes an SST to occur when another SST
tries to use that particular address as an entry point.
If an SST
occurs and
an associated entry point is not specified in the table,
the Executive aborts the task.
Depending on the reason for the SST, the task's stack may also contain
additional information, as follows:
Memory protect violation (complete stack)
SP+lO
SP+06
SP+04
SP+02
SP+OO

PS
PC
Memory protect status register (SRO)l
Virtual PC of the faulting instruction (SR2)1
Instruction backup register (SRl)l

TRAP instruction or EMT other than 377 (and 376 in the case
unmapped tasks and mapped privileged tasks) (complete stack}
SP+04

1 For details of SRO, SRl, and SR2, see the section on the
management unit in the appropriate PDP-11 Processor Handbook.

2-5

memory

SIGNIFICANT EVENTS, SYSTEM TRAPS, AND STOP-BIT SYNCHRONIZATION
SP+02
SP+OO

PC
Instruction operand (low-order byte) multiplied by
non-sign-extended

All items except the PS and PC must be removed from the
the SST service routine exits.

2.3.3

stack

before

Asynchronous System Traps (ASTs)

The primary purpose of an AST is to inform the task that a certain
event has occurred, for example, the completion of an I/O operation.
As soon as the task has serviced the event,
it can return to the
interrupted code.
Some directives can specify both an event flag and an AST;
with these
directives, ASTs can be used as an alternative to event flags or the
two can be used together.
This capability enables the user to specify
the same AST routine for several directives, each with a different
event flag.
Thus, when the Executive passes control
to
the AST
routine, the event flag can determine the action required.
AST service routines must save and restore all registers used.
If the
registers are not restored after an AST has occurred, the task's
subsequent execution may be unpredictable.
Although not able to distinguish execution of an SST routine from task
execution,
the Executive
is aware that a task is executing an AST
routine.
An AST routine can be interrupted by an SST routine, but not
by another AST routine.
The following notes describe general characteristics and uses of ASTs:
•

If an AST occurs while the related task is executing, the task
is
interrupted so that the AST service routine can be
executed.

•

If an AST occurs while another AST is being processed,
the
Executive queues the latest AST (First-In-First-Out or FIFO)
and then processes the next AST in the queue when the current
AST service is complete (unless AST recognition was disabled
by the AST service routine).

•

If a task is suspended when an associated AST occurs, the task
remains suspended after
the AST routine has been executed,
unless it is explicitly resumed either by the AST service
routine
itself,
or by another task (the MCR Resume command,
for example).

•

If an AST occurs while the related
task
is waiting
for
an
event flag
to be set
(a Wait For directive),
the task
continues to wait after execution of the AST service routine
until
the AST service routine itself or another task sets the
appropriate event flag.

•

If an AST occurs for a checkpointed task, the Executive queues
the AST
(FIFO),
brings the task into memory,
and then
activates the AST when the task returns to memory.
When a checkpointed task is brought back
into memory,
the
Executive
issues an AST for
the task if its receive queue
contains one or more entries.
This
practice
prevents
checkpointed tasks from losing receive ASTs.

2-6

SIGNIFICANT EVENTS, SYSTEM TRAPS, AND STOP-BIT SYNCHRONIZATION
•

If a task is stopped when an AST occurs, it becomes unstopped
for the AST and becomes stopped after the AST routine has been
executed. The stopped task can be explicitly unstopped either
by the AST service routine itself, by another task, or by an
MCR command.

•

An optional RSX-llM feature that is always
in RSX-llM-PLUS
allows the checkpointing of tasks during terminal input. When
this feature is included, the Executive stops the execution of
a checkpointable task when the terminal driver receives an
input request for the task.
The task resumes execution when
the
terminal
input has finished.
A stopped task can execute
an AST service routine if an AST occurs; , but the task remains
stopped after
the routine finishes unless the terminal input
has finished in the meantime.
Note,
however,
that an AST
routine
itself can reactivate the stopped task by issuing an
I/O Kill function for the task's terminal input request.

•

The Executive allocates the necessary dynamic memory when an
AST is specified.
Thus, no AST condition lacks dynamic memory
for data storage when it actually occurs.

•

Two directives,
Disable AST Recognition and Enable
AST
Recognition,
allow ASTs to be queued for subsequent execution
during critical sections of code.
(A critical
section might
be one that accesses data bases also accessed by AST service
routines, for example.) If ASTs occur while AST recognition is
disabled,
they are queued (FIFO) and then processed when AST
recognition is enabled.

2.3.4
~·

AST Service Routines

When an AST occurs, the Executive pushes the task's Wait For mask
word,
the DSW,
the PS,
and
the PC onto the task's stack.
This
information saves the state of the task so that the AST service
routine has access to all
the available Executive services.
The
preserved Wait For mask word allows the AST routines to establish the
conditions necessary to unblock the waiting task.
Depending on the
reason for the AST, the stack may also contain additional
parameters.
Note
that the
task's general purpose registers RO-R6 are not saved.
If the routine makes use of them,
it must save and
restore them
itSE~lf.

The Wait For mask word comes from the offset H.EFLM in the
task's
header.
Its value and the event flag range to which it corresponds
depend on the last Wait For Single Event Flag or Wait For Logical OR
Of Event Flags directive issued by the task.
For example, if the last
such directive issued was Wait For Single Event Flag 42, the mask word
has a value of 1000(8) and the event flag range is from 33 to 48.
Bit
O of the mask word represents flag 33, bit 1 represents flag
34,
and
so on.
The Wait For mask word is meaningless
either type of Wait For directive.

the

task

has

not

issued

After processing an AST,
the task must
remove the
trap-dependent
parameters from
its stack;
that is, everything from the top of the
stack down to, but not including, the task's Directive Status Word.
It must then issue an AST Service Exit directive with the stack set as
indicated in the description of that directive
(see Section 6.3.4).
When the AST service routine exits, it returns control to one of two
places:
another AST, or the original task.

2-7

SIGNIFICANT EVENTS, SYSTEM TRAPS, AND STOP-BIT SYNCHRONIZATION
There are eleven variations on the format
follows:
1.

the

task's

stack,

If a
task needs to be notified when a Floating Point
Processor exception trap occurs, it issues a Specify Floating
Point Processor Excep~ion AST directive.
If the
task
specifies this directive, an AST will occur when a Floating
Point Processor exception trap occurs.
The stack will
contain the following values:
SP+l2
SP+lO
SP+06
SP+04
SP+02
SP+OO

Event flag mask word
PS of task prior to AST
PC of task prior to AST
Task's Directive Status Word
Floating exception code
Floating exception address
NOTE
Refer to the
appropriate
Processor
Handbook for a description of the FPU
exception code values.

If the task needs to be notified of power failure recoveries,
it issues a Specify Power Recovery AST directive.
An AST
will then occur when the power is restored if the task is not
checkpointed. The stack will contain the following values:
SP+06
SP+04
SP+02
SP+OO

If a task needs to be notified when it receives either a
message or a reference to a common area, it issues either a
Specify Receive Data AST or a Specify Receive By Reference
AST directive.
An AST will occur when the message or
reference is sent to the task.
The stack will contain the
following values:
SP+06
SP+04
SP+02
SP+OO

Event flag mask word
PS of task prior to AST
PC of task prior to AST
Task's Directive Status Word

When a
task queues an I/O request and
specifies
an
appropriate AST service entry point, an AST will occur upon
completion of the I/O request. The task's stack will contain
the following values:
SP+lO
SP+06
SP+04
SP+02
SP+OO

Event flag mask word
PS of task prior to AST
PC of task prior to AST
Task's Directive Status Word

Event flag mask word
PS of task prior to AST
PC of task prior to AST
Task's Directive Status Word
Address of I/O status block for
(or zero if none was specified)

I/O

request

When a task issues a Mark Time directive and specifies an
appropriate AST service entry point, an AST will occur when
the indicated time interval has elapsed.
The task's stack
will contain the following values:

2-8

SIGNIFICANT EVENTS, SYSTEM TRAPS, AND STOP-BIT SYNCHRONIZATION

SP+lO
SP+06
SP+04
SP+02
SP+OO

'-"'
6.

Event flag mask word
PS of task prior to AST
PC of task prior to AST
Task's Directive Status Word
Event flag number
(or zero
specified)

none

was

An offspring task, connected via a Spawn, Connect,
or Send,
Request
And
Connect directive,
returns status to the
connected (parent) task(s) upon exit via the Exit AST.
The
parent task's stack contains the following values:
SP+lO
SP+06
SP+04
SP+02
SP+OO

Event flag mask word
PS of task prior to AST
PC of task prior to AST
Task's Directive Status Word
Address of exit status block

2-9

SIGNIFICANT EVENTS, SYSTEM TRAPS, AND STOP-BIT SYNCHRONIZATION

11.

If a task issues a QIO IO.ATA function to the
full-duplex
terminal driver,
unsolicited
terminal input will cause AST
service routine entry with the task's stack containing the
following values:
SP+lO
SP+06
SP+04
SP+02
SP+OO

Event flag mask word
PS of task prior to AST
PC of task prior to AST
Task's Directive Status Word
Unsolicited character in low byte;
2 in the high byte

2-10

parameter

SIGNIFICANT EVENTS, SYSTEM TRAPS, AND STOP-BIT SYNCHRONIZATION
2.4

STOP-BIT SYNCHRONIZATION

Stop-bit synchronization allows tasks to be checkpointed during
terminal
input or while waiting for an event to occur.
(For example,
an event flag to become set or an Unstop directive to become ;issued.)
Synchronization between tasks can be controlled through the s~tting of
the task's Task Control Block (TCB) stop bit.
When the task's stop bit is set, the
task
is blocked
from
further
execution,
its priority for memory allocation effectively drops to
zero, and it may be checkpointed by any other task
in the system,
regardless of priority.
If checkpointed,
the task remains out of
memory until its stop bit is cleared, at which time the
task becomes
unstopped, its normal priority for memory allocation becomes restored,
and it is considered for memory allocation based on the
restored
priority.
If the stopped task receives an AST, it becomes unstopped
until
it
exits the AST routine.
Memory allocation for the task during the AST
routine is based on the task's priority prior to
the stopped
state.
Note that a task cannot be stopped when an AST is in progress, but the
AST routine can issue either an Unstop or Set Event Flag directive
to
reference the task, causing it to remain unstopped after it issues the
AST Service Exit directive.
There are three ways in which a nonprivileged task can become stopped
and
corresponding ways
to become unstopped.
Only one method for
stopping a task can be applied at a time.
1.

A task can stop itself for buffered I/9 by issuing
request
to the terminal driver,

n@.·'fi,.
:<~.·~;·:

b~·>·st:a··

input

·~~~;;~M,.]'.·®'.~'.~:i:.:::.

'h'.~h~:~:-~\f.
<· •t':l've·. ··•• The task
I/O
can only ~e unstopped by the -~~mpl~tlon of th~ · bu1fered
request.

A task can be stopped for event flag(s) by issuing
the Stop
For Single Event Flag directive or the Stop For Logical OR Of
Event Flags directive.
In this case, the task can only be
unstopped by setting the specified event flag(s).

A task can be stopped by issuing a Stop or
the Receive Or
Stop directive.
In this case, the task can only be unstopped
by issuing the Unstop directive.

A task cannot be stopped when an AST
directives that can cause a task to
AST state.
If buffered I/O requests
state,
the driver does not stop
request is dequeued.

is in progress (AST state).
become stopped are illegal at
occur when the task is at the
the task or buffer its I/O if

Any
the
AST
the

When a task is stopped for any reason at the task state, it can still
receive ASTs.
If the task has been checkpointed, it becomes eligible
for entrance back into memory when an AST is queued for it.
The task
retains
its normal priority in memory while it is at the AST state or
has ASTs queued.
Once ~t has exited the AST routine with no other
ASTs queued,
the
task
is again stopped and effectively has zero
priority for memory allocation.
Six directives can be used for stop-bit synchronization:
•

Stop - This directive stops the issuing
issued at the AST state.

2-11

task

and

cannot

SIGNIFICANT EVENTS, SYSTEM TRAPS, J\ND STOP-BIT SYNCHRONIZATION
•

Receive Data or Stop and variable Receive.baJ;.a Or ~tQp·:- These
directives attempt to dequeue send data packets from the
specified task (or any task if none is specified).
If there
is no such packet to be dequeued, the issuing task is stopped.
These directives cannot be issued at the AST state.

•

Stop For Logical OR Of Event Flags - This directive stops the
issuing task until the specified flags in the specified group
of local event flags become set.
If any of the specified
event flags are already set, the task does not become stopped.
This directive cannot be issued at the AST state.

•

Stop For Single Event Flag - This directive stops the
issuing
task until the indicated local event flag becomes set.
If the
specified event flag is already set, the task does not become
stopped. This directive cannot be issued at the AST state.

•

Unstop - This directive unstops a task that has become stopped
via the Stop or Receive Or Stop directive.

2-12

CHAPTER 3

MEMORY MANAGEMENT DIRECTIVES

Within the framework of memory management directives,
this chapter
discusses the concepts of extended logical address space, regions, and
virtual address windows.

3.1

ADDRESSING CAPABILITIES OF AN RSX-llM TASK

Without overlaying of tasks, an RSX-llM task cannot explicitly refer
to a location with an address greater than 177777 (32K words).
The
16-bit word size of the PDP-11 imposes this restriction on a
task's
addressing capability. Overlaying a task means that it must first be
divided into segments:
a single root segment, which is always
in
memory,
and any number of overlay segments, which can be loaded into
memory as required.
Unless an RSX-llM task uses the memory management
directives described
in this chapter, the combined size of the task
segments concurrently in memory cannot exceed 32K words.
When resident task segments cannot exceed a total of 32K words, a task
requiring
large amounts of data must access data that reside on disk.
Data are disk-based not only because of limited memory space but also
because transmission of large amounts of data between tasks is only
practical via disk.
An overlaid task, or a task that needs to access
or· transfer large amounts of data, incurs a considerable amount of
transfer activity over and above that caused by the task's function.
Task execution could obviously be faster if all or a greater portion
of the
task were resident in memory at run time.
RSX-llM includes a
group of memory management directives that provide the task with this
capability.
The
directives
overcome
the
32K-word addressing
restriction by allowing the task to dynamically change the physical
locations that are referred to by a given range of addresses.
With
these directives, a task can increase its execution speed by reducing
its disk I/O requirements, at the expense of increased physical memory
requirements •

•

'-"''
3-1

MEMORY MANAGEMENT DIRECTIVES
3.1.1

Address Mapping

In a mapped system, the user does not need to know where a task
resides in physical memory. Mapping, the process of associating task
addresses with available physical memory, is transparent to the user
and is accomplished by the KTll memory management hardware.
(See the
appropriate PDP-11 Processor Handbook for a description of the KTll.)
When a task references a location (virtual address), the KTll
determines the physical address in memory.
The memory management
directives use the KTll to perform address mapping at a level that is
visible to and controlled by the user.

3.1.2

Virtual and Logical Address Space

The two concepts defined below, virtual address space and logical
address space, provide a basis for understanding the functions
performed by the memory management directives:
•

Virtual Address Space -- A task's virtual address
space
corresponds to the 32K-word address range imposed by the
PDP-ll's 16-bit word length. The task can divide its virtual
address space into segments called virtual address windows
(see Section 3.2).

•

Logical Address Space -- A task's logical address space is the
total amount of physical memory to which the task has access
rights. The task can divide its logical address space into
various areas called regions (see Section 3.3). Each region
occupies a contiguous block of memory.

If the capabilities supplied by the RSX-llM memory
management
directives were not available, a task's virtual address space and
logical address space would directly correspond;
a single virtual
address would always point to the same logical location. Both types
of address space would have a maximum size of 32K words. However, the
ability of the memory management directives to assign or map a range
of virtual addresses (a window) to different logical areas (regions)
enables the user to extend a task's logical address space beyond 32K
words.
~:.·:

:.>··:: . . . . . : .·: .·. ·: ·:·:. . ;:_._: · . ·: : ._. .:. . ·:. ,;.-: :- : : .:- ~. :-: : ·: . . . . :·.:_·'.

<·:.·:. ·:"·. ~·.: ·.. ·' .· ..-:.

· . . r · ] ··.it.l}

• .·3J~J.3 :· $u.P:erv+~or Mode• Addres$ln9

. >Ri?*l}ijj'.~JPLus · ·.~~ppcirt~ . •pop~ll ... proc~s::;9rs·· .<fapabt~:

·J!Stil)~p 1.f'i$0( •rn·o~e •...•.• •.• TheSupeJ{yispr 1JlOd1~ .•ts on.~ .o.f •. t:~.f.'.~:~:;;

·.·. f99.er1· . K.er:~el.1: ctnd'St.JPe.J:"v iso.r} ..... in · wMcb··. ·thos.e· sy$tern·i;;r q

·,-:J}J:le'J:>·tf\.odei#i.~Jg.ht<·.aCtiVe.
·'··<~ddtt§.s

::',em

page

(egis.ter~ ..... (~f)~$). <Ci.pi ..

n1a!)pirrg · o·f <user . tasks.
Note . tha~ .ipnl}' ~~·~i
py.~d tn .U$er mode .. for ·.both instructio.nsarfd O.q:t;~;

,;:.~ci:~e.~!~tjsdf ;;~od~ .su~p~}t.d6ubles the

i11str~ctio~· ... , ....
i'l'l'iis. is ··because . sixteen: .Al?Rs :Celgbt"
·,:~ight Slip~ryif>or m9(je .. r~spaceJ. are · ava Bable. tor; :;~e.tff~~:§>
:·::cprit;.~n~s +.Pf; ·tJS~r \tnode: . . . r..-space A.PRs. are copied>lfrt()· ?·.·

::-"•~af3.~p<.

<J).~.sp~<;:~J\l'~9·~.~p·;,:..a1.i<:>w!:.Supervisor .mode. :ro.utines ... t9·•· . . :~ff9~~s::'.:;
;'.):l.~~9:-:: .(R~~er; '. to·< t:he <appropriate ·. PDp•ll •.· Pro(J~8:sp .•r';! n
.::,po~Pt;~t~ cl~sc:rJpt.ion ... of a¢iclress mappinq.·, .• ·•mem8J'.Y'.:roill·l1~9~·m. ~,

·. v,a.• ~J<;l98: ·~RB reg}stersL.

3-2

· ·

MEMORY MANAGEMENT DIRECTIVES
3.2

VIRTUAL ADDRESS WINDOWS

In order to manipulate the mapping of virtual
addresses to various
logical
areas,
the
user must
first divide a task's 32K of virtual
address space
into segments.
These segments are called virtual
address windows.
Each window encompasses a continuous
range of
virtual addresses, which must begin on a 4K word boundary
(that
is,
the
first address must be a multiple of 4K).
The number of windows
defined by a task can vary from 1 to 7 (as discussed below, window 0
is not available to the user).
The size of each window can range from
a minimum of 32 words to a maximum of 32K.
A task that
includes directives to manipulate address
windows
dynamically must have window blocks set up in its task header.
The
Executive uses window blocks to identify and describe each currently
existing window. When linking the task, the programmer specifies the
required number of window blocks to be set up by the Task Builder (see
the RSX-llM/M-PLUS Task Builder Reference Manual).
The number of
blocks should equal the maximum number of windows that will
exist at
any one time when the task is running.
A window's identification is a number from O to 7 ,>:-(-$<F;_i. "td i~,'.~{5fk::'( - fP:t'':
:,;-,}i:fi#?i~!\~ )~)'(\;~~ which is an index to the wi~~io~·~-s -c~rresponding
window b ock.
The address window identified by O is the window that
maps
the
task's
header
and
root segment.
The Task Builder
automatically creates window O, which is mapped by the Executive and
cannot. be specified in any directive.

>:$-~:i~l.~;¥,;\ir

Figure 3-1 shows the virtual address space of a task divided into four
address windows
(windows O, 1, 2, and 3). The shaded areas indicate
portions of the address space that are not included in any window
(9K
to
12K and
23K to
24K).
Addresses that fall within the ranges
corresponding to the shaded areas cannot be used.
When a task uses memory management directives, the Executive views the
relationship between the task's virtual and logical address space in
terms of windows and regions.
Unless a virtual address is part of an
existing address window,
reference to
that address will cause an
illegal address trap to occur.
Similarly, a window can be mapped only
to an area that is all or part of an existing region within the task's
logical address space (see Section 3.3).
Once a task has defined the necessary windows and
regions,
it can
issue memory management directives to perform operations such as the
following:
•

Map a window to all or part of a region.

•

Unmap a window from one region in order to map it
region.

•

Unmap a window from one part of a region in order to map it to
another part of the same region.
NOTE
It is currently possible for a task with
outstanding
I/O to unmap from a region
(although
it
cannot
detach
from
it -- see Section 3.3.2).
Because this
feature may be impossible to support
in
future
releases of the system, it is
recommended
that
users
consider
carefully
before
designing
an
application based on this capability.
3-3

another

MEMORY MANAGEMENT DIRECTIVES

VIRTUAL.
ADDRESS
SPACE

.------.-32K

3 (8K)

WINDOW3

28K

.ummnrnrnrnn 24 K
20K
WINDOW 2

2 (11 K)
16K

12K

BK
WINDOW 1

1 (5K)
4K

WINDOW 0

0 (4K)

=virtual address
window
= unused virtual
address space

Figure 3-1

Virtual Address Windows

REGIONS

3. 3

A region is a portion of a physical memory to which a
task has
(or
potentially may have) access to.
The current window-to-region mapping
context determines that part of a task's logical address space that
the
task can access at one time.
A task's logical address space can
consist of various ~ypes of regions:

'.-~~--~· ··~;-·,

(

~:.'·:-_;·.·p:~

;--... ~·~::;-

•

Task Region -- A contiguous block of memory in which the
runs.

task

•

Static Common Region -- An area defined by an operator at run
time or at system generation time, such as a global common
area.

•

Dynamic Region -- A region created dynamically at run time
issuing the memory management directives.

. ·~Na t"a~le.. B~~1·9n .·..•. . . r~•9(]~p.nJ Pe>t~•ton 6e' . fit4~···
A. • .

Y·.

>et~~··.·. +n.·.9ha;r·~ble. r.e9lons •. ·.. (~SX-:llM~PLU,S· <>l1:l,•yJ:~.··

·"'·
3-4

MEMORY MANAGEMENT DIRECTIVES
Tasks refer to a region by means of a region ID returned to the task
by the Executive. Region ID O always refers to a task's task region.
Region ID 1 always refers to the read-only
(pure code)
portion of
multiuser
tasks.
All other region IDs are actually addresses of the
attachment descriptor maintained by the Executive
in the system
dynamic storage area.
Figure 3-2 shows a sample collection of regions that could make up a
task's logical address space at some given time. The header and root
segment are always part of the task region. Since a region occupies a
contiguous area of memory, each region is shown as a separate block.
Figure 3-3 illustrates a possible mapping
relationship
windows and regions shown in Figures 3-1 and 3-2.

3.3.1

between

the

Shared Regions

Address mapping not only extends a task's logical address space beyond
32K words, it also allows the space to extend to regions that have not
been linked to the task at task-build time.
·one result
is an
increased potential for task interaction by means of shared regions.
For example, a task can create a dynamic region to accommodate large
amounts of data.
Any number of tasks can then access that data by
mapping to the region.
Another result is the ability of tasks to use
a greater number of common routines.
Thus, tasks can map to required
routines at run time, rather than linking to them at task-build time.

3.3.2

Attaching to Regions

Attaching is the process by which a region becomes part of a task's
logical address space. A task can map only a region that is part o(
the task's logical address space. There are three ways to attach a
task to a region:
1.

All tasks are automatically attached
linked to them at task-build time.

regions

A task can issue a directive to attach itself
static common region or a named dynamic region.

A task can request the Executive to attach another specified
task to any region within the logical address space of the
requesting task.

that

are

named

Attaching identifies a task as a user of a
region and prevents the
system from deleting a region until all user tasks have been detached
from it.
(It should be noted that fixed tasks do not automatically
become detached from regions upon exiting.)

•

3-5

MEMORY MANAGEMEN'I' DIRECTIVES

LOGICAL
ADDRESS
SPACE

Figure 3-2

3-6

Regions

"''

MEMORY MANAGEMENT DIRECTIVES

LOGICAL
ADDRESS
SPACE
.......

. ···'

-5K{·-~

~8K{~0.~
VIRTUAL
ADDRESS
SPACE
32K

WINDOW 3

3 (BK)

2BK

rrn mmr.mn rn

24K

20K
WINDOW 2

2 (11 K)
16K

WINDOW1

11 K

12K

1 (5K)

-------- 4K
WINDOW.fl

)J'(4K)
K
Legend:

[~ = vi ~tual address

r•
•

------

~= logical address space
mapped areas of

window

t=]

unused virtual
address space

pointer to area
mapped by a window

Figure 3-3

unmapped portions of
logical address space

Mapping Windows to Regions

3-7

MEMORY MANAGEMENT DIRECTIVES
NOTE
When sending and receiving data
by
reference,
each
Send
By Reference
directive issued by a sending
task
creates a new attachment descriptor for
the receiving task, although multiple
Send By Reference directives referencing
the same region
only
require
one
attachment
descriptor.
After
the
receiving task issues a
series
of
Receive By Reference directives and all
pending
data
requests
have
been
received, the task should detach the
region in order to return the attachment
descriptors to the pool.

~P*~.i.lM~P4tr$.·.·~·Y? te.rn~J'··.i~ /!· ·~·.· · · · · ·.· f>c£~s.~Bl~;·>•
ayo.ict··.·ml11,pi.p~e .

attachmept .·...(l~.f:>C~~p~

:wheri,> sending ... and r~<?•~ivi#9· ·.aa~a.·.. :;
~~r~n.c.e •.. ,.· setting . ·. ·. tl)e \'/'§··:~1\'l' ~iJ·~
'··.·····.·.· . ~ .. Wi n8()W· pescr lptor B:Lqck.·.··. (.$e~·>s~e.~~

· <3 •.~. (~)....· ·..... 9c:ru~es. the Ex~cutiye.··.• to ··PF~a:te~
· ·~~./ . . ~t:t.~p.~ment g~$c::J.iP~?r ·. . ·.·~e>.r: J.>

e<1·¢.qn·.· 011ly .l~. · ne.ces:iary· (~p~t }~·.
:/~h~.··1;.~~~··.ls.curnmtl,y not ~.;ttac}1e:4 .. :.;
'th~ :x~g>~<:>n> •

Region Protection

3.3.3

A task cannot indiscriminately attach to any region. Each region has
a protection mask to prevent unauthorized access. The mask indicates
the types of access (read, write, extend, delete)
allowed for each
category of user (system, owner, group, world). The Executive checks
that the requesting task's User Identification Code (UIC) allows it to
make the attempted access. The attempt fails if the protection mask
denies that task the access it wants.
To determine when tasks can attach to regions outside their logical
address space, the following points must be considered.
(Note that
all considerations presume there is no protection violation.):
•

Any task can attach to a named dynamic region, so long as it
knows the name. In the case of an unnamed dynamic region, a
task can attach to the region only after receiving a Send By
Reference directive from the task that created the region •

.¥: ~~~+1•1•~LptQ§<·f:·~···.~·J{·•;··~a·n·.··.··. ·1··s·s·de·;•••··~·········s~n~··•>:a.~·r.·~~·f:~:· . ···~t~.'.·.·t.::• . . . .·. ·.·. ·.· ,.,. ·.· ·

t!:l·J:1otf;ie,; .>t~s.k ,t;;q any. r~g}ipn~ HRSX-llM tasks can do
same thing except that the task region itself may not be
one of the regions involved. The reference sent includes the
access rights with which the receiving task attaches to the
region. The sending task can only grant access rights that it
has itself.
t~e

•

·~~·t·1?c}1

Any task can map to a named static common region.

3-8

MEMORY MANAGEMENT DIRECTIVES
3.4

DIRECTIVE SUMMARY

This section briefly describes the function of each memory
directive.

3.4.1

management

Create Region Directive (CRRG$)

The Create Region directive creates a dynamic region in a designated
system-controlled partition and optionally attaches the issuing task
to it (see Section 6.3.12}.

3.4.2

Attach Region Directive (ATRG$)

The Attach Region directive attaches the
issuing task to a
static
common region or to a named dynamic region (see Section 6.3.5}.

3.4.3

Detach Region Directive (DTRG$)

The Detach Region directive detaches the issuing task from a specified
region.
Any of the task's address windows that are mapped to the
region are automatically unmapped (see Section 6.3.18}.

3.4.4

Create Address Window Directive (CRAW$)

The Create Address Window directive creates an address window,
establishes its virtual address base and size, and optionally maps the
window.
Any other windows that overlap with the range of addresses of
the new window are first unmapped and then eliminated (see Section
6.3.10}.

3.4.5

Eliminate Address Window Directive (ELAW$)

The Eliminate AddrE~ss Window directive eliminates an existing
window, unmapping it first if necessary (see Section 6.3.19}.

3.4.6

address

Map Address Window Directive (MAP$)

The Map Address Window directive maps an existing window to an
attached
region.
The mapping begins at a specified offset from the
start of the region and goes to a specified length.
If the window is
already mapped elsewhere, the Executive unmaps it before carrying out
the map assignment described in the directive (see Section 6.3.37}.

3.4.7

Unmap Address Window Directive (UMAP$)

The Unmap Address Window directive unmaps a specified window.
After
the window has been unmapped,
its virtual address range cannot be
referenced until
the task
issues another mapping directive
(see
Section 6.3.70}.

3-9

MEMORY MANAGEMENT DIRECTIVES

3.4.8

Send By Reference Directive (SREF$)

The Send By Reference directive inserts a packet containing a
reference to a region into the receive queue of a specified task. The
receiver task is automatically attached to the region referred to (see
Section 6. 3. 62).

3.4.9

Receive By Reference Directive (RREF$)

The Receive By Reference directive requests the Executive first to
select the next packet from the receive-by-reference queue of the
issuing task, and then to make the information in the packet available
to the task.
Optionally the directive can map a window to the
referenced region or cause the task to exit if the queue does not
contain a receive-by-reference packet (see Section 6.3.48).

3.4.10

Get Mapping Context Directive (GMCX$)

The Get Mapping Context directive causes the Executive to return to
the issuing task a description of the current window-to-region mapping
assignments. The description is in a form that enables the user to
restore the mapping context through a series of Create Address Window
directives (see Section 6.3.31).

3.4.11

Get Region Parameters Directive (GREG$)

The Get Region Parameters directive causes the Executive to supply the
issuing task with information about either its task region (if no
region ID is given) or an explicitly specified region (see Section
6.3.33).

3.5

USER DATA STRUCTURES

Most memory management directives are individually
capable
of
performing a number of separate actions. For example, a single Create
Address Window directive can unmap and eliminate up to
seven
conflicting address windows, create a new window, and map the new
window to a specified region.
The complexity of the directives
requires a special means of communication between the user task and
the Executive. The communication is achieved through data structures
that:
•

allow the task to specify which directive options it wants the
Executive to perform

•

permit the Executive to provide the task
the outcome of the requested actions

with

details

about

There are two types of user data structures that correspond to the two
key
elements (regions and address windows) manipulated by the
directives. The structures are called:
•

The Region Definition Block (RDB)

•

The Window Definition Block (WDB)

3-10

MEMORY MANAGEMENT DIRECTIVES

'"-"'

Every memory management directive, except Get Region Parameters,
uses
one of these structures as its communications area between the task
and the Executive.
Each directive issued includes
in the Directive
Parameter Block
(DPB) a pointer to the appropriate definition block.
Symbolic address offset values are assigned by the task,
pointing
to
locations within an RDB or a WDB.
The task can change the contents of
these locations to define or modify the directive operation.
After
the
Executive has carried out the specified operation, it assigns
values to various locations within the block to describe the actions
taken and
to provide the task with information useful for subsequent
operations~

,_,,.

3.5.1

Region Definition Block {RDB)

Figure 3-4 illustrates the format of an RDB.
In addition to
the
symbolic offsets defined
in the diagram,
the region status word,
R.GSTS, contains defined bits that may be set or cleared by the
Executive or the
task.
(RSX-llM reserves undefined bits for future
expansion.) The bits and their definitions follow.
Definition

Bit
RS.CRR=.100000

Region was successfully created.

RS.UNM=40000

At least one window was unmapped on a detach.

RS.MDL=200

Mark region for deletion on last detach.

RS.NDL=lOO

Created
region is not
deletion on last detach.

RS.ATT=40

Attach to created region.

RS.NEX=20

Created region is not extendable.

RS.DEL=lO

Delete access desired on attach.

RS.EXT=4

Extend access desired on attach.

RS.WRT=2

Write access desired on attach.

RS.RED=l

Read access desired on attach.

The three memory management directives that require a
RDB are:

marked

pointer

for

Create Region (CRRG$)
Attach Region (ATRG$)
Detach Region (DTRG$)
When a task issues one of these directives, the Executive clears the
four high-order bits in the region status word of the appropriate RDB.
After completing the directive operation,
the Executive sets the
RS.CRR or RS.UNM bit to indicate to the task what actioris were taken.
The other bits are never modified by the Executive.

3-11

MEMORY MANAGEMENT DIRECTIVES

Array
Element

Symbolic
Offset

irdb (1)

R.GID

Byte
Offset
0

Block Format

REGION

2
irdb (2)

R.GSIZ

SIZE OF

REGION

(32W BLOCKS)
4

irdb (3)
R.GNAM

NAME OF

REGION

(RAD50)

irdb (4)

10
irdb (5)
R.GPAR

REGION'S MAIN PARTITION NAME (RAD50)

irdb (6)
14
irdb (7)

R.GSTS

REGION STATUS WOF:D
16

irdb (8)

R.GPRO

REGION PROTECTION WORD
'

Figure 3-4

Region Definition Block

3.5.1.1 Using Macros to Generate an RDB - RSX-llM provides two
macros,
RDBDF$
and RDBBK$,
to generate and define an RDB.
RDBDF$
defines the offsets and status word bits for a
region definition
block;
RDBBK$
then creates the actual region definition block. The
format of RDBDF$ is:
RDBDF$
Since RDBBK$ automatically invokes RDBDF$, the programmer need only
specify RDBBK$
in a module that creates an RDB.
The format of the
call to RDBBK$ is:
RDBBK$

siz,nam,par,sts,pro

siz

the region size in 32-word blocks

nam

the region name (RADSO)

par

the name of the partition in which to create
(RADSO)

where

3-12

...

the

region

MEMORY

MANAGEMEN~l'

DIRECTIVES

sts

bit definitions of the region status word

pro

the region's default protection word

The sts argument sets specified bits in the status word
argument normally has the following format:

R.GSTS.

The

<bitl [1 ••• !bitn] >
where bit is a defined bit to be set.
The argum~nt pro is an octal number.
The 16-bit binary
specifies the region's default protection as follows:
Bits 15

12 11

8 7

GROUP

[WORLD

3
[DELETE

4 3

I OWNER I SYSTEM

Each of the four categories above
representing a type of access:
Bit

equivalent

has

EXTEND

WRITE

READ

four

bits,

with

each

bit

A bit value of zero indicates that the specified type of access is to
be allowed;
a bit value of one indicates that the specified type of
access is to be denied.
The macro call:
RDBBK$

102.,ALPHA,GEN,<RS.NDL1RS.ATT!RS.WRT1RS.RED>,167000

exp.ands to:
.WORD
.WORD
.RAD50
.RAD50
.WORD
.WORD
.WORD

102"
/ALPHA/
/GEN/
0

RS.NDL!RS.ATT!RS.WRT!RS.RED
167000

If a Create Region directive pointed to the RDB defined by this
expanded macro call, the Executive would create a region 102 (decimal)
32-word blocks in length, named ALPHA, in a partition named GEN.
The
defined bits specified in the sts argument tell the Executive:

•

Not to mark the region for deletion on the last detach

•

To attach region ALPHA to the task issuing the directive macro
call

•

To grant read and write access to the attached task

The protection word specified as 167000
(octal)
assigns a default
protection mask to the region.
The octal number, which has a binary
equivalent of 1110111000000000, grants all types of access to system
and owner tasks (0000), and read access only to group and world tasks
(1110).
If the Create Region directive is successful, the Executive will fir~t
return to the issuing task a region ID value in the location accessed
by symbolic offset R.GID, and then will set the defined bit RS.CRR in
the status word R.GSTS.
3-13

MEMORY MANAGEMEN'f DIRECTIVES
3.S.1.2 using FORTRAN to Generate an RDB - FORTRAN programmers must
create an 8-word, single-precision integer array as the ROB tQ be
supplied in the subroutine calls:
CALL ATRG
CALL CRRG
CALL DTRG

(Attach Region directive)
(Create Region directive)
(Detach Region directive)

(See the PDP-11 FORTRAN Language Reference Manual for
information
the creation of arrays.) An RDB array has the following format:
Word

Contents

irdb(l)

Region ID

irdb(2)

Size of the region in 32-word blocks

irdb(3)
irdb(4)

Region name (2 words in Radix-SO format)

irdb(S)
irdb(6)

Name of the partition that contains the region
(2 words in Radix-SO format)

irdb(7)

Region status word (see
this list)

irdb(8)

Region protection code

the

paragraph

following

The FORTRAN programmer modifies the region status word,
irdb(7),
by
setting or clearing the appropriate bits.
See the list in Section
3.S.l that describes the defined bits.
The bit values are listed
alongside the symbolic offsets.
Note that Hollerith text strings can be converted to Radix-SO values
by calls to the FORTRAN library routine IRADSO (see the appropriate
FORTRAN User's Guide).

3.S.2

Window Definition Block (WDB)

Figure 3-S illustrates the format of a WDB. The block consists of a
number of symbolic address offsets to specific WDB locations. One of
the locations is the window status word, W.NSTS, which contains
defined bits that can be set or cleared by the Executive or the task.
(RSX-llM reserves all undefined bits for future expansion.)
The bits
and their definitions follow.
Bit

Definition

WS.CRW=lOOOOO

Address window was successfully created.

WS.UNM=40000

At least one window was unmapped by a Create
Address Window, Map Address Window, or Unmap
Address Window directive.

WS.ELW=20000

At least one window was eliminated
in a
Create Address Window or Eliminate Address
Window directive.

WS.RRF=lOOOO

Reference was successfully received.

3-14

MEMORY MANAGEMENT DIRECTIVES
Bit

•

'-"''

Definition

WS.RES=2000

Map only if resident.

WS.64B=400

Defines the
task's
permitted
boundaries
0 for
256-word
alignment, 1 for 32-word (64-byte)

WS. MAP=:200

Window is to be mapped in a
Create Address
Window or Receive By Reference directive.

WS. RCX=:l 00

Exit if no references to receive.

WS .DEL=:lO

Send with delete access.

WS. EXT=:4

Send with extend access.

WS .WHT==2

Send with write
access.

WS. RED==l

Send with read access.

A.rray
Element

Symbolic
Offset

access

Block Format

map

alignment
(512-byte)
alignment.

with

write

Byte
Offset

0
·~

ivvdb (1)

W.NID
W.NAPR

BASE APR

WINDOW ID

2
ivvdb (2)

W.NBAS

VIRTUAL BASE ADDRESS (BYTES)
4

iwdb (3)

W.NSIZ

WINDOW SIZE (32W BLOCKS)
6

.........
ivvdb (4)

W.NRID

REGION

ID
10

ivvdb (5)

W.NOFF

OFFSET IN

REGION

(32W BLOCKS)

ivvdb (6)

W.NLEN

LENGTH TO MAP (32W BLOCKS)
14

iwdb (7)

W.NSTS

WINDOW STATUS WORD
16

iwdb (8)

W.NSRB

SEND/RECEIVE BUFFER

Figure 3-5

ADDRESS (BYTES)

Window Definition Block
3-15

MEMORY MANAGEMENT DIRECTIVES
The following directives require a pointer to a WDB:
Create Address Window (CRAW$)
Eliminate Address Window (ELAW$)
Map Address Window (MAP$)
Unmap Address Window (UMAP$J
Send By Reference (SREF$)
Receive By Reference (RREF$)
When a task issues one of these directives, the Executive clears the
four high-order bits in the window status word of the appropriate WDB.
After completing the directive operation, the Executive can then set
any of these bits to tell the task what actions were taken.
The other
bits are never modified by the Executive.

3.5.2.1 Using Macros to Generate a WDB - RSX-llM provides two macros,
WDBDF$ and WDBBK$, to generate and define a WDB.
WDBDF$ defines the
offsets and status word bits for a window definition block;
WDBBK$
then creates the actual window definition block.
The format of WDBDF$
is:
WDBDF$
Since WDBBK$ automatically invokes WDBDF$, the programmer need only
specify WDBBK$
in a module that generates a WDB.
The format of the
call to WDBBK$ is:
WDBBK$

apr,siz,rid,off,len,sts,srb

apr

a number from 0 to 7 that specifies the window's base
Active Page Register
(APR). The APR determines the 4K
boundary on which the window is to begin.
APR 0
corresponds to virtual address O, APR 1 to 4K, APR 2 to
BK, and so on.

siz

the size of the window in 32-word blocks

rid·

a region ID

off

the offset within the region to
blocks

mapped,

32-word

len

the length within the reg ion to
blocks

mapped,

32-word

sts

the bit definitions of the window status word

srb

a send/receive buffer virtual address

where

The argument sts sets specified bits in the status word
argument normally has the following format:
<bitl[! ••• !bitn]>
where bit is a defined bit to be set.

3-16

W.NSTS.

The

MEMORY MANAGEMENT DIRECTIVES
The macro call:
WDBBK$

5,76.,0,50.,,<WS.MAPlWS.WRT>

expands to::
.BYTE
.WORD
• WORD
.WORD
• WORD
.WORD
.WORD
.WORD

(Window ID returned in low-order byte)
(Base virtual address returned here)

0,5
0

76 •
0
50 •
0
WS.MAP!WS.WRT
0

If a Create Address Window directive pointed to the WDB defined by the
macro call expanded above, the Executive would:
•

Create a window 76 (decimal) blocks long
(virtual address 20K or 120000 octal)

•

Map the window with write access
(<WS.MAP!WS.WRT>)
to the
issuing task's task region (because the macro call specified 0
for the region ID)

•

Start the
and map
[decimal]
whichever
argument)

•

Return values to the symbolic W.NID
(the
W.NBAS (the window's virtual base address)

'-""'

beginning

APR 5

map 50 (decimal) blocks from the base of the
region
an area either equal to the length of the window (76
blocks) or the length remaining
in the region,
is smaller (because the macro call defaulted the len
window's

ID)

and

3.5.2.2 Using FORTRAN to Generate a WDB - FORTRAN programmers must
create an 8-word, single-precision integer array as the WDB to be
supplied in the subroutine calls:
CALL CRAW
CALL ELAW
CALL MAP
CALL UNMAP
CALL SHEF
CALL RREF

(Create Address Window directive)
(Eliminate Address Window directive)
(Map Address Window directive)
(Unmap Address Window directive)
(Send By Reference directive)
(Receive By Reference directive)

(See the PDP-11 FORTRAN Language Reference Manual for
information
the creatlon of arrays.) A WDB array has the followin~ format:
Contents

Word

•

iwdb(l)

Bits 0 to 7 contain the window ID;
contain the window's base APR

i wdb ( 2)

Base virtual address of the window

iwdb(3)

Size of the window in 32-word blocks

i wdb ( 4)

Region ID

i wdb ( 5)

Offset length within the
begins, in 32-word blocks

3-17

region

bits 8

which

map

MEMORY

MANAGEMEN~r

DIRECTIVES

Word

Contents

iwdb(6)

Length mapped within the region in 32-word blocks

iwdb(7)

Window status word (see
this list)

iwdb(8)

Address of send/receive buffer

the

paragraph

following

The FORTRAN programmer modifies the window status word,
iwdb(7),
by
setting or clearing
the appropriate bits.
See the list in Section
3.5.2 that describes the defined bits.
The bit values are listed
alongside the symbolic offsets.
Note that:
•

The contents of bits 8 to 15 of iwdb(l) must normally be set
without destroying the value in bits O to 7 for any directive
other than Create Address Window.

•

A call to GETADR (see Section 1.5.1.4) can be used t6
the address of the send/receive buffer.
For example:

set

CALL GETADR(IWDB,,,,,,,,IRCVB)
This call places the address of buffer IRCVB in array element
8.
The
remaining elements are unchanged.
The subroutines
SREF and RREF also set up this value.

3.5.3

Assigned Values or Settings

The exact values or settings assigned to individual fields within the
RDB or the WDB vary according to each directive.
Fields that are not
required as input can have any value when the directive
is issued.
Chapter 6 describes which offsets and settings are relevant for each
memory management directive.
The values assigned by the
task are
called
input parameters;
those assigned by the Executive are called
output parameters.

3.6

PRIVILEGED TASKS

When a privileged task maps to the Executive and
the
I/O page,
the
system normally dedicates five or six APRs to
this mapping.
A
privileged task.can issue memory management directives to
remap any
number of these APRs to regions.
Programmers should take great care
when using the directives in this way.
Such remapping can cause
obscure bugs to occur. When a directive unmaps a window that formerly
mapped the Executive or the I/O page!,
the Executive restores the
former mapping.

3-18

•

CHAPTER 4

PARENT/OFFSPRING TASKING

4.1

~·

PARENT/OFFSPRING TASKING SUPPORT OVERVIEW

Parent/offspring tasking
has
many
real-time
applications
in
establishing and controlling complex interrelationships between parent
and offspring tasks.
A parent task is one that starts or connects to
another
task,
called an offspring task.
A major application for the
parent-offspring task relationship is batch processing. When running
tasks
in this manner, task relationships and parameters can be set up
on line to control the processing of a batch job (or
jobs)
that run
off line.
Starting
(or activating)
offspring tasks
is called
"spawning".
Spawning also
includes the ability to establish task communications;
a parent task can be notified when an offspring task exits and can
receive status information from the offspring task.
Status returned from an offspring task to a
parent task
indicates
successful
completion of the offspring task or identifies specific
error conditions.

4.2

DIRECTIVE SUMMARY

Parent/Offspring Tasking Directives

4.2.1

Three directives can connect a parent task to an offspring task:
•

•

Spawn - This directive requests activation
to, a specific offspring task.

of,

and

connects

An offspring task that is spawned by a
parent task has the
following
three task functions that are not provided by the
Request or Run directive •
1.

A spawned offspring task can be a command line interpreter
( CLI) •

•
3.

A spawned offspring
information or exit
parent task or tasks.

task can return current
status
status
information to a connected

4-1

PARENT/OFFSPRING TASKING
Spawn directive options include:
l.

Queuing a command line for the offspring task
be a command line interpreter).

(which

may

offspring task•
ti;:
~:~.
in RSX-llrvt~i?Lus·· •;$y$t~ins>
terminal unit.
.

:·}tr·

tasks in Rsx 7 11M-J?Ll)S s&~#~'rn$:~y
the offspring TI#:'
·>:;·};-·".
•

"'· .

Connect - This directive establishes task communications for
synchronizing with the exit status P.t.:emict.:.s~ta.;.µ.~: issued by a
task that is already active.

·:•·,_·.;._$.~fa~-~ '.~~quest.· And•• connect - ·Thi.s ·•···Rsx+il~~~'.pu~;\~;.j2t~:·

.aa1;a t()· the sp~cified task, . requ~sts:actiy~1;i<;>J:1 :f/
,itJ$ not alr~adyact1v:e, •.. anq:·:<::onnectE)J:(>.: t;Jte:•·.t . . . .

·:·.(Y: . ·

A parent task can connect to more than one offspring task using the
Spawn and Connect directives, as appropriate. In addition, the parent
task can use the directives in any combination to multiply connect to
offspring tasks.
An offspring task can be connected to multiple parent tasks.
An
appropriate data structure, the Offspring Control Block, is produced
{in addition to those already present)
each time a parent task
connects to the offspring task.

Task Communication Directives

4.2.2

Two directives in an offspring task return status to connected
tasks:
•

parent

Exit With Status - This directive in an offspring task causes
the offspring task to exit, passing a status word to all
connected parent tasks (one or more) that have been previously
connected via . a Spawn, Connect, tjf'{:: ~f(ij$~t.l·i~.~R~·Q.e.:··.~)"~13~~~·.~"~!.'J:W!
And Connect directive.
·
·

When status is passed to tasks in this manner, the parent
longer remains connected.

task(s)

Offspring task status values that can be returned to parent tasks
listed as follows:

are

Symbol

Value
Returned

EX$WAR

Warning - task
succeeded,
irregularities are possible

EX$SUC

Success

EX$ERR

Error - results are unlikely
expected

Meaning

4-2

results should be as

but
expec~ed

•

PARENT/OFFSPRING TASKING

4.3

Symbol

Value
Returned

EX$SEV

Meaning
Severe Error - one or more fatal
detected, or task aborted

errors

CONNECTING AND PASSING STATUS

Offspring task exit status
task ( s)
by issuing

status.
The means by which a
task
connects
to
another
task
are
indistinguishable once the connect process is complete.
For example,
Task A can become connected to Task B in one of the three ways shown
below.
1.

Task A spawned Task B when Task B was inactive.

Task A connected to Task B when Task B was active.

Regardless of the way in which Task A became connected to Task B, Task
B can pass status
information back to Task A, set the event flag
specified by Task A, or cause the AST specified by Task A to occur
in
any of the
five ways shown below. Note that once offspring task
status is returned to one or more parent tasks,
the parent tasks
become disconnected.
1.

Task B issues a normal (successful) exit directive.
receives a status of EX$SUC.

Task B is aborted.
EX$SEV.

Task B issues an Exit With Status directive, returning status
to Task A upon completion of Task B.

Task

Task A receives a severe error status

When a task has previously specified another task in a Spawn, Connect,
o r ';~!J~'.f;l;::i:\{%'.g~(g~~i~~ff:.~tjg:;.;:tfg:~.tJ~qJ?J d i r e c t iv e and then ex i ts , and i f st a tu s
has not yet been returned, the OCB representing this connect remains
queued,
but
is marked
to indicate that the parent task has exited.
When this OCB
is subsequently dequeued due

4-3

PARENT/OFFSPRING TASKING
directiv•, or any type of exit, no action is taken since the parent
This
procedure
is
followed
to
help
a
task has exited.
multiply-connected task to keep in synchronization when parent tasks
unexpectedly exit.
Examples of directive usage for intertask synchronization are provided
below (macro call form for directives are shown). Task A is the
parent task and Task B is the offspring task.
Task A

Task B

Action

SPWN$

EXST$

Task A spawns Task B.
Upon Task
Task B returns status to Task A.

CNCT$

EXST$

Upon Task
Task A connects to active Task B.
completion, Task B returns status to Task A.

completion,
~

. . :·

Task A sends data t:9 T<tsk ·s, t~9h¥~~~~
is presently. no~· a<::tiye, a.n~ ~(>pp;~p~.~::;
Task B receives . the d~ta,::d()~S'.., ··
based on. the . data, ret..~;n~ .. ';:i~~
'<(possibly setting .an flvent •. t~~ ·
· ASTJ,and becom.es disconnected>.•tr

'r.~·.~.~·.···:A·.....send.s dat·a to··.•. Taski•e/ \rf~:kti'.¢g#~····,.::

is presently not active1. 'G9,0l)ec.~7 ·~9···-
unstops Task B... Task ·a t>epoµt.es .. tips·.tf'
B IJreviously could not d~qu.~u~ .. ~Ji.~.·······<:
receives the data,. doew.so.me·.gr;9ce!Ss:
.•.. the data,. and . •returns •stat:.us•'t.p .!!'~
:·.::• sett·ing •.• an ·event flag pr r<fl~sJ:~~Jpg;•.~:P•:.:;;.
SDAT$,
USTP$

RCST$

Task A queues a data packet for Task B and unstops
Task B; Task B receives the data.

4-4

5-1

RSX-llM-PLUS EXECUTIVE DIRECTIVES AND FUNCTIONS

5-2

HSX-llM-PLUS EXECUTIVE DIRECTIVES AND FUNCTIONS

•

5-3

RSX-llM-PLUS EXECUTIVE DIRECTIVES AND FUNCTIONS
I

""'

installed

UNIBUS r-un
ORed at assembly

5-4

RSX-llM-PLUS EXECUTIVE DIRECTIVES AND FUNCTIONS

•

5-5

RSX-llM-PLUS EXECUTIVE DIRE1CTIVES AND FUNCTIONS

This allows for the specification of a specific copyof a ml.lltit~,~k in
a directive whose TI: is different from that of the issuing task. tf
the TI: of the target task is known, the task's name can be
qalculated and explicitly specified in a directive.

'~
.
'!

•

5-6

CHAPTER 6
DIRECTIVE DESCRIPTIONS

Each directive description consists of an explanation
of
the
directive's function and use, the names of the corresponding macro and
FORTRAN calls, the associated parameters, and possible return values
of the Directive Status Word (DSW).
The descriptions generally show
the $ form of the macro call (for instance, QIO$), although the $C and
$S forms are also available. Where the $S form of a macro requires
less space and performs as fast as a DIR$ (because of a small DPB), it
is recommended.
For these macros, the expansion for the $S form is
shown, rather than that for the $ form.
In addition to the directive macros themselves, the programmer can use
the DIR$ macro
to execute a directive if the directive has a
predefined DPB.
See Sections 1.4.1.1 and 1.4.2 for further details.

6.1

DIRECTIVE CATEGORIES

For ease of reference,
the directive descriptions are presented
alphabetically in Section 6.3 according to the directive macro calls.
This section, however, groups the directives by function and gives the
number of the section that describes each directive in detail.
The
directives are grouped into the following nine categories:

"-"''

6.1.1

'-'

Task Execution Control Directives

Task Status Control Directives

Informational Directives

Event-Associated Directives

Trap-Associated Directives

I/0- and Intertask Communications-Related Directives

Memory Management Directives

Parent/Offspring Tasking Directives

Task Execution Control Directives

The task execution control directives deal principally with starting
and stoppinq tasks.
Each of these directives (except Extend Task)
results in a change of the task's state (unless the task is already in
the state being requested).
These directives are:
6-1

DIRECTIVE DESCRIPTIONS
Macro

Section

Directive Name

ABRT$
CSRQ$
EXIT$S
EXTK$
RQST$
RSUM$
RUN$
SPND$S

6.3.1
6.3.14
6.3.26
6.3.28
6.3.47
6.3.49
6.3.50
6.3.57

Abort Task
Cancel Time Based Initiation Requests
Task Exit ($S form recommended)
Extend Task
Request Task
Resume Task
Run Task
Suspend ($S form recommended)

6.1.2

Task Status Control Directives

Two task status control directives alter the checkpointable attribute
of a task.
A third directive changes the running priority of an
active task. These directives are:
Macro

Section

Directive Name

ALTP$
DSCP$S
ENCP$S

6.3.2
6.3.17
6.3.24

Alter Priority
Disable Checkpointing ($S form recommended)
Enable Checkpointing ($S form recommended)

6.1.3

Informational Directives

Several directives provide the issuing task with system information
and parameters such as:
The time of day, the task parameters, the
console switch settings, and partition or region parameters.
These
directives are:
Macro

Section

Directive Name

GPRT$
GREG$
GSSW$S
GTIM$
GTSK$

6.3.32
6.3.33
6.3.34
6.3.35
6.3.36

Get
Get
Get
Get
Get

6.1.4

Partition Parameters
Region Parameters
Sense Switches ($S form recommended)
Time Parameters
Task Parameters

Event-Associated Directives

The event and event flag directives are? the means provided in the
system for inter- and intra-task synchronization and signaling. These
directives must be used carefully since software faults resulting from
erroneous
signaling
and synchronization are often obscure and
difficult to isolate. The directives are:
Macro

Section

Directive Name

CLEF$
CMKT$
CRGF$
DECL$S
ELGF$
EXIF$
MRKT$
RDAF$
RDXF$

6.3.7
6.3.8
6.3.11
6.3.15
6.3.20
6.3.25
6.3.38
6.3.44
6.3.45

Clear Event Flag
Cancel Mark Time Requests
Create Group Global Event Flags
Declare Significant Event ($S form recommended)
Eliminate Group Global Event Flags
Exit If
Mark Time
Read All Event Flags
Read Extended Event Flags

6-2

DIRECTIVE DESCRIPTIONS

~·

Macro

SE~ction

Directive Name

SET1i'$
WSIG$S
WTLO$
WTSE$

6 .. 3.54
6 .. 3.76
6 .. 3.77
6 .. 3.78

Set Event Flag
Wait For Significant Event ($S form recommended}
Wait For Logical OR Of Event Flags
Wait For Single Event Flag

6.1.5

•

Trap-Associated Directives

The trap-associated directives provide the user with
that allow transfer of control (software interrupts}
tasks.
These directives are:

trap facilities
to the executing

Macro

Section

Directive Name

ASTX$S
DSAH$S
ENAH$S
IHAH$S
SFP.i\$
SPRA$
SRDA$
SRRA$
SVDl3$
SVTK$

6.3.4
6.3.16
6.3.23
6.3.16
6.3.55
6.3.58
6.3.60
6.3.63
6.3.68
6.7.69

AST Service Exit ($S form recommended}
Disable AST Recognition ($S form recommended}
Enable AST Recognition ($S form recommended}
Inhibit AST Recognition ($S form recommended}
Specify Floating Point Processor Exception AST
Specify Power Recovery AST
Specify Receive Data AST
Specify Receive-By-Reference AST
Specify SST Vector Table For Debugging Aid
Specify SST vector Table For Task

6.1.6

I/O- and Intertask Communications-Related Directives

The I/0- and intertask communications-related directives allow tasks
to access
I/O devices at the driver interface level or interrupt
level, to communicate with other tasks in the system, and to
retrieve
the MCR command line used to start the task.
These directives are:

Macro

Section

Directive Name

ALUN$
CIN'r$
GLUN$
GMCH$
QIO$
QIOW$
RCVD$
RCVX$
SDAT$

6.3.3
6.3.6
6.3.29
6.3.30
6.3.39
6.3.40
6.3.42
6.3.43
6.3.52

Assign LUN
Connect To Interrupt Vector
Get LUN Information
Get MCR Command Line
Queue I/O Request
Queue I/O Request And Wait
Receive Data
Receive Data Or Exit
Send Data

6.1.7

Memory Management Directives

The memory management directives allow a
task to manipulate
its
virtual
and
logical
address spacE~,
and
to set up and control
dynamically the window-to-region mapping assignments.
The directives
also provide the means by which tasks can share and pass references to
data and routines..
These directives are:
Macro

Section

Directive Name

ATRG$
CRAW$

6.3.5
6.3.10

Attach Region
Create Address Window

6-3

DIRECTIVE DESCRIPTIONS

Macro

Section

Directive Name

CRRG$
DTRG$
ELAW$
GMCX$
MAP$
RREF$
SREF$
UMAP$

6.3.12
6.3.18
6.3.19
6.3.31
6.3.37
6.3.48
6.3.62
6.3.70

Create Region
Detach Region
Eliminate Address Window
Get Mapping Context
Map Address Window
Receive By Reference
Send By"Reference
Unmap Address Window

Parent/Offspring Tasking Directives

6.1.8

Parent/offspring tasking directives permit tasks to start other tasks,
connect to other tasks in order to receive status information, stop
for terminal I/O, and unstop other tasks. These directives are:
Macro

Section

Directive Name

CNCT$
EXST$
RCST$
SPWN$
STLO$
STOP$S
STSE$
USTP$

6.3.9
6.3.27
6.3.41
6.3.59
6.3.65
6.3.66
6.3.67
6.3.71

Connect
Exit With Status
Receive Data Or Stop
Spawn
Stop For Logical 'OR' Of Event Flags
Stop
Stop For Single Event Flag
Unstop

. <.;">.

'..~

•:.·~·.~.._-.::_;.:;··

• ..'.'. ".. :. ,

'"" """.•'

. RSX~iliM_;P.LUS·· Directives

-''°.". :.

•ho"•"

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

·~

•

. :i +· t;'·:··C..'T

J'.f~t~n t9 , the directives· ju$t listed). ~~~~'fi'~j~
.t:!:Y;~.·is. > t}lat.. . ~µppotJ:: .·. . parent/offspr)ng. t~skingi'{f ~~:B

·. . ~l~Y§ ·~.~~Jf)lty.,.· Supervisor·. . mode .. l.ibr(;lJy.· .•• ro·qtfµ~~f·:y~ <

9.Zr:~r~JYe .·ct(lta ..•... buffers, .. and

por;t:'.:">.Tfl.esE! ·dir:ectives are:\

:-,:~~@~~·
•: : :···=· •'. ~ •:: :. : '.'·. :•••

•.<· R·J··?2
' . ;··: 6.~ 3 .• 46

:.:·:;·•.• ::·~:. 3 . ~.Si

'. '. :· .• ·::§. 3··i53
6 ···~·· 56

.:;~;>:::; .·:~:·.·~.·:~!

$·
$.. ..... ··..... ~.·~.·~"74
'':·W~P9-1·>·
. > . ·.· •· ~· ·'.·.. ·. . . . .6.•·.:.· ·.·•.•: :.·.·•.·.3.•.·.·.·. ·.·~~.· .·.·.·.1.·.·..
,... ··<:>·±r'>L'

err·or

and ·:exiit

Directive

·.:. : ..

•; .:c<_· . §.)£k3
. . ' : · '. ' :p"' 3 • 2 l.

·•'Yt.J

parity

·.·.3•.•·.·
..

\.'.F~~g~~'::'.°.:

,•·~:;:.J~

create Virtua±.·. .T~r;mlh~r;. :rTi~.:
Eliminate Virtual· tet,mina~··· :.:<··
Emit S'tatµs. . . . ·... •...·. <
· ·y: ·
Rem.eve . . /\ff in i ty J$ s form orq~):,
supervtse>r ··Call. ($S ..··f()ff!l df1tYJ: , ....
Send; Request A.lid Cqrtnfi!9~·,. ~·:
"'""
SpeciJy· J?ar;ity Error.·.·A~'r:.:,:•/•
Sp~(: i fy Request~d Ex.it ~§'rr·.·· ·
Set Affinity·.
·.
. . .. .
·

.gmm mI~fit~:!rg~ ~~ir "t\\+~~~·~g;

6-4

~.
!

DIRECTIVE DESCRIPTIONS
6.2

DIRECTIVE CONVENTIONS

Programmers using system directives should
'-"".

adhere

the

following

conv~rntions:

In MACR0-11 programs,
unless a number
is followed by a
decimal point (.), the system assumes the number to be octal.
In FORTRAN programs, use integer*2 type unless the
description states otherwise~

•

directive

In MACR0-11 programs, task and partition names can be from
one to six characters long and should be represented as two
words in Radix-50 form •
In FORTRAN programs, specify task and partition names by a
variable of type REAL (single precision) that contains the
task or partition name
in Radix-50 form.
To establish
Radix-50
representation,· either use the DATA statement at
compile time, or use the IRAD50 subprogram or RAD50 function
at run time.

Device names are two characters long and are
one word of ASCII code.

Some directive descriptions state that a certain parameter
must be provided even though the system ignores it.
Such
parameters are included to maintain RSX-llM compatibility
with IAS.

In the directive descriptions, square brackets ([
]) enclose
optional parameters or arguments. To omit optional items,
either use an empty (null) field in the parameter list, or
omit a trailing optional parameter.

Logical Unit Numbers (LUNs)

Event flag numbers range from 1 to 96(10). Numbers from 1 to
32(10)
denote local
flags.
Numbers from 33 to 64 denote
common flags.
Numbers 65 to 96 denote group-global event
flags.

Note that the Executive preserves
issues a directive.

6.3

represented

can range from 1 to 255(10).

all

task

registers

when

all

the

each

parameter

task

SYSTEM DIRECTIVE DESCRIPTIONS

Each directive description includes
elements:

most

following

NamE~:

The function of the directive is described.
FOR~rRAN

Call:

The FORTRAN subroutine call
defined.

6-5

shown,

and

DIRECTIVE DESCRIPTIONS
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 parameters, only nonzero default
values are shown.
Parameters ignored by RSX-llM are required for
compatibility with RSX-llD.
Macro Expansion:
in most of the directive
The $ form of the macro is expanded
Where the $S form is recommended for a directive,
descriptions.
the expansion for that form is shown instead.
Expansions for all
three forms and for the DIR$ macro are illustrated in Section
1.4.5.
Definition Block Parameters:.
These parameters are given only in the memory
management
directive descriptions.
This section describes all the relevant
input and output parameters in the Region or Window Definition
Block (see Section 3.5).
Local Symbol Definitions:
Macro expansions usually generate local symbol definitions with
an assigned value equal to the byte offset from the start of the
DPB to the corresponding DPB element. These symbols are listed.
The length in bytes of the element pointed to by the symbol
appears in parentheses following the symbol's description.
Thus:
A.BTTN

Task name (4)

defines A.BTTN as pointing to a task name in the Abort Task
the task name has a length of 4 bytes.

DPB;

DSW Return Code:
All valid return codes are listed.
Notes:
The notes presented with some directive descriptions expand on
the function,
use, and/or consequences of using the directives.
Users should always read the notes carefully.

6-6

•

DIRECTIVE DESCRIPTIONS

ABRT$
Abort Task

6.3.1

The Abort Task directive
instructs the system to
terminate
the
execution of the
indicated task.
ABRT$ is intended for use as an
emergency or fault exit.
A termination notification
is displayed,
based on the described condition, at one of the following terminals:
1.

The terminal from which the aborted task was requested

The originating terminal
aborted task

The operator's console
(CO:)
if the task was
started
internally from another task via a Run directive, or via an
MCR Run command that specified one or more time parameters

the

task

that

requested

the

A task may abort any task, including itself. When a task is aborted,
its state changes from active to dormant.
Therefore, to reactivate an
aborted task, a task or an operator must request it.
In systems that support multiuser protection,
a
task must
be
privileged to issue the Abort Task directive (unless it is aborting a
task with the same TI:).
FORTRAN Call:
CALL ABORT (tsk[,ids])
tsk

Task name

ids

Directive status

Macro Call:
ABRT$
tsk

tsk
Task name

Macro Expansion:
ABRT$
.BYTE
.RADSO

ALPHA
83. '3
/ALPHA/

;ABRT$ MACRO DIC, DPB SIZE=3 WORDS
;TASK "ALPHA"

Local Symbol Definitions:
A.BTTN

Task name (4)

DSW Return Codes:

rs.sue

Successful completion

IE.INS

Task not installed

IE.ACT

Task not active

IE.PRI

Issuing task is not privileged (multiuser
protection systems only)

6-7

DIRECTIVE DESCRIPTIONS
IE.ADP

Part of
space

the DPB is out of the issuing task's address

IE.SOP

DIC or DPB size is invalid

Note:
When a task is aborted, the Executive frees
resources.
In particular, the Executive:

all

the

task's

•

Detaches all attached devices

•

Flushes the AST queue

•

Flushes the receive and receive-by-reference queue

•

Flushes the clock queue for outstanding Mark Time requests for
the task

•

Closes all open files (files open for write access are locked)

•

Detaches all attached regions except in the case
task, where no detaching occurs

•

Runs down the task's I/O

•

Frees the task's memory if the aborted task was not fixed

•

Returns a severe error status (EX$SEV) to the parent task when
a connected task is aborted.

•

Marks virtual terminals created by the aborted task for
deallocation.
The
virtual
terminals
actually
become
deallocated when all tasks using the virtual terminal(s)
are
aborted or exit (see Section 4.2). Nonprivileged tasks using
virtual terminal units that are marked for deallocation as TI:
are also aborted.

6-8

fixed

DIRECTIVE DESCRIPTIONS

ALTP$
6.3.2

Alter Priority

The Alter Priority directive
instructs the system to change the
running priority of a specified active task to either a new priority
indicated in the directive call, or the task's default
(installed)
priority if the call does not specify a new priority.
The specified task must be installed and active. The Executive resets
the task's priority to its installed priority when the task exits.
If the directive call omits a task name, the Executive defaults to the
issuing task.
The Executive reorders any outstanding I/O requests for
the I/O queue and
reallocates the task's partition.
reallocation may cause the task to be checkpointed.

the task in
The partition

In systems· that support multiuser protection,
a
task must
be
privileged
to
issue the Alter Priority directive;
however,
a
nonprivileged task can lower its priority or raise it to its installed
priority.
FORTRAN Call:
CALL ALTPRI

([tsk],[ipri][,ids])

tsk

Active task name

ipri

1-word integer value equal to
number from 1 to 250 (decimal)

ids

Directive status

the new

priority, a

Macro Call:
ALTP$
tsk
pri

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

(decimal)

Macro Expansion:
ALTP$
.BYTE
.RAD50
• WORD

ALPHA, 75.
9• I 4

/ALPHA/
75 •

;ALTP$ MACRO DIC, DPB SIZE=4 WORDS
;TASK ALPHA
;NEW PRIORITY

Local Symbol Definitions:

•

A.LTTN

Task name (4)

A.LTPR

Priority (2)

DSW Return Codes:

rs.sue

Successful completion

IE.INS

Task not installed

IE.ACT

Task not active

6-9

DIRECTIVE DESCRIPTIONS
IE.PR!

Issuing task is not privileged (multiuser protection
systems only)

IE. I PR

Invalid priority

IE.ADP

Part of the DPB
space

IE.SOP

DIC or DPB size is invalid

is out of the issuing task's address

6-10

DIRECTIVE DESCRIPTIONS

ALUN$
6.3.3

Assign LUN

The Assign LUN directive instructs the system to assign a physical
device unit to a logical unit number (LUN).
It does not indicate that
the task has attached itself to the device.
The actual physical device assigned to the logical unit is dependent
on the logical
assignment table (see the MCR Assign command in the
RSX-llM/M-PLUS MCR Operations Manual).
The Executive first
searches
the logical
assignment table for a device name match.
If a match is
found, the physical device unit associated with the matching entry is
assigned
to
the logical unit.
Otherwise, the Executive searches the
physical device tables and assigns the actual physical device unit
named to
the logical unit.
In systems that support multiuser
protection, the Executive does not search the logical assignment table
if the task has been installed with the slave option (/SLV=YES).
When a task :reassigns a LUN from one device to another, the Executive
cancels all
I/O requests for the issuing task in the previous device
queue.
FOR'rRAN Cal 1:
CALL ASNLUN

(lun,dev,unt[,ids])

lun

Logical unit number

dev

Device name

unt

Device unit number

ids

Directive status

(format:

1A2)

Macro Call:
ALUN$ lun,dev,unt
lun

Logical unit number

dev

Device name

unt

Device unit number

(two characters)

Macro Expansion:
ALUN$
.BYTE
.WORD
.ASCII
.WORD

7,TT,O
7,4
7

/TT/
0

;ASSIGN LOGICAL UNIT NUMBER
;ALUN$ MACRO DIC, DPB SIZE=4 WORDS
;LOGICAL UNIT NUMBER 7
;DEVICE NAME IS TT (TERMINAL)
;DEVICE UNIT NUMBER=O

Local Symbol Definitions:
A.LULU

Logical unit number

(2)

A.LUNA

Physical device name

(2)

A. LUNU

Physical device unit number

6-11

(2)

DIRECTIVE DESCRIPTIONS
DSW Return Codes:

rs.sue

Successful completion

IE.LNL

LUN usage is interlocked (see Note 1 below)

IE. I DU

Invalid device and/or unit

IE. I LU

Invalid logical unit number

IE.ADP

Part of
space

IE.SOP

DIC or DPB size is invalid

the DPB is out of the issuing task's address

Notes:
1.

A return code of IE.LNL indicates that the specified LUN
cannot be assigned as directed.
Either the LUN is already
assigned to a device with a file open for that LUN, or the
LUN is currently assigned to a device attached to the task,
and the directive attempted to change the LUN assignment.
If
a
task has a LUN assigned to a device and the task has
attached the device, the LUN can be reassigned, provided that
the task has another LUN assigned to the same device.

6-12

DIRECTIVE DESCRIPTIONS

ASTX$S
AST Service Exit ($S form recommended)

6.3~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, then the Executive
immediately effects the next AST.
Otherwise, the Executive restores
the task's pre-AST state. See Notes below.

•

FOR~rRAN

Call::

Neither the FORTRAN language nor the ISA standard permits direct
linking to system trapping mechanisms;
therefore, this directive
is not available to FORTRAN tasks.
Macro Call:
ASTX$S [err]
err

Error routine address

Macro Expansion:
ASTX$S
MOV
.BYTE
EMT
JSR

ERR
(PC)+,-(SP)
115.,l
377
PC,ERR

;PUSH DPB ONTO THE STACK
;ASTX$S MACRO DIC, DPB SIZE=l WORD
;TRAP TO THE EXECUTIVE
;CALL ROUTINE "ERR" IF DIRECTIVE
;UNSUCCESSFUL

Local Symbol Definitions:
None
DSW Return Codes:

rs.sue

Successful completion

IE.AST

Directive not issued from ·an AST service
routine

IE.A[)P

Part of the DPB or stack is out of the issuing task's
address space

IE. SOP

DIC or DPB size is invalid

Notes:
1.

A return to the AST service routine occurs if, and only if,
the directive is rejected.
Therefore, no Branch on Carry
Clear instruction is generated if an error routine address is
given.
(The return occurs only when the Carry bit is set.)

When an AST occurs, the Executive pushes, at
following information onto the task's stack:
SP+06
SP+04
SP+02
SP+OO

Event flag mask word
PS of task prior to AST
PC of task prior to AST
DSW of task prior to AST

6-13

minimum,

the

DIRECTIVE DESCRIPTIONS

The task stack must be in this state when the AST Service Exit
directive is executed.

~'\

In ~ddition to the data parameters,
the Executive pushes
supplemental information onto the task stack for certain ASTs.
For I/O completion, the stack contains the address of the I/O
status block;
for Mark Time, the stack contains the Event
Flag Number;
for a floating-point processor exception,
the
stack contains the exception code and address.
These AST parameters must be removed from the task's stack
prior to issuing an AST exit directive. The following example
shows how to remove AST parame!ters when a task uses an AST
routine on I/O completion:
Example:
EXAMPLE PROGRAM
LOCAL DATA
IOSB:
BUFFER:

.BLKW
• BLKW

30.

;I/O STATUS DOUBLEWORD
;I/O BUFFER

START OF MAIN PROGRAM
START:

;PROCE:SS DATA
QIOW$C

IO.WVB,2,l,,IOSB,ASTSER,<BUFFER,60.,40>
;PROCE:SS & WAIT

EXIT$S

;EXIT TO EXECUTIVE

AST SERVICE ROUTINE
ASTSER:

; PROCE:ss AST

TST
ASTX$S

(SP)+

;REMOVE ADDRESS OF I/O STATUS BLOCK
;AST EXIT

The task can alter its return address by manipulating the
information on its stack prior to executing an AST exit
directive.
For example,
to return to task state at an
address other than the pre-AST address indicated on the
stack, the task can si~ply replace the PC word on the stack.
This procedure may be useful in those cases in which error
conditions are discovered
in the AST routine;
but this
alteration should be exercised with extreme caution since AST
service routine bugs are difficul't to isolate.

Because this directive requires only a
I-word DPB,
the $S
form of the macro is recommended.
It requires less space and
executes with the same speed as the DIR$ macro.

6-14

DIRECTIVE DESCRIPTIONS

ATRG$
6.3.5

Attach Region

The Attach Region directive attaches the
issuing task to a
static
common region or to a named dynamic region.· (No other type of region
can be attached to the task by means of this directive.) The Executive
checks the desired access specified in the region status word against
the owner UIC and the protection word of the region.
If there
is no
protection violation, the desired access is granted.
If the region is
successfully attached to the task,
the Executive returns a
16-bit
region ID
(in R.GID), which the task uses in subsequent mapping
dirE!Ctives ..
The directive can also be used to determine the ID of a region already
attached to the task.
In this case, the task specifies the name of
the attached region in R.GNAM and clears all four bits described below
in the
region status word R.GSTS. When the Executive processes the
directive, it checks that the named region is attached.
If the region
is attached to the issuing task, the Executive returns the region ID,
as well as the region size, for the task's first attachment to the
region.
A programmer may want to use the Attach Region directive in
this way to determine the region ID of a common block attached to
the
task at task-build time.
FOWrRAN Call::
CALL ATHG

( i rdb ['ids] )

irdb

An 8-word integer array containing a Region Definition
Block (see Section 3.5.1.2)

ids

Directive status

Macro Call:
ATRG$
rdb

rdb
Region Definition Block address

Macro Expansion:
ATRG$
.BYTE
.WORD

RDBADR
57. '2
RDBADR

;ATRG$ MACRO DIC, DPB SIZE=2 WORDS
;RDB ADDRESS

Region Definition Block Parameters:
Input parameters
Array
Element

Off set

irdb(3) (4) R.GNAM

Name of the region to be attached

irdb(7)

Bit settingsl in the region status word
(specifying desired access to the region):

R.GSTS

1
FORTRAN programmers should refer to Section 3.5.1 to determine
bit values represented by the symbolic names described.

6-15

the

DIRECTIVE DESCRIPTIONS

RS.RED

1 if read access is desired

RS.WRT

1 if write access is desired

RS.EXT

RS .. DEL

1 if delete access is desired

if extend access is desired

Clear all four bits to request the region
ID of the named region if it is already
attached to the issuing task.
Output parameters
irdb(l)

R.GID

ID assigned to the region

irdb(2)

R.GSIZ

Size in 32-word blocks of the attached
region

Local Symbol Definition:
A.TRBA

Region definition block address (2)

DSW Return Codes:

rs.sue

Successful completion

IE.UPN

An attachment descriptor cannot be allocated

IE.PR!

Privilege violation

IE.NVR

Invalid region ID

IE.PNS

Specified region name does not exist

IE.ADP

Part of the DPB or
address space

IE.SOP

DIC or DPB size is invalid

IE.HWR

Region had parity error or load failure

6-16

RDB is out of the issuing task's

DIRECTIVE DESCRIPTIONS

CINT$
6.3.6

Connect To Interrupt Vector

The Connect To Interrupt Vector directive provides a
task with the
capability of processing hardware interrupts through a specified
vector. The Interrupt Service Routine (ISR) is included in the task's
own space.
In a mapped system, the issuing task must be privileged.
The overhead entails the execution o:f about 10 instructions before
entry into the ISR, and 10 instructions after exit from the ISR.
A
mechanism is provided for
transfer of control
from the ISR to
task-level code, using either an AST or a local event flag.
After a task has connected to an
interrupt vector,
it can process
interrupts on three different levels:
interrupt, fork, and task.
The
task level may be subdivided into:
AST level and non-AST level.
l.

Interrupt Level
When an interrupt occurs, control
is transferred,
via the
Interrupt Transfer Block (ITB) that has been allocated by the
CINT$ directive, to the Executive subroutine $INTSC.
From
there control goes to the ISR specified in the directive.
The ISR processes the
interrupt and either dismisses the
interrupt directly or enters fork level through a call to the
Executive routine $FORK2.

:Pork Level
The fork-level routine executes at priority O,
the lowest
processor
priority,
allowing
interrupts
and
more
time-dependent tasks to be serviced promptly.
If required,
the fork routine sets a local event flag for the task and/or
queues an AST to an AST routine specified in the directive.

Task Level
At task level, entered as the result of a local event flag or
an AST,
the task does final interrupt processing and has
access to Executive directives.

Typically, the ISR does the minimal processing
required
for
an
interrupt and stores information for the fork routine or task-level
routine in a ring buffer.
The fork routine is entered after a number
of interrupts have occurred as deemed necessary by the ISR, and
condenses the information further.
Finally, the fork routine wakes up
the task-level code for ultimate processing that requires access to
Executive directives.
The fork level may, however,
be a
transient
stage from ISR to task-level code without doing any processing.
In a mapped system, a task must be built privileged to be able to use
the CINT$ directive.
However, it is legal to use the /PR:O switch to
the Task Builder to have "unprivileged mapping," that is,
up to
32K
words of virtual address space available. This precludes use of the
Executive subroutines from task-level code;
however,
the
ISR and
fork-level
routines are always mapped to the Executive when they are
executed.
In any case, the Executive symbol table file
(RSXllM.STB)
should be included as input to the Task Builder.

6-17

DIRECTIVE DESCRIPTIONS
As will be described later, in a mapped system, special considerations
apply to the mapping of the ISR, fork routine, and enable/disable
routine as well as all task data buffers accessed by these routines.
FORTRAN Call:
Not supported
Macro Call:
CINT$

vec,base,isr,edir,pri,ast

vec

interrupt vector address -- Must be in the range 60(8)
to highest vector specified during SYSGEN, inclusive,
and must be a multiple of 4.

base

virtual base address for kernel APR 5 mapping of the
This
ISR, and enable/disable interrupt routines
32(10)-word
address is automatically truncated to a
in an
boundary.
The "base"
argument is ignored
unmapped system.

isr

virtual address of the ISR, or 0
the interrupt vector

edir

virtual
routine

pri

initial
priority
at
which
the
ISR
is
to
execute -- This is normally equal to the hard-wired
interrupt priority, and is expressed in the form n*40,
where n is a number in the range 0-7. This form puts
the value in bits 5-7 of pri.
It is recommended that
the programmer make use of the symbols PR4, PRS, PR6,
and PR7 for this purpose. These are
implemented via
the macro HWDDF$ found in [l,l]EXEMC.MLB.

ast

virtual address of an AST routine to be entered
the fork-level routine queues an AST

address

the

disconnect

enable/disable

from

interrupt

after

To disconnect from interrupts on a vector, the argument isr is set
0 and the arguments base, edir, psw, and ast are ignored.

to
~\

Macro Expansion:
CINT$
.BYTE
.WORD
.WORD
.WORD
.WORD
.BYTE
.WORD

420,BADR,TADR,EDADR,PRS,ASTADR
129.,7
;CINT$ MACRO DIC, DPB SIZE= 7 WORDS
420
;INTERRUPT VECTOR ADDRESS = 420
BADR
;VIRTUAL BASE ADDRESS FOR KERNAL APR
IADR
;VIRTUAL ADDRESS OF THE INTERRUPT
; SERVICE ROUTINE
EDADR
;VIRTUAL ADDRESS OF THE INTERRUPT
;ENABLE/DISABLE ROUTINE
PRS,O
;INITIAL INTERRUPT SERVICE ROUTINE
;PRIORITY (LOW BYTE).
(HIGH BYTE
O.)
ASTADR
;VIRTUAL ADDRESS OF AST ROUTINE

Local Symbol Definitions:
C.INVE

vector address (2)

C. !NBA

base address (2)

C.INIS

ISR address (2)

6-18

DIRECTIVE DESCRIPTIONS
C. INDI

enable/disable interrupt routine address (2)

C. INPS

priority (1)

C. INAS

AST address (2)

DSW Return Codes:
IE.VPN

An ITB could not be allocated (no pool space)

IE. ITS

The function requested is "disconnect" and the task
is not the owner of the vector

IE.PHI

Issuing task is
unmapped system)

IE.RSV

The specified vector is already in use

IE.ILV

The specified vector is illegal
(lower than 60 or
higher than highest vector specified during SYSGEN,
or not a multiple of 4)

IE.MAP

ISR or enable/disable interrupt routine is not within
4K words from the value (base address & 177700)

IE.ADP

Part of the DPB is out of the issuing task's
space

IE. SDP

DIC or DPB size is invalid

not privileged

(not

applicable in

address

Notes:
1.

Checkpointable Tasks
The following points should be noted for checkpointable tasks
only:
When a task connects to an interrupt vector, checkpointing of
the task is automatically disabled.
When a task disconnects from a vector and is not connected to
any other vector, checkpointing of the task is automatically
enabled, regardless of its state before the first connect, or
any change in state while the task was connected.

Mapping Considerations
In an unmapped system, the argument "base"
is ignored, and
the arguments "isr," "edir," and "ast" require no further
explanation.
In a mapped system, however, it must be understood how the
Executive maps the ISR and enable/disable interrupt routine
when they are called.
The argument "base," after being
truncated to a 32(10)-word boundary,
is the start of a
4K-word area mapped in kernel APR 5. All code and data in
the task that is used by the routines must fall within that
area, or a fatal error will occur, probably resulting in a
system crash.
Furthermore,
the
code
and
data
must
be
either
position-independent or coded in such a way that the code can
execute in APR 5 mapping. When the routines execute, the
processor is in kernel mode, and the virtual address space
includes all of the Executive, the pool, and the I/O page.
6-19

DIRECTIVE DESCRIPTIONS
References within the task image must be PC-relative or use a
special offset defined below. References outside the task
image must be absolute.
The following solutions are possible:
a.

Write the ISR, enable/disable interrupt
data in position-independent code.

routines,

and

partition,
Include the code and data
in a common
task-build
it
with
absolute
addresses
in APH 5
(PAR=ISR:l20000:20000), and link the task to the common
par ti ti on.

Build the task privileged with APR S mapping and use the
constant
120000
as
argument "base"
in the CINT$
directive.

When accessing locations within the task image
in
immediate or absolute addressing mode, use an offset of
<120000-<base & 177700>>

ISR
When the ISR is entered, RS points to the fork block in the
Interrupt Transfer Block (ITB), and R4 is saved and free to
be used.
Registers RO through R3 must be saved and
restored
if
used.
If one ISR services multiple vectors,
the
interrupting vector can be identified by the vector address,
which is stored at offset X.VEC in the ITB.
The following
example loads the vector address into R4:
MOV X.VEC-X.FORK(R5),R4
The ISR either dismisses the interrupt directly via an RTS PC
instruction, or calls $FORK2 if the fork routine is to be
entered. When calling $FORK2, RS must point to the fork
block
in the ITB, and the stack must be in the same state as
it was upon entry to the ISR. Note that the call must use
absolute addressing:
CALL @#$FORK2.

Fork-Level Routine
The fork-level routine starts immediately after the call to
$FORK2.
On entry, R4 and RS are the same as when $FORK2 was
called. All registers are free to be used.
The first
instruction of the fork
routine must be CLR @R3, which
declares the fork block free.
The fork-level routine should be entered
if serv1c1ng the
interrupt takes more than SOO microseconds.
It must be
entered if an AST is to be queued or an event flag is to be
set.
(Fork level
is discussed
in greater detail in the
RSX-llM Guide to Writing an I/O Driver.)
An AST is queued by calling the subroutine $QASTC.
Input:
Output:

pointer to fork block in the ITB

if AST successfully queued -- Carry bit = O
if AST was not specified by CINT$ -- Carry bit

6-20

DIRECTIVE DESCRIPTIONS
Registers altered:

RO, Rl, R2, and R3

An event flag is set by calling the subroutine
Input: RO

event flag number

Output:

$SETF.

Task Control Block (TCB) address of task for
which flag
is to be set -- This is usually,
but not necessarily,
the task
that
has
connected to the vector.
This task's TCB
address is found at offset X.TCB in the ITB.
specified event flag set

Registers altered:

Rl and R2

Note that absolute addressing must be used when calling these
routines
(and any other Executive subroutines) from fork
level:
CALL @#$QASTC
CALL @#$SETF

Enable/Disable Interrupt Routine
The purpose of the enable/disable interrupt routine, whose
address
is included
in the directive call, is to allow the
user to have a routine automatically called in the
following
three cases:
a.

When the directive is successfully executed to connect to
an interrupt vector (argument isr nonzero) -- The routine
is called immediately before return to the task.

When the directive is successfully executed to disconnect
from an interrupt vector (argument isr=O)

When the task is aborted or exits with interrupt
still connected

vectors

In case a, the routine is called with the Carry bit cleared;
in cases b and c, with the Carry bit set.
In all three
cases, Rl is a pointer to the Interrupt Transfer Block (ITB).
Registers RO,
R2,
and R3 are free to be used;
other
registers
must
be
returned
unmodified.
Return
is
accomplished by means of an RTS PC instruction.
Typically, the routine dispatches to one of two
routines,
depending on whether
the Carry bit is cleared or set.
One
routine sets interrupt enable and performs
any
other
necessary initialization;
the other clears interrupt enable
and cleans up.

Note that the ITB contains the vector address, in case common
code is used for multiple vectors.
...

AST Routine
The fork routine may queue as AST for the task through a call
to the Executive routine $QASTC as described above. When the
AST routine is entered (at task level), the top word of the
stack contains the vector address and must be popped off the
stack before AST exit (ASTX$S).

6-21

DIRECTIVE DESCRIPTIONS
7.

!TB Structure
The following offsets are defined relative to
the !TB:

the

start

X.LNK

link word

X.JSR

subroutine call to $INTSC

X.PSW

PSW for !SR (low-order byte)

X. !SR

ISR address (relocated)

X.FORK

start of fork block

X.REL

APR 5 relocation (only in mapped systems)

X.DSI

address of
(relocated)

X.TCB

TCB address of owning task

X.AST

start of AST block

X.VEC

vector address

X.VPC

saved PC from vector

X.LEN

length in bytes of ITB

enable/disable

...
routine

interrupt

The symbols X.LNK through X.TCB are defined locally by
macro ITBDF$, which is included in
[l,l]EXEMC.MLB.
symbols are defined globally by [l,l]EXELIB.OLB.
The following programming example illustrates the
directive:

use

the

the
All

CINT$

.TITLE PUNTSK PUNCH ASCII TEXT ON PAPER TAPE PUNCH
;++
THIS TASK WILL PUNCH AN ASCII STRING TO THE PAPER TAPE PUNCH
USING THE CINT$ DIRECTIVE.
IT MUST BE BUILT USING THE /PR:O TASK BUILDER SWITCH.
NOTE THAT THIS METHOD ALLOWS A TASK TO BE A FULL 32K
WORDS LONG.
IF IT IS NECESSARY TO ACCESS THE I/O PAGE
IN OTHER THAN THE ENABLE/DISABLE ROUTINE OR THE !SR
THE TASK MUST BE LINKED TO A COMMON BLOCK COVERING
THE CORRECT PART OF THE I/O PAGE.
TASK BUILD COMMAND FILE:
PUNTSK/MM/PR:O/-FP,PUNTSK/-SP/MA=PUNTSK
[l,54]RSX11M.STB/SS

I
GBLDEF=$VECTR:74
GBLDEF=$DVCSR:l77554
UNITS=l
ASG=TI: 1
PAR=GEN:0:40000
IT IS POSSIBLE TO HAVE THIS TASK 1~YPE ON THE CONSOLE TERMINAL
IF THERE IS NO PAPER TAPE PUNCH AVAILABLE. TO DO THIS THE
VECTOR FOR THE CONSOLE OUTPUT MUST APPEAR TO BE UNUSED.
THIS
6-22

DIRECTIVE DESCRIPTIONS
MAY BE DONE BY (ON A TERMINAL OTHER THAN THE CONSOLE!) OPENING
THE VECTOR LOCATION (64) AND REPLACING ITS CONTENTS WITH
THE VALUE OF '$NSO' AS OBTAINED FROM A MAP OF THE SYSTEM.
BE
SURE TO REMEMBER THE OLD VALUE OR YOUR CONSOLE WILL BE DEAD
UNTIL YOU REBOOT THE SYSTEM. NOW TASK BUILD USING THE FOLLOWING
COMMAND FILE:
PUNTTY/MM/PR:O,/-FP,PUNTTY/-SP/MA=PUNTSK
[l,54]RSXllMoSTB/SS

I
GBLDEF=$VECTR:64
GBLDEF=$DVCSR:l77564
UNITS=l
ASG=TI: 1
PAR=GEN:0:40000
NOTE THAT IN THE ABOVE TWO TKB COMMAND FILES THE FOLLOWING
CHANGES MUST BE MADE IN ORDER TO RUN ON AN UNMAPPED SYSTEM:

1) /MM SHOULD BE CHANGED TO /-MM
2) 'PAR=GEN:0:40000' SHOULD BE CHANGED TO
'PAR=GEN:40000:40000'
IN ADDITION, PLACE A SEMI-COLON IN FRONT OF THE SOURCE LINE
BELOW THAT DEFINE THE SYMBOL 'M$$MGE'.
;--

.MCALL CINT$, QIOW$, CLEF$S, WTSE$S, EXIT$S, DIR$
i

; LOCAL SYMBOLS
;LUN FOR TERMINAL I/O
LUN.TT
l
;EFN FOR TERMINAL I/O
EFN.TT
l
;EFN TO WAIT FOR PUNCHING TO COMPLETE
EFN.WF
2
;DEFINE THIS SYMBOL TO RUN ON MAPPED SYSTEM
M$$JMGE
0
;++
MACRO TO GENERATE AN ASCII STRING AND A QIO TO OUTPUT
THE STRING TO THE TERMINAL.
MESSG

NAM,STRING

WHERE:
NAM
STRING

IS THE NAME OF THE GENERATED QIO DPB
IS THE ASCII STRING TO OUTPUT

;--

LBL:
NAM:

.MACRO MESSG
NAM,STRING,?LBL
$CHR=O
.IRPC
X,<STRING>
$CHR=$CHR+l
ENDR
.ENABL LSB
• ASCII /STRING/
.EVEN
QIOW$
IO.WVB,LUN.TT,EFN.TT,,r,<LBL,$CHR,40>
.DSABL LSB
.ENDM
MESSG HELLO,<CONNECT TO INTERRUPT TEST>
MESSG CINWRK,<CONNECT TO INTERRUPT WORKS--CHECK THE PAPER TAPE
PUNCH>

CINT:

CINT$

$VECTR,$BASE,$PNISR,$PNEDI,PR4

6-23

DIRECTIVE DESCRIPTIONS

;CONNECT TO INTERRUPT
VECTOR=$VECTR
BASE.FOR.MAPPING=$BASE
ISFt=$ PN !SR
ENB.DSABL.RTN=$PNEDI
PRIO=PR4
DISCON:CINT$

$VECTR,O,O

;DISCONNECT FROM INTERRUPT
VECTOR=74

;++
ENTRY POINT TO THE PUNCH TASK. THE TASK WILL ANNOUNCE
ITSELF ON THE INITIATING TERMINAL, CONNECT TO THE
SPECIFIED VECTOR, OUTPUT THE ASCII STRING, AND THEN
OUTPUT A MESSAGE THAT IT WAS SUCCESSFUL.
IF THE TASK
TERMINATES WITH AN I/O TRAP THE CONNECT-TO-INTERRUPT
DIRECTIVE FAILED, AND Rl WILL CONTAIN THE DSW RETURNED
IN ORDER TO DIAGNOSE THE ERROR.
;-$PUNTK: : DIR$
DIR$

ERRl:

#HELLO
#CINT

BC$
WTSE$S
DIR$
DIR$
EXIT$S

ERRl
#EFN. WF
#DISCON
#CINWRK

MOV
MOV
IOT

#1,RO
$DSW,Rl

$BASE;

;ANNOUNCE THAT WE ARE HERE
;CONNECT TO THE PUNCH
THIS CAN BE EITHER THE TERMINAL
;
OR THE PAPER TAPE PUNCH.
;IF CS THEN DIRECTIVE ERROR
;WAIT FOR PUNCH TO FINISH
;DISCONNECT FROM INTERRUPTS
;TELL USER THAT CINT WORKS
;ERROR # l
;GET THE DSW TO SHOW THE CINT ERROR RETURN
;DUMP REGISTERS

~
1--1

;THIS IS THE BASE OF THE MAPPING USED
;BY THE EXECUTIVE WHEN MAPPING TO THE
;'DRIVER'. THIS MAPPING IS REQUIRED
;ONLY ON MAPPED SYSTEMS; UNMAPPED
;SYSTEMS DO NOT HAVE THIS PROBLEM.

;++
FOLLOWING IS THE ASCII STRING PUNCHED BY THIS TASK.

;-PUNMSG:

.NLIST
.ASCIZ
.LIST
.EVEN

BEX
/ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!@#$%A&*() +-=/<i5><12>
BEX

PUNPTR:
.WORD
;POINTER INTO PUNMSG FOR ISR
0
TSKTCB:
.WORD
0
;TCB ADDRESS OF TASK
PUNCSR:
.WORD
$DVCSR
;PAPER TAPE PUNCH CSR ADDRESS
PUNBUF:
.WORD
$DVCSR+2
;PAPER TAPE PUNCH BUFFER ADDRESS
;++
ENABLE/DISABLE ROUTINE.
THIS ROUTINE IS CALLED BY THE EXEC ON EITHER A CONNECT OR DISCONNECT
FROM INTERRUPT VECTOR REQUEST, OH WHEN THE TASK EXITS WITH INTERRUPT
VECTORS STILL CONNECTED.
ENTRY CONDITIONS:
C-CLEAR
C-SET

THIS IS A SUCCESSFUL CONNECT.
THIS IS A DISCONNECT.

$TKTCB

THE TCB ADDRESS OF THE CURRENTLY EXECUTING TASK (MEM) •
6-24

•

DIRECTIVE DESCRIPTIONS

ACTION:
IF THE C-BIT IS SET WE MERELY DISABLE THE PUNCH AND RETURN.
IF
THE C·-BIT IS CLEAR WE WILL ENABLE THE PUNCH TO INTERRUPT. THIS
WILL IMMEDIATELY CAUSE AN INTERRUPT AND THE INTERRUPT SERVICE
ROUTINE WILL OUTPUT CHARACTERS TO THE PUNCH (ONE PER
INTERRUPT) UNTIL A ZERO BYTE IS OUTPUT. THE !SR WILL THEN FORK
AND SJ~T THE LOCAL EVENT FLAG 'EFN. WF' • THIS WI LL THEN CAUSE THE
TASK PORTION OF THIS TASK TO CONTINUE EXECUTING AND EVENTUALLY
EXIT.

;-$PNBDI::BCS
MOV

20$
;IF CS THEN DISCONNECT
@#$TKTCB,TSKTCB ;COPY TASK TCB ADDRESS FOR LATER
;SO WE CAN SET EFN •

• IF DF M$$MGE

;MAPPED SYSTEM?

MOV

#PUNMSG+l20000-<$BASE&l77700>,PUNPTR ;RELOCATE ADDRESS
;TO APR 5 MAPPING, AND SET UP
; BUFFER POINTER

.IFF

M$$MGE

MOV

#PUNMSG,PUNPTR ;SET UP BUFFER POINTER

;UNMAPPED SYSTEM?

.ENDC
BIS
RETUHN

#100,@PUNCSR ;ALLOW INTERRUPTS
;WHEN WE ARE DONE PUNCHING

20$:

BIC
RETUHN

#100,@PUNCSR ;DISABLE INTERRUPTS

.END

6-25

DIRECTIVE DESCRIPTIONS

CLEF$
6.3.7

Clear Event Flag

The Clear Event Flag directive
instructs the system
indicated event flag's polarity and then clear it.

report

FORTRAN Call:
CALL CLREF (efn[,ids])
efn

Event flag number

ids

Directive status

Macro Call:
CLEF$
efn

efn
Event flag number

Macro Expansion:
CLEF$
.BYTE
• WORD

52.
31. '2
52.

;CLEF$ MACRO DIC, DPB SIZE=2 WORDS
;EVENT FLAG NUMBER 52 •

Local Symbol Definitions:
C.LEEF

Event flag number

(2)

DSW Return Codes:
IS.CLR

Successful completion;

flag was already clear

IS.SET

Successful completion;

flag was set

IE.IEF

Invalid event flag number

IE.ADP

Part of the DPB is out of the issuing task's address
space

IE.SDP

DIC or DPB size is invalid

(EFN>64 or EFN<l)

•

6-26

DIRECTIVE DESCRIPTIONS

CMKT$
6.3.8

Cancel Mark Time Requests

The Cancel Mark Time Requests directive instructs the system to cancel
a specific Mark Time Request or all Mark Time requests that have been
made by the issuing task.
FOR~rRAN

Cal 1:

CALL CANMT ( [efn,ast] [,ids])

•

ids

Directive status

efn

Event flag number

ast

Mark time AST address

Macro Call:
CMKT$S

[efn,ast,err]

err

Error routine address

efn

Event flag number

ast

Mark time AST address

Macro Expansion:
CMKT$
MOV
.BYTE
• WORD
.WORD
EMT
BCC
JSR

52.,MRKAST,ERR
(PC)+,-(SP)
27. '3
52 •
MRKAST
377
.+6
PC,ERR

;NOTE: THERE ARE TWO IGNORED ARGUMENTS
;PUSH DPB ONTO THE STACK
;CMKT$ MACRO DIC, DPB SIZE=3 WORDS
;EVENT FLAG NUMBER 52.
;ADDRESS OF MARK TIME REQUEST AST ROUTINE
;TRAP TO THE EXECUTIVE
;BRANCH IF DIRECTIVE SUCCESSFUL
;OTHERWISE, CALL ROUTINE "ERR"
NOTE

The above example will cancel only the
request specified by the ast parameter.
If all requests are to be canceled, no
ast or efn parameters will be specified,
and the DPB size will equal 1.

•

Local Symbol Definitions:

(2)

C.MKEF

Event flag number

C.MKAE

Mark Time Request AST routine address (2)

DSW Return Codes:

rs.sue

Successful completion

IE.ADP

Part of the
space

IE. SDP

DIC or DPB size is invalid

DPB is out of the issuing task's address

6-27

DIRECTIVE DESCRIPTIONS
Notes:

If neither the efn nor ast parameters are specified, all Mark
Time Requests issued by the task are canceled.
In addition,
the DPB size will be 1 word.
(When either the efn and/or ast
parameters are specified, the DPB size will be 3 words.)

If both efn and ast parameters are specified (and non-zero),
only Mark Time Requests issued by the task specifying either
that event f1ag or AST address are canceled.

If only one efn or ast parameter is specified (and non-zero),
only Mark Time Requests issued by the task specifying the
event flag or AST address are canceled.

6-28

DIRECTIVE DESCRIPTIONS

CNCT$
6.3.9

Connect

The Connect directive synchronizes the task issuing the directive with
the ex i t '~;tiff?:j~m<~'.~'i''@!~~";t'i;JI~'.'l: of another task ( of f s pr i ng ) that i s al ready
active. An Offspring Control Block (OCB) is queued to the offspring
task, and the issuing task's rundown count (contained in the issuing
task's Task Control Block)
is incremented.
The rundown count is
maintained to indicate the combined total number of tasks presently
c on n e c t e d a s o f
ta s ks i,1~;~<[~'.';':t"tlf£: <ti9;~,~'f~i0{1'.i'umb~:tCj\q;~:$';'/'!(t;i;;Q.j}l;'ijzi:iz,itf'AAfi:~i~r§i2
The exit AST routine is called when the
offspring
":ti~~:j4;$i; with the
address of the associated
exit status
on the stack. This directive should not be issued
to connect to Command Line Interpreter (CLI) tasks;
it is illegal to
connect to a CLI task.
FORTRAN Call:
CALL CNCT (rtname, [iefn], [iast], [iesb], [iparm], [ids])
rtname

Name of the offspring task to be connected

iefn

Event fl

offspring

task

iast
iesb

when

exits
the

Address of an 8-word status
itten when
the offs pr i ng task ex i ts !{~,)~!&j~m~;~6~?,)'.~~~~1~,9$/{i
word

word 1-7

Offspring task exit status
Reserved

iparm

Address of a word to receive
address when an AST occurs

ids

Integer to receive the Directive Status Word

the

status

block

Macro Call:
CNCT$

tname, [efn] , [east] , [esb]

tname

Name of .the offspring task to be connected

efn

The event flag to be cleared on issuance and
when the o ff s pr i ng task ex i ts ~;~;!~~,-,]i_(~tffii!;~:~,j~Hi~;-~;1µ:,~,ilt

set

east

Address of an AST routine to be called
o t ts Pr i ng task ex i ts 'i~;,~I!!It'~m'~V~-'.$'i:i:i:r~::~'~,:~'.g:~,,,

the

esb
word

word 1-7

Offspring task exit status
Reserved

6-29

when

DIRECTIVE DESCRIPTIONS
Macro Expansion:
CNCT$
.BYTE
.RAD50
.WORD
.WORD
.WORD

ALPHA,l,CONAST,STBUF
143.,6
;CNCT$ MACRO DIC, DPB SIZE=6 WORDS
ALPHA
;OFFSPRING TASK NAME
1
;EVENT.FLAG NO= 1
CON AST
;AST ROUTINE ADDRESS
STBUF
;EXIT STATUS BLOCK ADDRESS

Local Symbol Definitions:
C.NCTN

Task name (4)

C.NCEF

Event flag

C.NCEA

AST routine address (2)

C.NCES

Exit status block address (2)

(2)

DSW Return Codes:

rs.sue

Successful completion

IE.UPN

Insufficient dynamic memory to allocate an offspring
control block

IE.INS

The specified task was a command line interpreter

IE.ACT

The specified task was not active

IE. I EF

An invalid event flag number was specified

IE.ADP

Part of the DPB or exit status block is not in the
issuing task's address space

IE.SOP

DIC or DPB size is invalid

6-30

DIRECTIVE DESCRIPTIONS

CRAW$
6.3.10

...

Create Address Window

The Create Address Window directive creates a
new virtual
address
window by allocating a window block from the header of the issuing
task and establishing its virtual address base and size.
(Space for
the window block has to be reserved at task-build time by means of the
WNDWS keyword.
See the RSX-llM/M·-PLUS Task Builder Manual.)
Any
existing windows that overlap the specified range of virtual addresses
are unmapped and then eliminated.
If the window is successfully
created, the Executive returns an 8-bit window ID to the task •
The 8-bit window ID returned to the task is a number
from 1 to
which is an
index to
the window block in the task's header.
window block describes the created address window.

15,
The

If WS.SIS in the window status word is set, the Executive creates the
window in Supervisor mode I-space.
Program control can subsequently
be transferred to Supervisor mode I-space upon issuing a Supervisor
Call directive.

A task can specify any length foi the mapping assignment that is less
than or
equal
to both the window size specified when the window was
created, and the length remaining between the specified offset within
the region and the end of the region.
If W.NLEN is set to O, the length defaults to either the window size
or the length remaining in the region, whichever is smaller.
(Because
the Executive returns the actual length mapped as an output parameter,
the task must clear that offset before issuing the directive each time
it wants to default the length of the map.)
The values that can be assigned to W.NOFF depend on the setting of bit
WS.648 in the window status word (W.NSTS):
•

If WS.64B = O, the offset specified in W.NOFF must represent a
multiple of 256 words
(512 bytes).
Because the value of
W.NOFF is expressed in units of 32-word blocks, the value must
be a multiple of 8.

•

If WS.648 = 1, the task can align on 32-word boundaries;
the
programmer can therefore specify any offset within the region.
NO'I'E
Applications dependent on 32-word or
64-byte alignment
(WS.648
1) may not
be compatible with
future
software
products.
To
avoid
future
incompatibility,
programmers
should
write applications adaptable to either
alignment requirement.
The bit setting
of WS.64B could be a parameter chosen at
assembly time
(by means of a
prefix
file),
at task-build time (as input to
the GBLDEF option), or at run time
(by
means of command input).

6-31

DIRECTIVE DESCRIPTIONS
FORTRAN Call:
CALL CRAW (iwdb[,ids])
iwdb

An 8-word integer array containing a window definition
block (see Section 3.5.2.2)

ids

Directive status

Macro Call:
CRAW$
wdb

wdb
Window Definition Block address

Macro Expansion:
CRAW$
.BYTE

.·woRD

WDBADR
117.,2
WDBADR

;CRAW$ MACRO DIC, DPB SIZE=2 WORDS
;WDB ADDRESS

Window Definition Block Parameters:
Input parameters
Array
Element

Off set

iwdb(l),
bits 8-15

W.NAPR

Base APR
created

i wdb ( 3)

W.NSIZ

Desired size, in 32-word blocks, of
address window

the

i wdb ( 4)

W.NRID

ID of the region to which the new window
is to be mapped, or O for task region (to
be specified only if WS.MAP=l)

iwdb(5)

W.NOFF

Off set in 32-word blocks from the start
of the region at which the window is to
start mapping
(to be specified only if
WS.MAP=l). Note that if WS.64B in the
window status word equals O, the value
specified must be a multiple of 8.

iwdb(6)

W.NLEN

Length in 32-word blocks to be mapped, or
i f the length is to default to either
0
the size of the window or the space
rema1n1ng
in the
region, whichever is
smaller
if
(to
be
specified
only
WS. MAP=l)

iwdb ( 7)

W.NSTS

Bit settingsl in the window

of the address

window

status word:

WS.MAP

1 if the new window is to
mapped

WS.WRT

1 if the mapping assignment
is to occur with write access

WS.648

0
for
256-word
(512-byte)
alignment,
or 1 for 32-word
(64-byte) alignment

6-32

DIRECTIVE DESCRIPTIONS

Output parameters
i wdb ( 1) ,

W.NID

ID assigned to the window

iwdb ( 2)

W.NBAS

Virtual address base of the new window

iwdb(6)

W.NLEN

Length,
in 32-word
mapped by the window

iwdb(7)

W.NSTS

Bit settings! in the window

bi ts 0-·7

Bit

blocks,

actually

status word:

Definition (if bit=l)

WS.CRW

Address window was
successfully created

WS.UNM

At least one window was
unmapped

WS.ELW

At least one window was
eliminated

WS.RRF

Reference was successfully
received

WS.RES

Map only if resident

WS.64B

Define the task's permitted
alignment boundaries
0
for 256-word (512-byte)
alignment, 1 for 32-word
(64-byte) alignment

WS.MAP

Window is to be mapped

WS.RCX

Exit if no references to
receive

WS.DEL

Send with delete access

WS.EXT

Send with extend access

~·

1 FORTRAN programmers should refer to Section 3.5.2 to determine
bit values represented by the symbolic names described.
6-33

the

DIRECTIVE DESCRIPTIONS

WS.WRT

Send with write access or map
with write access

WS.RED

Send with read access

Local Symbol Definitions:
C.RABA

Window definition block address (2)

DSW Return Codes:

rs.sue

Successful completion

IE .HWR

Directive failed in mapping
has incurred a parity error

IE.PR!

Requested access denied at mapping stage

IE.NVR

Invalid region ID

IE .ALG

Task specified either an
size combination, or an
length combination in
WS.648 = 0 and the value
of 8

IE.WOV

No window

IE.ADP

Part of the DPB
address space

IE.SOP

DIC or DPB size is invalid

blocks

st~rage

6-34

region

invalid base APR and window
invalid region offset and
the mapping assignment;
or
of W.NOFF is not a multiple

available in
or WDB

because

task's header

is out of the issuing task's

DIRECTIVE DESCRIPTIONS

CRGF$
6.3.11

Create Group Global Event Flags

The Create Group Global Event Flags directive creates a Group Global
Event Flag Control Block (GFB) and links it into the GFB list.
If a
GFB for the specified group is not present when the directive
is
issued,
the Executive creates the GFB data structure with all event
flags initialized to zero.
If a GFB is present when the directive
is
issued,
the present GFB is used and the event flags are not
initialized.
However,
if the GFB
is marked for delete
(by a
previously issued Eliminate Group Global Event Flags directive), the
Executive clears the GS.DEL bit (see Section 6.3.20).
FORTRAN CALL:
CALL CRGF ([group],[idsw])
group

Group number for
the flags to be created.
Only
privileged tasks can specify group numbers other than
the issuing task's group UIC.
If not specified,
the
task's protection UIC (H.CUIC+l) in the task's header
is used.

. idsw

Integer to receive the Directive Status Word

Macro Call:
CRGF$

group

Group number for
the flags
to be created.
Only
privileged tasks can specify group numbers other than
the issuing task's group UIC.
If not specified,
the
task's protection UIC (H.CUIC+l) in the task's header
is used.

Macro Expansion:
CRGF$
.BYTE
.WORD

157.,2

;CRGF$ MACRO DIC, DPB SIZE=2 WORDS
;GROUP 4 GLOBAL EVENT FLAGS

Local Symbol Definitions:
C.RGRP -- Group Number

(2)

DSW Return Codes:

rs.sue

Successful completion

IE. UPN

Insufficient dynamic storage

IE.PR!

Privilege violation

IE. I UI

Invalid group

IE.RSV

Event flags already exist

IE .. APD

Part of the DPB is out of the
space

IE.DIC -- DIC or DPB size is invalid

6-35

issuing

task's

address

DIRECTIVE DESCRIPTIONS

CRRG$
6.3.12

Create Region

The Create Region directive creates a
dynamic
region
in
a
system-controlled partition and optionally attaches it to the issuing
task.
If RS.ATT is set in the region status word, the Executive attempts to
attach the task to the newly created region.
If no region name has
been specified, the user must set RS.ATT (see the description of the
Attach Region directive).
By default, the Executive automatically marks a dynamically created
region for deletion when the last task detaches from it.
To override
this default condition, the user can set RS.NOL in the region status
word as an input parameter.
Note that programmers should be careful
in considering overriding the delete-on-last-detach option.
An error
within a program can cause the system to lock by leaving no free space
in a system-controlled partition.
If the region is not given a name, the Executive ignores the state of
RS.NOL.
All
unnamed regions are deleted when the last task detaches
from them.

:'.C>~<iltl~·<i· )teglon~ in RSX-HM-PLUS systems a re
:··[):f,~~C:::t()~y (CBD) •... ·However, memory is not

. ·.-tJ'\CiJ?~ : ~,_ ~et.f5k.to .the reg ion.

The Executive returns an error
if there
is not enough space to
accommodate the region in the specified partitione
See Notes below.

.,....:

FORTRAN Call:
CALL CRRG

(irdb[,ids])

irdb

An 8-word integer array containing a Region Definition
Block (see Section 3.5.1.2)

ids

Directive status
~.

Macro Call:
CRRG$
rdb

rdb
Region Definition Block address

Macro Expansion:
CRRG$
.BYTE
.WORD

RDBADR
55.,2
RDBADR

;CRRG$ MACRO DIC, DPB SIZE
;ROB ADDRESS

2 WORDS

Region Definition Block Parameters:
Input parameters
Array
Element

Off set

irdb(2)

R.GSIZ

Size,
in 32-word blocks, of the
to be c rea1 ted

6-36

region

DIRECTIVE DESCRIPTIONS
i rd b ( 3 ) ( 4 )

R • GNAM

Name of
the region
for no name

irdb(S) (6)

R.GPAR

Name of the system-controlled partition
in which the region is to be allocated,
or
0 for the partition in which the task
is running

irdb(7)

R.GSTS

Bit settingsl

irdb(8)

to be created, or 0

in the region status word:

Bit

Definition (if bit=l)

RS.CRR

Region was successfully
created

RS.UNM

At least one window was
unmapped on a detach

RS.MDL

Mark region for deletion on
last detach

RS.NOL

The region should not be
deleted on last detach

RS.ATT

Created region should be
attached

RS.NEX

Created region is not
extendible

RS.RED

Read access is desired on
attach

RS.WRT

Write access is desired on
attach

RS.EXT

Extend access is desired on
attach

RS.DEL

Delete access is desired on
attach

R.GPRO

Protection
word
for
(DEWR,DEWR,DEWR,DEWR)

the

region

irdb(l)

R.GID

ID
assigned
to the
(returned if RS.ATT=l)

created

region

irdb(2)

R.GSIZ

Size
in 32-word blocks of the attached
region (returned if RS.ATT=l)

irdb(7)

R .GSTS

Bit

Output parameters

settingsl

RS.CRR

in region

status

word:

1 if region was successfully
created

1
FORTRAN programmers should refer to Section 3.5.1 to define the bit
values represented by the symbolic names described.

6-37

DIRECTIVE DESCRIPTIONS
Local Symbol Definitions:
C.RRBA

Region Definition Block address (2)

DSW Return Codes:

rs.sue

Successful completion

IE. UPN

A Partition Control Block
(PCB)
or an attachment
descriptor could not be allocated, or the partition
was not large enough to accommodate
the
region,
or
there is currently not enough continuous space in the
partition to accommodate the region

IE.HWR

The directive failed in the attachment stage
a region parity error was detected

IE.PR!

Attach failed because desired access was not allowed

IE.PNS

Specified partition in which the
region was to be
allocated does not exist;
or no region name was
specified and RS.ATT = 0

IE.ADP

Part of the DPB or
address space

IE.SOP

DIC or RDB size is invalid

ROB

out

issuing

because

task's

Notes:
1.

The Executive does not return an error if the named
region
already exists.
In this case,
the Executive clears the
RS.CRR bit in the status word R.GSTS.
If RS.ATT has been
set,
the Executive attempts to attach the already existing
named region to the issuing task.

The protection word (see R.GPRO above) has the same format as
that of the file
system protection word.
There are four
categories, and the access for each category is coded
into
four bits.
From low order to high order, the categories
follow this order:
system, owner, group, world.
The access
code bits within each category are arranged (from low order
to high order) as follows:
read, write, extend, delete.
A
bit that is set indicates that the corresponding access is
denied.
The issuing task's UIC is the created region's owner UIC.
In order to prevent the creation of common blocks that are
not easily deleted,
the system and owner categories are
always forced to have delete access, regardless of the value
actually specified in the protection word.

6-38

J..,.\

DIRECTIVE DESCRIPTIONS

~·

6-39

DIRECTIVE DESCRIPTIONS
..

·:. ,· ..

, .'

thert si9nals I/0 compl etiC>l1
for
both ··;!"/.(;> · · ·
Similarly, if Macro-11 neE~ds to print an er"r9J. tn
does so with an IO.WVB or IO .. WLB to Tt:.

:t:r6C~;~~~:·~

·4. .ln its output AST routine, the Batch
IO.RVB or IO.RLB to .retrleve the .lirie ·V.Ia
terminal driver. The Batch Processor may t:heri.><(;)9
line to its log file. The third word· Qn •• tlie ~~.'r·:.131;,
Bat;qh output AST routine is the vertical fQrJT\a,t:, ·.:9,'l'i.~
telllf19 . Batch. what type of carriage. c911trol. *·$,·:~.)C~~g
the output line. This word would be ignored i.n· the. i.n
routine.

~(~~

'!'lie v!rt Ila a terminal. driver does not i. n te r pr.et
1116dtf§
J?y1:,es, I/O subfunction codes, or vertlcal format oharaq,tr·i'~i·.·.·:
~hi·$··· <triver· . does

automatically truncat:e .offsprin9

~/O. t'·.EiJ!CJt,;l~~t:,.~.;

IJlCll~rnum byte count specified in the "mlen" parame.ter n·e.t:. . i.~}"lPCiJ'•:tI.•~'f

't.he PCirent nor. of.fspr ing task..

The actual· nµmber. c>f,' byt~~ ~F~~q~J~e·

· on .... each . request .is equal to .. the small er of the ·?Yte9'.<;)t,;111.t:.;~\ .. ~P~·

.in the· offspring and parent I/O requests • • +he.'t;qt~l·'·q.!Jlnl:>~p· .• >·· · ·
);·rF·!lsferred.. i.s. returned . in the correspondiri9· I/Q ~t;Cl.tH;fS ..bl?R:··:•
tha't offspring tasks can receive "mlen" in the fourth· ·cha~r.ac:;J;
wdrd when a Get LUN Information directive is
<: ::•>\',

issued.

wh~Jl.. ~~~~);~~

Jntt\rmed1ate buffer illg in the Executive pooh
par.~nt .·task,. is performed on offspring input and p~tpµ): .~:·fl
\he ·offspring task is checkpointab1e, is not at A.S·T. st:ater: ;et, ...• J~:·_::
· ~lJ~ady . stopped •...· ·.offspring ·. tasks, therefore., ·.m?Y.
~~$t:?P~¢(
q·_heykpolnted. · · If the parent task is stopped and.:~:l}~ql(p9·it;i:t;~~. :\'·
.t.iro~: of the :issuaqce of an I/O request by the offs;prJ.ng·.·, 't;h·~;>,~~
~s.T brings the parent task to an unstc>pped state· fr<>Jt1i :. Vff'l~F-11,: :l:1r··
·.r:eturn to< memory to service the I/O. request. Upo11 • ~~-i~. fr:q~~l
:~oµt:Jne the parent task is again stopped.
'!'his, ft\():ci.~: .()J>·. ·
a}~e>ws
the parent and offspring tasks to fSha~e t;n~ ~a.,tn
· m~in().t'Y; eyen Y/hile the parent task services the termi}"l,:al.: ~/·(.)··.·•:?;'•~·.
.for. : J:he offspring task.
Whenever" for .. ariy .... reasoJl, > t.l)(!l:\:"74·~·:::
·.t;€tt'll\inal driver determines that iB should . not .•. · Ufi;~ ·*¥1t:~.p.~;~§··:
:t;>t1ff~Eing, . offspring tasks are locked in .memory>~hen· 1'(9. ·r~gµ·~.s;;t; . ~h·
·:,1. ssued, and transfers occur directly between P<:lr~pt. '. arid'. ::Q:f:~,i?i;>'
'bu~fers.·
·
· ·
··

···e:::.

>.·

·~~~ intermediate buffering of offspring. I/O requists· c~n:,
~11'19+ed
and disctbled .· by the parent task via t};}(;t ;q.S'J::S<:f
d~sqrlbed below.
An exception to thi 8 .exists ..... fC:i:r;,:· v:i·t':~q~.+:;.·..
:.GJ:-:eated <with a "mlen" parameter grnate,r tpan ia sye;1:.:~·rn7 · ·

·.spe9.ified at Sysgen time.
(Sysgen does not ·allow t}"ii~:m~x.
9·reat:,er th(ln 512.) If a create Virtual Terminal ¢iir.~gt~:y~·Y.~
>wi.t:h· a "m:ten" parameter greater than the system~wJ(;l.~· in·~
pqraJt1.et;e~ ·. ls .. accepted,
but. intermE!d iat;e bµ~·f.e.r.!119: .f?:1i'. ..·•. .·•..,~·.9,:r;.$
vt(tual. terminal unit is automatically .··. ,disClb~~d~; ::.·.:~\.IXFh~~,f~l
in~ennediate... buf,fer ing
for that unit: cannot be en(lble(;l . RY.·~l'l,'F~
· .Vl? •the lO.STC function.
· · · · · .· ... ··
.·... ·· ... · . . .

·J?arent . tasks· specify' the first word of the ··:r10 .. c()ll\pleti<:>p···}$K~~

.·Jhe ·~ffspring request in the third parameter word of t.J;J.~.-);;);t'.'9 I?.~
···~.xa~p.J,e,< an

offspring input request may be honored \ wl.~p':;.
10 characters with IS .CR in th~ third para.rn,.et:.~. :r;
.~he<()ffspring request was for IO charc1cters .or ,merer ~l'l~· .· ~~.§9:.~ •..
()t. its I/O status would be set to 10 and 10 .qhar-·a.c1;~:t'·~ wq.ul.<f
:transferred •. A special I/O fUnction, IO.ST~,. r~.~t.trf'ls .. ~telt:\.l~··::t.:OJ•>
.qf;f:Jpring . task withou,t a data transfer,. The para,met~r .. wq:J;'g:•'fpi;
·~he IQ.STC function is as follows:
··

·'l()<Jigal .. of

·wordO bitO set, indicating status'.is·re94~s~~·w· ·

6-40

DIRECTIVE DESCRIPTIONS

6-41

DIRECTIVE DESCRIPTIONS

buffer

one

of the
should
the virtual
as the null

6-42

DIRECTIVE DESCRIPTIONS

.........

6-43

DIRECTIVE DESCRIPTIONS

CSRQ$
6.3.14

Cancel Time Based Initiation Requests

The Cancel Time Based Initiation Requests directive instructs the
system to cancel all time-synchronized initiation requests for a
specified task, regardless of the source of each request.
These
requests
result
from
a
Run directive, or from any of the
time-synchronized variations of the MCR Run command.
In a multiuser protection system, a nonprivileged task can only cancel
time-based initiation requests for a task with the same TI:.
FORTRAN Call:
CALL CANALL (tsk[,ids])
tsk

Task name

ids

Directive status

·~

Macro Call:
CSRQ$

tsk

Scheduled (target)

task name

Macro Expansion:
CSRQ$
.BYTE
.RAD50

ALPHA
25.,3
/ALPHA/

;CSRQ$ MACRO DIC, DPB SIZE=3 WORDS
;TASK 11 ALPHA 11

Local Symbol Definitions:
C.SRTN

Target task name (4)

DSW Return Codes:

rs.sue

Successful completion

IE. INS

Task is not installed

IE.PR!

The issuing task is not privileged and is
to cancel requests made by another task

IE.ADP

Part of the DPB is out of the issuing task's
space

IE.SOP

DIC or DPB size is invalid

attempting
address

Note:
If the programmer specifies an error routine address when using
the $C or $S macro form, then a null argument must be included
for RSX-llD compatibility.
For example:
CSRQ$S

TNAME:

#TNAME,,ERR

;CANCEL REQUESTS FOR

.RADSO /ALPHA/

6-44

ALPHA 11

DIRECTIVE DESCRIPTIONS

DECL$S
6.3.15

Declare Significant Event ($S form recommended)

The Declare Significant Event
declare a significant event.

directive

instructs

the

system

Declaration of a significant event causes the Executive to scan the
Active Task List from the beginning, searching for
the highest
priority task that is ready to run. This directive should be used
with discretion to avoid excessive scanning overhead.
FORTRAN Call:
CALL DECLAR ([,ids])
ids

Directive status

Macro Call:
DECL$S
err

[,err]
Error routine address

Macro Expansion:
DECL$S
MOV
.BYTg
EMT
BCC
JSR

,ERR
(PC)+,-(SP)
35.,1
377
.+6
PC,ERR

;NOTE:
THERE IS ONE IGNORED ARGUMENT
;PUSH DPB ONTO THE STACK
;DECL$S MACRO DIC, DPB SIZE=l WORD
;TRAP TO THE EXECUTIVE
;BRANCH IF DIRECTIVE SUCCESSFUL
;OTHERWISE, CALL ROUTINE "ERR"

Local Symbol Definitions:
None
DSW Return Codes:

rs.sue

Successful completion

IE.ADP

Part of the
space

IE .SOP

DIC or DPB size is invalid

DPB is out of the issuing task's address

Note:

•
The $S form of the macro is recommended
requires only a 1-word DPB.

6-45

because

this

directive

DIRECTIVE DESCRIPTIONS

DSAR$S
or
IHAR$S
6.3.16

Disable (or Inhibit) AST Recognition ($S form recommended)

The Disable (or Inhibit)
AST Recognition directive instructs the
system to disable recognition of ASTs for the issuing task.
The ASTs
are queued as they occur and are effected when the task reenables AST
recognition.
There is an implied AST disable recognition directive
whenever an AST service routine is executing. When a task's execution
is started, AST recognition is enabled.
See Notes below.
FORTRAN Call:
CALL DSASTR
or
CALL INASTR
ids

[(ids)]
[ (ids)]

Directive status

Macro Call:
DSAR$S
err

[err]
Error routine address

Macro Expansion:
DSAR$S
MOV
.BYTE
EMT
BCC
JSR

ERR
(PC)+,-(SP)
99., 1
377
.+6
PC,ERR

;PUSH DPB ONTO THE STACK
;DSAR$S MACRO DIC, DPB SIZE=l WORD
;TRAP TO THE EXECUTIVE
;BRANCH IF DIRECTIVE SUCCESSFUL
;OTHERWISE, CALL ROUTINE "ERR"

Local Symbol Definitions:
None
DSW Return Codes:

rs. sue

Successful completion

IE. I TS

AST recognition is already disabled

IE.ADP

Part of the
space

IE.SOP

DIC or DPB size is invalid

DPB is out of the issuing task's address

Notes:
1.

Only the recognition of ASTs is disabled by this directive;
the Executive still queues the ASTs.
They are queued FIFO
and will occur in that order when the task reenables AST
recognition.

The FORTRAN calls, DSASTR (or INASTR) and ENASTR (see Section
6.3.23)
exist solely to control the possible jump to the
PWRUP routine (power-up).
FORTRAN is not designed to link to
a system's trapping mechanism. The PWRUP routine is strictly

6-46

DIRECTIVE DESCRIPTIONS
controlled by the system.
It is the system that both accepts
the trap and subsequently dismisses it. The FORTRAN program
is notified by a jump to PWRUP but must use DSASTR
(or
INASTR)
and ENASTR to ensure the integrity of FORTRAN data
structures, most importantly the stack, during power-up
processing.
3.

Because this directive requires only a 1-word DPB,
the $S
form of the macro is recommended.
It requires less space and
executes with the same speed as the DIR$ macro.

6-47

DIRECTIVE DESCRIPTIONS

DSCP$S
6.3.17

Disable Checkpointing ($S form recommended)

The Disable Checkpointing directive instructs the system to disable
the checkpointability of a
task that has been installed as a
checkpointable task. This directive can be issued only by the task
that is to be affected. A task cannot disable the ability of another
task to be checkpointed.
FORTRAN Call:
CALL DISCKP
ids

Directive status

Macro Call:
DSCP$S
err

[err]
Error routine address

Macro Expansion:
DSCP$S
MOV
.BYTE
EMT
BCC
JSR

ERR
(PC)+,-(SP)
95.,1
377
.+6
PC,ERR

;PUSH DPB ONTO THE STACK
;DSCP$S MACRO DIC, DPB SIZE=l WORD
;TRAP TO THE EXECUTIVE
;BRANCH IF DIRECTIVE SUCCESSFUL
;OTHERWISE, CALL ROUTINE "ERR"

Local Symbol Definitions:
None
DSW Return Codes:

rs.sue

Successful completion

IE.ITS

Task checkpointing is already disabled

IE.CKP

Issuing task is not checkpointable

IE.ADP

Part of the DPB is out of the issuing task's address
space

IE.SOP

DIC or DPB size is invalid

Notes:
1.

When a
checkpointable
task's
execution
checkpointing
is
enabled
(that is,
the
checkpointed).

is
started,
task can be

Because this directive requires only a 1-word DPB,
the $S
form of the macro is recommended.
It requires less space and
executes with the same speed as the DIR$ macro.

6-48

DIRECTIVE DESCRIPTIONS

DTRG$
6.3.18

Detach Region

The Detach Region directive detaches the
issuing task from
a
spec:ified, previously attached region. Any of the task's windows that
are currently mapped to the region are automatically unmapped.
If RS.MDL is set in the region status word when the directive
is
issued,
the task marks the region for deletion on the last detach. A
task must be attached with delete access to mark a
region for
delE!tion.
FOR'rRAN Call::
CALL DTRG (irdb[,ids])
irdb

An 8-word integer array containing a Region Definition
Block (see Section 3.5.1.2)

ids

Directive status

Macro Call:
DTRG$
rdb

rdb
Region Definition Block address

Mac1ro Expansion:
DTRG$
.BYTE
.WORD

RDBADR
59. '2
RDBADR

;DTRG$ MACRO DIC, DPB SIZE=2 WORDS
;RDB ADDRESS

Region Definition Block Parameters:
Input parameters
Array
Element

Offset

irdb(l)

R.GID

ID of the region to be detached

irdb(7)

R.GSTS

Bit

settingsl

the

region status word:

RS.MDL -- 1 if the region should be marked
for deletion when the last task
detaches from it

•

Output parameters
irdb(7)

R.GSTS

Bit

settingsl in the

RS.UNM -- l

any

region

status word:

windows

were unmapped

Local Symbol Definitions:
D.TRBA

Region Definition Block address (2)

1 FORTRAN programmers should refer to Section 3.5.l to determine
bit values represented by the symbolic names described.

6-49

the

DIRECTIVE DESCRIPTIONS
DSW Return

Cod~s:

Is.sue

Successful completion

IE.PR!

The task, which is not attached with delete access,
has attempted to mark the region for deletion on the
last detach, or the task has outstanding I/O
(not
necessarily to this region)

IE.NVR

The task specified an invalid region ID or
to detach region O (its own task region)

IE .ADP

Part of the DPD or RDB is out of the
address space

IE.SOP

DIC or DPB size is invalid

6-50

attempted

issuing

task's

•

DIRECTIVE DESCRIPTIONS

ELAW$
6.3.19

Eliminate Address Window

The Eliminate Address Window directive deletes an existing address
window,
unmapping
it first
if necessary.
Subsequent use of the
eliminated window's ID is invalid.
FOHTRAN Call:
CALL ELAW (iwdb[,ids])
iwdb

A Window Definition
Block
composed
integer array (see Section 3.5.2.2)

ids

Directive status

of an

8-word

Mac:ro Call:
ELAW$

wdb
Window Definition Block address

wdb

Macro Expansion:
ELAW$
.BYTE
.WORD

WDBADR
119 • I 2
WDBADR

;ELAW$ MACRO DIC, DPB SIZE=2 WORDS
;WDB ADDRESS

Window Definition Block Parameters:
Input

paramE~ters

Array
~en~

Off set

i wdb ( 1)
bits 0-7

W.NID

ID of the address window to be eliminated

W.NSTS

Bit settingsl in the window status word:

Output

parameter~

iwdb(7)

WS.ELW

1 if the address window
successfully eliminated

was

WS.UNM

1 if the address
unmapped

window

was

1 FORTRAN programmers should refer to Section 3.5.2 to determine
bit values represented by the symbolic names described.

the

Local Symbol Definitions:
E.LABA

Window Definition Block address (2)

DSW Return Codes:
...

rs.sue

Successful completion

IE.NVW

Invalid address window ID

6-51

DIRECTIVE DESCRIPTIONS
IE.ADP

Part of the DPB or WDB is out of the issuing task's
address space

IE.SOP

DIC or DPB size is invalid

""i

6-52

DIRECTIVE DESCRIPTIONS

ELGF$
6.3o20

Eliminate Group Global Event Flags

The Eliminate Group Global Event Flags directive marks group-global
event flags
for deletion.
If no tasks in this group are waiting for
group-global event flags (the count for this group maintained by the
Executive
in G.CNT is 0), the Group Global Event Flags Control Block
(GFB) is immediately unlinked and deallocated.
If tasks are waiting
for
flags
in this group, the Executive marks the flags for deletion
(GS~DEL is set to 1) and the GFB is eliminated when no remaining tasks
are waiting for
flags
in this group;
however, if a Create Group
Global Event Flags directive
is issued before the
flags
are
eliminated, the Executive clears GS.DEL.
FOR~rRAN

CALL:

CALL ELGF ( [grOUJ?] , [ids])
group

Group number of flags
to be eliminated.
Only
privileged tasks can specify group numbers other than
the issuing task's group UIC.
If not specified,
the
task's protection UIC (H.CUIC+l) in the task's header
is used.

ids

Integer to receive the Directive Status Word

Macro Call:
ELG F $

[ g r o up]

group

Group number of flags to be eliminated.
Only
privileged tasks can specify group numbers other than
the issuing task's group UIC.
If not specified,
the
task's protection UIC (H.CUIC+l) in the task's header
is used.

Macro Expansion:
ELGF$
.BYTE
.WORD

303
159.,2
303

;ELGF$ MACRO DIC, DPB SIZE=2 WORDS
;GROUP NUMBER 303 FLAGS

Local Symbol Definitions:
E.LGRP -- Group number

(2)

DSW Return Codes:

rs.sue

Successful completion

IE. PR!

Privilege violation

IE. I UI

Invalid group

IE. H~F

Group not found

IE.RSU

Event flags are already marked for deletion

IE.ADP

Part of the DPB is out of the
space

IE.DIC -- DIC or DPB size is invalid

6-53

issuing

task's

address

DIRECTIVE DESCRIPTIONS

6-54

DIRECTIVE DESCRIPTIONS

.......

6-55

DIRECTIVE DESCRIPTIONS

The.Emit Status directive returns the
·.::'$peclfied <::onnected task, possibly
::.an A.$T if previously specified by the
:: Reqµest And Connect, a Spawn, or a Connect
·.·ts specified, this action is taken for
. J<:> the . issuin9 .task at that titne • J:f
gonriec;=ted to the task issuing
di
.Q~fsprlng
Control Block (OCB}
:.,tr, (iny case, wpenever status is emf
' tasks . no longer remain connected to

<<:ti r~ctlve.

.([rtname] ,status[,ids])
=

Name of task connected
status is to be emitted
16-bit quantity to
Integer to receive

Name of a
which the
.16-bit qµantity to be

ALPHA,STWD
147., 4

ALPHA
STWD

Task name

( 4)

Status to be returned

Successful completion
The sp~cified task
task

space

of the DPB is

DIC or DPB size is

6-56

DIRECTIVE DESCRIPTIONS

ENAR$S
6.3.23

•

Enable AST Recognition ($S form recommended)

ThE! Enable AST Recognition directive instructs the system to recognize
ASTs for the issuing task;
that is, the directive nullifies a Disable
AST Recognition directive. ASTs that were queued while recognition
was disabled are effected at issuance. When a task's execution is
started, AST recognition is enabled.
FOHTRAN Call:
CALL ENASTR
ids

[(ids)]

Directive status

Macro Call:
ENAR$S
err

[err]
Error routine address

Macro Expansion:
ENAR$S
MOV
.BYTE
EMT
BCC
JSR

ERR
(PC)+,-(SP)
101., 1
377

.+6
PC,ERR

;PUSH DPB ONTO THE STACK
;ENAR$S MACRO DIC, DPB SIZE=l WORD
;TRAP TO THE EXECUTIVE
;BRANCE IF DIRECTIVE SUCCESSFUL
;OTHERWISE, CALL ROUTINE "ERR"

Local Symbol Definitions:
None
DSW Return Codes:

rs. sue

Successful completion

IE. I ~rs

AST recognition is not disabled

IE.ADP

Part of the DPB is out of the issuing task's
space

IE.SDP

DIC or DPB size is invalid

address

Notes:
1.

Because this directive requires only a 1-word DPB,
the $S
form of the macro is recommended.
It requires less space and
executes with the same speed as the DIR$ macro.

The FORTRAN calls DSASTR (or INASTR) (see Section 6.3.16) and
ENASTR exist solely to control the jump to the PWRUP routine
(power-up).
FORTRAN is not designed to link to a system's
trapping mechanism. The PWRUP routine is strictly controlled
by the system.
It is the system which both accepts the trap
and subsequently dismisses it.
The FORTRAN program is
notified by a jump to PWRUP but must use DSASTR
(or INASTR)
and
ENASTR
to
ensure the
integrity of FORTRAN data
structures, most importantly the stack, during power-up
processing.

6-57

DIRECTIVE DESCRIPTIONS

ENCP$S
6.3.24

Enable Checkpointing ($S form recommended)

The Enable Checkpointing directive ·instructs the system to make the
issuing task checkpointable after its checkpointability has been
disabled;
that is, the directive nullifies a DSCP$S directive.
FORTRAN Call:
CALL ENACKP
ids

Directive status

Macro Call:
ENCP$S
err

[err]
Error routine address

Macro Expansion:
ENCP$S
MOV
.BYTE
EMT
BCC
JSR

ERR
(PC)+,-(SP)
97., l
377

.+6
PC,ERR

;PUSH DPB ONTO THE STACK
;ENCP$S MACRO DIC, DPB SIZE=l WORD
;TRAP TO THE EXECUTIVE
;BRANCH IF DIRECTIVE SUCCESSFUL
;OTHERWISE, CALL ROUTINE "ERR"

Local Symbol Definitions:
None
DSW Return Codes:

rs.sue

Successful completion

IE.ITS

Checkpointing is not disabled or task is connected to
an interrupt vector

IE.ADP

Part of the DPB is out of the issuing task's
space

IE.SOP

DIC or DPB size is invalid

address

Note:
Because this directive requires only a 1-word DPB, the $S form of
the macro
is recommended.
It requires less space and executes
with the same speed as the DIR$ macro.

6-58

•

DIRECTIVE DESCRIPTIONS

EXIF$
6 • 3 • 25

Ex i. t

The Exit If directive instructs the system to terminate the execution
of the
issuing task if, and only if, an indicated event flag is NOT
set.
The Executive returns control
to the
issuing task
if the
specified event flag is set.
See Notes below.
FORTRAN Call:
CALL EXITIF (efn[,ids])
efn

Event flag number

ids

Directive status

Macro Call:
EXIF$
efn

efn
Event flag number

Macro Expansi.on:
EXIF$
.BYTE
• WORD

52.
53.,2
52.

;EXIF$ MACRO DIC, DPB SIZE=2 WORDS
;EVENT FLAG NUMBER 52 •

Local Symbol Definitions:
E. XFEJ~

Event flag number

(2)

DSW Return Codes:
IS.SE'r

Indicated EFN set, task did not exit

IE. I EF

Invalid event flag number

IE .ADP

Part of the DPB is out of the issuing task's
space

IE.SDP

DIC or DPB size is invalid

(EFN>64 or EFN< 1)
address

Notes:
1.

The Exit If directive is useful in avoiding a
possible race
condition that can occur between two tasks communicating via
the Send and Receive directives.
The race condition occurs
when one task executes a Receive directive and finds its
receive queue empty;
but before the task can exit, the other
task sends
it a message.
The message is lost because the
Executive flushed the receiver task's receive queue when it
decided
to exit.
This condition can be avoided if the
sending task specifies a common event flag
in the Send
directive
and the
receiving
task executes an Exit If
specifying the same common event flag.
If the event flag
is
set, the Exit If directive will return control to the issuing
task, signaling that something has been sent.

A FORTRAN program that issues the Exit If call must first
close all
files by issuing Close calls.
See the IAS/RSX-11

6-59

DIRECTIVE DESCRIPTIONS
FORTRAN IV or FORTRAN IV-PLUS User's Guide for
instructions
on how to ensure that such files are closed properly if the
task exits. To avoid the time overhead involved in the
closing and reopening of files, the task should f1rst issue
the appropriate test or clear event flag directive.
If the
directive status word. indicates that the flag was not set,
then the task can close all files and issue the call to Exit
If.
3.

On Exit, the Executive frees task resources.
the Executive:

particular,

•

Detaches all attached devices

•

Flushes the AST queue

•

Flushes the receive and receive-by-reference queues

•

Flushes the clock queue for any
requests for the task

outstanding

Mark

Time

•

Closes all open files (files open for write
locked)

access

are

•

Detaches all attached tasks, except in the
fixed
task in a system that supports
management directives

case of a
the memory

•

Runs down the task's I/O

•

Frees the task's memory if
fixed

•

Disconnects all connected tasks

If the task
event.

exits,

the

Executive

6-60

exiting

task

declares

was

not

significant

DIRECTIVE DESCRIPTIONS

EXIT$S
6.3.26

Task Exit ($S form recommended)

The Task Exit directive
instructs
execution of the issuing task.

the

system

terminate

the

FORTRAN Call:
CALL EXIT
or
STOP
[messg]
messg

Optional 1- to 26-character string to
when the STOP statement is executed

displayed

Macro Call:
EXIT$S

[err]

err

"-"''

Error routine address

Macro Expansion:
EXIT$S
MOV
.BYTE
EMT
JSR

ERR
(PC)+,-(SP)
51. '.1
377
PC,ERR

;PUSH DPB ONTO THE STACK
;EXIT$S MACRO DIC, DPB SIZE=l WORD
;TRAP TO THE EXECUTIVE
;CALL ROUTINE "ERR"

Local Symbol Definitions:
None
DSW Return Codes:
IE.ADP

Part of the DPB is out of the issuing task's
space

IE.SOP

DIC or DPB size is invalid

address

Notes:

A return to the task occurs if, and only if, the directive is
iejected. Therefore, no Branch on Carry Clear instruction is
generated if an error routine address is given,
since the
return will only occur with carry set.

Exit causes a significant event.

On Exit, the Executive frees task resources.
the Executive:

particular,

•

Detaches all attached devices

•

Flushes the AST queue

•

Flushes the receive and receive-by-reference queues

•

Flushes the clock queue for any
requests for the task

6-61

outstanding

Mark

Time

DIRECTIVE DESCRIPTIONS
•

Closes all open files (files open for write
locked)

•

Detaches all attached regions, except in the case
fixed task, where no detaching occurs

•

Runs down the task's I/O

•

Frees the task's memory if
fixed

•

Disconnects all connected tasks

the

exiting

access

task

was

are
of

not

Because this directive requires only a 1-word DPB, the $S for
of the macro
is recommended.
It requires less space and
executes with the same speed as the DIR$ macro.

FORTRAN tasks that terminate with the STOP statement rE~sult
in a message being displayed on the task's TI:.
This message
includes task name (as it appears in the Active Task List),
the statement causing the task to stop, and an optional
character string specified in the STOP statement.
Tasks that
terminate with CALL EXIT do not display a termination
message.
For example,
a FORTRAN task
containing
the
following statement:
20

STOP 'THIS FORTRAN TASK'

exits with the following message displayed on the
(TT37 in this example):

tasks

TI:

TT37 -- STOP THIS FORTRAN TASK

6-62

DIRECTIVE DESCRIPTIONS

EXST$

'-''

6.3.27

Exit With Status

The Exit With Status directive causes the
issuing task to exit,
passing a
16-bit status back to all tasks ~onnected (via the Spawn,
connect , i\~.~~~;;;~~'.fl~;:li!H.IV~;St'.}t~!:~:i;'i~/t't.~4ig~;~:it't~;~qi~~) d i rec t iv e ) • I f the i s s u i ng task
has no connected tasks,
then the directive simply performs a Task
Exit.
No format of the status word
is enforced by the Executive;
format conventions are a function of the cooperation between parent
and offspring tasks.
However, if an offspring task aborts for
any
reason, a status of EX$SEV is returned to the parent task. J.Will1~!~#:1',i:,i~i'.{\l~·i;R'.:
'.':i:;''.";;;{,~'~iP:·~.~/~:~J~'~;j:!;~;F1NH:~t~Vlrj;~:1,{f;i:.,~i.4i~~~i~;;!f'ii!~~:~i.~Mi~~~!t'i'·:!r.~'M(ffl~~~11~'.~tiifo'.j~'.f:,§}~'!i~~~];~.~l.,~n'1i
Fu r the rm o r e ,
if a
task performs a normal exit with other tasks connected to it, a
status of EX$SUC (successful completion) is returned to all connected
tasks.
FOR'TRAN Call:
CALL EXST (status)
status

16-bit quantity to be returned to parent task

Macro Call:
EXST$

status

16-bit quantity to be returned to parent task

Macro Expansion:
EXST$
.BYTE
.WORD

STWD
29 .• '2

STWD

;EXST$ MACRO DIC, DPB SIZE=2 WORDS
;VALUE OF STATUS TO BE RETURNED

Local Symbol Definitions:
E.XSTS

Value of status to be returned

(2)

DSW Return Codes:
No status is returned if the directive is successfully
since the directive causes the issuing task to exit.
IE.ADP

Part of the DPB is out of the issuing task's
space

IE.SOP

DIC or DPB size is invalid

6-63

completed
address

DIRECTIVE DESCRIPTIONS

EXTK$
6.3.28

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,
the
Executive makes the issuing task's size equal to its installed size.
The issuing task must be running
in a system-controlled partition,
must not use memory-resident overlays, and cannot have any outstanding
I/O when it issues the directive.
The
task
must
also
be
checkpointable to increase
its size;
if necessary, the Executive
checkpoints the task, then returns the task to memory with its size
modified as directed.
In a system that supports the memory management directives,
the
Executive does not change any current mapping assignments if the task
has memory-resident overlays. However, if the task does not have
memory-resident overlays,
the Executive attempts to modify, by the
specified number of 32-word blocks, the mapping of the task to
its
task region.
If the
issuing task is checkpointable but has no preallocated
checkpoint space available, a positive increment may require dynamic
memory and extra space in a checkpoint file sufficient to contain the
task.
There are several constraints on the size to which a task
itself using the Extend directive:

can

extend

•

No task can extend itself beyond the maximum size set by the
MCR command SET /MAXEXT or the size of the partition in which
it is running.
(See the ~SX-llM/M-PLUS MCR
Operations
Manual.)

·•

A task that does not have memory-resident
extend itself beyond 32K minus 32 words.

•

A task that has preallocated checkpoint space in its task
image file cannot extend itself beyond its installed size.

•

A task that has memory-resident
size.

overlays

cannot

reduce

its

FORTRAN Call:
CALL EXTTSK ( [inc] [,ids])
inc

A positive or negative number equal to
the number of
32-word blocks by which the task size is to be extended
or reduced

ids

Directive status

Macro Call:
EXTK$
inc

[inc]
A positive or negative number equal to the number of
32-word blocks by which the task size is to be extended
or reduced

6-64

DIRECTIVE DESCRIPTIONS
Macro Expansion:

EXTK$
.BYTE
.WORD

40
89. '3
40

.WORD

;EXTK$ MACRO DIC, DPB SIZE=3 WORDS
;EXTEND INCREMENT, 40(8) BLOCKS (lK
;WORDS)
;RESERVED WORD

Local Symbol Definitions:
E .XTIN

Extend increment (2)

DSW Return Codes:

rs.sue

Successful completion

IE.UPN

Insufficient dynamic memory, or insufficient space in
a checkpoint file

IE. I TS

Task has memory-resident overlays and
to reduce its size

IE.ALG

The issuing task attempted to reduce its size to less
than the size of its task header;
or the task tried
to increase its size beyond 32K words or beyond the
maximum set by the MCR SET /MAXEXT command;
or the
task tried to increase its size to the extent that
one virtual address window would overlap another

IE.ADP

Part of the DPB is out of the issuing task's
space

IE.RSU

Other tasks are attached

IE. IOP

I/O is in progress

IE.CKP

Task is not checkpointable and specified
integer

IE.NSW

Attempt to extend to larger than installed size (when
checkpoint space is allocated in the task)

IE.SOP

DIC or DPB size is invalid

6-65

attempting

address

positive

DIRECTIVE DESCRIPTIONS

GLUN$
6.3.29

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.
If requests to the physical device unit have been
redirected to another unit, the information returned will describe the
effective assignment.
FORTRAN Call:
CALL GETLUN (lun,dat[,ids])
lun

Logical unit number

dat

6-word integer array to receive LUN information

ids

Directive status

Macro Call:
GLUN$

lun,buf

lun

Logical unit number

buf

Address of
information

6-word

buffer that

will

receive the LUN

Buffer Format:
word

Name of assigned device

word

Unit number of assigned device and flags byte (flags
byte equals 200 if the device driver is resident or
O if the driver is not loaded)

word

First device characteristics word:
Bit 0

Record-or:iented device (l=yes)

Bit 1

Carriage-control device (l=yes) [FD.CCL]

Bit 2

Terminal device (l=yes) [FD.TTY]

Bit 3

Directory
(file-structured)
(l=yes) [FD.DIR]

Bit 4

Single diirectory device (l=yes) [FD.SDI]

Bit 5

Sequential device (l=yes) [FD.SQD]

Bit 6

Reserved

Bit 7

User-mode diagnostics supported (l=yes)

Bit 8

Massbus device (l=yes)

Bit 9

Unit software write-locked (l=yes)

Bit 10

Input spooled device (l=yes)

6-66

[FD.REC] 1

device

DIRECTIVE DESCRIPTIONS
Bit 11

Output spooled device (l=yes)

Bit 12

Pseudo device (l=yes)

Bit 13

Device mountable
channel ( l=yes)

Bit 14 --

Device mountable
( l=yes)

Bit 15

Device mountable (l=yes)

communications

a
a

Files-11

device

word

Second device characteristics word

word

Third device characteristics word (words 3 and 4 are
device driver specific)

word

Fourth device characteristics word

Macro Expansion:
GLUN$
.BYTE
.WORD
.WORD

·'-".

7,LUNBUF
5,3
7

LUNBUF

;GLUN$ MACRO DIC, DPB SIZE=3 WORDS
;LOGICAL UNIT NUMBER 7
;ADDRESS OF 6-WORD BUFFER

Local Symbol Definitions:
G.LULU

Logical unit number

G.LUBA

Buffer address (2)

(2)

The following offsets are assigned relative to the start
information buffer:
G.LUNA

Device name (2)

G.LUNU

Device unit number

G.LUFB

Flags byte (1)

G.LUCW

Four device characteristics words (8)

the

LUN

(1)

DSW Return Codes:

rs.sue

Successful completion

IE.ULN

Unassigned LUN

IE.ILU

Invalid logical unit number

IE .ADP

Part of the DPB or buffer is
task's address space

out

the

issuing

DIC or DPB size is invalid

Bits with associated symbols have the symbols shown
in square
brackets.
These symbols can be defined for use by a task via the
FCSBT$ macro.
See the IAS/RSX-11 I/O Operations Reference Manual.

6-67

DIRECTIVE DESCRIPTIONS

•

6-68

DIRECTIVE DESCRIPTIONS

GMCR$
6.3.30

Get MCR Command Line

The Get MCR Command Line directive instructs the system to transfer an
80-byte command line to the issuing task •

•

When a task is installed with a task name of " ••• tsk"
or "tskTn",
where "tsk" consists of three alphanumeric characters and n is an
octal
terminal
number,
the MCR dispatcher
requests the
task's
execution when a user issues the command:
>tsk command-line
from terminal number n.
A task invoked in this manner must execute a
call
to Get MCR Command Line, which results in the entire "command
line" following the prompt being placed into an 80-byte command line
buffer.
(The MCR dispatcher is de~cribed in the RSX-llM/M-PLUS MCR
~rations Manual~}

FORTRAN Call:
CALL GETMCR (buf[,ids]}
buf

80-byte array to receive command line

ids

Directive status

Macro Call:
GMCR$
Macro Expansion:
GMCR$
• BYTE:
.BLKW

127.,41 •
40.

;GMCR$ MACRO DIC, DPB SIZE=41. WORDS
;80.
CHARACTER MCR COMMAND LINE BUFFER

Local Symbol Definitions:
G. MCRB

MCR line buffer

(80}

DSW Return Codes:
+n

Successful completion;
n is the number of data bytes
transferred
(excluding the termination character}.
The termination character is, however, in the buffer.

IE.AST

No MCR command line exists for
the
issuing task;
that is, the task was not requested by a command line
as follows:
>tsk command-string
or the task has already issued the
Line directive.

MCR

Command

IE .ADP

Part of the DPB is out of the issuing task's
space.

address

IE.SDP

DIC or DPB size is invalid.

6-69

Get

DIRECTIVE DESCRIPTIONS
Notes:
1.

The GMCR$S form of the macro is not supplied, since
receives the actual command line.

The system processes all lines to:
•

Convert tabs to a single space

•

Convert multiple spaces to a single space

•

Convert lower case to upper case

•

Remove all trailing blanks

The terminator (<CR> or <ESC>)
line.

6-70

is the last character

the

DPB

•

the

DIRECTIVE DESCRIPTIONS

GMCX$
6.3.31

Get Mapping Context

The Get Mapping Context directive causes the Executive
to
return a
description of the current window-to-region mapping assignments.
The
returned description is in a form that enables the user to restore the
mapping
context through a series of Create Address Window directives
(see Section 6.3.10).
The macro argument specifies the address of a
vector that contains one Window Definition Block (WDB) for each window
block allocated in the task's header, plus a terminator word.
For each window block in the task's header, the Executive
WDB in the vector as follows:

sets

If the window block is unused
(that
is,
if
it does not
correspond to an existing address window) , the Executive does
not record
any
information about that block
in a WDB.
Instead,
the Executive uses the WDB to record information
about the first block encountered
that corresponds to an
existing window.
In t'his way,
unused window blocks are
ignored in the mapping context description returned
by the
Executive.

If a window block describes an existing
unmapped address
window,
the
Executive
fills
in the offsets W.NID, W.NAPR,
W.NBAS, and W.NSIZ with information sufficient to
recreate
the window.
The window status word W.NSTS is cleared.

If a window block describes an existing mapped window,
the
Executive
fills
in the offsets W.NAPR,
W.NBAS,
W.NSIZ,
W.NRID,
W.NOFF,
W.NLEN,
and
W.NSTS
with
information
sufficient to create and map the address window.
WS.MAP is
set in the status word (W.NSTS), and if the window is mapped
with write access, the bit WS.WRT is set as well.

Note that in no case does the Executive modify W.NSRB.
The terminator word, which follows the last WDB filled in, is a word
equal
to
the negative of the total number of window blocks in the
task's header.
It
is thereby possible
to
issue a
TST or TSTB
instruction
to detect the last WDB used
in the vector.
The
terminating word can also be used to determine the number of window
blocks built into the task's header.
When Create Address Window directives are used to restore the mapping
context,
there
is no guarantee that the same address window IDs will
be used.
The user must therefore be careful to use the latest window
IDs returned from the Create Address Window directives •

•

FOFtTRAN Call:
CALL GMCX (imcx[,ids])
imcx

An integer array to receive the mapping context.
The
size of the array is 8*n+l where n is 4he number of
window blocks in the task's header.
The maximum size
is 8*8+1=65 words.

ids

Directive status

6-71

DrRECTIVE DESCRIPTIONS
Macro Call:
GMCX$

wvec

The address of a vector of n Window Definition Blocks,
followed
by a
terminator word;
n is the number of
window blocks in the task's header

Macro Expansion:
GMCX$
.BYTE
.WORD

•

VECADR
113.,2
VECADR

;GMCX$ MACRO DIC, DPB SIZE=2 WORDS
;WDB VECTOR ADDRESS

Window Definition Block Parameters:
Input parameters
None
Output parameters
Array
Element

Off set

i wdb ( 1)
bits 0-7

W.NID

ID of address window

iwdb ( 1)
bits 8-15

W.NAPR

Base APR of the window

i wd b ( 2)

W.NBAS

Base virtual address of the window

iwdb ( 3)

W.NSIZ

Size, in 32-word blocks, of the window

iwdb(4)

W.NRID

ID of the mapped region, or no change if
the window is unmapped

iwdb ( 5)

W.NOFF

Offset, in 32-word blocks, from the start
of the region at which mapping begins, or
no change if the window is unmapped

iwd b ( 6)

W.NLEN

Length, in 32-word blocks,
of the area
currently mapped within the region, or no
change if the window is unmapped

iwdb(7)

W.NSTS

Bit settingsl in the window status word
(all 0 if the window is not mapped):
WS.MAP

1 if the window is mapped

WS.WRT

1 if the window
with write access

~
'I

mapped

Note that the length mapped (W.NLEN) can be less than the size of
the window
(W.NSIZ)
if the area from W.NOFF to the end of the
partition is smaller than the window size.

FORTRAN programmers should refer to Section 3.5.2 to determine
bit values represented by the symbolic names described.

6-72

the

DIRECTIVE DESCRIPTIONS

Local Symbol Definitions:
G.MCVA

Address of the vector (wvec)
containing the· window
definition blocks and terminator word (2)

DSW Return Codes:

•

rs. sue

Successful completion

IE.ADP

Address check of the DPB or the vector (wvec) failed

IE.SOP

DIC or DPB size is invalid

•

6-73

DIRECTIVE DESCRIPTIONS

GPRT$
6.3.32

Get Partition Parameters

The Get Partition Parameters directive instructs the system to fill an
indicated 3-word buffer with partition parameters.
If a partition is
not specified, the partition of the issuing task is assumed.

•

FORTRAN Call:
CALL GETPAR {[prt] ,buf[,ids])
prt

Partition name

buf

3-word integer array to receive partition parameters

ids

Directive status

Macro Call:
GPRT$

.
..
~~,·1.
·~-'"

[prt] ,buf

prt

Partition name

buf

Address of a 3-word buffer

---~1L·

Buffer Format:
word

Partition physical base address expressed as a
multiple of 32 words (partitions are always aligned
on 32-word boundaries).
Therefore,
a
partition
starting at 40000(8)
will have 400(8) returned in
this word.

word

Partition size expressed as a multiple of 32 words.

word

Partition flags word.
This word is returned equal
to
0 to indicate a system-controlled partition, or
equal to 1 to indicate a user-controlled partition.

Macro Expansion:
GPRT$
.BYTE
.RADSO
.WORD

ALPHA,DATBUF
65 • t 4

/ALPHA/
DATBUF

;GPRT$ DIC, DPB SIZE=4 WORDS
;PARTITION "ALPHA"
;ADDRESS OF 3-WORD BUFFER

Local Symbol Definitions:
G.PRPN

Partition name

(4)

G.PRBA

Buffer address (2)

•
The following offsets are assigned
partition parameters buffer:
G.PRPB

relative

Partition physical
base address
absolute 32-word block number (2)

6-74

the

start

the

expressed

•

DIRECTIVE DESCRIPTIONS
G.PRPS

Partition size expressed as
blocks ( 2)

G.PRPW

Partition flags word (2)

multiple

32-word

DSW Return Codes:
Successful completion is indicated by a cleared Carry bit,
and
the starting address of the partition is returned in the DSW.
The returned address is a physical address expressed
in 32-word
blocks.
Unsuccessful completion is indicated by a set Carry bit
and one of ~he following codes in the DSW:
IE.INS

Specified partition not in system

IE .ADP

Part of the DPB or buffer is
task's address space

IE.SDP

DIC or DPB size is invalid

out of the

issuing

Notes:
1.

Por Executives that support the memory management directives,
a variation of this directive exists called Get Region
Parameters (see Section 6.3.33). When the first word of the
2-word partition name
is O,
the Executive interprets the
second word of the partition name as a
region ID.
If the
2-word name
is O,O,
it refers to the task region of the
issuing task.

Omission of the partition-name argument returns parameters
for
the
issuing task's unnamed subpartition, not for the
system-controlled partition •

•

6-75

DIRECTIVE DESCRIPTIONS

GREG$
6.3.33

Get Region Parameters

The Get Region Parameters directive instructs the Executive to fill an
indicated 3-word buffer with region parameters.
If a region is not
specified, the task region of the issuing task is assumed.
This directive is a variation of the Get Partition Parameters
directive
(see Section 6.3.32) for Executives that support the memory
management directives.
FORTRAN Call:
CALL GETREG ([rid],buf[,ids])
rid

Region id

buf

3-word integer array to receive region parameters

ids

Directive status

Macro Call:
[rid] ,buf

GREG$
rid

Region ID

buf

Address of a 3-word buffer

Buffer Format:
word

Region base address expressed as a multiple of 32
words
(regions
are always aligned on 32-word
boundaries). Thus, a
region starting at 1000(8)
will have 10(8) returned in this word.

word

Region size expressed as a multiple of 32 words.

word

Region flags word. This word is returned equal to 0
if
the
region resides in a system-controlled
partition, or equal to 1 if the region resides in a
user-controlled partition.

Macro Expansion:
GREG$
.BYTE
.WORD

RID,DATBUF
65.,4

.WORD
.WORD

RID
DATBUF

;GREG$ MACRO DIC, DPB SIZE=4 WORDS
;WORD THAT DISTINGUISHES GRE$
;FROM GPHT$
; REGION :CD
;ADDRESS OF 3-WORD BUFFER

Local Symbol Definitions:
G.RGID

Region ID (2)

G .RGBA

Buffer address

•

6-76

DIRECTIVE DESCRIPTIONS
The following offsets are assigned relative to the start of the region
parameters buffer:

"-"'

G .RGRB

Region base address expressed as an absolute
block number ( 2)

32-word

G .RGRS

Region size
blocks ( 2)

32-word

G .RGFW

Region flags word ( 2)

expressed

multiple

DSW Return Codes:
Successful completion
starting address of
returned address is
indicated by carry set

·~·

is indicated by carry clear,
and the
the region is returned in the DSW. The
physical.
Unsuccessful
completion
is
and one of the following codes in the DSW:

IE.NVR

Invalid region ID

IE.ADP

Part of the DPB or
task's address space

IE. SDP

DIC or DPB size is invalid

•

6-77

buffer

is out

of the issuing

DIRECTIVE DESCRIPTIONS

GSSW$S
6.3.34

Get Sense Switches ($S form recommended)

The Get Sense Switches directive instructs the system to obtain the
contents of the console switch register and store it in the issuing
task's Directive Status word.
FORTRAN Call:
CALL READSW (isw)
isw

Integer to receive the console switch settings

The following FORTRAN call allows a program to read
single switch:
CALL SSWTCH

the

state

(ibt,ist)

ibt

The switch to be tested (0 to 15)

ist

Test results where
1

switch on

switch off

Macro Call:
GSSW$S
err

[err]
Error routine address

Macro Expansion:
GSSW$S
MOV
.BYTE
EMT
BCC
JSR

ERR
(PC)+,-(SP)
125.,l
377
.+6
PC,ERR

;PUSH DPB ONTO THE STACK
;GSSW$S MACRO DIC, DPB SIZE=l WORD
;TRAP TO THE EXECUTIVE
;BRANCH IF DIRECTIVE SUCCESSFUL
;OTHERWISE, CALL ROUTINE "ERR"

Local Symbol Definitions:
None
DSW Return Codes:
Successful completion is indicated by carry clear, and the
contents of the console switch register are returned in the DSW.
Unsuccessful completion is indicated by carry set and one of the
following codes in the DSW:
IE.ADP

Part· of the
address space

IE. SDP

DIC or DPB size is invalid

DPB

out

the issuing

task's

Note:
Because this directive requires only a 1-word DPB, the $S form of
the macro
is recommended.
It requires less space and executes
with the same speed as the DIR$ macro.

6-78

•

DIRECTIVE DESCRIPTIONS

GTIM$
6.3.35

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
(in
decimal) are shown in the table b~low.
FOR~rRAN

Call:

FORTRAN provides several subroutines for obtaining the time in a
number of formats.
See the IAS/RSX-llM FORTRAN IV or the FORTRAN
IV-PLUS User's Guide.
Macro Call:
buf

GTIM$
buf

Address of 8-word buffer

Buffer Format:
word

Year

word

Month (1-12)

word

Day ( 1-31)

word

Hour

word

Minute (0-59)

\'{Ord

Second (0-59)

word

Tick of second (depends on the frequency of the
clock)

word

Ticks per second (depends on the frequency of the
clock)

(since 1900)

(0-23)

Macro Expansion:
GTIM$
.BYTE
.WORD

DATBUF
61.,2
DATBUF

;GTIM$ DIC, DPB SIZE=2 WORDS
;ADDRESS OF 8.-WORD BUFFER

Local Symbol Definitions:

•

G .TIBA

Buffer address (2)

The following offsets are assigned relative to the start of
parameters buffer:
G.TIYR

Year

( 2)

G.TIMO

Month (2)

G.TIDA

Day ( 2)

G .TIHR

Hour

(2)

6-79

the

time

DIRECTIVE DESCRIPTIONS
G.TIMI

Minute (2)

G.TISC

Second ( 2)

G.TICT

Clock Tick of Second (2)

G.TICP

Clock Ticks per Second (2)

DSW Return Codes:

rs.sue

Successful completion

IE.ADP

Part of the DPB or
task's address space

IE.SOP

DIC or DPB size is invalid

6-80

buffer is

out of the issuing

DIRECTIVE DESCRIPTIONS

GTSK$
6.3.36

Get Task Parameters

The Get Task Parameters directive instructs the system
indicated 16-word buffer with parameters relating to the

fill
an
task.

issui~g

FOR'l'RAN Call:
CALL GETTSK (buf[,ids])
buf

16-word integer array to receive the task parameters

ids

Directive status

Macro Cal 1 .:
GTSK$

buf

Address of a 16-word buffer

Buffer Format:

'-"'

word

Issuing task's name in Radix-SO

(first half)

word

Issuing task's name in Radix-SO

(second half)

word

Partition name in Radix-50

(first half)

word

Partition name iq Radix-50

(second half)

word

Undefined in RSX-llM/M-PLUS (this
RSX-llD compatibility)

word

exists

for

word

Undefined in RSX-llM/M-PLUS (this
RSX-llD compatibility)

word

exists

for

word

Run priority

word

User identification code (UIC) of issuing task (in a
multiuser protection system,
the task's default
UIC)l

word 10

Number of logical I/O units (LUNs)

word 11

Undefined
in RSX-llM/M-PLUS
RSX-llD compatibility)

(this

word exists for

word 12

Undefined
in RSX-llM/M-PLUS
RSX-llD compatibility)

(this

word

word 13

(Address of task SST vector tables)2

word 14

(Size of task SST vector table in words)2

exists for

1 See note in RQST$ description (Section 6.3.47) on contents of words
07 and 17.
2 Words 13 and 14 will contain valid data if word 14 is not zero.
word 14 is zero, the contents of word 13 are meaningless.

6-81

DIRECTIVE DESCRIPTIONS

word 15

Size (in bytes) either of task's address window 0 in
mapped systems, or of task's partition in unmapped
system (equivalent to partition size)

word 16

System on which task is running:
0 for RSX-llD

1
2
3
4
5
6

for
for
for
for
for
for

RSX-llM
RSX-llS
IAS
RSTS
VAX/VMS
RSX-llM-PLUS

Protection UIC
UIC)l

word 17

(in

multiuser

system,

the

log-in

Macro Expansion:
GTSK$
.BYTE
.WORD

DATBUF
63.,2
DATBUF

;GTSK$ DIC, DPB=2-WORDS
;ADDRESS OF 16-WORD BUFFER

Local Symbol Definitions
G.TSBA

Buffer address (2)

The following offsets are assigned
buffer:

relative

the

G.TSTN

Task name (4)

G.TSPN

Partition name (4)

G.TSPR

Priority (2)

G.TSGC

UIC group code (1)

G.TSPC

UIC member code (1)

G.TSNL

Number of logical units (2)

G.TSVA

Task's SST vector address (2)

G.TSVL

Task's SST vector length in words (2)

G.TSTS

Task size (2)

G.TSSY

System on which task is running (2)

G.TSDU

Protection UIC (2)

task

parameter

DSW Return Codes:

rs. sue

Successful completion

IE.ADP

Part of the DPB or buffer
task's address space

IE.SOP

DIC or DPB is invalid

out

the

issuing

1 See note in RQST$ description (Section 6.3.47) on contents of words
07 and 17.

6-82

DIRECTIVE DESCRIPTIONS

MAP$

._....
.

6.3.37

Map Address Window

The Map Address Window directive maps an existing window to an
attached
region.
The mapping begins at a specified offset from the
start of the region.
If the window is already mapped elsewhere,
the
Executive unmaps
it before carrying out the mapping assignment
described in the directive.
For the mapping asssignment, a task can specify
less than or equal to both:

any

length

that

within

the

•

The window size specified when the window was created

•

The length remaining between the specified offset
region and the end of the region

A task must be attached with write access to a region in order to map
to
it with write access.
To map to a region with read-only access,
the task must be attached with either read or write access.
If W.NLEN is set to O, the length defaults to either the window size
or the length remaining in the region, whichever is smaller.
(Since
_the Ex~cutive returns the actual length mapped as an output parameter,
thE~
task must clear
that parameter
in the WDB before issuing the
directive each time it wants to default the length of the map.)
The values that can be assigned to W.NOFF depend on the setting of bit
WS.648 in the window status word (W.NSTS):
•

•

If WS.64B = 1, the task can align on 32-word boundaries;
the
programmer can therefore specify any offset within the region.
NOTE
Applications dependent on 32-word or
64-byte alignment
(WS.648 = 1) may not
be compatible with
future
software
products.
Therefore, programmers should
write applications adaptable to either
alignment requirement.
The bit setting
of WS.64B could be a parameter chosen at
assembly time
(by means of a prefix
file), at task-build time (as input to
the GBLDEF option), or at run time (by
means of command input) •

FOHTRAN Call:
CALL MAP (iwdb[,ids])

6-83

DIRECTIVE DESCRIPTIONS
iwdb

An 8-word integer array containing a Window Definition
Block (see Section 3.5.2.2)

ids

Directive status

Macro Call:
MAP$

wdb

Window Definition Block address

Macro Expansion:
MAP$
.BYTE
.WORD

WDBADR
121., 2
WDBADR

;MAP$ MACRO DIC, DPB SIZE=2 WORDS
;WDB ADDRESS

Window Definition Block Parameters:
Input parameters
Array
Element

Off set

iwdb (1)
bits 0-7

W.NID

ID of the window to be mapped

i wdb ( 4)

W.NRID

ID of the region to which the window is
to be mapped, or O if the task region is
to be mapped

i wdb ( 5)

W.NOFF

Offset, in 32-word blocks,
within the
region at which mapping
is to begin.
Note that if WS.64B in the window status
word equals O, the value specified must
be a multiple of 8.

iwdb ( 6)

W.NLEN

Length, in 32-word blocks, within the
region to be mapped, or O if the length
is to default to either the size of the
window or the space remaining
in the
region
from
the
specified
offset,
whichever is smaller

iwdb(7)

W.NSTS

Bit settingsl in the window status word:
WS.WRT
1 if write access is desired
WS.64B

~
I.

0 for
256-word
(512-byte)
alignment,
or 1 for 32-word
(64-byte) alignment.

•.

Output parameters
iwdb(6)

W.NLEN

Length of the area within the
actually mapped by the window

iwdb(7)

W.NSTS

Bit settingsl in the window status word:
WS.UNM -- 1 if the
first

window

was

region

unmapped

1 FORTRAN programmers should refer to Section 3.5.2 to determine
bit values represented by the symbolic names described.

6-84

the

DIRECTIVE DESCRIPTIONS

Local Symbol Definitions:
M.APBA

Window Definition Block address (2)

DSW Return Codes:

"-"'

rs.sue

Successful completion

IE.PR!

Privilege violation

IE.NVR

Invalid region ID

IE.NVW

Invalid address window ID

IE .ALG

Task specified an invalid region offset and
length
combination
in
the
Window
Definition
Block
parameters;
or WS.64B = 0 and the value of W.NOFF is
not a multiple of 8

IE .ADP

Part of the DPB or WDB is out of the
address space

IE.SOP

DIC or DPB size is :invalid

IE .HWR

Hegion had a parity error or:; a load failure

IE. I TS

WS.RES was set and region is not resident

issuing

task's

Notes:
1.

When the Map Address Window directive is issued, the task may
be blocked until the region is loaded.

Bit WS.RES in word W.NSTS of the Window Definition Block,
when set, specifies map the region only if the region is
resident.

6-85

DIRECTIVE DESCRIPTIONS

MRKT$
6.3.38

Mark Time

The Mark Time directive instructs the system to declare a
significant
event after an indicated time interval. The interval begins when the
task issues the directive;
however, task execution continues during
the interval.
If an event flag is specified, the flag is cleared when
the directive is issued, and set when the significant event occurs.
If an AST entry point address is specified, an AST {see Section 2.3.3)
occurs at the time of the significant event. When the AST occurs, the
task's PS,
PC,
directive status, Wait For mask words, and the event
flag number specified in the directive are pushed onto
the
issuing
task's stack.
If neither an event flag number nor an AST service
entry point is specified, the significant event still occurs after the
indicated time interval.
See Notes below.
FORTRAN Calls:
CALL MARK {efn,tmg,tnt[,ids])
efn

Event fiag number

tmg

Time interval magnitude {see Note 5)

tnt

Time interval unit {see Note 5)

ids

Directive status

The ISA standard call
for
interval is also provided:

delaying

task

for

specified

time

CALL WAIT {tmg,tnt[,ids])
tmg

Time interval magnitude {see last Note below)

tnt

Time interval unit {see last Note below)

ids

Directive status

Macro Call:

MRKT$

[efn] ,tmg ,tnt [,a st]

efn

Event flag number

tmg

Time interval magnitude {see last Note below)

tnt

Time interval unit {see last Note below)

ast

AST entry point address

Macro Expansion:
MRKT$
.BYTE
• WORD
• WORD
.WORD
.WORD

52.,30.,2,MRKAST
23.,5
;MRKT$ MACRO DIC, DPB SIZE=5 WORDS
52.
;EVENT FLAG NUMBER 52 •
30.
;TIME MAGNITUDE=30 •
2
;TIME UNIT=SECONDS
MRKAST
;ADDRESS OF MARK TIME AST ROUTINE

6-86

DIRECTIVE DESCRIPTIONS
Local Symbol Definitions:

'--"'

M.KTEF

Event flag

M.KTMG

Time magnitude (2)

M.KTUN

Time unit (2)

M.KTA.E

AST entry point address (2)

( 2)

DSW Return Codes:
For CALL MARK and MRKT$:

rs.sue

Successful completion

IE.UPN

Insufficient dynamic memory

IE. ITI

Invalid time parameter

IE.IEF

Invalid event flag number

IE .ADP

Part of the DPB is out of the issuing task's
space

IE.SOP

DIC or DPB size is invalid

(>64 or <O)
address

:r·or CALL WAIT:
RSX-llM/M-PLUS provides the following positive error codes to
returned for ISA calls:
2

Insufficient dynamic storage

Specified task not installed

Invalid time parameters

Invalid event flag number

Part of DPB out of task's range

100

DIC or DPB size invalid

Notes:

Mark Time requires dynamic memory for the clock queue entry.

If an AST entry point address is specified, the AST service
routine
is entered with the task's stack in the following
state:
SP+lO - Event flag mask wordl
SP+06 - PS of task prior to AST
SP+04 - PC of task prior to AST

1
The event flag mask word preserves the Wait For conditions of a
task prior
to AST entry.
A task can, after an AST, return to a Wait
For state.
Because these flags and the other stack data are
in the
user
task,
they can be modified.
Such modification is strongly
discouraged, however, since the
task can easily fault
on obscure
conditions.

6-87

DIRECTIVE DESCRIPTIONS

SP+02 - DSW of task prior to AST
SP+OO - Event flag number or zero (if none was
specified in the Mark Time directive)
The event flag number must be removed from the task's stack
before an AST Service Exit directive (see Section 6.3.4) is
executed.
3.

If the directive is rejected, the specified event flag is not
guaranteed to be cleared or set. Consequently, if the task
indiscriminately executes a Wait For directive and the Mark
Time directive is rejected, the task may wait indefinitely.
Care should always be taken to ensure that the directive was
successfully completed.

If a task issues a Mark Time directive that specifies a
common event flag
and then exits before the indicated time
has elapsed, the event flag is not set.

The Executive returns the code IE.IT!
(or 94)
in the
Directive Status Word if the directive specifies an invalid
time parameter.
The time parameter
consists
of
two
components:
the time
interval magnitude and the time
interval unit, represented by the arguments tmg and tnt
respectively.
A legal magnitude value
( tmg)
is related to the value
assigned to the time interval unit (tnt). The unit values
are encoded as follows:
For an ISA FORTRAN call (CALL WAIT):
0

Ticks.
A tick occurs for each clock interrupt and
is dependent on the type of clock installed in the
system.
For a line frequency clock,
the tick rate
is
either 50 or 60 per second, corresponding to the
power-line frequency.
For a programmable clock, a maximum of 1000 ticks
per
second is available
(the exact rate
is
determined at system generation time).

Milliseconds.
The
specified magnitude
system clock ticks.

subroutine
converts
the
to the equivalent number of

For all other FORTRAN and macro calls:
1

Ticks.

See definition of ticks above.

For both types of FORTRAN calls and all macro calls:
2

Seconds

Minutes

Hours

6-88

DIRECTIVE DESCRIPTIONS
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.
The list applies to both FORTRAN and macro
calls.
If tnt = O, l, or 2, tmg can be any positive value
a maximum of 15 bits.

with

If tnt

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

If tnt

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

•

6-89

DIRECTIVE DESCRIPTIONS

010$
6.3.39

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) assigned to the
device.
The device drivers declare a significant event when the I/O transfer
completes.
If the directive call specifies an event flag, the
Executive clears the flag when the request is queued and sets the flag
when the significant event occurs.
The I/O status block is also cleared when the request is queued and is
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 task's Wait For mask word, PS, PC, DSW,
and the address of the I/O status block are pushed onto the task's
stack.
The description below deals solely with the Executive directive;
the
device-dependent information can be found in the RSX-llM/M-PLUS I/O
Drivers Reference Manual. See Notes below.
FORTRAN Call:
CALL QIO (fnc,lun, [efn], [pri], [isb], [prl] [,ids])
f nc

I/O function codel

lun

Logical unit number

efn

Event flag number

pri

Priority;

isb

2-word integer array to receive final I/O status

prl

6-word integer
array
containing
device-dependent
parameters to be placed in parameter words 1 through 6
of the DPB.

ids

Directive status

ignored, but must be present

Macro Call:
QIO$

fnc,lun, [efn], [pri], [isb]

[ast], [prl]

•

f nc

I/O function codel

lun

Logical unit number

efn

Event flag number

pri

Priority;

ignored, but must be present

1 I/O function code definitions are included
I/O Drivers Reference Manual.

6-90

the

RSX-llM/M-PLUS

DIRECTIVE DESCRIPTIONS
isb

Address of I/O status block

ast

Address of entry point of AST service routine

prl

Parameter list of the form <Pl, ••• P6>

Macro Expansion:
QIO$
.BYTE
.WORD
.WORD
.BYTE
.WORD
.WORD
.WORD
• WORD
• WORD
• WORD
• WORD
.WORD

IO.RVB,7,52.,,IOSTAT,IOAST,<IOBUFR,512.>
1,12.
;QIO$ MACRO DIC, DPB SIZE=l2
IO.RVB
;FUNCTION=READ VIRTUAL BLOCK
7
;LOGICAL UNIT NUMBER 7
52.,0
;EFN 52., PRIORITY IGNORED
IOSTAT
;ADDRESS OF 2-WORD I/O STATUS BLOCK
IOAST
;ADDRESS OF I/O AST ROUTINE
IOBUFR
;ADDRESS OF DATA BUFFER
512.
;BYTE COUNT=512 •
0
;ADDITIONAL PARAMETERS •••
0
; ••• NOT USED IN •••
0
; ••• THIS PARTICULAR •••
0
; ••• INVOCATION OF QUEUE I/O

Local Symbol Definitions:
Q. I OFN

I/O function code (2)

Q. I OLU

Logical unit number (2)

Q.IOEF

Event flag number (1)

Q. I OPR

Priority {l)

Q. I OSB

Address of I/O status block (2)

Q. I OAE

Address of I/O done AST entry point (2)

Q .. IOPL

Parameter list {6 words)

{12)

DSW Return Codes:

•

rs.sue

Successful completion

IE.UPN

Insufficient dynamic memory

IE. ULN

Unassigned LUN

IE.HWR

Device driver not loaded

IE.PR!

Task other than despooler attempted a
block operation

IE. I LU

Invalid LUN

IE. I EF

Invalid event flag number {>64 or <O)

IE.ADP

Part of the DPB or I/O status block
issuing task's address space

IE.SOP

DIC or DPB size is invalid

6-91

write

out

logical

the

DIRECTIVE DESCRIPTIONS
Notes:
1.

'
If the directive call specifies an AST entry point address,
the task enters the AST service routine with its stack in the
following state:
SP+lO
SP+06
SP+04
SP+02
SP+OO

Event flag mask word
PS of task prior to AST
PC of task prior to AST
DSW of task prior to AST
Address of I/O status block, or zero, if none
was specified in the QIO directive.

block,
which
is
a
The address of the I/O
status
trap-dependent parameter, must be removed from the task's
stack before an AST Service Exit directive
(see Section
6.3.4) is executed.
2.

If the directive is rejected, the specified event flag is not
guaranteed to be cleared or set. Consequently, if the task
indiscriminately executes a Wait For directive and the QIO
directive
is ~ejected, the task may wait indefinitely.
Care
should always be taken to ensure that the directive was
successfully completed.

Tasks cannot be checkpointed with
reasons:

QIO

outstanding

for

two

If the QIO directive results in a data transfer, the data
transfers directly to or from the user-specified buffer.

If an I/O status block address is specified,
the
directive status is returned directly to the I/O status
block.

The Executive waits until
a task has no outstanding I/O
before initiating checkpointing in all cases except the one
described below.
In systems that support the checkpointing of tasks during
terminal
input, the terminal driver checks for the following
conditions when the driver dequeues an input request for a
task:
•

That the task is checkpointable

•

That checkpointing is enabled

•

That the task is not executing an AST routine

If the three conditions exist,
the Executive
immediately
stops the task's execution. Any competing task waiting to be
loaded into the partition can checkpoint the stopped task,
regardless of priority.
If the stopped task is checkpointed,
the Executive does not bring it back into memory until
its
terminal input has completed. While the task is stopped, the
terminal driver buffers the task's terminal input.

A privileged task that is linked to a common (read-only)
can issue QIO write requests to that area.

6-92

area

DIRECTIVE DESCRIPTIONS

QIOW$
6.3o40

Queue I/O

R~quest

And Wait

The Queue I/O Request And Wait directive is identical
to Queue I/O
Request in all but one aspect.
If the Wait variation of the directive
specifies an event flag, the Executive automatically effects a Wait
For Single Event Flag directive.
If an event flag is not specified,
however, the Executive treats the directive as if it were a
simple
Queue I/O Request.
The following description lists the FORTRAN and macro calls with the
associated parameters,
as well as the macro expansion.
Consult the
description of Queue I/O Request for a definition of the parameters,
the local
symbol definitions, the DSW return codes, and explanatory
notc~s.

FOR'rRAN Call:
CALL WT QI 0

( fn c , l u n , [ e fn ] , [ p ri ] , [ i s b ] , [ pr 1 ] [ , i d s ] )

f nc

I/O function codel

lun

Logical unit number

efn

Event flag number

pri

Priority;

isb

2-word integer array to receive final I/O status

prl

6-word
integer
array
containing
device-dependent
parameters to be placed in parameter words 1 through 6
of the DPB

ids

Directive status

ignored, but must be present

Macro Call:
QIOW$

fnc,lun,efn, [pri], [isb], [ast] [,prl]

f nc

I/O function codel

lun

Logical unit number

efn

Event flag number

pri

Priority;

isb

Address of I/O status block

ast

Address of entry point of AST service routine

prl

Parameter list of the form <Pl, ••• P6>

ignored, but must be present

1
I/O function codes are defined in the
Reference Manual.

6-93

RSX-llM/M-PLUS

I/O

Drivers

DIRECTIVE DESCRIPTIONS
Macro Expansion:
QIOW$
• BYTE
.WORD
.WORD
.BYTE
.WORD
.WORD
.WORD
• WORD
• WORD
• WORD
• WORD
.WORD

IO.RVB,7,52.,,IOSTAT,IOAST,<IOBUFR,512.>
3,12.
;QIO$ MACRO DIC, DPB SIZE=l2 •
IO.RVB
;FUNCTION=READ VIRTUAL BLOCK
7
;LOGICAL UNIT NUMBER 7
52.,0
;EFN 52., PRIORITY IGNORED
IOSTAT
;ADDRESS OF 2-WORD I/O STATUS BLOCK
IOAST
;ADDRESS OF I/O AST ROUTINE
IOBUFR
;ADDRESS OF DATA BUFFER
512.
;BYTE COUNT=512 •
0
;ADDITIONAL PARAMETERS •••
0
; ••• NOT USED IN •••
0
; ••• THIS PARTICULAR •••
0
; ••• INVOCATION OF QUEUE I/O

6-94

DIRECTIVE DESCRIPTIONS

RCST$
6~3.41

Receive Data Or Stop

The Receive Data Or Stop directive attempts to dequeue a Send Data
packet from the specified task (or any task).
If there is no such
packet to be dequeued, the issuing task
is stopped.
In this case
another
task,
the sender
task,
is expected to
issue an Unstop
directive after
sending data.
On successful
return from
this
directive,
a directive status of rs.sue indicates that a packet has
been received.
A status of IS.SET indicates that the task was stopped
and has been unstopped.
The directive must then be reissued to
retrieve the packet.
FOR'l~RAN

Cal 1:

CALL HCST ( [ rtname] , ibuf, [ids])
rtname

Name of task from which data is to be received

ibu:E

Address of 15-word buffer to receive the sender task
name and data

ids

Integer to receive the directive status word

Macro Call:
RCST$

[tname] ,buf

tname

Name of task from which data is to be received -- If
not specified, data may be received from any task

buf

Address of 15-word buffer to receive the sender task
name and data

Macro Expansion:
RCST$
.BYTE
.RAD50
.WORD

ALPHA,TSKBUF
139. , 4
ALPHA
TSKBUF

;RCST$ MACRO DIC, DPB SIZE=4 WORDS
;DATA SENDER TASK NAME
;BUFFEH ADDRESS

Local Symbol Definitions:
R.CSTN

Task name

(4)

R.CSBF

Buffer address (2)

DSW Return Codes:
rs.sue

Successful completion

IS.SET

No data was received and task was stopped (note
that
the task must be unstopped before it can see this
status)

IE.AST

The issuing task is at AST state

IE.ADP

Part of the DPB is out of the issuing task's
space

IE. SDP

DIC or DPB size is invalid

6-95

address

DIRECTIVE DESCRIPTIONS

6-96

DIRECTIVE DESCRIPTIONS

RCVD$
6.3.42

Receive Data

The Receive Data directive instructs the system to dequeue a 13-word
data block for
the
issuing task;
the data block has been queued
{FIFO) for the task via a Send Data Directive •
A 2-word sender task name (in Radix-50
form)
and the 13-word data
block are returned in an indicated 15-word buffer, with the task name
in the first two words.
In a system that supports multiuser protection,
a
task can be
installed as a slave by the keyword /SLV=YES (see the RSX-llM/M-PLUS
MCR Operat:lons Manual). When a slave task issues the Receive Data
di r E~c ti v e,
it assumes the UIC and TI:
terminal of the task that sent
the data.
FOR~~RAN

Cal 1 ~

CALL RECEIV ( [tsk] ,buf [,,ids])
tsk

Sender task name

buf

15-word integer array for received data

ids

Directive status

Macro Call:
RCVD$

[tsk] ,buf

tsk

Sender task name

buf

Address of 15-word buffer

Macro Expansion:
RCVD$
.BYTE
.RAD50
.WORD

ALPHA,DATBUF
75 m f 4

/ALPHA/
DATBUF

;TASK NAME AND BUFFER ADDRESS
;RCVD$ MACRO DIC, DPB SIZE=4 WORDS
;SENDER TASK NAME
;ADDRESS OF 15.-WORD BUFFER

Local Symbol Definitions:
R.VDTN

Sender task name (4)

R.VDBA

Buffer address (2)

DSW Return Codes:

rs.sue

Successful completion

IE. I 'I'S

No data currently queued

IE.ADP

Part of the DPB or buffer
task's address space

IE.SDP

DIC or DPB size is invalid

6-97

out

the

issuing

DIRECTIVE DESCRIPTIONS

•

6-98

DIRECTIVE DESCRIPTIONS

RCVX$
6.3.43

Receive Data Or Exit

The Receive Data Or Exit directive instructs the system to dequeue a
13-word data block
for
the
issuing task;
the data block has been
queued (FIFO) for the task via a Send Data directive.
A 2-word sender task name (in Radix-50
form)
and
the 13-word data
block are returned in an indicated 15-word buffer, with the task name
in the first two words.
If no data has been sent, a task exit occurs.
To prevent the possible
loss of Send packets, the user should not rely on I/O rundown to take
care of any outstanding I/O or open files;
the
task should assume
this responsibility.
In a
system that supports multiuser protection,
a
task can be
installed as a slave by the keyword /SLV=YES (see the RSX-llM/M-PLUS
MCR Operations Manual).
When a slave task issues the Receive Data Or
Exit directive, it assumes the UIC and TI:
terminal of the task that
sent the data.
See Notes below.
FORTRAN Ca 11:
CALL RE:COEX ([tsk],buf[,,ids])
tsk

Sender task name

buf

15-word integer array for received data

ids

Directive status

Macro Call:
RCVX~i

[tsk] ,buf

tsk

Sender task name

buf

Address of 15-word buffer

Macro Expansion:
RCVX$
.BYTE
. RAD~) 0
.WORD

ALPHA,DATBUF
77 • I 4

/ALPHA/
DATBUF

;TASK NAME AND BUFFER ADDRESS
;RCVX$ MACRO DIC, DPB SIZE=4 WORDS
;SENDER TASK NAME
;ADDRESS OF 15.-WORD BUFFER

Local Symbol Definitions:
R. VX~rN

R.VXBA

Sender task name (4)
Buffer address (2)

DSW Return Codes:

rs.sue

Successful completion

IE.ADP

Part of the DPB or buffer
task's address space

IE.SDP

DIC or DPB size is invalid

6-99

out

the

issuing

DIRECTIVE DESCRIPTIONS
Notes:
1.

A FORTRAN program that issues the RECOEX call must first
close all files by issuing CLOSE calls.
See the IAS/RSX-11
FORTRAN IV or
the FORTRAN IV-PLUS
User's
Guide
for
instructions concerning how to ensure that such files are
closed properly if the task exits.
To avoid the time overhead
involved in the closing and
reopening of files,
the task should first issue the RECEIV
call.
If the directive status indicates that no data were
received,
then the task can close all files and issue the
call to RECOEX.

If no data have been sent, that is, if no Send Data directive
has been issued, the task exits.
Send packets may be lost if
a task exits with outstanding I/O or open files
(see third
paragraph of this section).

The Receive Data Or Exit directive is useful
in avoiding a
possible race condition that can occur between two tasks
communicating via the Send and Receive directives.
The race
condition occurs when one task executes a Receive directive
and finds its receive queue empty;
but before the task can
exit, the other task sends it a message.
The message is lost
because the Executive flushes the receiver task's receive
queue when it exits.
This condition can be avoided by the
receiving task's executing a Receive Data Or Exit directive.
If the receive queue is found to be empty, a task exit occurs
before the other task can send any data;
thus,
no loss of
data can occur.

On Exit, the Executive frees task resources.
the Executive:

particular,

•

Detaches all attached devices

•

Flushes the AST queue

•

Flushes the receive and receive-by-reference queues

•

Flushes the clock queue
requests for the task

outstanding

Mark

Time

•

Closes all open files (files open for write
locked)

access

are

•

Detaches all attached regions except in the
fixed task, where no detaching occurs

case

•

Runs down the task's I/O

•

Frees the task's memory if
fixed

for

the

•

exiting

task

was

not

Jh:~sx~~Irvi~gt.us ·. . syst.ems·.,. rnt1r~$ . . . . • ~dCJ. ;\y.~r
un.its the task .has created for dea:1),oc·a~'f
•
5.

Disconnects all connected tasks

If the task
event.

exits,

the

Executive

6-100

declares

significant

DIRECTIVE DESCRIPTIONS

6-101

DIRECTIVE DESCRIPTIONS

ROAF$
6.3.44

Read All Event Flags

The Read All Event Flags directive instructs the system to read all 64
event flags for the issuing task and record their polarity in a 64-bit
(4-word) buffer.
NOTE
Group-globl event flags
(event flags
65 - 96)
are
not returned by this
directive.
FORTRAN Call:
Only one event flag can be read by a FORTRAN task.

The call is:

CALL READEF (efn,ids)
efn

Event flag number

ids

Directive status

The Executive returns the status codes IS.SET
(+02)
and
(00) for FORTRAN calls to report event flag polarity.

IS.CLR

Macro Call:
RDAF$

buf

Buffer Format:
word

Task Local Flags 1-16

word

Task Local Flags 17-32

word

Task Common Flags 3 3-·48

word

Task Common Flags 4 9-·64

Macro Expansion:
RDAF$
.BYTE
.WORD

FLGBUF
39. '2
FLGBUF

;RDAF$ MACRO DIC, DPB SIZE=2 WORDS
;ADDRESS OF 4-WORD BUFFER

Local Symbol Definitions:
R.DABA

Buffer address (2)

DSW Return Codes:

rs.sue

Successful completion

IE.ADP

Part of the DPB or buffer
task's address space

IE.SDP

DIC or DPB size is invalid
'

6-102

out

the

issuing

DIRECTIVE DESCRIPTIONS

RDXF$
6.3.45

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 task
and record their polarity in a 64-bit (6-word) buffer.
FOR'l~RAN

Call:

Only one event flag can be read by a FORTRAN task.

The call is:

CALL READEF (efn[,ids])
efn

Event flag number

ids

Directive status

The Executive returns the status codes IS.SET
(+02)
and
(00) for FORTRAN calls to report event flag polarity.

IS.CLR

Macro Call:
RDXF$

buf

Buffer· Format:
word

Task Local Flags 1-16

word

Task Local Flags 17-32

word

Task Common Flags 33-48

word

Task Common Flags 49-64

word

Task Group-Global F'lags 65-80

word

Task Group-Global Flags 81-96

Macro Expansion:
RDXF$
.BYTE
.WORD

FLGBUF
39., 3
FLGBUF

;RDXF$ MACRO DIC, DPB SIZE=3 WORDS
;ADDRESS OF 6-WORD BUFFER

Local Symbol Definitions:
R.DABA

Buffer address (2)

DSW Return Codes:

rs.sue

Successful completion

IS.CLR

Group-global event flags do not exist.,
of the buffer contain O

IE.ADP

Part of the DPB or buffer
task's address space

IE. SDP

DIC or DPB size is invalid

6-103

out

Words 4 and 5
the

issuing

DIRECTIVE DESCRIPTIONS

~.
:

6-104

DIRECTIVE DESCRIPTIONS

ROST$
6.3.47

Request Task

The Request Task directive instructs the system to activate a
task.
The task is activated and subsequently runs contingent upon priority
and memory availability.
Request is the basic mechanism used by
running tasks to initiate other installed (dormant) tasks.
Request is
a frequently used subset of the Run directive.
See Notes below.
FORTRAN Call:
CALL REQUES (tsk, [opt] [,ids])
tsk

Task name

opt

4-word integer array

ids

opt(l)

partition name
first
must be present

half;

ignored,

but

opt(2)

partition name second
must be present

half;

ignored,

but

opt ( 3)

priority;

opt(4)

user Identification Code

ignored, but must be present

Directive status

Macro Call:
RQST$

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

tsk

Task name

prt

Partition name;

pri

Priority; ignored, but must be present

ugc

UIC group code

umc

UIC member code

ignored, but must be present

Macro Expansion:
RQS'l $
• BY'l'E
.RAD50
.WORD
.WORD
.BYTE
1

ALPHA,,,20,10
11., 7
/ALPHA/
0,0
0

10,20

;RQST$ MACRO DIC, DPB SIZE=7 WORDS
;TASK "ALPHA"
;PARTITION IGNORED
;PRIORITY IGNORED
;UIC UNDER WHICH TO RUN TASK

Local Symbol Definitions:
R.QSTN

Task name (4)

R.QSPN

Partition name (4)

R.QSPR

Priority (2)

6-105

DIRECTIVE DESCRIPTIONS

R.QSGC

UIC group (1)

R.QSPC

UIC member

(1)

DSW Return Codes:
IS. sue

Successful completion

IE.UPN

Insufficient dynamic memory

IE.INS

Task is not installed

IE.ACT

Task is already active

IE .ADP

Part of the DPB is out of the issuing task's
space

IE. SDP

DIC or DPB size is invalid

address

Notes:
1.

The requested task must be installed in the system.

If the partition in which a
requested task
is to
run
is
already occupied, the Executive places the task in a queue of
tasks waiting for that partition. The requested
task then
runs,
depending on priority, and resource availability, when
the partition is free.
Another
possibility
is
that
checkpointing may occur.
If the current occupant(s) of the
partition is checkpointable, has checkpointing enabled,
and
is of lower priority than the requested task, it is written
to disk when its current outstanding I/O completes;
the
requested task is then read into the partition.

Successful completion means that the task has been
active, not that the task is actually running.

The requested task acquires the same TI:
as that of the requesting task.

The requested task always runs at the priority
its task header.

A task
that executes in a system-controlled
partition
requires dynamic memory 'for the partition control block used
to describe its memory requirements.

In a system that does not support multiuser protection,
a
task can be requested under any UIC, regardless of the UIC of
the requesting task.
If no UIC is specified in the
request,
the system uses the UIC from the task's header, which was
specified at task-build time.

In a system that supports multiuser protection,
each active
task has two UICs -- a
protection UIC and a default UIC.
These are both returned when a
task
issues a Get Task
Parameters directive
(GTSK$).
The UICs are used in the
following ways:
a.

declared

terminal assignment
specified

The protection UIC determines the task's access rights
for opening files and attaching to regions.
When a task
task's
attempts to open a file, the system compares the
protection
UIC against the protection mask of the
specified UFD;
the comparison determines whether
the

6-106

DIRECTIVE DESCRIPTIONS
task is to be
world access.
b.

considered for system, owner, group, or

The default UIC is used by the File Control Subroutines
(FCS)
to determine the default UFD when a file-open
operation does not specify a UIC.
(The default UIC has
no significance when a task attaches to a region.)

In a multiuser protection system, each terminal
also has a
protection
UIC and a default UIC.
If a
terminal
is
nonprivileged, the protection UIC is the log-on UIC, and the
default UIC is the UIC specified in the last SET /UIC command
issued.
If no SET /UIC command has been issued, the default
UIC
is equal
to
the log-on UIC.
If the
terminal
is
privileged, both the protection and
the default UICs are
equal
either to
the UIC specified
in the last SET /UIC
command or to the log-on UIC if a SET /UIC command has not
been issued.
The system establishes a
task's UICs when the
task
is
activated.
In general, when the MCR Dispatcher or the MCR
Run command activates a task, the task assumes the protection
and default UICs of the issuing terminal.
However, if the
user specifies the /UIC keyword to the MCR Install
or Run
command,
the specified UIC becomes the default UIC for the
activated task;
and if the issuing terminal
is privileged,
the specified UIC becomes the activated task's protection UIC
as well.
The system establishes UICs in the same manner when one task
issues a Request directive to activate another task.
The
protection and default UICs of the
issuing task generally
become
the
corresponding UICs of the
requested
task.
However,, if a nonprivileged task specifies a UIC in a Request
directive, the specified UIC becomes only the default UIC for
the requested task.
If a privileged task specifies a UIC
in
a
Request directive,
the specified UIC becomes both the
protection and default UIC for the requested task.

6-107

DIRECTIVE DESCRIPTIONS

RREF$
6.3.48

Receive By Reference

The Receive By Reference directive requests the Executive to dequeue
the ne~t packet in the receive-by-reference queue of the issuing
(receiver) task.
Optionally, the task will exit if there are no
packets in the queue.
The directive may also specify that the
Executive proceed to map the region referred to.
If successful, the directive declares a significant event.
Each reference in the task's receive-by-reference queue represents a
separate attachment to a region.
If a task has multiple references to
a given region, it is attached to that region the corresponding number
of times.
Because region attachment requires system dynamic memory,
the receiver task should detach from any region that it was already
attached to
in order to prevent depletion of the memory pool. That
is, the task needs to be attached to a given region only once.
If the Executive does not find a packet in the queue, and the task has
set WS.RCX in the window status word (W.NSTS), the task exits.
If
WS.RCX is not set, the Executive returns the DSW code IE.ITS.
If the Executive finds a packet, it writes the information provided to
the
corresponding words
in the Window Definition Block.
This
information provides sufficient information to map the reference,
according
to the sender task's specifications, with a previously
created address window.
If the address of a 10-word receive buffer has been specified
(W.NSRB
in the Window Definition Block), then the sender task name and the
eight additional words passed by the sender task (if any)
are placed
in the specified buffer.
If the sender task did not pass on any
additional information, the Executive writes in the sender task name
and eight words of zero.
If the WS.MAP bit in the window status word has been set to 1,
the
Executive transfers control to the Map Address Window directive (see
Section 6.3.37) to attempt to map the reference.
When a task that has unreceived packets in its receive-by-reference
queue exits or is removed, the Executive removes the packets from the
queue and deallocates them.
Any related flags are not set.
FORTRAN Call:
CALL RREF ( iwdb, [ i srb] [,ids] )
iwdb

An 8-word integer array containing a Window Definition
Block (see Section 3.5.2.2)

isrb

A 10-word integer array to be used as the receive
the
buffer.
If the call omits this parameter,
contents of iwdb(8) are unchanged.

ids

Directive status

Macro Call:
RREF$
wdb

wdb
Window Definition Block address
6-108

"""'·

DIRECTIVE DESCRIPTIONS
Macro Expansion:
RREF$
.BYTE
.WORD

WDBADR
81. '2
WDBADR

;RREF$ MACRO DIC, DPB SIZE=2 WORDS
;WDB ADDRESS

Window Definition Block Parameters:
Input parameters
Array
Element

Off set
---

i wdb ( l)
bits 0·-7 W.NID
iwdb(7)

iwdb(8)

W.NSTS

W.NSRB

ID of an existing window if region is to be
mapped
Bit settingsl in the window status word:
WS.MAP

l if received reference
be mapped

WS.RCX

1 if task exit desired when no
packet is found in the queue

Optional address of a 10-word buffer,
to
contain the sender task name and additional
information

Output parameters

"-"''

(pofnter

attachment

iwbd(4)

W.NRID

Region
ID
description)

iwdb ( 5)

W.NOFF

Offset word specified by sender task

iwdb(6)

W.NLEN

Length word specified by sender task

iwdb ( 7)

W.NSTS

Bit settingsl in the window status word:
WS.RED

1 i f attached with read access

WS.WRT

1 i f attached with write access

WS.EXT

if attached
1
access

with

extend

WS.DEL

if attached
1
access

with

delete

WS.RRF

1 if receive was successful

The Executive clears the remaining bits.
Local Symbol Definitions:
R.REBA

Window definition block address (2)

1 FORTRAN programmers should refer to Section 3.5.2 to determine
bit values represented by the symbolic names described.

6-109

the

DIRECTIVE DESCRIPTIONS

DSW Return Codes:

Is.sue

Successful completion

IS.HWR

Region has incurred a parity error

IE.ITS

No packet found in the receive-by-reference queue

IE.ADP

Address check of the DPB, WDB, or the receive buffer
(W.NSRB) failed

IE.SOP

DIC or DPB size is invalid

~\I

6-110

DIRECTIVE DESCRIPTIONS

RSUM$
6.3.49

Resume Task

The Resume Task directive instructs the system to resume the execution
of a task that has issued a Suspend directive.
FORTHAN Call:
CALL RESUME

(tsk[,ids])

tsk

Task name

ids

Directive status

Macro Call:
RSUM$
tsk

tsk
Task name

Macro Expansion:
RSUM$
.BYTE
.RADSO

ALPHA
4 7. '3
/ALPHA/

;RSUM$ MACRO DIC, DPB SIZE=3 WORDS
; TASK 11 l\LPHA II

Local Symbol Definitions:
R.SUTN

Task name (4)

DSW Return Codes:

rs.sue

Successful completion

IE.INS

Task is not installed

IE.ACT

Task is not active

IE. ITS

Task is not suspended

IE.ADP

Part of the DPB is out of the issuing task's address
space

IE.SOP

DIC or DPB size is invalid

6-111

DIRECTIVE DESCRIPTIONS

RUN$
-~\

6.3.50

Run Task

The Run Task directive causes a task to be requested at a specified
future
time,
and optionally to be requested periodically.
The
schedule time is specified in terms of delta time from
issuance.
If
the smg,
rmg,
and
rnt parameters are omitted, Run is the same as
Request except that:
1.

Run causes the task to become active one clock tick after the
directive is issued

The system always sets the
task, to CO:

TI:

device

for

the

requested

See Notes below.
FORTRAN Call:
CALL RUN (tsk, [opt], [smg] ,snt, [rmg], [rnt] [,ids])
tsk

Task name

opt

4-word integer array
opt(l)

partition name first
must be present

half;

opt ( 2)

partition name
second
but must be present

opt(3)

priority;

opt(4)

User Identification Code

ignored,

half;

Schedule delta magnitude

snt

Schedule delta unit (either 1, 2, 3, or 4)

rmg

Reschedule interval magnitud~

rnt

Reschedule interval unit

ids

Directive status

The ISA standard call for initiating a task is also provided:
CALL START(tsk,smg,snt[,ids])
tsk

Task name

smg

Schedule delta magnitude

snt

Schedule delta unit (either O, 1, 2, 3, or 4)

ids

Directive status

Macro Call:
RUN$

ignored,

ignored, but must be present

smg

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

6-112

but

DIRECTIVE DESCRIPTIONS
tsk

Task name

prt

Partition name;

pri

Priority;

ugc

UIC group code

umc

UIC member code

smg

Schedule delta magnitude

snt

Schedule delta unit (either 1, 2, 3, or 4)

rmg

Reschedule interval magnitude

rnt

Reschedule interval unit

ignored, but must be present

Macro Expansion:
RUN$
BYTE
.RAD50
.WORD
.WORD
.BYTE
.WORD
.WORD
• WORD
.WORD

ALPHA,,,20,10,20.,3,l0.,3
17.,11.
;RUN$ MACRO DIC, DPB SIZE=ll. WORDS
/ALPHA/
;TASK "ALPHA"
0,0
;PARTITION IGNORED
0
;PRIORITY IGNORED
10,20
;UIC TO RUN TASK UNDER
20.
;SCHEDULE MAGNITUDE=20
3
;SCH. DELTA TIME UNIT=MINUTE (=3)
10.
;RESCH. INTERVAL MAGNITUDE=lO •
3
;RESCH. INTERVAL UNIT=MINUTE (=3)

Local Symbol Definitions:
R.UNTN

Task name ( 4)

R.UNPN

Partition name ( 4)

R.UNPH

Priority ( 2)

R.UNGC

UIC group code ( l)

R.UNPC

UIC member code ( l )·

R.UNSM

Schedule magnitude (2)

R.UNSU

Schedule unit ( 2)

R.UNRM

Reschedule magnitude ( 2)

R.UNRU

Reschedule unit ( 2)

DSW Return Codes:
For CALL RUN and 'RUN$:

rs.sue

Successful completion

IE. UPN

Insufficient dynamic memory

IE .ACT

Multiuser task name specified

IE.INS

Task is not installed

IE.PR!

Nonprivileged task specified a UIC other than its own

6-113

DIRECTIVE DESCRIPTIONS

IE.ITI

Invalid time parameter

IE.ADP

Part of the DPB is out of the issuing task's address
space

IE. SDP

DIC or DPB size is invalid

For CALL STAR'l':
RSX-llM/M-PLUS provides the following positive error codes to
returned for ISA calls:
2

Insufficient dynamic storage

Specified task not installed

Invalid time parameter

Invalid event flag number

Part of DPB out of task's address space

100

DIC or DPB size invalid

Notes:
1.

In a multiuser protection system, a nonprivileged task cannot
specify a UIC that is not equal to its own protection UIC.
(See the Note 8, Section 6.3.47,
for
a definition of the
protection UIC.) A privileged task can specify any UIC.

In a system that does not support multiuser protection,
a
task may be run under any UIC, regardless of the UIC of the
requesting task.
If no UIC is specified in the request,
the
Executive uses the default UIC from the requested task's
header.
The priority is always that specified
in the
requested task's Task Control Block.

The target task must be installed in the system.

If there is not enough room
in the partition in which a
requested
task is to run, the Executive places the task in a
queue of tasks waiting for
that partition.
The requested
task will
then run,
depending on priority and resource
availability, when
the
partition
is
free.
Another
possibility is that checkpointing will occur.
If the current
occupant(s)
of the
partition
is
checkpointable,
has
checkpointing
enabled,
is of lower
priority than the
requested task, or is stopped for terminal input, it will
be
written to disk when its current outstanding I/O completes.
The requested task will then be read into the partition.

Successful completion means the task has been made
it does not mean that the task is actually running.

Time Intervals

active;

The Executive returns the code IE.IT!
in the DSW if the
directive specifies an
invalid
time
A time
parameter.
parameter consists of two components:
the
time
interval
magnitude and the time interval unit.

6-114

DIRECTIVE DESCRIPTIONS
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:
For an ISA FORTRAN call
0

(CALL START):

Ticks -- A tick occurs for
each clock
interrupt
and is dependent on the type of clock installed in
the system.
For a line frequency clock,
the
tick
rate
is
either
50 or 60 per second, corresponding to the
power-line frequency.
For a programmable clock, a maximum of 1000 ticks
per
second
is available
(the exact rate
is
determined during system generation).

Milliseconds
The subroutine
converts
the
specified magnitude to the equivalent number of
system clock ticks.

For all other FORTRAN and all macro calls:

·~·

Ticks -- See definition of ticks above.

For both types of FORTRAN calls and all macro calls:
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.
The list applies to both FORTRAN and macro calls.
If unit= O, 1, or 2, the magnitude can be any
value with a maximum of 15 bits.

positive

If unit = 3, the magnitude can have a maximum

value

1440 (10).

If unit
24(10).

•

4, the magnitude can have a maximum

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

The reschedule interval is the difference in time from
task
initiation to the time the task is to be reinitiated.
If
this time interval elapses and the task is still active,
no
reinitiation
request
will
be
issued.
However,
a new
reschedule interval will
be started.
The Executive will
continually try to start a task, wait for the specified time
interval, and then restart the task.
This process continues
until
a CSRQ$
(Cancel Time Based
Initiation Requests)
directive or an MCR Cancel command is issued.

6-115

DIRECTIVE DESCRIPTIONS
9.

Run requires dynamic memory for the clock queue entry used to
start the
task after the specified delta time. · If the task
is to run in a system-controlled partition,
further dynamic
memory is required
for
the task's dynamically allocated
partition control block (PCB).

10.

If optional rescheduling is not desired, then the macro
should omit the arguments rmg and rnt.

call

~\.I

•

6-116

DIRECTIVE DESCRIPTIONS

6-117

DIRECTIVE DESCRIPTIONS

,.,

6-118

DIRECTIVE DESCRIPTIONS

SDAT$
6.3~52

Send Data

The Send Data directive instructs
event and to queue
(FIFO)
a
receive
When a local event flag
fla~J
is set for the sending
declared.
FOR~rRAN

the system to declare a significant
13-word block of data for a task to
is specified,
the indicated event
task; a significant event is always

Call::

CALL SEND (tsk,buf, [efn] [,ids])
tsk

Task name

buf

13-word integer array of data to be sent

efn

Event flag number

ids

Directive status

Macro Call:
SDAT$

''-"''

tsk,buf [,efn]

tsk

Task name

buf

Address of 13-word data buffer

ef n

Event flag number

Macro Expansion:
SDAT$
.BYTE
.RAD50
.WORD
• WORD

ALPHA,DATBUF,52.
71.,5
;SDAT$ MACRO DIC, DPB SIZE=5 WORDS
/ALPHA/
;RECEIVER TASK NAME
DATBUF
;ADDRESS OF 13.-WORD BUFFER
52.
;EVENT FLAG NUMBER 52 •

Local Symbol Definitions:
S.DATN

Task name

( 4)

S.DABA

Buffer address

S.DAE.F

Event flag number

(2)
(2)

DSW Return Codes:

rs .sue

Successful completion

IE.INS

Receiver task is not installed

IE.UPN

Isuff icient dynamic memory

IE. IEF

Invalid event flag number

IE .ADP

Part of the DPB or data block is out of the issuing
task's address space

IE.SDP

DIC or DPB size is invalid

6-119

(>64 or <O)

DIRECTIVE DESCRIPTIONS

Notes:
1.

Send Data requires dynamic memory.

If the directive specifies a local event flag,
the flag
is
local
to the sender (issuing) task.
RSX-llM does not allow
one task to set or clear a flag
that
is local to another
task.
In RSX-HM•PLUS systems that suppqrt:• <~a~l.~:~ix::~2/Y?"
receive . dfredtfves
(secondary . pool sµpf>P.r:~· -sYsG·

,.·

the ~end •. Pata.directive is treated asa .. <13 •.,::···y·~:/P
Send Data ditectiv·e (see Section 6.3.7:5J~.

·~,

6-120

DIRECTIVE DESCRIPTIONS

6-121

DIRECTIVE DESCRIPTIONS

'
~\

6-122

DIRECTIVE DESCRIPTIONS

SETF$
6.3.54

Set Event Flag

The Set Event Flag directive instructs the system to set an
event flag, reporting the flag's polarity before setting.

indicated

FORTH.AN Call:
CALL SETEF (efn[,ids])
efn

Event flag number

ids

Directive status

Mac re:> Cal 1:
SETF$
efn

efn
Event flag number

Macn:> Expansion:
SETF$
.BYTE
• WORD

52.

33.,2
52.

;SETF$ MACRO DIC, DPB SIZE=2 WORDS
;EVENT FLAG NUMBER 52 •

Local Symbol Definitions:
S.ETEF

Event flag number

(2)

DSW Return Codes:
IS.CLR

Flag was clear

IS. SET

Flag was already set

IE. I EF

Invalid event flag number

IE.ADP

Part of the DPB is out of the issuing task's
space

IE.SOP

DIC or DPB size is invalid

(>64 or <1)
address

Note:
Set Event Flag does not declare a significant event;
sets the specified flag.

6-123

merely

DIRECTIVE DESCRIPTIONS

SFPA$
6.3.55

Specify Floating Point Processor Exception AST

The Specify Floating Point Processor Exception AST directive instructs
the system to record one of the two following cases:
•

Floating Point Processor exception ASTs for the issuing task
are desired, and the Executive is to transfer control to a
specified address when such an AST occurs for the task

•

Floating Point Processor exception ASTs for the
are no longer desired.

issuing

task

When as AST service routine entry point address is specified,
future
Floating Point Processor exception ASTs will occur for the issuing
task, and control will be 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 will
not occur until
the task issues a directive that specifies an AST
entry point.
See Notes below.
FORTRAN Call:
Not supported
Macro Call:
SFPA$
ast

[ast]
AST service routine entry point address

Macro Expansion:
SFPA$
.BYTE
.WORD

FLTAST
111. '2
FLTAST

;SFPA$ MACRO DIC, DPB SIZE=2 WORDS
;ADDRESS OF FLOATING POINT AST

Local Symbol Definitions:
S.FPAE

AST entry address (2)

DSW Return Codes:

rs.sue

Successful completion

IE.UPN

Insufficient dynamic memory

IE. ITS

AST entry point address is already unspecified or
task was built without floating-point support (FP
switch not specified in Task Builder
.TSK file
specification)

IE.AST

Directive was issued from an AST service routine,
ASTs are disabled

IE.ADP

Part of the DPB is out of the issuing task's
space

IE.SOP

DIC or DPB size is invalid

6-124

address

DIRECTIVE DESCRIPTIONS
Nob~s:

Specify Floating
dyni:tmic memory.

The Executive queues Floating Point Processor exception ASTs
when a Floating Point Processor exception trap occurs for the
task. No future ASTs of this kind will be queued
for
the
task until the first one queued has actually been effected.

The Floating Point Processor exception AST service routine is
entered with the task stack in the following state:
SP+l2 SP+lO SP+06 SP+04 SP+02' SP+OO -

Point

Processor

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 task must remove the floating exception code and address
from the task's stack before an AST Service Exit (see Section
6.3.4) directive is executed.
4.

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

This directive applies only to the Floating Point Processor.

6-125

service

routine

DIRECTIVE DESCRIPTIONS

6-126

DIRECTIVE DESCRIPTIONS

6-127

DIRECTIVE DESCRIPTIONS

SPND$S
6.3.57

Suspend ($S form recommended)

The Suspend directive instructs the system to suspend the execution of
the
issuing task.
A task can suspend only itself, not another task.
The task can be restarted either by a Resume directive, or by an MCR
Resume command.
FORTRAN call:
[(ids)]

CALL SUSPND
ids

Directive status

Macro Call:
SPND$S
err

[err]
Error routine address

Macro Expansion:
SPND$S
MOV
.BYTE
EMT
BCC
JSR

ERR
(PC)+,-(SP)
45.,1
377
.+6
PC,ERR

;PUSH DPB ONTO THE STACK
;SPND$S MACRO DIC, DPB SIZE=l WORD
;TRAP TO THE EXECUTIVE
;BRANCH IF DIRECTIVE SUCCESSFUL
;OTHERWISE, CALL ROUTINE "ERR"

Local Symbol Definitions:
None
DSW Return Codes:
IS.SPD

Successful completion (task was suspended)

IE.ADP

Part of the DPB is
space

IE.SOP

DIC or DPB size is invalid

out of the issuing task's address

Notes:
1.

A suspended task retains control of the system resources
allocated to
it.
The Executive makes no attempt to free
these resources, until a task exits.

A suspended task is eligible for checkpointing unless
fixed or declared to be noncheckpointable.

Because this directive requires only a 1-word DPB,
the &s
form of the macro is recommended.
It requires less space and
executes with the same speed as the DIR$ macro.

.~,

6-128

DIRECTIVE DESCRIPTIONS

SPRA$
'~

6.3.58

Specify Power Recovery AST

The Specify Power Recovery AST directive
record one of the two following cases:

instructs

the

system

Power recovery ASTs for the issuing task are desired, and
control
is to be transferred when a powerfail recovery AST
occurs.

Power recovery ASTs
desired.

for

the

issuing

task

are

longer

When an AST service routine entry point address is specified,
future
power recovery ASTs will occur for the issuing task, and control will
be transferred to the indicated location at the time of the AST's
occurrence. When an AST service entry point address is not specified,
future power recovery ASTs will not occur until an AST entry point is
again specified. See Notes below.
FOR'I'RAN Call
To establish an AST
EXTERNAL sub
CALL PWRUP (sub)
sub

Name of a subroutine to be executed upon
recovery.
The PWRUP subroutine will effect a

power

CALL sub (no arguments).
The subroutine is called as a
result of a power
recovery
AST and therefore may be controlled at
critical points by using DSASTR and ENASTR subroutine
calls.
To remove an AST
CALL PWHUP
Mac 1ro Cal 1:
SPRA$
ast

[a st]

AST service routine entry point address

Macro Expansion:
SPRA$
.BYTE
.WORD

PWRAST
167.,2
PWRAST

;SPRA$ MACRO DIC, DPB SIZE=2 WORDS
;ADDRESS OF POWER RECOVERY AST

Local Symbol Definitions:
S.PRAE

AST entry address (2)

DSW Return Codes:

rs. sue

Successful completion

6-129

DIRECTIVE DESCRIPTIONS
IE.UPN

Insufficient dynamic memory

IE. I TS

AST entry point address is already unspecified

IE.AST

Directive was issued from an AST service routine, or,
ASTs are disabled

IE.ADP

Part of the DPB is out of the issuing task's address
space

IE.SOP

DIC or DPB size is invalid

Notes:

Specify Power Recovery AST requires dynamic memory.

The Executive queues power recovery ASTs when the power-up
interrupt occurs following a
power failure.
No future
powerfail ASTs will be queued for the task until
the first
one queued has been effected.

The task enters the powerfail AST service
task stack in the following state:
SP+06
SP+04
SP+02
SP+OO

routine

with

the

Event flag mask word
PS of task prior to AST
PC of task prior to AST
DSW of task prior to AST

No trap-dependent parameters accompany a power recovery AST;
therefore, the AST Service Exit directive (see Section 6.3.4)
can be executed with the stack in the same state as when the
AST was entered.
4.

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

6-130

service

routine

DIRECTIVE DESCRIPTIONS

SPWN$
6.3.59

Spawn

The

directive
requests a
specified
task
for
execution,
queuing a
command linel, and establishing the task's TI:
as a~~~l~~~~~~~~~h~~~·~~~~~~~~~~~~ physical terminal.

•

When this directive is issued, an Offspring Control
Block
(OCB)
is
queued
to the offspring TCB and a rundown count is incremented in the
parent task's TCB.
The rundown count is used to inform the
Executive
that the task is a parent task and has one or more offspring tasks '..etr).;g·,
'."'.:):~ 1:~{~:~·~:.e:~FL:·~.~;t:m)~.:g::~:~{t.'.~;),;<~hfl'. cleanup is necessary if a parent task exits with
active offspring
tasks.
The
rundown count is decremented when the
spawned task exits.
The OCB contains the TCB address as well
as
sufficient information to effect all of the specified exit events when
the offspring task exits.
If a command line is specified, it is buffered in the Executive pool
and queued
for
the offspring
task for subsequent retrieval by the
offspring task via
the Get MCR Command
Line directive.
Maximum
command line length is 79 characters.
If an AST address is specified, an exit AST routine is effected when
the
spawned
task exits with the address of the task's exit status
block on the stack.
The AST routine must remove this word
from
the
stack before issuing the AST Service Exit directive.
Special action is taken if the task being spawned is a
Command
Line
Interpreter
(CLI),
such as MCR~i·~--~{j';J;),~,]4·/~Ml: In this case, a command line
must be specified, and both the cit~.·~~~ .the command
line
are queued
for the interpreter task.
MCR ;;~.P,a'·''
.•either handle commands directly
or dispatch them to another ta~k~·
n the case of direct execution of
the command, the OCB may be used to immediately effect the proper exit
conditions and return exit status via an Executive routine.
If MCR ~t
:;!'..;'f:Q·~~:D·d i spa tch another task, they simply move the OCB from their own OCB
queue directly to the OCB queue of the dispatched
task.
They also
queue
the command
line
for
the dispatched task as usual.
At this
point, the s:Ltuation is exactly the same as if the SPWN$ directive had
specified
the dispatched
task directly.
No exit conditions occur
until the dispatched task exits.
FOR'rRAN call:
CALL SPAWN

(rtname, [iugc], [iumc], [iefn], [iast], [iesb], [iparm],
[ icml in] , [ icmlen] , [ i unit] , [dnam] , [ids])

rtname

Name of the offspring task to be spawned

iugc

Group code number for the UIC of the offspring task

iumc

Member code number for the UIC of the offspring task

iefn

Event fla~ to be set when the offspring
.;;9:~~%%.~rm.~;&:~m;.:·$[~.'.:~<:!~·µ;~·x.

iast

Address of an AST routine
to be called
o f f s pr i n g ta s k e x i ts <~~jp;,\t'.~.tt!. ~1.1~:'.$it~.$1~F~j~:i?/

task
when

Command line processing is not available for RSX-llS tasks.

6-131

exits
the

DIRECTIVE DESCRIPTIONS

iesb

Address of an 8-word status block to be written when
the offspring task exits or -emits. st~#).:1$
word

word 1-7

Offspring task exit status
Reserved

iparm

Address of a word
to
receive
address when the AST occurs

icmlin

Address of a command
offspring task

icmlen

Length of the command line (79.

iunit

Unit number of terminal to be used as
TI:
for
the offspring task •. r~ th.~ opt;;~c>B~;·
is . . . not specified, th is .P'arame,t7t ·rnU§:#.<n >.
: number . of a virtual terminal cre'at.ea-::tjyY
taslq
if a value of 0 is specified, ·the"'Tf~·
issuing
task
is propagated.
A task must
privileged in order to specify a TI:
other than
parent task's TI:.

dnam

Device .name mnemonic ... rf··•·!lot . . •specff~·~k:t;S<r.(h.~i.f;
: terminal is used as ~rI:.
· · ,. ·
·

ids

Integer to receive the directive status word

line

the
be

status

queued

for

block
the

characters maximum)

Macro Call:
SPWN$

tname,,, [ugc], [umc], [efn] ,. [east], [esb], [cmdlin], [cmdlen],
[unum], [dnam]

tname

Name of the offspring task to be spawned

ugc

Group code number for the UIC of the offspring task

umc

Member code number for the UIC of the offspring task

efn

The event flag to be cleared on
when the offspring task exits Ot

east
esb

issuance

and

set

emtts.)liitq_.tt.:f~::

~.
i

Address of an AST routine to
offspring task exits or ~mit;;s

called

stat·us

when

the

Address of an 8-word status block to be written when
the offspring task exits or emits ~t•tQ$j
word

word 1-7

Offspring task exit status
Reserved

cmdlin

Address of a command
offspring task

cmdlen

Length of the command line (maximum length is 79.)

unum

Unit number of terminal to be used as the TI:
th7. of f~pr ing task •. If the opt:;p.f:~il:t ··~f'l~rn
.i~. not specified.,. this ·parameter ~u.st··~-PEf·;.
numl;)er of: a virtual terminal .cr~~tecl:.~y-.:f ~.
ta~k;
if a value of 0 is spe~ified, the TI:

6-132

line

queued

for

the

for

DIRECTIVE DESCRIPTIONS
issuing
task
is propagated.
A
privileged in order to specify a TI:
parent task's TI:.
dnam

•

task must be
other than the

Device name mnemonic.

Macro Expansion:
SPWN$
.BYTE
.RAD50
.BLKW
.BYTE
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD

ALPHA,,,3,7,l,ASTRUT,STBLK,CMDLIN,72.,2
11.,13.
;SPWN$ MACRO DIC, DPB SIZE=l3 WORDS
ALPHA
;NAME OF TASK TO BE SPAWNED
3
;RESERVED
7,3
;UMC = 7
UGC = 3
1
;EVENT FLAG NUMBER = 1
ASTRUT
;AST ROUTINE ADDRESS
STBLK
;EXIT STATUS BLOCK ADDRESS
CMDLIN
;ADDRESS OF COMMAND LINE
72.
COMMAND LINE LENGTH = 72. CHARACTERS
2

NOTE
one ad it1ona
parameter (device name)
can be added for a hardware terminal
name • F o r ex amp 1 e , TT 2 ii~V~~i~~lg;~;l~lr]bfl~~~~~i'.!I,~~<;
would have the same macro expans10~
shown above, plus the following:
.ASCII

/TT/

;ASCII

DEVICE NAME

The DPB size will then be 14 words.

Local Symbol Definitions:
S.PWTN

Task name (4)

S.PWXX

Reserved (6)

S.PWUM

User member code (1)

S.PWUG

User group code (1)

S.PWEF

Event flag number (2)

S.PWEA

Exit AST routine address (2)

S.PWES

Exit status block address (2)

S.PWCA

Command line address (2)

S.PWCL

Command line length (2)

S.PWVT

Terminal unit number (2)

S.PWDN

Device name ( 2)

DSW Return Codes:

Is.sue

Successful completion

6-133

DIRECTIVE DESCRIPTIONS

IE. UPN

Insufficient dynamic memory to allocate an offspring
control
block,
command
line ~uffer,
task control
block, or partition control block

IE. INS

The specified task was not installed,
or
it was a
command
line
interpreter but no command line was
specified

IE.ACT

The specified task was already active and it was
a command line interpreter.

IE. I DU

The specified virtual terminal unit does not
or it was not created by the issuing task

IE. I EF

An invalid event flag number was specified

IE.ADP

Part of the DPB, exit status block, or command
is out of the issuing task's address space

IE. SDP

DIC or DPB size is invalid

6-134

not

exist,

line

•

DIRECTIVE DESCRIPTIONS

SRDA$
6.3.60

Specify Receive Data AST

The Specify Receive Data AST directive instructs the system to
one of the following two cases:

-·

record

•

Receive data ASTs for the issuing task are desired,
and
the
Executive transfers control to a specified address when data
have been placed in the task's receive queue

•

Receive data ASTs for the issuing task are no longer desired.

When the directive specifies an AS'l' service routine entry point,
receive data ASTs for the task will subsequently occur whenever data
have been placed in the task's receive queue;
the Executive will
transfer control to the specified address.
When the directive omits an entry point address,
the Executive
disables receive data ASTs for the issuing task.
Receive data ASTs
will not occur until the task issues another Specify Receive Data AST
directive that specifies an entry point address.
See Notes below.
FOR'TRAN Cal 1:
Neither the FORTRAN language nor the ISA standard permits direct
linking to system trapping mechanisms;
therefore, this directive
is not available to FORTRAN tasks.
Macro Call:
SRDA$
ast

[ ast]
AST service routine entry point address

Macro Expansion:
SRDA$
.BYTE
.WORD

RECAST
107.,2
RECAST

;SRDA$ MACRO DIC, DPB SIZE=2 WORDS
;ADDRESS OF RECEIVE AST

Local Symbol Definitions:
S.RDAE

AST entry address (2)

DSW Return Codes:

rs.sue

Successful completion

IE.UPN

Insufficient dynamic memory

IE. ITS

AST entry point address is already unspecified

IE.AST

Directive was issued from an AST service routine,
ASTs are disabled

IE.ADP

Part of the DPB is out of the issuing task's
space

IE. SDP

DIC or DPB size is invalid

6-135

address

DIRECTIVE DESCRIPTIONS
Notes:
1.

Specify Receive Data AST requires dynamic memory.

The Executive queues receive data ASTs when a message is sent
to the task.
No future receive data ASTs will be queued for
the task until the first one queued has been effected.

The task enters the recieve data AST service routine with the
task stack.in the following state:
SP+06
SP+04
SP+02
SP+OO

Event flag mask word
PS of task prior to AST
PC of task prior to AST
DSW of task prior to AST

•

No trap-dependent parameters accompany a
receive data AST;
therefore, the AST Service Exit directive (see Section 6.3.4)
must be executed with the stack in the same state as when the
AST was effected.
4.

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

6-136

service

routine

DIRECTIVE DESCRIPTIONS

•

6-137

DIRECTIVE DESCRIPTIONS

SREF$
6.3.62

Send By Reference

The Send By Reference directive inserts a packet containing a
reference to a region into the receive-by-reference queue of a
specified (receiver) task. The Executive automatically attaches the
receiver task for each Send By Reference directive issued by the task
to the specified region (the region identified in W.NRID of the Window
Definition Block). The attachment occurs even if the receiver task is
a 1 ~eac}X . . . att~.C:h.e·d··. ··to. the . r.~g ion, unless. bit·. . W$.~;i::J.!\1')id.4)J>;fY:~~.i:;J~··~B--X:F:. §(~r(%!:::.~#:l;i'.~'.·?,f/>
·'W:;Q'ct~'.>'~.i p~.fint~:~Pt1 •. B).oc~.· . .·•is
set.
'I'he successful exe.cufion o.f 't:fii'·5··
-~ii~ctive cause~ a si~nificant event to occur.

•

The send packet contains:
•

A pointer to the created attachment descriptor, which
the region ID to be used by the receiver task

becomes

•

The offset and length words specified in W.NOFF and W.NLEN of
the Window Definition Block
(which the Executive passes
without checking)

•

The receiver task's permitted access to the region,
in the window status word W.NSTS

•

The sender task name

•

Optionally, the address of an 8-word buffer that contains
additional
information
(If the packet does not include a
buffer address, the Executive sends eight words of O.)

contained

The receiver task automatically has access to the entire region as
specified in W.NSTS. The sender task must be attached to the region
with at least the same types of access.
By setting all the bits in
W.NSTS to O, the permitted access can be defaulted to that of the
sender task.
If the directive specifies an event flag, the Executive sets the flag
in the sender task when the receiver task acknowledges the reference
by issuing the Receive By Reference directive
(see Section 6.3.48).
When the sender task exits, the system searches for any unrecelved
references that specify event flags, and prevents any invalid attempts
to set the flags.
The references themselves remain in the recelver
task's receive-by-reference queues.
FORTRAN Call:
CALL SREF (tsk, [efn] ,iwdb, [isrb] [,,ids]
tsk

A single precision, floating-point variable containing
the name of the receiving task in Radix-50 format

efn

Event flag number

iwdb

An 8-word integer array containing a Window Definition
Block (see Section 3.5.2.2)

isrb

An 8-word
integer
array
containing
additional
information
(If specified, the address of isrb is
placed.in iwdb(8).
If isrb is omitted, the contents
of iwdb(8) remain unchanged.)

6-138

•

•.

DIRECTIVE DESCRIPTIONS

ids
'-""

Directive status

Macro Call:
SREF$

task,wdb[,efn]

task

Name of the receiver task

wdb

Window Definition Block address

efn

Event flag number

Macro Expansion:
SREF$
.BYTE
.RAD50
.WORD
.WORD

ALPHA,WDBADR,48.
69.,5
;SREF$ MACRO DIC, DPB SIZE=5 WORDS
/ALPHA/
;RECEIVER TASK NAME
48.
;EVENT FLAG NUMBER
WDBADR
;WDB ADDRESS

Window Definition Block Parameters:
Input parameters
Array
Element

Off set

iwdb(4)

W.NRID

ID of the region to be sent by reference

i wdb ( 5)

W.NO:L<'F

Offset word, passed without checking

iwdb(6)

W.NLEN

Length word, passed without checking

iwdb ( 7)

W.NSTS

Bit settingsl in window status word
receiver task's permitted access):

iwdb(8)

W.NSRB

(the

WS.RED

1 if read access is permitted

WS.WRT

1 if write access is permitted

WS.EXT

1 if extend access is permitted

WS.DEL

1 if delete access is permitted

Optional
address of
an 8-word
containing additional information

buffer

Output parameters
None
Local Symbol Definitions:
S.RETN

Receiver task name (4)

S.REBA

Window Definition Block base address (2)

S. REEli'

Event flag number

(2)

1 FORTRAN programmers should refer to Section 3.5.2 to determine
bit values represented by the symbolic names described.

6-139

the

DIRECTIVE DESCRIPTIONS
DSW Return Codes:

rs. sue

successful completion

IE. UPN

A send packet or an attachment descriptor
be allocated

IE.INS

The sender task attempted to send a reference to an
Ancillary Control Processor (ACP) task, or task not
installed

IE.PR!

Specified access not allowed to sender task itself

IE .NVR

Invalid region ID

IE. IEF

Invalid event flag number

IE.ADP

The address check of the DPB, the WDB,
buffer failed

IE.HWR

Region had load failure or parity error

IE.SOP

DIC or DPB size is invalid

could

not

'<I

the

send

Notes:
1.

For the user's convenience, the ordering of the SREF$ macro
arguments does not qirectly correspond to the format of the
DPB. The arguments have been arranged so that the optional
argument
(efn)
is at the end of the macro call. This
arrangement is also compatible with the SDAT$ macro.

Because region attachment requires system dynamic memory, the
receiver task should detach from any region that it was
already attached to, in order to prevent depletion of the
memory pool.
That is,
the task needs to be attached to a
given region only once.

.~,

6-140

DIRECTIVE DESCRIPTIONS

SRRA$
6.3.63

Specify Receive-By-Reference AST

The Specify Receive-By-Reference AST directive instructs the system to
record one of the following two cases:
•

Receive-by-reference ASTs for the issuing task are desired,
and the Executive transfers control to a specified address
when such an AST occurs.

•

Receive-by-reference ASTs for the issuing task are
desired.

longer

When the directive specifies an AST service routine entry point,
receive-by-reference ASTs for the task will occur:
the Executive will
transfer control to the specified address.
When the directive omits an entry point address, the Executive stops
the occurrence of receive-by-reference ASTs for the issuing task.
Receive-by-reference ASTs will not occur until the task issues another
Specify Receive-By-Reference AST directive that specifies an entry
point address.
See Notes below.
FORTRAN Call:
Neither the FORTRAN language nor the ISA standard permits direct
linking to system-trapping mechanisms;
therefore, this directive
is not available to FORTRAN tasks.
Macro Call:
SRRA$
ast

[ast]
AST service routine entry point address (0)

Macro Expansion:
SRRA$
.BYTE
.WORD

RECAST
21. '2
RECAST

;SRRA$ MACRO DIC, DPB SIZE=2 WORDS
;ADDRESS OF RECEIVE AST

Local Symbol Definitions:
S.RRAE

AST entry address (2)

DSW Return Codes:

rs.sue

Successful completion

IE.UPN

Insufficient dynamic memory

IE. ITS

AST entry point address is already unspecified

IE .AS'l'

Directive was issued from an AST service routine,
ASTs are disabled

IE.ADP

Part of the DPB is out of the issuing task's
space

IE.SOP

DIC or DPB size is invalid

6-141

address

DIRECTIVE DESCRIPTIONS
Notes:
1.

Specify Receive-By-Reference AST requires dynamic memory.

The Executive queues receive-by-reference ASTs when a message
is sent to the task.
Future receive-by-reference ASTs will
not be queued for the task until the first one queued has
been effected.

The task enters the receive-by-reference AST service
with the task stack in the following state:
SP+06
SP+04
SP+02
SP+OO

routine

Event flag mask word
PS of task prior to AST
PC of task prior to AST
DSW of task prior to AST

No trap-dependent parameters accompany a receive-by-reference
AST;
therefore, the AST Service Exit directive (see Section
6.3.4) must be executed with the stack in the same state as
when the AST was effected.
4.

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

6-142

service

routine

~.
~\

DIRECTIVE DESCRIPTIONS

6-1L13

DIRECTIVE DESCRIPTIONS

6-144

DIRECTIVE DESCRIPTIONS

STLO$
6.3.65

Stop For Logical OR Of Event Flags

The Stop For Logical OR Of Event Flags directive instructs the system
to stop the issuing task until the Executive sets one or more of the
indicated local event flags from one of the following groups:
GR 0

Flags 1-16

GR 1

Flags 17-32

The task does not stop itself if any of the
already s~t when the task issues the directive.
be issued at AST state.

indicated flags are
This directive cannot

A task that is stopped for one or more event flags can only become
unstopped by setting the specified event flag;
it cannot become
unstopped via the Unstop directive.
FOR~rRAN

Call::

CALL STLOR (iefl,ief2,ief3, •••
iefl

ief(n)

ief(n))

List of event flag numbers

Macro Call:
STLO$

grp, msk

grp

Desired group of event flags

msk

A 16-bit mask word

Macro Expansion:
STLO$
.BYTE
.WORD
.WORD

1,47
137.,3
1

;STLO$ MACRO DIC, DPB SIZE=3 WORDS
;GROUP 1 FLAGS (FLAGS 17-32)
; MASK WORD = 47 (FLAGS 17, 18, 19 ,, 22)

Local Symbol Definitions:
S.TLG:R

Group flags (2)

S.TLMS

Mask word (2)

DSW Return Codes:

IS.sue

Successful completion

IE.AST

The issuing task is at AST state

IE.IEF

An event flag group other than 0 or 1
or the event flag mask word is zero

IE.ADP

Part of the DPB is out of the issuing task's
space

IE.SCP

DIC or DPB size is invalid

6-145

was

specified
address

DIRECTIVE DESCRIPTIONS
Notes:
1.

There is a one-to-one correspondence between bits in the mask
word and the event flags in the specified group. That isv if
group l were specified
(as in the above macro expansion
example),
bit O in the mask word would correspond to event
flag 17, bit l to event flag 18, and so forth.

The Executive does not arbitrarily clear event flags when
Stop For Logical OR Of Event Flags conditions are met. Some
directives (Queue I/O Request, for example) implicilty clear
a flag;
otherwise,
they must be explicitly cleared by a
Clear Event Flag directive.

The argument list specifie~ in the FORTRAN call must contain
only event flag numbers that lie within one event flag group.
If event flag numbers are specified that lie in more than one
group, or if an invalid event flag number is specified, a
fatal FORTRAN error is generated.

Tasks stopped for event flag conditions cannot be unstopped
by issuing the Unstop directive;
tasks stopped in this
manner can only be unstopped by
meeting
event
flag
conditions.

The grp operand must always be of the form n regardless of
the macro form used. In all other macro calls, numeric or
address values for $S form macros have the form:
#n
For STLO$S this form of the grp argument would be:
n

6-146

DIRECTIVE DESCRIPTIONS

STOP$S
6.3.66

Stop ($S form recommended)

The Stop directive stops the issuing task.
This directive cannot be
issued at AST state.
A task stopped
in this manner can only be
unstopped by another task that issues an Unstop directive directed to
this task.
FORTRAN Call:
CALL STOP ([ids])
ids

Integer to receive the directive status word

Macro Call:
STOP$S
Macro Expansion:
STOP$S
.BYTE

131.,1

;STOP$ MACRO DIC, DPB SIZE=l WORD

Local Symbol Definitions:
None
DSW Return Codes:
IS.SET

Successful completion

IE.AS'r

The issuing task is at AST state

IE.ADP

Part of the DPB is out of the issuing task's
space

IE.SOP

DIC or DPB size is invalid

6-147

address

DIRECTIVE DESCRIPTIONS

STSE$
6.3.67

Stop For Single Event Flag

The Stop For Single Event Flag directive instructs the system to stop
the
issuing task until the specified local event flag is set.
If the
flag is set at issuance, the task is not stopped.
This directive can
not be issued at the AST state.
A task that is stopped for one or more event flags can only become
unstopped by setting the specified event flag;
it cannot become
unstopped via the Unstop directive.
FORTRAN Call:
CALL STOPFR {iefn,[ids])
iefn

Event flag number

ids

Integer to receive directive status word

Macro Call:
STSE$

efn

Event flag number

Macro Expansion:
STSE$
.BYTE
.WORD

135.,2
7

;STSE$ MACRO DIC, DPB SIZE=2 WORDS
;LOCAL EVENT FLAG NUMBER = 7

Local Symbol Definitions:
S.TSEF

Local event flag number (2)

DSW Return Codes:

Is.sue

Successful completion

IE.AST

The issuing task is at AST state

IE.IEF

An event flag number other than a
local
was specified {not in the range 1-32)

IE.ADP

Part of the DPB is out of the issuing task's
space

IE.SOP

DIC or DPB size is invalid

6-148

event

flag

address

DIRECTIVE DESCRIPTIONS

SVOB$
6.3.68

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-task debugging aid (ODT, for example).
To deassign the vector table, omit the parameters adr and len from the
macro call.
Whenever an SST service routine entry is specified in both the table
used by the task and the table used by a debugging aid, the trap
occurs for the debugging aid, not for the task.
FOR'rRAN Call:
Neither the FORTRAN language nor the ISA standard permits direct
linking to system trapping mechanisms;
therefore, this d:irective
is not available to FORTRAN tasks.
Macro Call:
SVOB$

[adr][,len]

adr

Address of SST vector table

len

Length of (that is, number of entries in)
words

the table

The vector table has the following format:
word 0

Odd address of none>c is tent memory error

word 1

Memory protect violation

word 2

T-bit trap or execution of a BPT instruction

word 3

Ei:xecution of an !OT instruction

word 4

.Execution of a reserved instruction

word 5

Execution of a non-RSX EMT instruction

word 6

Execution of a TRAP instruction

word 7

PDP-11/40 floating point exception

A 0 entry in the table indicates that the task does not
process the corresponding SST.

want

Macro Expansion:
SVOB$
.BYTE
.WORD
.WORD

SSTTBL,4
105 • .,3
SSTTBL
4

;SVOB$ MACRO DIC, DPB SIZE=3 WORDS
;ADDRESS OF SST TABLE
;SST TABLE LENGTH=4 WORDS

6-149

DIRECTIVE DESCRIPTIONS
Local Symbol Definitions:
S.VDTA

Table address (2)

S.VDTL

Table length (2)

DSW Return Codes:

rs.sue

Successful completion

IE .ADP

Part of the DPB or table is out of the issuing task's
address space

IE. SDP

DIC or DPB size is invalid

6-150

DIRECTIVE DESCRIPTIONS

:SVTK$
6.3.69

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 task.
To deassign the vector table, omit the parameters adr and len from the
macro call.
Whenever an SST service routine entry is specified in both the table
used
by the task and
the
table used by a debugging aid, the trap
occurs for the debugging aid, not for the task.
FORTRAN Call:
Neither the FORTRAN language nor the ISA standard permits direct
linking to system trapping mechanism;
therefore, this directive
is not available to FORTRAN tasks.
Macro Call:
SVTK$

[adr] [, len]

adr

Address of SST vector table

len

Length of (that is, number of entries in)
words

the table

The vector table has the following format:
word

Odd address of nonexistent memory error

word

Memory protect violation

word

T-bit trap or execution of a BPT instruction

word

Execution of an !OT instruction

word

Execution of a reserved instruction

word

Execution of a non-RSX EMT instruction

word

Execution of a TRAP instruction

word

PDP-11/40 floating point exception

A 0 entry in the table indicates that the task does not
process the corresponding SST.

want

Macro Expansion:
SVTK$
.BYTE
.WORD
.WORD

SSTTBL,4
105.,3
SSTTBL
4

;SVTK$ MACRO DIC, DPB SIZE=3 WORDS
;ADDRESS OF SST TABLE
;SET TABLE LENGTH=4 WORDS

6-151

DIRECTIVE DESCRIPTIONS
Local Symbol Definitions:
S.VTTA

Table address (2)

S.VTTL

Table length (2)

DSW Return Codes:

rs.sue

Successful completion

IE.ADP

Part of the DPB or table is out of the issuing task's
address space

IE.SOP

DIC or DPB size is invalid

6-15:2

DIRECTIVE DESCRIPTIONS

UMAP$
6.3.70

Unmap Address Window

The Unmap Address Window directive unmaps a specified window.
After
the window has been unmapped, references to the corresponding virtual
addresses are invalid and cause a processor trap to occur.
FORTIRAN Call:
CALL UNMAP (iwdb[,ids])

iwdb

An 8-word integer array containing a Window Definition
Block (see Section 3.5.2.2)

ids

Directive status

Mac n:> Cal 1:
UMAP$

wdb

Window Definition Block address

Macro Expansion:
UMAP$
.BYTE
.WORD

WDBADR
123.,2
WDBADR

;UMAP$ MACRO DIC, DPB SIZE=2 WORDS
;WDB ADDRESS

Window Definition Block Parameters:

'-'

Input parameters
Array
Elemen_!:

Q!f set

i wdb ( 1)
bits 0-7

W.NID

ID of the window to be unmapped

W~NSTS

Bit settingsl in the window status word:

Output parameters
iwdb(7)
~

WS.UNM

1
if
the
window
successfully unmapped

was

Local Symbol Definitions:
U.MABA

Window Definition Block address (2)

DSW Return Codes:

rs.sue

Successful completion

IE. ITS

The specified address window is not mapped

IE .NVW

Invalid address window ID

FORTRAN programmers should refer to Section 3.5.2 to determine
bit values represented by the symbolic names described.

6-153

the

DIRECTIVE DESCRIPTIONS

IE.ADP

DPB or WDB out of range

IE. SDP

DIC or DPB size is invalid

.,I

~.I

6-154

DIRECTIVE DESCRIPTIONS

LJSTP$
6.3.71

Unstop Task

The Unstop Task directive unstops the specified task which has stopped
itself via either the Stop or Receive Data Or Stop directive.
It does
not unstop tasks stopped
for
event flag(s)
or
tasks stopped
for
buffered
I/O.
If the Unstop directive is issued to a task previously
stopped via the Stop or Receive Or Stop directive while at task state,
and
the
task
is presently at AST state,
the
task only becomes
unstopped when it returns to task state.

•

The Unstop directive can be issued by a
nonprivileged
task.
It
is
considered the responsibility of the unstopped task to determine if it
has been validly unstopped.
FORT'RAN Call:
CALL USTP (rtname,[ids])
rtname

Name of task to be unstopped

ids

Integer to

rec~ive

directive status information

Macro Call:
USTP$

tname

Name of task to be unstopped

Macro Expansion:
USTP$
.BYTE
.RAD50

ALPHA

133.,3
ALPHA

;USTP$ MACRO DIC, DPB SIZE=3 WORDS
;NAME OF TASK TO BE UNSTOPPED

Local Symbol Definitions:
U.STTN

Task name

(4)

DSW Return Codes:

rs.sue

Successful completion

IE.INS

The specified task is not installed in the system

IE.ACT

The specified task is not active

IE. I TS

The specified task is not stopped, or it
for event flag(s) or buffered I/O

stopped

IE.ADP

Part of the DPB is out of the issuing task's
space

address

IE.SOP

DIC or DPB size is invalid

"·

6-155

DIRECTIVE DESCRIPTIONS

6-156

DIRECTIVE DESCRIPTIONS

•

6-157

DIRECTIVE DESCRIPTIONS

.•

6-158

DIRECTIVE DESCRIPTIONS

•

6-159

DIRECTIVE DESCRIPTIONS

Length of buff er
Integer to receive

Sender task name
Buff er address
Buffer size in words

task name ( 4)
address ( 2)

6-160

DIRECTIVE DESCRIPTIONS

6-161

DIRECTIVE DESCRIPTIONS

6-162

DIRECTIVE DESCRIPTIONS

6-163

DIRECTIVE DESCRIPTIONS

WSIG$S
6.3.76

Wait For Significant Event ($S form recommended)

The Wait For Significant Event directive is used to suspend the
execution of the issuing task until the next significant event occurs.
It is an especially effective way to block a task that cannot continue
because of a
lack of dynamic memory,
since significant events
occurring throughout the system often result in the release of dynamic
memory.
The execution of a Wait For Significant Event directive does
not itself constitute a significant event.
FORTRAN call:
CALL WFSNE
Macro Call:
WSIG$S
err

[err]
Error routine address

Macro Expansion:
WSIG$S
MOV
.BYTE
EMT
BCC
JSR

ERR
(PC)+,-(SP)
49. '1

377
.+6
PC,ERR

;PUSH DPB ONTO THE STACK
;WSIG$S MACRO DIC, DPB SIZE=l WORD
;TRAP TO THE EXECUTIVE
;BRANCH IF DIRECTIVE SUCCESSFUL
;OTHERWISE, CALL ROUTINE "ERR"

Local Symbol Definitions:
None
DSW Return Codes:

rs.sue

Successful completion

IE.ADP

Part of the DPB is out of the issuing
space

IE.SOP

DIC or DPB size is invalid

task's

address

Notes:
1.

If a directive is rejected for lack of dynamic memory,
this
directive
is the only technique available f~r blocking task
execution until dynamic memory may again be available.

The wait state induced by this directive is satisfied by the
first significant event to occur after the directive has been
issued. The significant event that occurs may or may not be
related to the issuing task.

Because this directive requires only a
1-word DPB,
the $S
form of the macro is recommended.
It requires less space and
executes with the same speed as the DIR$ macro.

6-164

DIRECTIVE DESCRIPTIONS
4.
~

Significant events include the following:

• I/O completion
• Task exit
• Execution of a Send Data directive
• Execution of a Send By Reference directive

• Execution of an Alter Priority directive
•

Removal of an entry from the clock queue (for instance,
resulting from the execution of a Mark Time directive or
the issuance of a rescheduling request)

•

Execution of a Declare Significant Event directive

•

Execution of the round-robin scheduling algorithm at the
end of a round-robin scheduling interval

""-''

6-165

DIRECTIVE DESCRIPTIONS

WTLO$
6.3.77

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 task until the Executive sets
the indicated event flags from one of the following groups:
GR 0

Flags 1-16

GR 1

Flags 17-32

GR 2

Flags 33-48

GR 3

Flags 49-64

GR 4

Flags 65-80

GR 5

Flags 81-96

The task does not block itself if any of the
already set when the task issues the directive.

indicated flags
See Notes below.

are

FORTRAN Call:
CALL WFLOR (efnl,efn2, ••• efnn)
efn

List of event flag numbers taken as the set of flags to
be specified in the directive
~~

Macro Call:
WTLO$

grp,msk

grp

Desired group of event flags

msk

A 16-bit flag mask word

Macro Expansion:
WTLO$
.BYTE
.WORD
. WORD

2,160003
43.,3
2

160003

;WTLO$ MACRO DIC, DPB SIZE=3 WORDS
; FLAGS SE'l' NUMBER 2 (FLAGS 33: 48.)
;EVENT FLAGS 33,34,46,47 AND 48 •

Local Symbol Definitions:
None
DSW Return Codes:

Is.sue

Successful completion
No event flag specified in the mask word or
group indicator other than O, 1, 2, 3, 4, or 5

IE.ADP

Part of the DPB is out of the issuing task's
space

IE. SDP

DIC or DPB size is invalid

6-166

flag

address

DIRECTIVE DESCRIPTIONS

Notes:
1.

There is a one-to-one correspondence between bits in the mask
word and the event flags in the specified group. That is, if
group 1 were specified, then bit O in the mask word would
correspond to event flag 17, bit 1 to event flag 18, and so
forth.

The Executive does not arbitrarily clear event flags when
Wait For conditions are met.
Some directives (Queue I/O
Request, for example) implicitly clear a flag;
otherwise,
they must be explicitly cleared by a Clear Eveht Flag
directive.

The grp operand must always be of the form n regardless of
the macro form used.
In all other macro calls, numeric or
address values for $8 form macros have the form:
#n
For WTLO$S this form of the grp argument would be:

n
4.

The argument list specified in the FORTRAN call must contain
only event flag numbers that lie within one event flag group.
If event flag numbers are specified that lie in more than one
group,
or if an invalid event flag number is specified, a
fatal FORTRAN error is generated.

6-167

DIRECTIVE DESCRIPTIONS

WTSE$
~\

6.3.78

Wait For Single Event Flag

The Wait For Single Event Flag directive instructs the system to block
the execution of the issuing task until the indicated event flag is
set.
If the flag is set at issuance, task execution is not blocked.
FORTRAN Call:
CALL WAITFR (efn[,ids])
efn

Event flag number

ids

Directive status

Macro Call:
WTSE$
efn

efn
Event flag number

Macro Expansion:
WTSE$
.BYTE
• WORD

52.
41., 2
52 •

;WTSE$ MACRO DIC, DPB SIZE=2 WORDS
;EVENT FLAG NUMBER 52.

Local Symbol Definitions:
W.TSEF

Event flag number (2)

DSW Return Codes:

rs.sue

Successful completion

IE. I EF

Invalid event flag number (EFN>64 or EFN<l)

IE.ADP

Part of the DPB is out of the issuing task's
space

IE.SOP

DIC or DPB size is invalid

6-168

address

APPENDIX A

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL

ABRT$

Abo1rt Task
FOR~rRAN

Call:

CALL ABORT (tsk[,ids])
tsk

Task name

ids

Directive status

Maciro Call:
ABRT$

tsk

Task name

ALTP$

Al t4~r Priori 1l:y

FOR'rRAN Call:
CALL .AL'rPRI

( [tsk] '[ipri] [,ids])

tsk

Active task name

ipri

1-word integer value
to 250 (decimal)

ids

Directive status

equa~

to the new priority, from

Macro Call:
ALTP$

[tsk] [ ,pri]

tsk

Active task name

pri

New priority, from 1 to 250 (decimal)

ALUN$

Ass:lgn LUN
FOR'rRAN Call:
CALL ASNLUN (lun,dev,unt[,ids])
lun

Logical unit number

dev

Device name

(format 1A2)

A-1

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
unt

Device unit number

ids

Directive status

:~\

Macro Call:
lun,dev,unt

ALUN$
lun

Logical unit number

dev

Device name

unt

Device unit number

(two characters)

AS'rX$S

AST Service Exit ($S form recommended)
FORTRAN Call:

Neither the FORTRAN language nor the ISA standard permits direct
linking to system-trapping mechanisms;
therefore, this directive
is not available to FORTRAN tasks.
Macro Call:
ASTX$S

[err]

err

Error routine address

Attach Region

ATRG$
~.

FORTRAN Call:
CALL ATRG
irdb

ids

( irdb [,ids])
An 8-word integer array containing a Region
Block (see Section 3.5.1.2)

Definition

Directive status

Macro Call:
ATRG$
rdb

rdb
Region Definition Block address

CINT$

Connect To Interrupt Vector
FORTRAN Call:
Not supported
Macro Call:
CINT$

vec,base,isr,edir,psw,ast

vec

Interrupt vector address -- Must be in the range 60(8)
to highest vector specified during SYSGEN, inclusive,
and must be a multiple of 4

base

Virtual base address for kernel APR 5 mapping
!SR, and enable/disable interrupt routines

A-2

the

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL

isr

Virtual address of the !SR, or O to disconnect from the
interrupt vector

edir

Virtual address of the enable/disable interrupt routine

psw

Low-order byte of the Processor
loaded before entering the !SR

ast

Virtual address of an AST routine to be
the fork-level routine queues an AST

Status

Word
entered

after

CLEF$

Clea1r Event li'lag

FOR'I'RAN Call:
CALL CLREF (efn[,ids])
efn

Event flag number

ids

Directive status

Macro Call:
CLEF$

efn

Event flag number
CMKT$

Cancel Mark Time Requests
FOR'I'RAN Call:
CALL CANMT ( [efn,ast] ,ids)
ids

Directive status

efn

Event flag number

ast

Mark time AST address

Macro Call:
CMKT$

[efn,ast,err]

efn

Event flag number

ast

Mark time AST address

err

Error routine address
CNCT$

Connect
FOR'I'RAN Call:
CALL CNCT (rtname, [iefn], [iast], [iesb], [iparm], [ids])
rtname~

Name of the offspring task to be connected

iefn

Event flag to be set when the offspring
or emits status

A-3

task

exits

DIRECTIVE SUMMARY - ALPHABETIC.AL ORDER BY MACRO CALL

iast

Address o~ an AST routine to be called
offspring task exits or emits status

iesb

Address of an 8-word status block to be written when
the offspring task exits or emits status
word

word 1-7

when

the

Offspring task exit status
Reserved

iparm

Address of a word to receive
address when an AST occurs

ids

Integer to

~eceive

the

status

block

the Directive Status Word

Macro Call:
CNCT$

tname, [efn] , [east], [esb]

tname

Name of the offspring task to be connected

efn

The event flag to be cleared on issuance and
when the offspring task exits or emits status

set

east

Address of an AST routine to be called
offspring task exits or emits status

the

esb

Address of an 8-word status block to be written when
the offspring task exits or emits status
word

word 1-7

when

Offspring task exit status
Reserved

Create Address Window

CRAW$

FORTRAN Call:
CALL CRAW (iwdb[,ids])
iwdb =

An 8-word integer array containing a Window
Block (see Section 3.5.2.2)

ids

Directive status

Definition

Macro Call:
CRAW$
wdb

wdb
Window Definition Block address

Create Group Global Event Flags

CR.GF$

FORTRAN Call:
CALL CRGF ([group] , [ids])
group

Group number for the flags to be created - If not
specified, the task's protection UIC (H.CUIC+l) in
the task's header is used

A-4

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
ids

Integer to receive the Directive Status Word

Mac r10 Cal 1:
CRGF$

[group]

group

Group number for the flags to be created - If not
specified,
the
task's protection UIC (H.CUIC+l) in
the task's header is used

Create Region

CRRG$

FORTRAN Call:
CALL CRRG
irdb
ids

(irdb[,ids])
An 8-word integer array containing a Region
Block (see Section 3.5.1.2)
Directive status

Macro Call:
CRRG$
rdb

rdb
Region Definition Block address

A-5

Definition

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL

Cancel Time Based Initiation Requests

CSRQ$

FORTRAN Call:
CALL CANALL (tsk[,ids])
tsk

Task name

ids

Directive status

Macro Call:
CSRQ$

tsk

Task name

Declare Significant Event ($S form recommended)

DECL$S

FORTRAN Call:
CALL DECLAR ([,ids])
ids

Directive status

Macro Call:
DECL$S
err

[,err]
Error routine address

Disable AST Recognition ($S form recommended)

DS.AR$S

FORTRAN Call:
CALL DSASTR [(ids)]
ids

Directive status

Macro Call:
DSAR$S
err

[err]
Error routine address

Disable Checkpointing ($S form recommended)
FORTRAN Call:
CALL DISCKP

A-6

DSCP$S

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
Macro Call:
DSCP$S

[err]

err

Error routine address

Deta4::h Reg ion

DTRG$

FORTIRAN Call:
CALL DTRG
irdb

ids

(irdb[,ids])
An 8-word integer array containing a Region
Block (see Section 3.5~1.2)

Definition

Directive status

Macro Call:
DTRG$
rdb

rdb
Region Definition Block address

ELAW$

Eliminate Address Window
FORT'RAN Call:
CALL ELAW ( iwdb [,ids])
iwdbi

An 8-word
integer array
containing
Definition Block (see Section 3.5.2.2)

ids

Directive status

Window

Macro Call:
ELAW$
wdb

wdb
Window Definition Block address

ELGF$

Eliminate Group Global Event Flags
FOR'.rRAN Call:
CALL ELGF ([group], [ids])
group

Group number of flags to be eliminated

ids

Integer to receive the Directive Status Word

Macro Call:
ELGF$
group

[group]
Group number of flags to be eliminated

A-7

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL

Enable AST Recognition ($S form recommended)

EN.AR$S

FORTRAN Call:
CALL ENASTR
Macro Call:
ENAR$S
err

[err]
Error routine address

Enable Checkpointing ($S form recommended)
FORTRAN Call:
CALL ENACKP
Macro Call:
ENCP$S
err

[err]
Error routine address

A-8

ENCP$S

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
EXIF$

Exit If
FORTIRAN Cal 1:
CALL EXITIF (efn[,ids])
efn

Event flag number

ids

Directive status

Macro Call:
EXIF$

efn

Event flag number

EXIT$S

Task Exit ($S form recommended)
FORT'RAN Call:
STOP
or
CALL E:XIT
Macro Call:
EXIT$S

[err]

err

Error routine address

EXST$

Exit: With Status
FOR'l~RAN

Call:

CALL EXST (istatus)
istatus

16-bit quantity to be returned to parent task

Macro Call:
EXST$

status

16-bit quantity to be returned to parent task

EXTK$

Exttrnd Task
FOR'.rRAN Call:
CALL EX'rTSK ( [inc] ['ids])
inc

A positive or negative number equal to the number of
32-word blocks by which the task size is to be extended
or reduced - If omitted, task
size
defaults
to
installed task size

ids

Directive status

Macro Call:
EXTK$

[inc]

A-9

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
inc

A positive or negative number equal to
the number of
32-word blocks by which the task is to be extended or
reduced - If omitted, task size defaults to
installed
task size

GLUN$

Get LUN Information
FORTRAN Call:
CALL GETLUN (lun,dat[,ids])
lun

Logical unit number

dat

6-word integer array to receive LUN information

ids

Directive status

Macro Call:
GLUN$

lun,buf

'.'.'\

lun

Logical unit number

buf

Address of 6-word buffer
information

that

will

receive

the

LUN

GMCR$

Get MCR Command Line
FORTRAN Call:
CALL GETMCR (buf[,ids])
buf

80-byte array to receive command line

ids

Directive status

Macro Call:
GMCR$

G:MCX$

Get Mapping Context
FORTRAN Call:
CALL GMCX (imcx[,ids])
imcx =

An integer array to receive the mapping context.
The
size of the array is 8*n+l, where n is the number of
window blocks in the task's header - The maximum size
is 8*8+1=65.

ids

Directive status

Macro Call:
GMCX$
wvec

wvec
The address of a vector of n Window Definition Blocks;
n is the number of window blocks in the task's header

A-10

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
GPRT$

Get Partition Parameters
FOR'TRAN Call:
CALL GETPAR ( [prt] ,buf [,ids])
prt

Partition name

buf

A 3-word integer array to receive partition parameters.

ids

Directive status

Macro Call:
GPRT$

[ prt] , buf

prt

Partition name

buf

Address of 3-word buffer

GREG$

Get Region Parameters
FOR.TRAN Call:
CALL GETREG

([rid] ,buf [,ids])

rid

Region id

buf

3-word integer array to receive region parameters

ids

Directive status

Mac:ro Call:
GREG$

[rid] [ ,buf]

rid

Region id

buf

Address of 3-word buffer

Get Sense Switches ($S form recommended)

GSSW$S

FOHTRAN Call:
CALL READSW (isw)
isw

Integer to receive the console switch settings

Macro Call:
GSSW$S
err

[err]
Error routine address

GTIM$

Get Time Parameters
FOHTRAN Call:

FORTRAN provides several subroutines for obtaining the time in a
number of formats.
See the IAS/RSX-11 FORTRAN-IV User's Guide or
the FORTRAN IV-PLUS User's Guide.

A-11

DIRECTIVE SUMMARY - ALPHABETI1CAL ORDER BY MACRO CALL
Macro Call:
GTIM$

buf

Address of 8-word buffer
GTSK$

Get Task Parameters
FORTRAN Call:
CALL GETTSK (buf[,ids])
buf

16-word integer array to receive the task parameters

ids

Directive status

Macro Call:
GTSK$

buf

Address of 16-word buffer

Inhibit AST Recognition ($S form recommended)

IHAR$S

FORTRAN Call:
CALL INASTR
ids

[(ids)]

Directive status

Macro Call:
IHAR$S

[err]

err

Error routine address
MAP$

Map Address Window
FORTRAN Call:
CALL MAP (iwdb[,ids])
iwdb

ids

An 8-word integer array containing a Window
Block (see Section 3.5.2.2)

Definition

Directive status

Macro Call:
....

MAP$
wdb

wdb
Window Definition Block address
;·,

A-12

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
MRKT$

Mark. Time

FOR'I'RAN Cal 1:
CALL MARK (efn,tmg,tnt[,ids])
efn

Event flag number

tmg

Time interval magnitude

tnt

Time interval unit

ids

Directive status

The ISA standard call for delaying a task for
interval is also included:

specified

time

CALL WAIT (tmg,tnt,ids)
tmg

Time interval magnitude

tnt

Time interval unit

ids

Directive status

Macro Call:
MRKT$

[efn]i ,tmg ,tnt [,a st]

efn

Event flag number

tmg

Time interval magnitude

tnt.

Time interval unit

ast

AST entry point address

QIO$

Queue I/O Request
FOR:TRAN Call:
CALL QIO (fnc,lun, [efn], [pri], [isb], [prl] [,ids])
·~

fuc
lun

I/O function code
=

Logical unit number

efn

Flag number

pr.i

Priority;

isb

2-word integer array to receive final I/O status

prl

6-word integer
array
containing
device-dependent
parameters to be placed in parameter words 1 through 6
of the Directive Parameter Block (DPB)

ids

Directive status

ignored, but must be present

A-13

DIRECTIVE SUMMARY - ALPHABET:CCAL ORDER BY MACRO CALL

Macro Call:
QIO$

fnc,lun, [efn], [pri], [isb], [ast] [,prl]

fnc

I/O function code

lun

Logical unit number

efn

Event flag number

pri

Priority;

isb

Address of I/O status block

ast

Address of AST service routine entry point

prl

Parameter list of the form <Pl, ••• P6>

ignored, but must be present

QIOW$

Queue I/O Request And Wait

FORTRAN Call:
CALL WTQIO (fnc,lun,efn, [pri], [isb], [prl] [,ids])
fnc

I/O function code

lun

Logical unit number

efn

Event flag number

pri

Priority;

isb

2-word integer array to receive final I/O status

prl

6-word integer array containing
device
dependent
parameters to be placed in parameter words 1 through 6
of the DPB

ids

Directive status

ignored, but must be present

Macro Call:
QIOW$

fnc,lun,efn, [pri], [isb], [ast] [,prl]

f nc

I/O function code

lun

Logical unit number

ef n

Event flag number

pri

Priority;

isb

Address of I/O status block

ast

Address of AST service routine entry point

prl

Parameter list of the form <Pl, ••• P6>

ignored, but must be present

A-14

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
Receive Data Or Stop

RCST$

FOWrRAN Call::
CALL :RCST ( [rtname] ,ibuf [,ids])
rtname

Name of task from which data is to be received

ibuf

Address of 15-word buffer to receive the sender task
name and data

ids

Integer to receive the Directive Status Word

Mac:ro Call:
RCST$

[ tname] , buf

tname

Name of task from which data is to be received -- If
not specified, data may be received from any task

buf

Address of a 15-word buffer to
task name and data

receive

the

sender

RCVD$

Receive Data
FORTRAN Call:
CALL RECEIV (tsk,buf[,,ids])
tsk

Sender task name

buf

15-word integer array for received data

ids

Directive status

Macro Call:
RCVD$

tsk,buf

tsk

Sender task name

buf

Address of 15-word buffer

RCVX$

Receive Data Or Exit
FOHTRAN Call:
CALL RECOEX (tsk,buf[,,ids])
tsk

Sender task name

buf

15-word integer array for received data

ids

Directive status

Macro Call:
RCVX$ tsk,buf
tsk

Sender task name

buf

Address of 15-word buffer

A-15

DIRECTIVE SUMMARY -

ALPHABET:CCAL ORDER BY MACRO CALL
l~DAF$

Read All Event Flags

FORTRAN Call:
Only a single event flag can be read by a FORTRAN task.
is:

The call

CALL READEF (efn[,ids])
efn

Event flag number (l-64.)

ids

Directive status

Macro Call:
ROAF$

buf

Address of 4-word buffer
FlDXF$

Read Extended Event Flags

FORTRAN Call:
Only a single event flag can be read by a FORTRAN task.
is:

The call

CALL RDADEF (efn[,ids])
efn

Event flag number (1-96.)

ids

Directive status

Macro Call:
RDXF$

buf

Address of 6-word buffer

Request Task

RQST$

FORTRAN Call:
CALL REQUES (tsk, [opt] [,ids])
tsk

Task name

A-16

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
opt

4-word integer array

ids

opt(l)

partition name first
must be present

half;

ignored,

but

opt(2)

partition name second
must be present

half;

ig no re!d,

but

opt ( 3)

priority;

opt(4)

User Identification Code

ignored, but must be

prese~n t

Directive status

Macro Call:
RQST$

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

tsk

Task name

prt

Partition name;

pri

Priority;

ugc

UIC group code

umc

UIC member code

ignored, but must be present

RREF$

Receive By Reference
FOR'.rRAN Call:
CALL RREF ( iwdb, [ isrb] ['ids])
iwdb =

An 8-word integer array containing a Window
Block (see Section 3.5.2.2)

isrb

A 10-word integer array
buff er

ids

Directive status

used

DeJcinition
the

receive

Macro Call:
RREF$

wdb

Window Definition Block

RSUM$

Resume Task
FORTRAN Call:
CALL RESUME (tsk[,ids])
tsk

Task name

ids

Directive status

Macro Call:
RSUM$
tsk

tsk
Task name
A-17

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
RUN$

Run Task

FORTRAN Call:
CALL RUN {tsk, [opt], [smg] ,snt, [rmg], [rnt] [,ids])
tsk

Task name

opt

4-word integer array
opt { 1)

partition name
first
must be present

half;

ignored,

but

opt{2)

partition name second
must be present

half;

ignored,

but

opt { 3)

priority;

opt{4)

User Identification Code

ignored, but must be present

smg

Schedule delta magnitude

snt

Schedule delta unit

rmg

Reschedule interval magnitude

rnt

Reschedule interval unit

ids

Directive status

The ISA standard call for initiating a task is also included:
CALL START {tsk,smg,snt,ids)
tsk

= Task name

smg

Schedule delta magnitude

snt

Schedule delta unit

ids

Directive status

Macro Call:
RUN$

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

tsk

Task name

prt

Partition name;

pri

Priority;

ugc

UIC group code

umc

UIC member code

smg

Schedule delta magnitude

snt

Schedule delta unit

rmg

Reschedule interval magnitude

rnt

Reschedule interval unit

ignored, but must be present

A-18

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL

.•

SDAT$

Send Data
FORTRAN Call::
CALL SEND (tsk,buf, [efn] [,ids])
tsk

Task name

buf

13-word integer array of data to be sent

efn

Event flag number

ids

Directive status

Macro Call:
SDAT$

tsk ,buf [ ,efn]

tsk

Task name

buf

Address of 13-word data buffer

efn

Event flag number

A-19

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL

SETF$

Set Event Flag
FORTRAN Call:
CALL SETEF (efn[,ids])
efn

Event flag number

ids

Directive status

Macro Call:
SETF$
efn

efn
Event flag number

·A!I\

Specify Floating Point Exception AST

Sl~PA$

FORTRAN Call:
Not supported
Macro Call:
SFPA$
ast

[ast]
AST service routine entry point address

A-20

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL

Suspend ($S form recommended)

•

FOR~rRAN

SPND$S

Call:

CALL SUSPND

•

Macro Call:
SPND$S

[err]

err

Error routine address

Specify Power Recovery AST

SPRA$

FORTRAN Call:
CALL PWRUP (sub)
sub

Name of a
recovery.
following:

subroutine to be executed upon
power
The
PWRUP subroutine will effect the

CALL sub (no arguments)
The subroutine
is called as a
result of a power
recovery AST,
and
therefore the subroutine can be
controlled at critical points by using the DSASTR
(or
INASTR) and ENASTR subroutine calls
Macro Call:
SPRA$

[ast]

ast

AST service routine entry point address

SPWN$
FOFtTRAN Call:
CALL SPAWN ( rtname, [ i ugc] , [ i umc] , [ iefn] , [ iast] , [ iesb] , [ iparm] ,
[icmlin], [icmlen], [iunit], [dnam], [ids])
rtname

Name of the offspring task to be spawned

iuqc

Group code number for the UIC of the offspring task

iumc

Member code number for the UIC of the offspring task

iefn

Event fla

to be set when the offspring

iast

A-21

task

exits

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
iesb

Address of an
the offspring
word

word 1-7

itten when
Offspring task exit status
Reserved

iparm

Address of a word to receive.
address when the AST occurs

icmlin

Address of a command
offspring task

icmlen

Length of the command line (79.

iunit

Unit number of terminal to be used as the
.t:~.E:!..•.....• of f~pr.if1g . task. - . ·I·~ i~he RB~~·?··
is /n<)t ·.··sf?ec·~. f.i.ed . t .. 1:.his.·••··li'~r~met.~p l1J·~

line

the

status

queued

block

for

the

characters maximum)

TI:

o.f ·a vi rtua·1 termin.a:l·.·ore~e~·. ·
if a value of 0 is specified, the TI:
issuing task is propagated

for

J'lUrt)l:>?r

of the

b:~~I<;

dnam
ids

I)~yic:e n~me mn~.moni·9. ~ .•. • lf·. :hot ;~·p~~i·.~·l~~~(';\; .#~~A>'

~t.e.i':mtnal."< is . used . / as

'J?l:

Integer to receive the Directive Status Word

Macro Call:
SPWN$

tname,,, [ugc], [umc], [efn], [east], [esb], [cmdlin], [cmd:Len]
, [unum], [dnam]

tname

Name of the offspring task to be spawned

ugc

Group code number for the UIC of the offspring task

umc

Member code number for the UIC of the offspring task

ef n

The event flag to be cleared on issuance and
when the o f f s pr i n g ta s k ex i t s c).i~' ·:;:~'ijt~.·~~·r!;~:t;:·i'.~':ff~it.

set

east

Address of an AST routine to be called
offspring task exi t:s ¢}: ~mft·s:: ~ t·~·.tif~':\~

the

esb

Address of an 8-word status block to be written when
the offspring task exits or· ~mJ:t:s . $#:~~µ·~. . ·

word

word 1-7

when

Offspring task exit status
Reserved

cmdlin

Address of a command
offspring task

line

queued

for

cmdlen

Length of the command line (maximum length is 79.)

unum

Unit number of terminal to be used as the
~h .•?........ () f fs pr in9 . . ta.~.~. ·. ~ .•.. :tl:>.ij9:7"}<;)p#.~.p'.B. ·

TI:

the

for

··~·.~<JJOt ~.PE:!dif:ied1· thfs·· P'?r.citrie~~J:'.:'~4

·J'"i.~llll;>.E:!J of a virtual •terminal ¢J·ea.t
:t;:ts.]<;::• if a value of O is specified the TI:

issuing task is propagated
dnam

Dev ice name mnemonic - .lf .ho~t.· :~:p~.~~}l·~·ii~.~\~F. \~·ij;~;E~.<.'

tefmihal: J.s· .•. used/as tt'f.
A-22

the

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
NOTE
1.

If neither unum nor dnam is specified,
the
TI:
of the
issuing task
is
propagated •

•
SRDA$

Specify Receive Data AST

FOHTRAN Call:
Not supported
Macro Call:
SRDA$
ast

[ast]
AST service routine entry point address

SREF$

Send By Reference
FOHTRAN Call:
CALL SHEF (tsk, [efn] ,iwdb, [isrb] [,ids])

•

tsk

Receiver task name

efn

Event flag number

iwdb

An 8-word integer array containing a Window
Block (see Section 3.5.2.2)

Definitio~

isrb

An
8-word
information

additional

ids

Directive status

integer

Macro Call:
SREF$

•

task ,wdb [ ,efn]

task

Receiver task name

wdb

Window Definition Block

efn

Event flag number

A-23

array

containing

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
SRRA$

Specify Receive-By-Reference AST
FORTRAN Call:
Not supported
Macro Call:
SRRA$

[ast]

ast

•

AST service routine entry point address

S'l'LO$

Stop For Logical OR Of Event Flags
FORTRAN Call:
CALL STLOR (iefl,ief2,ief3,
iefl

ief (n)

ief(n))

List of event flag numbers

Macro Call:
STLO$

grp, msk

·~.

grp

Desired group of event flags

msk

A 16-bit mask word

STOP$S

Stop ($S form recommended)
FORTRAN Call:
CALL STOP ([ids])
ids

Integer to receive the Directive Status Word

Macro Call:
STOP$S

A-24

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
Stop For Single Event Flag

STSE$

FOR'I'RAN Ca 11:
CALL STOPFR (iefn[,ids])
iefn

Event flag number

ids

Integer to receive Directive Status Word

Macro Call::
STSE$

•

efn

Event flag number

SVDB$

Specify SST Vector Table For Debugging Aid
FOR~rRAN

Call::

Not supported
~·

Mac 1ro ca 11 :
SVDB$

[adr] [, len]

adr

Address of SST vector table

len

Length of (that is, number
words

entries

in)

table

SVTK$

Specify SST Vector Table For Task
FORTRAN Call:
Not supported
Macro Call:
SVTK$

[adr] ( ,len]

adr

Address of SST vector table

len

Length of (that is, number
words

entries

in)

table

UNMAP$

Unmap Address Window
FORTRAN Call:
CALL UNMAP (iwdb[,ids])
iwclb

An 8-word integer array containing a Window
Block (see Section 3.5.2.2)

ids

Directive status

Macro Call:
UMAP$
wdb

wdb
Window Definition Block address

A-25

Definition

DIRECTIVE SUMMARY - ALPHABETJ:CAL ORDER BY MACRO CALL
UISTP$

Unstop
FORTRAN Call:
CALL USTP (rtname[,ids])
rtname

Name of task to be unstopped

ids

Integer to receive directive status information

•

Macro Call:
USTP$
tname

tname
Name of task to be unstopped

A-26

•

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL

•

A-27

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
Wait For Significant Event ($S form

rec~mmended)

WSIG$S

FORTRAN Call:
CALL WFSNE
Macro Call:
WSIG$S

[err]

err

Error routine address

Wait For Logical OR Of Event Flags

WTLO$

FORTRAN Call:

•

CALL WFLOR (efnl,efn2, ••• efnn)
efn

List of event flag numbers taken as the set of flags to
be specified in the directive

Macro Call:
WTLO$

grp,msk

grp

Desired group of event flags

msk

A 16-bit octal mask word

Wait For Single Event Flag

WTSE$

FORTRAN Call:
CALL WAITFR (efn[,ids])
efn

Event flag number

ids

Directive status

Macro Call:
WTSE$
efn

efn
Event flag number

A-28

APPENDIX B
STANDARD ERROR CODES

The symbols listed below are associated with the directive status
codes returned by the RSX-llM/M-PLUS Executive. They are determined
(by default) at task-build time.
To
include these
in a MACR0-11
program, the progiammer uses the following two lines of code:
• MCALL
DRERR$

DRERR~~

STANDARD ERROR CODES RETURNED BY DIRECTIVES IN THE DIRECTIVE STATUS
WORD

'--"'

•

IS .. CLR
IS .. SUC
ISoSE:T

+00
+01
+02

EVENT FLAG WAS CLEAR
OPERATION COMPLETE, SUCCESS
EVENT FLAG WAS SET

IE .. UPN
IE .. INS
IE.UNS
IE. ULN
IE.HWR
IE.ACT
IE.ITS
IE.FIX
IE.CKP
IE.TCH
IE.RBS
IE.PHI
IE.RSU
IE.NSW
IE. I LV

-01.
-02.
-04.
-05.
-06.
-07.
-08.
-09.
-10.
-11.
-15.
-16.
-17.
-18.
-19.

INSUFFICIENT DYNAMIC STORAGE
SPECIFIED TASK NOT INSTALLED
INSUFFICIENT DYNAMIC STORAGE FOR SEND
UNASSIGNED LUN
DEVICE DRIVER NOT RESIDENT
TASK NOT ACTIVE
DIRECTIVE INCONSISTENT WITH TASK STATE
TASK ALREADY FIXED/UNFIXED
ISSUING TASK NOT CHECKPOINTABLE
TASK IS CHECKPOINTABLE
RECEIVE BUFFER TOO SMALL
PRIVILEGE VIOLATION
SPECIFIED VECTOR ALREADY IN USE
NO SWAP SPACE AVAILABLE
SPECIFIED VECTOR ILLEGAL

IE.AST
IE.MAP

-80.
-81.

IE. IOP
IE.ALG
IE .WOV
IE.NVR
IE.NVW
IE.ITP
IE. IBS
IE.LNL
IE.IUI

-83.
-84.
-85.
-86.
-87.
-88.

DIRECTIVE ISSUED/NOT ISSUED FROM AST
ISR OR ENABLE/DISABLE INTERRUPT ROUTINE
NOT WITHIN 4K WORDS FROM VALUE OF
BASE ADDRESS & 177700
WINDOW HAS I/O IN PROGRESS
ALIGNMENT ERROR
ADDRESS WINDOW ALLOCATION OVERFLOW
INVALID REGION ID
INVALID ADDRESS WINDOW ID
INVALID TI PARAMETER
INVALID SEND BUFFER SIZE (>255.)
LUN LOCKED IN USE
INVALID UIC

-H9.
-90.
-91.

B-1

STANDARD ERROR CODES
IE.IOU
IE. I TI
IE.PNS
IE.IPR
IE. I LU
IE.IEF
IE .ADP
IE. SOP

-92.
-93.
-94.
-95.
-96.
-97.
-98.
-99.

INVALID DEVICE OR UNIT
INVALID TIME PARAMETERS
PARTITION/REGION NOT IN SYSTEM
INVALID PRIORITY (>250.)
INVALID LUN
INVALID EVENT FLAG NUMBER
PART OF DPB OUT OF USER'S SPACE
DIC OR DPB SIZE INVALID

...

B-2

APPENDIX C

DIRECTIVE IDENTIFICATION CODES

•
Directive Identification Codes
(DICs)
are used
to
identify eact
directive.
The DIC appears in the low byte of the first (or only)
word in the Directive Parameter Block
(DPB).
The DPB length
(in
words)
appears
in the high byte of the first DPB word.
Thus, both
bytes make up the word format shown below:

First Word
In DPB

DPB Length

DIC

(High byte)

(Low byte)

The remainder of this appendix contains a
listing of directives
arranged
in numerical sequence, according to the octal value for the
first DPB word.
In addition, the DIC and DPB lengths are included as
decimal values as they appear in Chapter 6.
This list can be used as a software debugging aid to quickly identify·
directives based on the octal value of the first word in a DPB.
An
example for the SDAT$ directive is provided below,
illustrating the
manner in which the octal value is obtained:

First Word
In DPB

5 ( 10)

71(10)

Octal Byte
Values

5 ( 8)

Binary Word
Value

101

107(8}

000

•
Octal Word
Value

2507

C-1

(=SDAT$}

111

DIRECTIVE IDENTIFICATION CODES

Octal Value For
DPB First word

Directive
(Macro Call)

433
443
455
461
463
537
541
543
545
563
575

CMKT$
DECL$
SPND$S
WSIG$S
EXIT$S
DCSP$
ENCP$S
DSAR$S or IHAR$S
ENAR$S
ASTX$S
GSSW$S
STOP$S

Decimal Values For
DIC
27.
35.
45.
49.
51.
95.
97.
99.
101.
115.
125.

DPB Length
1.
1.
1.
1.
1.
1.
1.
1.
1.
1.
1.

29.
31.
33.
39.
41.
53.
55.
57.
59.
61.
63.
81.
107.
109.
111.
113.
117.
121.
123.
135.

2.
2.
2.
2.
2.
2.
2.
2.
2.
2.
2.
2.
2.
2.
2.
2.
2.
2.
2.
2.

25.
27.
39.
43.
47.
83.
89.
103.
105.
133.
137.

3.
3.
3.
3.
3.

9.
65.
75.
77.

4.
4.
4.
4.

RMAF$
1035
1037
1041
1047
1051
1065
1067
1071
1073
1075
1077
1121
1153
1155
1157
1161
1165
1171
1173
12

STAF$
SRRA$
EXST$
CLEF$
SETF$
ROAF$
WTSE$
EXIF$
CRRG$
ATRG$
DTRG$
GTIM$
GTSK$
RREF$
SRDA$
SPRA$
SFPA$
GMCX$
CRAW$
MAP$
UMAP$
STSE$
-ELVT$
CRGF$
ELGF$
-· STAF$
Sl?EA$
.$REA$

1 05
1431
1433
1447
1453
1457
1523
1531
1547
1551
1605
1611
162
2011
2101
2113
2115

GLUN$
CSRQ$
CMKT$
RDXF$
WTLO$
RSUM$
ABRT$
EXTK$
SVOB$
SVTK$
USTP$
STLO$
CNCT$

.·scAL$S
ALUN$
ALTP$
GPRT$ or GREG$
RCVD$
RCVX$

C-2

DIRECTIVE IDENTIFICATION CODES
Octal Value for
DPB First Word

Directive
(Macro Call)

Decimal Values For
DIC

DPB Length

1.
3.
11.
11.

12.
12.
13.

127 •

C-3

14.
41.

•

APPENDIX D
RSX-11 SYSGEN SELECTION OF EXECUTIVE DIRECTIVES

The following
list contains all
Executive directive macro calls
described-in this manual and means of selection at SYSGEN time~
Those
directives not available for specific RSX-11 systems are noted as N/A.
Directives that are SYSGEN options are noted as o.
The number in
parentheses after the O refers to the SYSGEN options at the end of the
list.
Directives that are standard (not SYSGEN options) are indicated
by an asterisk (*).
Directive
Macro
Call
ABRT~?
ALTP~?
ALUN~?
ASTX~?S

ATRG:?
CINT:S
CLEF:$
CMKT:S
CNCT:S
CRAW$
CRGF:S
CRRG
DECL
DSAR$S or IHAR$S
DSCP$S
DTRG$.
ELAW$
ELGF$
ENAR$S
ENCP$S
EXIF$
EXIT$S
EXST$
EXTK$
GLUN$

GMCR$
GMCX.$
GPR'I'$
GREG$
GSSW$S
GTIM$

System Type
RSX-llS

RSX-llM

* ( 1)
*0 ( 2)
0
0

* ( 1)
*
0 ( 2)

*
*
*

0
0

( 3)
( 1)

RSX-llMl-PLUS

( 3)
( 1)

( 3)

*
*
0 ( 4)

0
0

0
0
0

( 3)
( 5)

N/A

* ( 2)

( 3)
( 5)
( 3)

* ( 2)

0
0
0
0
0

( 7)
( 3)
( 3)
( 5)

N/A

0
0

( 2)
( 7)

*
*N/A

*
*0 ( 4)

N/A
0
0
0

( 3)
( 3)
( 5)

( 2)

( 1)

*N/A

0
0
0
0

( 3)
( 1)
( 3)
( 1)

D-1

( 1)

( 3)
( 1)
( 3)
( 1)

0
0

( 3)
( 3)

*
*
*
0 ( 3)
0

( 3)

*
*
*

*0 ( 4)
*

*
*
0 ( 3)

* ( 3)

0
0

( 1)

RSX-11 SYSGEN SELECTION OF EXECUTIVE DIRECTIVES
System Type

Directive
Macro
Call

RSX-llS

RSX-llM

GTSK$
MAP$
MRKT$
QIO$
QIOW$
RCST$
RCVD$
RCVX$
RDAF$
RDXF$

N/A

0
0

RMAF$s<

N/A

0
0

( 1)
( 3)

0
0

RQS.T$
RREF$
RSUM$
RUN$

*
0

(3)

*
*
*

( 1)

*
*

( 8)
( 8)

( 5)

(4)
(8)
(8)

RSX-UM-PLUS

~.I

* (3)
*
*
*
*
*
*
*

( 8)

*
*

:sc!t$sY
.·:
·soA.T$ . ·

N/A.

··sp~¢$··.•. ·.::···

N/A

( 8)

SETF.$
SFPA$

-'·SPE.1\$:

N/A

* ( 2,

SPND$S
SPRA$
SPWN$
SRDA$

:$.REA.$;· <• ··· · ·

( 2,

( 4)

0 ( 2,
:N/A

SREF$
SRRA$

( 8)

( 2,

··sTA'E\$·: .· · · .::.····:·. '". ·· · · .··.

N/A

STLO$ .
STOP$S
STSE$
SVDB$
sv·rK$
UMAP$
USTP$

0
0
0

*
*

0
0

;·yRCi::)$.. ·

( 4)
( 4)
( 4)

*
*

( 3)
( 4)

( 3)

N/A
N/A

·vRd~$ ..
'/~G*-$
vs'i:'JA}~·
WSIG$S
WTLO$
WTSE$

·~/A

. N/A

*
*
*

*
*

SYSGEN Options

Specific Executive directive support

AST support

Memory management directives

Parent/offspring tasking support

Group-global event flag support

Checkpointing support

D-2

RSX-11 SYSGEN SELECTION OF EXECUTIVE DIRECTIVES
8.

Send/receive by reference directives

11.

Floating point processor support

12.

Powerfail recovery support

D-3

INDEX

Abort AST, 6-137
Abort Task,. 6-7
Aborting a task, 6-7, 6-37
Activating a task, 4-1, 6-105,
6-112, 6-121, 6-131, 6-155
Active task, 1-15
Address,
DPB, l·-2
error routine, 1-7
Address mapping, 3-1, 3-6, 3-7
Address space,
logical, 3-2, 3-4
virtual, 3-2
User-mode, 5-3, 5-4
Supervisor-mode, 5-3, 5-4, 6-117
Address window,
creating, 6-31
eliminating, 6-51
mapping, 6-83
unmapping, 6-153
virtual, 3-2, 3-3, 6-31
A:Ef ini ty, task
CPU/UNIBUS, 5-4, 6-143
removing, 6-104
Alignment boundaries,
offset, 6-31, 6-32
Alter priority, 6-9
Arguments,
integer, 1-11
INTEGER*2, 1-11
optional, 6-5
optional subroutine, 1-10
Array,
integer, 1-11
RDB integer, 3-14
WDB integer, 3-17
Assign I.UN, 6-11
AST, 2-1, 2-4, 2-6
abort, 6-137
floating point processor, 6-124
power recovery, 6-129
receive data, 6-135
receive-by-reference, 6-141
parity error, 6-126
receive data, 6-135
requested exit (abort) , 6-137
AST recognition,
disabling, 6-46
enabling, 6-57
AST service exit, 6-13, 6-14
AST service routine, 2-7
abort, 6-137
cancel mark time, 6-27, 6-28,
6-86, 6-87
floating point processor
exception, 6-124, 6-125

AST service routine (Cont.)
I/O completion, 6-90, 6-92, 6-93
interrupt processing, 6-17 to
6-22
mark time, 6-26, 6-27, 6-86,
6-87
MCR command line, 6-69
offspring task exit, 6-29,
6-121, 6-131
parity error, 6-126
power recovery, 6-129, 6-130
receive-by-reference, 6-141,
6-142
receive data, 6-13~, 6-136
requested exit, 6-137
virtual terminal, 6-39 to 6-42
service routine exit, 6-13,
6-14
Asynchronous System Trap
(AST) I 2-1, 2-4 I 2-6
Attach Region, 6-15
Attaching to region, 3-8, 6-15,
6-36
Attachment descriptor, 3-8

B
Bit definitions, 3-10, 3-13
Block,
Directive Parameter (DPB) ,
1-2, 1-4, 1-6
Group global Event
Flag (GFB), 6-35, 6-53
Region Definition (RDB), 3-10
to 3-14
Window Definition (WDB), 3-10,
3-14 to 3-17
Blocked task, 1-16
Blocking a task, 6-166, 6-168
Blocks, window, 3-2
Boundaries,
offset alignment, 6-31, 6-83
Byte, DPB size, 1-2, C-1

c
$C form, 1-6
CALL ABORT, 6-7
CALL ALTPRI, 6-9
CALL ASNLUN, 6-15
CALL CANALL, 6-44
CALL CANMT, 6-27
CALL CLREF, 6-26
CALL CNCT, 6-29
CALL CRAW, 6-31
CALL CRGF, 6-35
CALL CRRG, 6-36
CALL CRVT, 6-39

Index-!

INDEX
CALL DSASTR, 6-46
CALL DECLAR, 6-45
CALL DISCKP, 6-48
CALL DTRG, · 6-49
CALL ELAW, 6-51
CALL ELGF, 6-53
CALL ELVT, 6-54
CALL EMST, 6-56
CALL ENASTR, 6-57
CALL ENACKP, 6-58
CALL EXITIF, 6-59
CALL EXIT, 6-61
CALL EXST, 6-63
CALL EXTTSK, 6-64
CALL GETLUN, 6-66
CALL GETMCR, 6-69
CALL GETPAR, 6-74
CALL GETREG, 6-76
CALL GETTSK, 6-81
CALL GMCX, 6-71
CALL INASTR, 6-~6
CALL MAP, 6-83
CALL MARK, 6-86
CALL PWRUP, 6-129
CALL QIO, 6-90
CALL RCST, 6-95
CALL REDEF, 6-102
CALL READSW, 6-78
CALL RECEIV, 6-97
CALL RECOEX, 6-99
CALL REQUES, 6-105
CALL RESUME, 6-111
CALL RMAF, 6-104
CALL RREF, 6-108
CALL RUN, 6-112
CALL SEND, 6-119
CALL SETEF, 6-123
CALL SDRC, 6-121
CALL SPAWN, 6-131
CALL SREF, 6-138
CALL STAF, 6-143
CALL STLOR, 6-145
CALL STOP, 6-147
CALL STOPFR, 6-148
CALL SUSPND, 6-128
CALL UNMAP, 6-153
CALL USTP, 6-155
CALL VRCD, 6-156
CALL VRCS, 6-158
CALL VRCX, 6-160
CALL VSDA, 6-162
CALL WAITFR, 6-168
CALL WFLOR, 6-166
CALL WFSNE, 6-164
CALL WTQIO, 6-93
Calls,
macro, 1-5
subroutine, 1-12
Cancel Mark Time Requests, 6-27

Cancel Time Based Initiation
Requests, 6-44
Checkpointing, 6-19
disabling, 6-48
enabling, 6-58
Clear Event Flag, 6-26
Code,
Directive Identification,
(DIC) I 1-2 I C-1
User Identification (UIC),
6-81, 6-106
Cd'des,
error, 1-3
standard error, B-1
Command line, getting
MCR, 6-69
Common event flags, 2-2
Common regions,
static, 3-4
Conditional task
termination,
Conditions,
FORTRAN error, 1-14
Connect, 4-1, 4-2, 6-29
Connect, Send, Request And,
6-121
Connect to Interrupt Vector, 6-17
Console switch registers, 6-78
Conventions,
directive, 6-5
macro name, 1-5
CPU affinity, 5-4
setting, 6-143
removing, 6-104
Create Address Window, 6-31
Create Group Global Event Flags,
6-35
Create Region, 6-36
Create Virtual Terminal, 6-39

D
Data,
receiving, 6-95, 6-97, 6-99
receiving variable length
data, 6-156, 6-158, 6-160
sending, 6-119
sending variable length data,
6-162
Data AST, receive, 6-135
Data structures, user, 3-10
Debugging aid SSTs, 6-149, 6-151
Declare Significant Event, 6-45
Declaring significant event, 6-45,
6-86, 6-119, 6-162
Default UIC, 6-114
Definition Block,
Region (RDB) , 3-10 to 3-14
Window (WDB), 3-10, 3-14 to 3-17

Index-2

• J_

INDEX
Delta time,
schedule, 6-112
Detach Region, 6-49
DIC, 1-2, C-1
DIR$ macro, 1-6, 1-7
Directive categories, 6-1
Directive conventions, 6-5
Directive definition,
system, 1-1
Directive functions,
system, 1-1
Directive Identification Code
(DIC) I 1-2 I C-·l
Directive macros, using, 1-3, 1-4
Directive Parameter Block (DPB),
1-2, 1-4, 1-6
Directive processing,
system, 1-2
Directive restrictions,
Directive selection during
SYSGEN, D-1
nonprivileged task, 1-18
Directive Status Word (DSW), 1-2
Directive summary, system, 6-2,
6-3, 6-4, A-1
Directives,
implementing system, 1-1
memory management, 3-1
Disable AST Recognition, 6-46
Disable Checkpointing, 6-48
Dispatching, Executive-level,
5-5, 5-6
Dormant task, 1-16
DPB, 1-2, 1-4, 1-6
DPB,
creating a, 1-4
predefined, 1-7
DPB address, 1-2, 1-4
DPB pointer, 1-2, 1-4
DPB size byte, 1-2, C-1
DSW, 1-2
DSW values, 1-3
Dynamic regions, 3-4

EFN, 2-2
Eliminate Address Window, 6-51
Eliminate Group Global Event
Flags, 6-53
Eliminate Virtual Terminal, 6-54
Emit Status
EMT, 1-1, 1-2, 1-4
Emu.later trap (EWr), 1-1
Enable AST Recognition, 6-57
Enable Checkpointing, 6-58
Entry points, routine, 2-4
Error codes, standard, 1-3, B-1
Error conditions, FORTRAN, 1-15

Error routine address, 1-7
Error status, 1-3
Event,
declaring significant, 6-45,
6-86, 6-119, 6-162
significant, 2-1, 6-45
waiting for, 6-166, 6-168
stopping for, 6-145, 6-166
Event flag numbers (EFNs), 2-2,
6-5
Event flags, 2-1
common, 2-2
group global, 2-2, 6-34, 6-53,
6-103
local, 2-2
logical OR of, 6-145, 6-166
reading, 6-102, 6-103
setting, 6-123
testing, 2-3
using, 2-2
EX$ERR, 4-2
EX$SEV I 4-2
EX$SUC, 4-2
EX$WAR, 4-3
Examples,
connecting and passing status,
4-4
event flag usage, 2-3
macro call, 1-8
Exit, 6-61
If, 6-59
task, 1-3, 6-59, 6-61
task, with status, 4-1 to 4-4,
6-63
Expansions, macro, 1-9
Extend Task, 6-64
EXTERNAL, 6-129

F
Flag,
clearing event, 6-26
Create Group Global Event,
6-35
Eliminate Group Global Event,
6-53
setting event, 6-123
stopping for event, 6-145, 6-166
waiting for event, 6-166, 6-168
Flag numbers (EFNs),
event, 2-2, 6-5
Flag polarity,
reporting, 6-102, 6-103, 6-123
Flags,
common event, 2-2
event, 2-1
group global, 2-2, 6-35, 6-53,
6-103
local event, 2-2

Index-3

INDEX
Flags (Cont.)
logical OR of event, 6-145,
6-166
reading event, 6-102, 6-103
testing event, 2-3
using event, 2-2
Floating-Point Processor
Exception AST, 6-124
Fork level, 6-17
Form,
$ t 1-6
$C, 1-6
$S, 1-6
Format,
stack, 2-5, 2-7, 2-8
FORTRAN,
error conditions, 1-4
subroutines, 1-9
summary, 1-12
using, 1-10
Functions,
system directive, 1-1

G
General Information Directive,
1-18
Get LUN Information, 6-66
Get Mapping Context, 6-71
Get MCR Command Line, 6-69
Get Partition Parameters, 6-74
Get Region Parameters, 6-76
Get Sense Switches, 6-78
Get Task Parameters, 6-81
Get Time Parameters, 6-79
Getting current time, 6-79
Getting issuing task parameters,
6-81
Getting LUN information, 6-66
Getting mapping context, 6-71
Getting MCR command, 6-69
Getting partition parameters, 6-74
Getting region parameters, 6-76
Getting switch register contents,
6-78
$$GLB, 1-8
Group global event flag, 2-2,
6-35, 6-53, 6-103
Group Global Event Flag Control
Block, 6-35, 6-53
GFB, 6-35, 6-53
GS.DEL, 6-35, 6-53

I/O request,
queuing, 6-90, 6-93
Identification,
region, 3-5
User Code (UIC), 6-81, 6-106
window, 3-2

Identification Code,
Directive (DIC) , 1-2
User (UIC), 6-81, 6-106
Inhibit AST Recognition, 6-46
Installed task,
removing, 1-18
Integer arguments, 1-11
Integer array, 1-11
ROB, 3-14
WDB, 3-17
INTEGER*2 arguments, 1-11
Interrupt Service Routine,
6-17, 6-20
Interrupt Transfer Block, 6-17,
6-20, 6-22
Interrupts,
software, 2-3
Interval,
reschedule, 6-112
time, 6-86 to 6-88
Intervals, time, 6-88
ISA standard call, 6-86, 6-112,
6-115
ISA subroutines, 1-9
ISR, 6-17 I 6-20
ITB, 6-17, 6-20, 6-22

K
KTll memory management unit, 3-1

L
Library,
object module, 1-10
supervisor mode, 3-1, 3-2, 3-3,
5-3, 5-4, 6-117
system macro, 1-5
Local event flags, 2-2
Logical address space, 3-2, 3-4
Logical OR of event flags, 6-145,
b-166

Logical Unit Numbers (LUNs) ,
6-5, 6-11
LUN information, getting, 6-66
LUNs, 6-5
assigning, 6-11

M
Macro call examples, 1-8
Macro calls, 1-5
Macro expansions, 1-8
Macro library,
system, 1-5
Macro name conventions, 1-5
Macros,
using directive, 1-4, 1-5
Magnitude values, 6-86, 6-112
Map Address Window, 6-83

Index-4

INDEX
Mapping,
address, 3-1, 3-6, 3-7
privileged task, 3-18
Mapping contE~xt,
getting, 6·-71
Mark Time, 6·-86
Mark time request,
cancelling, 6-27
Mask word,
Wait for, 2-7
.MCALL directive, 1-5
MCR command,
getting, 6·-69
Memory management
directivE~S, 3-1
Memory-management unit,
K~rll, 3-1
Module library,
object, 1-10
Multiuser task Executive-level
dispatching, 5-5

Parameters (Cont.)
getting region, 6-76
RDB, 3-18
time, 6-79, 6-112
WDB, 3-18
Parent/offspring tasking, 4-1
directive summary, 4-1, 4-2
Parent task, 4-2
receiving status, 4-1, 4-2
Parity error AST, 6-126
Partition parameters,
getting, 6-74
Pointer, DPB, 1-2, 1-4
Power recovery AST, 6-129
Power recovery subroutinei, 6-129
Predefined DPB, 1-7
Priority,
altering task, 6-9
Privileged task mapping, 3-18
Processing,
system directive, 1-2
Processor AST,
floating point, 6-124
Processor Status word (PS) , 1-2
Protection, region, 3-8
Protection UIC, 6-106, 6-114
PS, 1-2

N
Name conventions,
macro, 1-5
Names, task, 1-10
Numbers,
Event Flag (EFNs), 2-2, 6-5
Logical Unit (LUNs), 6-5, 6-11

·'-'.

Object module library, 1-10
Offset alignment boundaries, 6-31,
6-83
Offsets, symbolic, 1-8
Offspring,
emitting status, 4-2, 6-56,
6-63
exit, 4-2
exit with status, 4-2, 6-63
starting, task, 4-1, 4-2
spawn, 6-131
status, task, 4-1
task defined, 4-1
tasking support, 4-1
use of virtual terminals, 4-1,
4-2, 5-2
Optional arguments, 6-5
Optional subroutine arguments,
1-10

p
Packet, send-by-reference, 6-138
Parameters,
getting issuing task, 6-81
getting partition, 6-74

QIO directive, 6-90
Queue,
receive, 6-119
receive-by-reference, 6-108,
6-138
Queue I/O Request, 6-90
Queue I/O Request And Wait, 6-93

R
R.GID, 3-12, 6-15, 6-37, 6-49
R.GNAM, 3-12, 6-15, 6-37
R.GPAR, 3-12, 6-37
R.GPRO, 3-12, 6-37
R.GSIZ, 3-12, 6-16, 6-36
R.GSTS, 3-12, 6-15, 6-37, 6-49
RDB, 3-10
generating an, 3-11, 3-.12
RDB integer array, 3-14
RDB parameters, 3-18
Read All Event Flags, 6-102
Read Extended Event Flags, 6-102
Receive By Reference, 6-108
Receive Data, 6-97
Receive data AST, 6-135
Receive Data Or Exit, 6-99
Receive Data Or Stop, 6-9.5
Receive queue, 6-119
Receive-by-reference AST, 6-141
Receive-by-reference queue, 6-108

Index-5

INDEX
Receiving data, 6-95, 6-97, 6-99
Region,
attaching to, 3-5, 6-15, 6-16
creating, 6-36
detaching from, 6-49
sending reference to, 6-138
Region Definition Block (ROB),
3-10
Region identification, 3-5
Region parameters,
getting, 6-76
Region protection, 3-8
Region reference, 6-138
Region status word (R.GSTS), 3-10,
6-15, 6-37, 6-49
Regions,
dynamic, 3-4
sharable, 3-4
shared, 3-5
static common, 3-4
task, 3-4
Registers,
console switch, 6-78
task, 1-2, 2-6
Remove Affinity, 6-104
Removing installed task, 1-18
Request Task, 6-105
Requesting a task, 6-105, 6-112,
6-121
Requests,
cancelling Mark Time, 6-27
cancelling time-based, 6-44
Reschedule interval, 6-112
Restrictions, nonprivileged
task directive, 1-18
Resuming suspended task, 6-111
Routine,
AST service, 2-7
SST service, 2-4, 6-149, 6-151
Supervisor-mode completion, 5-3,
5-4, 6-117
terminating AST service, 6-13
Routine address,
error, 1-7
Supervisor-mode
completion, 5-3, 5-4, 6-117
Routine entry points, 2-4
RS.ATT, 3-11, 6-36
RS.CRR, 3-11, 6-37
RS.DEL, 3-11, 6-16, 6-37
RS.EXT,
3-11, 6-16, 6-37
RS.MDL, 3-11, 6-37, 6-49
RS.NOL, 3-11, 6-36
RS.NEX, 3-11, 6-37
RS.RED, 3-11, 6-16, 6-37
RS.UNM, 3-11, 6-37, 6-49
RS.WRT, 3-11, 6-16, 6-37
RSX-llM-PLUS, 1-19, 5-1
Run Task, 6-112
Running a task, 6-105, 6-112

s
$S form, 1-6
Schedule delta time, 6-112
Scheduling a task, 6-112
Send By Reference, 6-138
S·end Data, 6-119
Send-by-reference packet, 6-138
Send, Request And Connect, 4-2,
6-121
Sending data, 6-119
Sending variable length data,
6-162
Sending reference to
region, 6-138
Service routine
(see routine)
Set Affinity, 6-143
Set Event Flag, 6-123
Shared regions, 3-5
Significant event, 2-1, 6-164
declaring, 6-45, 6-119, 6-162
Size, extending task, 6-64
Software interrupts, 2-3
Spawn, 4-1, 4-2, 6-131
Spawning tasks, 4-1, 4-2
Specify Floating Point
Processor, 6-124
Specify Parity Error AST, 6-126
Specify Power Recovery AST, 6-129
Specify Receive Data AST, 6-135
Specify Receive-ByReference AST, 6-141
Specify Requested Exit AST, 6-137
Specify S~T Vector Table
For Debugging Aid, 6-149
Specify SST Vector Table For.Task,
6-151
SST, 2-4
SST service routines, 2-4, 6-149,
6-151
SST vector table, 6-149, 6-151
SSTs, 2-4
debugging aid, 6-149
task, 6-151
Stack format, 2-5, 2-8
Standard error codes, B-1
State, task, 1-16
Static common regions, 3-4
Status, error, 1-3
Status, offspring task, 4-1
return to parent task, 4-1 to
4-4
Status Word,
Directive (DSW) , 1-2
Program (PS), 1-2
region (R.GSTS), 3-11
window (W.NSTS), 3-14
STOP, 6-61
Stop, 6-147

Index-·6

~i
!

INDEX
Stop For Logical OR Of Event
Flags, 6-145
Stop For Single Event Flag,
6-148
Stop, Receive Data Or, 6-95
STOP statement message, 6-62
Stopped task state, 1-16
Structures, user data, 3-10
Subroutine arguments,
optional, 1-10
Subroutine calls, 1-11
Subroutines,
PORTRAN, 1-9
ISA, 1-9
summary PORTRAN, 1-12
using FOR~rRAN' 1-10
Summary,
system directive, 6-2, A-1
Summary FOR~rRAN subroutines, 1-12
Supervisor Call, 6-117
Supervisor-mode addressing, 3-1,
3-2
Supervisor-mode completion
routine, 5-3, 5-4, 6-117
Supervisor-mode library routines,
5-3
Suspend, 6-128
Suspended task, resuming, 6-111
Suspending a task, 6-128, 6-164
Switch register,
getting contents of, 6-78
Symbolic offsets, 1-8
Synchronization,
stop-bit, 2-11
Synchronous System Trap (SST),
2-4
SYSGEN, directive selection
during, D-1
System directive definition, 1-1
System directive functions, 1-1
System directive processing, 1-2
System directive summary, 6-2, A-1
System directives, implementing,
1-1
System macro library, 1-5
System Trap, 2-3
Asynchronous (AST), 2-1, 2-4,
2-6
Synchronous (SST) , 2-4

T
1

TABLE,
SST vector, 6-149, 6-151
trap vector, 2-4
Task,
aborting a, 6-7, 6-137
activating a, 6-105, 6-112,
6-121, 6-131, 6-155
active, 1-·16

Task (Cont.)
affinity, 6-104, 6-143
altering priority, 6-9
blocked, 1-16
blocking a, 6-166, 6-168
communication,
directives for, 4-2
connecting to, 4-1 to 4-4
dispatching multiuser, 5-5
dormant, 1-16
ready-to-run, 1-16
removing installed, 1-18
requesting a, 6-105, 6-112,
6-121
resuming suspended, 6-111
rundown count, 6-2 9, 6-·3 9,
6-54, 6-131
running a, 6-105, 6-112
scheduling a, 6-112
spawning a, 4-1, 6-131
states of, 1-16
passing status of, 4-3
stopping a, 2-11, 4-4, 6-145,
6-147, 6-148
suspending a, 6-128, 6-164
synchronization, 2-11
unstopping a, 2-11, 4-4, 6-155
Task CPU/UNIBUS affinity, 5-4
Task execution,
terminating, 6-7, 6-59, 6-61,
6-137
Task Exit, 6-61
conditional, 6-59
Task exits, 1-3
Task mapping,
privileged, 3-18
Task names, 1-10
Task parameters,
getting issuing, 6-81
Task priority,
altering, 6-9
Task regions, 3-4
Task registers, 1-2, 2-6
Task size, extending, 6-64
Task SSTs, 6-151
Task state, 1-16
Task termination,
conditional, 6-59
Terminal UIC, 6-81, 6-105
Terminating task execution, 6-7,
6-59, 6-61, 6-137
Termination,
conditional task, 6-59
Terminator word, 6-71
Testing event flags, 2-3
Time,
getting current, 6-79
Schedule delta, 6-112
Time interval, 6-86 to 6-88
Time intervals, 6-88, 6-112

Inde:1e-7

INDEX

·~.
Time parameters, 6-79, 6-86 to
6-88
Time-based requests,
cancelling, 6-44
Trap,
Asynchronous System (AST),
2-1, 2-4, 2-6
Emulator (EMT) , 1-1
Synchronous (SST) , 2-4
system, 2-3
Trap vector table, 2-5

u
UIC,
default, 6-105, 6-114
protection, 6-106, 6-114
terminal, 6-81, 6-105
UNIBUS run, 5-4
specifying, 6-143
Unmap Address Window, 6-153
Unstop, 6-155
Unstopping tasks, 2-11, 4-4
User data structures, 3-10
User Identification Code (UIC) ,
6-74, 6-105

v
Values,
DSW, 1-3
magnitude, 6-112
Variable Receive Data, 6-156
Variable Receive Data Or Exit,
6-160
Variable Receive Data Or Stop,
6-158
Variable Send Data, 6-162
Vector table,
SST, 6-149, 6-151
trap, 2-4
Virtual address space, 3-2
Virtual addres~ window, 3-2
Virtual terminal, 5-2
creating, 6-39
eliminating, 6-54, 6-60, 6-62,
6-100, 6-131
using, 5-2

w
W.NAPR, 3-15, 6-32, 6-71
W.NBAS, 3-15, 6-33, 6-71
W.NID, 3-15, 6-33, 6-51, 6-71,
6-84, 6-109

W.NLEN, 3-15, 6-31, 6-71, 6-83,
6-109, 6-138, 6-153
W.NOFF, 3-15, 6-31, 6-71, 6-83,
6-109, 6-138, 6-153
W.NRID, 3-15, 6-32, 6-71, 6-84,
6-109, 6-138
W.NSIZ, 3-15, 6-32, 6-71
W.NSRB, 3-15, 6-71, 6-109, 6-139
W.NSTS, 3-14 to 3-16, 6-31, 6-51,
6-71, 6-83, 6-108, 6-138, 6-153
Wait For Logical "OR" Of
Event Flags, 6-166
Wait For Significant Event, 6-164
Wait For Single Event, 6-168
Wait For mask word, 2-7
WDB, 3-8, 3-16
generating a, 3-16, 3-17
WDB integer array, 3-17
WDB parameters, 3-18
Window,
creating address, 6-31
eliminating address, 6-51
mapping address, 6-83
unmapping address, 6-153
virtual address, 3-2, 3-3, 6-31
Window blocks, 3-2
Window Definition Block (WDB) r
3-10, 3-14 to 3-17
Window identification, 3-2
Window status word, (W.NSTS), 3-14
Word,
Directive Status (DSW) , 1-2
Processor Status (PS) , 1-2
region status (R.GSTS), 3-10
Wait For mask, 2-7
window status (W.NSTS), 3-14,
6-32, 6-51, 6-71, 6-83, 6·-108,
6-138 t 6-153
WS.64B, 3-15, 6-31 to 6-33, 6-83
WS.BPS, 3-15, 6-33
W:S.CRW, 3-14, 6-33
WS.DEL, 3-15, 6-33, 6-109
WS.ELW, 3-14, 6-33, 6-51
~S.EXT, 3-15, 6-33, 6-109
WS.MAP, 3-15, 6-32, 6-71, 6-108
WS.NAT, 3-15, 6-33, 6-138
WS.NBP, 3-14, 6-33
WS.RES, 3-15, 6-33
WS.RCX, 3-15, 6-33, 6-108
WS.RED, 3-15, 6-34, 6-109
WS.RRF, 3-14, 6-109
WS.SIS, 3-15, 6-33
WS.UNM, 3-14, 6-33, 6-51, 6-84,
6-153
WS.WRT, 3-15, 6-32, 6-34, 6-71,
6-84, 6-109

Index-8

~t:

,_
j

RSX-llM/M-PLUS
Executive
Re.f erencE~ Manual
AA-H265A--TC
READER'S COMMENTS

NOTE:

•

This form is for document comments only.
DIGITAL will
use comments submitted on this form at the company's
discretion.
If you require a written reply and are
eligible to receive one under Software Performance
Report (SPR) service, submit your comments on an SPR
form .

Did you find this manual understandable, usable, and well-organized?
Please make suggestions for improvement.

''-"

c:
0
0

Did you find errors in this manual?
patge number.

If so, specify the error and the

·~·

Please indicate the type of reader that you most nearly represent.

D Assembly language programmer
D Higher-level language programmer
D Occasional programmer (experienced)

D User with little programming experience

D Student programmer
D Other (please specify) _______________________________,________
Na.me _______________________ Da te ______________
Organization
Street
City

- - - · - - - - - - - - - S t a t e - - - - - - - Zip Code
or
Country

Do Not Tear- Fold Here and Tape
No Postage
Necessary
f M~i led in the
[
United States

111111

BUSINESS FlEPLY MAIL
FIRST CLASS PERMIT N0.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

RT/C SOFTWARE PUBLICATIONS TW/A14
DIGITAL EQUIPMENT CORPORATION
1925 ANDOVER STREET
TEWKSBURY, MASSACHUSETTS

Do Not Tear - Fold Here

-- -

01876