Digital PDFs

ZK-2054-81

November 1981

350 pages

Original

21MB

Document:	RSX-11M/M-PLUS Executive Reference Manual
Order Number:	ZK-2054-81
Revision:	0
Pages:	350
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsx11m_s/RSX11M_V4.1_Apr83/4_ProgramDevelopment/AA-L675A-TC_execRef_198111.pdf

OCR Text

RSX-11 M/M-PLUS
Executive Reference Manual
Order No. AA-L67.5A-TC

RSX-11 M Version 4.0
RSX-11 M-PLUS Version 2.0

digital equipment corporation · maynard, massachusetts

First Printing, May 1979
Revised, November 1981
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 be used or copied only in accordance with the terms of such
license.
No responsibility is assumed for the use or reliability of software on
equipment that is not supplied by DIGITAL or its affiliated companies.

@) 1979, 1981 by Digital Equipment Corporation
All Rights Reserved.

Printed in U.S.A.

The postage-paid 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:

DEC
DEC US
DIGITAL
PDP
UNIBUS
VAX
DECnet

DECsystem-10
DECSYSTEM-20
DECwriter
DIBOL
Edusystem
IAS
MASSBUS

PDT
RSTS
RSX
VMS

ZK-2054-81

CONTENTS

Page
PREFACE

SUMMARY OF TECHNICAL CHANGES

USING SYSTEM DIRECTIVES

CHAPTER 1

INTRODUCTION • • • • • • • • •
1.1
DIRECTIVE PROCESSING •
1. 2
ERROR RETURNS
• • • •
1. 3
USING THE DIRECTIVE MACROS •
1. 4
Macro Name Conventions • •
1. 4.1
$ Form • • •
1.4.1.1
. . . .
$C Form
1.4.1.2
$S Form
1.4.1.3
DIR$ Macro •
1. 4. 2
Optional Error Routine Address •
1. 4. 3
Symbolic Offsets • • •
1. 4. 4
Examples of Macro Calls
1.4.5
FORTRAN SUBROUTINES • • • • • • • •
1. 5
Subroutine Usage • •
1. 5.1
Optional Arguments •
• • • •
1.5.1.l
Task Names • • • • • • • • • •
1.5.1.2
Integer Arguments
• • • • • • • •
1.5.1.3
GETADR Subroutine
• • • • • • • • •
1.5.1.4
The Subroutine Calls
• • • • • •
1. 5. 2
Error Conditions • • •
1. 5 .. 3
AST Service Routines • • • • •
1. 5. 4
TASK STATES • • • • • •
1.6
1. 6.1
Task State Transitions • • •
Removing an Installed Task
1. 6. 2
THE GENERAL INFORMATION DIRECTIVE
•
1. 7
DIRECTIVE RESTRICTIONS FOR NONPRIVILEGED
1. 8
RSX-llM-PLUS • • • • • • • • • • • • • •
1. 9
CHAPTER 2

1-1

• • 1-2
. • • • . 1-3
• 1-4
• • • 1-5
. . . . . 1-5
. . • • • 1-6
• 1-6
• • 1-6
• 1-7
• 1-7
1-8
. • . • . 1-9
• 1-9
• • • • 1-10
• • • • 1-10
1-11
• • • • 1-11
1-11
1-16
1-16
1-17
• •••
1-18
• • • • 1-20
• • • • 1-20
TASKS • 1-20
• • • • 1-21

SIGNIFICANT EVENTS, SYSTEM TRAPS, AND STOP-BIT
SYNCHRONIZATION

2.1
2.2
2.3
2.3.1
2.3.2
2.3.3
"I

.c. • ..) • "%

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 • • • • •

iii

•
• •
•
•
• •
•

2-1
2-2
2-4
2-4
2-5
2-6

• 2-7
2-11

CONTENTS
Page
CHAPTER 3

MEMORY MANAGEMENT DIRECTIVES

ADDRESSING CAPABILITIES OF AN RSX-llM TASK •
• 3-1
3.1
Address Mapping
• • • • • • • • •
• 3-2
3.1.1
3.1. 2
Virtual and Logical Address Space
• • • • • • • 3-2
Supervisor-Mode Addressing • • • •
• 3-2
3 .1. 3
3e 1. 4
Mapping Structure of I- and D-Space Tasks
• 3-3
3.2
VIRTUAL ADDRESS WINDOWS
• • • • • • • • • • • • • 3-3
3.3
REGIONS
• • • • • • • •
• • • 3-5
3.3.1
Shared Regions • • • • • • • • • • • • •
• • 3-6
3.3.2
Attaching to Regions • • • • • • • • • • • • • • 3-6
Region Protection
• • • • • • • • • • • • • 3-9
3.3.3
DIRECTIVE SUMMARY
• • • • • . • • • • • • • 3-9
3.4
Create Region Directive (CRRG$)
3-10
3.4.1
3.4.2
Attach Region Directive (ATRG$)
• • • •
3-10
Detach Region Directive (DTRG$)
• • • • •
3-10
3.4.3
Create Address Window Directive (CRAW$)
3-10
3.4.4
Eliminate Address Window Directive (ELAW$)
3-10
3.4.5
Map Address Window Directive (MAP$)
3-10
3.4.6
Unmap Address Window Directive (UMAP$)
3-10
3.4.7
Send By Reference Directive (SREF$)
3-10
3.4.8
Receive By Reference Directive (RREF$)
3-11
3.4.9
Get Mapping Context Directive (GMCX$)
• • • •
3-11
3.4.10
Get Region Parameters Directive (GREG$)
3-11
3.4.11
USER DATA STRUCTURES • • • • • • • • • • • • • •
3-11
3.5
Region Definition Block (RDB)
3-12
3.5.1
Using Macros to Generate an RDB
• • • •
3-13
3.5.1.1
Using FORTRAN to Generate an RDB
3-15
3.5.1.2
Window Definition Block (WDB)
• • • •
3-15
3.5.2
Using Macros to Generate a WDB • • •
3-17
3.5.2.1
Using FORTRAN to Generate a WDB
• • • • • •
3-19
3.5.2.2
Assigned Values or Settings
3-20
3.5.3
PRIVILEGED TASKS • • • • • • • • • • •
3-20
3.6
CHAPTER 4

PARENT/OFFSPRING TASKING

PARENT/OFFSPRING TASKING SUPPORT OVERVIEW
4.1
DIRECTIVE SUMMARY
• • • • • • • •
4.2
•
Parent/Offspring Tasking Directives
4.2.1
Task Communication Directives
•••••
4.2.2
CONNECTING AND PASSING STATUS
• • • • •
4.3
SPAWNING SYSTEM TASKS
• • • • • • • • •
4.4
Spawning a Command Line Interpreter
4.4.1
Spawning a Utility • • • • • • • • •
4.4.2
Spawning a Utility under RSX-llM • •
4.4.2.1
•
Spawning a Utility under RSX-llM-PLUS
• •
4.4.2.2
Passing Command Lines to Utilities • •
4.4.2.3
CHAPTER 5
5.1
5.1.1
5.1. 2
5.1. 3
5.1.4
5.1. 5
5.1. 6
5.1.7
5.1. 8
5.1. 9

• • 4-1
• • 4-1
• 4-1
4-2
4-3
• • 4-5
4-5
• • 4-5
• • 4-5
• • 4-6
• 4-6

DIRECTIVE DESCRIPTIONS
• •
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/Offspring Tasking Directives
RSX-llM-PLUS Directives
•.••••.
iv

• •
•
• •
•
•
• •

•
•
•
•
•
•

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

• • • 5-3

5-3
• • • 5-4
• • 5-4

CONTENTS
Page
5 .1.10
5.2
5.3
5.3.1
5.3.2
5.3.3
5.3.4
5.3.5
5.3.6
5.3.7
5.3.8
5.3.9
5.3.10
5.3.ll
5.3.12
5.3.13
5.3.14
5.3.15
5.3.16
5.3.17
5.3.18
5.3.19
5.3.20
5.3.21
5.3.22
5.3.23
5.3.24
5.3.25
5.3.26
5.3.27
5.3.28
5.3.29
5.3.30
5.3.31
5.3.32
5.3.33
5.3.34
5.3.35
5.3.36
5.3.37
5.3.38
5.3.39
5.3.40
5.3.41
5.3.42
5.3.43
5.3.44
5.3.45
5.3.46
5.3.47
5.3.48
5.3.49
5.3.50
5.3.51
5 .. 3 .. 52
5.3.53
5.3.54
5.3.55
5.3.56
5.3.57
5.3.58
5.3.59

CLI Support Directives • • • • • • • •
• • 5-5
DIRECTIVE CONVENTIONS • • • • • •
• • • • • • 5-5
SYSTEM DIRECTIVE DESCRIPTIONS
• • • 5-6
Abort Task • •
• • • •
• 5-8
Alter Priority •
• • • • •
5-10
Assign LUN • • •
• • • •
• • • • • 5-12
AST Service Exit ($S form recommended) • • • • 5-14
Attach Region
• • • •
5-16
Connect to Interrupt Vector
5-18
Clear Event Flag • • • • • • •
• • • •
5-28
Cancel Mark Time Requests
5-29
Connect • • • • • • • • • • • •
5-31
Checkpoint Common Region •
5-34
Create Address Window
5-36
Create Group Global Event Flags
• • • • 5-40
Create Region • • • • • • • • •
• • • • 5-42
Create Virtual Terminal
• • • • • • •
5-45
Cancel Time Based Initiation Requests
• •
5-51
Declare Significant Event {$S Form Recommended) 5-52
Disable (or Inhibit) AST Recognition ($S Form
Recommended) • • • • • • • • • • • • • • • • • 5-53
Disable Checkpointing ($S Form Recommended)
5-55
Detach Region • • • • • • • • • • • • • • • • 5-56
Eliminate Address Window • •
• • • •
5-58
Eliminate Group Global Event Flags •
5-60
Eliminate Virtual Terminal •
5-62
Emit Status • • • • • • • • • • • •
5-64
Enable AST Recognition ($S Form Recommended) • 5-65
Enable Checkpointing ($S Form Recommended)
5-66
Exit If
• • • • • • • • • • • • • • • • •
5-67
Task Exit ($S Form Recommended)
5-69
Exit With Status • • • • • • • • •
5-71
Extend Task • • • • • • • • • • • •
5-73
Get Command for Command Interpreter
5-75
Get Command Interpreter Information • • • • • 5-79
Get LUN Information
• • • • • • •
5-81
Get MCR Command Line • •
• • • •
5-84
Get Mapping Context
• • • • • • • • 5-86
Get Partition Parameters • •
5-89
Get Region Parameters
5-91
Get Sense Switches ($S Form Recommended)
5-93
Get Time Parameters
5-95
Get Task Parameters
• • • •
• • • • 5-97
Map Address Window • • • • • • • • • • • • • • 5-100
Mark Time • • • • •
• • • • • • 5-103
Map Supervisor D-Space
• 5-107
Move To/From User/Supervisor I/D-Space • • • • 5-110
Queue I/O Request • • • • •
• • • • • • 5-112
Queue I/O Request and Wait •
• • • 5-116
Receive Data Or Stop •
• • • • • • • 5-118
Receive Data • • • •
• • • • • • • • 5-120
Receive Data Or Exit •
• • • • • 5-122
Read All Event Flags • • • • • • •
• 5-125
Read Event Flag
• • • • • • • • • • • • • 5-126
Read Extended Event Flags • • • • • • • • • • 5-127
Remove Affinity ($8 Form Recommended)
........ 5-128
Request and Pass Offspring Information •
• 5-129
Request Task • • • • • • • • • • • • • • • • • 5-133
Receive By Reference • • • •
• • 5-136
Resume Task • • • • • • • • •
5-139
Run Task • • • • • • • • • • • • • • • • • • • 5-140
Specify Command Arrival AST • • • • •
• 5-145
Supervisor Call ($S Form Recommended)
• 5-146
v

CONTENTS
Page
5.3.60
5.3.61
5.3.62
5.3.63
5.3.64
5.3.65
5.3.66
5.3.67
5.3.68
5.3.69
5.3.70
5.3.71
5.3.72
5.3.73
5.3.74
5.3.75
5.3.76
5.3.77
5.3.78
5.3.79
5.3.80
5.3.81
5.3.82
5.3.83
5.3.84
5.3.85
5.3.86
5.3.87
5.3.88
5.3.89
5.3.90
5.3.91
5.3.92
5.3.93

Set Command Line Interpreter • • • • •
• 5-148
Send Data
• • • • • • • • • • • • •
5-150
Send, Request and Connect • • • • • •
• 5-152
Send Data Request and Pass Offspring Control
Block • • • • •
• • • • • 5-155
Set Event Flag • • • •
• • • • • 5-159
Specify Floating Point Processor Exception AST 5-160
Send Message • • • • • • • • • • • • • •
• 5-162
Send Next Command
• • • • • • •
• • 5-165
Specify Parity Error AST • • •
• • 5-167
Suspend ( $S Form Recommended)
• • • •
• 5-169
Specify Power Recovery AST • • • • • •
5-170
Spawn
• • • • • • • • • •
• • • •
5-172
Specify Receive Data AST • • • • •
• • • 5-182
Specify Requested Exit AST Directive - SREA$
or SREX$ • • • • • • • • •
• • • •
• 5-184
Send by Reference
• • • • •
• 5-188
Specify Receive-by-Reference AST •
• 5-191
Set Affinity • • • • • • • •
• 5-193
Set System Time Directive • • . •
• 5-195
Stop For Logical OR Of Event Flags •
• 5-198
Stop ($S Form Recommended) •
• 5-200
Stop For Single Event Flag •
• 5-201
Specify SST Vector Table For Debugging Aid • • 5-202
Specify SST Vector Table For Task
• 5-204
Unlock Group Global Event Flags ($S Form
Recommended) • • • •
• ••••
• 5-206
Unmap Address Window • •
• 5-207
Unstop Task
• • • • •
• 5-209
Variable Receive Data
• • • •
• 5-210
Variable Receive Data Or Stop
• • 5-212
Variable Receive Data Or Exit
••••
• 5-214
Variable Send Data • • • •
• • • • • 5-216
Variable Send, Request and Connect
• 5-218
Wait For Significant Event ($S Form
Recommended) • • • • • • • .
5-221
Wait For Logical OR Of Event Flags • • •
• 5-223
Wait For Single Event Flag •
• 5-225

APPENDIX A

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL

APPENDIX B

STANDARD ERROR CODES

APPENDIX C

DIRECTIVE IDENTIFICATION CODES

APPENDIX D

RSX-11 SYSGEN SELECTION OF EXECUTIVE DIRECTIVES

INDEX

CONTENTS
Page
FIGURES
FIGURE

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

Directive Parameter Block (DPB) Pointer on the
Stack
• • • • • • • • • • • • • •
• • • 1-4
Directive Parameter Block {DPB) on the Stack
• 1-4
Virtual Address Windows
• • 3-5
Region Definition Block
• • • • • • • • •
• 3-7
Mapping Windows to Regions
• • • • • • • • • • 3-8
Region Definition Block
• • • • • • • • •
3-13
Window Definition Block
• • • •
3-17

TABLES
TABLE

1-1

FORTRAN Subroutines and Corresponding Macro Calls 1-12

vii

PREFACE

MANUAL OBJECTIVES
The RSX-llM/M-PLUS Executive Reference Manual describes the system
a1rec~1ves
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 4 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
programmer.

STRUCTURE OF THIS DOCUMENT
A Summary Of Technical Changes provides the experienced RSX-llM
/RSX-llM-PLUS 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
directives.
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 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.

PREFACE
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 same octal values that they have 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-llS,
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:
the RSX-llM/M-PLUS Task Builder Manual and the
PDP-11 MACR0-11 Language Reference Manual, the IAS/RSX-11 FORTRAN IV
User's Guide, or the FORTRAN-77 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 portions of text that apply to
RSX-llM-PLUS only are indicated by background shading on the printed
page.

SUMMARY OF TECHNICAL CHANGES

This revision of the RSX-llM/M-PLUS Executive Reference
Manual
contains
changes
and
additions
to
document
two
operating
systems: RSX-llM V4.0 and RSX-llM-PLUS V2.0.
The following new directives have
RSX-llM-PLUS:

been

added

both

RSX-llM

and

Request and Pass Offspring Information
Send, Request and Pass Offspring Control Block
Set System Time
Unlock Group Global Event Flags
The following directives that were formerly specific
are now common to both operating systems:

RSX-llM-PLUS

Send, Request and Connect
Specify Requested Exit AST

There are also four new directives that support alternate Command Line
Interpreters.
These CLI support directives are common to both
operating systems:
Get Command for Command Line Interpreter
Get Command Interpreter Information
Set Command Line Interpreter
Specify Command Arrival AST
The description of the Spawn directive now includes an example that
shows how to use parent/offspring tasking to provide AST service
routines in FORTRAN.
Guidelines for coding FORTRAN AST service
routines are included in Chapter 1.

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. You use the directives to
control the execution and interaction of tasks.
If you are a MACR0-11
programmer, you usually issue directives in the form of macros defined
in the system macro library.
If you are a FORTRAN programmer,
issue
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

•

Spawn other tasks

•

Communicate and synchronize with other tasks

•

Manipulate a task's logical and virtual address space

•

Suspend and resume execution

•

Exit

Directives are implemented by 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.
If you are a MACR0-11 programmer, use the system directive macros
supplied in the system macro library for directive calls, rather than
hand-coding calls to directives. Then you need only reassemble the
program to incorporate any changes in the directive specifications.
Sections 1.2, 1.3, and 1.6 are intended for all users.
Section 1.4
specifically describes the use of macros, while Section 1.5 describes
1-1

USING SYSTEM DIRECTIVES
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) or FORTRAN subroutine.

The Executive processes the directive.

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

Note that the Executive preserves
issues a directive.

all

task

information

registers

when

directive

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 an odd-numbered value.
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 an Asynchronous System Trap
(AST)
exit.
The Executive also clears or sets the Carry bit in the Processor
Status Word
{PSW) 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$,
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

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 incompatibilities with future RSX-llM releases.
1-2

USING SYSTEM DIRECTIVES
Section 1.3).
(The Instrument Society of America (ISA) FORTRAN calls
CALL START and CALL WAIT are exceptions, since ISA requires positive
numeric error codes. See Sections 5.3.57 and 5.3.41 for details; the
specific 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:
•

Detaches all attached devices

•

Flushes the AST queue and despecifies all specified ASTs

•

Flushes the receive and receive-by-reference queues

•

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

•

Deaccesses the group global event flags for the task's group

•

Disconnects from interrupts

•

Flushes all outstanding CLI command buffers for the task

•

Breaks the connection with any offspring tasks

•

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

fixed

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.
You should always 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
5 contains
directive-related interpretations of the error codes.

1-3

addition,
specific,

USING SYSTEM DIRECTIVES
1.4

USING THE DIRECTIVE MACROS

If you are programming in MACR0-11, you must decide how to create the
DPB before you issue a directive. The DPB may either be created on
the stack at run time (see Section 1.4.1.3, which describes the $S
form, of directive) or 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).
If parameters vary and the code must be reentrant, the
DPB must be created on the stack.
Figures 1-1 and 1-2 illustrate the alternative directives and
show the relationship between the stack pointer and the DPB.

# ADDR,-(SP)
377

MOV
EMT

DPB

DPB
ITEMS
SP----

also

ADDRESS OF DPB

SIZE

DIC

INCREASING
MEMORY
ADDRESSES

STACK
GROWTH

l
ZK-305-81

Figure 1-1

Directive Parameter Block (DPB) Pointer on the Stack

MOV

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

MOV
.BYTE
EMT

(PC)+,-(SP)
D!C,SIZE
377

SP----

DPB
ITEMS
SIZE

STACK
GROWTH

DIC

INCREASING
MEMORY

I ADDRESSES

l
ZK-306-81

Figure 1-2

Directive Parameter Block (DPB) on the Stack
1-4

USING SYSTEM DIRECTIVES
1.4.1

Macro Name Conventions

When you are programming in MACR0-11, you use system directives by
including directive macro calls in your programs~ The macros for the
RSX-llM directives are contained in the System
Macro
Library
(LB: [l,l]RSXMAC.SML).
The
.MCALL assembler directive makes these
macros available to a program. 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.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. The $ form is most useful when the
directive is issued several times with varying parameters (one or more
but not all parameters change), or in a reentrant program section when
a directive is issued several times even though the DPB is not
modified.
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).
You can
alter individual parameters in the DPB.
You might do this if you want
to use the directive many times with varying parameters.

1-5

USING SYSTEM DIRECTIVES
1.4.1.2 $C Form - Use the $C form when a directive is to be issued
only once.
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 new value of the assembler's location counter redefines the DPB
address $$$ 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, you 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 .RAD50).
(This
is not true for the p-section argument and the error routine argument,
which are not part of the DPB.)

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 you should not use the Stack
Pointer (or any reference to the Stack Pointer) to address directive
parameters when the $S form is used.2
(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.)
Note that in the $S form of
processed from right to left.

the macro, the macro arguments are
Therefore, when using code of the form:

MACRO$S,,(R4)+, (R4)+
the result may be obscure.

1.4.2

DIR$ Macro

The DIR$ macro allows you 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.

1. Refer to the PDP-11 MACR0-11 Language Reference
description of p-sections (program sections).

Manual

for

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

USING SYSTEM DIRECTIVES
The DIR$ macro generates an RSX-llM Executive trap using a
DPB:
Macro Call:

DIR$

predefined

adr,err

adr and err are optional
adr
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
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

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.

1.4.4

Symbolic Offsets

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
offset of a given DPB element.
Because
modify
offsets
release

the offsets are defined symbolically, you can refer to or
DPB elements without knowing
the offset values.
Symbolic
also eliminate the need to
rewrite programs if a
future
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.

1-7

USING SYSTEM DIRECTIVES
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 using symbolic offsets, you should use the $ form of directives.

1.4.5

Examples of Macro Calls

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.,5
1
5
2
MTRAP

"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

the

1,5,2,MTRAP,PROGl,ERR

generates the following code:
• PSECT
$$$=.
.BYTE
.WORD
.WORD
.WORD
.WORD
• PSECT
MOV
EMT
BCC
JSR
3.

$DPB$$
23., 5
1

5
2

MTRAP
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~
MRKT$S #l,#5,#2,R2,ERR
generates the following code:
MOV
MOV
MOV

MOV
MOV
.BYTE
EMT
BCC
JSR

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

1-8

USING SYSTEM DIRECTIVES
4.

The DIR$ macro issues a directive that has a predefined DPB.
DIR$

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 5 describe
subroutine calls, as well as the macro calls.

subroutines
the

FORTRAN

The FORTRAN subroutines fall into three basic groups:
•

Subroutines based on the Instrument Society of America
(ISA)
Standard ISA 62.1
These subroutines are included in the
subroutine descriptions associated with the macro calls
(see
Chapter 5).

•

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

•

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.

1.5.1

Subroutine Usage

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.
You call these subroutines by including 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 librarye
If the subroutine is found, it is included in
the linked task.

1-9

USING SYSTEM DIRECTIVES
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, you may omit the arguments BB, CC, EE, and FF in one of
the following ways:
e

CALL SUB (AA,,,DD,,)

CALL SUB (AA,,,DD)

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 5.

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 0 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.)
--FORTRAN subroutine calls require that a task name be defined as a
2-word variable or array that contains the task name as Radix-50 code.
This variable may be any of the following:
•

REAL

INTEGER*4

•

An INTEGER*2 array of 2 elements

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
call, the task name could be defined and used as follows:

directive

DATA CCMF1/5RCCMF1/

CALL REQUES (CCMFl)
A program may define task names 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-10

USING SYSTEM DIRECTIVES
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 you specify the /I4
option switch when compiling a program, ensure that all integer array
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
that are the addresses of other variables or arrays.
Since the
FORTRAN language does not provide a means of assigning such an address
as a value, you must use the GETADR subroutine described below.
Calling Sequence:
CALL GETADR(ipm,[argl],[arg2], ••• [argn])
ipm
An array of dimension n.
argl, ••• argn
Arguments whose addresses are to be inserted in ipm.
Arguments
are inserted in the order specified.
If a null argument is
specified, then the corresponding entry in ipm is left unchanged.
When the argument is an array name, the address of the first
array element is inserted into ipm.
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)

In this example, CALL GETADR enables you to specify a
in the CALL QIO directive (see Section 5.3.44).

1.5.2

buffer

address

The Subroutine Calls

Table 1-1 is a list of the FORTRAN subroutine calls (and corresponding
macro calls)
associated with system directives (see Chapter 5 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$]).

1-11

USING SYSTEM DIRECTIVES

Table 1-1
FORTRAN Subroutines and Corresponding Macro Calls
Directive

Macro Call

FORTRAN Subroutine

Abort Task

ABRT$

CALL ABORT

Alter Priority

ALTP$

CALL ALT PR I

Assign LUN

ALUN$

CALL ASNLUN

Attach Reg ion

ATRG$

CALL ATRG

Cancel Time Based
Initiation Requests

CRSQ$

CALL CANA LL

Cancel Mark
Time Requests

CMKT$

CALL CANMT

Clear Event Flag

CLEF$

CALL CLREF

Connect

CNCT$

CALL CNCT

Create Address Window

CRAW$

CALL CRAW

Create Group Global
Event Flags

CRGF$

CALL CRGF

Create Reg ion

CRRG$

CALL CRRG

Create Virtual 'I'e;r11,1fnal

.i:C;RVT$

CALL. CRVT

Declare Significant Event

DECL$S

CALL DECLAR

Disable AST Recognition

DSAR$S

CALL DSASTR

Disable Checkpointing

DSCP$S

CALL DISC KP

Detach Region

DTRG$

CALL DTRG

Eliminate Address Window

ELAW$

CALL ELAW

Eliminate Group Global
Event Flags

ELGF$

CALL ELGF

Eliminat~

ELVT$

CALL ELVT

Emit Status

EMST$

CALL EMST

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 Task

EXTK$

CALL EXTTSK

Get Command for
Command Interpreter

GCCI$

CALL GTCMCI

Virtual Terminal

(continued on next page)

1-12

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

Macro Call

Get Command
Interpreter Information

GCII$

CALL GETCII

Get LUN Information

GLUN$

CALL GETLUN

Get Mapping Context

GMCX$

Get MCR Command Line

GMCR$

CALL GETMCR

Get Partition Parameters

GPRT$

CALL GET PAR

Get Region Parameters

GREG$

CALL GETREG

Get Sense Switches

GSSW$S

CALL READSW
CALL SSWTCH

Get Task Parameters

GTSK$

CALL GETTSK

Get Time Parameters

GTIM$

CALL GETTIM

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$

FORTRAN Subroutine

CALL GMCX

RDXF$

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

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 and Pass Offspring
Information

RPOI$

CALL RPOI
(continued on next page)

1-13

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

Macro Call

FORTRAN Subroutine

Request

RQST$

CALL REQUES

Resume

RSUM$

CALL RESUME

Run

RUN$

CALL RUN
CALL START (ISA
Standard
call)

Send By Reference

SREF$

CALL SREF

Send Data

SDAT$

CALL SEND

Send Message

SMSG$

CALL SMSG

Send Next Command

SNXC$

CALL SNXC

Send, Request And Connect

SDRC$

CALL SDRC

Set Command Line Interpreter

SCLI$

CALL SCLI

Send Data Request and Pass OCB

SDRP$

CALL SDRP

Set Event Flag

SETF$

CALL SETEF

Set System Time

STIM$

CALL SETTIM

Spawn

SPWN$

CALL SPAWN

Specify Power Recovery AST

SFPA$

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

Specify Requested Exit AST

SREA$
SREX$

CALL SREA
CALL SREX

Stop

STOP$S

CALL STOP

STLO$

CALL STLOR

Stop For Single Event .Flag

STSE$

CALL STOPFR

Suspend

SPND$S

CALL SUSPND

Task Exit

EXIT$S

CALL EXIT

Unlock Group Global Event
Flags

ULGF$S

CALL ULGF

Unmap Address Window

UMAP$

CALL UNMAP

Stop For Logical OR Of
, Event Flags

,,...,..'t"'\.f-;,..,,,,,..__,:J

\'-VU ... .i..uucu

1-14

--.., .. ~
HCA I,..

____ ,

tJO~

c J

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

Macro Call

FORTRAN Subroutine

Unstop

USTP$

CALL USTP

Wait For Single Event Flag

WTSE$

CALL WAITFR

Wait For Logical OR Of
Event Flags

WTLO$

CALL WFLOR

Wait For Significant Event

WSIG$S

CALL WFSNE

NOTE
The
following
directives
are
available as FORTRAN subroutines:
Directive

not

Macro Call

AST Service Exit

ASTX$S

Connect To Interrupt Vector

CINT$

Specify Command Arrival AST

SCAA$

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$

1-15

USING SYSTEM DIRECTIVES
1.5.3

Error Conditions

Each subroutine call includes an optional argument that specifies the
integer to receive the Directive Status Word (ids). When you specify
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 5.3.41 and 5.3.57).
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 are:

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

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

1.5.4

AST Service Routines

The following FORTRAN callable routines provide support
FORTRAN programs:
e

CALL CNCT

CALL CRVT

CALL PWRUP

CALL SDRC

CALL SPAWN

CALL SREA

CALL SREX

Use great
following
state:
e

caution when coding an AST
types of FORTRAN operations

for

ASTs

routine in FORTRAN.
The
may not be performed at AST

FORTRAN I/O of any kind
(including
statements and internal file I/O)

ENCODE

and

DECODE

FORTRAN I/O is not reentrant, therefore the information
the impure data area may be destroyed.
•

Floating-point operations
The floating-point processor's context is not saved while
in
AST state.
Since the scientific subroutines use
floating-point operations, they may not be called at AST
state.

1-16

USING SYSTEM DIRECTIVES
•

Traceback information in the generated code
Use of traceback corrupts the error recovery in the FORTRAN
run time library. Any FORTRAN modules that will be called
at AST state must be compiled without traceback.
See the
FORTRAN IV or FORTRAN-77 User's Guide for more information.

•

Virtual array operations
Use of virtual arrays at AST state remaps the current array
such that any operations at non-AST state will not be
executed correctly.

•

Subprograms may not be
normal task processing.

shared

between

•

EXIT or STOP statements with files open

AST

processing

and

FORTRAN flushes the task's buffers, which could be in an
intermediate state.
Therefore, data might be lost if any
output files are open when the EXIT or STOP is executed.
You can EXIT or STOP at AST state if no
open.

output

files

are

Since the message put out by STOP uses a different
mechanism from the normal FORTRAN I/O routines, the act of
putting out this message does not corrupt impure data in
the run time system.
Therefore, you can issue a STOP
statement at AST state unless there are output files open.
Note also the following:

1.6

•

Any execution
program.

time

error

AST

state

will

corrupt

the

•

Use extreme care if the FORTRAN task is overlayed.
Both the
interface routine and the actual code of the FORTRAN AST
routine must be located in the root segment.
Any routines
that are called at AST state must also be in the root segment.

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 only 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 eithe-r~dormant or
active. These states are defined as follows:
•

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.

1-17

USING SYSTEM DIRECTIVES
•

Active -- A task is active from the time it is requested until
the time it exits. ~~questing a task means issuing the RQST$,
RUN$, SPWN$, SDRC$, VSRC$, RPO!$, or SDRP$ 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:

1.6.1

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.

Blocked -- A blocked task is unable to compete for CPU
time for synchronization reasons or because a needed
resource is not available.
Task priority effectively
remains unchanged, allowing the task to compete for memory
space.

Stopped -- A stopped task is unable to compete for CPU
time because of pending I/O 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.

Task State Transitions

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

A RUN$ directive

•

A RQST$ directive

•

A SPWN$ directive

•

A SDRC$ directive

•

A RPOI$ directive

•

A SDRP$ directive

•

An MCR or DCL Run command

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

directives

events

cause

•

A SPND$ directive

•

An unsatisfied Wait For condition

•

Checkpointing of a task out of memory by the Executive

1-18

the

active,

USING SYSTEM DIRECTIVES
Ready-to-Run to Stopped
The following
ready-to-run task to become stopped:
•

events

cause

active,

S':['OP$S directive is executed, or an RCST$, SDRP$, GCCI$,

VRCS$ directive is issued when no data packet is available.

•

An unsatisfied Stop For condition.

•

An unsatisfied Wait For
outstanding buffered r;o.l

condition

while

the

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

task

has

blocked

task

•

A RSUM$ directive issued by another task

•

A Wait For condition is satisfied

•

The Executive reads a checkpointed task into memory

MCR Resume command or a DCL Continue command

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:
•

A task stopped by the STOP$, RCST$, {g'.f;{HWP~,\~: di rec ti ve becomes
unstopped by USTP$ directive execution, or an MCR Unstop
command or DCL START command.

•

A Wait For condition is satisified for a task with outstanding
buffered I/O.

•

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

Active to Dormant - The following
become dormant:

events

cause

active

•

An EXIT$S, EXIF$, RCVX$, ?qi~,'.'j,'.'.~~~~-;\- directive,
or
GCCI$ directive that speciflei th~ exit option

•

An ABRT$ directive

•

An MCR or DCL Abort command

•

A Synchronous System Trap (SST)
specified a service routine

for

which

task

RREF$

task

has

not

Blocked to Stopped - The following event causes a task that is blocked
due to an unsatisfied Wait For condition to become stopped:
•

The task initiates buffered I/O at AST state
from AST state.

and

then

exits

1. Only in systems that support the checkpointing of tasks during
buffered I/O.
An I/O request can be buffered only when the task is
checkpointable and the region that I/O is being done to/from is
checkpointable.
1-19

USING SYSTEM DIRECTIVES
Stopped to Blocked - The following event causes a task that is stopped
due to an unsatisfied Wait For condition and outstanding buffered I/O
to return to a blocked state:
•

1.6.2

Completion of all outstanding buffered I/O

Removing an Installed Task

You remove an installed task from the system by issuing the MCR or DCL
Remove
command
from
a
privileged
terminal.
Refer to the
RSX-llM/llM-PLUS MCR Operations Manual or the RSX-llM/M-PLUS Command
Language Reference Manual.

1.8

DIRECTIVE RESTRICTIONS FOR NONPRIVILEGED TASKS

Nonprivileged tasks cannot issue certain Executive directives,
as listed below:
Directive

except

Macro Call

Comments

Abort Task

ABRT$

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

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.

1-20

USING SYSTEM DIRECTIVES
Directive

Macro Call

Comments

Connect To interrupt
Vector

CINT$

Cannot
be
issued
by a
nonprivileged task in mapped
systems.

Set Command Line
Interpreter

SCLI$

Cannot
be
issued
by a
nonprivileged task under any
circumstances.

1-21

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

This chapter introduces the concept of significant events
and
describes the ways in which your code 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
(For some significant events, specifically those in which the current
task becomes ineligible to run, only those tasks of lower priority are
examined.) 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 5.3.61)

•

The execution of a Send Data, Request and Pass
(see Section 5.3.63)

•

The execution of a Send, Request, and Connect
Section 5.3.62)

•

The execution of a Send By Reference or a Receive By Reference
directive (see Sections 5.3.74 and 5.3.55)

•

The execution of an
5.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 5.3.16)

•

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

the

•

The execution of an Exit, an Exit
Status directive

Emit

Alter

2-1

Priority

OCB

directive

With

Event

directive

(see

Section

directive

Status,

(see

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

EVENT FLAGS

Event flags 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
sets the specified flag.
Several examples later in this section
describe how tasks 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." You can use these flags in any application where common
event flags can be used;
however, only tasks running under UICs
containing the group code specified when the group-global event flags
were created can use them. Four directives (Create Group Global Event
Flags, Eliminate Group Global Event Flags, Unlock Group Global Event
Flags, and Read Extended Event Flags) provide the Executive support
for implementing group-global event flags.
Tasks can use the common or group global flags for intertask
communication or their own local event flags internally. They can
set, clear, and test event flags by using Set Event Flag (SETF$),
Clear Event Flag (CLEF$), and Read All Event Flags (ROAF$) 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 using
the Read Extended Event Flags (RDXF$) directive.)
Take great care when setting or clearing event flags, especially
common and group global 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 schedule 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.

2-2

SIGNIFICANT EVENTS, SYSTEM TRAPS, AND STOP-BIT SYNCHRONIZATION
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.
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 Executive 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.
If the
flag has been set first, the directive is a no-op and the task is
not blocked.
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 directives instead of Wait For directives.
When this is done, an event flag condition ·not satisfied will result
in the task's being stopped instead of being blocked until the event
flag(s)
is set.
A task that is blocked still competes for memory
resources at its running priority. A task that is stopped competes
for memory resources at priority O.
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

2-3

SIGNIFICANT EVENTS, SYSTEM TRAPS, AND STOP-BIT SYNCHRONIZATION
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 simultaneously 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
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 (SSTs) -- 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 -- and therefore 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).

2.3.1

Synchronous System Traps (SSTs)

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 1 the task is abortede The SST routine enables
the user to process the failure and then return to the
interrupted
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.

2-4

SIGNIFICANT EVENTS, SYSTEM TRAPS, AND STOP-BIT SYNCHRONIZATION
SST routines must always be reentrant if there is a possibility that
an SST can occur within the SST routine itself.
Although the
Executive 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
an RTI or RTT instruction.
Note that the task's general purpose
registers RO-RS and SP 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.
Note
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 points.
You can specify 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:
Associated
Vector

Trap

Word

Of fest

S.COAD

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

S.CSGF

250

Memory protect violation

S.CBPT

T-bit trap or
instruction

S.CIOT

Execution of an IOT instruction

S.CILI

Execution of a reserved instruction

S.CEMT

Execution
of
instruction

S.CTRP

Execution of a TRAP instruction

S.CFLT

244

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

2-5

execution

non-RSX

BPT

EMT

SIGNIFICANT EVENTS, SYSTEM TRAPS, AND STOP-BIT SYNCHRONIZATION
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.
An even vector entry causes the SST routine to be executed in the same
mode
(either user or supervisor) that the processor was in when the
SST vector was specified. An odd vector entry causes the SST routine
to be executed in the other mode. For example, if the processor was
in supervisor mode and the vector entry was odd, the SST routine is
executed in user mode.
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 (SRQ)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
SP+02
SP+OO

PS
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. Therefore, you can 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.

1. For details of SRO, SRI, and SR2, see the section on the
management unit in the appropriate PDP-11 processor handbook.
2-6

memory

SIGNIFICANT EVENTS, SYSTEM TRAPS, AND STOP-BIT SYNCHRONIZATION
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).
The task 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 or stopped when an associated AST
occurs, the task remains suspended or stopped after the AST
routine has been executed, unless it is explicitly resumed or
unstopped either by the AST service routine itself, or by
another task (the MCR and DCL Resume or UNSTOP command, for
example).

•

If an AST occurs while the related task is waiting
(or
stopped)
for an event flag to be set (a Wait For (Stop For)
directive), the task continues to wait after execution of the
AST service routine unless the event flag is set upon AST
exit.

•

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.

•

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. The AST re-uses the
storage
allocated
for
I/O
and Mark Time directives.
Therefore, no additional dynamic storage is required.

•

Two directives, Disable AST Recognition and Enable
AST
Recognition, allow a program to queue ASTs 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-RS and SP are not
saved.
If the routine makes use of them, it must save and restore
them itself.
On RSX-llM systems that
support
stop-bit
synchronization
or
checkpointing during buffered I/O and all RSX-llM-PLUS systems, the
Wait For mask word comes from the offset T.EFLM in the task's Task
Control Block
CTCB). On svstems that do not suooort those features.
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

2-7

SIGNIFICANT EVENTS, SYSTEM TRAPS, AND STOP-BIT SYNCHRONIZATION
depend on the last Wait For or Stop For 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 0 of the mask word represents flag 33,
bit 1 represents flag 34, and so on.
The Wait For mask word is meaningless if the task has not
type of Wait For or Stop For directive.

issued

any

Your code should not attempt to modify the Wait For mask while in the
AST routine.
For example, putting a zero in the Wait For mask results
in an unclearable Wait For state.
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 5.3.4).
When the AST service routine exits, it returns control to one of two
places: another AST, or the original task.
There are 13 variations on the format of the task's stack, as follows:
•

If a task needs to be notified when a Floating Point Processor
exception trap occurs,
it issues a Specify Floating Point
Processor Exception 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

•

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

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 common
reference is sent to the task.
The stack will contain the
following values:

2-8

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

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
Address of I/O status block for I/O request
zero if none was specified)

(or

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:
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
Event flag number
(or zero
specified)

none

was

An offspring task, connected by a Spawn, Connect, or Send,
Request And Connect directive, returns status to the connected
(parent) task(s) upon exiting by 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

If a command arrives for a CLI,
the Command
• routine
is entered. The stack contains:
SP+lO
SP+06
SP+04
SP+02
SP+OO

AST

Arrival

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

Jf1
.•. . . a//p~f ~r1~/········t·~·~~.·····t~~·~h.~#•••······~i·~~~a~~!¥~.fl.t··~.~··t·.·. .~~.·~J(l~~~l.·.. . ···".1:u..•.•.·er.·•. e.• ..c.·t• · ·.
tti·~. ··: . .i~pµtr '<ip,.<l·.·'i o~~puj: ... f\9'1'•.f?~·~·~~.~·si .a·re entered:.·

dT
•....

/.e•. . .•.s.···.'..··.· .

•.·.·a.t.·······...·s1.·
.. ·.•.'.vk·
..·

st<;lcK.·.·.·.<:·orit,ct~ns ·.·. .··t;qe·.···• f]q:llow:i.r\<.t . •.·.·y..aclue::;··=:

·SP+l4
SP+l2
SP+lO
SP+06

'i·············i·······.·. .•.•••• i .•.• • . i···············. · · .· .•· ·. . •. . ·.·•· · · •· . · . . ·. . . •.·.·.· · .· .. · ····••··.
Svent
;::t:1ag: .m,a;sk.· .word
PS of tqSk prior to AST

PC·• of]task.prior . to·AST
Task's Directive Status Word
Third

parameter
word
· {Vertical
yFc>.. of. the .o.ffspf lng·· r.eqµest
Byte c~\jntof .offspring . · reque::;t
Virtual terminal unit number
(low byte);
I/O
sub function code of .offspring request (high
byte)
Contr~1. ~..·

2-9

SIGNIFICANT EVENTS, SYSTEM TRAPS, AND STOP-BIT SYNCHRONIZATION

•

If a task issues a Specify Parity Error
parity error AST service routine is entered.
contains the following values:
Event flag mask word
PS of task prior to AST
PC of task prior to AST
Task's Directive Status Word

Contents of memory parity CSRs
(hardware-dependent information)

•

If a task becomes aborted via directive, DCL or MCR when the
Specify Requested Exit AST (SREA$) is in effect, the abort AST
is entered with the task's stack containing the following
values:

2-10

SIGNIFICANT EVENTS, SYSTEM TRAPS, AND STOP-BIT SYRCHRONIZATIOll
SP+06
SP+04
SP+02
SP+OO
•

If a task becomes aborted by directive, DCL, or MCR when the
Extended Specify Requested Exit AST (SREX$) is in effect, the
abort AST is entered. The task's stack contains 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
DSW of task prior to AST
Trap dependent parameter
Number of bytes to add to SP to clean the stack

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

2.4

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
Unsolicited character in low byte;
in the high byte

parameter

STOP-BIT SYNCHRONIZATION

Stop-bit synchronization allows tasks to be checkpointed during
terminal (buffered) I/O or while waiting for an event to occur (for
example, an event flag to become set or an Unstop directive to become
issued). You can control synchronization between tasks by the setting
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.
This causes 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 three corresponding ways to become unstopped. Only one method for
stopping a task can be applied at a time.

2-11

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

A task is stopped whenever it is in a Wait For state and has
outstanding buffered I/O.
A task is unstopped when the
buffered I/O is completed or when the Wait For condition is
satisfied.

•

You can stop a task 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).

•

You can stop a task by issuing a Stop; the Receive Data Or
Stop directive, or the Get Command Command for Command
Interpreter directive.
In this case, the task can only be
unstopped by issuing the Unstop directive or by the MCR or DCL
Unstop command.

You cannot stop a task when an AST is in progress
(AST state).
Any
directives that can cause a task to become stopped are illegal at the
AST state.
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 it has exited the AST routine with no other
ASTs queued, the task is again stopped and effectively has zero
priority for memory allocation.
You can use six directives for stop-bit synchronization:
•

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

task
·: SY .

and

cannot

.. ··. '

Receive Data Or Stop ,Fln~t iVPJ:'i~b.l~<.iRe.
;ei . ~;t:a ;()~.>:Stop - 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.

For Single Event Flag - This directive stops the issuing
• Stop
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
by the Stop or Receive Data Or Stop directive.

Command for Command Interpreter - This directive stops a
• Get
CLI task when there is no command queued for it. The GC.CST
option must be specified to force the task to stop.
See
Section 5.3.30.
This directive cannot be issued at the AST
state.

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 by means of 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.

~~i~i~~~~~~~~~~~
. ~w~=~~i ~,•~~~
supervts()::r:' mode .th.~oµq11··the· ;use ..·of ....•....tsU,'pe.rvisor7·mo:d~ ..••.•. ·r~}:)~ar'Y . .•. . .J(:<>utines

and· . .· separat~. · useI'.~mode ......· +..:.. an:a.. ··p...space •..· superV'i:·sqr.;mo(j:~; 'lilj~(:l·ry
·routtrre.s . •. .•. . . a.r~·.•·· . . ins·t:'I'l1c;t'~9·1'l:-ol)•ly < ·r;·?~ti~ne'.s< .. ·.t:'.ba·t ·.· ·a·I''e·>map~.. . tnto
supervisor-mo,d~· ....... I.-.sp~c~ ( . ·(UP>><~(): . i32l<<<~()I'ds>. maxi.1num}.
Us·er .... task
parameters, ,stac~r:and any location~ that may.be .. written. a.re ma.pped
. into su.pervisof:-~ode o..,.~pa,ce (UI) to. 32K words maximum) •. User tasks
th,at use >I- and. D~space may consiS;t ;ot" up ·to 321< words of instructions
and 32l{ w-orqs of data.

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 three concepts defined below, physical address space, logical
address space, and virtual address space, provide a basis for
understanding the functions performed by the memory
management
directives:
•

Physical Address Space -- A task's physical address
the entire set of physical memory addresses.

space

•

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

•

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).

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.

3.1. 3 . :'Supervisor-Mode. ·~dqress·~ng
'RSX.;.llM,.;;PLU's> · su:pporfs..

POP,...U

processors

c~peibJ.e

operai;:ing ..Jn

supf!? ry ii13or •. < .nio~~······ ········-r~e .· superylsor·<.m()g~·fE) ·. one.:.:o f • .• three . . p9ssib~e·····:~oO:es
'(us~r,

kern~l~ :·a~d su:p~rvJ.sor)<Jn ~hich>tbose·.sys~~ms•·•can·· ()Pf?ra.~~}·

·In'

Ii\ode, · ·eight ·.·. act.i:Ve · pcige · · · registers (APRs;) a re available for
: addr~s.s: .ma:p~ing••<~f• .• u~e.~: . . · • ·.taslcs·. ·.••.•.•••. •. N().t~ ....... ~ha.t •.• . .•. :C>'ryJ•. ~·•· · l-E)pa·pe ·APRs: . · ..are
user

emp;l.oyea .•.·.Jn . . .·t.ls,er. mode . fo.r· qotn.:·i. n·s.t:ruct.ions,.ci.r:ld.·. q.cit21..

Sup~;.•v:1.•·s·p·•r;,~~·a:~ ····::.·s\l;~f>(>.·~···~;····:d:<>~~1.~·~:.·········the··· i·•n•st'ruc•t••i·()·n···••••••·.·:~pac•E?•·

· ·

.•
. ·. . .
. •'·•••a:va·•·1·1.••a:b·l..• e••·••·· . . ·to,
···~asks .....• t;)eq~,~t1e; :.:· 16:.... ·.;A.~~s••· .• •.·• ··(8· ·••· . µ$e.1!°'.""ln.()d ~,····\I ...,p,pac~ •.··; ~.n<t·. ·~.. ::sµp,erv:~~.<:> l'.'"'."ln()d~·····.
:·r-ospage} ··ar~.;·~y~il'.~ble·•. f()r.·• address . mapp~r9. •. < .:!l:l7:.9o_n~~nt::1.·. <>f . ·.use•~•..-ll'l()d~
p~sp(\lg~::·.········.~l?~s · · ·:·.·•.. ( ~'·-:s,gpce. ••'·I\~~~··.· p·r . •. sY1:;>te1n·~···· e:n.~t· . • ;9()>.•n<>t:·· ~l1PP<> r:ti.··•·.ilser.• ,da t•<t:
::spa9~h.:•••. e.l'.'e,•··:>c9:p~~:9 ;..•. 1rit<>•··: .• sl1pe;rvi·s:o·!'..,.m · ·•f!.·•·.••.· . . J)7:sP.:JSe>·· .J~l?~·s.· . .·.' . ·. . to . •. •. .•. . ··. a.:+ low·«
·s;u.pe.1'.'i'1'.i.~pr--~qge.Tx'()utl11~s> t<>.•· • :<lC9~~s , <·· ~r....,1ll()9~ ·, ~at(l• '·: .·,(~e~er .~e; the·.
.·.r~•P'f>r:<>P£;~,ft:e·>E>p!:>7p •.•. . pr()~~ssp;::.N:!?'ld.b,c)():~··•~?.r': 1 .~::'<:.G.pm,p~~·te.: :. ·o~~qz:ipt·ion.,, of .
·aao·rf!$S··i m.applrig ,,.·.~emo~y- :::nia11ci$ ~men ~··i;,,ah<3···: ~.11.e··'· va;-.;().us:, AI?~., r'.~9 ist:~ rsJ •··
3-2

MEMORY MANAGEMENT DIRECTIVES

3.2

VIRTUAL ADDRESS WINDOWS

In order to manipulate the mapping of virtual addresses to various
logical areas, you must first divide a task's 32K of virtual address
space into segments.
These segments are called virtual address
windows.
Each window encompasses a contiguous range of virtual
addresses, which must begin on a 4K-word boundary (that is, the first
address must be a mult!.~1~ of 4KJ.• > The 11umber of wt~c:l()\YS ?~~iI'l~c:l by ~
ta.s~ ..•c=.~.I'l. . . . varr . . ~.rom il ··•to· . ·7i{o.r< ~SX'"'":llM.t~~lc;; and t:~.Qit\.('·•J:·i{•.·:t:b;:•:n··2:3···• . 1;o.r.
.·.~~~;,..l;:J;t-t;,..~r..u~:·Wi·'.P
x··<·F'~r a.~~.<~asks, window o is not avaf1abie ·t:o "the··
:.:.·. ~·.·vs. . . ··:·;···.·.;··a·.·... b.)1~.~.•.0e·•·.'. .r·;·:·: .:t~:o.a•. ••~.•~..
i.ng .... ~h
nT. •. ,ah•</e·:.·:.·.·•. :. s i zae)~•.~·otAf:·.': .~e. .'a~.nc....~h:·().ww.'s1· .'.n/:·d:.,.:o.Q:w; ;,. ,ac)a·.,·.·.·. an
.·•. ·. ·.'.htr·~'-;la·•n.. g,:.•)ae·. .'~\ef...':r\'.'o·\'. nm'J9ta... d
"'Jo
µ~~~'.··~···
minimum of ... 32 'wor'as'"to ·.a. maximum of 32K words.
ea.··

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. You specify the required number of additional window
blocks (the number used for windows created by the memory management
directives) to be set up by the Task Builder when linking the task
(see the RSX-llM/M-PLUS Task Builder Reference Manual) • The number of
blocks that you speci~should equal the maximum number of windows
that wiii exist at any one time when the task is running.

3-3

MEMORY MANAGEMENT DIRECTIVES

A window's identification is a number from 0 to 15. for either user
. .. . . . >.::• .. ~:t,t:t
. •. . a·. . •o:~s
.... ... ·•:. p:n ...:.·s···..·:''·.·;z.. ·s.···.·.·t·.·.·.··•:e··.·.·.m·.·····.·.s·.... ·.·•.··•··. ·.·:h·· t..:·.·.:.· .•:.·.•'.·.···:··.·•s·.·.·.··u. ·.·.•.. P·.'o·. ·. •·.·•.·:r·..·•.
o.r.·.····•·· ./ ~.tiP~~'/,.J;~9·:r
!;µp~.r.y1·so t~Jlipde ·
J.ibJ:"ar:~ es·:/ fQ:: .:'l:qi··.·. g~:•· .epr.·.·.··.sY~tem.s.• .~~'l::tli·.·····•.tis~t" · .·. .·•fi:qa··<i.···. ·•.·. ·.s.IJ~l'ij'lsp,r'···••.·:, . :r·~·•. ·:·•·.:.· .· .·. al)d\•······:·.··p.;o.· ·
spa(:!e.) 1 which is an index to the window's corresponding window block.
The address window identified by 0 is the window that maps the task's
h.e.a?er . . ~n? . . r()()t segment •.... ··I"'T'·f:.~.~~~· ;~~;~. ..·.I'f·•~*1~Y~.7~.......
·~·:·~~:µ~.o~ ;~:··~~~·
·~~~·.:··:ta'.~~ ':sS¥•.·:· . •~P(l~i··•.·:•~n..$·l::~'fP'(:.i<:>n.:··.~·~'FJ~~~·t;.;···.····\ . . ·. . . :ap~:. ·;l.i·• m!';lPs· j •e:f: ;::l:.gsl\~··.s1::ij~a~~t'·:~· ·
.s~•a.
'Glna·.:r;;p(J,it.J<J~;t<il·:.:~~g.•1:!n.:ti.. : The Task Builder automatically creates
window 0, which is mapped by the Executive and cannot be specified in
any directive.
t·.···
..

·.:·.a···.···.:..

·p·.·
.•

· .•..··••·.
t·

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ·•····· · . . . . . . . . . . . . . . . . .

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.

3-4

another

MEMORY MANAGEMENT DIRECTIVES
VIRTUAL
ADDRESS
SPACE
32K

3 (SK)

WINDOW3

2SK

.rrmrn rn m 24K
20K
2 (11 K)

WINDOW 2

16K

Ill_

12K

SK
1 (SK)

WINDOW 1

4K
0 (4K)

WINDOWO

D =
•

virtual address
window

=unused virtual
address space
ZK-307-81

Figure 3-1

3.3

Virtual Address Windows

REGIONS

A region is a portion of a physical memory to which a task has (or
potentially may have) access. 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 types of regions:
•

Task region -- A contiguous block of memory in which the
runs

•

Static common region -- An area, such as a global common area,
defined by an operator at run time or at system generation
time
NOTE
RSX-llM
systems,
static
common
regions occupy· physical memory from the
time thev are created. On RSX~llM;..PLUS

f>Ys+t~ms,-.·. t.hey . are . C1Yr'tamica11ry · ioa.aea
whenever· needed.
· ·

3-5

task

MEMORY MANAGEMENT DIRECTIVES
•

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

Tasks refer to a region by means of a region ID returned to the task
by the Executive. A region ID from 0 to 23 refers to a task's static
attac!i~-~.nt.
ion ......!:··~:::R,,... ~. ~ . ~~X~•. ,.)'.". ~.~.~1r.~:<: to ~ .. 17~~k.'.~ task reg i<?n •.
i~i ji ·.pii
iM!.t11ui ;~~~~~~1 I. :1~p1:ntt:;ib~: :i~•e.(l:
ilJ;lf!. ~~ur:a coa·e) : ~fftt fo'.lll · of
;!~~~!(
. . All other region IDs are actually addresses of the
'attachment
escriptor 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 of
the task's logical address space. There are three ways to attach a
task to a region:
•

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-6

MEMORY MANAGEMENT DIRECTIVES

LOGICAL
ADDRESS
SPACE

ZK-308-81

Figure 3-2

Region Definition Block

3-7

MEMORY MANAGEMENT DIRECTIVES

LOGICAL
ADDRESS
SPACE

VIRTUAL
ADDRESS
SPACE
32K

3 (BK)

2BK

mmmaHIIm

24K

WINDOW3

20K
2 (11 K)

WINDOW2

16K

11 K

12K

il
BK
WINDOW1

1 (5K)

------- 4K
)1{4K)

WINDOW,Rf

K
Legend:

•

~ =

= virtual address

window

~ =

= unused virtual

address space

mapped areas of
logical address space
unmapped portions of
logical address space

= pointer to area

____,.

mapped by a window
7K-309-81

Figure 3-3

Mapping Windows to Regions

3-8

MEMORY MANAGEMENT DIRECTIVES
NOTE
Each Send By Reference directive issued
by
a
sending
task creates a new
attachment descriptor for the receiving
task.
However,
multiple
Send
By
Reference directives referencing
the
same region require only 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.

3.3.3

Region Protection

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 may add to their logical address space by
attaching regions, 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, provided 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.
to .·. atte19li.·.. :.ari9:t..ll.~I'.::·.tas~.·t.9:·C1ttyi r~gJo·n.i; on. RSX~llM, the task
reg ion itse1 f may not be one of the regions invo1 ved •
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.

•

3e4

Any task can map to a named static common region.

DIRECTIVE SUMMARY

This section briefly describes the function of each memory
directive.

3-9

management

MEMORY MANAGEMENT DIRECTIVES
3.4.1

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 5.3.13).

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 5.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 5.3.19).

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
5.3.11).

3.4.5

Eliminate Address Window Directive (ELAW$)

The Eliminate Address Window directive eliminates an existing
window, unmapping it first if necessary {see Section 5.3.20).

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 5.3.40).

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 5.3.85).

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 5.3.74).

3-10

MEMORY MANAGEMENT DIRECTIVES
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 5.3.55).

3.4.10

Get Mapping Context Directive (GMCX$)

The Get Mapping Context directive causes the Executive

return

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 5.3.34).

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
5.3.36).

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 (ROB)

•

The Window Definition Block (WDB)

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 ROB 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 assians
values to various locations within the biock to describe the actions
taken and to provide the task with information useful for subsequent
operations.
3-11

MEMORY MANAGEMENT DIRECTIVES
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=lOOOOO

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.
When a region is created by means of a CRRG$
directive it is normally marked for deletion
on last detach.
However, if RS.NOL is set
when the CRRG$ directive is executed, the
region
is
not
marked
for
deletion.
Subsequent execution of a DTRG$ directive
with
RS.MDL
set
marks the region for
deletion.

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.

marked

for

These symbols are defined by the RDBDF$ macro, as described in section
3.5.1.1.
The three memory management directives that require a
RDB are:

pointer

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 actions were taken.
The Executive never modifies the other bits.

3-12

MEMORY MANAGEMENT DIRECTIVES

Array
Element

Symbolic
Offset

Byte
Offset

Block Format

0
irdb (1)

R.GID

REGION ID
2

irdb (2)

R.GSIZ

SIZE OF REGION (32W BLOCKS)
4

irdb (3)
R.GNAM

NAME OF REGION (RAD50)

irdb (4)

irdb (5)
R.GPAR

REGION'S MAIN PARTITION NAME (RAD50)

irdb (6)

14
irdb (7)

R.GSTS

REGION STATUS WORD
16

irdb (8)

R.GPRO

REGION PROTECTION WORD

ZK-310-81

Figure 3-4

Region Definition Block

3.5.1.l 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$, you 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 the region (RADSO).

3-13

MEMORY MANAGEMENT DIRECTIVES
sts
Bit definitions of the region status word.
pro
The reg ion's default protection word.
The sts argument sets specified bits in the status word
argument normally has the following format:

R.GSTS.

The

<bitl[! ••• !bitn]>
bit
A defined bit to be set.
The argument 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

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

has

DELETE

EXTEND

4 3

OWNER

equivalent

SYSTEM

four

bits,

with

each

bit

I WRITE READ I

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

102.,ALPHA,GEN,<RS.NDL!RS.ATT!RS.WRT!RS.RED>,167000

expands to:
.WORD
• WORD
.RADSO
.RADSO
.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 1110 1110 0000 0000, grants access as follows:
System
Owner
Group
World

(1110)

All access

(liiOj

All access

(0000)
(0000)

Read access only
Read access only
3-14

MEMORY MANAGEMENT DIRECTIVES
If the Create Region directive is successful, the Executive will first
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.5.1.2 Using FORTRAN to Generate an RDB - When
programming
in
FORTRAN, you must create an 8-word, single-precision integer array as
the RDB to 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:

Contents

Word
irdb(l)

Region ID

irdb(2)

Size of the region in 32-word blocks

irdb(3)
irdb(4)

Region name (2 words in Radix-50 format)

irdb(S)
irdb(6)

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

irdb(7)

Region status word (see
this list)

irdb(8)

Region protection code

the

paragraph

following

You can modify the region status word irdb(7) by setting or clearing
the appropriate bits.
See the list in Section 3.5.1 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.5.2

Window Definition Block (WDB)

Figure 3-5 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.
3-15

M!MORY MANAGEMENT DIRECTIVES
WS.RRF=lOOOO

Reference was successfully received.

WS.RES=2000

Map only if resident.

WS.64B=400

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

WS.MAP=200

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

WS.RCX=lOO

Exit if no references to receive.

WS.DEL=lO

Send with delete access.

WS.EXT=4

Send with extend access.

WS.WRT=2

Send with write access.
or
Map with write access.

WS.RED=l

Send with read access.

3-16

MEMORY MANAGEMENT DIRECTIVES

Array
Element

Symbolic
Offset

Block Format

Byte
Offset

0
W.NID
W.NAPR

iwdb (1)

BASE APR

WINDOW ID

2
iwdb (2)

W.NBAS

VIRTUAL BASE ADDRESS (BYTES)
4

iwdb (3)

W.NSIZ

WINDOW SIZE (32W BLOCKS)

6
iwdb (4)

W.NRID

REGION ID

10
iwdb (5)

W.NOFF

OFFSET IN REGION (32W BLOCKS)

12
iwdb (6)

W.NLEN

LENGTH TO MAP (32W BLOCKS)

14
iwdb (7)

W.NSTS

WINDOW STATUS WORD
16

iwdb (8)

W.NSRB

SEND/RECEIVE BUFFER ADDRESS (BYTES)

ZK-311-81

Figure 3-5

Window Definition Block

These symbols are defined by the WDBDF$ macro, as described in Section
3.5.2.1.
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$)
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
Executive never modifies the other bits.

3.5.2.l 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$
3-17

MEMORY MANAGEMENT DIRECTIVES
Since WDBBK$ automatically invokes WDBDF$, you 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 be mapped, in 32-word blocks.
len
The length within the region to be mapped,
{defaults to the value of siz above}.

32-word

blocks

sts
The bit definitions of the window status word.
srb
A send/receive buffer virtual address.
The argument sts sets specified bits in the status word
argument normally has the following format:

W.NSTS.

The

<bitl[! ••• !bitn]>
bit
A defined bit to be set.
The macro call
WDBBK$

5,76.,0,50.,,<WS.MAP!WS.WRT>

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

0,5
0

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

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)

3-18

beginning

APR 5

MEMORY MANAGEMENT DIRECTIVES
Start the map 50 (decimal) blocks from the base of the region,
• and
map an area either equal to the length of the window (76
(decimal] blocks) or to the length remaining in the region,
whichever is smaller (because the macro call defaulted the len
argument)

•

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

window's

ID)

and

3.5.2.2 Using FORTRAN to Generate a WDB - You 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 SREF
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 creation of arrays.) A WDB array has the following 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.

i wdb ( 3)

Size of the window in 32-word blocks.

iwdb(4)

Region ID.

iwdb(5)

Offset length within the
begins, in 32-word blocks.

i wdb ( 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

region

bits 8

which

map

paragraph

following

You can modify 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 0 to 7 for any directive
other than Create Address Window.

•

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

set

CALL GE TA DR ( 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. If you use the SREF and
RREF routines, you do not need to use GETADR.
3-19

MEMORY MANAGEMENT DIRECTIVES
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 5 describes which offsets and settings are relevant for each
memory management directive. The values assigned by the task are
called input parameters, whereas 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.
Take great care when using the
directives in this way, because 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.
NOTE
Tasks should not remap APRO. If APRO is
remapped, information such as the DSW,
overlay structures, or language runtime
systems will become inaccessible.

3-20

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, you can set up task relationships and parameters
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

This section summarizes the directives
and inter-task communication.

4.2.1

for

parent/offspring

tasking

Parent/Offspring Tasking Directives

There are two classes of parent/offspring tasking directives:
•

Spawning

directives that create a connection between tasks

•

Chaining

directives that transfer a connection

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 spawned by a parent task has the following
three task functions that are not provided by the Request or
Run directive.

4-1

PARENT/OFFSPRING TASKING
1.

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

A spawned offspring
information or exit
parent task or tasks.

task can return current
status
status information to a connected

Spawn directive options include:
1.

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

(which

may

For privileged or CLI tasks, designating any
the offspring TI:

terminal

3.
•

Connect - This directive establishes task communications for
synchronizing with the exit status or emit status issued by a
task that is already active.

•

Send, Request, and Connect - This directive sends data to the
specified task, requests activation of the task if it is not
already active, and connects to the task.

There are also two directives that support task chaining:
•

Request and Pass Offspring Information -- This
directive
allows an offspring task to pass its parent connection to
another task thus making the new task the offspring of the
original parent.
The RPO!$ directive offers all the options
of the Spawn directive.

•

Send Data, Request and Pass Offspring Control Block -- This
directive sends a data packet for a specified task, passes its
parent connection to that task, and requests it if it is not
already active.

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.

4.2.2

Task Communication Directives

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

4-2

parent

PARENT/OFFSPRING TASKING
•

Exit With Status - This directive in an offspring task causes
the offspring task to exit, passing status words to all
connected parent tasks (one or more) that have been previously
connected by a Spawn, Connect, or Send, Request, and Connect
directive.

•

Emit Status - This directive causes the offspring task to pass
status words to either the specified connected task or all
connected parent tasks if no task is explicitly specified.

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

task(s)

Standard offspring task status values that can be returned
tasks are listed as follows:

parent

EX$WAR

Warning - task
succeeded,
irregularities are possible

EX$SUC

Success - results should be as expected

EX$ERR

Error - results are unlikely
expected

EX$SEV

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

but

errors

These symbols are defined in DIRSYM.MAC. They become defined locally
when the EXST$ macro is invoked. However, the exit status may be any
16-bit value.

4.3

CONNECTING AND PASSING STATUS

Offspring task exit status can be returned to connected
(parent)
task(s)
by issuing the Exit With Status directive. Offspring tasks
can return status to one or more connected parent tasks at any time by
issuing
the
Emit Status Directive.
Note that only connected
parent-offspring tasks can pass 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 four ways shown
below.
•

Task A spawned Task B when Task B was inactive.

•

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

•

Task A issued a Send, Request, And Connect to Task B when Task
B was either active or inactive.

•

Task A either spawned or connected to Task c, which then
chained to Task B by means of either an RPO!$ directive or an
SDRP$ directive.

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.

4-3

PARENT/OFFSPRING TASKING
Task

status

•

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

directive.

•

Task B is aborted.
EX$SEV.

•

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

•

Task B issues an Emit Status directive specifying Task A.
If
Task A is multiply connected to Task B, the OCBs that contain
information about these multiple connections are stored in a
FIFO queue.
The first OCB is used to determine which event
flag, AST address, and exit status block to use.

•

Task B issues an Emit Status directive to all connected
(no task name specified) •

Task A receives a severe error

status

tasks

When a task has previously specified another task in a Spawn, Connect,
or Send, Request, and Connect directive and then exits, and if status
has not yet been returned, the OCB representing this connect remains
queued.
However,
the OCB is marked to indicate that the parent task
has exited. When this OCB is subsequently dequeued due to an Emit
Status directive, or any type of exit, no action is taken since the
parent task has exited.
This procedure is followed to help a
multiply-connected task to remain synchronized when parent tasks
unexpectedly exit.
Examples of using directives 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$

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

SDRC$

RCVX$,
EMST$

Task A sends data to Task B, requests Task B if it
is presently not active, and connects to Task B.
Task B receives the data, does some processing
based on the data,
returns status to Task A
(possibly setting an event flag or declaring an
AST), and becomes disconnected from Task A.

SDRC$,
USTP$

RCST$,
EMST$

Task A sends data to Task B, requests Task B if it
is presently not active, connects to Task B, and
unstops Task B.
Task B becomes unstopped (if Task
B previously could not dequeue the data packet),
receives the data, does some processing based on
the data, and returns status to Task A (possibly
setting an event flag or declaring an AST).

SDAT$,
USTP$

RCST$

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

SPWN$

RPOI$
SDRP$

Task A spawns Task B. Task B chains to Task C by
issuing an RPOI$ or an SDRP$ directive. Task A is
now
Task C's parent.
Task A is no longer
connected to Task B.

4-4

completion,
B

PARENT/OFFSPRING TASKING
4.4

SPAWNING SYSTEM TASKS

One special use of the Spawn directive is to pass a command line to a
system task.
You may use the Spawn directive to pass a command line
to a command line interpreter, or to an installed utility.

4.4.1

Spawning a Command Line Interpreter

Command line interpreters can be broken into three classes:
CLI that is active from TI:, and all others.

MCR,

the

•

To pass a command line to MCR, use the task name MCR •••

•

To pass a command line to the CLI that is currently active
from TI:, use the task name CLI • • • • You can determine which
CLI is active from your TI:
by issuing the GCII$ directive.

•

To pass a command to a specific CLI other than MCR or the CLI
active from TI:, simply use that CLI's task name in your Spawn
directive.
The task name of DCL is ••• DCL.
Check with your
system manager for the task names of any user-written CLI's.

•

On RSX-llM systems, you may pass a command to a specific CLI
only if the specified task name is not already active.
If the
task name is already active, the Spawn directive will fail.

Spawning a Utility

4.4.2

Utilities are generally installed under task names of the form ••• tsk.
This convention allows the utilities to be invoked as MCR commands.
(See the RSX-llM/M-PLUS MCR Operations Manual.)
You can pass commands to a utility in one of two ways.
You can spawn
the utility directly, using the task name ••• tsk.
Or, you can spawn
MCR and pass it a command line that begins with three-character task
name.

4. 4. 2~ 1 spaWl)i.ng a Utility under :RSX'.--l.11- -- .!:( yo.u attempt to. spawn
•.•• tsk dlr~ctly on an RSX--llM 9_ysi::ern, the : operatfor1 behaves as
follows:

•

If that task is not yet active, the
it, under the name ••• tsk.

•

If the task •• ~tsk is already active, your Spawn directive
will fail,
regardless of which terminal has activated that
task.

executive

will

activate

If you passMCR a command line beginning with "tsk", MCR will:
•

Attempt to activate the task ••• tsk.

•

If that tas.k name is already active, MCR will attempt to
activate the task under the name tskTnn, where nn is the unit
number of your TI:.

•

If both ••• tsk and tskTnn are already active, MCR will
failure to your task.

4-5

report

PARENT/OFFSPRING TASKING
Unless you· are ·certain that the utlli£y you' desire fa not yet active
in . the system, direct spawning of the. utility.· offers a great~r
likelihood of failure than requesting the utility through MCR.. · For
this reason, . i t . is recommended that o.n RSX--llM systems you request
utilitie$.• through· MCR.

4.4.2.3 Passing Command Lines to Utilities - Even when you spawn a
utility directly, pass a command line that includes the entire command
as you would type it at the terminal or pass it to MCR.
Include the
3-character
task
name
followed
by a space.
This maintains
compatibility with the format used by MCR to pass commands to
utilities. (See the description of the GMCR$ directive in Chapter 5.)

4-6

CHAPTER 5
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, you 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.

5.1

DIRECTIVE CATEGORIES

For ease of reference, the directive descriptions are presented
alphabetically in Section 5.3 according to the directive macro calls.
This section, however, groups the directives by function.
The
directives are grouped into the following ten 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/offspring tasking directives

•

Command line interpreter (CLI) support directives

5.1.1

Task Execution Control Directives

The task execution control directives deal principally with starting
and stopping 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:
5-1

DIRECTIVE DESCRIPTIONS
Macro

Directive Name

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

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

5.192

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

Directive Name

ALTP$
DSCP$S
ENCP$S

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

5.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
GPRT$
GREG$
GSSW$S
GTIM$
GTSK$

5.1.4

Directive Name
Get
Get
Get
Get
Get

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

Event-Associated Directives

The event and event flag directives provide inter- and
intratask
synchronization and signaling and the means to set the system time.
You must use these directives carefully since software
faults
resulting from erroneous signaling and synchronization are often
obscure and difficult to isolate.
The directives are:
Macro
CLEF$
CMKT$
CRGF$
DECL$S
ELGF$
EXIF$
MRKT$
RDAF$
RDXF$
SETF$
STIM$

Directive Name
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
Set Event Flag
Set System Time

5-2

DIRECTIVE DESCRIPTIONS
Macro
STLO$
STOP$S
STSE$
ULGF$S
USTP$
WSIG$S
WTLO$
WTSE$

5.1.5

Directive Name
Stop For Logical 'OR' of Event Flags
Stop ($S form recommended)
Stop For Single Event Flag
Unlock Group Global Event Flags ($S form recommended)
Unstop
Wait For Significant Event ($S form recommended)
Wait For Logical OR Of Event Flags
Wait For Single Event Flag

Trap-Associated Directives

The trap-associated directives provide trap
transfer of control
(software interrupts)
These directives are:

5.1.6

facilities that allow
to the executing tasks.

Macro

Directive Name

ASTX$S
DSAR$S
ENAR$S
IHAR$S
SCAA$
SFPA$
SPRA$
SRDA$
SREA$
SREX$
SRRA$
SVDB$
SVTK$

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 Command Arrival AST
Specify Floating Point Processor Exception AST
Specify Power Recovery AST
Specify Receive Data AST
Specify Requested Exit AST
Specify Requested Exit AST (extended)
Specify Receive-By-Reference AST
Specify SST Vector Table For Debugging Aid
Specify SST Vector Table For Task

I/0- 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:

5.1.7

Macro

Directive Name

ALUN$
CINT$
GLUN$
GMCR$
QIO$
QIOW$
RCVD$
RCVX$
SDAT$
SMSG$

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

Memory Management Directives

The memory management directives allow a
task to manipulate
its
virtual and logical address space:
and to set uo 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:
5-3

DIRECTIVE DESCRIPTIONS
Macro

Directive Name

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

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

5.1.8

Parent/Offspring Tasking Directives

Parent/offspring tasking directives permit tasks to start other tasks,
and to connect to other tasks in order to receive status information.
These directives are:
Macro

Directive Name

CNCT$
EMST$
EXST$
RPOI$
SDRC$
SDRP$
SPWN$

Connect
Emit Status
Exit With Status
Request and Pass Offspring Information
Send, Request And Connect
Send Data, Request and Pass OCB
Spawn

5.1.9

RSX-UM-PLUS Directives

In addition to the directives just listed, RSX-llM-PLUS includes
directives
that support vfrtual tenninals, CPU/UNIBUS affinity,
supervlsor-,.mode library routines, variable-length send/receive data
buffers, and parity error AST routine support.; These directives are:

Macro

Directive Name

CPCR$

Ch(i!ckpo~nt .•·common.Reg ion

CRVT$

C.reate .· Virtual Terminal

. ELVT.$
MSDS$
MVTS$····
.RpEF$.

RMJ\F$S

·:•scAL:$s ··
$PEA$ ..

$NXC$

~TAFf . ·.·.· ·

VRCP$.···•

·:mR.S$ .. ·

Elimi ne:1~7. Vi rtucil . . Terminal
r.iap··.•. sµper\1~90 r. ·p-$pac::e
Move · t?/from .I/D.-"Sp9ce .. ·
:Reaa·.·. ···.si r191 e •. Ev~J).~· Fla<.{
·... Remoye·•. ·. •. ~;~Jl1it.:(···($Et fprin only)
St1pervtso·r.:Ca1.:t .·.·.J$S for·m· only} .
Specif}>'. ~~r;i~Y·~.f'fOJ. AST

s.epq •. Next• .Command

>.set· i\~ffnity

.v13-~i(3l)~7 Re~·~hie na::

Y~.·.~·i~b~.·~•. ··R~·o~ive o

. ·.· .

5-4

•·

Qr•···•.st·~~.··.·i·.: ;···\/•·;\.::·:

>v.?:r;il:lb·J:~ . ·
.~~.~ . . ,l)e:fy·~·
Variable
.
·~·.~·.··.·
R~;<lf.e:~~~·.
•. )V'S,.QJ\ $ .' ' ,:~·:~:.:·.va:,t,:fa',b·.i:e: SeJl<f:.f·. ,Pa:t,~~.·.:.·:1;,
-

YftC:X$
·:vsRC$<

. · ·.

.... ······ · .:··. .'. · ·····: < •

~X:i~ :./·r >> X i · · .

and ~onne:ct
·.·
--··;·._;;~--=·:

DIRECTIVE DESCRIPTIONS

5.1.10

CL! Support Directives

The CLI support directives allow CLI tasks to get command lines,
request and pass offspring information, get command interpreter
information, and set a specified CLI for a terminal. These directives
are:

5.2

Macro

Directive Name

GCCI$
GCII$
SCLI$

Get Command for Command Interpreter
Get Command Interpreter Information
Set Command Line Interpreter

DIRECTIVE CONVENTIONS

The following are conventions for using system directives:
1.

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.

5-5

directive

DIRECTIVE DESCRIPTIONS
2.

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-SO 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-SO form.
To establish
Radix-SO representation, either use the DATA statement at
compile time, or use the IRADSO subprogram or RADSO 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 compatibility between
RSX-llM, RSX-llM-PLUS, and 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) can range from 1 to 2SS(l0).

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 6S to 96 denote group-global event
flags.

Note that the Executive preserves
issues a directive.

S.3

all

task

represented

registers

when

all

the

and

defines

task

SYSTEM DIRECTIVE DESCRIPTIONS

Each directive description includes
elements:

most

following

Name:
This describes the function of the directive.
FORTRAN Call:
This shows
parameter.

the

FORTRAN

subroutine

call,

each

Macro Call:
This shows the macro call, defines each parameter, and gives the
defaults for optional parameters 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/M-PLUS
are
required
for
compatibility with IAS.

S-6

DIRECTIVE DESCRIPTIONS
Macro Expansion:
Most of the directive descriptions expand the $S form of the
macro.
Where the $S form is recommended for a directive, the
expansion for that form is shown instead.
Section
1.4.5
illustrates expansions for all three forms and for the DIR$
macro.
Definition Block Parameters:
Only the memory management directive descriptions include these
parameters.
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. This section lists these
symbols.
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 four bytes.

DPB;

DSW Return Code:
This section lists all valid return codes.
Notes:
The notes presented with some directive descriptions expand on
the function, use, and/or consequences of using the directives.
Always read the notes carefully.

5-7

DIRECTIVE DESCRIPTIONS

ABRT$
5.3.1

Abort Task

The ~..bort Task directive instructs the system to terminate the
execution of the indicated task.
ABRT$ is intended for use as an
emergency or fault exit. ABRT$ displays a termination notification
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 by a Run directive, or by an MCR
or DCL Run command that specified one or more time parameters

the

task

that

requested

the

On systems without multiuser protection, 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

Name of the task to be aborted (RAD50)

ids

Directive status

Macro Call:
ABRT$
tsk

tsk
Name of the task to be aborted (RAD50)

Macro Expansion:
ABRT$
.BYTE
.RAD50

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

5-8

DIRECTIVE DESCRIPTIONS
IE.PR!

Issuing task is not privileged (multiuser
protection systems only)

IE.ADP

Part of
space

IE.SDP

DIC or DPB size is invalid

the DPB is out of the issuing task's address

Notes:
1.

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 and despecifies all specified ASTs.

•

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
locked).

•

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

•

Runs down the task's I/O.

•

Deaccesses the group global event
group.

•

Disconnects from interrupts.

•

Flushes all outstanding CLI command buffers for the task.

•

Breaks the connection with any offspring tasks.

•

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

•

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

for

flags

write

access

are

the

case

for

the

task's

task

If the aborted task had a requested exit AST specified, the
task will receive that AST instead of being aborted. No
indication that this has occurred is returned to the task
that issued the abort request.

When the aborted task actually exits, the Executive
a significant event.

5-9

declares

DIRECTIVE DESCRIPTIONS

ALTP$
5.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 non-privileged task
can issue ALTP$ only for itself, and only for a priority equal to or
lower than its installed priority. A privileged task can change the
priority of any task to any value less than 250.
FORTRAN Call:
CALL ALT PR I { [ ts k ] , [ i pr i ] [ , i d s ] )
tsk

Active task name

ipri

A 1-word integer value equal to
a number from 1 to 250 {decimal)

ids

the new

priority,

Directive status

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.,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)

5-10

DIRECTIVE DESCRIPTIONS
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) •

IE. IPR

Invalid priority.

IE.ADP

Part of the DPB
space.

IE. SDP

DIC or DPB $ize is invalid.

is out of the issuing task's address

5-11

DIRECTIVE DESCRIPTIONS

ALUN$
5.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 Assign command in the
RSX-llM/M-PLUS MCR Operations Manual or the RSX-llM/M-PLUS Command
Language Reference Manual). The Executive first searches the logical
assignment table for a device name match. If it finds a match, the
Executive assigns the physical device unit associated with the
matching entry 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.
FORTRAN Call:
CALL ASNLUN (lun,dev,unt[,ids])
lun

Logical unit number

dev

Device name (format:

unt

Device unit number

ids

Directive status

1A2)

Macro Call:
ALUN$ lun,dev,unt
Logical unit number

lun
dev

Device name (two characters)

unt

Device unit number

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 (2)

5-12

DIRECTIVE DESCRIPTIONS
DSW Return Codes:

rs.sue

Successful completion.

IE.LNL

LUN usage is interlocked (see Note 1 below).

IE.IOU

Invalid device and/or unit.

IE.ILU

Invalid logical unit number.

IE.ADP

Part of
space.

IE.SDP

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.

5-13

DIRECTIVE DESCRIPTIONS

ASTX$
5.3.4

AST Service Exit ($S form recommended)

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.
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

Macro Expansion:
ASTX$S
MOV
.BYTE
EMT
JSR

ERR
( PC ) + I - ( s p )
ll 5. , 1
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:
IS. sue

Successful completion.

IE.AST

Directive not issued from an AST service
routine.

IE.ADP

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

IE. SDP

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

5-14

minimum,

the

DIRECTIVE DESCRIPTIONS
The task stack must be in this state when the AST Service Exit
directive is executed.
In addition 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 parameters when a task uses an AST
routine on I/O completion:
Example:
EXAMPLE PROGRAM
LOCAL DATA
IOSB:
.BLKW
BUFFER: .BLKW

;I/O STATUS DOUBLEWORD
;I/O BUFFER

30.

START OF MAIN PROGRAM
;PROCESS DATA

START:
QIOW$C

IO.WVB,2,l,,IOSB,ASTSER,<BUFFER,60.,40>
;PROCESS & WAIT
;EXIT TO EXECUTIVE

EXIT$S
AST SERVICE ROUTINE

;PROCESS AST

ASTSER:

TST
ASTX$S

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

(SP)+

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 simply 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 you should
use extreme caution when doing
this alteration since AST
service routine bugs are difficuit to isoiate.

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

5-15

DIRECTIVE DESCRIPTIONS

ATRG$
5.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 Executive grants the desired access. 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
directives.
You can also use the directive 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.
You 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.
FORTRAN Call:
CALL ATRG {irdb[,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

Offset

irdb(3) (4) R.GNAM
irdb{7)

R.GSTS

Name of the region to be attached
Bit settings 1 in the region status word
(specifying desired access to the region):

1. If you are a
FORTRAN programmer, refer to Section 3. 5.1 to
determine the bit values represented by the symbolic names described.

5-16

DIRECTIVE DESCRIPTIONS
Bit

Definition

RS.RED

1 if read access is desired

RS.WRT

1 if write access is desired

RS.EXT

1 if extend access is desired

RS.DEL

1 if delete 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. PRI

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. SDP

DIC or DPB size is invalid.

5-17

RDB is out of the issuing task's

DIRECTIVE DESCRIPTIONS

CINT$
5.3.6

Connect to Interrupt Vector

The Connect to Interrupt Vector directive enables a task to process
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 of about 10 instructions before
entry into the ISR, and 10 instructions after exit from the ISR. The
Executive provides a mechanism 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.
1.

Interrupt Level
When an interrupt occurs, control is transferred, with the
Interrupt Transfer Block {ITB) that has been allocated by the
CINT$ directive, to the Executive subroutine $TNTSC.
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.

Fork 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
further condenses the information. 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 in order 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.

5-18

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
ISR, and enable/disable interrupt routines
This
address is automatically truncated to a 32(10)-word
boundary.
The "base" argument is ignored in an
unmapped system.

isr

Virtual address of the ISR, or 0
the interrupt vector

edir

Virtual
routine

address

the

disconnect

enable/disable

from

interrupt

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, PR5, PR6,
and PR? for this purpose. These are implemented via
the macro HWDDF$ found in [l,l]EXEMC.MLB. Also, the
programmer should take care to specify the correct
value
for this parameter.
An
incorrect initial
priority (for example, specifying PR4 for a device
that interrupts at PR5) may result in a system crash.

ast

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

after

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

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

420,BADR,TADR,EDADR,PR5,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
PR5,0
;INITIAL INTERRUPT SERVICE ROUTINE
;PRIORITY (LOW BYTE).
(HIGH BYTE= 0.)
ASTADR
;VIRTUAL ADDRESS OF AST ROUTINE

5-19

DIRECTIVE DESCRIPTIONS
Local Symbol Definitions:
C.INVE

Vector address (2)

C.INBA

Base address (2)

C.INIS

ISR address (2)

C.INDI

Enable/disable interrupt routine address (2)

C.INPS

Priority (1)

C.INAS

AST address (2)

DSW Return Codes:
IE.UPN

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.PR!

Issuing task is not privileged
unmapped system) •

IE.RSU

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.SOP

DIC or DPB size is invalid.

(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
the
arguments
"isr,"
"edir," and "ast"
addresses.

ignored, and
are physical

In a mapped system, however;
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

5-20

DIRECTIVE DESCRIPTIONS
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 (refer to the PDP-11 MACR0-11 Language Reference
Manual for more information on position-independent code) or
coded in such a way that the code can execute in APR S
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.
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

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

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(RS),R4
The ISR either dismisses the interrupt directly by 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.

S-21

DIRECTIVE DESCRIPTIONS

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 servicing 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.
pointer to fork block in the ITB

Input:

Output:

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

Registers altered:

RO, Rl, R2, and R3

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

$SETF.

event flag number

Output:

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
S.

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.

S-22

vectors

DIRECTIVE DESCRIPTIONS
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
that common code is used for multiple vectors.
6.

the

event

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).

ITB Structure
The following offsets are defined relative to
the ITB:

the

start

X.LNK

Link word

X.JSR

Subroutine call to $INTSC

X.PSW

PSW for ISR (low-order byte)

X.ISR

ISR address (relocated)

X.FORK

Start of fork block

X.REL

APR 5 relocation (only in mapped systems)

X.DSI

Address of enable/disable interrupt routine
(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

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.

5-23

the
All

DIRECTIVE DESCRIPTIONS

The following programming example illustrates the
directive:

use

the

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 rs NECESSARY TO ACCESS THE I/O PAGE
IN OTHER THAN THE ENABLE/DISABLE ROUTINE OR THE ISR
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:l
PAR=GEN:0:40000
IT rs POSSIBLE TO HAVE THIS TASK TYPE ON THE CONSOLE TERMINAL
IF THERE rs NO PAPER TAPE PUNCH AVAILABLE. TO DO THIS THE
VECTOR FOR THE CONSOLE OUTPUT MUST APPEAR TO BE UNUSED. THIS
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]RSX11M.STB/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 1 M$$MGE'.
;--

.MCALL CINT$, QIOW$, CLEF$S, WTSE$S, EXIT$S, DIR$
LOCAL SYMBOLS

5-24

DIRECTIVE DESCRIPTIONS

1
1
2

LUN. TT
EFN.TT
EFN.WF
M$$MGE
;++

;LUN FOR TERMINAL I/O
;EFN FOR TERMINAL I/O
;EFN TO WAIT FOR PUNCHING TO COMPLETE
;DEFINE THIS SYMBOL TO RUN ON MAPPED SYSTEM

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

.MACRO MESSG
NAM,STRING,?LBL
$CHR=O
.IRPC
X,<STRING>
$CHR=$CHR+l
ENDR
.ENABL LSB
LBL:

.ASCII

NAM:

.EVEN
QIOW$ IO.WVB,LUN.TT,EFN.TT,,,,<LBL,$CHR,40>
.DSABL LSB
.ENDM

/STRING/

MESSG -HELLO,<CONNECT TO INTERRUPT rEST>
MESSG CINWRK,<CONNECT TO INTERRUPT WORKS--CHECK THE PAPER TAPE PUNCH>
CINT$

CINT:

$VECTR,$BASE,$PNISR,$PNEDI,PR4
;CONNECT TO INTERRUPT
VECTOR=$VECTR
BASE.FOR.MAPPING=$BASE
ISR=$PNISR
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$
BC$
WTSE$S
DIR$
DIR$
EXIT$S

#HELLO
iCINT
ERRl
iEFN.WF
#DISCON
iCINWRK

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

5-25

DIRECTIVE DESCRIPTIONS

ERRl:

MOV
MOV
IOT

U,RO

$DSW,Rl

ERROR i 1
GET THE DSW TO SHOW THE CINT ERROR RETURN
DUMP REGISTERS
;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.

$BASE;

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

PUNMSG:

• NLIST
.ASCIZ
.LIST
.EVEN

BEX
/ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!@i$%A&*()_+-=/<15><12>
BEX

;POINTER INTO PUNMSG FOR ISR
PUNPTR:
.WORD
0
;TCB ADDRESS OF TASK
TSKTCB:
.WORD
0
$DVCSR
;PAPER TAPE PUNCH CSR ADDRESS
PUNCSR:
.WORD
;PAPER TAPE PUNCH BUFFER ADDRESS
PUNBUF:
.WORD
$DVCSR+2
;++
ENABLE/DISABLE ROUTINE.
THIS ROUTINE IS CALLED BY THE EXEC ON EITHER A CONNECT OR DISCONNECT
FROM INTERRUPT VECTOR REQUEST, OR 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) •

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 ISR WILL THEN FORK
AND SET THE LOCAL EVENT FLAG 'EFN.WF'. THIS WILL THEN CAUSE THE
TASK PORTION OF THIS TASK TO CONTINUE EXECUTING AND EVENTUALLY
EXIT.

5-26

DIRECTIVE DESCRIPTIONS

$PNEDI::BCS
MOV

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

• IF DF M$$MGE

;MAPPED SYSTEM?

MOV

iPUNMSG+l20000-<$BASE&l77700>,PUNPTR ;RELOCATE ADDRESS
;TO APR 5 MAPPING, AND SET UP
;BUE'FER POINTER

.IFF

M$$MGE

MOV

iPUNMSG,PUNPTR ;SET UP BUFFER POINTER

;UNMAPPED SYSTEM?

.ENDC
BIS
RETURN

ilOO,@PUNCSR ;ALLOW INTERRUPTS
;WHEN WE ARE DONE PUNCHING

20$:

BIC
RETURN

ilOO,@PUNCSR ;DISABLE INTERRUPTS

.END

5-27

DIRECTIVE DESCRIPTIONS

CLEF$
5.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 (EFN<l, or EFN>96, if group
global event flags exist for the task's group; or
EFN>64 if not).

IE.ADP

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

IE. SDP

DIC or DPB size is invalid.

5-28

DIRECTIVE DESCRIPTIONS

CMKT$
5.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.
FORTRAN Call:
CALL CANMT ( [ efn] [,ids] )

efn

Event flag number

ids

Directive status

Macro Call:
CMKT$

[efn ,ast ,err]

err

Error routine address

efn

Event flag number

ast

Mark time AST address

Macro Expansion:
CMKT$
.BYTE
.WORD
• WORD

52.,MRKAST,ERR
27.,3
52.
MRKAST

;NOTE: THERE ARE TWO IGNORED ARGUMENTS
;CMKT$ MACRO DIC, DPB SIZE=3 WORDS
;EVENT FLAG NUMBER 52 •
;ADDRESS OF MARK TIME REQUEST AST ROUTINE
NOTE

The above example will cancel only the
Mark Time requests that were specified
with efn 52 or the AST address MRKAST.
If
no
ast
or efn parameters are
specified, all Mark Time requests issued
by the task are cancelled, and the DPB
size will equal 1.
Local Symbol Definitions:
C.MKEF

Event flag number (2)

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

5-29

DIRECTIVE DESCRIPTIONS
Notes:
1.

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 one word.
(When either the efn and/or
ast parameters are specified, the DPB size will be three
words.)

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

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

If the specified event flag is a group global, then the use
count for the event flag's group is run down when a Mark Time
request is canceled.

5-30

DIRECTIVE DESCRIPTIONS

CNCT$
5.3.9

Connect

The Connect directive synchronizes the task issuing the directive with
the exit or emit status of another task (offspring) that is already
active.
Execution of this directive queues an Offspring Control Block
(OCB) to the offspring task, and increments the issuing task's rundown
count (contained in the
issuing task's Task Control Block).
The
rundown count is maintained to indicate the combined total number of

~.C1. ~.·.~. ~. . . . R~ ~~.~p~J.~ c.~pp ~.S·:~~?. •. . ·~···~. ·. . . ?~. ~. ~.PF ip~·.· ·.·~ c:t . ~. ~. ~ \~(ifl.~>\ti&~:Ht~:Q':'.t#·a·~~\;O/·\:n,~•·~~r.r< >.::(~·~
':.V'i~;r:;t·~~·.;l..;;,::ot~·rm~n;~l~···:.::tJi.·~·::·:;;~.:ot:~~~.·o.:·fi~s.;..q·:i.g.a.'f.~4·~
The exit AST routine is

...

. . . ..

··caiied .when. the . offsprlng'. e'x.its 'or .e.mi ts ''status with

the address of
the associated exit status block 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

A
single-precision,
floating-point
containing the offspring task name in
format.

iefn

Event flag to be set when the offspring
or emits status

iast

Name of an AST routine to be called
offspring task exits or emits status

when

the

iesb

Name of an 8-word status block to be written
the offspring task exits or emits status

when

task

Word

Offspring task exit status

Word

TKTN abort code

Word 2-7

variable
Radix-50
exits

Reserved
NOTE

The exit status block defaults to one word.
To use the 8-word exit status block, you
must specify the logical or of the symbol
SP.WX8 and the event flag number in the iefn
parameter above.

iparm

Name of a word to receive the status
when an AST occurs

block

ids

Integer to receive the Directive Status Word

address

Macro Call:
CNCT$

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

tname

Name (RAD50) 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
5-31

set

DIRECTIVE DESCRIPTIONS
east

Address of an AST routine to be called
offspring task exits or emits status

esb

Address of an 8-word status block to be written when
the offspring task exits or emit status
word

Offspring task exit status

word

TKTN abort code

word 2-7

when

the

Reserved
NOTE

The exit status block defaults to one word.
To use the 8-word exit status block, you
must specify the logical or of the symbol
SP.WX8 and the event flag number in the efn
parameter above.
Macro Expansion:
CNCT$
.BYTE
• RAD50
.BYTE
.BYTE
.WORD
.WORD

ALPHA,l,CONAST,STBUF
143.,6
;CNCT$ MACRO DIC, DPB SIZE=6 WORDS
ALPHA
;OFFSPRING TASK NAME
1
;EVENT FLAG NO = 1
16.
;EXIT STATUS BLOCK CONSTANT
CONAST
;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. IEF

Invalid event flag number (EFN<O, or EFN>96 if group
global event flags exist for the task's group; or
EFN>64 if not).

IE.ADP

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

IE. SDP

DIC or DPB size is invalid.

5-32

DIRECTIVE DESCRIPTIONS
Notes:
1.

If the specified event flag is a group global, the use count
for
the event flag's group is incremented to prevent
premature elimination of the event flags.
The use count is
run down when:
•

The connected task returns status

•

The issuing task exits before status is returned

Do not change the virtual mapping of the exit status block
while the connection is in effect.
Doing so may cause
obscure errors since the exit status block is always returned
to the virtual address specified regardless of the physical
address to which it is mapped.

5-33

DIRECTIVE DESCRIPTIONS

·<
:.· · ·.:"_.:\:-.:/:"'
< .··.··::.(:::·.:/
· · · · '··.../•·····.
•· >L : /···. ·•·.
"\<. . :!_:'
,. ...... · ·, ........-.. .-:;-... .... ·.-.· . .:,'

<· .. ,·...

.·. : . . ··

~~~~1<~1tit hQl~h ~~~to~

........

'·

. :, .'·:'':.. .

· .. ·. ·:,

. :... , . .

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

·. . . . ·....... : : ·.· : .... · . ._.···.:, .:· . . . . :··;

s;1:1&
· · /./ •· •·• • <
> {/ i i
• i
i\·
1~i~ Jiik~fi$kiillsikJg;t~iiR~·<~~i~~ ~/~;r~~;~ll~ [~~~0~1~~·i;s~~~a)~i1~i;

·c·o·mJri(>n.·.·•.•~ F~9ipn·.tq•.• ..t:Je c~edkp<>1~1:~d· •• >T~is .• a.irf?C:~iv.~. . · ~~op~ a11.· . . .·t:tn~ ~asKs
·~~~.:t :~r~.11lapp~d • · ~()<th~· <?911t11l()D- .r~<gi()n,••·wrJ:tes·· the.· . cq1:rur1orr•·.·.~e9ioJ'J.··out··: .• ·to'
··•.t·be. di$Rand •. th.¢J1.···. ··urie;tt>Eis>tbe:··•:tasks.,
·
'... _,··,:· ...::..........:::=......... -

·'the 1~?91'@ ;-t,a~k ·must be<. pl"f01i~~ea: ;(~~;\61~
......

•'.The f§~uiri~.·· task must .be: a'ttached to t.ti~·.:specJff~d common region~·:·····

A.nl'

~loc.ke<;f•···· ...•.·.
ta:k (including.•.·.·. th~.•.··is~ui119· tclsk) J.sals() •·blqcked .•. . tf. it
1llG{J?S· t;.o tht:•·. C()1ll¢on reg i()Jl while th~ checkpoJpt is ··.·try progz-e:s •.· ..·. If" th~
tas~.· .... was bui~t•vdth the /CO~MON~ quallfJ~r, the t.ask .... wi11 be. block.ea
whencit.····. tssu~~·····.this directJve •.•.•.... ~f·.the>.task b~comes .. attached •. bY . . . mearys
<.lf:. •. . the. ·. /\t~.ach RegiondirectJve.; :Jt .•. isnot•. blocked . ·unless· Jt·issue>s •a
·Map .·directive~

tb preserve cJ:1anges made .·to a memory
r~sident common reglori~ When a region fscheckP:oint~d, i~is c<:>pled
tp it.s own image .· on
the disk and not ·.to th~ checkpoint file~·
Therefore,· any µpdate to the memory resident copy of the common region

You ca11 use this directive

becomes permanent.

FORTRAN·Call:
CALL. CPCR(name (,ids]}

name = Name

(in

RADSO}

the

common

region

checkpointed

ids

= Directive Status

Macro Call:
name

CPCR$

name = Name of the common reg ion to be checkpointed

Macro Expansion:
CPCR.$

NAME

.BYTE

205 .. , 3
/NAf1E/

!RAD50
Local·· Symbol
C.PCR

5-34

DIRECTIVE DESCRIPTIONS

5-35

DIRECTIVE DESCRIPTIONS

CRAW$
5.3.11

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.) Execution
of this directive unmaps and then eliminates any existing windows that
overlap the specified range of virtual addresses.
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 15
(l~
t.'.o {·',4·3
a~x;fiM';.,.ptti.s. $ys.t\~~·~j.,\' which is an index to the window block
in the task's header. The window block describes the created address
window.

,ort.

~indo,w . •. ln :· s.u~e·rvlsor..,.1tlode .·r-~pap.e• . · • •· ·..Program ·pont:rpl·. . can•· sub~e9.l1ently
b.Ef :trat1st~r:r~fl.•·t:osupe.rylspr-:-It\p~e.,r-..apac.e

CalT .• d .ir:e:ctilve'

r.f : ws. ups ·i~f 'the. Windo't s.tatus word. is
window .. in u~e·r ...,,mo(]eD'"'"'spacer

upon·· iss·qing

a ·•. ·. . su.perv~sor

set, the Eie'Gµtfve 'preat:es

the

If WS.MAP in the window status word is set, the Executive proceeds to
map the window according to the Window Definition Block input
parameters.
A task can specify any length for 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.64B 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.64B = 1, the task can align on 32-word boundaries;
the
programmer can therefore specify any offset within the region.

5-36

DIRECTIVE DESCRIPTIONS

NOTE
Applications dependent on 32-word or
64-byte alignment
(WS.64B = 1) may not
be compatible with future RSX emulators.
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) •
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 0 for task region (to
be specified only if WS.MAP=l).

i wdb ( 5)

W.NOFF

Offset 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.

5-37

of the address

window

DIRECTIVE DESCRIPTIONS

i wdb ( 6)

W.NLEN

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

i wdb ( 7)

W.NSTS

Bit settingsl in the window

status word:

Definition

Bit
WS.MAP

1 if the new window is to
mapped

WS.WRT

1 if the mapping assignment
is to occur with write access

WS.64B

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

Output parameters
i wdb ( 1) ,
bits 0-7

W.NID

ID assigned to the window

i wdb ( 2)

W.NBAS

Virtual address base of the new window

i wd b ( 6)

W.NLEN

Length,
in 32-word
mapped by the window

i wdb ( 7)

W.NSTS

Bit settingsl in the window

blocks,

actually

status word:

Definition (if bit=l)

Bit
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.

not .bypass the cache {for
mult;iprocessor systems).

Do.

WS.RES

Map only if resident.

ct~~fe p·t.ta~l'lment .descripthr

only 1f.he~.~psary•.· {for.·send

.l}y . g~~~r;~pqe q~p~ct.~•Y~·~.) • :

1. If you are a FORTRAN programmer,
refer to Section 3.5.2 to
determine the bit values represented by the symbolic names described.
5-38

DIRECTIVE DESCRIPTIONS
Definition (if bit=l)

Bit
WS.64B

Define the task's permitted
alignment boundaries
0
for 256-word (512-byte)
alignment; or 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.

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 storage
has incurred a parity error.

IE.PRI

Requested access denied at mapping stage.

IE. NVR

Invalid region ID.

IE. ALG

Task specified either an invalid base APR and window
size combination, or an invalid region offset and
length combination in the mapping assignment; or
WS.64B = 0 and the value of W.NOFF is not a multiple
of 8.

IE.WOV

No window

IE.ADP

Part of the DPB
address space.

IE. SDP

DIC or DPB size is invalid.

blocks

available in
or WDB

5-39

because

region

task's header.

is out of the issuing task's

DIRECTIVE DESCRIPTIONS

CRGF$
5.3.12

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 Executive uses the present GFB 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 5.3.20).
If the specified group code matches the group code of the issuing
task's protection UIC {H.CUIC+l), this directive increments the access
count for the event flags.
This locks the event flags so they cannot
be eliminated by another task that is sharing them. The issuing task
can explicitly unlock the event flags with an Unlock Group Global
Event Flags directive or an Eliminate Group Global Event Flags
directive. The Executive automatically unlocks the event flags when
the task exits if necessary. Note that a task may not lock the event
flags more than once in succession. Any attempt to lock event flags
that are already locked will return the IE.RSU error code.
FORTRAN Call:
CALL CRGF ([group] [I ids])
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.

ids

Integer to receive the Directive Status Word.

Macro Call:
CRGF$

[group]

group

Macro Expansion:
CRGF$
.BYTE
.WORD

157. ,2
4

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

Local Symbol Definitions:
C.RGRP -- Group Number (2)

5-40

DIRECTIVE DESCRIPTIONS
DSW Return Codes:

rs.sue

Successful completion.

IE.UPN

Insufficient dynamic storage.

IE.PRI

Privilege violation.

IE.IUI

Invalid group.

IE.RSU

Event flags already exist or are already locked.

IE.APD

Part of the DPB is out of the
space.

IE.DIC

DIC or DPB size is invalid.

issuing

task's

address

Note:
A privileged task may specify group numbers other than the group
UIC of the issuing task. However, the task can only lock the
event flags created for its own group. This directive does not
return an error if it does not lock the event flags.

5-41

DIRECTIVE DESCRIPTIONS

CRRG$
5.3.13

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's program 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, set RS.NOL in the region status word as an
input
parameter.
Be
careful
in considering to override 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.
Named regions in RSX-llM ....PLUS systems are put in the Common Block
Directo,ry HZ.BD). However, m$n:tory is not allqcated until the Executive
maps a task to .the region.
The Executive returns an error if there is not enough space to
accommodate the region in the specified partition.
See Notes below.
FORTRAN Ca 11 :
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 created

5-42

region

DIRECTIVE DESCRIPTIONS
i rd b ( 3 ) ( 4 )

R • GN AM

Name of
the region
for no name

to be created, or 0

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

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 settingsl in the region status

irdb(8)
Output parameters

Bit

Definition

RS.CRR

1 if the region was
successfully created

1. If you are a FORTRAN programmer, refer to Section 3.5.l

the bit values represented by the symbolic names described.
5-43

word:

define

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. PRI

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 = O.

IE.ADP

Part of the DPB or
address space.

IE. SDP

DIC or RDB size is invalid.

RDB

out

issuing

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.

5-44

DIRECTIVE DESCRIPTIONS

Parent tasks can service each offspring input or output request with a
corresponding output or input request to the correct virtual device
unit. For example, .where Macro-11 has been activated as an offspring
task of the Batch Processor with a TI: of VT3:
1.

Macro-il issues an IO.RVB or IO.RLB to TI:
for its first
. input line.
The virtual terminal driver queues the read
request internally and effects an AST in the Batch Processor
at the virtual address "iast" with the unit number 3 and the
byte count from Macro-ll's I/O request on the stack.

5-45

DIRECTIVE DESCRIPTIONS

, tr1.)t·~~ A$T- t6'titfrie} ti1·~·. •·~~tcb····~t"o<!~$$()~··· . . · r~.triey€!s .•.•.·. ~.n.- ., . . i-frput
.Ii,11~:•···· ~or••·.· f.t~crp~~l·•. <from· . ~h~.·.··.~a tsJ1.:streain .••arHJ>,specifies ·. •.this
·~<inE!<in• a'-Qio.aitective' ~o--aLUN··.a~slgnedt:o: ·:V'f3:.
-With··an
lO •.W'VB ,07 :r().\.'IL~ furiqtion., . -a••·bytE7:count··of the lin~,·.·ana< the
•st.a;t !JS\ ;to .be' r:etu.rned .·.··(such-. a$-.IS .CR)·•.·
· ·
··
>. ):; . . . .'-: ..:. . -:.. . :.· : : .> '."·:>·> :-:;=,_-:_ ··< >':;;,:::>:·::.·.;.'.". ',· ::.. ::.-· ..:~~· .·'..·.~::- ::-:> . .-" >:./.. . >:..: ·::.<:·<<> ·. >-·~./: . _,. . ~ .··-.>-:.:-·

3.·· T9e··.·•••·.\1-i.•.~t··l1a1.·····•·••••feitnii.'na•1······•a1·••t•J~.t-··••r'.¢a(js••··.·.•th-e . . .•. .•_.l 1ne··.· .•. :. .•.f·rom .. th·~· sa·tch
·J?r()C~f;.f;<:)X' ~ byffe~,< write~·.·. ~he··•·li11E! >to. -·ttificr.<>711 '.s •. bttf fer, and
tnen .• ••sl911al$ J/O conipletJqn •+pr b()t}:lI/(:)·request~··.•~·
'..<.· . •.·. •.•••.•.• < <>)i··>>•.·. . ·.•· · · >.i , . . < >'<< >>
sfmi~ar~y~,
't£/:r-1acro.--11.x1eE!a$ . to print:,
error mes~age,- ·.·.·. ·tt
doE!s . ·.· .s<> . . . . . • wit;h ..... a,n ...... 19.•.;•.¥1.~·.···<?.F··.·.··.··· rq.~¥1J'..J3 - to Tr:·. The .•·•virtual
y~r:~ipa,1 -9ri.v~r: .•·.·. qpE7P~;~·•······••·.·-t:pe••·•.•< ·~r:Jt:.·.··.•.··.·. r;~tju~st:•.••. •.•.·.·.f riter;f1~lly.···.··•··•.a,r1d
•··.•~.·~·~~p;t;s •. . _an-(~9'.l' --r9.·.th-e.•a~:t:s-n-rt'•p.ce§s{).r•·.•·····at .•. •··t:h-~:vtrtu~1:.-a.~are~s-_
·~•.Pa~t"-·•:.~~-t:}lt:l'l: --up1t:l'l-l1~l:>e;,,.•.•~.f :t:pe pyte- . q().l1l'l•t) ·and:, ··t.hE! VFC
fr9nt . Ma,c'r;.o'""+l}•s' :r:to •··reqt;iest: ioJ1::>the . • .• stack••
,_..
....

·.·,·;··

::··:··.-

·5~ ·····.·~n-Jt:s?.()tit:·p~t Asi~ t6l1~iHe,- •tl'le .. Batch .• •. .• •. P~?c~ess-Ot •1sstie.s an
ro-.JlVJ? . ···p r ·!? .. HLB······ t.d re~r i ey~ the . . . line •. . by.·· .• meaJ1~··o fr the yirti.l.a1

t~rinin~·~c]r~v~r.

··.··The Bptch· J?roc~~~9p··· 1ll~Y.·. .•. •then< o.utpl1t; . ·. t.his
line to itSilO<J file ••. ··. The>th•Jrd t¥Ordpn···.·the [\.~T: stack·.in the
~atch -outp~~ AST routJne .i$. ~he:.·.· vert:ic(il···.··<format .C:haracter,
-telling . Ba,tch ·. what type pf car.riag~ control is expected. for
the·•output .... Iine. Thiswo·rd would·· oe·ignorea •. ·.i-n·· t:he input· AS'r
routine.

not

The Virtual term'ifr~l a~iver does
intefpret: or modify transferred
bytes,. I/O .s\lbfunction codes, Of \rertical··.format chara<,:ters •. ·However,
this driver does cil1tomatically truncate offspring I/O requests to . the
maximum byte count specified in the "mlen" parameter, notifying
neither the parent nor offspring task. The actual number of bytes
transferred on each request is equal to the smaller of the byte counts
specified in the offspring and paren.t I/O requests. The total number
of bytes transferred is returned in the correspondingI/O status
blocks. Note that offspring tasks can receive "mlen" in the fourth
characteristics word when a Get LUN Information directive is issued.
Intermediate buffering in secondary pool, when enabled by the parent
task, is performed on offspring input and output requests when the
offspring task is checkpointable. Offspring tasks, therefore, may be
stopped
and checkpointed.
If the parent task is stopped and
checkpointed when the offspring task issues an I/O request, the
resulting AST brings the parent tas.k to an unstopped state from which
it may return to memory to service the I/O request.
Upon exit from
the. AST routine, the parent task is again stopped. This mode of
operation allows the parent and offsprin9 tasks to . share the same
p}1ysical memory, even while the parent task services> the terminal I/O
requests for the . offspring task •. ·. Whenever, for any reason, the
virtu~J terminal dr~v.er determines that. is. should not ~se intermediate
buffering, offspring tasks are lock~d in memory when· 1;0 requests are
issued, and transfers occur d itectl y between pa rent and offspring
buffers••
.. .

.. . . .

The Intermediate buffering of offs_pflng )/O requests can. normally be
enabled. ?nd disabled . by the pare;nt task. by the ·IO .. STC Junctiqp, as
described below. An excepti9n to t.hi:s exists • for . . . virtual ... terrnlf:lals
created with a umlen•• parameter• g:reater than.a .system.;;;wide maximum
-specified at Sys9en tfn1e. ·.. tsysgen 49e$ not allow.thfsfuaximun1. ·. to be
'greater th<ln .. 5124'.) ,If •••a Create··vtrtual -Terminal .. directive is. specified
wit:h a u~len" parameter great.er.· than f,:he systeiri-wide . maximum, the
parameter is accepted, but Jn.;~.-r-l1J~diate buffet:"ing for the created
yirtual _. t~rmin~l t,lnit is' autol1lat~·c.ally disabled.
.· Fuxtheptrore. ,
intermediate . buffE!ring . for that.unJ:t ·pannot be enabled by the'parent
tasJ< . by th~ . I()~S'f.C funct:i9n .. _

5-46

DIRECTIVE DESCRIPTIONS

purpose.
requests;
the same
is clear,
flag:
e

If. bit 0 is clear and bit l is
offspring I/O is disabled.

•

If bit 0 is clear and bit 1 is clear, buffering is enabled.

5-47

DIRECTIVE DESCRIPTIONS

:·.:ku.·.f fe:r'5.h·~•. :•.·c:an~6i.t•.··· b.~··.·.··.•ena·b:·i:~h.·····•8n••·.•·ia:··.:·.:v.•ir.1:ua·.l•.•·.:·. ·.'t:e:rm1.n~I:.•.·.·un•.•rt ... ttle·i:. .. .t1?•~···•·.·.·.~·e·~.11
createcl .•. ·witp a;~1 ''111ien" pa.ra1neter. gre~ter thar1 . . t~e systerrt~Wide. maximum
·specJfied ·at sysgen time~ An attempt to· do both.· results In. an error
return . of IE •.. IE'C.

:The only t?sk;s tn?t can :as$fgn . L.UNs to a. virtual. terminal J1I'l.tt

... Th~··/·.•·.t:··~·s.·~:···.·•.·.·•t~a·.·t·······.c=·.·r··:·~ted. ··thi·······Ji·r··.~.~~i·•·•i.·.~b.fmina.i.·······.··tn. i.•t·.•.:. ·.:
.

,. : .. ·.

.· ... : . ,. :.· ... , ..<·. ·.·. '. ,... : ... :. · ..... _.,

, ~: :.'.:

.-= .. ··:,:- ·'_;'_;

.• 'I'h~1: it~sk's.6Jfspririg ·: ~ask(s.r, · kha.~~ .·,-It.

·.····· .... · ··.· ..... ·t.erllllrialu~tt ...

·.)

th~: .vfrtu.?ll

•. : .:>.···>·

•~tt:achme:niti~f .··.·?····vi.r.t\1~1 ... t~t-~iKai··.••uniFihy(an ..... ·o..ffspi1119·· ··ta$~ ..·.· ·t>s~v~n~s
t:f1~·•d~q~eulng :()f.· .··•~/CJ . .r eque~t~ ~P·•···:tt1ati.1?it: . frolt\ 6.~her ·ci.f·+$p;rJhg: ::ipa ~ks ;
~

paren~<I/O.·. re.qµe.sts:.a;re . . always ... ~~rvlc~d. ·

.. :;:·· :. .-··:: . . · .;· -..:.::-.= :: .': ;. , ... ::.-. :.·.·-: :...::·:. '. : ·.:· :'.: .."' :, . .····.-.-: .. <:-: .. ·..... :- ..... ,·_. . ,=··:.:= ··<.

:.··::-_ . . ·.. ·.= .::- .· ··:::·:: .. ..:-::""_"._: .. ·.::

130.•th··•. :•·~e1·. rel1.'f:··.·····?nd·.·.······oifs.pr.• 1ric) .·.· .·t·~.•sks·.·.·.···c.at1.··.·.····.spec·1.·f:•y.····.•.•·ith.~· · ±•Jo .

f·.~n~··.t:i··~~~

I•9.····GTS.;r

s~.GMC., . . an.a··s~~sMc .. ·... Iio\\feve'F·, ~F~GM.can,cl ·sF •.st~lQ :S\lPJ?or·#· bn1y··a· limited
·num~er .. of.··.· 'f:e.:r1ninal ....·char.act:er.ist:ic.s; <.for .·.· vi;r.tual.·•·.·.· . termi11.als···:
Please

refex::t<>.·. the . Rsx~llM/M-PLUST/O ·Privers ·R:eference Mariualfor: a list .of
. valid ch:aracter1st1.cs.
-.Note .that the .I?Ci~ent • tas.~ i.~ not
any: of the above di;rectives.

otifspring. · . issues

When an .··offspring ta9k:issues ·~···. read-with-prolllp~· reque~t . (ici.RPR) ,: i:he
virtual terminal driver separates the request into an 10.WLB request
and an IO.RLB request. The parent task cannot: issue an . . JO.RPR.
When a virtual terminal is iri half-duplex mode, the virtual terminal
driver .handles only . . one offspring request at a time. fpr example, .if
the offspring task issues a read request and then issues a write
request without waiting for the read to. be completed, the driver
queues the write request to be processed when.the read is completed.
The parent task may issue an SF. SMC function to set the virtual
terminal to full-duplex mode. In full-duplex mode, the write request
in the previous example would be processed even if the previous read
was not yet completed •. If the parent task is at AST state, it will
not receive notification of the I/O request.
Both parent and offspring tasks can issue an SF .GMC request .to
getermine the mode of the virtual terminal. Howey er, only the parent
task c<;tn change the mode (using SF.SMC).
FOR'I'RAN .. Ca 11:

( [ Hastl, [ioast] ,[iaast], f.imlen] ,iparm·, [ids] )
.wh1ch input
= AsT··address····af·
tasks are·. serviced
AST address at. wbiph output; requests
tasks '.are serviced:

from :offs pr irig

a1: whicli .. tl1~ p(lfe.nt 'l:ask may''be . not:Iffed
of . . thecoinpletipnpf Sl)CC~ssful offspring c:ittach .and
detach requests to. the··virtual.·. terminal.:unit

AST address

.NO'I'E .
O.f the
paramete,.['s
should . .
be
: otherwise, the virtual. t.erminal
···treated as the null device.

5-48

DIRECTIVE DESCRIPTIONS

5-49

DIRECTIVE DESCRIPTIONS

5-50

DIRECTIVE DESCRIPTIONS

CSRQ$
5.3.15

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 or DCL Run command.
In a multiuser protection system, a nonprivileged task can cancel
time-based initiation requests only for a task with the same TI:.
FORTRAN Call:
CALL CANALL (tsk [,ids])tsk
ids

Task name
=

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 "ALPHA"

Local Symbol Definitions:
C.SRTN

Target task name (4)

DSW Return Codes:

rs. sue

Successful completion.

IE. INS

Task is not installed.

IE. PRI

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. SDP

DIC or DPB size is invalid.

attempting
address

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

#TNAME,,ERR

TNAME: .RAD50

;CANCEL REQUESTS FOR "ALPHA"

/ALPHA/

5-51

DIRECTIVE DESCRIPTIONS

DECL$
5.3.16

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.
Use this directive 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
.BYTE
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:
IS. 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

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

5-52

because

this

directive

DIRECTIVE DESCRIPTIONS

DSAR$
or

IHAR$S
5.3.17

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 disable AST recognition directive
whenever an AST service routine is executing. When a task's execution
is started, AST recognition is enabled.
See Notes belowo
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 ) + , - (S P )
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. ITS

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

5-53

DIRECTIVE DESCRIPTIONS
Notes:
1.

This directive disables only the recognition of ASTs;
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
5.3.24), 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
controlled by 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.

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 that of the DIR$ macro.

5-54

DIRECTIVE DESCRIPTIONS

DSCP$S
5.3.18

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. Only the affected task can issue this directive.
A task cannot disable the ability of another task to be checkpointed.
FORTRAN Call:
CALL DISCKP [(ids)]
ids

Directive status

Macro Call:
DSCP$S
err

[err]
Error routine address

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

ERR
(PC ) + , - (S P )
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 II 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:
started,
is
task can be

When a
checkpointable
task's
execution
checkpointing
is
enabled
(that is, the
checkpo inted) •

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 that of the DIR$ macro.

5-55

DIRECTIVE DESCRIPTIONS

DTRG$
5.3.19

Detach Region

The Detach Region directive detaches the issuing task from
a
specified, 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
deletion.
FORTRAN 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

Macro 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

Off set

irdb(l)

R.GID

ID of the region to be detached

irdb(7)

R.GSTS

Bit settingsl in the region status word:
Bit
RS.MDL

Definition
1 if the region should be marked
for deletion when the last task
detaches from it

1. If you are a FORTRAN programmer, refer to Section 3.5.1 to
determine the bit values represented by the symbolic names described.
5-56

DIRECTIVE DESCRIPTIONS
Output parameters:
irdb(7)

R.GSTS

Bit settings! in the region status word:
Bit
RS.UNM

Definition
1 if

any

windows

were unmapped

Local Symbol Definitions:
D.TRBA

Region Definition Block address (2)

DSW Return Codes:

rs.sue

Successful completion.

IE. PR!

The task, which is not attached with delete access,
has attempted to mark the region for deletion on the
M.st q~.tac~r?I" tl1~.·.·. t~~k .•. . . Pf!~ qutstanqi.qg··•· J:/9 ...'.•(riqt•
···p~,9~.~~.~I.~.1y.·,...t:fr . . ,,F:g~.~\:·r;~g.~.gQ,.·p.n . ;<'R§X~ll"1·: . $y$·t~~sxgl':llYl •.;,: ·
<

IE.NVR

The task specified an invalid region ID or
to detach region 0 (its own task reg ion) •

IE.ADP

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

IE. SDP

DIC or DPB size is invalid.

attempted

issuing

task's

1. If you are a FORTRAN programmer, refer to Section 3.5.1 to
determine the bit values represented by the symbolic names described.
5-57

DIRECTIVE DESCRIPTIONS

ELAW$
5.3.20

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.
FORTRAN Call:
CALL ELAW {iwdb[,ids])
iwdb

An 8-word integer array containing a Window Definition
Block {see Section 3.5.2.2)

ids

Directive status

Macro Call:
ELAW$

wdb
Window Definition Block address

wdb

Macro Expansion:
ELAW$
.BYTE
.WORD

WDBADR
119.,2

WDBADR

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

Window Definition Block Parameters:
Input parameters:
Array
Element

Off set

iwdb(l)
bits 0-7

W.NID

ID of the address window to be eliminated

W.NSTS

Bit settingsl in the window status word:

Output parameters
iwdb(7)

Bit

Definition

WS.ELW

1 if the address window
successfully eliminated

was

WS.UNM

l if the address
unmapped

was

window

1. If you are a FORTRAN programmer, refer to Section 3.5.2 to
determine the bit values represented by the symbolic names described.
5-58

DIRECTIVE DESCRIPTIONS
Local Symbol Definitions:
E.LABA

Window Definition Block address (2)

DSW Return Codes:

Is. sue

Successful completion.

IE. NVW

Invalid address window ID.

IE.ADP

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

IE. SDP

DIC or DPB size is invalid.

5-59

DIRECTIVE DESCRIPTIONS

ELGF$
5.3.21

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 using the
group-global event flags (the use 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
using 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 using the 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.
If the specified group code matches the group code of the issuing
task's protection UIC and the event flags are locked by this task (by
a previous Create Group Global Event Flags directive), this directive
unlocks the event flags by decrementing the access count. Note that a
task may not unlock the event flags more than once in succession. Any
attempt to unlock event flags that are already unlocked will return
the IE.RSU error code.
FORTRAN Call:
CALL ELGF ( [group] [,ids] )
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.

group

ids

Integer to receive the Directive Status Word.

Macro Call:
ELGF$
group

[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)

5-60

DIRECTIVE DESCRIPTIONS

DSW Return Codes:

rs.sue

Successful completion.

IE.PR!

Privilege violation.

IE. IUI

Invalid group (group>377 octal).

IE. IEF

Group is not founde

IE.RSU

Event flags are already marked for deletion.

IE.ADP

Part of the DPB is out of the
space.

issuing

task's

address

IE.DIC -- DIC or DPB size is invalid.

.......

5-61

DIRECTIVE DESCRIPTIONS

ids

Integer to receive the, Directive Status Word

Macro Call:
ELVT$

unum

= Unit number of the 'virtual terminal to be eliminated.
The task must provide this parameter
virtual terminal is created (see Note).

Macro Expansion:

5-62

after

the

DIRECTIVE DESCRIPTIONS

5-63

DIRECTIVE DESCRIPTIONS

EMST$
5.3.23

Emit Status

The Emit Status directive returns the specified 16-bit quantity to the
specified connected task.
It possibly sets an event flag or declares
an AST if previously specified by the connected task in a Send,
Request And Connect, a Spawn, or a Connect directive.
If the
specified task is multiply connected to the task issuing this
directive, the first
(oldest)
Offspring control Block (OCB) in the
queue is used to return status. If no task name is specified, this
action is taken for all tasks that are connected to the issuing task
at that time.
In any case, whenever status is emitted to one or more
tasks, those tasks no longer remain connected to the task issuing the
Emit Status directive.
FORTRAN Call:
CALL EMST ([rtname],status[,ids])
rtname

Name of a task connected to the
which the status is to be emitted

status

= A 16-bit quantity to be returned

issuing

task

connected

the

task

Integer to receive the Directive Status Word

ids
Macro Call:
EMST$

[tname],status

tname

Name of a task connected to the
which the status is to be emitted

issuing

task

status

16-bit quantity to be returned to the connected task

Macro Expansion:
EMST$
.BYTE
.RAD50
.WORD

ALPHA,STWD
147.,4
ALPHA
STWD

;EMST$ MACRO DIC, DPB SIZE=4 WORDS
;NAME OF CONNECTED TASK TO RECEIVE STATUS
;VALUE OF STATUS TO BE RETURNED

Local Symbol Definitions:
E.MSTN

Task name (4)

E,,MSST

Status to be returned (2)

DSW Return Codes:

rs. sue

Successful completion.

IE.ITS

The specified task is not connected
task.

the

issuing

IE.ADP

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

address

IE. SDP

DIC or DPB size is invalid.

5-64

DIRECTIVE DESCRIPTIONS

ENAR$S
5.3.24

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.
FORTRAN 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 ) + , - ( S P )
101., 1

377
• +6

PC, ERR

;PUSH DPB ONTO THE STACK
;ENAR$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

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 that of the DIR$ macro.

The FORTRAN calls DSASTR (or INASTR) (see Section 5.3.17) 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 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.

5-65

DIRECTIVE DESCRIPTIONS

ENCP$S
5.3.25

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.
This
directive cannot be used to enable checkpointing of a task that was
built noncheckpointable.
FORTRAN Call:
CALL ENACKP [(ids)]
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.,1
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:
IS. 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 that of the DIR$ macro.

5-66

DIRECTIVE DESCRIPTIONS

EXIF$
5.3.26

Exit If

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 Expansion:
EXIF$
.BYTE
• WORD

52.
53.,2
52 •

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

Local Symbol Definitions:
E.XFEF

Event flag number (2)

DSW Return Codes:
IS.SET

Indicated EFN set;

task did not exit.

IE. IEF

Invalid event flag number (EFN<l, or EFN>96, if group
global event flags exist for the task's group; or
EFN>64 if not).

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 Exit If directive is useful in avoiding a possible race
condition that can occur between two tasks communicating by
means of 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.

5-67

DIRECTIVE DESCRIPTIONS
2.

A FORTRAN program that issues the Exit If call must first
close all files by issuing Close calls. See the IAS/RSX-11
FORTRAN IV or FORTRAN IV-PLUS User's Guide for instructions
on how ~o---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 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.

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

particular,

•

Detaches all attached devices

•

Flushes the AST queue and despecifies all specified ASTs

•

Flushes the receive and receive-by-reference queues

•

Flushes the clock queue
requests for the task

•

Closes all open files (files open
locked)

•

Detaches all attached regions, except in
fixed task

•

Runs down the task's I/O

•

Deaccesses the group global event
group

•

Disconnects from interrupts

•

Flushes all outstanding CLI command buffers for the task

•

Breaks the connection with any offspring tasks

•

Returns a success status (EX$SUC) to any parent tasks

•
•
4.

for

any

outstanding

Mark

Time

for

write

access

are

the

case

for

the

task's

flags

M.a.r~si.fo.r d.~.~If(Jbai:..f~~.·.·a.~t..v~ituai·· t:~rnd.#~1 ·1.lnit·s··•ifie task

l'.l~9. <::~~~fe<l·· .f~~~ 9e·~.~i9J.l.\?•: ~) ·

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

If the task
event.

exits,

the

Executive

5-68

declares

significant

DIRECTIVE DESCRIPTIONS

EXIT$S
5.3.27

Task Exit ($S Form Recommended)

The Task Exit directive instructs
execution of the issuing task.

the

system

terminate

the

FORTRAN Call:
See Note 5 below.
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:
1.

A return to the task 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, since the
return will only occur with carry set.

Exit causes a significant event to be declared.

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

particular,

•

Detaches all attached devices

•

Flushes the AST queue and despecifies all specified ASTs

•

Flushes the receive and receive-by-reference queues

•

Flushes the clock queue
requests for the task

•

Closes ail open files (files open
locked)

5-69

for

any

outstanding

Mark

Time

for

access

are

write

DIRECTIVE DESCRIPTIONS
•

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

•

Runs down the task's I/O

•

Deaccesses the group global event
group

•

Disconnects from interrupts

•

Flushes all outstanding CLI command buffers for the task

•

Breaks the connection with any offspring tasks

•

Returns a success code (EX$SUC) to any parent task

•

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

flags

the

case

for

the

task's

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 that of the DIR$ macro.

You can terminate FORTRAN tasks with the STOP statement or
with CALL EXIT.
CALL EXIT is a FORTRAN OTS routine that
closes open files and performs other cleanup before it issues
an EXIT$S directive (or an EXST$ directive in FORTRAN
IV-PLUS).
FORTRAN tasks that terminate with the
STOP
statement result 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):
TT37 -- STOP THIS FORTRAN TASK

5-70

tasks

TI:

DIRECTIVE DESCRIPTIONS

EXST$
5.3.28

Exit With Status

The Exit With Status directive causes the issuing task to exit,
passing a 16-bit status back to all tasks connected (by the Spawn,
Connect, or Send, Request And Connect directive). If the issuing 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 . .•.~?E .Ci.~X

~~.~ ~~n.' ...·. ·.·..•~.•. ·.·.•.·.~ ~:~·.t.~s· ·.· · .·.~·.•.f·.·•· .·•·•.·.~.•~. ~s.·E·~····· ~.~i···.r.:~t.~.•~?~?·.··· t:~ . •. . . •~.~. ~·.·.·······J?~.~t~•.•t···· .:~~.s k • Fur
·X:w~i§:\;,,.v.~d;.9o~Y
the rm ore ,

\(.t~;§··..':;i.:~.1::~·?;,·p~\~:.~.~~l::.:Fl'·~L·~.:>~.~~;;$~.\\l~{~J~./.·~:;;b.~~.·~:~/:;.,1~.~ ·:;.F?:~;;·¢:~:'..:·p~.~.~.~;$,~.~5,'.·.t.:.

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.
FORTRAN Call:
CALL EXST (istat)
is tat

A 16-bit quantity to be returned to parent task

Macro Call:
EXST$

status

A 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. SDP

DIC or DPB size is invalid.

5-71

completed
address

DIRECTIVE DESCRIPTIONS
Notes:
1.

The executive does the following to free a
on Exit:

task's

resources

•

Detaches all attached devices

•

Flushes the AST queue and despecifies all specified ASTs

•

Flushes the Receive and Receive-by-reference queues

•

Flushes the clock queue
requests for the task

for

any

all open files (files open
• Closes
locked)

outstanding

Mark

Time

for

access

are

write

all attached regions except in the case of a
• Detaches
fixed task
•

Runs down the task's I/O

•

Deaccesses the group global event
group

•

Disconnects from interrupts

•

Flushes all outstanding CLI command buffers for the task

•

Breaks the connection with any offspring tasks

•

Returns the specified exit status to any parent tasks

flags

for

the

task's

,(1~$ .·f()'fc•.• ~~~ll:o6~t'
.~n.~·.H,·~a~'%.'•.•n~~·l.·.,~·.l'J·~·<1:~~g
•
2.

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

If the task
event.

exits,

the

executive

5-72

declares

significant

DIRECTIVE DESCRIPTIONS

EXTK$
5.3.29

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 or
specifies an increment value of zero, the Executive makes the issuing
task's size equal to its installed size. The issuing task must be
running
in
a system-controlled partition 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, and 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 DCL command SET EXTENSION LIMIT or
the size of the partition in which it is running&
(See the
RSX-llM/M-PLUS MCR Oterations Manual or the RSX-llM/M-PLUS
Command Language Manua .)

•

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 overlays cannot reduce
size below the highest window in the task partition.

overlays

cannot

its

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

ids

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

Directive status

5-73

DIRECTIVE DESCRIPTIONS
Macro Call:
[inc]

EXTK$
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

Macro Expansion:
EXTK$
.BYTE
.WORD

.WORD

89.,3

;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:
IS. sue

Successful completion.

IE. UPN

Insufficient dynamic memory, or insufficient space in
a checkpoint file.

IE.ITS

The issuing task is
controlled partition.

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 DCL
SET EXTENSION LIMIT command; or the task tried to
increase its- size to the extent that one virtual
address window would overlap another;
or the task
has memory-resident overlays and it attempted to
reduce its size below the highest window mapped to
the task partition.

not

, ..................... ""

running

system

pa·~ti.pl9tj·~

~E~RSU

IE. !OP

I/O is in progress for this task 'e~~;l:.i#~·~J:l~

IE.CKP

The issuing task is not checkpointable and
a positive integer.

IE. NSW

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

IE.ADP

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

IE. SOP

DIC or DPB size is invalid.

5-74

specified

address

DIRECTIVE DESCRIPTIONS

GCCI$
5.3.30

Get Command for Command Interpreter

The Get Command for Command Interpreter directive instructs the system
to retrieve a command buffer for a Command Line Interpreter (CLI) task
and copy it to a buffer in the task's address space.
Information
about the issuing terminal can also be returned to the CLI task.
Only CLI tasks can issue this directive.
FORTRAN Call:
CALL GTCMCI (icbf,icbfl,[iibuf], [iibfl], [iaddr], [incp] [,ids])
icbf

Name of a byte array to receive the command

icbfl = Integer containing the size of the icbf array in bytes
iibuf = Name of an integer
information buffer

array

receive

the

optional

iibfl = Name of an integer containing the length of the
optional information buffer. If you specify a length
shorter than
the
information
buffer,
as
much
information as will fit in the length you specified is
returned.
iaddr = Name of an integer that contains the address in pool of
the command desired.
This address was obtained by a
previous call to GTCMCI with GC.CND specified.
incp

= Name of an integer containing a bit mask indicating the

action to take if there is no command queued:
Bit

Octal
Value

GC.CCS

000

Return with carry set (default).

GC.CEX

001

Force CLI
returning.

exit

instead

GC.CST

002

Force CLI
returning.

stop

instead

GC.CND

200

Copy command into buffer but
dequeue it from the list.

Definition

You must specify these
FORTRAN program.
ids

decimal

values

= Integer to receive the Directive Status Word

Macro Call:
GCCI$ cbuf,cbfl,[ibuf] ,[ibfl],[addr] ,[ncp]
cbuf

= Address of buffer to receive command string

5-75

not

your

DIRECTIVE DESCRIPTIONS
cbfl
ibuf

Address of buffer to receive information on the issuing
terminal

ibfl

Length of buffer to receive information

addr

ncp

= Address of command.
This address is returned in G.CCCA of the
information
buffer if GC.CND is specified in the ncp argument.
If
this argument is nonzero then only the command with the
address specified by this argument is copied and/or
dequeued. Note that this address is only filled in if
the command is not dequeued.

Action to take if no command buffer present:
Bit

Octal
Value

GC.CCS

000

Return with carry set (default).

GC.CEX

001

Force CLI
returning.

exit

instead

GC.CST

002

Force CLI
returning.

stop

instead

GC.CND

200

Copy command into buff er but
dequeue it from the list.

Definition

NOTE
GC.CND can be supplied with one of
the other options, for example,
GC.CND!GC.CEX.
Command Buffer Format:
G.CCDV

ASCII device name of issuing terminal

(2)

G.CCCT

Number of characters (1)

G.CCUN

Octal unit number of issuing terminal

G.CCCL

Number of characters in command line (2)

G.CCFL

Flags (1)

(1)

The values returned in the flag byte, G.CCFL, are:
Flag
GC.CNL =
GC.CTE =

Definition

Value

.J.

Null command line
Prompt from a task exit

5-76

not

DIRECTIVE DESCRIPTIONS
G.CCTC

Terminator (1)
command text in ASCII :(sp>'_l:)yb(:! :::c)n: :,~_$x:...1114 - :~ys~:elnsi

G.CCBF

}:!~i~:~,,f~~~~!HiI~~::Il'~~~It±;~!~~~~~:ll'.i~:t~l~1~~~;l

Information Buffer Format:
The format of the information buffer
space is:

G.CCW2

u.cw2 of 'issuing terminal

(2)

G.CCPT

Name of parent task (if any)

the

CL!

address

task

(4)

Address of offspring control block from parent (2)
G.CCPU

GeCCCU

Current UIC of issuing terminal (2)

G.CCCA

Address of command, if not dequeued (2)

Macro expansion:
GCCI$
.BYTE
.BYTE
.BYTE
.WORD
.WORD
.WORD
.WORD
.WORD

CBUF,CBFL,IBUF,IBFL,ADDR,NCP
127.,7.
;DIC= 127., DPB SIZE=? WORDS
NCP
;ACTION TO TAKE IF NO COMMAND QUEUED
0

;ADDRESS OF COMMAND
;COMMAND BUFFER ADDRESS
;COMMAND BUFFER LENGTH
;INFORMATION BUFFER ADDRESS
;INFORMATION BUFFER LENGTH

ADDR
CBUF
CBFL
IBUF
IBFL

Local Symbol Definitions:
G.CCNC

Action if no command queued (2)

G.CCAD

Address of command to be returned (2)

G.CCBA

Address of command buffer

G.CCBL

Length of task's command buffer (2)

G.CCIA

Address of optional information buffer (2)

G. CCIL

Length of optional information buffer (2)

(2)

DSW Return Codes:
the

The stop-on-no-command option was
directive was issued from AST state.

IE.PR!

Task is not a CLI.

IE.RSU

The issuing task has a group global context active
and next command to be received would have caused the
task's protection group to have changed.

5-77

set

and

IE.AST

DIRECTIVE DESCRIPTIONS
IE.ITS

No command was queued for the CLI and the directive
was issued with the return-with-carry-set option.

IS.CLR

Returned with carry clear when the CLI was unstopped
due to command arrival, after having been stopped by
a GCII$ with the stop-on-no-command-option set.

IE.ADP

DPB, send buffer or information buffer was outside
the task's address space, or the information buffer
was shorter than nine bytes.

IE.SOP

DIC and DPB size is invalid.

Notes:
1.

The number of characters returned (G.CCCT) could be less than
the number of characters in the command (G.CCCL) if the
length of the command buffer in the task, as specified by
cbfl argument,
is smaller than the actual command line.
If
there is sufficient room, a carriage return is placed at the
end of the command line returned at G.CCBF in the command
buffer inside the task to ease parsing.

If a command is successfully returned, the protection and
default UICs for
the
issuing task are changed by this
directive to match the UICs of the originating terminal.
These UICs are returned
in words G.CCPU and G.CCCU of the
optional information buffer.

5-78

DIRECTIVE DESCRIPTIONS

GCll$
S.3.31

Get Command Interpreter Information

The Get Command Interpreter Information directive instructs the system
to fill a buffer with information about a specified CLI or the CLI
associated with a given terminal. A task must be privileged in order
to issue this directive for any terminal other than its own TI:, or a
CLI to which its TI: is not set.
FORTRAN Call:
CALL GETCII (ibuf,ibfl,[icii],[idev],[iunitj [,ids])
ibuf
ibfl

Name of an integer array to receive the CLI
information
=

icli
idev

Length in bytes of the integer array to receive the
CLI information
Name of a two-word array element containing the
Radix-SO name of the CLI

Name of an integer containing the ASCII name of
terminal {default= TI:)

iunit

Name of an integer containing the Octal unit number
of terminal

ids

Directive status

MACRO Call:
GCII$ buf,bufl,[cli],[dev,unit]
buf

Address of buffer to receive information

bufl

Length of information buffer

cli

Name in Radix-SO of the CLI that information is
requested on

dev

ASCII name of terminal whose CLI should be used
{default= TI:)

unit

Octal unit number of terminal

Information Buffer Format:
G.CICL

Name of CLI

G.CICS

Bit settings in the CLI status word:
Bit

Value

Definition

CP.NUL=
CP.MSG=
CP.LGO=

CP. DSB=

Pass empty command lines to CLI.
CLI wants system messages.
CLI wants commands from logged-off
terminals.
CLI is disabled. {Note that MCR
does not check this bit.)

2
4

S-79

DIRECTIVE DESCRIPTIONS
Bit

Value

Definition

CP.PRV=

CP.SGL=

User must be privileged to set
ter.minal to this CL!.
Don't
handle
continuations.

CP. NIO=

100

MCR ••• , HEL,
BYE do no I/O to
terminal;
HEL,
BYE also do not
set CL!, and so forth.

CP.RST=

200

Restricted access; only this CL!
task can set a terminal to this
CL!.

CP.EXT=

400

Pass task exit prompt requests
CL!.

1\lways·.· set.•. •. Qn··.·•.R$~..,.ll:M .. sys:tems.

G.CITK

Name of task serving as CL!

G.CIW2

Terminal's U.CW2

G.CIPU

Terminal's protection UIC

G.CICU

Terminal's current UIC

G.CIDP

CL! default prompt string (16-byte block.
is length of string.)

First byte

Macro Expansion:
GCII$ buf ,bufl,cli,dev,unit
.BYTE
.WORD
.WORD
• RADSO
.ASCII
.WORD

173,7
buf
bu fl
/cli/
/dev/
unit

;DIC to be supplied. DPB SIZE=S
;ADDRESS OF BUFFER
;LENGTH OF BUFFER
;RADSO NAME OF CL!
;ASCII NAME OF TERMINAL
;TERMINAL UNIT NUMBER

DSW Returns:
IE.MAP

Both a terminal and a CL! were specified.

IE. INS

Specified CL! does not exist.

IE .. IDU

Specified device was
exist.

IE. PR!

Nonprivileged task attempted to get information on
CL! other than it's own.

IE.ADP

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

IE. SDP

DIC or DPB size is invalid.

not

was

terminal

out

the

does

not
a

issuing

Notes:
1.

If the buffer is not long enough to contain all the
information, the data that does not fit will not be supplied.
No indication of this is returned to the issuing task.
The
buffer is filled from left to right.

You may not specify both a CLI and a terminal.
If tha cli
argument is present, the dev and unit arguments must be zero.

5-80

DIRECTIVE DESCRIPTIONS

GLUN$
5.3.32

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

A 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

Word

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

First device characteristics word:
Bit 0

Record-oriented device
(DV. REC, l=yes) [FD. REC] 1

Bit 1

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

Bit 2

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

Bit 3

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

Bit 4

Single directory device
(DV. SDI, l=yes) [FD. SDI]

Bit 5

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

Bit 6

Mass storage device (DV.MSD,l=yes)

Bit 7

User-mode diagnostics supported (DV.UMD,l=yes)

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

DIRECTIVE DESCRIPTIONS
Bit 8

Device supports extended
controller (DV.EXT,l=yes)

Bit 9

Unit software write-locked (DV.SWL,l=yes)

Bit 10

Input spooled device {DV.ISP,l=yes)

Bit 11

Output spooled device (DV.OSP,l=yes)

Bit 12

Pseudo device (DV.PSE,l=yes)

Bit 13

Device mountable as a
channel (DV.COM,l=yes)

Bit 14 --

Device mountable
(DV.Fll, l=yes)

Bit 15

Device mountable (DV.MNT,l=yes)

22-bit

UNIBUS

communications
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
(normally
buffer-size as specified in the MCR or DCL SET/BUFF
command)

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 (2)

G.LUBA

Buffer address (2)

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

Device name (2)

G.LUNU

Device unit number (1)

G. LUFB

Flags byte (1)

G., LUCW

Four device characteristics words (8)

the

LUN

the

issuing

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
task's address space.

IE;SDP

DIC or DPB size is invalid=

5-82

out

DIRECTIVE DESCRIPTIONS

5-83

DIRECTIVE DESCRIPTIONS

GMCR$
5.3.33

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 described in the RSX-llM/M-PLUS MCR
Operations Manual.)
FORTRAN Call:
CALL GETMCR (buf[,ids])
buf

An 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.

5-84

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 lowercase to uppercase

•

Remove all trailing blanks

The terminator (<CR> or <ESC>) is the last character
line.

5-85

the

DPB

the

DIRECTIVE DESCRIPTIONS

GMCX$
5.3.34

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 5.3.11). 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 this 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 re-create
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.
FORTRAN Call:
CALL GMCX (imcx[,ids])
imcx

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 Is header. The maximum size
l.s 8*8+1=65> words on . RSX-lH.f>systems. ·Tl)~!_ ma)t:1mum

"s~.:~~· .'~:$:>a·~~~:t;#f*~~-: :~n

ids

Directive status.

5-86

Rsx+11M+Pt:os :~·¥'.$~~~s·:~

DIRECTIVE DESCRIPTIONS
Macro Call:
GMCX$
wvec

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

iwdb(l)
bits 0-7

W.NID

ID of address window

i wdb ( 1)
bits 8-15

W.NAPR

Base APR of the window

iwdb(2)

W.NBAS

Base virtual address of the window

i wdb ( 3)

W.NSIZ

Size, in 32-word blocks, of the window

i wdb ( 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

i wdb ( 6)

W.NLEN

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

i wdb ( 7)

W.NSTS

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

Definition

WS.MAP

1 if the window is mapped

WS.WRT

1 if the window
with write access

ws.sis

1 if the window is mapped in
supervisor-mode
instruction
space

mapped

1. If you are a FORTRAN programmer, refer to Section 3.5.2 to
determine the bit values represented by the symbolic names described.
5-87

DIRECTIVE DESCRIPTIONS
Definition

Bit
WS.UDS

1 if the window is mapped
user-mode data space

WS.NBP

1 if the window was created
with cache bypass disabled
(on multiprocessor
systems
only)

WS.RCX

1 if cache bypass has been
enabled
for
the
current
mapping of the window (on
multiprocessor systems only)

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.
Local Symbol Definitions:
G.MCVA

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

window

DSW Return Codes:

rs.sue

Successful completion.

IE.ADP

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

IE. SDP

DIC or DPB size is invalid.

r>iie to t.he
•may n:~'ed' to".,
:lssue a dRAw$ · or

<)niy.')

the ws. RCX .to· indicate cache--bypa.ss s·tat.e,.. · you
additibn:a"l!
:a11·t'p~~:.at:t9·n'• o'f• 't'lle· . . ttDB•·. be!f~·r·~'··~()U
1

MAP$

•· , {O~

:di.re

5-88

mul tlprocess<>P

.~Ys.;t;.~1ll~,

DIRECTIVE DESCRIPTIONS

GPRT$
5.3.35

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

A 3-word integer array to receive partition parameters

ids

Directive status

Macro Call:
GPRT$

[prt] ,buf

prt

Partition name

buf

Address of a 3-word buffer

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
• RAD50
.WORD

ALPHA, DATBUF
65.,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)

5-89

DIRECTIVE DESCRIPTIONS
The following offsets are assigned
partition parameters buffer:

relative

the

G.PRPB

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

G.PRPS

Partition size expressed as
blocks (2)

G.PRFW

Partition flags word (2)

start

the

expressed

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.
In
unmapped systems, the address is physical.
In mapped systems,
the returned address is virtual and is always zero if it is not
the task partition. Unsuccessful completion is indicated by a
set Carry bit and one of the following codes in the DSW:
IE.INS

Specified partition not in system.

IE.ADP

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

IE.SOP

DIC or DPB size is invalid.

the

issuing

Notes:
1.

For Executives that support the memory management directives,
a variation of this directive exists called Get Region
Parameters (see Section 5.3.36). 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 0,0,
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.

5-90

DIRECTIVE DESCRIPTIONS

GREG$
5.3.36

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 5.3.35) for Executives that support the memory
management directives.
FORTRAN Call:
CALL GETREG ([rid] ,buf[,ids])
rid

Region id

buf

A 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 GREG$
;FROM GPRT$
;REGION ID
;ADDRESS OF 3-WORD BUFFER

Local Symbol Definitions:
G. RGID

Region ID (2)

G.RGBA

Buffer address

5-91

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 is indicated by carry clear, and the
starting address of the region is returned
in the DSW.
In
unmapped systems, the returned address is physical.
In mapped
systems, the returned address is virtual and is always zero if it
is not the task region. Unsuccessful completion is indicated by
carry set and one of the following codes in the DSW:
IE.NVR

Invalid region ID.

IE.ADP

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

IE.SOP

DIC or DPB size is invalid.

5-92

the

issuing

DIRECTIVE DESCRIPTIONS

GSSW$S
5.3.37

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

ist

Test results where:
1

switch on

switch off

(0 to 15)

Macro Call:
GSSW$S
err

[err]
Error routine address

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

ERR
(PC ) + , - (S P )
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 II 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

5-93

out

the issuing

task's

DIRECTIVE DESCRIPTIONS
Note:
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 that of the DIR$ macro.

5-94

DIRECTIVE DESCRIPTIONS

GTIM$
5.3.38

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 below.
FORTRAN Call:
CALL GETTIM (ibfp[,ids])
ibfp = An 8-word integer array
Macro Call:
GTIM$

buf
Address of 8-word buffer

buf
Buff er Format:
Word

Year (since 1900)

Word

Month (1-12)

Word

Day ( 1-31)

Word

Hour (0-23)

Word

Minute (0-59)

Word

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)

Macro Expansion:
GTIM$
.BYTE
.WORD

DATBUF
61. I 2
DATBUF

;GTIM$ DIC, DPB SIZE=2 WORDS
;ADDRESS OF 8.-WORD BUFFER

Local Symbol Definitions:
G.TIBA

Buffer address (2)

5-95

DIRECTIVE DESCRIPTIONS

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)

G. TIMI

Minute (2)

G. TISC

Second {2)

G.TICT

Clock Tick of Second (2)

G.TICP

Clock Ticks per Second {2)

the

time

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.

buffer is

out of the issuing

Note:
The format of the time buffer is compatible with
buffers used with the Set System Time directive.

5-96

that

the

DIRECTIVE DESCRIPTIONS

GTSK$
5.3.39

Get Task Parameters

The Get Task Parameters directive instructs the system to fill an
indicated 16-word buffer with parameters relating to the issuing task.
FORTRAN Call:
CALL GETTSK (buf[,ids])
buf

A 16-word integer array to receive the task parameters

ids

Directive status

Macro Call:
GTSK$

buf

Address of a 16-word buffer

Buff er Format:
Word

Issuing task's name in Radix-50 (first half}

Word

Issuing task's name in Radix-50 (second half)

Word

Partition name in Radix-50 (first half)

Word

Partition name in Radix-50 (second half)

Word

Undefined in RSX-llM/M-PLUS
RSX-llD compatibility)

(this

word

exists

for

Word

Undefined in RSX-llM/M-PLUS
RSX-llD compatibility}

(this

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 exists for

Word 13

{Address of task SST vector tables)2

1. See note
in RQST$ description (Section 5.3.54) on contents of words
, ..,
07 and

..I. I •

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.
5-97

DIRECTIVE DESCRIPTIONS
Word 14

(Size of task SST vector table in words)2

Word 15

Size (in bytes) either of task's address window O 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
1 for
2 for
3 for
4 for
5 for
6 for
7 for
10 for
and

Word 17

RSX-llD
RSX-llM
RSX-1 lS
!AS
RSTS
VAX/VMS
RSX-llM-PLUS
RTll single Job Monitor
RTll Foreground/Background
Extended Memory Monitor

Protection UIC
UIC)l

(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

1. See note in RQST$ description (Section 5.3.54) on contents of words
07 and 17.
2. Words 13 and 14 will contain data if word 14 is not zero.
14 is zero, the contents of word 13 are meaningless.
5-98

word

DIRECTIVE DESCRIPTIONS
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.

5-99

out

the

issuing

DIRECTIVE DESCRIPTIONS

MAP$
5.3.40

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 Executive 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.64B 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.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.64B = 1) may not
be
compatible
with
future
implementations
of
RSX
emulators.
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).

FORTRAN Call:
CALL MAP (iwdb[ ,ids])
iwdb

An 8-word integer array containing a Window Definition
Block (see Section 3.5.2.2)

ids

Directive status
5-100

DIRECTIVE DESCRIPTIONS
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(l)
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 0 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.

i wdb (6)

W.NLEN

Length, in 32-word blocks, within the
region to be mapped, or 0 if the length
is to default to either the size of the
in the
window or the space remaining
specified
offset,
region
from
the
whichever is smaller.

i wdb ( 7)

W.NSTS

Bit settings 1 in the window status word:
Bit

Definition

WS.WRT

1 if write access is desired

WS.64B

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

Output parameters:
i wdb ( 6)

W.NLEN

Length of the area within the
actually mapped by the window

i wdb (7)

W.NSTS

Bit settingsl in the window status word:
WS.UNM -- 1 if the
first

window

was

region

unmapped

1. If you are a FORTRAN programmer, refer to Section 3.5.2 to
determine the bit values represented by the symbolic names described.
5-101

DIRECTIVE DESCRIPTIONS
Local Symbol Definitions:
M.APBA

Window Definition Block address (2)

DSW Return Codes:

rs. sue

Successful completion.

IE. PRI

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.

issuing

task's

Notes:
1.

When the Map Address Window directive ls issued, the.task may
be blocked until the region is loaded.

2.o

Bit ws.RES in word W.NSTS of the Window Definition Block,
when set, specifies that the region should be mapped only if
the region is resident.

5-102

DIRECTIVE DESCRIPTIONS

MRKT$
5.3.41

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 flag 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

CALL WAIT (tmg,tnt[,ids])
tmg

Time interval magnitude (see Note 5 below)

tnt

Time interval unit (see Note 5 below)

ids

Directive status

Macro Call:
MRKT$

[efn],tmg,tnt[,ast]

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

5-103

time

DIRECTIVE DESCRIPTIONS
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

Local Symbol Definitions:
M.KTEF

Event flag

( 2)

M.KTMG

Time magnitude ( 2)

M.KTUN

Time unit ( 2)

M.KTAE

AST entry point address ( 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
(EFN<O,
group global event flags exist
group; or EFN>64 if not).

or EFN>96 if
for the task's

IE.ADP

Part of the DPB
address space.

issuing

IE.SDP

DIC or DPB size is invalid.

out

the

task's

For CALL WAIT:
RSX-llM/M-PLUS provides the following positive error codes to
returned for ISA calls:
1

Successful completion

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

5-104

DIRECTIVE DESCRIPTIONS
Notes:
1.

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
SP+06
SP+04
SP+02
SP+OO

Event flag mask wordl
PS of task prior to AST
PC of task prior to AST
DSW of task prior to AST
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 or group global event flag and then exits before the
indicated time has elapsed, the event flag is not set.

The Executive returns the code IE.ITI
(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):
O

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) •

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.
For example, clearing the mask word results in a
permanent Wait For State.
5-105

DIRECTIVE DESCRIPTIONS
1

Milliseconds. The subroutine converts the specified
magnitude to the equivalent number of system clock
ticks.
On systems with line frequency clocks,
millisecond
Mark
Time
requests
can only be
approximations.

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

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, 1, or 2, tmg can be any positive value with
maximum of 15 bits.

If tnt

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

If tnt

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

If the specified event flag is a group global, the use count
for
the event flag's group is incremented to prevent
premature elimination of event flags.
The use count is run
down when:
•

The Mark Time event occurs.

•

The Mark Time event is cancelled.

•

The issuing task exits with the Mark Time event
the clock queue.

still

The minimum time interval is one tick.
If you specify a time
interval of zero, it will be converted to one tick.

5-106

DIRECTIVE DESCRIPTIONS

is only

5-107

the

DIRECTIVE DESCRIPTIONS

To······pr?>vfde ·for 'tl'1e .p<i91e ···Yl~.e.n·•······.~'.sllpe r.yis()r.'.:.,mpd.~ iJ. ihr<Jp}..~:s. .q~in<J . • .·.· •· .·. us~d

by .· .... some· .•.... tas1<$ . ·as a· userc--1nPd~·.···. library,. t~is·difectiy~ cioe~n?t .c~ah<J~ ·

>t:he.:t:ask'~· lltCiPPing when it js·. issued 'fro1nuseFmoae.···.·.'floY1eY~rr<t:he·. :bsw

is still returned.

When . t:~e

directive · is

st.1cces~fuJ.£y

.executed,

the ·:DSW: < pr;gviqes:

Jntc),~milt:i:.ori. ·~aQot1t: . : the •t:ask\~ .. current.· mappfpg·. •. aJ'ld rr1pge . . . . . . . . J3pec~.·f~ing . ······•·.·(l·

·n~gatJve'mask va~ue. causes the.·dlr.ective .to· return information

•·t:hap ·s~an9·~ ·t11.~···I1l?l'Pip9.

·..··.. ·..

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

.. •.·•• .- ••••••'.··.· ••·.•.· •.·•.·.··••·. ••

.::···;·.·: ...·:.:··.•.·.··.·· · :. .. .. ..··.·••
•••

·E'Ol(TR~~

••• ·.·.· ··.··.··•.·•• ···.·.•··•.•.......

rather

·.•·••·..•·.

Pall:·:

with one
supervisor.,_mode .D-spape . .
If th~ bit· is set,
APR is mapped to supervisor-mode . . r-spac~. If the
is clear, the APR is mapped t9 user-mode D-space.
7 bits are specified in bits 8 through i4 of the
word.

Macro Expansion:
MSDS$ mask

.BYTE

201., 1

;DIC=20L

DPB SIZE= l WORD

DSW Return Codes:
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.

When including data in a supervisor-mode library, the library
may. not overmap APR 0 with the supervisor-mode library. The
executive assumes it has access to the task's DSW regardless
of the mode from which a directive is issued. Data must
therefore be placed near the end of the library, or mapped
through a memory resident overlay to force its mapping into
some APR ~ther than o.

In the following example, ~ supervisor~mode library routine
changes its mapping in order to access an error message
(which is datcrJ. · · · ·

5-108

DIRECTIVE DESCRIPTIONS

5-109

DIRECTIVE DESCRIPTIONS

MV.TUI
MV.TUD
MV.TSI
MV.TSD
MV.FUI
MV.FUD
MV.FSI
MV.FSD

I-space
user D-space
supervisor I-space
Move to supervisor D-space
Move from user I-space
Move from user D-space
Move from supervisor I-space
Move from supervisor D-space

addr

= Address of the location in the task

buff

= Buffer to receive the value

fetched,

for

the

move

from operations
val

Value to be stored in the location, for the
operations

5-110

move

DIRECTIVE DESCRIPTIONS

5-111

DIRECTIVE DESCRIPTIONS

010$
5.3.44

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 Executive declares 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])
fnc

I/O function codel

lun

Logical unit number

efn

Event flag number

pri

Priority;

isb

A 2-word integer array to receive final I/O status

prl

A 6-word integer array containing device-dependent
parameters to be placed in parameter words 1 through 6
of the DPB.
Fill in this array by using the GETADR
routine (see Section 1~5.1.4).

ids

Directive status

ignored, but must be present

Macro Call:
QIO$

fnc,lun, [efn], [pri], [isb], [ast], [prl]

fnc

I/O function codel

lun

Logical unit number

1. I/O function code definitions are included
I/O Drivers Reference Manual.
5-112

the

RSX-llM/M-PLUS

DIRECTIVE DESCRIPTIONS
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

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.IOFN

I/O function code (2)

Q. IOLU

Logical unit number (2)

Q. IOEF

Event flag number (1)

Q. IOPR

Priority (1)

Q. IOSB

Address of I/O status block (2)

Q. IOAE

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. !LU

Inv al id LUN.

IE. IEF

Invalid event flag number (EFN<O, or EFN>96 if group
global event flags exist for the task's group; or
EFN>64 if not).

IE.ADP

Part of the DPB or I/O status block
1ssu1ng task's address space.

IE.SOP

DIC or DPB size is invalid.

5-113

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

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

SP+OO - 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
(see Section
stack before an AST Service Exit directive
5.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 or Stop For directive
and the QIO directive is rejected, the task may wait
indefinitely. Care should always be taken to ensure that the
directive was successfully completed.

Tasks i'<;>\~;:',i,~~i$~fi;~~rj;,~~tjJi'lJ1~~~!~d$ ,~,~~:i:;~~'~jIC cannot normally be
checkpointed with I/O outstanding for two reasons:
•

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 buffered I/O, drivers that buffer I/O
check for the following conditions for a task:
•

That the task is checkpointable

•

That checkpointing is enabled

If those two conditions are met, the driver and/or the
Executive buffers the I/O request internally and the task is
checkpointable with this outstanding I/O.
If the task also
entered a Wait For state when the I/O was issued (see the
QIOW$ directive) or subsequently enters a Wait For state: the
task is stopped.
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 the
stopped state is terminated by completion of buffered I/O or
satisfaction of the Wait For condition.
Not all drivers buffer I/O requests.
an example of one that does.

5-114

The terminal driver

DIRECTIVE DESCRIPTIONS
4.

A privileged task on RSX-llM
that is linked to a common (read-only) area can issue QIO
write requests to that area.

If the specified event flag is a group global, the use count
for
the event flag's group is incremented to prevent
premature elimination of the event flags. The use count is
run down when:
•

The I/O is completed.

•

The I/O is killed by reassigning the
the ALUN$ directive.

specified

LUN

with

•

The I/O is killed by issuing the IO.KIL function
specified LUN.

for

the

•

The task exits before I/O is completed.

5-115

DIRECTIVE DESCRIPTIONS

QIOW$
5.3.45

Queue I/O Request and Wait

The Queue I/O Request And Wait directive is identical to the 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
notes.
FORTRAN Call:
CALL WTQIO (fnc,lun, [efn], [pri], [isb], [prl] [,ids])
fnc

I/O function codel

lun

Logical unit number

efn

Event flag number

pri

Priority;

isb

A 2-word integer array to receive final I/O status

prl

A 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]

fnc

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.
5-116

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

5-117

DIRECTIVE DESCRIPTIONS

RCST$
5.3.46

Receive Data Or Stop

The Receive Data Or Stop directive instructs the system to dequeue a
13-word data block for the issuing task; the data block was queued
for the task with a Send Data Directive or a Send, Request and Connect
directive.
A 2-word task name of the sender {in Radix-50 format) and the 13-word
data block are returned in an indicated 15-word buffer. The task name
is contained in the first two words of the buffer.
If no data has been sent, the issuing task is stopped. In this case,
the sender task is expected to issue an Unstop directive after sending
data. A success status code of rs.sue indicates that a packet has
been received.
A success status code of IS.SET indicates that the
task was stopped and has been unstopped. The directive must then be
reissued to retrieve the packet.
When a slave task issues the Receive Data or Stop directive, it
assumes the UIC
(if it has no outstanding group global context) and
TI:
terminal of the task that sent the data.
FORTRAN Call:
CALL RCST ([rtname] ,ibuf[,ids])
rtname

Sender task name (if not
received from any task.)

specified,

data

may

ibuf

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

Sender task name (If not
received from any task.)

specified,

data

may

buf

Address of 15-word buffer to receive the sender task
name and data

Macro Expansion:
RCST$

ALPHA, TSKBUF

.BYTE
.RAD50
.WORD

139., 4
ALPHA
TSKBUF

;RCST$ MACRO DIC, DPB SIZE=4 WORDS
;DATA SENDER TASK NAME
;BUFFER ADDRESS

Local Symbol Definitions:
R.CSTN

Task name (4)

R.CSBF

Buffer address (2)

5-118

DIRECTIVE DESCRIPTIONS
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.RSU

The issuing task is a slave task with a group global
context active, and the next packet received would
have changed the task's group number.

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.

5-119

address

DIRECTIVE DESCRIPTIONS

RCVD$
5.3.47

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 by 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.
When a slave task issues the Receive Data directive, it assumes the
UIC (if it has no outstanding group global event flag context) and TI:
terminal of the task that sent the data.
FORTRAN Call:
CALL RECEIV ([tsk] ,buf[,,ids])
tsk

Sender task name (If not specified, data may be
received from any task.)

buf

A 15-word integer array for received data

ids

Directive status

Macro Call:
RCVD$

[tsk],buf

tsk

Sender task name (If not specified, data may be
received from any task.)

buf

Address of 15-word buffer

Macro Expansion:
RCVD$
.BYTE
.RAD50
.WORD

ALPHA, DATBUF
75., 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. ITS

No data currently queued.

IE. RSU

The issuing task is a slave task with a group global
context active, and the next packet to be received
would have changed the task's group number.

IE.ADP

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

IE. SDP

DIC or DPB size is invalid.

5-120

out

the

issuing

DIRECTIVE DESCRIPTIONS
Notes:

If the sending task specifies a common or group global event
flag in the Send Data directive, the receiving task may use
that event flag for synchronization.
However, between the
time that the receiver issues this directive and the time the
receiver issues it's next instruction, the sender can send
data and set the event flag. If the next instruction is an
Exit directive, any data sent during this time will be lost
because the Executive flushes the task's receive list as part
of exit processing. Therefore, use the Exit If directive or
the Receive Data or Exit directive in order to avoid the race
condition.

5-121

DIRECTIVE DESCRIPTIONS

RCVX$
5.3.48

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 by 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.
When a slave task issues the Receive Data Or Exit directive, it
assumes the UIC
(if it has no outstanding group global event flag
context) and TI:
terminal of the task that sent the data. See Notes
below.
FORTRAN Call:
CALL RECOEX ([tsk] ,buf[,,ids])
tsk
buf
ids

Sender task name (If not specified, data may be
received from any task.)
=

A 15-word integer array for received data
Directive status

Macro Call:
RCVX$

[tsk] , buf

tsk

Sender task name (If not specified, data may be
received from any task.)

buf

Address of 15-word buffer

Macro Expansion:
RCVX$
.BYTE
• RAD50
.WORD

ALPHA, DATBUF
77.,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.VXTN

Sender task name (4) R.VXBA

5-122

Buffer address (2)

DIRECTIVE DESCRIPTIONS
DSW Return Codes:

rs.sue

Successful completion.

IE.RSU

The issuing task is a slave task with a group global
context active, and the next packet to be received
would have changed the task's group number.

IE.ADP

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

IE.SOP

DIC or DPB size is invalid.

out

the

issuing

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.
The following example illustrates the same
overhead saving in MACRO:
RCVBUF: • BLKW

15 •

Receive buffer

START:

,RCVBUF
OPEN

Attempt to receive message
Call user subroutine to open files.

RCVX$C
CALL

PROC:
Process packet of data
RCVD$C
BCC
CALL

,RCVBUF
PROC
CLOSE

JMP

START

Attempt to receive another message
If CC successful receive
Call user subroutine to close files
and prepare for possible task exit
Make one last attempt at receiving

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 by 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.

5-123

DIRECTIVE DESCRIPTIONS

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

particular,

•

Detaches all attached devices

•

Flushes the AST queue and despecifies all specified ASTs

•

Flushes the receive and receive-by-reference queues

•

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

•

Closes all open files (files open
locked)

•

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

•

Runs down the task's I/O

•

Deaccesses the group global event
group

•

Disconnects from interrupts

•

Flushes all outstanding CLI command buffers for the task

•

Returns a success status (EX$SUC) to any parent tasks

for

write

access

the

case

for

the

task's

flags

are
a

: .Rs·x,771.1.M-.1ai:urax 1·.
~~~~.lj:). i·~~!~-~(il,i;~;: ;"

•

Breaks the connection with any offspring tasks

•

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

If the task
event.

exits,

the

Executive

declares

significant

6. ; In Rsx~l.lM .... PL;tJS system;s · t.hat supt¥>ft .\Tari.able serid. and
re(Zrlve. ·.·. qi~e~t.ives
(sejcondary··· P()Ol.;s.\lpport. SYSGEN optlo!lJ;
the; <Recelve.D:q:t.a Or Exi~ d
ctive l.s treate<i .. as .·a ·.·•.·.· ·.·.·.1•·.·. :37.~o·r·d····
.Y:'Cl.t:.'·~·Cll?.l~.Re<::e~YEf.l)~t~· Q;f)~
c:l·jr;.a.qtJ;V°e•·.·.·(se.-~··•·. $.ec1:ir<:>n' ,~ ... l .... ?9>.

5-124

DIRECTIVE DESCRIPTIONS

ROAF$
5.3.49

Read All Event Flags

The Read All Event Flags directive inscructs the system to read all 64
event flags for the issuing task and record their polarity in a 64-bit
(4-word) buffer.
NOTE
This
directive
not
return
does
(event flags
group-global event flags
65 - 96).
FORTRAN Call:
A FORTRAN task can read only one event flag.

The call is:

CALL READEF (efn[,ids])
efn

Event flag number

ids

Directive status

The Executive returns the status codes IS.SET
(+02)
and IS.CLR
(00) for FORTRAN calls in order to report event flag polarity.
Macro Call:
ROAF$

buf

Buff er 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

Macro Expansion:
ROAF$
.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.SOP

DIC or DPB size is invalid.

5-125

out

the

issuing

DIRECTIVE DESCRIPTIONS

The following symbol
equal to the byte
element:
R .. DEEF

DSW Return Codes:

5-126

DIRECTIVE DESCRIPTIONS

RDXF$
5.3.51

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 96-bit (6-word) buffer~
FORTRAN Call:
A FORTRAN task can read only one event flag.

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 Flags 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.

5-127

out

Words 4 and 5
the

issuing

DIRECTIVE DESCRIPTIONS

5-128

DIRECTIVE DESCRIPTIONS

RP01$
5.3.53

Request and Pass Offspring Information

This directive instructs the system to request the specified task, and
to chain to it by passing any or all of the parent connections from
the issuing task to the requested task. Optionally, the directive can
pass a command line to the requested task. Only a privileged or CLI
task may specify the UIC and TI: of the requested task.
FORTRAN Call:
CALL RPOI

(tname,[iugc] ,[iumc] ,[iparen] ,[ibuf] ,[ibfl] ,[isc],
[idnam], [iunit], [itask], [ocbad] [,ids])

tname

(in
Name of an array containing the actual name
RAD50)
of the task to be requested and optionally
chained to.

iugc

Name of an integer containing the group code number
for the UIC of the requested target chain task.

iumc

Name of the integer containing the member code number
for the UIC of the requested target chain task.

iparen

Name of an array (or I*4 integer)
containing the
RAD50 name of the parent task. This is returned in
the information buffer of the GTCMCI subroutine.

ibuf

Name of an array that contains the command line
for the chained task.

text

Name of an integer that contains the number of
in the command in the ibuf array.

bytes

ibfl
isc

Flag byte controlling the actions of this directive
request when executed. The bit definitions of this
byte
(only the low order byte of the
integer
specified in the call is ever used) are as follows:
RP.OEX = 128.
RP. OAL

Force this task to exit on
successful execution of the RPOI
directive.
Pass all of this task's
connections to the requested
task.
{The default is none.)
NOTE
You
cannot
pass
all
connections if the target
task is a CLI task.

RP.ONX

Pass the first connection
in the queue if there is one.

5-129

DIRECTIVE DESCRIPTIONS

idnam

Name of an integer containing the ASCII
of the requested task's TI:

device

name

i unit

Name of an integer containing the unit number of
requested tasks TI: device.

the

itask

Name of an array which contains the RAD50 name the
requested .... task is..to rl]n .uJ'ld.e~ •... · f.)h.J~S~prif.iisystems;
.tf1f·§ argl1riterit···~s ·val/id<.on,;ly Lf ·th(i! <is.s.(l.i.n9.ta9k··.t§ · a
.

CLI tas!{~

ocbad

Name of an integer containing the pool address of the
parent OCB.
This value may only be obtained in the
information buffer of the GTCMCI subroutine, which
only a CLI can issue, so therefore, only a CL! can
specify this argument.

ids

Name of an integer to receive
word

the

directive

status

Macro Call:
RPO!$ tname,,, [ugc], [umc], [parent], [bufadr], [buflen], [sc], [dnam],
[unit], [task], [ocbad]
tname

Name of task to be chained to

ugc

Group code for UIC of the requested task

umc

Member code for UIC of the requested task

parent

Name of issuing task's parent task whose connection
is to be passed. If not specified, all connections
are passed.

bufadr

Address of buffer to be given to the requested task

buflen

Length of buffer to be given to requested task

Flags byte:
RP.DEX
(200) Force issuing task to exit
RP.OAL -- (1)
Pass all connections (Default is
none.)
NOTE
You
cannot
pass
all
connections if the target
task is a CLI task.
RP.ONX

-- (2)

Pass the first connection in the
queue, if there is one.

5-130

DIRECTIVE DESCRIPTIONS
dnam

ASCII device name for TI:

unit

Unit number of task TI:

task

RADS.a.

ncill\.~ tticit ~h~

r:-equested task is to

run

under.

()ti...•..• Jlp~-.1i~: •: · 9y!;:t~.m$ , •. ,th.~·•$······.P~r(lrne~er is·. only·.···veilid·•.· if

. the••.· . . issl]ing <ta.$,1<·····~:$•.···a: . ·.G~l·. ~asK;;

Address of OCB to pass {CLis only)

ocbad

Local Symbol Definitions:
R~POTK

RADSO name of task to be chained to ( 2)

R. POUM

UIC member code ( 1)

R. POUG

UIC group code

R.POPT

Name of parent whose OCB should be passed ( 4)

R.POOA

Address of OCB to pass ( CLis only)

R.POBF

Address of command buffer ( 2)

R. POBL

Length of command ( 2)

R. POUN

Unit number of task TI:

R.POSC

Flags byte ( 1)

R.PODV

ASCII device name for TI:

R. POTN

RADSO name of task to be started (4)

(2)

( 1)

( 2)

Macro Ex pans ion:
RPOI$
.BYTE
.RADSO
.BLKW
.BYTE
.BYTE
• RADSO
.WORD
.WORD
.WORD
.ASCII
.BYTE
.BYTE

tname,,,ugc,umc,ptsk,buf,buflen,sc,dev,unit,task,ocbad
11,16
;DIC 11 DPB SIZE= 16. words
/tname/
;NAME OF TASK TO CHAIN TO
3
;RESERVED
umc
;UIC MEMBER CODE
ugc
;UIC GROUP CODE
ptsk
:NAME OF TASK WHOSE OCB SHOULD BE PASSED
ocbad
;ADDRESS OF OCB
buf
;ADDRESS OF BUFFER TO SEND
buflen
;LENGTH OF BUFFER
/dev/
;ASCII NAME OF TI: OF REQUESTED TASK
unit
;UNIT NUMBER OF TI: DEVICE
sc
;PASS BUFFER AS SEND PACKET OR COMMAND
;CODE

5-131

DIRECTIVE DESCRIPTIONS
DSW Return Codes:
IE.VPN

Insufficient dynamic memory to allocate an offspring
control block, command line buffer, task control
block, or partition control block.
The specified task was not installed, or it was a CLI
but no command line was specified.

IE.ACT

The specified task was already active and it was
a command line interpreter.

IE.ITS

A task that is not a CLI specified a CLI only
parameter or specified passing all connections to a
CLI.

IE.NVR

There is no offspring
specified parent task.

IE.ALG

A CLI specified a parent name and an offspring
control block address that did not describe the same
connection, or either a parent name or an offspring
control block address was specified and the pass all
connections flag or the pass next connection flag was
set.

IE.PNS

The task control block cannot be created in the
partition as its prototype.

same

IE.ADP

Part of the DPB, exit status bl9ck, or command
is out of the issuing task's address space.

line

IE.SDP

DIC or DPB size is invalid.

5-132

control

block

from

not

the

DIRECTIVE DESCRIPTIONS

RQST$
5.3.54

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. The Request Task directive is the basic
mechanism used by running tasks to initiate other installed {dormant)
tasks. The Request Task directive is a frequently used subset of the
Run directive. See Notes below.
FORTRAN Call:

CALL REQUES {tsk, [opt] [,ids])
tsk

Task name

opt

A 4-word integer array
Partition name first
must be present

half;

ignored,

but

opt {2)

Partition name second
must be present

half;

ignored,

but

opt{3)

Priority;

opt{l)

opt{4)
ids

ignored, but must be present

User Identification Code

Directive status

Macro Call:
RQST$
tsk

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

Task name

prt

Partition name;

pri

Priority;

ugc

UIC group code

umc

UIC member code

ignored, but must be present

Macro Expansion:
RQST$
.BYTE
.RAD50
.WORD
.WORD
.BYTE

ALPHA,,,20,10
11., 7
/ALPHA/
0,0
0

10,20

;RQST$ MACRO DIC, DPB SIZE=? WORDS
;TASK "ALPHA"
;PARTITION IGNORED
;PRIORITY IGNORED
;UIC UNDER WHICH TO RUN TASK

5-133

DIRECTIVE DESCRIPTIONS
Local Symbol Definitions:
R.QSTN

Task name ( 4)

R. QSPN

Partition name ( 4)

R. QSPR

Priority (2)

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.SOP

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.

5-134

declared

terminal assignment
specified

DIRECTIVE DESCRIPTIONS
7.

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:
•

The protection UIC determines the task's access rights for
opening files and attaching to regions.
When a task
attempts to open a file, the system compares the task's
protection
UIC
against the protection mask of the
specified UFD; the comparison determines whether the task
is to be considered for system, owner, group, or world
access a

•

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 or DCL 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.
lf a privileged task specifies a UIC in
a Request directive, the specified UIC becomes both the
protection and default UIC for the requested task.

5-135

DIRECTIVE DESCRIPTIONS

RREF$
5.3.55

Receive By Reference

The Receive By Reference directive requests the Executive to dequeue
the next 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.40) 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, [isrb] [,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
buffer.
If the call omits this parameter, the
contents of iwdb(B) are unchanged.

ids

Directive status

Macro Call:
RREF$
wdb

wdb
Window Definition Block address

5-136

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

iwdb(l)
bits 0-7

W.NID

ID of an existing window if region is to be
mapped

iwdb {7)

W.NSTS

Bit settingsl in the window status word:
Definition

Bit

i wdb ( 8)

W.NSRB

WS.MAP

1 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:
i wbd ( 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

i wdb ( 7)

W.NSTS

Bit settingsl in the window status word:

(po i"nter

attachment

Bit

Definition

WS.RED

1 if attached with read access

WS.WRT

1 if attached with write access

WS.EXT

1 if attached
access

with

extend

WS.DEL

1 if attached
access

with

delete

WS.RRF

1 if receive was successful

The Executive clears the remaining bits.

1. If you are a FORTRAN programmer, refer to Section 3.5.2 to
determine the bit values represented by the symbolic names described.
5-137

DIRECTIVE DESCRIPTIONS
Local Symbol Definitions:
R.REBA

Window definition block address (2)

DSW Return Codes:
IS. sue

Successful

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. SDP

DIC or DPB size is invalid.

completion~

5-138

DIRECTIVE DESCRIPTIONS

RSUM$
5.3.56

Resume Task

The Resume Task directive instructs the system to resume the execution
of a task that has issued a Suspend directive.
FORTRAN Call:
CALL RESUME (tsk[,ids])
tsk

Task name

ids

Directive status

Macro Call:
RSUM$
tsk

tsk
=

Task name

Macro Expansion:
RSUM$
.BYTE
.RAD50

ALPHA
47.,3
/ALPHA/

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

Local Symbol Definitions:
R.SUTN

Task name (4)

DSW Return Codes:
IS. 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.

5-139

DIRECTIVE DESCRIPTIONS

RUN$
5.3.57

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 Ca 11 :
CALL RUN (tsk, [opt] , [ smg] , snt, [ rmg] , [ rnt] [,ids] )
tsk

Task name

opt

A 4-word integer array
opt ( 1)

Partition name first
must be present

opt ( 2)

Partition name
second
but must be present

opt(3)

opt ( 4)

Priority;

half;

User Identification Code

Schedule delta magnitude

snt

Schedule delta unit (either 1, 2, 3, or 4)

rmg

Reschedule interval magnitude

ids

Reschedule interval unit
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 0, 1, 2, 3, or 4)

ids

Directive status

5-140

but

ignored,

ignored, but must be present

smg

rnt

ignored,

DIRECTIVE DESCRIPTIONS
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 (either 1, 2, 3, or 4)

rmg

Reschedule interval magnitude

rnt

Reschedule interval unit

ignored, but must be present

Macro Expansion:
RUN$
BYTE
.RADSO
.WORD
.WORD
.BYTE
.WORD
.WORD
• WORD
.WORD

ALPHA,,,20,10,20.,3,10.,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. UNPR

Priority (2)

R.UNGC

UIC group code ( 1)

R. UNPC

UIC member code ( 1)

R.UNSM

Schedule magnitude ( 2)

R.UNSU

Schedule unit ( 2)

R.UNRM

Reschedule magnitude ( 2)

R.UNRU

Reschedule unit (2)

5-141

DIRECTIVE DESCRIPTIONS
DSW Return Codes:
For CALL RUN and RUN$:

rs.sue

Successful completion.

IE.UPN

Insufficient dynamic

IE.ACT

Multiuser task name specified.

IE.INS

Task is not installed.

IE.PR!

Nonprivileged task specified a UIC other than its

memory~

o~.

IE.IT!

Invalid time parameter.

IE.ADP

Part of the DPB is
address space.

IE.SDP

DIC or DPB size is invalid.

out

of the

issuing

task's

For CALL START:
RSX-llM/M-PLUS provides the following positive error codes
be returned for ISA calls:
2

Insufficient dynamic storage.

Specified task not installed.

Invalid time parameter.

Invalid event flag number.

Part of DPB is out of task's address space.

100

DIC or DPB size is 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 Note 8,
Section 5.3.54,
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.

5-142

DIRECTIVE DESCRIPTIONS
3.

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 parameter.
A time
parameter consists of two components:
the time interval
magnitude, and the time interval unit.
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 (CALL START):
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 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:
1

Ticks

See definition of ticks above.

For both types of FORTRAN calls and all macro calls:
2

Seconds

Minutes

Hours

5-143

DIRECTIVE DESCRIPTIONS
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
value with a maximum of 15 bits.

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

maximum

value

If unit
24(10).

maximum

value

4, the magnitude can have

any

positive

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 or DCL Cancel command is issued.

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.

5-144

call

DIRECTIVE DESCRIPTIONS

SCAA$
5.3.58

Specify Command Arrival AST

This.directive instructs the system to enable or disable command
arrival ASTs for the issuing CLI task. If command arrival ASTs are
enabled, the executive transfers control to a specified address when
commands have been queued to the CLI.
Only CLI tasks can use this AST.
The format of the stack when the AST routine is entered is as follows:
zero since no event flags are involved
PS of task prior to AST
PC of task prior to AST
DSW of task prior to AST
address of command buffer just queued

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

The AST routine must remove the command buffer address from the
before issuing an ASTX$ directive.

stack

The command buffer address may be used when issuing a GCCI$ directive.
FORTRAN Call:
Not supported.
Macro Call:
SCAA$

[ast]
ast = AST service routine entry point.
Omitting this
parameter disables command arrival ASTs for the
issuing task until the directive is respecified.

Macro Expansion:
SCAA$
.BYTE
.WORD

ast
173.,2

ast

;DIC = 173 , DPB SIZE= 2 WORDS
;ADDRESS OF AST ROUTINE

Local Symbol Definitions:
S.CAAE

Address of AST routine

DSW Return Codes:
IE. ITS

ASTs are already not desired.

IE.AST

Directive issued from AST state.

IE. PRV

Issuing task is not a CLI.

IE.UPN

Insufficient dynamic memory.

IE.ADP

Part of the DPB was out of the issuing task's address
space.

IE. SDP

DIC or DPB size is invalid.

5-145

DIRECTIVE DESCRIPTIONS

saddr
caddr

=
=

the

routine

the compleiion routine for return

5-146

the

DIRECTIVE DESCRIPTIONS

5-147

DIRECTIVE DESCRIPTION.S

SCLI$
5.3.60

Set Command Line Interpreter

The Set Command Line Interpreter directive instructs the system to set
up the specified CLI as the CLI for the indicated terminal. The
issuing task must be privileged or a CLI.
If the restricted access flag (CP.RST} in the CL! status word is set,
the issuing CL! task is the only CLI task that can set a terminal to
that CLI.
FORTRAN Call:
CALL SETCLI

( icl i, idev, i unit [,ids])

icli

Name of a two-word array element containing the
of the CLI the terminal is to be set to

name

idev

Name of an integer containing the ASCII name
terminal to be set (default= TI:)

the

iunit

Name of an integer
terminal

number

ids

Directive status

containing

the

unit

Macro Call:
SCLI$ cli,[dev] ,[unit]
cli

Name of the CL! the terminal is to be set to

dev

ASCII name of the terminal to be set (default

unit

Unit number of terminal

TI:)

Local Symbol Definitions:
S. CIDV

ASCII name of the terminal whose CLI is to be set

S. CIUN

Octal unit number of terminal

S.CICN

RAD50 name of the CL! that the terminal is to be
to

Macro Expansion:
SCLI$
.BYTE
.RAD50
.ASCII
.WORD

cli,dev,unit
173.,5
/cli/
/dev/
unit

;DIC 173. DPB SIZE = 5 WORDS
;CL! NAME
;ASCII NAME OF TERMINAL TO BE SET
;UNIT NUMBER

5-148

set

DIRECTIVE DESCRIPTIONS
DSW Returns:
IE. PRI

Task not privileged or not a CLI.
task was not the CLI itself.

IE. IOU

Device not a terminal or does not exist.

IE. INS

Specified CLI does not exist.

IE. UPN

Insufficient dynamic memory.

IE.ADP

Part of the DPB was out of the issuing task's address
space.

IE. SOP

DIC or DPB length is invalid.

5-149

If CP.RST was set,

DIRECTIVE DESCRIPTIONS

SDAT$
5.3.61

Send Data

The Send Data directive instructs the system to declare a significant
event and to queue
(FIFO)
a 13-word block of data for a task to
receive.
NOTE
When a local event flag
is specified,
the indicated event flag is set for the
sending task; a significant event is
always declared.
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

Macro Expansion:
SDAT$
.BYTE
e RAD50
.WORD
.WORD

ALPHA, DATB UF, 52.
71.,5
;SDAT$ MACRO DIC, DPB SIZE=S 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 (2)

S.DAEF

Event flag number (2)

5-150

DIRECTIVE DESCRIPTIONS
DSW Return Codes:

rs.sue

Successful completion.

IE.INS

Receiver task is not installed.

IE.UPN

!sufficient dynamic memory.

IE~IEF

Invalid event flag number (EFN<O, or EFN>96 if group
global event flags exist for the task's group; or
EFN>64 if not).

IE.ADP

Part of the DPB or data block is out of
task's address space.

IE.SOP

DIC or DPB size is invalid.

the

issuing

Notes:
1.

Send Data requires dynamic memory.

If the directive specifies a local event elag, 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.
Normally, the event flag is used to trigger the receiver task
into some action. For this purpose, the event flag must be
common (33 through 64) or group global (65 through 96) rather
than local.
(Refer to the descriptions of the Receive Data
directive and the Exit IF directive.)

5-151

DIRECTIVE DESCRIPTIONS

SDRC$
5.3.62

Send, Request and Connect

The Send, Request And Connect directive performs a Send Data to the
specified task, Requests the task if it is not already active, and
then Connects to the task. The receiver task normally returns status
by an Emit Status or Exit With Status directive.
FORTRAN Call:
CALL SDRC (rtname, ibuf,[iefn],[iast],[iesb] ,[iparm] [,ids])
rtname

Target task
connected

offspring

task

ibuf

Name of 13-word send buffer

iefn

Event flag to be set when the offspring
or emits status

task

exits

iast

iesb

name

the

Name of an AST routine to be called
offspring task exits or emits status

when

the

Name of an 8-word status block to be written
the offspring task exits or emits status

when

Word

Offspring task exit status

Word

TKTN abort code

Word

2-7

Reserved
NOTE

The exit status block defaults to 1 one
word.
To use the 8-word exit status block,
you must specify the logical or of the
symbol SP.WXB and the event flag number in
the iefn parameter above.

iparm

Name of a word to receive the status
when an AST occurs

ids

Integer to receive the Directive Status Word

block

address

Macro Call:
SDRC$

tname,buf,[efn] ,[east] ,[esb]
Target task
connected

tname

name

the

offspring

task

buf

Address of 13-word send buffer

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

5-152

when

DIRECTIVE DESCRIPTIONS
esb

Address of an 8-word status block to be written when
the offspring task exits or emits status
Word

Offspring task exit status

Word

TKTN abort code

Word 2-7

Reserved
NOTE

The exit status block defaults to 1 one
word.
To use the 8-word exit status block,
you must specify the logical or of the
symbol SP.WXB and the event flag number in
the efn parameter above.
Macro Expansion:
SDRC$
.BYTE
.RAD50
.WORD
.BYTE
.BYTE
.WORD
.WORD

ALPHA,BUFFR,2,SDRCTR,STBLK
141.,7
;SDRC$ MACRO DIC, DPB SIZE=7 WORDS
ALPHA
;TARGET TASK NAME
BUFFR
;SEND BUFFER ADDRESS
2
;EVENT FLAG NUMBER = 2
16.
;EXIT STATUS BLOCK CONSTANT
SDRCTR
;ADDRESS OF AST ROUTINE
STBLK
;ADDRESS OF STATUS BLOCK

Local Symbol Definitions:
S.DRTN

Task name ( 4)

S.DRBF

Buffer address (2)

S.DREF

Event flag ( 2)

S.DREA

AST routine address ( 2)

S.DRES

Status block address (2)

DSW Return Codes:

rs. sue

Successful completion.

IE. UPN

Insufficient dynamic memory to
packet, Offspring Control Block,
or Partition Control Block.

allocate

IE. INS

The specified task is
attribute.

has

IE. IEF

An invalid event flag number was specified (EFN < 0
or EFN > 96 if group global event flags exist for the
task. EFN > 64 if not.).

IE.ADP

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

IE. SDP

DIC or DPB size is invalid.

5-153

ACP

send
~~~~:~~~

the

not

no-send

the

DIRECTIVE DESCRIPTIONS
Notes:
1.

If the specified event flag is group global, the use count
for
the event flag's group is incremented to prevent
premature elimination of the event flags. The use count is
run down when:
•

Status is returned from the connected task.

•

The issuing task exits before status is returned.

The virtual mapping of the exit status block should not be
changed while the connection is in effect. Doing so may
result in obscure errors.

If the directive is rejected,
event flag is indeterminate.

5-154

the

state

the

specified

DIRECTIVE DESCRIPTIONS

SDRP$
5.3.63

Send Data Request and Pass Offspring Control Block

This directive instructs the system to send a send data packet for the
specified task, chain to the requested task, and request it if it is
not already active.
FORTRAN Call:
CALV SDRP(task,ibuf,[ibfl],[iefn] ,[iflag] ,[iparen] ,[iocbad]
[,ids])
task

Name of an array (REAL,INTEGER,!*4) that contains the
RAD50 name of the target task

ibuf

Name of an integer array containing the
sent

ibfl

Name of an integer containing the
(integers) in the array to be

data

number

S!jS~ell;~i;J· .••t-~lS:

d.ef·al;llted•• ·

':1;':p!~1.:::~:?J!·'..•:~ij~i1':j"

this argument is
13 • i s assumed •

not spec

iefn

Name of an integer containing the number of the event
flag that is to be set when this directive is
executed successfully.

iflag

Name of an integer containing
the
flag
controlling the execution of this directive.
are defined as follows:
SD.REX = 128.
SD.RAL = 1

bits
They

Force this task to exit upon
successful execution of
this directive
Pass all connections to the
requested task (default is pass
none). If you specify this
flag, do not specify the parent
task name.
NOTE
The target task may not be
a CL! task.

SD.RNX = 2

i paren

Pass the first connection
in the queue, if there is one,
to the requested task. If
you specify this flag, do not
specify the parent task name.

Name of an array containing the RAD50 name of the
parent task whose connection should be passed to the
target task.
The name of the parent task was
returned in the information buffer of the GTCMCI
subroutine.

5-155

DIRECTIVE DESCRIPTIONS
iocbad

= Name of an integer containing the pool address of the
OCB
to pass.
This value was returned in the
information buffer of the GTCMCI subroutine.
Only
CLI tasks may specify this parameter.

ids

Name of an integer to receive
Directive Status Word.

the

contents

the

Macro Call:
SDRP$ task,bufadr,[buflen] ,[efn] ,[flag] ,[parent] ,[ocbad]
task

Name of task to be chained to

bufadr

Address of buffer to be given to the requested task

buflen =

Length of buffer to be given to requested task

efn

Event flag

flag

Flags byte controlling the
execution
of
this
directive. The flag bits are defined as follows:
SD.REX

= 128.

SD.RAL

Force this
successful
directive.

task to exit
completion
of

upon
this

Pass all
connections
to
the
requested task (default is pass
none). If you specify this flag,
do not specify the parent task
name.
NOTE
The target task may not be
a CL! task.

SD.RNX

Pass the first connection in the
queue, if there is one, to the
requested task.
If you specify
this flag, do not specify the
parent task name.

parent =

Name of issuing task's parent task whose connection
is to be passed. If not specified, all connections
or no connections are passed depending on the flag
byte.

ocbad

Address of OCB to pass (CLI tasks only)

Macro Expansion:
SDRP$ task,bufadr,[buflen] ,[efn] ,[flag] ,[parent] ,[ocbad]
• BYTE
.RAD50
.WORD
.BYTE
.WORD
.RAD50
.WORD

141.,9 •

/task/
BUFADR
EFN,FLAG
BUFLEN
/PARENT/
OCBAD

;DIC = 141, DPB LENGTH =9 WORDS
;TASK NAME IN RADIX-50
;BUFFER ADDRESS
;EVENT FLAG, FLAGS BYTE
;BUFFER LENGTH
;PARENT TASK NAME
;ADDRESS OF OCB

5-156

DIRECTIVE DESCRIPTIONS
Local Symbol Definitions:
S.DRTK

RAD50 name of task to be chained to

S.DRAD

Send data buffer address

S.DREF

Event flag

S.DRFL

Flags byte:

SD .. REX

(200) Force task to exit (task issuing
directive)
SD.RAL
(1)
Pass all connections to the
requested task (default is pass
none). If you specify this
flag, do not specify the parent task
name.
Pass the first connection in the
SD.RNX -- (2)
queue, if there is one, to the
requested task. If you specify
this flag, do not specify the
parent task name.
S. DRBL

Leng th .~ . ~. . . . .~. ~ nd
·~~...;l•lM.t> htj~/

S.DRPT

Name of parent whose OCB should be passed

S.DROA

Address of OCB to pass (CLis only)

DSW Return Codes:
IE. ITS

A task that is not a CLI specified a CLI only
parameter, or attempted to pass all connections to a
CLI.

IE. NVR

No offspring control block from specified parent.

IE. ALG

A CLI specified a parent name and an offspring
control block address that did not describe the same
connection, or either a parent name or an OCB address
was specified and the pass all connections flag was
set.

IE. IBS

Length of send packet is illegal. pn.:'RS~;..:ll,~·!;?y~teiri~r
tJ:'l,eL . : $e,na. ;P~.9k;et ·mu;s.~ · be•.:.1.3. · .t>yt;:·e~ · .1ori9~ ... :·
•·.R.·p:){·-.••t:.•±~. 71:>~~.s.·. +.·.·.• s.;·y~:t·····•·~ifl:$ :t:11:1~.·· ·$:~'P:<:i··P~.o.1<:¢..t., •-iri~:y; ·· :l)e>7 . !µp/ ·
:;.~··~ij;~:<;i;.::.·~:y't,~$;::·:1:~.~9;:;;... ·
''''"'""
,, .... '

IE. UPN

Insufficient dynamic memory to allocate a
send
packet, offspring control block, task control block,
or partition control block.

IE. INS

The specified task is
attribute.

IE. IEF

An invalid event flag number was specified (EFN<O or
EFN >96 if group global event flags exist. EFN >64
if not).

IE.ADP

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

IE. SOP

DIC or DPB size is invalid.

5-157

ACP

has

the

out

no-send

the

DIRECTIVE DESCRIPTIONS
Notes:
1.

If the directive is rejected,
event flag is indeterminate.

the

state

the

If the specified event flag is group global, the use count
for
the event flag's group is incremented to prevent
premature elimination of the event flags.
The use count is
run down when:
•

Status is returned from the connected tasks

•

The issuing task exits before status is returned.

5-158

specified

DIRECTIVE DESCRIPTIONS

SETF$
5.3.64

Set Event Flag

The Set Event Flag directive instructs the system to set an
event flag, reporting the flag's polarity before setting.

indicated

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

Event flag number

ids

Directive status

Macro Call:
SETF$
efn

efn
=

Event flag number

Macro 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. IEF

Invalid event flag number (EFN<l, or EFN>96 if group
global event flags exist for the task's group; or
EFN>64 if not).

IE.ADP

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

IE. SDP

DIC or DPB size is invalid.

address

Note:
Set Event Flag does not declare a significant event;
sets the specified flag.

5-159

merely

DIRECTIVE DESCRIPTIONS

SFPA$
5.3.65

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 an 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
lll. I 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 entrv 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.

5-160

address

DIRECTIVE DESCRIPTIONS
Notes:
1.

A Specify Floating Point
dynamic 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

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
5.3.4} directive is executed.
4.

This directive cannot be issued either from
routine or when ASTs are disabled.

This directive applies only to the Floating Point Processor.

5-161

AST

service

DIRECTIVE DESCRIPTIONS

SMSG$
5.3.66

Send Message

The Send Message directive instructs the system to create and send a
formatted data packet to a system-defined target task.
The only valid
target for the Send Message directive is Error Logger, and the Error
Logging formatted data packet is an Error Log packet.
The task that
issues the SMSG$ directive must be privileged.
The valid system
defined target and identifier are:
TARGET
IDENTIFIER

CODE

Error Logging

SM.SER

FORTRAN Call:
CALL SMSG (itgt,ibuf ,ibufl,iprm,iprml,ids)
itgt

The name of the integer containing the target
(currently only SM.SER is defined)

ibuf

The name of an integer array containing the
be inserted into the formatted data packet.

data

ibufl

The name of an integer containing the length
ibuf array.

the

iprm

The name of an
integer
additional parameters.

containing

any

iprml

The name of an integer containing
parameters in the iprm array.

the

ids

The name of an optional
directive status.

array

integer

object

number

receive

the

MACRO Call:
SMSG$ tgt,buf,len,<pri, ••• ,prn>
tgt

Target identifier

buf

Address of optional data buffer

len

Length in bytes of optional data buffer
Target-specific parameter list:
Parameter list for Error Logging
SMSG$ SM.SER,buf ,len,<typ,sub,lun,msk>
typ

Error Log packet type code

sub

Error Log packet subtype code

lun

Logical unit number of device

msk

Control mask word

5-162

DIRECTIVE DESCRIPTIONS
The directive creates an Error Log packet of the specified type and
subtype codes.
If you specify a
LUN, the directive also records
information about the device to which the LUN refers.
The control
mask word sets flags to zero I/O and error counts on the device
specified, as shown below:
Control mask word flag:
Zeroes device I/O
specified by LUN

SM.ZER

and

error

counts

for

device

The directive also creates the following subpackets and places them in
the Error Log packet in the order listed below:
1.

Header Subpacket - The header subpacket 1 which contains the
type
and
subtype
codes, the time stamp, and system
identification, is always recorded.

Task Subpacket - The task subpacket, which identifies
task that issued the directive, is always recorded.

Device Subpacket - The device subpacket, which identifies the
device,
is recorded if the directive specifies a
LUN
argument.

Data Subpacket - The data subpacket is recorded if the
directive specifies an address and length of an optional data
buffer.

Macro Expansion (with Error Logging target)
SMSG$
• BYTE
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD

SM.ERR
DIC,8 •
SM.ERR
DATBUF
DATLEN
PRl
PR2
PR3
PR4

DATBUF,DATLEN,<PR1,PR2,PR3,PR4>
;SMSG$ MACRO DIC, DPB SIZE=8 WORDS
;TARGET IDENTIFIER - ERROR LOGGING
;DATA BUFFER ADDRESS
;DATA BUFFER LENGTH
;PARAMETER 1
;PARAMETER 2
;PARAMETER 3
;PARAMETER 4

Local Symbol Definitions:
S.MTGT

Target identifier (2)

S.MDBA

Buffer address (2)

S.MDBL

Buffer length (2)

S.MPRL

Parameter list

S.MERR

Error Log Target Identifier

DSW Return Codes:

rs.sue

Successful completion.

IE.ILU

Invalid LUN (Error Log target only).

IE.SDP

DIC or DPB size is invalid.

5-163

the

DIRECTIVE DESCRIPTIONS
IE.ULN

Unassigned LUN (Error Log target only) •

IE.UPN

Insufficient dynamic memory.

IE.INS

Target task is not installed.

IE.ITS

Invalid target identifier or invalid control mask.

IE.ADP

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

5-164

issuing

DIRECTIVE DESCRIPTIONS

5-165

DIRECTIVE DESCRIPTIONS

5-166

DIRECTIVE DESCRIPTIONS

5-167

DIRECTIVE DESCRIPTIONS

5-168

DIRECTIVE DESCRIPTIONS

SPND$S
5.3.69

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
or DCL Resume command.
FORTRAN Call:
CALL SUSPND
ids

[(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. SDP

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 that of the DIR$ macro.

5-169

DIRECTIVE DESCRIPTIONS

SPRA$
5.3.70

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.
FORTRAN 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 PWRUP
Macro Call:
SPRA$
ast

[ast]
AST service routine entry point address

Macro Expansion:
SPRA$
.BYTE
.WORD

PW RAST
109., 2
PW RAST

;SPRA$ MACRO DIC, DPB SIZE=2 WORDS
;ADDRESS OF POWER RECOVERY AST

Local Symbol Definitions:
S.PRAE

AST entry address (2)

5-170

DIRECTIVE DESCRIPTIONS
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, or,
ASTs are disabled.

IE.ADP

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

IE.SDP

DIC or DPB size is

invalid~

Notes:
1.

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 5.3.4)
can be executed with the stack in the same state as when the
AST was entered.
4.

This directive cannot be issued either from
routine or when ASTs are disabled.

Refer to Chapter 1 for a list of the restrictions on
operations that may be performed in a FORTRAN AST routine.

5-171

AST

service

DIRECTIVE DESCRIPTIONS

SPWN$
5 • 3 • 71

spawn

The

Spawn directive requests a specified task
for
execution,
ionally queuing a command linel and establishing the task's TI: as
.~!··-~~~i~N
~.
· a 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
~~~.~,.~~.; .. ~. ~sk is . w~i parent task and has one or more offspring tasks ·.~I~?
:l~:~~!~M~j;t:e:~~i
.... r:~:§i}!; cleanup is necessary if a parent task exits with
a·ctive· 'of spring 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 with the Get MCR Command Line directive.
Maximum
command 1 ine 1
th
:Ch:a)r'ao•ter::s·' <>n' iij,$Jx;...µ.·1:J;ff>sy~if;~lt\·~· ;~~~~~'...1~,~~:·?
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 or DCL. In this case, a command line
must be specified, and both the OCB and the command line are queued
for the interpreter task. MCR and DCL either handle commands directly
or dispatch them to another task. In the case of direct execution of
the command, the OCB may be used to immediately effect the proper exit
conditions and return exit status by an Executive routine. If MCR or
DCL dispatch 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 situation is exactly the same as if the SPWN$ directive had
specified the dispatched task directly.
No exit conditions occur
until the dispatched task exits.
FORTRAN Call:
CALL SPAWN (rtname,[iugc] ,[iumc],[iefn],[iast] ,[iesb] ,[iparm],
[icmlin], [icmlen], [iunit], [dnam] [,ids])
rtname

Name (RADSO) of the offspring task to be spawned.

iugc

Group code number for the UIC of the offspring task.

iumc

Member code number for
task.

iefn

the

UIC

the

Event flag to be set when the offspring
or emits status.

offspring
task

1. Command line processing is not available for RSX-llS tasks.
5-172

exits

DIRECTIVE DESCRIPTIONS
iast

Name of an AST routine to be called
offspring task exits or emits status.

when

the

iesb

Name of an 8-word status block to be written
the offspring task exits or emits status.

when

Word

Offspring task exit status

Word

TKTN abort code
Reserved

Word 2-7

NOTE
The exit status block defaults to one word.
To use the 8-word exit status block, you
must specify the logical or of the symbol
SPaWX8 and the event flag number in the iefn
parameter above.

iparm

Name of a word to receive the status
when the AST occurs.

icmlin

Name of a command
offspring task.

icmlen
iunit

Length of
maximum) •
=

the

line

to
line

command

block
queued

address
for

the

characters

( 79.

Unit number of terminal to be used as the

TI:

:~};:;;-.

for
--:;~:

:tL
.~tt\.~:~:~:iiI::.·'~~;~.~:.:;m:ij;~fl·I#!b~·:: .t::$$'µ:~•ng:'
a value of 0 is specified, the TI: of the
issuing
task
is propagated.
A task must be
privileged or must be a CLI task in order to specify
a TI: other than the parent task's TI:.
m:et:e:

dnam
ids

Device
=

Integer to receive the directive status word.

Macro Call:
SPWN$

tname,,,[ugc] ,[umc],[efn] ,[east],[esb] ,[cmdlin],[cmdlen],
[unum], [dnam]

tname

Name (RAD50) of the offspring task to be spawned.

ugc

Group code number for the UIC of the offspring task.

umc

Member code number for
task.

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

5-173

the

UIC

the

offspring

when

DIRECTIVE DESCRIPTIONS
Address of an 8-word status block to be written when
the offspring task exits or emits status.

esb

Word

Offspring task exit status

Word

TKTN abort code

Word 2-7

Reserved
NOTE

The exit status block defaults to one
word.
To use the 8-word exit status
block, you must specify the logical or
of the symbol SP.WX8 and the event flag
number in the efn parameter above.

Address of a command
offspring task.

cmdlin
cmdlen

line

queued

for

Length of the command line (maximum length is 79.).
Unit number of terminal to be used as the TI:
for
the offspring task.
:iro!rial;J<.foal:n pat·P:m:~'ter'
rs .n i.r.~·!J~,~,i.~i.~~l~t· :t;\h\;:,,
!lll.·.~·s··· t'' !l~, · ithe unit
!num
· '1 ()t:: ·~:· 'q'i;~;t:J~~1;x:1
!elait'.e
y the issuing
i:tas
if a value. of o is specified, the TI:· of the
issuing
task
is propagated.
A task must be
privileged or must be a CLI task in order to specify
a TI: other than the parent task's TI:.

unum

Device name mnemonic.

dnam

.:tex:lltQ.~1:;,r:91;;,µ~m:•~·····.···•i'-;t·~i'"',

Macro Expansion:
SPWN$
.BYTE
.RADSO
.BLKW
.BYTE
.BYTE
.BYTE
.WORD
.WORD
.WORD
• WORD

the

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
16.
;EXIT STATUS BLOCK CONSTANT
ASTRUT
;AST ROUTINE ADDRESS
STBLK
;EXIT STATUS BLOCK ADDRESS
CMDLIN
;ADDRESS OF COMMAND LINE
72.
COMMAND LINE LENGTH = 72 •

NOTE
·::.
'j~~~)~i(;
I'
one addi tionaf · parameter (device name)
can be added for a hardware terminal
name. For ex ample, TT 2 !"(~g
fq T
···~)
would have the same macro expansion
shown above, plus the following:

.ASCII

/TT/

;ASCII

DEVICE NAME

The DPB size will then be 14 words.

5-174

DIRECTIVE DESCRIPTIONS
Local Symbol Definitions:
S. PWTN

Task name (4)

S. PWXX

Reserved (6)

S. PWUM

User member code (1)

S. PWUG

User group code {l)

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:

rs. sue

Successful completion.

IE. UPN

Insufficient dynamic memory to allocate an offspring
control block, command line buffer, 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. PRI

Nonprivileged task attempted to specify an
task's TI: to be different from its own.

5-175

not

offspring

DIRECTIVE DESCRIPTIONS
DSW Return Codes:
IE.IOU

The

terminal unit does

speci

is not a terminal.

not

exist,_,

IE.IEF

Invalid event flag number (EFN<O, or EFN>96 if group
global event flags exist for the task's group; or
EFN>64 if not).

IE.ADP

Part of the DPB, exit status block, or command
is out of the issuing task's address space.

IE.SOP

DIC or DPB size is invalid.

line

Notes:
1.

If the UIC is defaulted and the offspring task is not a
Command Line Interpreter (CLI), that task is requested to run
under the UIC of the parent task.
If the UIC is defaulted,
the offspring task is a CLI, and the CLI passes the specified
command line to a dispatched task, the dispatched task will
run under the UIC of its TI:
terminal.
See the notes for
the Request Task (RQST$) directive for more information about
task UICs.

If the specified event flag is group global, then the use
count for the event flag's group is incremented to prevent
premature elimination of event flags.
The use count is run
down when:
•

Status is returned from the spawned task.

•

The issuing task exits before status is returned.

The virtual mapping of the exit status block should not be
changed while the connection is in effect. Doing so may
cause obscure errors.

The types of operations that
perform are extremely limited.
a list of restrictions.

a
FORTRAN AST routine may
Please refer to Chapter 1 for

The following program illustrates the use of the FORTRAN callable
SPAWN routine and the mechanism for handling ASTs from a FORTRAN
program:

P R 0 G R A M

S P WA S T

c
C This program illustrates the use of the FORTRAN callable
C SPAWN routine and the use of a FORTRAN subprogram at AST state.
C This example keeps "ITMAX" tasks active at any point in time
C without having several copies of each utility installed under
C different names. The input file consists of single line commands
C of up to 45 characters in length which invoke tasks in the system
C library UIC. The first three characters of the input command line
Care the name of the task to be invoked(ie: MAC).
The output file
C consists of a log file containing the command lines and the exit status
C of the program invoked.

5-176

DIRECTIVE DESCRIPTIONS

C The above is accomplished as follows:

A command is read from the input file "CMDFIL.CMD" which has the

c form "NAM COMMAND where NAM is the name of the task and COMMAND is the
c command to be passed to this task. This input command line is transformed
c into an MCR "RUN° command line such as
•RUN $MAC/TASK=TSK#/EST=NO/CMD="COMAND•.
c
c where i is a number assigned by this task so that the target task name
c is both known and unique. The MCR dispatcher (MCR ••• ) is spawned with this
c transformed command line, which in turn causes the MCR ••• task to dispatch
c a copy of ••• MCR under the name MCRTnn to execute this command. When
c this copy of ••• MCR exits, an exit AST is serviced by this task which
This method introduces a timing
c issues a "CONNECT" to the target task "TSKf
c window such that the target task could exit before the CONNECT is made. In
c this case, an error message is written to the log file indicating that
c exit status could not be returned due to a connect failure.
c
c This non-privileged FORTRAN IV-PLUS program is compiled and
0

•

c built as follows:

C MCR>F4P SPWAST,SPWAST/-SP=SPWAST
C MCR>TKB SPWAST/FP,SPWAST=SPWAST,LB:[l,l]F4POTS/LB

c
c
C Define data structures

c
c
c
c
c
c

The following variables are kept on a per active 0 invoked task 0 basis
For lack of a better name, each respective entry is called task
inforamation block.
IESTAT(8,XXX)

IEXSAD(XXX)

ISTAT(XXX)

ICMDLN(45,XXX)

c
PARAMETER ITMAX=3
COMMON /KOM1/IESTAT(8,ITMAX),IEXSAD(ITMAX),ISTAT(ITMAX),IPARM,RTNAME(2)
COMMON /KOM2/THISTK(l6)
COMMON /COMMAN/ICMDLN(45,ITMAX)
INTEGER IE STAT
INTEGER IE XS AD
INTEGER IS TAT

c
INTEGER I PARM
INTEGER RTNAME

c
INTEGER THISTK
BYTE ICMDLN

!exit status array for each task
!array containing the address of each task's iestat
!array containing the status (active vs free) of
each task information block.
!contains address of IESTAT at AST state
!contains the RAD50 name of the target task to be
!connected to at AST state
!saved input command line per task

c
C

Local input buffer variables
DIMENSION INPCOM(3)
DIMENSION INPBUF(45)
EQUIVALENCE (INPBUF(l),INPCOM(l))
BYTE INPBUF
BYTE INPCOM

! INPUT BUFFER
!COMPONENT NAME FIELD OF INPBUF

5-177

DIRECTIVE DESCRIPTIONS

c
C

Local variables for SPAWN call
EXTERNAL EXTAST

!define the name of the AST routine externally

DIMENSION

!maximum command line passed to is 79. bytes

CMDLI~(79)

BYTE CMDLIN
INTEGER*4 DSPNAM

c
C

DATA

!actual command line passed to MCR •••
!variable containing RAD50 task name of MCR •••

DSPNAM/6RMCR ••• /!fill in name of ••• MCR at compile time

Local control variables
INTEGER ITCNT
LOGICAL EOF

!count of number of free task information blocks
!flag indicating EOF detected on command input file

c
C

Misc. local variables
INTEGER IDSW

!integer to contain directive status

C Open files

OPEN (UNIT=l,TYPE='OLD',READONLY,NAME='CMDFIL.CMD')
OPEN (UNIT=2,TYPE='NEW' ,CARRIAGECONTROL='FORTRAN',NAME='CMDFIL.LOG')

c
C Initialize Variables

ITCNT=ITMAX+l
EOF=.FALSE.

!set current count of available task info blocks
! reset EOF flag

CALL IRAD50(3,'TSK',RTNAME(l))
CALL GETTSK(THISTK(l))
C

!setup first half of target task name
!determine this task's name so that
STOPing and UNSTOPing may be done

C Initialize the IEXSAD array such that each entry contains the address
C of the exit status block which has the corresponding index. This is
C necessary so that the correct exit status block may be determined at AST
C state.

DO 5 I=l,ITMAX
CALL GETADR(IEXSAD(I),IESTAT(l,I))
CONTINUE

c
C Read a command line from the input file and initialize a free task info
C block.

15
16

20
30
C

READ (l,900,END=30)I,INPBUF
!read input command line
ITCNT=ITCNT-1
!one less free block
DO 20 K=l,ITMAX
!search for the free block
IF (ISTAT(K) .NE. 0) GOTO 20
!IF NE, block is in use
ISTAT(K)=l
!ELSE found one, mark it in use
DO 15 J=l,I
!save command line for output later
ICMDLN(J,K)=INPBUF(J)
CONTINUE
DO 16 J=I+l,45
!pad saved command line with spaces
ICMDLN(J,K)="40
CONTINUE
GOTO 40
!exit search loop
CONTINUE
EOF=.TRUE.
set EOF flag
GOTO 55
continue to log exit status of what's currently
active

5-178

DIRECTIVE DESCRIPTIONS

c
C Construct the actual command line specified in the SPAWN call

c
c
c
40
710
8 00

Write saved command line to TI: so that any MCR "RUN" error messages
have context.
WRITE(5,710) (ICMDLN(J,K) ,J=l,45)
FORMAT(lX,45Al)
ENCODE(I+35,800,CMDLIN)INPCOM,K,(INPBUF(J),J=l,I)
FORMAT ( I RUN $', 3Al, I /TASK=TSK I , Il, I /EST=NO/CMD="' , 45Al)
CMDLIN(I+32)="42
!add terminating quote
CMDLIN(I+33)="15
!and terminator.

C Spawn MCR ••• with the command line such as~
c
C

"RUN $MAC/TASK=TSK1/EST=NO/CMD="MAC TESTl=TESTl""

C At this point the second half of the RAD50 target task name is calculated
C so that the first exit AST may issue a connect after ••• MCR exits.
RTNAME(2)=40*40*(30+K)

!calculate second half of RAD50 taskname

C Spawn the MCR dispatcher with the constructed command line. The dispatcher
C will then spawn a copy of ••• MCR which will in turn process the "RUN" command.
45
C
C
C
C
C

CALL SPAWN(DSPNAM,,,l,EXTAST,IESTAT(l,K),IPARM,CMDLIN,I+33,0,,IDSW)
An error could be received from the SPAWN call. This could be due to a
variety of reasons, such as the task file specified was not found or there
was insufficient system resources at the time the executive directive
was issued. Only the IE.RSU errors will be recovered by waiting for
a significant event and reissuing the call to SPAWN.
IF(IDSW+l) 50,52,54

!check directive status returned

c
C Spawn error

c
50

IESTAT(l,K)=5
IESTAT (2, K) =IDSW
ISTAT(K)=3
GOTO 60

!if mi, uncorrectable error mark status
!save directive status returned for log
·!indicate status present
!go write error to log file and cleanup

C Spawn error due to insufficient resources
c
52
CALL WFSNE
!wait for significant event
GOTO 45
! reissue SPAWN

C Spawn successful, wait till ••• MCR exits and first AST has been serviced.

c
54

CALL WAITFR(l)

!wait for ••• MCR to exit

C Do not STOP if connect failed, just process task info block and continue ••

IF(IESTAT(l,K)

.EQ. 6) GOTO 60

!exit status code of 6 indicates
connect failure ••

C At this point a check is made to determine whether this task has
C completed its quest. If there is no more input and all task information
C blocks are free, then exit processing will be performed.

5-179

DIRECTIVE DESCRIPTIONS

IF(EOF .AND.

(ITCNT .EQ. ITMAX+l)) GOTO 500

C Next, if all the task information blocks are being used, or if there
C is no more input to process, this task is stopped so as to lower its
C priority effectively to zero. This task will once again wake up when
C the connect AST unstops this task.

IF(ITCNT .EQ. 1 .OR.

(EOF)) CALL STOP

C Scan all the task information blocks to process task information blocks
C which are now waiting for cleanup and log file processing.

60
C
C
61
62
C
63
64
65
66
67
68
70
900
901
902
903
904
905
906
907
908

DO 70 K=l,ITMAX

!search task information blocks for
the task(s) which exited
IF (ISTAT(K) .NE. 3) GOTO 70
!if eq, then offspring task connect AST
has not occurred for this task
WRITE (2,901) (ICMDLN(J,K),J=l,45)
!write cmdlin to log file
GOTO (62,63,64,61,65,66,67),(IESTAT(l,K) .AND. "377)+1 !decode exit status
WRITE (2,902) (IESTAT(l,K) .AND. "377) !unknown exit status
GOTO 68
WRITE (2,903)
!EX$WAR -- warning
!or none returned
GOTO 68
WRITE (2,904)
!EX$SUC
success
GOTO 68
!EX$ERR
WRITE (2,905)
error
GOTO 68
WRITE (2,906)
!EX$SEV
severe error
GOTO 68
WRITE (2,907)IESTAT(2,K)
!internal -- SPAWN failure
GOTO 68
WRITE (2,908)IESTAT(2,K)
internal -- CONNECT failure
ISTAT(K)=O
free up task info block
IESTAT(l,K)=O
initialize exit status
ITCNT=ITCNT+l
adjust free task info block ct
CONTINUE
GOTO 10
FORMAT(Q,45Al)
FORMAT('$',45Al)
FORMAT('+','Unknown exit status =',I3)
FORMAT('+','<< Warning')
FORMAT('+','<< Success')
FORMAT('+','<< Error')
FORMAT('+','<< Severe error')
FORMAT('+','<< Spawn error, DSW =',I3)
FORMAT('+','<< Connect error, DSW =',I3)

c
C Exit cleanly by closing all files
c
500

CLOSE (UNIT=l)
CLOSE (UNIT=2)
CALL EXIT

close input file on LUN 1
close output file on LUN 2
exit

END

5-180

DIRECTIVE DESCRIPTIONS
S UB R 0 UT I N E

E XT A S T

PARAMETER ITMAX=3
COMMON /KOMl/IESTAT(B,ITMAX),IEXSAD(ITMAX),ISTAT(ITMAX),IPARM,RTNAME(2)
COMMON /KOM2/THISTK(l6)
INTEGER IESTAT
INTEGER IEXSAD
INTEGER ISTAT

c
INTEGER I PARM
INTEGER RTNAME

!exit status array for each task
!array containing the address of each task's IESTAT
!array containing the status (active vs free) of
each task information block.
!contains address of IESTAT at AST state
!contains the RADSO name of the target task to be
!connected to at AST state

INTEGER THISTK

EXTERNAL TSKEXT

C Using IPARM, which contains the address of the exit status block array,
C find the task information block, by comparing this with the address of each
C exit status block array.(contained in IEXSAD)

10
20

DO 10 I=l,ITMAX
IF (IEXSAD(I) .EQ. IPARM) GOTO 20 !found the task info block
CONTINUE
GOTO 30
I STAT (I) =2
! indicate ••• MCR has exited

C Try to connect to the target task

CALL CNCT(RTNAME(l),2,TSKEXT,IESTAT(l,I),IPARM,IDSW)
IF(IDSW .EQ. 1) GOTO 30
!IF EQ, then successful connect
IESTAT(l,I)=6
!else pass connect failed status
IESTAT(2,I)=IDSW
ISTAT (I) =3
!mark task info block as done.
RETURN
!return from AST state (returns to internal AST handler)
END
S UB R 0 UT I N E

C
C

T S K E X T

PARAMETER ITMAX=3
COMMON /KOM1/IESTAT(8,ITMAX),IEXSAD(ITMAX),ISTAT(ITMAX),IPARM,RTNAME(2)
COMMON /KOM2/THISTK(l6)
INTEGER IESTAT !exit status array for each task
INTEGER IEXSAD !array containing the address of each task's IESTAT
INTEGER ISTAT
!array containing the status (active vs free) of
each task information block.
INTEGER IPARM
!contains address of IESTAT at AST state
INTEGER RTNAME !contains the RADSO name of the target task to be
!connected to at AST state
INTEGER THISTK !This task's name (so that an UNSTOP may be performed)

C Find exit status block

10
20
30

DO 10 I=l,ITMAX
IF (IEXSAD(I) .EQ. IPARM) GOTO 20 !found the task info block
CONTINUE
GOTO 30
ISTAT(I)=3
!indicate AST has been serviced
CALL USTP(THISTK)
!UNSTOP this task
RETURN
!return from AST state (returns to internal AST handler)
END

5-181

DIRECTIVE DESCRIPTIONS

SRDA$
5.3.72

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
has been placed in the task's receive queue

•

Receive data ASTs for the issuing task are no longer desired.

When the directive specifies an AST service routine entry point,
receive data ASTs for the task will subsequently occur whenever data
has 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.
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:
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.

5-182

address

DIRECTIVE DESCRIPTIONS
Notes:
1.

A 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 5.3.4)
must be executed with the stack in the same state as when the
AST was effected.
4.

This directive cannot be issued either from
routine or when ASTs are disabled.

5-183

AST

service

DIRECTIVE DESCRIPTIONS

SREA$
SREX$
5.3.73

Specify Requested Exit AST Directive - SREA$ or SREX$

The Specify Requested Exit AST directive allows the task issuing the
directive to specify the AST service routine to be entered if an
attempt is made to abort the task by a directive or MCR or DCL ABO
command.
This allows a task to enter a routine for clean-up instead
of abruptly aborting.
If an AST address is not specified, any previously specified exit
is canceled.

AST

Privileged tasks enter the specified AST routine each time an abort is
issued.
However, subsequent exit ASTs will not be queued until the
fitst exit AST has occurred.
Nonprivileged tasks enter the specified AST routine only once.
Subsequent attempts to abort the task will actually abort the task.
SREX$ is the preferred form of this directive.
explained in Notes 1 and 2 below.

The

differences

are

FORTRAN Call:
CALL SREA(ast[,ids])
ast
ids

Name of the externally declared AST subroutine
=

Name of an optional integer to receive the
Status Word

Directive

CALL SREX (ast, i pbl k, i pblkl, [dummy] [,ids])
ast
ipblk

Name of the externally declared AST subroutine
=

Name
of
an
integer
trap-dependent parameters

array

receive

ipblkl

Number of parameters to be returned
array.

dummy

Reserved for future use

ids

Name of an optional integer to receive the
Status Word

Macro Call:
SREA$

[ast]

SREX$

[ast] [,dummy]

ast
= AST service routine entry point address
dummy = Reserved for future expansion

5-184

into

the

the
ipblk

Directive

DIRECTIVE DESCRIPTIONS

Macro Expansion:
SREA$
.• BYTE
.WORD

REQAST
167.,2
REQAST

SREX$
.BYTE
.WORD
.WORD

REQAST
167.,3
REQAST
0

;SREA$ MACRO DIC, DPB SIZE=2 WORDS
;EXIT AST ROUTINE ADDRESS
;SREX$ MACRO DIC, DPB SIZE=3 WORDS
;EXIT AST ROUTINE ADDRESS
;RESERVED FOR FUTURE EXPANSION
NOTE

The DPB length for the SREA$ form of the
For the SREX$
directive is two words.
form of the directive, it is three
words.

Local Symbol Definitions:
S.REAE

Exit AST routine address (2)

DSW Return Codes:

rs. sue

Successful completion.

IE.UPN

Insufficient dynamic storage.

IE. AST

Directive was issued from an AST service routine,
ASTs are disabled.

IE. ITS

ASTs already not desired, or nonprivileged task
attempted to respecify or cancel the AST after one
had already occurred.

IE.ADP

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

IE. SDP

DIC or DPB size is invalid.

5-185

address

DIRECTIVE DESCRIPTIONS
Notes:
1.

The SREX$ form of the directive is recommended for tasks that
wish
to handle all privileged and nonprivileged abort
attempts that do not violate multiuser protection checks.
The issuing task can use the information returned on the
stack for this version of the directive to decide how to
handle the abort attempt.
After specifying a requested exit AST using the SREX$ form of
the directive, the issuing task will enter the AST service
routine if any attempt is made to abort the task. On systems
with multiuser protection, nonprivileged abort attempts must
originate from the same TI: as that of the issuing task.
When the AST service routine is entered and the AST has been
specified using the SREX$ version of the directive, the
task's stack is in the following state:
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
DSW of task prior to AST
Trap-dependent parameter
Number of bytes to add to SP to clean stack (4)

The trap-dependent parameter is formatted as follows:
Bit 0

0 if the abort attempt was privileged
1 if the abort attempt was nonprivileged

Bit 1

0 if the ABRT$ directive was issued
1 if the MCR or DCL abort command was used

Bits 2-15 are reserved for future use
Tpe task must remove the trap-dependent parameters

from
stack before an AST Service Exit directive is executed.
recommended method is to add the value stored in SP+OO to
This
is also the only recommended way to access
non-trap-dependent parameters on the stack.
2.

the
The
SP.
the

The SREA$ form of the directive is recommended for privileged
tasks that do not wish abort attempts from a nonprivileged
user's MCR or DCL abort command to be allowed, and do not
otherwise care about the nature of the abort attempt. It is
also recommended for any nonprivileged tasks that simply do
not care about the nature of the abort attempt.
After specifying a requested exit AST using the SREA$ form of
the directive, privileged tasks will enter the AST service
routine if any of the following abort attempts is made:
•

Any privileged ABRT$ directive or privileged
abort command

•

Any nonprivileged ABRT$
multiuser protection

•

Any nonprivileged ABRT$ directive from the
systems with multiuser protection

5-186

directive

MCR

systems
same

DCL

without
TI:

DIRECTIVE DESCRIPTIONS
Nonprivileged tasks will enter the AST service routine for
all of the abort attempts listed above, plus the following:
•

Any nonprivileged MCR or DCL
without multiuser protection

abort

command

•

Any nonprivileged MCR or DCL abort command from
TI: on systems with multiuser protection

systems
the

When the AST service routine is entered, the task's stack
in the following state:
SP+06
SP+04
SP+02
SP+OO

same
is

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 an AST specified by
SREA$;
therefore, the AST Service Exit directive can be
executed with the stack in the same state as when the AST was
entered.
3.

The event flag mask word at the bottom of the stack 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 other stack data are in the user task, they can be
modified.
However, modifying the stack data may cause
unpredictable results.
Therefore, such modification is not
recommended.

If an SREX$ requested exit AST is not specified for a task,
it
is
impossible to abort a privileged task from a
nonprivileged terminal using either MCR or DCL on systems
with multiuser protection.

in the
The two forms of this directive should not be mixed
same code, since the stack format and the trap-dependent
parameters differ. Any mismatch between the form of the
directive
and the AST routine will have unpredictable
results.

Please see Chapter 1 for a list of restrictions on operations
that can be performed in a FORTRAN AST routine.

5-187

DIRECTIVE DESCRIPTIONS

SREF$
5.3.74

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 attachmerit .ocp~rs ~yen iLtl"l~ .rec:edyer:- .ta.sk .i~
al~~~dy a.t~C:l?l"l~d . t() . tl"l~ regl().1!, ~ri.;·e·s$ b•it•l11l'S~~A<'lt::
W'•·.~S~S:c
thei
:w1nd(>'w Pef:fnitioh. ··B.l:ock is·· set•
The successful execution of this
directive causes a significant event to occur.

i.n·<

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 8 words of 0.)

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 receiver task can default the permitted access 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 5.3.55). When the sender task exits, the system searches for
any unreceived references that specify event flags, and prevents any
invalid attempts to set the flags.
The references themselves remain
in the receiver 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.j

ids

Directive status
5-188

DIRECTIVE DESCRIPTIONS
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, 4 8.
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

i wd b ( 4 )

W. NR ID

ID of the region to be sent by reference

i wdb ( 5)

W. NOFF

Offset word, passed without checking

iwdb(6)

W.NLEN

Length word, passed without checking

i wdb ( 7)

W. NSTS

Bit settings 1 in window status word (the
receiver task's permitted access):

iwdb(8)

W.NSRB

Bit

Definition

WS.RED

1 if read access is permitted

WS.WRT

1 if write access is permitted

WS. EXT

1 i f 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.REEF

Event flag number (2)

1. If you are a FORTRAN programmer,
refer to Section 3.5.2 to
determine the bit values represented by the symbolic names described.
5-189

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. PRI

Specified access not allowed to sender task itself.

IE. NVR

Invalid region ID.

IE.IEF

Invalid event flag number (EFN<O, or EFN>96 if group
global event flags exist for the task; or EFN>64 if
not) •

IE. ADP

The address check of the DPB, the WDB,
buffer failed.

IE. SDP

DIC or DPB size is invalid.

could

the

not

send

Notes:
1.

For the user's convenience, the ordering of the SREF$ macro
arguments does not directly 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 to which it was
already attached, 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 specified event flag is group global, then the use
count for the event flag's group is incremented to prevent
premature elimination of the event flags.
The use count is
run down when:
•

The packet is received.

•

The issuing task exits before the packet is received.

5-190

DIRECTIVE DESCRIPTIONS

SRRA$
5.3.75

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.VPN

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

invalid.

5-191

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
5.3.4) must be executed with the stack in the same state as
when the AST was effected.

This directive cannot be issued either from
routine or when ASTs are disabled.

5-192

AST

service

DIRECTIVE DESCRIPTIONS

5-193

DIRECTIVE DESCRIPTIONS

STAF$

CPB ! UBF ! UBJ

.BYTE

161. I 2
242

.. WORD

;STAF$ MACRO DIC, DPB SIZE=2 WORDS
; AFFINITY MASK WORD ('OR' OF PARAMETERS)

Local Symbol Definitions:
Affinity mask word (2)

S.AFAF

DSW Return Codes:
IS.SUC
IE.ITS

Successful completion.
Task installed with affinity

5-194

DIRECTIVE DESCRIPTIONS

STIM$
5.3.77

Set System Time Directive

The Set System Time directive instructs the system to set the sys~em's
internal time to the specified time parameters. Optionally, the Set
System Time directive returns the system's current internal time to
the issuing task before setting it to the specified values.
All time parameters must be specified as binary numbers.
A task must be privileged to issue this directive.
When this directive changes the system time by a specified amount,
it
also effectively changes the time of anything resident on the clock
queue by the same amount. Thus, the time synchronization of events is
maintained.
FORTRAN Call:
CALL SETTIM (ibufn[,ibufp[,ids]])
An 8-word integer array -- new time specification
buffer

ibufn
ibufp

An 8-word integer array -- previous time buffer

ids

Directive status

Macro Call:
STIM$ bufn,[bufp]
buf n

Address of 8-word new time specification buffer

buf p

Address of 8-word buffer to receive the
previous system time parameters

Buffer Format:
Word 0

Year (since 1900).

Word 1

Month (1-12).

Word 2

Day (1-n, where n is the highest day possible for the
given month and year).

Word 3

Hour (0-23).

Word 4

Minute (0-59).

Word 5

Second (0-59).

Word 6

Tick of second (0-n, where n is the frequency of the
system clock minus one) •
If the next parameter
(ticks per second) is defaulted, this parameter is
ignored.

Word 7

Ticks per second (must be defaulted or must match the
frequency of the system clock). This parameter is
used to verify the intended granularity of the "tick
of second" parameter.

5-195

DIRECTIVE DESCRIPTIONS
NOTE
If any of the specified
new
time
parameters are defaulted (equal to -1),
the corresponding previous system time
parameters will
remain unchanged and
will be substituted for the defaulted
parameters during argument validation.
Macro Expansion:
STIM$
.BYTE
.WORD
.WORD

NEWTIM,OLDTIM
61., 3
NEWT IM
OLDTIM

;STIM$ DIC, DPB SIZE=3 WORDS
;ADDRESS OF 8.-WORD INPUT BUFFER
;ADDRESS OF 8.-WORD OUTPUT BUFFER

Local Symbol Definitions:
S. TIBA

Input buffer address (2)

S. TIBO

Output buffer address (2)

The following offsets are assigned relative to the start of each
parameters buffer:
S.TIYR

Year {2)

S.TIMO

Month ( 2)

S.TIDA

Day (2)

S.TIHR

Hour

S.TIMI

Minute ( 2)

S.TICS

Second ( 2)

S.TICT

Clock tick of second ( 2)

S. TICP

Clock ticks per second ( 2)

time

( 2)

DSW Return codes:

rs. sue

Successful completion.

IE. PRI

The issuing task is not privileged.

IE. !TI

One of the specified time parameters is out of range,
or
both
the
tick-of-second parameter and the
ticks-per-second parameter were specified and the
ticks-per-second
parameter
does
not match the
system's clock frequency.
The system time at the
moment the directive is issued
(returned
in the
second buffer) can be useful in determining the cause
of the fault if any of the specified time parameters
were defaulted.

IE.ADP

Part of the DPB or one of the buffers is out
issuing task's address space.

IE. SDP

DIC or DPB size is invalid.

5-196

the

DIRECTIVE DESCRIPTIONS
Notes:
1.

Execution of this directive generates an Error Log packet and
sends it to the Error Logging subsystem.

The highest clock frequency supported by the operating system
is 1000 hz for a programmable clock. Note that as the clock
frequency approaches this value, the maximum resolution for
this directive becomes more time critical. The accuracy of
this directive depends upon the elapsed time between the
moment that a new system time is specified and the time that
the directive actually traps to the Executive.

The buffers used in this directive are compatible with
of the Get Time Parameters (GTIM$) directive.

The second buffer (previous time) is only filled
in if the
directive was successfully executed or if it was rejected
with an error code of IE.IT!.

5-197

those

DIRECTIVE DESCRIPTIONS

STLO$
5.3.78

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 event flags from one of the following groups:
GR 0

Local flags 1-16

GR 1

Local flags 17-32

GR 2

Common flags 33-48

GR 3

Common flags 49-64

GR 4

Group global flags 65-80

GR 5

Group global flags 81-96

The task does not stop itself if any of the
already set 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 with the Unstop directive or the MCR Unstop or DCL START
command.
FORTRAN Call:

...

CALL STLOR (iefl, ief2, ief 3,
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
47

;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.TLGR

Group flags (2)

S. TLMS

Mask word (2)

5-198

DIRECTIVE DESCRIPTIONS
DSW Return Codes:

rs.sue

Successful completion.

IE.AST

The issuing task is at AST state.

IE.IEF

An event flag group other than 0 thru 5
specified, or the event flag mask word is zero.

IE.ADP

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

IE.SDP

DIC or DPB size is invalid.

was

address

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 l were specified
(as in the above macro expansion
example), bit 0 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
Stop For Logical OR Of Event Flags conditions are met.
Some
directives (Queue I/O Request, for example) implicitly clear
a
flag;
otherwise, they must be explicitly cleared by a
Clear Event Flag directive.

The argumer1t 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.

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 .9!.E operand must always be of the form n regardless of
the macro form used.
In all other macro calls, numeric or
address values for---SS-form macros have the form:

For STLO$S this form of the grp argument would be:
n

If the specified event flag group is group global,
the
group's
use count is incremented to prevent premature
elimination of the event flags.
The use count is run down
when:
•

The Stop For condition is satisfied.

•

The issuing task exits before the Stop
satisfied.

5-199

For

condition

DIRECTIVE DESCRIPTIONS

STOP$S
5.3.79

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; this task issuing an Unstop directive at AST state; or
the MCR Unstop or DCL START command.
FORTRAN Ca 11 :
CALL STOP ([ids])
ids

Integer to receive the directive status word

Macro Call:
STOP$S
Macro Expansion:
STOP$S
MOV
.BYTE
EMT

(PC)+, -(SP)
131., 1
377

;PUSH DPB ONTO THE STACK
;STOP$ MACRO DIC, DPB SIZE=l WORD
;TRAP TO THE EXECUTIVE

Local Symbol Definitions:
None
DSW Return Codes:
IS. SET

Successful com pl et ion.

IE.AST

The issuing task is at AST state.

IE. ADP

Pa rt of the DPB is out of the issuing task's
space.

IE. SDP

DIC or DPB size is invalid.

5-200

address

DIRECTIVE DESCRIPTIONS

STSE$
5.3.80

Stop For Single Event Flag

The Stop For Single Event Flag directive instructs the system to stop
the issuing task until the specified 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 by the Unstop directive or the MCR Unstop or DCL START
command.
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:

7
135.,2
7

STSE$
.BYTE
.WORD

;STSE$ MACRO DIC, DPB SIZE=2 WORDS
;LOCAL EVENT FLAG NUMBER = 7

Local Symbol Definitions:
S.TSEF

Event flag number (2)

DSW Return Codes:

rs.sue

Successful completion.

IE.AST

The issuing task is at AST state.

IE.IEF

Invalid event flag number (EFN<l, or EFN>96 if group
global event flags exist for the task's group; or
EFN>64 if not).

IE.ADP

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

IE.SOP

DIC or DPB size is invalid.

address

Note:
If the specified event flag is group global, the

the

event

flag's

group

elimination of event flags.

incremented

use

count

for

prevent premature

The use count is run down when:

•

The Stop For condition is satisfied.

•

The issuing task
satisfied.

exits

before

5-201

the

Stop

For

condition

DIRECTIVE DESCRIPTIONS

SVOB$
5.3.81

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 intratask 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.
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:
SVOB$

[adr] [ ,len]

adr

Address of SST vector table

len

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

The vector table has the following format:
Word O

Odd address of nonexistent memory error

Word 1

Memory protect violation

Word 2

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

PDP-11/40 floating-point exception

A O entry in the table indicates that the task does not
process the corresponding SST.

want

Macro Expansion:
SVOB$
.BYTE
.WORD
.WORD

SSTTBL, 4
103.,3
SSTTBL
4

;SVOB$ MACRO DIC, DPB S!ZE=3 WORDS
;ADDRESS OF SST TABLE
;SST TABLE LENGTH=4 WORDS

5-202

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.

5-203

DIRECTIVE DESCRIPTIONS

SVTK$
5.3.82

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) the table
words

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 IOT 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

5-204

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. SDP

DIC or DPB size is invalid.

5-205

DIRECTIVE DESCRIPTIONS

ULGF$
5.3.83

Unlock Group Global Event Flags ($S Form Recommended)

The Unlock Group Global Event Flags directive instructs the Executive
to decrement the use count of the group global event flags for the
issuing task's protection group UIC (H.CUIC+l)~
This unlocks flags
that were locked by the Create Group Global Event Flags directive.
A task may only unlock the event flags once before locking them again.
The group global event flags
conditions are satisfied:

are

eliminated

the

•

The use count in the group global
event flag
(GFB) is zero after this directive is issued ..

•

The GFB is marked for deletion.

following

two

control

block

FORTRAN Ca 11 :
CALL ULGF ([ids])
ids

Directive status

Macro Call:
ULGF$S
err

[err]
Error routine address

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

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

;PUSH DPB ONTO THE STACK
;DIC=l59., DPB SIZE= 1 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. RSU

Event flags already unlocked from the issuing task.

IE.ADP

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

IE. SDP

DIC or DPB size is invalid.

5-206

address

DIRECTIVE DESCRIPTIONS

UMAP$
5.3.84

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.
FORTRAN Ca 11 :
CALL UNMAP ( i wdb [,ids] )
iwdb

An 8-word integer array containing a Window Definition
Block (see Section 3.5.2.2}

ids

Directive status

Macro Call:
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
Element

Off set

iwdb(l}
bits 0-7

W.NID

ID of the window to be unmapped

Output parameters
i wdb ( 7}

W.NSTS

Bit settings 1 in the window status word:
Bit

Definition

WS.UNM

1
if
the
window
successfully unmapped

was

Local Symbol Definitions:
U.MABA

Window Definition Block address (2)

1. If you are a FORTRAN programmer, refer to Section 3.5.2 to
determine the bit values represented by the symbolic names described.
5-207

DIRECTIVE DESCRIPTIONS

DSW Return Codes:

rs. sue

Successful completion.

IE. ITS

The specified address window is not mapped.

IE.NVW

Invalid address window ID.

IE.ADP

DPB or WDB out of range.

IE. SDP

DIC or DPB size is invalid.

5-208

DIRECTIVE DESCRIPTIONS

USTP$
5.3.85

Unstop Task

The Unstop Task directive unstops the specified task that has stopped
itself by either the Stop or the 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 by means of 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.
It is considered the responsibility of the unstopped task to determine
if it has been validly unstopped.
The Unstop directive does not cause a significant event.
FORTRAN Call:
CALL USTP (rtname[,ids])
rtname

Name of task to be unstopped

ids

Integer to receive 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.ITS

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.SDP

DIC or DPB size is invalid.

5-209

DIRECTIVE DESCRIPTIONS

,·

.. ·.

·:··,: .. ·'

····~.s;·.86 variab1e R~d~iV<l.··.I>at~
•if
i i/;i•••<•••···
. 'flt~ ~arr~bl g~ecei"~. l)~~~ dii~cft-,.l .itlstructi (theri 1is~.;m
.•
•t:Fs*;·····.
.

tb i d<l<Jti<lll<;·····. a·.
tJ1e::.d~t.~·<blo9ik . . h~·~.···

•. Yiiriable.,..~~pgth ...•.. da.t:.a· . · .blpp·~ f9·r.·. t:h~.lssLiJ.1'19 ..•
·been . ··qQeued (jf lFQ)/ . . .f:o r .. the. ·1:,a§k. by · a .. ;Variable · . .:$end >•. J)at~.•·i· . qirective ~· ·
.\VllE!cl'l .a: ~en~er ·tasJ< is :SPeGifiea, 9nJ.y :P:e\ta s:er1t by the s:peqiftec1 task.
is·receivea·...
..·.·. ·.·
· ::>· •. ·•....•.... >. > ··,\ .·;<;\;.
•.•.
<> :
:·>_=.:. ; . <; . . :" . :.=:··
,_:·... . .. .
.. ,
)~qlf:¢r .si•;#.e: c~A ~ b~·· ·2.S6;~ >>. wC>.f"~i n\'a~iiirt·u~·. < •:rt ·no ::bt1ti~r ·•sX·~~··;. rs
··s.p.ec.~. . f.i~.·~·,.:·· . . .• th<?···.·······.:·~·\.ir•~~. r: ii···~:iz:~··•••i. s.•i•.fp.ij.:·. ·:. ·~~f(fsi.•~. . . ·········•····iI~.··.•;a.·•.·.···6:i;t·£~r.·.····.·~·1·i~··•. ·.·9r-.ea:i:·e·~···
than.:·· 2:s6~
is .• ·• specified1an•·IE·~.
IB S; •.• e .,rrot•.· .•. i·s.> returned•· ·
'"
:
"·i···< :'"':·:·'

... ;·.-_::,:.::.

., , . ... . .. .. .

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

...... ..

':.·~

, .

. . . .. .

. . '... .. ;

.. '., . . : . . . .. . . . : . : .... : .. ~. : . :

. . . : .. : . : ... ~ : : . .

;, . : .: . :.- . : ..... , ....... : : . . .. . . . ·..

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

: : .... ·.: ·.: : . . : .. , .. . : . . ...... : : '; . .; : . .. '

· re:turned · . in th.(3;· sp~c~f:i~·c1 b{1ffe.~, \Vith·t:h~~·ta·~ki·na~e·.·. in·.:.tbe.·fi.rGb .two·~.·
words• F():r·.· this·.•. r:eason,: · t~J:t.sto}'(l9e<yoµ . all;ocat.Et · wLt.:hil'l·.· . .· .ttie •.. buffer
.should .b.e .... two worcls <Jreater .than the size. <:if the dat;:a po·rtion of the
inessage· ·specifieq in the.··. d.irecHve.
·
·
·
.

.'::_·,

. . ···

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

... ·.··

... · .. ·;·

: ·. . . · . . . . .

·. . '

. Varlabl~~Tengt~ data blocks :are.· transferred ·.from.···~he sending

t.he· receivi~g •task by .means <of•.·bu.:f:fer:~.in .·th~ seco~dary ·'f)ool

FORTRAN Call:

Ct task] ;bufadr, [bufleri] [ ;ldSJ)

CALL VRCD
task

Sender task .name

buf.

Address of buffer to receive the sender task name and

buflen =

L~ngth

ids

data

of buffer

Integerto receive the directive status word.

If the directive was successful, it returns the number of words
transferred into the user buffer. If the directive execution
encountered an error, It returns the error code in the ids
parameter.

Any error return ·of the form IE.XXX is a negative word value. If
the. status is positive, the . value of the .status word is the
J1Umber of words transferredinclud ing the taskname. For:example;
i f you specify a buffer size. of 13 in the VRCD$ call1 the value
returned in the direc'tive statu.s word is 15 (13 words of data
plus the two words, nee<)ed ·to return the taskname).

size in

5-210

DIRECTIVE DESCRIPTIONS

5-211

DIRECTIVE DESCRIPTIONS

·s. 3.87

Variable< Recelye :bata·(lr ·stop

•. Ahe Vad~bl e ReceJ\le. Pata ··or StO£> atre<!t1J.e .. instructs.. the
d<le99.eue .... · <l ·yariablE!-l~ngth da~ablo9k fo.r :t:hE! .~ssµi11<f . ta~k;

}:)1opk\has>beeni .. qµe11ed< (FIFO).·.·.· for·.· tbe<task ·.by ·a . • ·. . vc:iri9ble• .... s~nd, D~t~
. cliri;;ctiy.E!·....
u ... tber~<·· . i.§.. ·no >s.u<:h.·.paq·ket.to.be. dequeµl$q•, . th~··.· .• issuipg ..
~qSk is.··stopped• ....In> this pase 1 ~n()~hE!.r .·.~ap~ .... <ttie . . . s~ndE!r >t<isk) . if;
expepted·.· . . t() •.... issµe .....· aI) . .• unstopdirect:ive. <l~t~r sel'ldlngtl:le.data~ . ·.When
stoRJ?ed. Jn. this man:.ne·r, ·.. the di rectiye .· • .. status . · returnE!d is . .· IS;. 9Wrr
iJ1<lica~ing ·. tha~ >,t;~e tzssk 'Was ... st()PPE!d: . >aJ1p >that.. n() (iata:·. hcts been
rf!<Jeiv.ed; ·. hoY?eyer1 . • ·~in.c:.e ttie t9$k ~.µ$tl}e.• ·,1.1l}st:opp~ci 111 . orq~r . ••. t:<:> ......se;e
.th.isi .·.·sta t:;us, . ·. · the.·.· .•. tasl<.·.·.·· can now. ·J::t:is.su~··· the. Vt;jriable: Receive Data·.• Qr
s'top>directi.ve to agtua1ly re~eive t.he data.packet.
.
' '
'
When a sender task :ts. specified, only data sent by the
is received·.

Buffer size can be 256..
words
If no buffer
specified, t:be . }:)uff~r size is 13. V/()rds. I f a buffer she greater
than 256. is specified,· an IE.TBS error is returned.;.
A 2;,.;wor<l sender task name (in Rad ix_;SO form) and the

data olock are
returned in the specified buffer, with the task name in the first 2
words. For this reason, the storage you allocate within the buffer
should be two words greater than the size of the data portion of the
message sp·ecified in the directive.
Variable-length data blocks are transferred from the sending task
the receiving task by means of buffers in the secondary pool.

FORTRAN Call:

CALL VRCS ([task] ,bufadr, [buflenJf ,ids])
task

;::

Sender task name

buf

;::

Address of buffer to receive the sender J:ask name .and
data

buflen

Length of· buffer

ids

Iritegerto····receive the.· direbtive . . st.~itus word
'.·:·· .··=····=:

. ,._ .. _::

If<the direct,ive was' SUCCe$Sfy1, ft rett1rns the number of words
transferred into the user buffer. u· the directive execution:
encountered an error, it returns the error code in the. ids
parameter.
Ar)y·.·errof retur,Il of the . formi .IE~XXX .if; a ne~l~t~ve •.,..,opLv~lu~) If
the .• st:atus ••.·.•.·.rs· pos~tive1· · :the .•. •. . vaJ.ue·.·.·()f·t:h.e sta.tus:·\V()~d:Js the
r1Um~er· . · of.•· VIO.rds.· . :. t;ran~fer:r~d ,11'.lfludil}g· t~~i t<lskJ1(;l~e ~ ..· · · Jr()r...· ex9~p1··~,
•. . i.f· . .·, yo~.>· ~pecify . ·a ~t:l~fe:r st;z:'e; o~f }3 1~ tbe: 'VRCS$,. Ccl~l, the' value
··r~tu:r!'led: Jn . . t~e d~rec.tive . .• ?~a'f:.ps. wopd Js.. 1s. {13 word•s of data
······plus. t~e .·twq.·•.·w<:>·rosine~<led•to • l;'e't;,t.trn>th.e>J:asknamet~

5-212

DIRECTIVE DESCRIPTIONS

5-213

DIRECTIVE DESCRIPTIONS

Hii}<< . <>><·.
.·.s •..s.dsa .. ·i~ari.ab.l~iRe~·~•iv~··.·.oa~···~·. . . gf.··. . Exit· . .·.·.·. .· · . ·. . · . ·.·:.· •· •.·•·•· ·. .• .•. .•. •. •.• . .• . • · · · · .·.· .·
·••iTI1e . . .•. . va.·f i·•~bl·~····· ····R~c·e:i~e:·••·n1ia.·.··.···Or.··········E~. .•l~··· · · i •.'f~.·c·t:·iv·e·.•·. in.•s.truc··~ s . •.· · the

s·y~.t.em·.•· .·.·. to
~equeuE!..•.•. ~a· ya.r-tapl~--le~gth .qata t>I·()ck· ~o.r·.·the. Js$uing·. t:a$k; . ·the:d<:lta .
. ·b~oc.k.·hasb'.¢en 9l1eued . · · <rIF.O) fop t:l1e ta~J<·. by··•·.·.·. 9 .Variab~e ·s~l)d .•. Data
dir~c.tive • . ::~er1 ..·a. .....·s~nder ·. t:ask.·fs spe.clf,ied, cmly data..sent: ·by ttie:
specified.·.·
task. is•·r:ec.eived.···· · ·. ··· ...·'...... · .·, . . · .. , .. , .
.
.
..
: ·:_.··_.,':=!.'·.·.,,

.*i~or~ l>~nd.,r t_~.~l<ill~m~
. r•eturned ·. }1).

tih. ~<l~fic:~o . ·ibi~> .~r<<l th~

th~ ·.. specifie~. 'bufr.~r,.wit:~· th~ :·~a-~k

data . bidck .. ;>r.,
name. in the'fits;t .·2,

wod:ls • ·. J?9·rt:9i'~······r~a:EjoJ1, . .·.t9e·.·.St:ot'a~j'e. yo~ ·~~~.OC<ite witf}in .... th~...·.·: .bµ:Efer.
sl}oulcf··· ·be··· 'tw,o··. ·.wpird.$ . .·.·9re'at~r· than t:h~~. sJze:. of·.·.the a:<=i~a''P<>'rtl~n· .of·. th~.
111essag e ?Peci~J ~<l in .t:he .··cl ir ec:tive·.
·

; :····.•. >>·•>> . .·. -.·:••' i' i<u:<••········.·· ... ··· :< • : •••. ••
I~···. no .·data.·ha$.····b.ee.n ... sent:, .a . .·ta,~ke:}{·~t. ... oc~urs .•
loss· ... of sen<ld~ta p<:ickets, . . the· user should
tgke care o.f any out~t:.and.ing I/0 or
assume this responsibility~
·

pr;~vetJt .. the.· ~sslt>li:r;

on .. I/O xun,down to
.the. task shoulP,

Buffet size can be 256~
words·; maximurth
is
Specified, the buffer size. is 13. words.
a buffer size greater
than 256.
is. specified, an ·IE.•IBS error is returned.

Variable-length data blocks are transferred from the >sending task
the receiving task by means of buffer~ in the secondary pool~

FORTRAN .Call:
CALL VRCX ([task] ,bufadr, [ buflen] [,ids])
task

Sender task name

buf

Address of buffer to receive the sender task name and
data

buflen =

Length of buffer

ids

Integer to receive the directive status word

If the directive was successful, it returns the number of words
transferred into the user buffer. If the directive execution
encountered an error, it
parameter.

returns

the . erro?,"

code

the

ids

of the form TE.XXX is a negcitiye word value. If
1S po Si tive, . the. value . of the Stat;uS Word is the
numbe;- of \'1ord$ transferr:ec:l including the tasknG\me., For example,
if . you specify. a .·J:>uffer .size of .. 13. in t})e· VRCX$. call,. ·
returned in the directive status word is 1,5 <·p.3· words
plus the two W<nds needea··to teturn.t})e t(:lsk,name).;..

Macro cail~

Sender
Buffer

-· Buffer

5-214

DIRECTIVE DESCRIPTIONS

5-215

DIRECTIVE DESCRIPTIONS

efn

Event flag number
Integer to receive the directive status word

ids
Macro Call:
VSDA$

task

5-216

DIRECTIVE DESCRIPTIONS

5-217

DIRECTIVE DESCRIPTIONS

iast

= Name of

when

the

Name of an 8-word status block to be written
the offspring task exits or emits status

when

offsprin~

iesb

an AST routine to
task exits or emits

Word

Offspring task exit status

Word

TKTN abort code

2-7

Reserved
NOTE

5-218

DIRECTIVE DESCRIPTIONS

5-219

DIRECTIVE DESCRIPTIONS

5-220

DIRECTIVE DESCRIPTIONS

WSIG$S
5.3.91

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 ) + , - ( S P)
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 n ERR"

Local Symbol Definitions:
None
DSW Return Codes:
IS. sue

Successful completion.

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.

If a directive is rejected for lack of dynamic memory, this
directive is the only technique available for blocking task
execution until dynamic m€mory 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 $8
form of the macro is recommended= It requires less space and
executes with the same speed as that of the DIR$ macro.

5-221

DIRECTIVE DESCRIPTIONS

Significant events include the following:
•

I/O completion

•

Task exit

•

Execution of a Send Data directive

•

Execution of a Send Data, Request and Pass OCB directive

•

Execution of a Send, Request and Connect directive

•

Execution of a Send By Reference directive or a Receive 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
end of a round-robin scheduling interval

•

Execution of an Exit, an Exit with Status, or Emit
directive

Status

5-222

the

DIRECTIVE DESCRIPTIONS

WTLO$
5.3.92

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

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 SET NUMBER 2 (FLAGS 33:48.)
;EVENT FLAGS 33,34,46,47 AND 48.

Local Symbol Definitions:
None
DSW Return Codes:

rs. sue

Successful completion.

IE. IEF

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.

5-223

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 l were specified, then bit 0 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 Event 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 $S form macros have the form:

#n
For WTLO$S this form of the grp argument would be:
n

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.

If the issuing task has outstanding buffered I/O when it
enters the Wait For state, it will be stopped. When the task
is in a stopped state, it can be checkpointed by any other
task regardless of priority. The task is unstopped when:

•

The outstanding buffered I/O completes.

•

The Wait For condition is satisfied.

If the specified group of event flags is group global, the
group's
use count is incremented to prevent premature
elimination of the event flags.
The use count is run down
when:
•

The Wait For condition is satisfied.

•

The issuing task exits before the Wait
satisfied.

5-224

For

condition

DIRECTIVE DESCRIPTIONS

WTSE$
5.3.93

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.IEF

Invalid event flag number (EFN<l, or EFN>96 if group
global event flags exist for the task's group; or
EFN>64 if not).

IE.ADP

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

IE.SOP

DIC or DPB size is invalid.

address

Notes:
1.

The outstanding buffered I/O completes.

•

The Wait For condition is satisfied.

If the specified event flag is group global, the group's use
count is incremented to prevent premature elimination of
event flags. The use count is run down when:
•

The Wait For condition is satisfied.

•

The issuing task exits before the Wait
satisfied.
5-225

For

condition

APPENDIX A
DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL

ABRT$

Abort Task
FORTRAN Call:
CALL ABORT (tsk[,ids])
tsk

Task name to be aborted (RAD50)

ids

Directive status

Macro Call:
ABRT$

tsk

Task name to be aborted (RAD50)

Alter Priority

ALTP$

FORTRAN Call:
CALL ALTPRI ( [tsk], [ ipri] [,ids])
tsk

Active task name

ipri

A 1-word integer value equal to the new priority,
1 to 250 (decimal)

ids

Directive status

Macro Call:
ALTP$

[tsk] [,pri]

tsk

Active task name

pri

New priority, from 1 to 250 (decimal)

A-1

from

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
ALUN$

Assign LUN
FORTRAN Call:
CALL ASNLUN (lun,dev,unt[,ids])
lun

Logical unit number

dev

Device name (format:

unt

Device unit number

ids

Directive status

1A2)

Macro Call:
ALUN$

lun,dev,unt

lun

Logical unit number

dev

Device name (two characters)

unt

Device unit number

AST Service Exit ($S form recommended)

ASTX$S

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 =

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

ids

Directive status

Definition

Macro Call:
ATRG$
rdb

rdb
Region Definition Block address
CINT$

Connect To Interrupt Vector
FORTRAN Call:
Not supported

A-2

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
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
ISR, and enable/disable interrupt routines

isr

Virtual address of the ISR, or 0 to disconnect from the
interrupt vector

edir

Virtual address of the enable/disable interrupt routine

pri

Initial priority at which the ISR is to execute

ast

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

entered

the

after

CLEF$

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

Event flag number

ids

Directive status

Macro Call:
CLEF$

efn

Event flag number

Cancel Mark Time Requests

CMKT$

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

Event flag number

ids

Directive status

Macro Call:
CMKT$

[ efn ,a st, err]

efn

Event flag number

ast

Mark time AST address

err

Error routine address

A-3

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
Connect

CNCT$

FORTRAN Call:
CALL CNCT (rtname, [iefn], [iast], [iesb], [iparm] [,ids])
rtname

Name (RAD50) of the offspring task to be connected

iefn

Event flag to be set when the offspring
or emits status

iast

Name of an AST routine to be called
offspring task exits or emits status

when

the

iesb

Name of an 8-word status block to be written
the offspring task exits or emits status

when

Word

Word 1-7

task

exits

Offspring task exit status
Reserved

iparm

Name of a word to receive the status
when an AST occurs

block

address

ids

Integer to receive the Directive Status Word

Macro Call:
CNCT$

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

tname

Name (RADSO) 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

Offspring task exit status
Reserved

A-4

when

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL

CRAW$

Create Address Window
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

Window Definition Block address

Create Group Global Event Flags

CRGF$

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

ids

Integer to receive the Directive Status Word

Macro Call:
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 =

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

ids

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
FORTRAN Call:
CALL CANALL (tsk[,ids])
tsk

ids

Task name
Directive status

Macro Call:

CSRQ$
tsk

tsk
Task name

A-6

CSRQ$

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
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 ($5 form recommended)

DSAR$S

FORTRAN Call:
CALL DSASTR [(ids)]
ids

Directive status

Macro Call:
DSAR$S

[err]

err

Error routine address

Disable Checkpointing ($S form recommended)

DSCP$S

FORTRAN Call:
CALL DISCKP [(ids)]
ids

Directive status

Macro Call:
DSCP$S

[err]

err

Error routine address

Detach Region

DTRG$

FORTRAN Call:
CALL DTRG (irdb[,ids])
irdb =

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

ids

Directive status

Macro Call:
DTRG$
rdb

rdb
=

Region Definition Block address

A-7

Definition

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
ELAW$

Eliminate Address Window
FORTRAN Call:
CALL ELAW { i wd b [ , ids] )
iwdbi

An 8-word integer array
containing
Definition Block {see Section 3.5.2.2)

ids

Directive status

Window

Macro Call:
ELAW$

wdb

Window Definition Block address
ELGF$

Eliminate Group Global Event Flags
FORTRAN 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

El.iminate Virtqal .Terminal

FORTRAN Call:

EMST$

Emit Status
FORTRAN Call:
CALL EMST ([rtname] ,istat[,ids])
rtname

= Name of task connected to issuing task to which

the

status is to be emitted

is tat
ids

A 16-bit quantity to be returned
task

the

connected

Integer to receive the Directive Status Word

A-8

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
Macro Call:
[tname] ,status

EMST$
tname

Name of a task connected to the
which the status is to be emitted

issuing

task

status

A 16-bit quantity to be returned
task

connected

Enable AST Recognition ($S form recommended)

the

ENAR$S

FORTRAN Call:
CALL ENASTR [(ids)]
ids

Directive status

Macro Call:
ENAR$S

[err]

err

Error routine address

Enable Checkpointing ($S form recommended)

ENCP$S

FORTRAN Call:
CALL ENACKP [(ids)]
ids

Directive status

Macro Call:
ENCP$S
err

[err]
=

Error routine address
EXIF$

Exit If
FORTRAN Ca 11:
CALL EXITIF (efn[,ids])
efn
ids

Event flag number
=

Directive status

Macro Call:
EXIF$
efn

efn
Event flag number

A-9

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
EXIT$S

Task Exit ($S form recommended)
FORTRAN Call:

Fortran tasks that terminate with the STOP statement result in a
message that includes task name, a statement causing the task to
stop, and an optional character string specified in the STOP
statement.
CALL EXIT terminates with the message STOP THIS
FORTRAN TASK.
Macro Call:
EXIT$S
err

[err]
Error routine address
EXST$

Exit With Status
FORTRAN Ca 11 :
CALL EXST (istat)
is tat

A 16-bit quantity to be returned to parent task

Macro Call:
EXST$

status

A 16-bit quantity to be returned to parent task

Extend Task

EXTK$

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 {If omitted, task size defaults to installed
task size.)

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 is to be extended or
reduced (If omitted, task size defaults to installed
task size.)

Get Command for Command Interpreter

GCCI$

Fortran Call:
CALL GTCMCI ( icbf, icbfl, [ i ibuf] , [ i ibfl] , [ iaddr] , [ incp] [,ids])
icbf

= Name of a byte to receive the command

A-10

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
icbfl

Integer containing the size of the icbf array in bytes

iibuf

Name of an integer containing
optional information buffer

iaddr

Name of an integer that contains the address in pool of
the command desired {This address was obtained by a
previous call to GTCMCI with GC.CND specified.)

incp

Name of an integer containing a value indicating
action to take if there is no command queued

ids

Integer to receive the directive status word

the

length

the

Macro Call:
GCCI$ cbuf,cbfl,[ibuf] ,[ibfl] ,[addr] ,[ncp]
cbuf

Address of buffer to receive command string

cbfl

Length of buffer.

ibuf

Address of buffer to receive information on the issuing
terminal

ibfl

Maximum

buffer

size

= Length of buffer to receive information

addr

Address of command

ncp

Action to take if no command buffer is present
GC.CCS {000)

Return with carry set {default)

GC.CEX {001)

Force CLI
returning

exit

instead

GC.CST (002)

Force CL!
returning

stop

instead

GC.CND {200) -- Copy command into buffer but do
dequeue it from the list

not

Get Command Interpreter Information

GCII$

FORTRAN Call:
CALL GETCII {ibuf ,ibfl, [icli], [idev], [iunit] [,ids]
ibuf

Name of an integer array to receive the CLI information

ibfl

Length in bytes of the integer array to receive the CLI
information

icli

Name of a 2-word array
name of the CLI

idev

Name of an integer containing
terminal (default= TI:)

name

iuni t

Name of an integer containing the octal unit number
terminal

ids

Directive status

A-11

element

containing
the

ASCII

the

RADSO

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
Macro Call:
GCII$ buf,bufl,cli,[dev] ,[unit]
buf

Address of buffer to receive information

bufl

Length of information buffer

cli

Name in RADSO of the CLI that information is
on

dev

ASCII name of terminal whose CL! should be used

unit

Octal unit number of terminal

requested

GLUN$

Get LUN Information
FORTRAN Call:
CALL GETLUN {lun,dat[,ids])
lun

Logical unit number

dat

A 6-word integer array to receive LUN information

ids

Directive status

Macro Call:
GLUN$

1 un ,buf

lun
buf

Logical unit number
=

Address of 6-word buffer
information

that

will

receive

the

LUN

GMCR$

Get MCR Command Line
FORTRAN Call:
CALL GETMCR {buf[,ids])
buf

An 80-byte array to receive command line

ids

Directive status

Macro Call:
GMCR$

A-12

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
GMCX$

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 th.e ~ask' s heade~ ~t'~;.~axiil\~.Il\.si:~:~ .. i,~
8*8:+1==65 .. on RSX".'."'llM .systems.
·Wll:~:;·:.111 .
um:::':s4,:z:~::;~$:\:
:.~'~.~;.~;++.¥':l::~:~··:;9p::: ~B'~'+?l~~~ft1ff£~'.~~~::,;;~y~rB:~~~:~'.t·

ids

:·· ·

· ·. · · · · · · ·

Directive status

Macro Call:
GMCX$

wvec

The address of a vector of n Window Definition Blocks;
n is the number of window blocks in the task's header.
GPRT$

Get Partition Parameters
FORTRAN 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

[prt] ,buf
=

buf

Partition name
Address of 3-word buffer
GREG$

Get Region Parameters
FORTRAN Call:
CALL GETREG ([rid],buf[,ids])
rid

Region id

buf

A 3-word integer array to receive region parameters

ids

Directive status

Macro Call:
GREG$

[rid] ,buf

rid

Region ID

buf

Address of 3-word buffer

A-13

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
Get Sense Switches ($S form recommended)

GSSW$S

FORTRAN Ca 11 :
CALL READSW (isw)
isw

Integer to receive the console switch settings

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

the

state

CALL SWITCH (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

Get Time Parameters

GTIM$

FORTRAN Ca 11 :
CALL GETTIM (ibfl[,ids])
ibfl

An 8-word integer array

ids

= Directive status

Macro Call:
GTIM$

buf

Address of 8-word buffer
GTSK$

Get Task Parameters
FORTRAN Call:
CALL GETTSK (buf(,ids])
buf
ids

A 16-word integer array to receive the task parameters
Directive status

Macro Call:
GTSK$
buf

buf
Address of 16-word buffer

A-14

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
IBAR$S

Inhibit AST Recognition ($S form recommended)
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 =

An 8-word integer array containing a Window
Block (see Section 3.5.2.2)

ids

Directive status

Definition

Macro Call:
MAP$
wdb

wdb
=

Window Definition Block address
MRK'1'$

Mark Time
FORTRAN Ca 11 :
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
interval is also included:

delaying

CALL WAIT (tmg,tnt,ids)
tmg

Time interval magnitude

tnt

Time interval unit

ids

Directive status

A-15

task

for

specified

time

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
Macro Call:
MRKT$

[efn] ,tmg ,tnt[ ,ast]

efn

Event flag number

tmg

Time interval magnitude

tnt

Time interval unit

ast

AST entry point address

Move to/from User/Supervisor I/D..;.Space

14V'l'S$

FORTRAN Call:
Not supported.
Macro Call:

MVTS$
action

action,addr ,val
buff

= One of the. following:
MV.TUI
Move to user I-space
MV.TUD
Move to user D...;.space
MV.TSI -- Move to supervi~ox I-space
MV.TSD
Move to.sut>ervfsorp•space
M.V.FUI
Move f,rom user I-space
.MV. FUD
Move from 'l1ser p-space ...·..
MV.FSI
Move from st1pervisor J,:-s·pace
MV.FSD·
Move frOm supervisor D"'."space

aaa·r
buf

= ·~dar·.ess ~f·the Joc~tion· irf.t.ne ··task:
= :Bttff7r t() r~c~~ve .the' value< fe.tcbed ~ for:
~r()JP•·.()t>er(lt;i.0~1~
.•••...·•.·:·.•.•· · · •\••·•·•i•··,/\ . .• •. ?/·. •.• •.•.•. •. •. · ·.·. . · •· · .·•.·.·
= Vall.le<to: be·. stored• 'lri t.hEl lOc_at:l()n~ f()tt.h~<move to
·. •.·•.•.•o~~i.a•t.•i.·o.ns

A-16

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
QIO$

Queue I/O Request
FORTRAN Call:
CALL QIO ( fn c , 1 un , [ e f n ] , [ pr i ] , [ i s b] , [ pr 1 ] [ , i d s ] )
fuc

I/O function code

lun

Logical unit number

efn

Event flag number

pri

Priority;

isb

A 2-word integer array to receive final I/O status

prl

A 6-word integer array containing device-dependent
parameters to be placed in parameter words 1 through 6
of the Directive Parameter Block (DPB). Fill in this
array
by
using the GETADR routine (see Section

ignored, but must be present

1.5.1.4).

Directive status

ids
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

ignored, but must be present

A 2-word integer array to receive final I/O status

prl

A 6-word integer array containing device dependent
parameters to be placed in parameter words 1 through 6
of the DPB

ids

Directive status

A-17

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
Macro Call:
QIOW$

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

prl

ignored, but must be present

Address of AST service routine entry point
Parameter list of the form <pl, ••• p6>

Receive Data Or Stop

RCST$

FORTRAN Call:
CALL RCST ([rtname] ,ibuf[,ids])
rtname
ibuf

Sender task name (If not
received from any task.)
=

ids

specified,

data

may

Address of 15-word buffer to receive the sender task
name and data
Integer to receive the Directive Status Word

Macro Call:
RCST$

[tname],buf

tname

Sender Task name (If not
received from any task.)

buf

Address of a 15-word buffer to
task name and data

specified,
receive

data
the

Receive Data

may

sender

RCVD$

FORTRAN Call:
CALL RECEIV ([tsk] ,buf[,,ids])
tsk

Sender task name
not specified, data may be
received from any task.)
IT~
\ ..... J..

buf

A 15-word integer array for received data

ids

Directive status

Macro Call:
RCVD$

[tsk],buf

tsk

Sender task name (If not
received from any task.)

buf

Address of 15-word buffer

A-18

specified,

data

may

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
RCVX$

Receive Data Or Exit
FORTRAN Call:
CALL RECOEX ([tsk],buf[,,ids])
tsk

Sender task name
(If not
received from any task.)

buf

A 15-word integer array for received data

ids

specified,

data

may

data

may

Directive status

Macro Call:
RCVX$ [tsk],buf
tsk

Sender task name
(If not
received from any task.)

buf

Address of 15-word buffer

specified,

ROAF$

Read All Event Flags
FORTRAN Call:
A FORTRAN task can only read a single event flag.
CALL READEF (efn[,ids])
efn

Event flag number (1-64.)

ids

Directive status

Macro Call:
ROAF$
buf

buf
Address of 4-word buffer

A-19

The call is:

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
Read Extended Event Flags

RDXP$

FORTRAN Ca 11 :
A FORTRAN task can read only a single event flag.

The call is:

CALL READEF (efn[,ids])
efn

Event flag number (1-96.)

ids

Directive status

Macro Call:
RDXF$

buf

Address of 6-word buffer

Request and Pass Offspring Information

RPOI$

FORTRAN Call:
CALL RPOI (tname, [iugc], [iumc], [iparen], [ibuf], [ibfl], (isc],
[itask], [ocbad] [,ids])
tname
iugc

An array containing the actual name of the task to be
requested and optionally chained to
= Integer containing the group code number for the

UIC

of the requested target chain task
iumc

Integer containing the member code number for the UIC
of the requested target chain task

i paren

Array (or I*4 integer) containing the RADSO name of
the parent task (This is returned in the information
buffer of the GTCMCI subroutine.)

ibuf

Array that contains the command
chained task.

A-20

line

text

for

the

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
isc

= Flag byte controlling the actions of

request when executed.
byte are as follows:

this directive
The bit definitions of this

RP.OEX = 128. Force
this
task
to
successful execution of
directive.
RP.OAL

exit
on
the RPO!

Pass all of this task's OCBs to the
requested task.
(Default is none.)

idnam

Integer containing the
requested tasks TI:

i unit

Integer containing the unit number of
tasks TI: device

itask

Array which contains the RAD50 name the requested
task is to run under.
(Valid only for CLis.)

ocbad

Integer containing the internal pool address of the
parent OCB (Only a CLI can specify this argument
because the value can only be obtained in the
information buffer of the GTCMCI subroutine.)

ids

ASCII

device

name
the

the

requested

= Integer to receive the directive status word

Macro Call:
RPO!$
tname,,,, [ugc], [umc], [parent], [bufadr], [buflen], [sc], [dnam],
[unit] , [ tas] k, [ ocba] d
tname

Name of task to be chained to

ugc

Group code for UIC of the requested task

umc

Member code for UIC of the requested task

parent

Name of issuing task's parent task whose OCB is to be
passed. If not specified, all OCB's are passed.

bufadr

Address of buffer to be given to the requested task

buflen
sc

= Length of buffer to be given to requested task

Flags byte:
RP.OEX
RP. OAL

(200) Force issuing task to exit
Pass all OCBs
(1)

dnam

ASCII device name for TI:

unit

Unit number of task TI:

task

RAD50 name of task to be started

ocbad

Address of OCB to pass (CLis only)

A-21

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
RQST$

Request Task
FORTRAN Call:
CALL REQUES {tsk, [opt] [,ids])
tsk

Task name

opt

A 4-word integer array:

ids

opt {1)

Partition name first half;
must be present

ignored,

but

opt{2)

Partition name second half;
must be present

ignored, but

opt {3)

Priority;

opt {4)

User Identification Code

ignored, but must be present

Directive status

Macro Call:
RQST$
tsk

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

prt
pri

Task name
Partition name;

Priority;

ignored, but must be present

ugc

UIC group code

umc

UIC member code
RREF$

Receive By Reference
FORTRAN Call:
CALL RREF { iwdb, [ isrb] [I ids])
iwdb = An 8-word integer array containing a Window
Block {see Section 3.5.2.2)
isrb

A 10-word integer array
buffer

ids

Directive status

Macro Call:
RREF$
wdb

wdb
Window Definition Block

A-22

used

Definition
the

receive

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
RSUll$

Resume Task
FORTRAN Call:
CALL RESUME (tsk[,ids])
tsk

Task name

ids

Directive status

Macro Call:
RSUM$

tsk

Task name

Run Task

RUN$

FORTRAN Call:
CALL RUN (tsk, [opt] , [ smg] , snt, [ rmg] , [mt] [,ids])
tsk

Task name

opt

A 4-word integer array:
opt ( 1)

Partition name first half;
must be present

ignored,

opt ( 2}

Partition name second half;
must be present

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

A-23

but

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
Macro Call:
RUN$
tsk

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

Task name

prt

Partition name;

pri

Priority;

ugc

UIC group code

umc

ignored, but must be present

UIC member code

smg

Schedule delta magnitude

snt

Schedule delta unit

rmg

Reschedule interval magnitude

rnt

Reschedule interval unit

SCLI$

Set Command Line Interpreter
FORTRAN Call:
CALL SETCLI ( icl i, idev, i unit [,ids])
icli

A two word array element containing the name of the CLI
to which the terminal is to be set

idev

Integer containing the ASCII name of the terminal to be
set (default= TI:)

iunit

Integer containing the unit number of terminal

ids

Directive status

Macro Call:
SC LI $ c 1 i , [ de v ] , [ un i t]
cli

Name of the CLI to which the terminal is to be set

dev

ASCII name of the terminal to be set (default= TI:)

unit

Unit number of terminal

A-24

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
SDAT$

Send Data
FORTRAN Call:
CALL SEND (tsk ,buf, [ efn] [,ids])
tsk

Task name

buf

A 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

SDRC$

Send, Request And Connect
FORTRAN Call:
CALL SDRC {rtname,ibuf, [iefn], [iast], [iesb], [iparm] [,ids])
rtname

Target task
connected

offspring

task

ibuf

Name of 13-word send buffer

iefn

Event flag to be set when the offspring
or emits status

task

exits

iast

Name of an AST routine to be called
offspring task exits or emits status

when

the

iesb

Name of an 8-word status block to be written
the offspring task exits or emits status

when

Word

Word 1-7

name

the

Offspring task exit status
Reserved

iparm

Name of a word to receive the status
when an AST occurs

ids

Integer to receive the Directive Status Word

block

address

Macro Call:
SDRC$

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

tname

Target task
connected

name

buf

Address of a 13-word send buffer

A-25

the

offspring

task

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
efn

The event flag to be cleared on issuance and when the
offspring task exits or emit status

east

Address of an AST routine to be called
offspring task exits or emits status

when

the

esb

Address of a 8-word status block to be written
the offspring task exits or emits status

when

Word

Word 1-7

Offspring task exit status
Reserved
SDRP$

Send Data Request and Pass Offspring Control Block
FORTRAN Call:
CALL SDRP (task,ibuf, [ibfl], [iefn], [iflag], [iparen],
[ iocbad] [,ids])
task

Name of an array (REAL, INTEGER,
the RAD50 name of target task

ibuf

Integer array containing data to be sent

ibfl

Integer containing number of words (integers)
in the
array to be sent (On RSX-llM systems, this argument
must be 13., and on RSX-llM-PLUS systems,
this
argument may be in the range of 1 to 255.) (Default =
13.)

iefn

Integer containing the number of the event flag to
set when this directive is executed successfully

iflag

Integer containing
flags
bits
controlling
execution. They are defined as follows:

the

SD.REX = 128.
SD.RAL

I*4)

that

contains

Force this task to exit
upon successful execution
Pass all OCBs

iparen

Name of array containing the RAD50 name of the parent
task whose OCB should be passed to the target task

iocbad

Name of an integer containing internal pool address of
the OCB to pa SS

ids

Integer to
receive
Status Word

the

contents

the

Directive

Macro Call:
SDRP$ task,bufadr, [buflen], [efn], [flag], [parent], [ocbad]
task

Name of task to be chained to

bufadr

Address of buffer to be given to the requested task

buflen

Length of buffer to be given to requested task

A-26

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
efn

Event flag

flag

Flags byte (Force exit, pass all OCB's)

parent

Name of issuing task's parent task whose OCB is to
passed

ocbad

Address of OCB to pass (CLI's only)

Set Event Flag

SETF$

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

Event flag number

ids

Directive status

Macro Call:
SETF$
efn

efn
Event flag number
SEPA$

Specify Floating Point Exception AST
FORTRAN Call:
Not supported
Macro Call:
SFPA$
ast

[ast]
AST service routine entry point address

Send Message

SMSG$

FORTRAN Call:
CALL SMSG (itgt,ibuf,ibufl,iprm,iprml,ids)
itgt

Integer containing the target object

ibuf

Integer array containing the data to be
the formatted data packet

ibufl

Integer containing length of the ibuf array

iprm

Integer array containing any additional parameters

iprml

Integer containing the number of parameters in the iprm
array

ids

Optional integer to receive the directive status

A-27

inserted

into

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
Macro Call:
SMSG$ tgt,buf,len,<pri, ••• ,prn>
tgt

Target identifier

buf

Address of optional data buffer

len

Length in bytes of optional data buffer

pri, ••• ,prn

Target-specific parameter list:

Parameter list for Error Logging
SMSG$ SM.SER,buf ,len,typ,sub,lun,mask>
typ

Error Log packet code

sub

Error Log packet subtype code

lun

Logical unit number of device

msk

Control mask word

A-28

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
Suspend ($5 form recommended)

SPllD$S

FORTRAN Call:
CALL SUSPND
ids

[(ids)J

= Directive status

Macro Call:
SPND$S

[err]

err

Error routine address

Specify Power Recovery AST

SPRA$

FORTRAN Call:
EXTERNAL sub
CALL PWRUP (sub)
Name of a
recovery.
following:

sub

power
subroutine to be executed upon
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.
To Remove an AST:
CALL PWRUP
Macro Call:
SPRA$

[ast]

ast

AST service routine entry point address

Spawn

SPifN$

FORTRAN Call:
CALL SPAWN (rtname,[iugc],[iumc] ,[iefn] ,[iast] ,[iesb] ,[iparm],
[icmlin], [icmlen], [iunit], [dnam] [,ids])
rtname

Name (RADSO) 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 flag to be set when the offspring

task

exits

or emits status
iast

Name of an AST routine to be called
offspring task exits or emits status

A-29

when

the

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
iesb

Name of an 8-word status block to be written
the offspring task exits or emits status
Word

Word 1-7

when

Offspring task exit status
Reserved

iparm

Name of a word to receive the status
when the AST occurs

icmlin

Name of a command
offspring task

icmlen

Length of the command line (79.

iunit

Unit number of terminal to be used as

dnam

Device name mnemonic (If not specified, the
terminal is used as TI:.)

ids

Integer to receive the Directive Status Word

line

block

address

queued

for

the

characters maximum)

th~
TI:
fo~
~(3~k (/~·$:.~'.'¥'. ' '·pt>~idpal.. ilrtam P<=tiram e.l; .·
9p~·p.~~~~9'.\f' ;Pili · ~ci. > .· .·~~.~:.lt'ltt~f::''i. tie· the..
··t::
Qif.. ·~··.··.·. . ;\t•irtual
;rn:t.i:n~1L c.;reate·d · by the is~h1rig
if a value of 0 is specified, the TI: of the
issuing task is propagated.)

oJf ~prip~

virtual

Macro Call:
SPWN$

tname,,, [ugc], [umc], [efn], [east], [esb], [cmdlin], [cmdlen]
, [ un um] , [ dnam]

tname

Name (RADSO) 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 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

cmdlin

Address of a command
offspring task

cmdlen

Length of the command line (maximum length is 79.)

unum

line

Unit number of termin9,l. to be used

queued

the

for

the

.r.r.: :·. J9.F·

.t}1e .· offspr}~9 . . < ..tas.K> .. 1If t:he :o.ptJ9#~·i-. dn~m J?<Itoaine·t~.~ ..
is:· ~·op-- spt~:~i·t~~~:~·:. tg~f> ·~<Jr~~7~r~ i1n0st· b:e ·the· •urfit
.:number .ofL.cL.virtu:al t:ermin.al... created .by the i.sslifng<i

·t:~.~k:-;'

i f a value of 0 is specified, the TI:
issuing task is propagated.)

A-30

of the

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
dnam

Device name mnemonic (If not specified, the
terminal is used as TI:.)
NOTE
1.

If neither unum nor dnam is specified,
the
TI:
of the issuing task is
propagated.

SRDA$

Specify Receive Data AST
FORTRAN Ca 11 :
Not supported
Macro Call:
SRDA$

[ast]
AST service routine entry point address

ast

SREA$
SREX$

Specify Requested Exit AST
FORTRAN Call:
CALL SREA (ast[,ids])
ast

Name of the externally declared AST subroutine

ids

Name of an optional
Status Word

integer

receive

the

Directive

CALL SREX (ast,ipblk,ipblkl, [dummy] [,ids])
ast

Name of the externally declared AST subroutine

ipblk

Name of an integer array to receive the
parameters

ipblkl = Number of parameters to be
array

returned

dummy

Reserved for future use

ids

Name of an optional integer to
Status Word

receive

Macro Call:
SREA$ [ast]
SREX$

[ast] [,dummy]

ast

AST service routine entry point address

dummy

Reserved for future expansion

A-31

trap-dependent
into

the

ipblk

Directive

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
Send By Reference

SREF$

FORTRAN Call :
CALL SREF {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)

Definition

isrb

An
8-word
information

additional

ids

Directive status

integer

array

containing

Macro Call:
SREF$

task,wdb[,efn]

task

Receiver task name

wdb

Window Definition Block address

efn

Event flag number

Specify Receive-By-Reference AST

SRRA$

FORTRAN Call:
Not supported
Macro Call:
SRRA$
ast

[ast]
AST service routine entry point address

A-32

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
Set System Time Directive

STiil$

FORTRAN Call:
CALL SETT IM ( ibufn [, i bufp] [,ids] )
ibufn

An 8-word integer array, new time specification buffer

ibufp

An 8-word integer array, previous time buffer

ids

= Directive status

Macro Call:
STIM$ bufn, [ buf p]
buf n

Address of 8-word new time specification buffer

buf p

Address of 8-word buffer to receive the previous system
time parameters

Stop For Logical OR Of Event Flags

STLO$

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 form recommended)

STOP$S

FORTRAN Call:
CALL STOP ([ids])
ids

Integer to receive the Directive Status Word

Macro Call:
STOP$S
Stop For Single Event Flag

STSE$

FORTRAN Call:
CALL STOPFR (iefn[,ids])
iefn

Event flag number

ids

Integer to receive Directive Status Word

A-33

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
Macro Call:
STSE$

efn

Event flag number
SVDB$

Specify SST Vector Table For Debugging Aid
FORTRAN Call:
Not supported
Macro Call:
SVOB$

[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)

Unlock Group Global Event Flags ($S form recommended)

table

ULGF$S

FORTRAN Call:
CALL ULGF ([ids])
ids

= Directive status

Macro Call:
ULGF$S [,err]
err

= Error routine address
UNMAP$

Unmap Address Window
FORTRAN Ca 11 :
CALL UNMAP (iwdb[,ids])
iwdb =
. ids

An 8-word integer array containing a Window
Block (see Section 3.5.2.2)
Directive status

A-34

Definition

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
Macro Call:
UMAP$
wdb

wdb
Window Definition Block address

Unstop TASK

USTP$

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-35

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL

A-36

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL

A-37

DIRECTIVE SUMMARY - ALPHABETICAL ORDER BY MACRO CALL
Wait For Significant Event ($S form recommended)

WSIG$S

FORTRAN Ca 11 :
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
WTSF$

Wait For Single Event Flag
FORTRAN Call:
CALL WAITFR (efn[,ids])
efn

Event flag number

ids

Directive status

Macro Call:
WTSE$
efn

efn
Event flag number

A-38

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, use the following two lines of code:
.MCALL
DRERR$

DRERR$

STANDARD ERROR CODES RETURNED BY DIRECTIVES IN THE DIRECTIVE STATUS
WORD
IS. CLR

IS.SET

+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.PRI
IE. RSU
IE. NSW
IE. ILV

-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

-80.
-81.

DIRECTIVE ISSUED/NOT ISSUED FROM AST
ISR OR ENABLE/DISABLE INTERRUPT ROUTINE
NOT WITHIN 4K WORDS FROM VALUE OF
BASE ADDRESS & 177700

rs. sue

IE .MAP

B-1

STANDARD ERROR CODES
IE. IOP
IE .ALG
IE.WOV
IE.NVR
IE.NVW
IE.ITP
IE. IBS
IE.LNL
IE. IUI
IE. IDU
IE. ITI
IE. PNS
IE. IPR
IE.ILU
IE. IEF
IE.ADP
IE. SDP

-83.
-84.
-85.
-86.
-87.
-88.
-89 ..
-90.
-91.
-92.
-93.

-94.
-95.
-96.
-97.
-98.
-99.

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
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 each
directive.
The DIC appears in the low byte of the first {or only)
word in the Directive Param€ter 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)
ZK-312-81

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 5.
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

Octal Byte
Values

Binary Word
Value

5(10)

71(10)

107(8)

5(8)

101

Octal Word
Value

000

111

2507 (=SDAT$)
ZK-313-81

C-1

DIRECTIVE IDENTIFICATION CODES
Octal Value For
DPB First Word

Directive
(Macro Call)

Decimal
DIC

Values For
DPB Length

433
443
455
461
463
537
541
543
545
563
575
603

CMKT$
DECL$S
SPND$S
WSIG$S
EXIT$S
DSCP$S
ENCP$S
DSAR$S or IHAR$S
ENAR$S
ASTX$S
GSSW$S
STOP$S

2 7.
35.
45.
49.
51.
95.
97.
99.
101.
ll5.
125.
131.

1.
1.
1.
1.
1.
1.
1.
1.
1.
1.
1.
1.

1025
1035
1037
1041
1047
1051
1065
1067
1071
1073
1075
1077
ll21
1153
1155
1157
1161
1165
1171
1173
1207

SRRA$
EXST$
CLEF$
SETF$
RDAF$
WTSE$
EXIF$
CRRG$
ATRG$
DTRG$
GTIM$
GTSK$
RREF$
SRDA$
SPRA$
SFPA$
GMCX$
CRAW$
MAP$
UMAP$
STSE$

21.
29.
31.
3 3.
39.
41.
53.
55.
57.
59.
61.
63.
81.
107.
109.
lll.
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.

151:.

·2~

157.
159.
i.61~

2.
2.
2:~:

:2.
2.
3.
3.
3.
3.
3.
3.
3.
3.
3.
3.
3.
3.

u G s

1'.22:1

EiVT$ .·

1235
1237

CRGF$
ELGF$

.lf:~~

SifAF;$

12145

SPEA$

jJ65~

1247
1405
1431
1433
1447
1453
1457
1475
1523
1531
1547
1551
1605

SREA$
GLUN$
CSRQ$
CMKT$
RDXF$
WTLO$
RSUM$
STIM$
ABRT$
EXTK$
SVDB$
SVTK$
USTP$

167.
5.
25.
27.
39.
43.
4 7.
61.
83.
89.
103.
105.
133.

C-2

DIRECTIVE IDENTIFICATION CODES
Octal Value For
DPB First Word

Directive
(Macro Call)

Decimal
DIC

Values For
DPB Length

1611

STLO$

137.

1647
2007
2011
2101
2113
2115
2213
2223
2427
2505
2507

SREX$
ALUN$
ALTP$
GPRT$ or GREG$
RCVD$
RCVX$
RCST$
EMST$
MRKT$
SREF$
SDAT$

167.
7.
9.
65.
75.
77.
139.
147.
23.
69.
71.

3.
4.
4.
4.
4.
4.

3413
3601
3615

RQST$
CINT$
SDRC$

11.
129.
141.

7.
7.
7.

4.
4.
5.
5.

11.
12.
12.
13.
14.
41.

QIO$
QIOW$
SPWN$
SPWN$
GMCR$

C-3

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$
CLEF$
CMKT$

System Type
RSX-llM

RSX-llS

* ( 1)
*
0 (2)

0
0

0
0
0

(3)
(1)

(2)
(3)
(1)

*
*
*
*
*

(1)

RSX-HM-PLUS

CRGF$

*
*

DECL$S
DSAR$S or IHAR$S
DSCP$S
DTRG$
ELAW$

*
*
0 (2)

*
0 (2)

N/A
0
0

( 3)
(3)

0
0
0

(7)
( 3)
(3)

0
0

(2)
(7)

*
*
*

ENAR$S
ENCP$S
EXIF$
EXIT$S
EXST$
EXTK$
GCCI$
GCII$
GLUN$
GMCR$
GMCX$
GPRT$
GREG$
GSSW$S
GTIM$

( 2)

N/A

*
*
0 ( 4)
0

*
*

(1)

N/A
N/A

( 4)
(1)

(15)
( 15)

*
*

N/A

0
0

(3)

( 3)

I"\

I 1

\ .L J

I"\

I 1 \

\.LI

0
0

(3)
( 1)

0
0

( 3)
( 1)

*
D-1

*
*0 (15)
0

*
*

( 15)

RSX-11 SYSGEN SELECTION OF EXECUTIVE DIRECTIVES

Directive
Macro
Call

GTSK$
MAP$
MRKT$

QIOW$
RCST$
RCVD$
RCVX$

RQST$
RREF$
RSUM$
RUN$
SCAA$
SC1\L$S'
SCLI$
SDAT$
SDRC$
SDRP$
SETF$
SFPA$
SMSG$
SNXC$
SPEA$:

System Type
RSX-llS
0
0

RSX-llM

(1)
(3)

0
0

( 1)
(3)

*
*
*

* (13, 14)

*
*
*
*

* (13,14)

( 14)
(14)

0
0

* ( 1, 3)
*
*
N/A
0

( 14)
( 14)

* ( 1, 3)
*
*

* (2, 10)

0
0
0
0

( 14)
(4,14)
(14,15)

* (2, 10)

N/A

0
0

N/A

N/A;

( 12)

SPND$S
SPRA$
SPWN$
SRDA$
SREA$
SREF$
SREX$
SRRA$
SRRC$
STAF$
STIM$
STLO$
STOP$S
STSE$
SVDB$
SVTK$
ULGF$S
UMAP$

N/A.

N/!

0
0
0
0

WTLO$
WTSE$

*
*

* (2, 11)

0
0
0
0
0
0
0

(4)
( 2, 14)
( 1, 2)
( 1, 3)
( 1, 2)
( 1, 2, 3)
N/A
(
(13)

( 13)
(13)

*
*

* ( 2, 11)

0
0
0
0
0
0
0

(4)
( 2, 14)
( 1, 2)
( 1, 3)
( 1, 2)
( 1, 2, 3)
N/A

*
*
0
0

*
*

D-2

*
*
*
*
0 ( 15)

.. ·. iQ

't!f/~:

N/A
0 ( 14)
0 (4,14)
N/A

RSX-1111-PLUS

(1
( 13}
(13)

( 13)

H~J

( 15)

*
*
*
*
0 ( 10)
*
*
*
*
*
*
*
*
*
*
*
*
0

*
*
*
*
*
*
*
*

*
*

(SJ

RSX-11 SYSGEN SELECTION OF EXECUTIVE DIRECTIVES
SYSGEN Options:
1.

Specific Executive directive support

AST support

Memory management directives

Parent/offspring tasking support

Group-global event flag support

Checkpointing support

10.

Floating Point Processor support

11.

Powerfail recovery support

12.

Error Logging support

13.

Stop bit synchronization support

14.

Send/receive support

15.

Alternate CLI support

.·1-.6.~ ·····•P;$~~A~·····~µl?~~lt

D-3

INDEX

Abort Task, 5-8
ABRT$, 5-8
Address mapping, 3-2
Address space,
logical, 3-2, 3-4
physical, 3-2
virtual, 3-2, 3-4
Address window,
virtual, 3-3
Addressing,
PDP-11, 3-1
Affinity, 5-128
removing, 5-128
setting, 5-193
Alter Priority, 5-10
ALTP$, 5-10
ALUN$, 5-12
Assign LUN, 5-12
AST,
command arrival, 5-145
definition, 2-4
exit, 5-184
floating point processor
exception, 5-160
general characteristics, 2-7
parity error, 5-167
power recovery, 5-170
purpose, 2-6
receive data, 5-182
receive-by-reference, 5-191
service routine, 2-7
task's stack format,
2-8 to 2-11
trap-dependent parameters,
2-8
AST recognition, 5-53 to 5-54
AST routine,
FORTRAN callable, 1-16
AST Service Exit, 5-14
ASTX$S, 5-14
Asynchronous System Trap
(AST) , 2-4
ATRG$, 5-16
Attach Region, 5-16
Attachment descriptor, 3-9

Batch processingr 4-1
Buffer format,
for GTIM$ directive, 5-95
for GTSK$ directive, 5-97

$C macro form, 1-6
CALL ABORT, 5-8
CALL ALTPRI, 5-10
CALL ASNLUN, 5-12
CALL ATRG, 5-16
CALL CANALL, 5-51
CALL CANMT, 5-29
CALL CLREF, 5-28
CALL CNCT, 5-31
CALL CPCR, 5-34
CALL CRAW, 5-37
CALL CRGF, 5-40
CALL CRRG, 5-42
CALL CRVT, 5-48
CALL DECLAR, 5-52
CALL DISCKP, 5-55
CALL DSASTR, 5-53
CALL DTRG, 5-56
CALL ELAW, 5-58
CALL ELGF, 5-60
CALL ELVT, 5-62
CALL EMST, 5-64
CALL ENACKP, 5-66
CALL ENASTR, 5-65
CALL EXIT, 5-70
CALL EXITIF, 5-67
CALL EXST, 5-71
CALL EXTTSK, 5-73
CALL GETCII, 5-79
CALL GETLUN, 5-81
CALL GETMCR, 5-84
CALL GETPAR, 5-89
CALL GETREG, 5-91
CALL GETTIM, 5-95
CALL GETTSK, 5-97
CALL GMCX, 5-86
CALL GTCMCI, 5-75
CALL INASTR, 5-53
CALL MAP, 5-100
CALL MARK, 5-103
CALL PWRUP, 5-170
CALL QIO, 5-112
CALL RCST, 5-118
CALL READEF, 5-125, 5-127
CALL RECEIV, 5-120
CALL RECOEX, 5-122
CALL RESUME, 5-139
CALL RMAF, 5-128
CALL RPO!, 5-129
CALL RREF, 5-136
CALL RUN, 5-140
CALL SDRC, 5-152

Index-1

INDEX

CALL SDRP, 5-155
CALL SEND, 5-150
CALL SETCLI, 5-148
CALL SETEF, 5-159
CALL SETTIM, 5-195
CALL SMSG, 5-162
CALL SNXC, 5-165
CALL SPAWN, 5-172
CALL SREA, 5-184
CALL SREF, 5-188
CALL SREX, 5-184
CALL STAF, 5-194
CALL STLOR, 5-198
CALL STOP, 5-200
CALL STOPFR, 5-201
CALL SUSPND, 5-169
CALL ULGF, 5-206
CALL UNMAP, 5-207
CALL USTP, 5-209
CALL VRCD, 5-210
CALL VRCS, 5-212
CALL VRCX, 5-214
CALL VSDA, 5-216
CALL VSRC, 5-218
CALL WAIT, 5-103
CALL WAITFR, 5-225
CALL WFSNE, 5-221
CALL WTQIO, 5-116
Cancel Mark Time Requests,
5-29
Cancel Time Based Initiation
Requests, 5-51
Chaining, 4-1, 5-129, 5-155
Checkpoint Common Region, 5-34
Checkpointing during buffered
I/O, 2-11
CINT$, 5-18 to 5-19
Clear Event Flag, 5-28
CLEF$, 5-28
CMKT$, 5-29
CNCT$, 5-31
Command buffer format, 5-76
Common block attached,
determining region ID of,
5-16
Common Block Directory {CBD),
5-42
Common event flag,
reading, 5-127
Common region,
force checkpointing, 5-34
Connect, 5-31
Connect to Interrupt Vector,
5-18
Connecting and passing status,
4-3
Console switch register, 5-93
Convention,
for using system directives,

Index-2

Convention (Cont.)
5-5
macro name, 1-5
CPCR$, 5-34
CPU/UNIBUS affinity, 5-128,
5-193
CRAW$, 5-36 to 5-39
Create Address Window, 5-36
Create Group Global Event
Flags, 5-40
·
Create Region, 5-42
Create Virtual Terminal, 5-45
CRGF$, 5-40
CRRG$, 5-42
CRVT$, 5-45
CSRQ$, 5-51

Data,
including in supervisor-mode
library, 5-107
Data space, 5-107
mapping user, 5-107
supervisor, 5-107
Data structure,
user, 3-11
Declare Significant Event,
5-52
DECL$S, 5-52
Delaying a task,
ISA standard call for, 5-103
Detach Region, 5-56
DIC, 1-2
DIR$ macro, 1-5 to 1-7
Directive,
macros, 1-4
processing, 1-2
rejection, 1-3
Directive Identification Code
{DIC) , 1-2
Directive Parameter Block
{DPB) , 1-2
Directive Status Word (DSW),
1-2
DIRSYM.MAC, 4-3
Disable AST Recognition, 5-53
Disable Checkpointing, 5-55
DPB, 1-2
on stack, 1-4, 1-6
pointer on stack, 1-4
predefined, 1-6 to 1-7
$DPB$$, 1-6
DRGIN.MAC, 1-20
DSAR$S, 5-53
DSCP$S, 5-55
D-space, 3-1 to 3-2
mapping, 3-3 to 3-4
DSW, 1-2

INDEX

$DSW, 1-2
DTRG$, 5-56
Dynamic region, 5-42

ELAW$, 5-58
ELGF$, 5-60
Eliminate Address Window, 5-58
Eliminate Group Global Event
Flags, 5-60
Eliminate Virtual Terminal,
5-62
ELVT$, 5-62
·Emit Status,. 5-64
EMST$, 5-64
EMT 377 instruction, 1-1
Enable AST Recognition, 5-65
Enable Checkpointing, 5-66
ENAR$S, 5-65
ENCP$S, 5-66.
Error logging, 5-162
Error return, 1-3
Error routine argument, 1-7
Event,
flag, 2-2
significant, 2-1, 5-52
Event flag, 2-2
common, 2-2
group global, 2-2
group-global, 5-60, 5-206
implicitly altering, 2-2
locking, 5-40
mask word, 5-105
polarity, 5-28
reporting polarity,
5-125 to 5-127
setting, 5-159
stopping for, 5-198, 5-201
testing, 2-3
unlocking, 5-60, 5-206
wait for, 5-223
Executive-level dispatching,
5-5
EXIF$, 5-67
Exit,
task resources freed, 1-3
Exit If, 5-67
Exit With Status, 5-71
EXIT$S, 5-69
EXST$, 5-71
Extend Task, 5-73
EXTK$j 5-73

FORTRAN, 1-9
AST service routine, 1-16
directives not available,
1-15
operations forbidden at AST
state, 1-16 to 1-17
specifying task names, 1-10
FORTRAN subroutine,
1-9 to 1-10
assigning address arguments,
1-11
corresponding macro call,
1-12 to 1-15
directives not available as,
1-15
error condition, 1-16
integer arguments, 1-11
list, 1-11 to 1-15
optional arguments, 1-10

GCCI$, 5-75
GCII$, 5-79
General Information Directive,
1-20
Get Command for Command
Interpreter, 5-75
Get Command Interpreter
Information, 5-79
Get LUN Information, 5-81
Get Mapping Context, 5-86
Get MCR Command Line, 5-84
Get Partition Parameters, 5-89
Get Region Parameters, 5-91
Get Sense Switches, 5-93
Get Task Parameters, 5-97
Get Time Parameters, 5-95
GETADR, 1-11
$$$GLB, 1-8
GLUN$, 5-81
GMCR$, 5-84
GMCX$, 5-86
GPRT$, 5-89
GREG$, 5-91
Group Global Event Flag
Control Block (GFB), 5-40,
5-60
Group-global event flag, 5-60
reading, 5-127
GSSW$S, 5-93
GTIM$, 5-95
GTSK$, 5-97

IHAR$S, ~-~.:S
Information buffer format,
5-79

Flag,
event, 2-2
Fork Level, 5-18

Index-3

INDEX

Inhibit AST Recognition, 5-53
Installed task,
removing, 1-20
Instruction space, 5-107
Interrupt Level, 5-18
Interrupt Service Routine
{ISR), 5-18
Interrupt Transfer Block, 5-18
Inter-task communication, 4-1
ISA Standard, 1-9
I-space, 3-1 to 3-2
accessing single word of,
5-110
mapping, 3-3 to 3-4

Logical address space, 3-2

Macro,
$C form, 1-6
$C form example, 1-8
DIR$, 1-5, 1-7
example calls, 1-8
$ form, 1-5
$ form example, 1-8
$S form, 1-6
$S form example, 1-8
Macro DIR$, 1-6
Macro name convention, 1-5
MAP$, 5-101
Map Address Window, 5-100
Map Supervisor D-Space, 5-107
Mapped system, 3-2
Mapping,
APRO, 3-20
I/O page, 3-20
privileged tasks, 3-20
Mapping context, 5-86
Mark Time, 5-103
MCR dispatching algorithm, 5-5
Memory management, 3-1 to 3-2,
3-4, 3-12
directives, 3-9 to 3-11
Memory resident common region,
preserving changes to, 5-34
Move To/From User/Supervisor
I/D-Space, 5-110
MRKT$, 5-103
MSDS$, 5-107
MVTS$, 5-110

ODT, 5-202
Offset,
symbolic, 1-7
Offspring Control Block {OCB),
5-31, 5-172
Offspring task,
status values, 4-3

Parent connection,
creating, 4-1
transferring, 4-1
Parent/offspring tasking, 4-1
Physical address space, 3-2
Physical memory, 3-5
Processor Status Word {PSW) ,
1-2
PSW, 1-2
PWRUP routine, 5-54

QIO$, 5-112
QIOW$, 5-116
Queue I/O Request, 5-112
Queue I/O Request And Wait,
5-116

Nonprivileged task,

directive restrictions,
1-20 to 1-21

Index-4

RCST$, 5-118
RCVD$, 5-120
RCVX$, 5-122
RDAF$, 5-125
RDB, 3-12 to 3-13
assigned setting, 3-20
generating, 3-13 to 3-14
generating in FORTRAN, 3-15
macros, 3-13 to 3-14
RDBBK$, 3-13
macro call, 3-14
macro expansion, 3-14
RDBDF$, 3-13
RDEF$, 5-126
RDXF$, 5-127
Read All Event Flags, 5-125
Read Event Flag, 5-126
Read Extended Event Flags,
5-127
Receive By Reference, 5-136
Receive Data, 5-120
Receive Data Or Exit, 5-122
Receive Data Or Stop, 5-118
Redirecting a spooled device,
5-83
Region, 3-5
attaching to, 3-6
definition block, 3-7,

INDEX

Region (Cont.)
3-12 to 3-13
dynamic, 3-6, 5-42
ID, 3-6
mapping windows, 3-8
protection, 3-9
shareable, 3-6
shared, 3-6
static common, 3-5
task, 3-5
Region Definition Block,
5-16 to 5-17, 5-42,
5-56 to 5-57
Region Definition Block (RDB),
3-12
Region ID,
determining, 5-16
region status word, 5-42, 5-56
Remove Affinity, 5-128
Request and Pass Offspring
Information, 5-129
Request Task, 5-133
Resume Task, 5-139
RMAF$, 5-128
RPOI$, 5-129
RQST$, 5-133
RREF$, 5-136
RSUM$, 5-139
RSX-llM-PLUS,
features, 1-21
RSXMAC.SML, 1-5
RUN$, 5-140
Run Task, 5-140
Rundown count, 5-31, 5-62

$S macro form, 1-6
SCAA$, 5-145
SCAL$S, 5-146
SCLI$, 5-148
SDAT$, 5-150
SDRC$, 5-152
SDRP$, 5-155
Send By Reference, 5-188
Send Data, 5-150
Send Data Request and Pass
Offspring Control Block,
5-155
Send Message, 5-162
Send Next Command, 5-165
Send, Request And Connect,
5-152
Service routine,
SST, 2-5
Set Affinity, 5-193
Set Command Line Interpreter,
5-148
Set Event Flag, 5-159

Index-5

Set System Time, 5-195
SETF$, 5-159
SFPA$, 5-160
Significant event, 2-1, 5-52
list of, 2-1, 5-222
SMSG$, 5-162
SNXC$, 5-165
Spawn, 5-172
Spawning, 4-1
Spawning a CLI, 4-5
Spawning a utility, 4-5
Spawning system tasks, 4-5
SPEA$, 5-167
Specify Command Arrival AST,
5-145
Specify Floating Point
Processor Exception AST,
5-160
Specify Parity Error AST,
5-167
Specify Power Recovery AST,
5-170
Specify Receive Data AST,
5-182
Specify Receive-By-Reference
AST, 5-191
Specify Requested Exit AST,
5-184
Specify SST Vector Table For
Debugging Aid, 5-202
Specify SST Vector Table For
Task, 5-204
SPND$S, 5-169
Spooled device,
redirecting, 5-83
SPRA$, 5-170
SPWN$, 5-1 72
SRDA$, 5-182
SREA$, 5-184
SREF$, 5-188
SREX$, 5-184
SRRA$, 5-191
SST I 2-5
definition, 2-4
service routine, 2-5
specifying vector table,
5-204
task's stack content, 2-6
trap vector table format,
2-5
STAF$, 5-193
Static common region, 5-16
Status,
emitting, 5-64
STIM$, 5-195
STLO$, 5-198
Stop, 5-200
Stop For Logical OR Of Event
Flags, 5-198

INDEX

Stop For Single Event Flag,
5-201
STOP statement, 5-70
Stop-bit synchronization, 2-7,
2-11

directives, 2-12
STOP$S, 5-200
STSE$, 5-201
Subroutine,
FORTRAN, 1-9
optional arguments, 1-10
usage, 1-9
Supervisor Call, 5-146
Supervisor mode, 3-1 to 3-2
Supervisor-mode D-space, 5-107
Supervisor-mode I-space, 5-36,
5-107
Supervisor-mode library,
5-107, 5-146
Suspend, 5-169
SVOB$, 5-202
SVTK$, 5-204
Symbolic offset, 1-7
Synchronous System Trap (SST),
2-4
System,
mapped, 3-2
System Macro Library, 1-5

Task state transition
(Cont.)
1-19
Task termination notification,
5-8
Time buffer format, 5-95
Time-synchronized initiation
requests, 5-51
Trap,
AST, 2-4
SST, 2-4
system, 2-4
Trap-dependent parameter, 2-8

Task,
extend, 5-73
installed, 1-20
Task builder, 3-3
Task Exit, 5-69
Task Level, 5-18
Task name,
in FORTRAN subroutine, 1-10
Task parameter buffer format,
5-97
Task state, 1-17
active, 1-18
active blocked, 1-18
active ready-to-run, 1-18
active stopped, 1-18
transition, 1-18
Task state transition,
active to dormant, 1-19
blocked to ready-to-run,
1-19
blocked to stopped, 1-19
dormant to active, 1-18
ready-to-run to blocked,
1-18
ready-to-run to stopped,
1-19
stopped to blocked, 1-20
stopped to reacy-to-run,

Index-6

ULGF$S, 5-206
UMAP$, 5-207
Unlock Group Global Event
Flags, 5-206
Unmap Address Window, 5-207
Unstop Task, 5-209
User-mode D-space, 5-36, 5-107
USTP$, 5-209

Variable Receive Data, 5-210
Variable Receive Data Or Exit,
5-214
Variable Receive Data Or Stop,
5-212
Variable Send Data, 5-216
Variable Send, Request and
Connect, 5-218
Virtual address space, 3-2
Virtual address window, 3-3
creating, 5-36
figure, 3-5
Virtual terminal, 5-62 to 5-63
creating, 5-45
VRCD$, 5-210
VRCS$, 5-212
VRCX$, 5-214
VSDA$, 5-216
VSRC$, 5-218

Wait For Logical OR Of Event
Flags, 5-223
Wait For Single Event Flag,
5-225
WDB, 3-15, 3-17, 3-19
assigned setting, 3-20
format, 3-15 to 3-16
generating, 3-17 to 3-18
generating in FORTRAN, 3-19

INDEX

WDBBK$, 3-18
macro call, 3-18
macro expansion, 3-18
WDBDF$, 3-18
Window,
definition block, 3-15
identification number, 3-4
virtual address, 3-3 to 3-4
Window block, 5-36
Window Definition Block,
5-36 to 5-37, 5-39,
5-58 to 5-59, 5-87, 5-101
Window definition block, 5-38,
5-189

Window Definition Block (WDB),
3-15
Window ID, 5-36
Window status word, 5-36,
5-101
W.NLEN, 5-36
W.NOFF, 5-36
WSIG$S, 5-221
WS.MAP, 5-36
WS. SIS, 5-36
WS.UDS, 5-36
WTLO$, 5-223
WTSE$, 5-225

Index-7

RSX-llM/M-PLUS
Executive
Reference Manual
Order No. AA-L675A-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.

Did you find errors in this manual? If so, specify the error and the page number.

Please indicate the type of user/reader that you most nearly represent.

D
D
D
D
D
D

Assembly language programmer
Higher-level language programmer
Occasional programmer (experienced)
User with little programming experience
Student programmer
Other (please specify)

Organization

Street
State _ _ _ _ _ _ Zip Code _ _ _ _ __
or Country

Do Not Tear- Fold Here and Tape

____,

11 I

No Postage
Necessary
if Mailed in the
United States

BUSINESS REPL V MAIL
FIRST CLASS PERMIT N0.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

BSSG PUBLICATIONS ZK1-3/J35
DIGITAL EQUIPMENT CORPORATION
110 SPIT BROOK ROAD
NASHUA, NEW HAMPSHIRE 03061

~
- -

Do Not Tear - Fold Here