Digital PDFs

DEC-11-OMERA-A-D

May 1974

116 pages

Original

3.1MB

Document:	RSX-11M Executive Reference Manual
Order Number:	DEC-11-OMERA-A-D
Revision:	0
Pages:	116
Original Filename:	http://bitsavers.org/pdf/dec/pdp11/rsx11m_s/RSX11M_V1/DEC-11-OMERA-A-D_V1_ExecRef.pdf

OCR Text

RSX-11M
Executive Reference Manual
Order No. DEC-II-OMERA-A-D

RSX-llM Version 1

Order additional copies as directed on the Software
Information page at the back of this document.

digital equipment corporation · maynard. massachusetts

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 manual.
The software described in this document is furnished to the purchaser under a license for use
on a single computer system and can be copied (with inclusion of DIGITAL's copyright notice)
only for use in such system, except as may otherwise be provided in writing by DIGITAL.
Digital Equipment Corporation assumes no responsibility for the use or reliability of its software
on equipment that is not supplied by DIGITAL.

The HOW TO OBTAIN SOFTWARE INFORMATION page, located at the back of this document explains the various services available to DIGITAL software users.
The postage prepaid READER'S COMMENTS form on the last page of this document requests
the user's critical evaluation to assist us in preparing future documentation.

The following are trademarks of Digital Equipment Corporation.
CDP
COMPUTER LAB
COMSYST
COMTEX
DDT
DEC
DECCOMM
DECTAPE
DIBOL

DIGITAL
DNC
EDGRIN
EDUSYSTEM
FLIP CHIP
FOCAL
GLC-8
IDAC
IDACS

INDAC
KAIO
LAB-8
LAB-8/e
LAB-K
OMNIBUS
OS/8
PDP
PHA

PS/8
QUICKPOINT
RAD-8
RSTS
RSX
RTM
RT-ll
SABR
TYPESET-IO
UNIBUS

PREFACE
MANUAL OBJECTIVES AND READER CLASS ASSUMPTION
The intent of this manual is to provide experienced MACRO-l1 or FORTRAN IV programmers the technical details necessary to use the services provided by the RSX-l1M Executive.
The manual is not self-contained. The MACRO-II Reference Manual (for the MACRO-II programmer), the FORTRAN IV Reference Manual (for the FORTRAN IV programmer), and
the Task Builder Reference Manual are prerequisite sources of information. Further the Introduction to RSX-l1M, the RSX-l1M System Generation Manual, the RSX-l1M 110 Operations
Reference Manual, the RSX-IIM Operators Guide, and the How To Write an 110 Driver
Manual are closely allied to the purposes of this manual. All the details in the manual may not
be relevant to the strictly FORTRAN IV programmer, but, without question, his exposure to
them cannot but add to his ability to obtain the most efficient results from his programming
efforts.
The reader is assumed to understand PDP-II Processors and Processor-related terminology.
The manual is tutorial in bias, but is not meant to train programmers. Experience on DEC or
other manufacturers realtime systems is assumed.

NOTE
The How To Write an 110 Driver Manual will be published as a follow-on document.

iii

CONTENTS

Page
MANUAL OBJECTIVES AND READER CLASS
ASSUMPTION .... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. iii

PREFACE

CHAPTER

1
1.1
1.2
1.2.1
1.2.2
1.2.2.1
1.3
1.4
1.4.1
1.4.2
1.5

FUNDAMENTAL CONCEPTS .................................. 1-1
INTRODUCTION ............................................. 1-1
DIRECTIVE IMPLEMENTATION ............................. 1-2
Directive Conventions (MACRO-II and FORTRAN IV) ........... 1-4
Specialized FORTRAN Subroutines .............................. 1-4
GETADR .................................................... 1-5
ERROR RETURNS ........................................... 1-5
USING THE DIRECTIVE MACROS ............................ 1-8
Symbolic Offsets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-10
Examples of Macro Calls ....................................... 1-10
TASK STATES .............. , ................................ 1-12

CHAPTER

2
2.1
2.1.1
2.1.2
2.1.3
2.1.4
2.1.5
2.1.6
2.2
2.2.1
2.2.2
2.2.3
2.2.4
2.2.4.1
2.2.5
2.2.6

DIRECTIVE DESCRIPTIONS .................................. 2-1
DIRECTIVE CATEGORIES .................................... 2-2
Task Execution Control. ........................................ 2-2
Task Status Control .... ~ ....................................... 2-2
Informational Directives ........................................ 2-2
Event-Associated Directives .................................... 2-2
Trap-Associated Directives .... , ................................. 2-3
I/O and Inter-task Communications Related Directives ............. 2-3
DIRECTIVE DESCRIPTIONS .................................. 2-4
Task Execution Control Directives ............................... 2-5
Task Status Control Directives ................................. 2- 15
Informational Directives ....................................... 2-17
Event-Associated Directives ................................... 2-23
Directives Which Result In The Setting Of An Event Flag .......... 2-24
Trap-Associated Directives '" ................................. 2-39
I/O Related Directives ......................................... 2-59

APPENDIX

DIRECTIVE SUMMARY-ALPHABETICAL ORDER ............. A-I

APPENDIX

STANDARD ERROR CODES .................................. B-1

FIGURES
Figure
Figure
Figure

1-1
1-2
1-3

TABLES
Table

1-1

Page
Directive Parameter Block (DPB) Pointer On The Stack .................... 1-2
Directive Parameter Block (DPB) On The Stack ........................... 1-3
Calling Directives From Macro Library .................................. 1-9
Page
General Error Codes .................................................. 1-6

CHAPTERl

FUNDAMENTAL CONCEPTS
1.1

INTRODUCTION

Executive services exist to permit users to access structures and facilities inherently available in
the hardware, but because of multiprogramming and realtime constraints, must be disbursed by
the Executive on a controlled or shared basis.
A typical example is 110. If many independent tasks seek access to 110 devices, then to prevent
chaos, and to provide access based on the importance of the request, an intermediary is required
between the independent requests of the tasks and the actual hardware device being accessed:
the RSX-llM Executive is this intermediary.
The objective of the Executive is to provide to the user as many of the facilities that are inherent in the hardware as possible, and, where desirable, augment these facilities; the Executive aims to provide these services without impacting the throughput capabilities of the raw
hardware. The system provides these facilities through instruction-like constructs called directives.
•
These Executive directives are analogous to similar hardware facilities (like 110 request directives) or desirable augmentations to the hardware (like SEND and RECEIVE directives for
communication between tasks). In any event, the directives are used just as the instruction set
is used. The cqmbination of the instruction set and the directives can be viewed as an extended
machine.
The applications programmer uses the directives to control the execution and interaction of
tasks. These directives are usually implemented via macros in the System Macro Library (SML).
The FORTRAN programmer invokes system directives through subroutine calls which are
listed with each Executive directive.
Directives are implemented via the EMT 377 instruction. Programs using EMT 0 through EMT
367 can be run via the non-RSX EMT system trap. Any EMT, other than EMT's 370-377,
which are reserved for system use, will trap to a task-contained service routine, which may
simulate another environment to whatever degree is desired; for example, the emulation of
another operating system interface. It should be noted that if the EMT numbers (370-376) are
issued by a user task, the resulting trap will be directed to the user task. User tasks should consider these EMT's as internal program errors, since system conventions reserve these EMT's.
Note that by using macros instead of coding the directives, the programmer need only re-assemble to re-adjust programs if changes are made in the directive specifications.

1-1

Fundamental Concepts

1.2 DIRECTIVE IMPLEMENTATION
A brief discussion of how directives are implemented will help the programmer better understand and use the macros which are associated with the directives.
The EMT 377 is issued with either the address of a Directive Parameter Block (DPB), or a DPB
itself, on the top of the issuing task's stack.
The first word of a DPB contains a Directive Identification Code (DIC), and a DPB size. The
DIC indicates which directive is to be performed; the size 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.
Figures 1-1 and 1-2 illustrate the alternatives for issuing directives and also show the relationship between the stack pointer and the DPB.

MOV
EMT

DPB

#ADDR,-(SP)
377

DPB
ITEMS
SP ...

SIZE

ADDRESS OF DPB

DIC

STACK
GROWTH

l
Figure 1-1
Directive Parameter Block (DPB) Pointer
On The Stack

1-2

INCREASING
MEMORY
ADDRESSES

Fundamental Concepts

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

MOV
BYTE
EMT

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

SP--.........

SIZE

DIC

STACK
GROWTH

INCREASING
MEMORY
ADDRESSES

~
Figure 1-2
Directive Parameter Block (DPB) On The Stack

When the stack contains a DPB address, the address is removed after the directive is processed.
When the stack contains a DPB, the entire DPB is removed after the directive is processed. In
both cases the removal occurs prior to the Executive returning control to the task. The Executive distinguishes an actual DPB word from a DPB pointer by determining if the first word on
the stack is even or odd. An even word specifies a DPB pointer, an odd word indicates the DPB
is on the stack.
With the exception of the EXIT and EXITIF and RECEIVE DATA or EXIT directive, control
is returned to the instruction following the EMT, with the carry condition code cleared or set
indicating the directive has been accepted (cleared) or rejected (set). Further, the Directive Status Word (DSW) which is always referred to symbolically as $DSW*, is set to indicate a more
specific cause for acceptance or rejection of the specific directive involved. The DSW is usually
+ 1 for exceptance and has a range of negative values when the directive has been rejected. The
detailed return values are listed with each directive.

"The Task Builder resolves the address of $DSW. Users addressing the DSW with a physical address are not guaranteed upward compatibility with RSX-IID
and may experience incompatibilities with future RSX-IIM releases.

1-3

Fundamental Concepts

1.2.1

Directive Conventions (MACRO-II and FORTRAN IV)

The following conventions and assumptions are standard for all directives.

For MACRO-II programs decimal radix is used in all cases except hardware addresses and device unit numbers. Octal is assumed in MACRO-II
code examples if the number is not followed by a decimal point.
For FORTRAN IV, type integer*2 is used in all cases unless specifically
noted otherwise.

For MACRO-II programs task and partition names may be up to six characters long and are always represented as two words in Radix-50 form.
For FORTRAN IV, task and partition names are specified by a variable of
type REAL (single precision) which contains the task or partition name
in radix-50 representation. Radix-50 representation may be.established at
compile time by use of the OAT A statement, or at runtime by means of
the IRAD50 subprogram or RAD50 Function.

Device names are two characters long and are represented by one word in
ASCII code.

Time unit indicators, used for initial and repeated requests, are" 1" for
clock ticks, "2" for seconds, "3" for minutes, and "4" for hours.

Optional parameters are enclosed in square brackets.

Trailing optional arguments that are n ullmay be omitted.

Certain parameters are stated as being ignored, yet required. This convention is needed to maintain RSX-Il M, RSX-ll 0 compatibility.

8. Consecutive commas denote omitted arguments.
9.

Legal range of Logical Unit Numbers (LUN's) is 1-255(10).

10. Event Flags are numbered 1-64(10).
Directives are listed according to category, in sections 2.2.1 through 2.2.6.

1.2.2 Specialized FORTRAN Subroutines
This section contains Fortran subroutine calls which may be used for simplifying interfacing
with the system's Executive directives.

1-4

Fundamental Concepts

1.2.2.1 GETADR
The primary intent of this call is to facilitate the construction of the parameter array for the QIO
Directive subroutine.
Calling Sequence:
CALL GETADR(ipm,[argl,],[arg2], ... ,[argn))
lpm

is an integer array of dimension n

argl ,... argn

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

1.3 ERROR RETURNS
Directive rejections are divided into two classes: those where a programmed recovery would be
common, and those where it would be unlikely. The error code, which is always negative, is returneo in the DSW which is at symbolic location $DSW. Rejections with expected programmed
recoveries (i.e., where a branch is taken to an error routine) have values between -1 and -19.
Error codes indicating errors for which programmed recoveries are not feasible are in the range
of -20 through -99.
All error codes in RSX-IIM are defined symbolically. The mnemonics used reflect the cause of
the error. In the text of the manual, the symbolics are used exclusively. The macro, DRERR$,
which is expanded in Appendix B, provides a correspondence between the symbolic error name
and its numeric value.
Table 1-1 summarizes general interpretations of error codes. Others are described in individual
directive descriptions.

1-5

Fundamental Concepts
Table 1-1
General Error Codes

Code
IE.UPN

Reason For Rejection
Insufficient Dynamic Memory
User tasks cannot request dynamic memory; however, several Executive requests require it for their execution. When it cannot be obtained, this error return results. The user can try again later by
suspending himself. (Note: W AITFOR SIGNIFICANT EVENT is
recommended, since most other suspend-type directives themselves
require dynamic memory.)

IE.INS

Task Name Not In The STD or Undefined Partition Name
Indicates the task has not been installed in the system, that a partition has not been defined at SYSGEN, or has not been specified in a
Set command.

IE.ULN

Unassigned LUN
The LUN (Logical Unit Number) in the request has not been assigned to a physical device. Recovery is possible by issuing a valid
ASSIG N LUN directive, then re-issuing the rejected request.

IE.ACT

Task Is Active/Not Active
An attempt is made to cause a task state-transition which is a task
state inconsistent with the existing task state. For example, an attempt is made to ABORT a task which is not active. Or a task has
attempted to request a task which is already active.

IE.lTS

Red undan t Request
Occurs when the request is such that it duplicates an existing task
state. For example, the task attempts to enable AST's but AST recognition is already enabled.

IE.CKP

Task is: Checkpointable/Not Checkpointable
This error occurs if the task is not checkpointable, and the task attempts to enable or disable checkpointability.

1-6

Fundamental Concepts
Table 1-1 (Cont.)
General Error Codes

IE.ITI

In valid Time Parameter
A time parameter consists of two words:
1.

A magnitude word, and

A units word.

The legal value of the magnitude is related to the value of the units
word, which is encoded as:
1 = Ticks. A tick causes a clock interrupt and the rate at
which interrupts occur depends on the type of clock installed on 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 (frequency is selectable at SYSGEN).
2 = Seconds
3
Minutes
4 = Hours
The magnitude is the number of units to be clocked, but the magnitude value cannot exceed 24 hours in the specified units.
Units = 1
Any positive value is valid (maximum
of 15 bits)
Units = 2
Any positive value is valid (maximum
of 15 bits)
Units = 3
1440(0) is maximum magnitude
Units = 4
24(10) is maximum magnitude

1-7

Fundamental Concepts

Table 1-1 (Cont.)
General Error Codes

IE.lLU

Invalid Logical Unit Number
A Logical Unit Number has been specified which is invalid for the
issuing task. For example, if the task has established only five
LUN's and has attempted to use a LUN greater than five, then this
error will occur.

IE.lEF

Invalid Event Flag Number
An event flag number has been illegally specified. In the case where
the EFN was required, it was less than 1 or greater than 64; in the
case when it was not required, it was less than 0 or greater than 64.
The only valid non-specification is O.

IE.ADP

Invalid Address
A buffer has been specified in the directive and the buffer lies outside the user's address space or has an improper alignment (not on a
word boundary). Also returned if part of the DPB is outside of the
task's address space.

IE.SDP

Invalid DIC number or DPB size
Either the DIC number, or the DPB size or both were incorrect.
DICs range from 1-127 and are always odd.

1.4 USING THE DIRECTIVE MACROS
This discussion applies to MACRO-II programmers. FORTRAN programmers execute
directives via subroutine calls and therefore need no( concern themselves with the details of
this section.
Directives are issued by including appropriate macro calls in the program. The macros which
generate RSX-IIM directives, are contained in the System Macro Library (SY:
[l,l]RSXMAC.SML). The user makes the macros available to his program by supplying the
.MCALL assembler directive, and using as arguments to .MCALL all the system macros used in
his program. Figure 1-3 is an example of calling and subsequently using macros in the System
Macro Library (SML).

1-8

Fundamental Concepts
Example:

; CALLING DIRECTIVES OUT OF THE SYSTEM MACRO LIBRARY
; AND INVOKING THEM .

.MCALL MRKT$S,WTSE$S
Additional .MCALL's or code

MRKT$S #1,#1,#2"ERR
WTSE$S #1

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

Figure 1-3
Calling Directives From Macro Library

Directive names consist of up to four letters followed by a dollar sign and, optionally, one letter.
The optional letter specifies which of three possible expansions of the macro is desired.
If the optional letter is omitted ($ form), the macro will produce only the directive's DPB. The
DPB is inserted at the point of macro invocation, but does not contain executable code. This
form allows for dynamic modification of the DPB, but is not re-entrant and is usually used in
conjunction with the DIR$ macro discussed below. It should be noted that DPB's should not
appear embedded in instruction sequences, since the Executive always returns to the instruction immediately following the EMT 377, with three exceptions: EXIT, EXITIF, and RECEIVE DATA or EXIT (when the IF condition holds). If the $ form of macro is used, it is assumed that the parameters required for DPB construction are valid expressions to be used in
assembler data storage directives (e.g., .BYTE, .WORD, .RAD50).
If the optional letter is "S" ($S form), the macro produces code to push a DPB on the stack,
followed by an EMT 377. This form can be used by a program with re-entrancy requirements. If
the $S form is used, the parameters must be valid source operands to be placed directly in MOV
instructions.
~fthe optional letter is "C" ($C form), the macro generates a DPB in a separate program section
called $DPB$$. The DPB is followed by a return to the original program section, an instruction
to push the DPB address on the stack, and an EMT 377. To ensure that the correct program
section is re-entered, the user must specify its name in the argument list immediately following
the required DPB parameters. If the argument is not specified, the blank p-section is assumed.
The $C form is used when the program has no re-entrancy requirements and plans to use the
DPB on a one-shot basis. This form has low overhead since the DPB is generated at Iilssembly
time, thereby eliminating the run time requirement to push the parameters on th'e stack. The
DPB, however cannot be accessed from another part of the program since its address is not

1-9

Fundamental Concepts
known. If the $C form of macro is used, it is assumed that the parameters requireo for DPB construction are valid expressions to be used in assembler data storage directives (e.g., .BYTE,
.WORD, .RAD50).
Note that only the $S form (also referred to as s-form) produces the DPB dynamically. The
other two forms produce the DPB at assembly time.
If the user has a predefined DPB and wishes to avoid the creation of another one, the DIR$
macro can be used. This macro generates the code to push the DPB address on the stack using
MOV SSS,-(SP), where the macro parameter (shown here as SSS), represents a valid assembler
source operand, followed by an EMT 377.
The $C, $S and DIR$ forms of macro calls will accept an optional final argument. If included, it
must be a valid assembler destination operand to call a user error routine. It generates the following code (assume DOD is the macro parameter in the following example):
.+n
;BRANCH ON DIRECTIVE ACCEPTANCE
BCC
JSR
PC,DDD
; ELSE, CALL ERROR SERVICE ROUTINE
This option is not permitted when the user specifiesthe generation of the DPB only.

1.4.1 Symbolic Offsets
Most system directive macros generate local symbolic offsets. The symbols are unique to each
directive, and are assigned the values of the byte offset from the start of the directive's DPB to
the DPB elements. Because the offsets are defined symbolically, the programmer who must refer to, or modify DPB elements can do so with no need of calculating the offsets. Symbolic offsets also do away with the necessity of rewriting programs to accommodate changes in DPB
specifications.
All $ and $C forms of macros that generate DPBs longer than one word generate local offsets.
If any of the $ or $C forms of the macros are in voked, and the symbol $$$G LB has been defined
elsewhere in the program (i.e., $$$GLB=O), the DPB is not expanded. Instead the macro produces the symbolic offsets as global symbols. The symbol $$$GLB has no effect on the expansion of$S macros.

1.4.2 Examples of Macro Calls
Example 1 - Generate Only A DPB in the Current Program section
MRKT$

1,5,2,MTRAP

Generated Code:
.BYTE
.WORD

2:;.,5 .
1

;MRKT$ MACRO DIC & DPB SIZE
;EVENT FLAG NUMBER

1-10

Fundamental Concepts
.WORD
.WORD
.WORD

5
2
MTRAP

; TIME INTER VAL MAG NITUDE
; TIME INTERVAL UNIT (SECONDS)
;AST ENTR Y POINT ADDRESS

Example 2 - Generate a DPB in a Separate Program section
MRKT$C

1,5,2,MTRAP,PROG 1,ERR

Generated Code:
.PSECT

$DPB$$

$$$=.
.BYTE
.WORD
.WORD
.WORD
.WORD

23.,5 .
1
5
2
MTRAP

;MRKT$ MACRO DIC & DPB SIZE
;EVENT FLAG NUMBER
;TIME INTERVAL MAGNITUDE
;TIME INTER V AL UNIT (SECONDS)
;AST ENTRY POINT ADDRESS

.PSECT

PROG1

[return to the original Program
section]

MOV
EMT
BCC
JSR

#$$$,-(SP)
377
.+6
PC,ERR

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

Example 3 - Generate a DPB on the Stack
MRKT$S #1,#5,#2,R2,ERR
Generated Code:
MOV
MOV
MOV
MOV
MOV
.BYTE
EMT
BCC
JSR

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

;PUSH AST ENTR Y POINT
; TIME INTER VAL UNIT (SECONDS)
; TIME INTER VAL MAG NITUDE
; EVENT FLAG NUMBER
;AND MARK TIME DIC & DPB SIZE
;ON THE STACK
;TRAP TO THE EXECUTIVE
;BRANCH ON DIRECTIVE ACCEPTANCE
; ELSE,CAL~ ERROR SER VICE ROUTINE

1-11

Fundamental Concepts

Example 4 - DPB Already Defined
DIR$

Rl,(R3)

;Rl CONTAINS DPB ADDRESS

Generated Code:
MOV
EMT
BCC
JSR

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

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

1.5 TASK STATES
Throughout this manual references will be made to directives and events that cause the state of
a task to change. The following discussion is intended to enhance the reader's understanding of
the various internal transitions his task is subject to in the multiprogramming environment
maintained by RSX-llM.
An RSX -11 M task has four basic states:
Dormant;
Active;
Ready-to-Run, and
Blocked.
The Task Builder creates a task image on disk. To the Executive, however, a task exists only
after it has been successfully installed and has an entry in the System Task Directory. (Task installation is a process whereby a task is made known to the system.) Task states are defined as
follows:
Dormant:
The task has an entry in the STD, but its activation has not been requested (a RQST$ or RUN$
macro has not been issued for it). Immediately following the Monitor Console Routine's
(MCR) processing of an INStall command, a task is known to the system, but is dormant.
Active:
A task is Active from the time it is requested, until it exits. A task passes from the dormant state
to the active state as a result of the run -time issuance of the RQST$, or R UN$ macros, or by an
operator issuing the MCR RUN command. "Active"implies that the task is eligible for scheduling, while dormant (or equivalently inactive) implies the task is not eligible for scheduling. An
Active task may be in one of two states: ready-to-run or blocked.

1-12

Fundamental Concepts

Ready-To-Run:
The task is capable of competing with other tasks for the CPU on the basis of priority. There is
no "Running" state in RSX-IIM. The highest priority ready-to-run task will obtain the CPU,
thus becoming the current task.
Blocked:
The task, due to unavailability of a needed resource, or requirements of synchronization is unable to compete for access to the CPU.

1-13

CHAPTER 2

DIRECTIVE DESCRIPTIONS
Each directive description consists of a narrative explanation of its function and use, the name
of the associated macro and its parameters, and possible return values of the Directive Status
Word (DSW), which, as previously noted, must be referenced symbolically as $DSW.
In general the $ form of the macro name is given, although all three options are available unless
otherwise specified. Certain macros have an s-form only, and are so specified in their descriptions. When Digital Equipment Corporation supplies only the s-form, the programmer is not
restricted from either hand-coding the other forms or using the $DIR macro to execute them.
The absence of the other macro forms occurs only when, the s-form will always require less
•
space and execute at least as fast as the other two forms.
In addition to the macros which correspond to the directives, the DIR$ macro will be of use to
the programmer, particularly in cases where the DPB has been defined independently of the
execution of the directive.
DIR$ generates an RSX-11M Executive trap with a pre-defined DPB.
Macro Call:
DIR$

adr,err

Three forms are possible, with the following interpretation:
DIR$

assumes the address or the DPB itself has already been
pushed onto the stack and generates an EMT 377.

DIR$ adr

will generate the code to push the parameter adr onto the
stack followed by an EMT 377.

DIR$ adr,err

will generate the code to push the parameter adr onto the
stack, followed by an EMT 377. The EMT 377 is followed by
a branch on carry-clear to the address of the branch +4 (or
+6 if necessary) and a JSR PC to the err address.

The argument adr is optional but, if present, must be a valid assembler source operand pointing
to a DPB that will be pushed on the stack. The argument err is optional. If defined, it must be a
valid assembler destination operand to permit a JUMP TO SUBROUTINE instruction to an error handler if the directive is rejected.
The directive descriptions have been organized into categories based on functional similarity.
Within these groups they are ordered alphabetically. Six general categories are defined, and are
summarized below under the section identifier of each.

2-1

Directive Descriptions

2.1

DIRECTIVE CATEGORIES

2.1.1

Task Execution Control

The task execution control directives deal principally with starting and stopping tasks. Each of
these requests result in a change of the task's state (unless the task is already in the state being
requested). The requests are:
Macro

Directive Name

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

ABORT TASK
CANCEL TIME BASED INITIATION REQUESTS
TASK EXIT (only s-form supplied)
REQUEST TASK
RESUME TASK
RUN TASK
SUSPEND (only s-form supplied)

2.1.2 Task Status Control
These two directives alter the checkpointable attribute of a task. They are:
DSCP$S
ENCP$S

DISABLE CHECKPOINTING (only s-form supplied)
ENABLE CHECKPOINTING (only s-form supplied)

2.1.3 Informational Directives
The four informational directives provide to the requesting task data retained by the system.
These requests provide the time of day, task parameters, the console switch settings, and partition parameters. The directives are:
GPRT$
GSSW$S
GTIM$
GTSK$

2.1.4

GET PAR TITION PARAMETERS
GET SENSE SWITCHES (only s-form supplied)
GET TIME PARAMETERS
GET TASK PARAMETERS

Event-Associated Directives

The event and event flag directives are the means provided in the system for inter- and intratask synchronization and signalling. These directives must be used carefully, since software

2-2

Directive Descriptions
faults resulting from erroneous signalling and synchronization are often obscure and difficult to
isolate. These are:
CLEF$
CMKT$S
DECL$S
EXIF$
MRKT$
RDAF$
SETF$
WSIG$S
WTLO$
WTSE$

CLEAR EVENT FLAG
CANCEL MARK-TIME REQUESTS (only s-form supplied)
DECLARE SIG NIFICANT EVENT (only s-form supplied)
EXITIF
MARK TIME
READ ALL EVENT FLAGS
SET EVENT FLAG
WAIT FOR SIGNIFICANT EVENT (only s-form supplied)
WAIT FOR LOGICAL 'OR' OF EVENT FLAGS
WAIT FOR SINGLE EVENT FLAG

2.1.5 Trap-Associated Directives
These directives provide the user the same facilities inherent in the PDP-II hardware trap system. They provide true interrupts to the executing tasks. These are:
ASTX$S
DSAR$S
ENAR$S
SFPA$
SPRA$
SVDB$
SVTK$

2.1.6

AST (ASYNCHRONOUS SYSTEM TRAP) SERVICE EXIT (only
s-form supplied)
DISABLE AST RECOG NITION (only s-form supplied)
ENABLE AST RECOGNITION (only s-form supplied)
SPECIFY FLOATING POINT EXCEPTION AS'!
SPECIFY POWER RECOVERY AST
SPECIFY SST VECTOR TABLE FOR DEBUGG ING AID
SPECIFY SST VECTOR TABLE FOR TASK

I/O and Inter-task Communications Related Directives

These directives allow tasks to access I/O devices at the driver interface level, communicate
with other tasks in the system, and retrieve command lines sent via MCR to the task. These are:
ALUN$
GLUN$
GMCR$
RCVD$
RCVX$
SDAT$
QIO$

ASSIGNLUN
GET LUN INFORMATION
GET MCR COMMAND LINE
RECEIVE DAT A
RECEIVE DATA OR EXIT
SEND DATA
QUEUE I/O

2-3

Directive Descriptions
2.2.

DIRECTIVE DESCRIPTIONS

Each directive description consists of six elements:
Name:
The directive's intent within the system is described.
Fortran Call:
The Fortran subroutine call is shown, and each parameter defined.
Macro Call:
The macro call is shown, each parameter is defined, and the defaults for optional parameters are in parentheses following the definition of the parameter. Since zero is supplied for most defaulted parameters, only non-zero default values are shown. The ignored parameters are present for RSX-II D compatibility.
Macro Expansion:
The $-form of the macro is expanded. Eleven macros have only the s-form of an expansion and for these the s-form is presented.
Local Symbol Definitions:
Macro expansions usually generate local symbol definitions whose assigned value equals
the byte offset from the start of the DPB to the respective DPB element. These symbols
are listed. The length in bytes of the datum 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 task name in the DPB and the task name datum has a
length of 4-bytes.
DSW return code:
All valid return codes are listed.
Notes:
A list of special considerations that may prove helpful in assisting the programmer in the
proper use of the directive.

2-4

Directive Descriptions

2.2.1 Task Execution Control Directives

ABORT TASK

ABRT$

This directive instructs the system to terminate the execution of the indicated task. ABRT$ is
intended for use as an emergency or fault exit. A termination notification printout occurs at the
terminal from which the task was requested or at the operator console (device CO:) if the task
was started internally from another task. A task maY' abort any task, including itself. Aborted
tasks are not removed from the system; hence, they may be requested.
Fortran Call:
CALL ABORT (tsk,[ids])
tsk = Task name
ids = Directive status
Macro Call:
ABRT$

tsk

tsk = Task name
Macro Expansion:
ABRT$
.BYTE
.RAD50

ALPHA
83.,3
IALPHAI

;ABRT$ MACRO DIC, OPB SIZE=3 WORDS
;TASK 'ALPHA'

Local Symbol Definitions:
A.BTTN - Task name (4)*
DSW Return Codes:
IS.SUC -- Successful completion
IE.lNS -- Task is not installed
IE.ACT -- Task is not active
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.

An aborted task is no longer active; it moves from the active state to the dormant
state.

* The number in parentheses is the length of the datum to which the symbolic offset definition points.

2-5

Directive Descriptions
CANCEL TIME BASED INITIATION REQUESTS

CSRQ$.

This directive instructs the system to cancel all time-synchronized initiation requests for a specified task regardless of the source of the request; these requests result from a RUN directive, or
any of the time-synchronized variations of the RUN MCR function.
Fortran Call:
CALL CAN ALL (tsk,[idsD
Task name
Directive status

tsk
ids
Macro Call:
CSRQ$

tsk

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:
IS.SUC -- Successful completion
IE.INS -- Task is not installed
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.

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

ALPHA"ERR

;CANCEL REQUESTS FOR 'ALPHA'

2-6

Directive Descriptions

TASK EXIT (only s-form supplied)

EXIT$S

This directive instructs the system to terminate the execution of the issuing task.
Fortran Call:
STOP
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=1 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 address space
IE.SDP -- DIC or DPB size is invalid
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 err routine address is given, since
the return will only occur with carry set.

EXIT will cause a significant event.

3. On Exit the Executive frees task resources; in particular;
1 - All attached devices are detached;
2 - The AST queue is flushed;
3 - The receiver queue is flushed;
4 - All open files are closed;
5 - 110 is run -down, and
6 - If the task is not fixed, its partition is freed.
4.

This directive requires a I-word DPB, thus the EXIT$S form of the macro is recommended since it will always require less space and executes with the same speed as
the DIR$ macro form.

2-7

Directive Descriptions
REQUEST

RQST$

This directive instructs the system to make a task active. The task is activated and will subsequently run contingent upon priority and memory availability. Request is the basic mechanism
used by running tasks for initiating other installed (dormant) tasks. REQUEST is a frequently
used subset of the RUN directive.
Fortran Call:
CALL REQUES (tsk,[opt],[ids])
tsk = Task name
opt = 4-word integer array
opt(1) = Partition name first half; ignored, but must be present
opt(2) = partition name second half; ignored, but must be present
opt(3) = priority; ignored, but must be present
opt(4) = user identification code
ids = Directive status
Macro Call:
RQST$

tsk,[prtl,[pril,[ugcl,[uoc]

tsk = Task name
prt = Partition name; ignored, but must be present
pri = Priority; ignored, but must be present
.ugc = VIC group code
uoc = VIC owner code
Macro Expansion:
RQST$
.BYTE
.RAD50
.WORD
.WORD
.BYTE

ALPHA",20, 10
11.,7
IALPHAI
0,0

10,20

;RQST$ MACRO DIC, DPB SIZE=7 WORDS
;TASK 'ALPHA'
; PARTITION IGNORED
; PRIORITY IG NORED
;VIC VNDER WHICH TO RVN TASK

Local Symbol Definitions:
R.QSTN - Task name (4)
R.QSPN - Partition name (4)
R.QSPR - Priority (2)
R.QSGC - VIC group (1)
R.QSPC - VIC owner (1)

2-8

Directive Descriptions

DSW Return Codes:
IS.SUC
IE.lNS
IE.ACT
IE.ADP
IE.SDP

Successful completion
Task is not installed
Task is already active
Part of the DPB is out of the issuing task's address space
DIC or DPB size is invalid

Notes:
1.

The requested task must be installed in the system.

A requested task whose partition is busy is queued to the list of tasks waiting for the
partition and will run, based on priority and resource availability, when the partition
becomes free. If the requested task requires a partition that is currently occupied,
checkpointing may occur. If the current occupant of the partition is checkpointable,
has checkpointing enabled, and is of lower priority than the requested task, then it
will be written to disk when its current outstanding 110 completes and the requested
task will then be read into the partition.

3. Successful completion means that the task has been made active not that the task is
actually running.
4.

A task may be requested under any UIC regardless of the UIC of the requesting task.
If no UIC is specified in the request, the default UIC from the requested task's
header is used. The priority is always that specified in the requested task's Task Control Block.

2-9

Directive Descriptions

RSUM$

RESUME

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

ALPII A
47.,3
/ ALPHA/

;RSUM$ MACRO DIC, DPB SIZE=3 WORDS
;TASK 'ALPHA'

Local Symbol Definitions:
R.sUTN

Task name (4)

DSW Return Codes:
IS.SUC
IE.INS
IE.ACT
IE.ITS
IE.ADP
IE.SDP

-- Successful com pletion
-- Task is not installed
-- Task is not active
-- Task is not suspended
-- Part of the DPB is out of the issuing task's address space
-- DIC or DPB size is invalid

2-10

Directive Descriptions

RUN

RUN$

This directive causes a task to be requested at a specified future time, and optionally repeated
periodically. The schedule time is specified in terms of delta time from issuance. If the udc, smg,
snt, rmg, and rnt parameters are omitted, RUN is the same as REQUEST except that the task
will be initiated 1 clock tick from issuance when using the RUN directive.
Fortran Call:
CALL RUN (tsk,[opt],[smg],[snt],[rmg],[rnt],[ids))
tsk = Task name
opt = 4-word integer array
opt( 1) = Partition name first half; ignored, but must be present.
opt(2) = Partition name second half; ignored, but must be present
opt(3) = Priority; ignored, but must be present
opt(4) = User identification code
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 provided.
CALL STAR T(tsk,smg,snt,[ids))
tsk
smg
snt
ids

Taskname
Schedule delta magnitude
Schedule delta unit
Directive status

Macro Call:
RUN$

tsk, [prt], [pri], [ugc], [uoc], [smg], [sn t], [rmg], [rn t]

tsk
prt
pri
ugc
uoc
smg
snt
rmg
rnt

Task name
Partition name; ignored, but must be present
Priority; ignored, but must be present
UIC group code
UIC owner code
Schedule delta magnitude
Schedule delta unit
Reschedule interval magnitude
Reschedule interval unit

2-11

Directive Descriptions

Macro Expansion:
RUN$
.BYTE

ALPHA",20, 10,20.,3, 10.,3
17.,11.
;RUN$ MACRO DIC, DPB SIZE=II.'WORDS

.RADSO
.WORD
.WORD
.BYTE
.WORD
.WORD
.WORD
.WORD

/ALPHA/
0,0

;TASK 'ALPHA'
; PARTITION IGNORED
; PRIORITY IGNORED
;UICTO RUN TASK UNDER
;SCHEDULE MAGNITUDE=20.
;SCH. DELTA TIME UNIT=MINUTE (=3)
; RESCH. INTER VAL MAG NITUDE= 1O.
;RESCH. INTERVAL UNIT=MINUTE (= 3)

10,20
20 .

3
10.

Local Symbol Definitions:
R.UNTN
R.UNPN
R.UNPR
R.UNGC
R.UNPC
R.UNSM
R.UNSU
R.UNRM
R.UNRU

Task name (4)
Partition name (4)
Priority (2)
UIC group (1)
UIC owner (1)
Schedule magnitude (2)
Schedule unit (2)
Reschedule magnitude (2)
Reschedule unit (2)

DSW Return Codes:
IS.SUC -- Successful completion
IE.UPN -- Insufficient dynamic memory
IE.I NS -- Task is not installed
IE.ITI -- Invalid time parameter
IE.ADP -- Part of the DPB is out of the issuing task's address space
IE.SDP -- DIC or DPB size is invalid
Notes:

The target task must be installed in the system.

A task requested to run in a partition that is busy is queued in the list of tasks waiting for the partition and will run, based on priority, and resource and availability,
when the partition becomes free. If the requested task requires a partition that is
currently occupied, checkpointing may occur. If the current occupant of the partition is checkpointable, has checkpointing enabled, and is of lower priority than
the requested task, then it will be written to disk when its current outstanding 110
completes. The requested task will then be read into the partition.

Successful completion means the task has been made active, not that the task is
actually running.

2-12

Directive Descriptions

RUN requires dynamic memory for the clock queue entry used to start the task
after the specified delta time.

If optional rescheduling is not desired, then the macro arguments rmg and rmt
must be omitted.

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 default UIC from the requested task's
header i~ used. The priority is always that specified in the requested task's Task
Con trol Block.

2-13

Directive Descriptions
SUSPEND (only s-form supplied)

SPND$S

This directive instructs the system to suspend the execution of the issuing task. A task can suspend only itself, not another task. The task can only be restarted by a RESUME directive, or
RESume MCR command.
Fortran Call:
CALL SUSPND
Macro Call:
SPN D$S [err]
err = Error routine address
Macro Expansion:
SPND$S
MOV
.BYTE

ERR
(PC)+,-(SP) ; PUSH DPB ONTO THE STACK
45.,l
;SPND$S MACRO DIC, DPB SIZE=1 WORD

EMT
BCC
JSR

.+6

377
PC,ERR

;TRAP TO THE EXECUTIVE
; BR A NCB IF DIRECTIVE SUCCESSFUL
;OTHERWISE, CALL ROUTINE 'ERR'

Local Symbol Definitions:
None
DSW Return Codes:
IS.SUC
IE.ADP
IE.SDP

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

Notes:
1.

A suspended task retains control of the system resources allocated to it. No attempt is made to free the resources. A task which has exited will result in the executive checking if its resources can be freed.

A suspended task is eligible for checkpointing unless fixed or not checkpointable.

This directive requires a I-word DPB, thus the SPND$S form of the macro is recommended since it will always require less space and executes with the same
speed as the DIR$ macro form.

2-14

Directive Descriptions

2.2.2 Task Status Control Directives

DISABLE CHECKPOINTING (only s-form supplied)

DSCP$S

This directive instructs the system to disable the checkpointability of a task that has been installed as a checkpointable task. This directive can only be issued by the task to be affected. A
task cannot disable the checkpointability of another task.
Fortran Call:
CALL DISCKP
Macro Call:
DSCP$S [err]
err = Error routine address
Macro Expansion:
DSCP$S
MOV
.BYTE
EMT
BCC
JSR

ERR
(PC)+,-(SP) ;PUSH DPB ONTO THE STACK
95.,1
; DSCP$S MACRO DIC, DPB SIZE=l WORD
377
;TRAP TO THE EXECUTIVE
.+6
;BRANCH IF DIRECTIVE SUCCESSFUL
PC,ERR
;OTHERWISE, CALL ROUTINE 'ERR'

Local Symbol Definitions:
None
OSW Return Codes:
IS.SUC -- Successful completion
IE.lTS -- Task checkpointing IS already d~sabled
IE.CKP -- Issuing task is not checkpoin table
IE.AOP -- Part of the OPB is out of the issuing task's
address space
IE.SOP -- OIC or OPB size is invalid
Notes'

When a checkpointable task's execution is started, checkpointing is not disabled,
i.e., the task can be checkpointed.

This directive requires a I-word OPB, thus the DSCP$S form of the macro is recommended since it will always require less space and executes with the same
speed as the OIR$ macro form.

2-15

Directive Descriptions

ENABLE CHECKPOINTING (only s-form supplied)

ENCP$S

This directive instructs the system to make the issuing task checkpointable after its checkpointability has been disabled, i.e., to nullify a DSCP$S directive.
Fortran Call:
CALL ENACKP
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=1 WORD
; TRAP TO THE EXECUTIVE
;BRANCH IF DIRECTIVE SUCCESSFUL
;OTHERWISE, CALL ROUTINE 'ERR'

Local Symbol Definitions:
None
DSW Return Codes:
IS.SUC -- Successful completion
JE.ITS -- Checkpointing is not disabled
lE.ADP -- Part of the DPB is out of the issuing task's address space
IE.SDP -- DIC or DPB size is invalid
Notes:
1.

This directive requires a I-word DPB, thus the ENCP$S form of the macro is recommended since it will always require less space and executes with the same
speed as the DIR$ macro form.

2-16

Directive Descriptions

2.2.3

Informational Directives

GPRT$

GET PARTITION PARAMETERS

This directive instructs the system to fill an indicated 3-word buffer with partition parameters.
If a partition is not specified, the partition of the issuing task is assumed.
Fortran Call:
CALL GETPAR ([prt], buf ,[[ids])
prt = Partition name
buf = 3-word integer array to receive partition parameters
ids = Directive status
Macro Call:
GPRT$

[prt],buf

prt =
buf =

Partition name
Address of a 3-word buffer

The buffer has the following tormat:
WD.

WD.
WD.

Partition Base Address expressed as a multiple of 32 words (partitions are
always aligned on 32-word boundaries. Thus a partition starting at 1000(8)
will have 10(8) returned in this word.
Partition size expressed as a multiple of 32-words.
Partition flags word. This word is always returned equal to 1 to indicate a
user-controlled partition. This is done for RSX-11D compatibility.

Macro Expansion:
GPRT$ ALPHA,DATBUF
.BYTE
65.,4
.RAD50 / ALPHA/
.WORD 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)

2-17

Directive Descriptions
The following offsets are assigned relative to the start of the partition parameters buffer:
G.PRPB - Partition Base Address expressed as a multiple of 32·,words (2)
G.PRPS - Partition Siz.e expressed as a multiple of 32-words (2)
G.PRFW - Partition flags word expressed as a multiple of 32-words (2)
DSW Return Codes:
Successful completion is indicated by carry clear and the starting address of the partition is returned in the DSW. In unmapped systems, the returned address is physical, in mapped systems
it is virtual. Unsuccessful completion is indicated by carry set, and one of the following codes in
the DSW:

I E.I NS
IE.ADP
IE.SDP

Specified partition not in system
Part of the DPB or buffer is out of the issuing tasks' address space
DIe or DPB size is invalid

2-18

Directive Descriptions

GET TASK PARAMETERS

GTSK$

This directive instructs the system to fill an indicated 16-word buffer with parameters relating
to the issuing task.
Fortran Call:
CALL G ETTSK (buf,[idsD
buf = 16-word integer array to receive the task parameters
ids = Directive status
Macro Call:
buf

GTSK$
buf

Address of a 16-word buffer

The buffer has the following format:
WD. 00 -- Issuing task's name (first half),
WD. 01 -- Issuing task's name (second half),
WD. 02 -- Partition name (first half),
WD. 03 -- Partition name (second half),
WD. 04 -- Undefined in RSX-11M. This word exists
for RSX-11 D compatibility.
WD. 05 -- Undefined in RSX-IIM. This word exists
for RSX-ll D compatibility.
WD. 06 -- Run priority
WD. 07 -- User identification code of issuing task
WD. 10 -- Number ofiogical 110 units (LUN's)
WD. 11 -- Undefined in RSX-11M. This word exists for
RSX-IID compatibility.
WD. 12 -- Undefined in RSX-11M. This word exists for
RSX-IID compatibility.
WD. 13 -- (Address of task SST vector tables)*
WD. 14 -- (Size of task SST vector table (in words)*
WD. 15 -- (Reserved)
WD. 16 -- (Reserved)
WD. 17 -- (Reserved)
Macro Expansion:
GTSK$
.BYTE
.WORD

DATBUF
63.,2
DATBUF

;GTSK$ DIC, DPB=2-WORDS
; ADDRESS OF 16-WORD BUFFER

"These words will contain valid data if word 14 is non zero. If word 14 is zero, the contents of word 15 is meaningless.

2-19

nirective Descriptions

Local Symbol Definitions:
G.TSTN
G.TSPN
G.TSPR
G.TSGC
G.TSPC
G.TSNL
G.TSV A
G.TSVL

= Task name (4)
= Partition name (4)
= Priority (2)
= UIC Group code (2)
= UIC Programmer code (0
= Number of logical units (2)
= Task's SST vector address (2)
= Task's SST vector length in words (2)

DSW Return Codes:
IS.SUC ..: Successful completion
IE.ADP -- Part of the DPB or buffer is out of the issuing task's address space
IE.SDP -- DIC or DPB is invalid.

2-20

Directive Descriptions
GET SENSE SWITCHES (only s-form supplied)

GSSW$S

This 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

Macro Call:
GSSW$S
err

[err]

Error routine address

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

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

.+6
PC,ERR

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

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

Part of the DPB is out of the issuing task's
address space
DIC or DPB size is in valid

Notes:
1.

This directive requires a I-word DPB, thus the GSSW$S form of the macro is recommended since it will always require less space and executes with the same speed
as the DIR$ macro form.

2-21

Directive Descriptions

GET TIME PARAMETERS

GTIM$

This 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:
FORTRAN IV provides several subroutines for obtaining the time in a number of formats. See the RSX-llM FORTRAN IV Reference Manual DEC manual number DECll-LFLRA-A-D.
Macro Call:
GTIM$

buf

buf =

Address of 8-word buffer

The buffer has following format:
WD. 0 -- Year (since 1900)
WD. 1 -- Month of year 0-12)
WD. 2 -- Day of month (1-31)
WD. 3 -- Hour of day (0-23)
wo. 4 -- Minute of hour (0-59)
Wo. 5 -- Second of minute (0-59)
WD. 6 -- Tick of second (depends on the frequency of the clock)
WD. 7 -- Ticks per second (depends on the frequency of the clock)
Macro Expansion:
GTIM$
.BYTE
.WORD

DATBUF
61.,2
DATBUF

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

Local Symbol Definitions:
G.TIBA

- buffer address (2)

The following offsets are assigned relative to the start of the time parameters buffer:
G.TIYR G.TIMO G.TIDA G.TIHR G.TIMI
G.TISC
G.TICT
G.TICP

Year (2)
Month (2)
Day (2)
Hour (2)
Minute (2)
Second (2)
Clock Tick of Second (2)
Clock Ticks per Second (2)

2-22

Directive Descriptions
DSW Return Codes:
IS.SUC -- Successful completion
IE.ADP -- Part of the DPB or buffer is out of the issuing
task's address space
IE.SDP -- DIC or DPB size is invalid

2.2.4

Event-Associated Directives

Significant events and system traps are the means by which communication is effected between
various parts of the system. Significant Events and traps serve distinctly different functions
within the system; three points will help to clarify their uses:
1.

A significant event is a change in system status; it causes the RSX-II M Executive to
re-evaluate the eligibility for execution of all tasks. Significant events are also the major means by which one task communicates and synchronizes its execution with other
tasks and the system.

System traps are exclusive to a single task; they are useful for intra-task communication and control. System traps are the task level representation of the PDP-II hardware trapping mechanism.

The occurrence of an event may change the eligibility of a task to run, but that is all. A
trap, however, is a real interrupt; the sequence of instructions being executed by the
task will be interrupted and control will be transferred to another instruction sequence
in the program. This may be transparent to the user in some cases, but it occurs, nonetheless, and is a difference between events and traps.

Significant events provide a mechanism for achieving dynamic control of task execution. Tasks
are able to declare and recognize significant events through the event-associated directives discussed below. The declaration and occurrence of significant events provide dynamic control
over the execution of tasks. Waiting for an event, such as the completion of an 110 request, can
suspend a high priority task until that event occurs. Meanwhile, lower priority tasks are allowed
to run.
Event flags are the means by which RSX-IIM and tasks distinguish one event from another.
Associated with each task are 64 event flags. The first 32 flags 0-32) are unique to each task,
and are set or reset only as a result of that task's operation. The second 32 flags (33-64) are common to all tasks, and may be set or reset as a result of any task's operation. The two sets of event
flags are termed local 0-32) and common (33-64) respectively. Each event flag has a corresponding Event Flag Number (EFN) which uniquely identifies the flag.
Event flags are usually set when significant events occur, and tasks may read and/or clear them
by means of system directives. Also, task execution may be suspended until a particular event
flag, or one of a logical combination of event flags, is set.

2-23

Directive Descriptions

Some system processes running on behalf of the user need event flags. The last eight local (2532) and common (57-64) event flags are reserved, by convention, for use by RSX-llM System
Software.
All significant events occur as the result of a task having issued a system directive (the one exception is power failure). Some directives will have the event explicitly noted, while in others it
is implicit.
Setting and resetting event flags must be carefully planned and carefully executed; this is particularly true of the global event flags. Erroneous or multiple setting/resetting of event flags can
result in obscure, difficult to locate software faults. A typical application program can be written
without explicitly accessing or modifying event flags, since many of the directives implicitly
modify an event flag. The implicit setting of event flags provide a discipline which substantially
reduces the opportunity for multiple setting/resetting of event flags.

2.2.4.1

Directives Which Result In The Setting Of An Event Flag

Several directives automatically cause an event flag to be set, and the specification of an EFN is
required in their macro call. The programmer must provide an EFN, usually out the 24 local to
his task, if he expects the directive to set an EFN. The selection should be unique to a specific
directive, or at least never result in the possibility of multiple setting or resetting.
The following directives optionally cause the alteration of an event flag:

The SEND DATA directive causes a significant event at directive issuance; if an
event flag is specified, it will be set at the time the directive is issued.

The MARK TIME directive optionally clears an event flag at issuance; after the specified time interval has elapsed, a significant event is declared, and if an event flag has
been specified, it will be set.

I/O operations (initiated by the QUEUE I/O directive) optionally clear an event flag at
issuance; at I/O completion a significant event is declared and if an event flag was
specified, it will be set.

Examples 1 and 2 below show the usage of the common (33-64) event flags for task synchronization. Examples 3 and 4 illustrate the use of local (I -32) flags.

Example 1
Task B specifies a common event flag (for example, event flag number 35) in a W AITFOR directive, and task A specifies the same event flag in a SET EVENT FLAG Directive at the time it
is appropriate for Task B to proceed.

2-24

Directive Descriptions
Example 2
Task A specifies task B and a common event flag in a SEND directive. Task B has specified the
same common event flag in a W AITFOR directive and issues a RECEIVE directive when activated because its W AITFOR has been satisfied. The effect is to synchronize the transmission of
data between TASK A and TASK B.
Note that task A and task B have intimate knowledge of each other's requirements for synchronization and communication. The selection of an event flag is a mutual and unique choice
for the two tasks.

Example 3
If a task-local event flag is specified in QUEUE I/O and associated W AITFOR directives, the
flag will be cleared when the I/O request is queued. When the task executes a W AITFOR predicated on the same event flag, and the requested action has not yet completed, execution of the
task will be suspended.
The specified event flag is set when the I/O request is completed, and the task's execution will
be resumed at the instruction following the W AITFOR. Note that task execution continues after the I/O request is queued. The EFN is used to ensure that the task does not attempt to manipulate the incoming data until the transfer has actually completed.

Example 4
If a task-local event flag is specified in a MARK TIME and associated W AITFOR directive, the
flag will be cleared at MARK TIME issuance and set after the indicated time has' elapsed. When
the task executes a W AITFOR predicated on the same event flag and the time interval has not
yet elapsed, execution of the task will be suspended.
In examples 3 and 4, the choice of one of the first 32 (unique to task) local event flags is the
normal choice used to avoid possible interference by other tasks.
In examples 0-4) computation and/or event flag testing is not precluded prior to, or instead of,
the W AITFOR directive, i.e., specifying an event flag does not imply that a W AITFOR directive must be used. Event flag testing can be performed at any time. The purpose of a W AITFOR
directive is to stop execution until an indicated significant event occurs. Hence it is not necessary to issue a W AITFOR directive immediately following the issuance of a QUEUE I/O or a
MARK TIME directive.

2-25

Directive Descriptions
CLEAR EVENT FLAG

CLEF$

This directive instructs the system to clear an indicated event flag and report the flag's polarity
before clearing.
Fortran Call:
CALL CLFEF (efn,[idsD
efn = Integer containing an 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)
OSW Return Codes:

IS.CLR
IS.SET
IE.IEF
IE.AOP
IE.SOP

------

Flag was already clear
Flag was set
Invalid event flag number (EFN.GT.64 or EFN.LT.l)
Part of the OPB is out of the issuing task's addrESS space
OIC or OPB size is invalid

2-26

Directive Descriptions

CANCEL MARK TIME REQUESTS (only s-fonn supplied)

CMKT$S

This directive instructs the system to cancel all MARK TIME requests that have been made by
the issuing task.
Fortran Call:
CALL CANMT (,[ids])
ids

Directive status

Macro Call:
CMKT$S

["err]

err = Error routine address
Macro Expansion:
CMKT$S
MOV
.BYTE
EMT
BCC
JSR

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

.+6
PC,ERR

;NOTE: THERE ARE TWO IGNORED ARGUMENTS
;PUSH DPB ONTO THE STACK
;CMKT$S MACRO DIC, DPB SIZE= 1 WORD
;TRAP TO THE EXECUTIVE
; BRANCH IF DIRECTIVE SUCCESSFUL
;OTHERWISE, CALL ROUTINE 'ERR'

Local Symbol Definitions:
None
DSW Return Codes:
IS.SUC
IE.ADP
IE.SDP

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

Notes:
1.

This directive requires a 1-word DPB, thus the CMKT$S form of the macro is recommended since it will always require less space and executes with the same
speed as the DIR$ macro form.

2-27

Directive Descriptions

DECLARE SIGNIFICANT EVENT (only s-form supplied)

DECL$S

This directive instructs the system to declare a significant event.
Fortran Calf:
CALL DECLAR C[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=1 WORD
; TRAP TO THE EXECUTIVE
;BRANCH IF DIRECTIVE SUCCESSFUL
;OTHER WISE, CALL ROUTINE 'ERR'

Local Symbol Definitions:
None
DSW Return Codes:
IS.SUC -- Successful completion
IE.ADP -- Part of the DPB is out of the issuing task's address space
IE.SDP -- DIC or DPB size is invalid
Notes:

Declaration of a significant event causes the Executive to scan the System Task
Directory frotn the beginning, searching for the highest priority task that is ready
to run. This directive should be used with caution since excessive scanning overhead may result if used indiscriminately.

This directive requires a I-word DPB, thus the DECL$S form of the macro is recommended since it will always require less space and executes with the same
speed as the DIR$ macro form.

2-28

Directive Descriptions

EXITIF

EXIF$

This directive instructs the system to terminate the execution of the issuing task if, and only if,
an indicated event flag is NOT set. Control is returned to the issuing task if the specified event
flag is set.
Fortran Call:
CALL EXITIF (efn,[idsD
efn = Event flag number
ids = Directive status
Macro Call:
EXIF$
efn

efn
=

Event flag number

Macro Expansion:
EXIF$ 52.
.BYTE 53.,2
.WORD 52.

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

Local Symbol Definitions:
E.XFEF - Event flag number (2)
OSW Return Codes:
IS.sET
IE.IEF
IE.AOP
IE.SOP

Indicated EFN set, task not exited
Invalid event flag number (EFN.GT.64 or EFN.L T.1)
Part of the OPB is out of the issuing task's address space
OIC or OPB size is invalid

Notes:
1.

The EXITIF directive is useful in avoiding a possible race condition that may occur between two tasks communicating via the SEND and RECEIVE directives.
The race condition occurs when one task executes a RECEIVE directive and finds
its receive queue empty. But before the task can EXIT, the other task sends it a
message. Since the first task has already decided to exit, the message is lost since
the receiving queue is flushed during task 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 EXITIF specifying the same common event flag. The
EXITIF directive will return control to the issuing task signalling that something
has been sent.

2-29

Directive Descriptions

If the exit is taken, the Executive frees task resources. In particular
1 - All attached devices are detached;
2 - The AST queue is flushed;
3 - The receive queue is flushed;
4 - All open files are closed;
5 - 110 is run -down; and
6 - If the task is not fixed, its partition is freed.

If the exit is taken, a significant event is declared.

2-30

Directive Descriptions
MARK TIME

MRKT$

This directive instructs the system to declare a significant event after an indicated time interval.
The interval begins at issuance of the directive. If an event flag is specified, it is cleared at issuance and set at the time of the significant event. If an AST entry point address is specified, an
Asynchronous System Trap (see section 2.2.5 below) will occur at the time of the significant
event. At the AST, the task's PS, PC, directive status, W AITFOR mask words, and the event
flag number specified in the directive will be pushed onto the issuing task's stack. If neither an
event flag number~ nor an AST service entry point is specified, the significant event will still
occur after the indicated time in terval.
Fortran Calls:
CALL MARK (efn,tmg,tnt,[ids])
efn = Event flag number
tmg = Integer time interval magnitude
tnt = Integer time interval UGit
ids = Directive status
The ISA standard call for delaying a task for a specified time interval is also provided:
CALL WAIT (tmg,tnt,ids)
tmg = Integer time interval magnitude
tnt = Integer time interval unit
ids = Directive status
Macro Call:
MRKT$

[efn],tmg,tnt,[ast]

efn = Event flag number
tmg = Time interval magnitude
tnt = Time interval unit
ast = AST entry point address
Macro Expansion:
MRKT$
.BYTE
.WORD
.WORD
.WORD
.WORD

52.,30.,2,MRKAST
23.,5
52 .
30.
2
MRKAST

;MRKT$ MACRO DIC, DPB SIZE=5 WORDS
;EVENT FLAG NUMBER 52 .
;TIME MAGNITUDE=30 .
;TIME UNIT=SECONDS
;ADDRESS OF MARK TIME AST ROUTINE

2-31

Directive Descriptions

Local Symbol Definitions:
M.KTEF - Event flag (2)
M.KTMG - Time magnitude (2)
M.KTUN - Time unit (2)
M.KT AE - AST entry point address (2)
DSW Return Codes:
IS.SUC
ILUPN
IE.ITI
ILIEF
IE.AOP
ILSOP

Successful COI11 pletion
Insurticient dynamic memory
I n val id ti me parameter
Invalid event flag number (EfN.GT.64 or EFN.L T.O)
Part of the OPB is out of the issuing task's address space
OIC or OPB size is in valid

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+16 Event flag mask word for flags 1-16*
SP+ 14 Event flag mask word for flags 17-32
SP+ 12 Event flag mask word for flags 33-48
SP+ 10 Even t flag mask word for flags 49-64
SP+06 PS of task prior to AST
SP+04 PC of task prior to AST
SP+02 DSW of task prior to AST
SP+OO event flag number, or zero ifnone was specified
in the MARK TIME directive
The event flag number must be removed from the task's stack before an exit
AST directive (see section 2.2.5 below) is executed.

If the directive is rejected, the specified event flag is not guaranteed to be cleared
or set. Thus, if the task indiscriminately executes a W AITFOR directive and the
MARK TIME directive is rejected, then the task may wait forever. Care should
always be taken to insure that the directive was successfully completed.

* These event flag mask words preserve the waitfor conditions of a task prior to AST entry. A task can, after an AST,
return to a waitfor state. Since these flags and the other stack data are in the user task, they can be modified. Such
modi fication is strongly discouraged since if done erroneously or without sufficient comprehension of the task-wide
impact of the change, a given task may fault on extremely obscure conditions.

2-32

Directive Descriptions
RDAF$

READ ALL EVENT FLAGS

This directive instructs the system to read all 64 event flags for the issuing task and record
their polarity in a 64-bit (4-word) buffer.
Fortran Call:
Only a single event flag may be read by a FORTRAN IV task. The call is:
CALL READEF (efn,[ids])
efn = Event flag number
ids = Directive status
Macro Call:
RDAF$

buf

The buffer has the following format:
WD. 00 Task Local Flags 1-16
WD. 01 Task Local Flags 1-32
WD. 02 Task Common Flags 33-48
WD. 03 Task Common Flags 49-64
Macro Expansion:
RDAF$
.BYTE
.WORD

FLGBUF
39.,2
FLGBUF

;RDAF$ MACRO DIC, DPB SIZE=2 WORDS
; ADDRESS OF 4-WORD BUFFER

Local Symbol Definitions:
R.DABA - Buffer address (4)
DSW Return Codes:
IS.SUC -- Successful Completion
IE.ADP -- Part of the DPB or buffer is out of the issuing
task's address space
IE.SDP -- DIC or DPB size is invalid

2-33

Directive Descriptions
SETF$

SET EVENT FLAG

This directive instructs the system to set an indicated event flag and report the flag's polarity
before setting.
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 DIe, DPB SIZE=2 WORDS
;EVENT FLAG NUMBER 52 .

Local Symbol Definitions:
S.ETEF - Event flag number (2)
DSW Return Codes:
IS.CLR -- Flag was cleared
IS.SET -- Flag was already set
IE.IEF -- Invalid event flag number (EFN.GT.64 or EFN.LT.l)
IE.ADP -- Part of the DPB is out of the issuing task's address space
IE.SDP -- DIC or DPB size is invalid

Notes:
l.

SET EVENT FLAG does not declare a significant event, it merely sets the specified flag.

2-34

Directive Descriptions

WAIT FOR SIGNIFICANT EVENT (only s-form supplied)

WSIG$S

This directive is used to suspend the execution of the issuing task until the next significant
event occurs. It is an especially effective way to suspend a task which cannot continue because
of a lack of dynamic memory, since significant events occurring throughout the system often
result in the release of dynamic memory.
Fortran Call:
CALL WFSNE
Macro Call:
WSIG$S

[err]

err = Error routine address
Macro Expansion:
WSIG$S
MOV
.BYTE
EMT
BCC
JSR

ERR
(PC)+,-(SP)
49.,1

377
.+6
PC,ERR

; PUSH DPB ONTO THE STACK
; WSIG$S MACRO DIC, DPB SIZE= 1 WORD
;TRAP TO THE EXECUTIVE
; BRAN CH IF DIRECTIVE SUCCESSFUL
;OTHER WISE, CALL ROUTINE 'ERR'

Local Symbol Definitions:
None
DSW Return Codes:
IS.SUC -- Successful completion
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.

If a directive is rejected for lack of dynamic memory, this directive is the only
technique available for suspending task execution until dynamic memory may
again be available.

The wait state induced by this directive is satisified by the first significant event
which occurs following directive issuance. The significant event which occurs
mayor may not be related to the issuing task.

This directive requires a I-word DPB, thus the WSIG$S form of the macro is recommended since it will always require less space and executes with the same
speed as the DIR$ macro form.

2-35

Directive Descriptions
WAIT FOR LOGICAL 'OR' OF EVENT FLAGS

WTLO$

This directive instructs the system to suspend the execution of the issuing task until any indicated event flag within one of the following groups of event flags is set:
GR 0 -- Flags 1-16
GR 1 -- Flags 17-32
GR 2 -- Flags 33-48
G R 3 -- Flags 49-64
If the indicated condition is met at issuance, task execution is not suspended.
Fortran Call:
CALL WFLOR (efn l,efn2, ... efnn)
efn

List of event flag numbers is taken as the set of flags
to be specified in the directive.

Macro Call:
WTLO$

grp,msk

grp
msk

Desired group of event flags
A 16 bit octal 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:
IS.SUC
IE.IEF
IE.ADP
IE.SOP

-- Successful completion
-- No event flag specified in the mask word or flag
set indicator other than 0,1 ,2, or 3
-- Part of the DPB is out of the issuing task's
address space
-- OIC or OPB size is invalid

2-36

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 2 were specified, then bit 0 in the
mask word would correspond to event flag 17, bit 1 to event flag 18, and so forth.

Event flags are not arbitrarily cleared by the Executive when Waitfor conditions
are met. Some directives (QIO, for example) implicitly clear a flag; otherwise
they must be explicitly cleared by a Clear Event Flag directive.

The grp operand must always be absolute regardless of the macro form used. In all
other macro calls absolute values for s-form macros have the format:
#n

For WTLO$S this would be
n

The argument list specified in the FORTRAN call must contain only efn's that lie
with one event flag group. If efn's are specified that lie in more than one group or
an invalid efn is specified then a fatal FORTRAN error is generated.

2-37

Directive Descriptions
WTSE$

WAIT FOR SINGLE EVENT FLAG

This directive instructs the system to suspend the execution of the issuing task until the indicated event flag is set. If the flag is set at issuance, task execution is not suspended.
Fortran Call:
CALL W AITFR (efn,[ids])
efn
ids

Event flag number
Directive status

Macro Call:
WTSE$
efn

efn
=

Event flag number

Macro Expansion:
WTSE$
.BYTE
.WORD

52.
41.,2
52.

; WTSE$ MACRO OIC, DPB SIZE=2 WORDS
;EVENT FLAG NUMBER 52 .

Local Symbol Definitions:
W.TSEF - Event flag number (2)
DSW Return Codes:
IS.SUC -- Successful completion
IE.lEF -- Invalid event flag number (EFN.GT.64 or EFN.LT.1)
IE.AOP -- Part of the DPB is out of the issuing task's
address space
IE.SOP -- DIC or DPB size is invalid

2-38

Directive Descriptions

2.2.5 Trap-Associated Directives
System traps are task interrupts initiated by the RSX-ll M EXECUTIVE to allow servicing of
contingencies which are either exceptional events, such as an odd address error, or a signalling
event such as the completion of a previous I/O request. They are exclusive to an individual task,
i.e., there is nothing one task can do to cause a trap to occur in another task.
When a task plans to use the system trap facility, it must contain a trap service routine. This
routine is automatically entered when the trap occurs; the task's normal priority and privilege*
are in effect. The action taken by the RSX-l1M Executive if a service routine is not supplied is
dependent upon the type of trap, and is described below.
There are two types of system traps, Synchronous System Traps (SST's) and Asynchronous System Traps (AST's).
SST's provide a means of servicing fault conditions within a task. A synchronous condition is
one that will re-occur at precisely the same instruction if the sequence of instructions preceding
the fault were repeated. An odd address fault is a typical example. If a service routine is not included in the task, and a synchronous fault occurs, the task's execution is aborted.
AST's are closely linked to significant events. They commonly occur as the result of a significant event and thus occur asynchronously with respect to a task's execution, i.e., a task does not
have direct or complete control over the exact moment of AST occurrence. A characteristic of
AST's is that they are for information purposes, such as signalling an I/O completion for which a
task desires immediate knowledge. If a service routine is not provided, a trap does not occur and
task execution is not interrupted.
It should be emphasized that SST's are initiated by the RSX-ll M Executive, but are then forgotten, i.e., they appear just like normal task execution. The RSX-ll M Executive, having initiated an SST, cannot determine that the task is in the SST service routine. Thus, an SST service
routine can be interrupted by another SST or an AST.

Note that SST's are caused by occurrences within a task, while AST's occur as a result of an external event. The RSX-llM Executive keeps track of all AST's, queues them (FIFO), and is
aware when a task is servicing an AST.

'Privileged task definition and construction is discussed in the Task Builder Reference Manual (DEC-II-OMTBA-A-O)

2-39

Directive Descriptions

SST's are effected by pushing the tasks' PS (Processor Status) word and PC (Program Counter)
onto its stack, and return control by issuing an RTI or RTT instruction. Note that the tasks general purpose registers RO~R6 are not saved, and if the user-trap routine intends to make use of
them, the user routine itself must save and restore them.
Execution of an SST service routine is indistinguishable from task execution, and an SST service
routine may perform any operation that may be performed by the task. However, if a service
routine for an SST may cause that SST to occur, it must be coded re-entrantIy.
SST service routine entry points are provided in a trap vector table which is contained in the
task. The trap vector table has the following format:
WD. 00 -- Odd Address error
WD. 01 -- Memory Protect Violation
WD. 02 -- T-bit Trap or execution of a BPT instruction
WD. 03 -- Execution of an lOT instruction
WD. 04 -- Execution of a Reserved instruction
WD. 05 -- Execution of a Non-RSX EMT instruction
WD. 06 -- Execution of a Trap instruction
WD. 07 -- PDP-l 1140 floating point exception
A zero or odd address appearing in the table is interpreted as no entry point specified. If an SST
occurs and an entry point is not specified, the task's execution is aborted. The SST vector table is
specified to the Executive by use of the SPECIFY SST VECTOR FOR TASK or the SPECIFY
SST VECTOR FOR DEBUGGING AID directives.
On entrance to an SST service routine, the stack always contains the following information:
SP+02 -- PS
SP+OO--PC
The task's stack may also contain additional information depending on the cause:
Memory Protect Violation - Complete stack
SP+IO
SP+06
SP+04
SP+02
SP+OO

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

* For details ofSRO, SR 1 and SR2 see the memory managemen t unit section of the 11140 or 11/45 Processor Handbook.

2-40

Directive Descriptions

TRAP Instruction and EMT Other Than 377 - Complete stack
SP+04
SP+02
SP+OO

PS
PC
Instruction Operand (low-order byte) multiplied
by two, non-sign extended.

The additional information must be removed from the stack before an exit from the SST service
routine is executed. Exit from an SST is usually via an R TI or R TT instruction.
AST's occur with the task's four W AITFOR mask words, the DSW, the PS, and the PC pushed
onto its stack. In effect this saves the state of the task so that the AST service routine has available to it all the services provided by the Executive. The requirement to save the DSW, PS, and
PC is obvious. Saving the W AITFOR mask words is necessary to permit the AST routines to
execute W AITFOR type directives, since it is these words which establish the waiting conditions that must be met for unblocking the waiting task. There may also be other parameters
pushed onto the stack, depending upon the cause of the AST. Note that the tasks general purpose registers RO-R6 are not saved, and if the user-trap routine intends to make use of them, the
user routine itself must save and restore them.
After processing an AST, the trap dependent parameters must be removed from the task's stack,
and an EXIT AST SERVICE directive issued with the task's stack set as indicated in the description of the AST SER VICE EXIT directive. (Refer to ASTX$S below.)
Upon ASTservice exit, control is returned to one of three places:
1.

Another (queued) AST;

The task, or

Another task (e.g., the corresponding task was in a wait or suspend state prior to the
execution of the AST).

The five variations in the stack format, depending upon the AST cause, are as follows:
1.

If a task is to be notified when an 11/45 Floating Point Unit exception trap occurs, a
SPECIFY FLOATING POINT EXCEPTION AST directive is issued. If specified,
an AST will occur when an 11145 Floating Point Unit exception trap occurs with
the stack containing the following:
SP+20 -- Event flag mask word for flags 1-16
SP+ 16 -- Event flag mask word for flags 17-32
SP+ 14 -- Event flag mask word for flags 33-48
SP+ 12 -- Event flag mask word for flags 49-64
SP+ 10 -- PS of task prior to AST
SP+06 -- PC of task prior to AST
SP+04 -- Task's directive status word
SP+02 -- Floating exception code
SP+OO -- Floating exception address

2-41

Directive Descriptions

If a task is to be notified of power fail ure recoveries, a SPECIFY POWER RECOVERY
AST directive is issued. Ifspecified, an ASTwill occur when the power is restored with
the stack containing the following:
SP+14
SP+12
SP+10
SP+06
SP+04
SP+02
SP+OO

Even t flag mask word for flags 1-16
Event flag mask word for flags 17-32
Event flag mask word for flags 33-48
Event flag mask word for flags 49-64
PS of task prior to AST
PC of task prior to AST
Task's Directive Status Word

If a task is to be notified when a message is sent to it, a SPECIFY RECEIVE AST
directive is issued. If specified, an AST will occur when a message is sent to the task
with the stack containing the following:
SP+14
Event flag mask word for flags 1-16
Event flag mask word for flags 17-32
SP+12
Event flag mask word for flags 33-48
SP+IO
SP+06 -- Event flag mask word for flags 49-64
PS of task prior to AST
SP+04
PC of task prior to AST
SP+02
Task's directive status word
SP+OO

When an 110 request is queued, an AST service entry point may be specified in the
macro. If specified, an AST will occur upon completion of the 110 request with the
task's stack containing the following information:
SP+16
SP+14
SP+12
SP+IO
SP+06
SP+04
SP+02
SP+OO

----

Event flag mask word for flags 1-16
Event flag mask word for flags 17-32
Event flag mask word for flags 33-48
Event flag mask word for flags 49-64
PS of task prior to AST
PCoftask prior to AST
Task's Directive Status Word
Address of 110 status block for 110
request (or zero ifnone specified).

When a MARK TIME directive is issued, an ASTservice entry point may be specified
in the macro. If specified, when the indicated time interval has elapsed, an AST will
occur with the task's stack as follows:
SP+16
SP+14
SP+12
SP+10

Event flag mask word for flags 1-16
Event flag mask word for flags 17-32
Event flag mask word for flags 33-48
Event flag mask word for flags 49-64

2-42

Directive Descriptions
SP+06 -SP+04 -SP+02 -SP+OO --

PSoftask prior to AST
PC of task prior to AST
Task's Directive status Word
Event Flag number (or zero ifnone specified)

The following notes describe generalcharacteristics and use of AST's.

1. Two directives, DISABLE AST RECOGNITION and ENABLE AST RECOGNITION, allow AST's to be queued for subsequent execution during critical sections of
code that access data bases that are also accessed by AST service routines. If AST's occur while AST recognition is disabled, they are queued (FIFO), and will be processed
when AST recognition is enabled.
2.

If an AST occurs while another AST is being processed, it is queued (FIFO), and will
be processed when the current AST service is completed, unless AST recognition is
disabled by the AST service routine.

3. If an AST occurs while an SST is being processed, the SST service routine execution
will not be distinguished from task execution, and will be interrupted for execution
of the AST service routine.
4.

If an AST occurs while the related task is suspended, the task remains suspended after
execution of the AST service routine, unless explicitly resumed by the AST service
routine or another task.

If an AST occurs while the related task is waiting for an event flag setting (W AITFOR
directive), the task remains in a wait state after execution of the AST service routine
unless an appropriate event flag is set by the ASTservice routine or another task.

If an AST occurs while the related task is in execution, the task is interrupted for the
execution of the ASTservice routine.

If an ASToccurs for a checkpointed task, the ASTis queued (FIFO) and effected when
the task is returned to direct competition for processor resources.

AST memory is allocated when the AST is specified. Thus, no AST lacks memory for
data storage at the time the AST occurs.

2-43

Directive Descriptions

AST SER VICE EXIT (only s-form supplied)

ASTX$S

This directive instructs the system to terminate execution of an Asynchronous System Trap service routine.

If another AST is queued, and AST's are not disabled, then the next AST is immediately effected.
Otherwise, the task's pre-ASTstate is restored.
Fortran Call:
Neither the FORTRAN IV 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
BCC
JSR

ERR
(PC)+,-(SP) ;PUSH DPB ONTO THE STACK
115.,1
; ASTX$S MACRO DIC, DPB SIZE=l WORD
377
;TRAP TO THE EXECUTIVE
;BRANCH IF DIRECTIVE SUCCESSFUL
.+6
PC,ERR
;OTHER WISE, CALL ROUTINE 'ERR'

Local Symbol Definitions:
None
DSW Return Codes:
IS.SUC
IE.AST
IE.ADP
IE.SDP

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

2-44

Directive Descriptions
Notes:
1.

When an AST occurs, the Executive, pushes, at minimum, the following information onto the task's stack:
SP+ 14 -- Event flag mask word for flags 1-16
SP+ 12 -- Event flag mask word for flags 17-32
SP+ 10 -- Event flag mask word for flags 33-48
SP+06 -- Event flag mask word for flags 49-64
SP+04 -- PS of task prior to AST
SP+02 -- PC of task prior to AST
SP+OO -- DSW of task prior to AST
The task stack must be in this same state when the AST SER VICE EXIT directive
is executed.
In addition to the above parameters, supplemental information is also pushed
onto the task stack for certain AST's. For I/O completion the stack contains the
address of the 110 Status Block; for MARK TIME, the stack contains the Event
Flag Number; for 11145 FLOATING POINT 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 this is done when an AST
routine is used on 110 completion:

Example:

; EXAMPLE PROGRAM
; LOCAL DATA

IOSB:
BUFFER:

.BLKW
.BLKW

2
30.

; 110 STATUS DOUBLEWORD
;110 BUFFER

; START OF MAIN PROGRAM

2-45

Directive Descriptions
START:

; PROCESS DATA

QIO$S

# 10. WVB,#2",# IOSB,# ASTSER, < # BUFFER,#60.,#40 >
; PROCESS & WAIT

EXIT$S

;EXIT TO EXECUTIVE

; AST SER VICE ROUTINE

ASTSER:

; PROCESS AST

TST

(SP)+

;REMOVE ADDRESS OF 110 STATUS
; BLOCK
;ASTEXIT

ASTX$S
Notes: (cont.)
2.

The task may alter its return state 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 PC prior to the AST, the task may simply replace the PC
word on the stack. This may be useful in cases where error conditions are discovered in the AST routine, but, this alteration should be exercised with extreme caution since AST service routine bugs are difficult to isolate.

This directive requires a I-word DPB, thus the ASTX$S form of the macro is recommended since it will always require less space and executes with the same
speed as the DIR$ macro form.

2-46

Directive Descriptions

DISABLE AST RECOGNITION (only s-form supplied)

DSAR$S

This directive instructs the system to disable recognition of Asynchronous System Traps for the
issuing task. The AST's are queued as they occur, and will be effected when AST recognition is
enabled. There is an implied AST disable whenever an AST service routine is executing. When
a task's execution is started, AST recognition is not disabled.
Fortran Call:
CALL DSASTR
Macro Call:
DSAR$S [err]
err = Error routine address
Macro Expansion:
DSAR$S
MOV
.BYTE
EMT
BCC
JSR

ERR
(PC)+,-(SP) ;PUSH DPB ONTO THE STACK
99.,1
. ; DSAR$S MACRO DIC, DPB SIZE=l
;WORD
377
;TRAP TO THE EXECUTIVE
.+6
;BRANCH IF DIRECTIVE SUCCESS;FUL
PC,ERR
;OTHER WISE, CALL ROUTINE 'ERR'

Local Symbol Definitions:
None

2-47

Directive Descriptions

DSW Return Codes:
IS.SUC
IE.lTS
IE.ADP
IE.SDP

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

Notes:
1.

It is only the recognition which is disabled. The AST's are still queued by the system. They are queued FIFO and will occur in that order when AST recognition is
re-enabled.

This directive requires a I-word DPB, thus the DSAR$S form of the macro is recommended since it will always require less space and executes with the same
speed as the DIR$ macro form.

This Fortran call, as well as ENASTR below, 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. It is the
system which both accepts the trap and subsequently dismisses it. The Fortran program is notified by a jump to PWRUP but must use DSASTR and ENASTR to ensure the integrity of Fortran data structures, most importantly the stack, during
PWR UP processing.

2-48

Directive Descriptions

ENABLE AST RECOGNITION (only s-form supplied)

ENAR$S

This directive instructs the system to recognize Asynchronous System Traps for the issuing
task, i.e., to nullify a DISABLE AST RECOGNITION directive. AST's that have been queued
while recognition was disabled are effected at issuance. When a task's execution is started, AST
recognition is enabled.
Fortran Call:
CALL ENASTR
Macro Call:
EN AR$S [err]
err = Error routine address
Macro Expansion:
ENAR$S
MOV
.BYTE
EMT
BCC
JSR

ERR
(PC)+,-(SP) ;PUSH DPB ONTO THE STACK
101.,1
;ENAR$S MACRO DIC, DPB SIZE=1
;WORD
377
;TRAP TO THE EXECUTIVE
.+6
;BRANCH IF DIRECTIVE SUCCESS;"FUL
PC,ERR
;OTHER WISE, CALL ROUTINE' ERR'

Local Symbol Definitions:
None
DSW Return Codes:
IS.SUC -- Successful completion
IE.ITS -- AST recognition is not 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.

This directive requires a I-word DPB, thus the ENAR$S form of the macro is recommended since it will always require less space and executes with the same
speed as the DIR$ macro form.

2-49

Directive Descriptions
SPECIFY FLOATING POINT EXCEPTION AST

SFPA$

This directive instructs the system to record either:
1.

That floating point exception AST's for the issuing task are desired, and where
control is to be transferred when a floating point exception AST occurs, or

That floating poin t exception AST's for the issuing task are no longer desired.

When an AST service routine entry point address is specified, future floating point exception
AST's will occur for the issuing task, and control will be transferred to the indicated location
whenever a floating point exception AST occurs. When an AST service entry point address is
not specified, future floating point exception AST's will not occur until an AST entry point is
specified again.
Fortran Call:
Neither the FORTRAN IV language nor the ISA standard permits direct linking to
system trapping mechanisms; therefore, this directive is not available to Fortran tasks.
Macro Call:
SFPA$
ast

[ast]
Ast service routine entry point address (0)

Macro Expansion:
SFPA$
.BYTE
.WORD

FLTAST

111.,2
FLTAST

;SFPA$ MACRO DIC, DPB SIZE=2 WORDS
;ADDRESS OF FLOATING POINT AST

Local Symbol Definitions:
S.FPAE

AST Entry address

(2)

DSW Return Codes:
IS.SUC
IE.UPN
IE.ITS
IE.AST
IE.ADP
IE.SDP

Successful completion
I nsufficient dynamic memory
AST entry point address is already unspecified
Directive was issued from an AST service routine
or AST's arE; disabled
Part of the DPB is out of the issuing task's
address space
DIC or DPB size is invalid

2-50

Directive Descriptzons

Notes:
1.

SPECIFY FLOATING POINT EXCEPTION AST requires dynamic memory.

Floating point exception AST's are queued when a floating point exception trap
occurs. No future floating point exception AST's will be queued for the task until
the first one queued has actually been effected.

The floating point exception AST service routine is entered with the task stack in
the following state:
SP+20
SP+16
SP+14
SP+12
SP+10
SP+06
SP+04
SP+02
SP+OO

Event flag mask word for flags 1-16
Event flag mask word for flags 17-32
Event flag mask word for flags 33-48
Event flag mask word for flags 49-64
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 floating exception code and address must be removed from the task's stack
before an AST SER VICE EXIT directive is executed.
4.

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

This directive applies only to the 11145 Floating Point Unit.

2-51

Directive Descriptions
SPECIFY POWER RECOVERY AST

SPRA$

This directive instructs the system to record either:
1.

That power recovery AST's for the issuing task are desired and where control is to
be transferred when a power recovery AST occurs, or

That power recovery AST's for the issuing task are no longer desired.

When an AST service routine entry point address is specified, future power recovery AST's will
occur for the issuing task, and control will be transferred to the indicated location whenever a
power recovery AST occurs. When an AST service entry point address is not specified, future
power recovery AST's will not occur until an AST entry point is specified again.
Fortran Call:
To establish an AST:
EXTER N AL sub
CALL PWRUP (sub)
sub

name of a subroutine to be executed upon power recovery. The PWRUP
subroutine will effect a
CALL sub (no arguments).
sub is called as a result of a power recovery AST (Asynchronous System Trap),
and therefore may be controlled at critical points by using DISABLE and ENABLE AST recognition directives.

To remove an AST:
CALLPWRUP
Macro Call:
SPRA$

[ast]

ast = Ast service routine entry point address (0)
Macro Expansion:
SPRA$
.BYTE
.WORD

PWRAST
109.,2
PWRAST

;SPRA$ MACRO DIC, DPB SIZE=2 WORDS
; ADDRESS OF POWER RECOVERY AST

2-52

Directive Descriptions
Local Symbol Definitions:
S.PRAE -

AST En try address (2)

DSW Return Codes:
IS.SUC
IE.UPN
IE.ITS
IE.AST
IE.ADP
IE.SDP

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

Notes:
1.

SPECIFY POWER RECOVERY AST requires dynamic memory.

Power recovery AST's are queued when the power-up interrupt occurs following a
power failure. No future powerfail AST's will be queued for the task until the first
one queued has actually been effected.

The power fail AST service routine is entered with the task stack in the following
state:
SP+ 14 Even t flag mask word for flags 1-16
SP+ 12 Event flag mask word for flags 1T·32
SP+ 10 Event flag mask word for flags 33-48
SP+06 Event flag mask word for flags 49-64
SP+04 PS of task prior to AST
SP+02 PC of task prior to AST
SP+OO DSW of task prior to AST

No trap-dependent parameters accompany a powerfail AST, and thus the AST SERVICE EXIT directive must be executed with the stack in the same state as when the
AST was effected.
4.

If a power recovery AST entry point is specified by a checkpointable task and the
power fails while the task is checkpointed, the AST is not effected or queued. A
checkpointable task should disable checkpointing over critical regions where
power recovery AST's are essen tial.

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

2-53

Directive Descriptions
SPECIFY RECEIVE AST

SRDA$

This directive instructs the system to record either:

That receive AST's for the issuing task are desired, and where control is to be
transferred when a receive AST occurs, or

That receive AST's for the issuing task are no longer desired.

When an AST service routine entry point address is specified, future receive AST's will occur
for the issuing task, and control will be transferred to the indicated location whenever a receive
AST occurs. When an AST service entry point address is not specified, future receive AST's will
not occur until an AST entry point is specified again.
Fortran Call:
Neither the FORTRAN IV 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

last]
Ast service routine entry point address (0)

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:
IS.SUC
IE.UPN
IE.ITS
IE.AST
IE.ADP
IE.sDP

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

2-54

Directive Descriptions

Notes:
1.

SPECIFY RECEIVE AST requires dynamic memory.

Receive AST's are queued when a message is sent to the task. No future receive
AST's will be queued for the task un til the first one queued has actually been effected.

The receive AST service routine is entered with the task stack in the following
state:
SP+ 14
SP+ 12
SP+ 10
SP+06
SP+04
SP+02
SP+OO

Event flag mask word for flags 1-16
Event flag mask word for flags 17-32
Event flag mask word for flags 33-48
Event flag mask word for flags 49-64
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 AST, and thus the AST SERVICE EXIT directive must be executed with the stack in the same state as when
the AST was effected.
4.

If a receive AST entry point is specified by a checkpointable task and a message is
sent to the task while it is checkpointed, the AST is not effected or queued. A
checkpointable task should disable checkpointing over critical regions where receive AST's are essential.

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

2-55

Directive Descriptions
SPECIFY SST VECTOR TABLE FOR DEBUGGING AID

SVDB$

This directive instructs the system to record the address of a table of Synchronous System Trap
service routine entry points for LIse by an intra-task debugging aid (e.g., OOT). If the vector table is to be de-assigned, then the adr and len parameters are omitted from the macro invocation.
Whenever an SST service routine entry is specified in both the table used by the task, and the
table L1sed by a debugging aid, the trap occurs ror the debugging aid, and not for the task.
Fortran Call.:
Neither the FORTRAN IV language not the ISA standard permits direct linking to system trapping mcchani~ll1s; therefore, this directive is not available to Fortran tasks.

Macro Ca!l:
SVD13S

[adrJ,[Ienl

ddr
len

Addres:-, of SST vector table
Length or (n um ber or en tries in) the table in words

The vector table is of the following format:
WO.
WO.
WO.
WD.
WD.
WD.
WI).
WD.

00 -- Odd address error
0 I -- Meillory protect violation
02 -- T-bit trap or execution ora BPT instruction
03 -- ExecLltion oral1 lOT instruction
04 -- Execution or a reserved instruction
05 -- Execution or a non-RSX EMT instruction
06 -- Execution ora TRAP instruction
07 -- PDP-I 1/40 Floating Point exception

Macro Ex pansion:
SVDBS
.13YTE
.WORD
.WORD

SSTTBLA
103.,3

SSTTBL
4

;SVD13$ MACRO DIC, DPB SIZE=3 WORDS
; A DDR ESS OF SST TABLE
;SST TABLE LENGTIl=4 WORDS

Local Sym bol Definitions:
S.VDTA S.VDTL -

Table address (2)
Table length (2)

DSW Return Codes:
IE.SUC
IE.ADP
IE.SDP

Successful completion
Part of the DPB or table is out of the issuing TASK'S address space.
DIe or DPB size is invalid

2-56

Directive Descriptions

SVTK$

SPECIFY SST VECTOR TABLE FOR TASK

This directive instructs the system to record the address of a table of Synchronous System Trap
service routine entry points for use by the issuing task.
If the vector table is to be de-assigned, then the adr and len parameters are omitted from the
macro invocation.
Whenever an SST dervice 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, and not for the task.
Fortran Call:
Neither the FORTRAN IV language nor the ISA standard permits direct linking to
system trapping mechanisms; therefore; this directive is not available to Fortran
tasks.
Macro Call:
SVTK$

[adr],[Ien]

adr = Address of SST Vector table
len = Length of (number of entries in) the table in words
The vector table is of the following format:
WD.OO -- Odd address error
WD.Ol -- Memory protect violation
WD.02 -- T-bit trap or execution of a BPT instruction
WD.03 -- Execution of an lOT instruction
WD.04 -- Execution of a reserved instruction
WD.05 -- Execution of a non -RSX EMT instruction
WD.06 -- Execution of a TRAP instruction
WD.07 -- PDP-11l40 floating point exception,
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

Local Symbol Definitions:
S. VTT A - Table address (2)
S.VTTL - Table length (2)

2-57

Directive Descriptions
OSW Return Codes:
IS.SUC -- Successful completion
IE.AOP-- Part of the OPB or table is out of the issuing task's address space.
IE.SOP -- OIC or OPB size is invalid

2-58

Directive Descriptions
2.2.6

1/0 Related Directives

ASSIGNLUN

ALUN$

This directive instructs the system to assign a physical device unit to a Logical Unit Number
(LUN). ASSIGN LUN connects a LUN identifier with a physical device. It does not necessarily
indicate that the task has possession of the device.
Fortran Call:
CALL ASNLUN (lun,dev,unt'[ids])
lun = Integer containing a Logical Unit Number.
dev = Integer containing a device name (format: lA2).
unt = Integer containing a device unit number.
ids = Integer variable to receive the Direct Status Word.
Macro Call:
ALUN$lun,dev,unt
lun = Logical Unit Number
dev = Physical device name (two ASCII characters)
unt = Physical device unit number
Macro Expansion:
ALUN$
.BYTE
.WORD
.ASCII
.WORD

7,TT,O
7,4
7
ITTI

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

Local Symbol Definitions:
A.LULU - Logical Unit Number (2)
A.LUNA - Physical device name (2)
A.LUNU - Physical device unit number (2)
DSW Return Codes:
.IS.SUC -- Successful completion
IE.LNL -- LUN usage is interlocked (see note 1)
IE.lDU -- Invalid device and lor unit
IE.lLU -- Invalid Logical Unit Number
IE.ADP -- Part of the DPB is out of the issuing task's
address sQace
IE.SDP -- DIC or DPB size is invalid

2-59

Directive Descriptions
Notes:

A return code of IE.LNL means that the LUN may not be reassigned to another
device because it is already assigned to a device and a file is currently open on that
device for the specified LUN, or that the device is attached to the issuing task.

On successful reassignment all 110 requests for the issuing task in the previous device queue are cancelled.

2-60

Directive Descriptions
GET LUN INFORMATION

GLUN$

This 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
dat
ids

Integer contain~ng a logical unit number
6-word integer array to receive LUN information
Directive status

Macro Call:
GLUN$
lun
buf

lun,buf
Logical unit number
Address of 6-word buffer which will receive the LUN
information

Buffer Format:
WD. 00 -- Name of Assigned Device
WD. 01 -- Unit Number of Assigned Device and flags byte
WD. 02 -- First Device Characteristics Word
Bit 0 -- Record Oriented Device (1=yes) [FD.REC]*
Bit 1 -- Carriage Control Device (1=yes)[FD.CCL]
Bit 2 -- Terminal device (1 = Yes)[FD.TTY]
Bit 3 -- Directory Device (1=yes) [FD.DIR]
Bit 4 -- Single Directory Device (1=yes)[FD.SDI]
Bit 5 -- Sequential Device (1=yes)[FD.SDG]
Bits 6-11 Reserved
Bit 12 -- Pseudo Device (1 =yes)
Bit 13 -- Device Mountable as a
Communications Channel (1=yes)
Bit 14 -- Device mountable as a Files-II
device (1=Yes)
Bit 15 -- Device mountable (1=yes)
WD. 03 -- Second Device Characteristics Word
WD. 04 -- Third Device Characteristics Word
(Words 2 and 3 are device driver specific)
WD. 05 -- Standard device buffer size"

* Bits having symbolics associated with them have the symbols shown in square brackets. These symbols may be defined for use by a task via the FCSBT$ macro. See the I/O Operations Reference Manual (OEC-II-OMFSA-A-O).

2-61

Directive Descriptions
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 offsets are assigned relative to the start of the LUN 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)
DSW Return Codes:
IS.SUC -- Successful completion
IE.ITS -- No data currently queued
IE.ADP -- Part of the DPB or buffer is out of the issuing
task's address space
IE.SDP -- DIC or DPB size is invalid

* Always returned as 200(8) for RSX-IIDcompatibility.

2-62

Directive Descriptions
GET MCR COMMAND LINE

GMCR$

This directive instructs the system to transfer an 80-byte command line to the issuing Task.
Fortran Call:
CALL GETMCR (buf,[ids])
buf
ids

80-byte array to receive command line
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 termination character). The termination ~haracter is, however, in the buffer.
IE.AST -- Directive not issued by the last task requested by
MCR dispatch
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.

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

2-63

Directive Descriptions

RECEIVE DATA

RCVD$

This directive instructs the system to dequeue a I3-word data block for the issuing task that has
been queued (FIFO) for it via a SEND DATA Directive.
A 2-word sender task name (in RAD50) and the I3-word data block are returned in an indicated I5-word buffer, with the task name in the first two words.
Fortran Call:
CALL RECEIV (,buf,[ids])
buf
ids

I5-word integer array for received data
Directive status

Macro Call:
RCVD$ ,buf
buf = Address of I5-word buffer
Macro Expansion:
RCVD$
.BYTE
.WORD
.WORD

,DATBUF
75.,4
0,0
DATBUF

;NOTE: ONE ARGUMENT IS IGNORED
; RCVD$ MACRO DIC, DPB SIZE=4 WORDS
;SENDER TASK NAME (IGNORED)*
; ADDRESS OF I5.-WORD BUFFER

Local Symbol Definitions:
R.VDTN - Task name (4)
R.VDBA - Buffer address (2)
DSW Return Codes:
IS.SUC -- Successful completion
IE.AOP -- Part of the OPB or buffer is out of the issuing
task's address space
IE.SOP -- ole or OPB size is invalid

* This field exists for RSX -11 D compatibility and is not related to the task name delivered in R. VDTN. The task name
in R.VDTN is supplied by the Executive as part of its servicing of the SEND DATA directive.

2-64

Directive Descriptions
RECEIVE DATA OR EXIT

RCVX$

(,bufJidsD

I5-word integer array for received data
Directive status

Macro Call:
RCVX$
buf =

.buf
Address of I5-word buffer

Macro Expansion:
RCVX$
.BYTE
.WORD
.WORD

.DATBUF
77.,4
0,0
DATBUF

;NOTE: ONE ARGUMENT IS IGNORED
;RCVX$ MACRO DIC, DPB SIZE=4 WORDS
;SENDER TASK NAME (IGNORED)*
; ADDRESS OF 15.-WORD BUFFER

Local Symbol Definitions:
R.VXTN R.VXBA -

Task name (4)
Buffer address (2)

DSW Return Codes:
IS.SUC
IE.ADP
IE.SDP

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

This field exists for RSX-llD compatibility and is not related to the task name delivered in R.VXTN.
The task name in R. VXTN is supplied by the Executive as part of its servicing of the SEND DATA
directive.

2-65

Directive Descriptions

Notes:
1.

If no data has been sent, a task exit is effected.

The RECEIVE OAT A OR EXIT directive is useful in avoiding a possible race
condition that may occur between two tasks communicating via the SEND and
RECEIVE directives. The race condition occurs when one task executes a RECEIVE directive and finds its receive queue empty. But before the task can exit
the other task sends it a message. Since the first task has already decided to exit,
the message is lost since the receiving queue is flushed during task exit. This condition can be avoided by the receiving task executing a RECEIVE OAT A OR
EXIT directive. If the receive queue is found to be empty a task exit is effected
before the other task can send any data and thus no loss of data can occur.

If the exit is taken, the Executive frees task resources. In particular:
I-All attached devices are detached;
2-The AST queue is flushed;
3-All open files are closed;
4-110 is rundown; and
5-If the task is not fixed, its partition is freed.

If the exit is taken, a significant event is declared.

2-66

Directive Descriptions

QUEUE 1/0

QIO$

This directive instructs the system to place an 110 request for an indicated physical device unit
in a queue of priority-ordered requests for that device unit. The physical device unit is specified
as a logical unit number (LUN). A significant event is declared by device drivers upon 110 completion. If an event flag is specified, it is cleared when the request is queued, and set at the significant event. The 110 Status Block is also cleared when the request is queued and set to the
final 110 status when the 1/0 request is completed. If an AST service routine entry point address
is specified, the AST will occur upon 110 completion with the task's W AITFOR mask words, PS,
PC, DSW (directive status), and the address of the 110 status block pushed onto the task's stack.
The description below deals solely with the Executive directive; the device dependent information can be found in the 110 Drivers Reference Manual (DEC-II-OMDRA-A-D).
Fortran Call:
CALL Q10 (fnc,l un, [efn], [pri], [is b], [prl], [ids])
fun
lun
efn
pri
prl

ids

Integer 110 function code
Integer logical unit number
Integer event flag number
Integer priority; ignored, but must be present
A 6-word integer array containing device dependent parameters to be
placed in parameter words 1 to 6 of the Directive Parameter Block
(DPB).
Directive status

Macro Call:
QIO$
fnc
lun
efn
pri
isb
ast
prl

fnc,lun, [efn],[pri] 1[is b] ,last] ,[prJ]
110 function code (DEC-II-OMDRA-A-D)
Logical unit number
Event flag number
Priority; ignored, but must be present
Address of 110 status block
Address of AST service routine entry point
Parameter list of the form <Pl, ... ,P6>

2-67

Directive Descriptions

Macro Expansion:
QIO$
.BYTE
.WORD
.WORD
.BYTE
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD
.WORD

10.R VB, 7,52."IOST AT,IOAST, < IOBUFR,512. >
1,12.
;QIO$ MACRO DIC, DPB SIZE=12 .
10.RVB
; FUNCTION=READ VIRTUAL BLOCK
7
; LOG ICAL UNIT NUMBER 7
52.,0
; EFN 52., PRIORITY IGNORED
10STAT
; ADDRESS OF 2-WORD 110 STATUS BLOCK
; ADDRESS OF 110 AST ROUTINE
10AST
10BUFR
; ADDRESS OF DATA BUFFER
512~
;BYTE COUNT=512 .
o
;ADDITIONAL PARAMETERS...
o
;... NOT USED IN ...
o
;...THIS PARTICULAR ...
o
;.. .INVOCATION OF QUEUE 110

Local Symbol Definitions:
Q.lOFN - 110 function (2)
Q.lOLU - Logical unit number (2)
Q.lOEF - Event flag number (1)
Q.lOPR - Priority (1)
Q.lOSB - Address of I/O status block (2)
Q.lOAE - Address of 110 done AST entry point (2)
Q.lOPL - Parameter list (6 words) (12)
DSW Return Codes:
IS.SUC -- Successful completion
IE.UPN -- Insufficient dynamic memory
IE.ULN -- Unassigned LUN
IE.lLU -- Invalid LUN
IE.lEF -- Invalid event flag number (EFN.GT 64 or EFN.LT.O)
IE.ADI> -- Part of the DPB or 110 status block is out of the
issuing Task's address space
IE.SDP -- DIC or DPB size is invalid
Notes:
1.

If an AST entry point address is specified, the AST service routine is entered with
the task stack in the following state:
SP+ 16 Even t flag mask word for flags 1-16
SP+ 14 Event flag mask word for flags 17-32
SP+ 12 Event flag mask word for flags 33-48
SP+ 10 Event flag mask word for flags 49-64
SP+06 PS of task prior to AST
SP+04 PC of task prior to AST
SP+02 DSW of task prior to AST
SP+OO Address of 110 status block or zero if none
was specified in the QIO directive.

2-68

Directive Descriptions
The address of the I/O status block, which is a trap-dependent parameter, must be
removed from the task's stack before an exit AST directive is executed.
2.

If the directive is rejected, the specified event flar is not guaranteed to be cleared
or set. Thus, if the task indiscriminately executes a W AITFOR directive and the
QIO directive is rejected, then the task may wait forever. Care should always be
taken to insure that the directive was successfully completed.

2-69

Directive Descriptions
SEND DATA

SDAT$

This directive instructs the system to declare a significant event and to queue (FIFO) a I3-word
block of data for a task to receive. When an event flag is specified, the indicated event flag is set;
a significan t even t is always declared.
Fortran Call:
CALL SEND (tsk,buf,[efn]'[idsD
tsk
buf
efn
ids

Task name
I3-word integer array of data to be sent
Event flag number
Directive status

Macro Call:
SDAT$ tsk,buf,[efn]
tsk = Receiver task name
buf = Address of I3-word data buffer
efn = Event flag number
Macro Expansion:
SDAT$
.BYTE
.RAD50
.WORD
.WORD

ALPHA,DATBUF,52.
71.,5
;SDAT$ MACRO DIC, DPB SIZE=5 WORDS
IALPHAI
;RECEIVER TASK NAME
DATBUF
; ADDRESS OF I3.-WORD BUFFER
52.
; EVENT FLAG NUMBER 52 .

Local Symbol Definitons:
S.DATN - Task name (4)
S.DABA - Buffer address (2)
S.DAEF - Event flag number (2)
OSW Return Codes:
IS.SUC -- Successful completion
IE.INS -- Receiver Task is not installed
IE.UPN -- Insufficient dynamic memory
IE.lEF -- Invalid event flag number (EFN.GT.64 or EFN.LT.O)
IE.ADP -- Part of the OPB or data block is out of the issuing
task's address space
IE.SDP -- DIC or OPB size is invalid
Notes:
1.

SEND DATA requires dynamic memory.

2-70

APPENDIX A

DIRECTIVE SUMMARY - ALPHABETIC ORDER
ABRT$

ABORT TASK

Fortran Call:
CALL ABORT (tsk,Bds])
ABRT$

tsk

Macro Call:
tsk = Task name

ALUN$

ASSIGNLUN

Fortran Call:
CALL ASNLUN (Iun,dev,unt,Hds])
lun = Integer containing a Logical Unit Number.
dev = Integer containing a device name (format lA2).
unt = Integer containing a device unit number.
ids = Integer variable to receive the Directive Status Word.
Macro Call:
ALUN$

lun,dev,unt

lun = Logical Unit Number
dev = Physical device name (two characters)
unt = Physical device unit number

AST SERVICE EXIT (only s-form supplied)

ASTX$S

Fortran Call:
Neither the FORTRAN IV language nor the ISA standard permits direct linking
to system trapping mechanics, therefore, this directive is not available to Fortran
tasks.

A-I

Directive Summary - Alphabetical Order

Macro Call:

ASTX$S

[err]

err = Error routine address

CLEF$

CLEAR EVENT FLAG
Fortran Call:
CALL CLFEF (efn,[ids])
efn
ids

Integer containing an event flag number
Directive status

Macro Call:

CLEF$

efn

efn = Event flag number

CANCEL MARK TIME REQUESTS (only s-form supplied)
Fortran Call:
CALL CANMT (,[ids])
ids

Directive status

Macro Call:

CMKT$S ["err]
err = Error routine address

A-2

CMKT$S

Directive Summary - Alphabetical Order

CANCEL TIME BASED INITIATION REQUESTS

CSRQ$

Fortran Call:
CALL CAN ALL (tsk,[ids])
tsk
ids

Task name
Directive status

Macro Call:

CSRQ$ tsk
tsk = Task name

DECLARE SIGNIFICANT EVENT (only s-form supplied)

DECL$S

Fortran Call:
CALL DECLAR (,[ids])
ids

Directive status

Macro Call:

DECL$S

[,err]

err = Error routine address

DISABLE AST RECOGNITION (only s-form supplied)
Fortran Call:
CALL DSASTR
Macro Call:

DSAR$S

[err]

err = Error routine address

A-3

DSAR$S

Directive Summary - Alphabetical Order

DISABLE CHECKPOINTING (only s-form supplied)

DSCP$S

Fortran Call:
CALL DISCKP
Macro Call:

DSCP$S

[err]

err = Error routine address

ENABLE AST RECOGNITION (only s-form supplied)

ENAR$S

Fortran Call:
CALL ENASTR
Macro Call:

ENAR$S

[err]

err = Error routine address

ENABLE CHECKPOINTING (only s-fonn supplied)
Fortran Call:
CALL ENACKP
Macro Call:

ENCP$S [err]

err = Error routine address

A-4

ENCP$S

Directive Summary - Alphabetical Order
TASK EXIT (only s-form supplied)

EXIT$S

Fortran Call:
STOP
Macro Call:

EXIT$S

[err]

err = Error routine address

EXIF$

EXITIF
Fortran Call:
CALL EXITIF (efn'[ids])
efn
ids

Event flag number
Directive status

Macro Call:

EXIF$

efn

efn = Event flag number

GET LUN INFORMATION

GLUN$

Fortran Call:
CALL GETLUN (Iun,dat,[ids])
lun
dat
ids

Integer containing a logical unit number
6-word integer array to receive LUN information
Directive status

A-5

Directive Summary - Alphabetical Order

Macro Call:

GLUN$ lun,buf
lun = Logical unit number
buf = Address of 6-word buffer which will receive the LUN information

GMCR$

GET MCR COMMAND LINE
Fortran Call:
CALL GETMCR (buf,[ids])
buf
ids

80-byte array to receive command line
Directive status

Macro Call:
GMCR$

GET PARTITION PARAMETERS

GPRT$

Fortran Call:
CALL GETPAR ([prt],buf,[ids])
prt
buf
ids

a two word RADIX-50 partition name
a 3-word integer array to receive partition parameters
Directive status

Macro Call:
GPRT$ [prt],buf

prt = Partition name
buf = Address of a 3-word buffer

A-6

Directive Summary - Alphabetical Order

GET SENSE SWITCHES (only s-form supplied)

GSSW$S

Fortran Call:
CALL READSW (isw)
isw

Integer to receive the console switch settings

Macro Call:
GSSW$S [err]

err = Error routine address

GET TIME PARAMETERS

GTIM$

Fortran Call:
FORTRAN IV provides several subroutines for obtaining the time in a number of
formats. See the RSX-IIM FORTRAN IV Reference Manual DEC manual number DEC-II-LFLRA-A-D.
Macro Call:
GTIM$ buf
buf = Address of 8-word buffer

GET TASK PARAMETERS

GTSK$

Fortran Call:
CALL GETTSK
buf
ids

(buf,[idsD

16-word integer array to receive the task parameters
Directive status

Macro Call:
GTSK$

buf

buf = Address of a 16-word buffer

A-7

Directive Summaty - Alphabetical Order

MARK TIME

MRKT$

Fortran Call:
CALL MARK (efn,tmg,tnt,[ids])
efn
tmg
tnt
ids

Event flag number
Integer time interval magnitude
Integer time interval unit
Directi ve status

The ISA standard call for delaying a task for a specified time interval is also provided:
CALL WAIT (tmg,tnt,ids)
tmg
tnt
ids

Integer time interval magnitude
Integer time interval unit
Directive status

Macro Call:
MRKT$ efn,tmg,tnt,[ast]
efn = Event flag number
tmg = Time interval magnitude
tnt = Time interval unit
ast = ASTentry point address

QIO$

QUEUE 110
Fortran Call:
CALL QIO (fnc,lun,[efn],[pri],[isb],[prl],[ids])
fun = Integer I/O function code
lun
Integer logical unit numbe!'
efn
Integer flag number
pri
Integer priority; ignored, but must be present
isb
2-word integer array to receive final 110 status
prl
6-word integer array containing devir,e dependent
parameters to be placed in parameter words 1 to 6
of the Directive Parameter Block (DPB).
ids
Directive status

A-8

Directive Summary - Alphabetical Order

Macro Call:
QIO$

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

fnc = 110 function code (see DEC-II-0MFSA-A-D)
lun = Logical unit number
efn = Event flag number
pri = Priority; ignored, but must be present
isb = Address of 110 status block
ast = Address of AST service routine entry point
pri = Parameter list of the form <PI,.",P6>

RECEIVE DATA

RCVD$

Fortran Call:
CALL RECEIV (,buf,[ids])
buf = IS-word integer array for received data
ids = Directive status
Macro Call:
RCVD$

,buf

buf = Address of IS-word buffer

RCVX$

RECEIVE DATA OR EXIT

Fortran Call:
CALL RECDEX (,buf,,[ids])
buf
ids

IS-word integer array for received data
Directive status

Macro Call:
RCVX$ ;buf
buf

Address of IS-word buffer

A-9

Directive Summary - Alphabetical Order

RDAF$

READ ALL EVENT FLAGS
Fortran Call:
Only a single event flag may be read by a FORTRAN IV task. The call is:
CALL READEF (efn,[ids])
efn = Event flag number
ids = Directive status
Macro Call:
RDAF$ buf
buf = Address of 4-word buffer

REQUEST

RQST$

Fortran Call:
CALL REQUES (tsk,[optl,[ids])
tsk
opt

ids

Task name
4-word integer array
opteD
Partition name first half; ignored, but must be present
opt(2)
partition name second half; ignored, but must be present
opt(3)
priority; ignored, but must be present
opt(4)
user identification code
Directive status

Macro Call:
RQST$

tsk,[prt],[pri],[ugcl,[uoc]

tsk = Task name
prt = Partition name; ignored, but must be present
ugc = UIC group cOde
uoc = UIC owner code

A-lO

Directive Summary - Alphabetical Order

RESUME

RSUM$

Fortran Call:
CALL RESUME (tsk,[ids])
tsk
ids

Task name
Directive status

Macro Call:
RSUM$

tsk

tsk = Task name

RUN

RUN$

Fortran Calls:
CALL RUN (tsk,[opt],[smg],[snt],[rmg],[rnt],[ids])
tsk
opt

Task name
4-word integer array
opteD
Partition name first half; ignored, but must be present
opt(2)
Partition name second half; ignored, but must be present
opt(3)
Priority; ignored, but must be present
opt(4)
User identification code
smg = Schedule delta magnitude
snt = Schedule delta unit
rmg = Reschedule interval magnitude
rnt
Reschedule interval unit
ids = Directi ve status
The ISA standard call for initiating a task is also provided:
CALL START (tsk,smg,snt,ids)
tsk = Taskname
smg = Schedule delta magnitude
snt = Schedule delta unit
ids = Directive status

A-ll

Directive Summary - Alphabetical Order

Macro Call:
RUN$

tsk,[prt] ,[pri] ,[ugc], [uoc], [smg], [sn t] ,[rmg] ,[rn t]

tsk = Task name
prt = Partition name; ignored, but must be present
pri = Priority; ignored, but must be present
ugc = UIC group code
uoc = UIC owner code
smg = Schedule delta magnitude
snt = Schedule delta unit
rmg = Reschedule interval magnitude
rnt = Reschedule interval unit

SDAT$

SEND DATA
Fortran Call:
CALL SEND (tsk,buf,[efn],[idsD
tsk
buf
efn
ids

Task name
I3-word integer array of data to be sent
Event flag number
Directive status

Macro Call:
SDAT$ tsk,buf,[efn]
tsk = Recei ver task name
buf = Address of I3-word data buffer
efn = Event flag number

A-I2

Directive Summary - Alphabetical Order

SETF$

SET EVENT FLAG
Fortran Call:
CALL SETEF (efn,[idsD
efn
ids

Event flag number
Directive status

Macro Call:
SETF$ efn
efn = Event flag number

SUSPEND (only s-form supplied)

SPND$S

Fortran Call:
CALL SUSPND
Macro Call:
SPND$S
err

[err]
Error routine address

SPECIFY FLOATING POINT EXCEPTION AST
Fortran Call:
Not supported.
Macro Call:
SFPA$ [ast]
ast

Ast service routine entry point address

A-I3

SFPA$

Directive Summary - Alphabetical Order

SPRA$

SPECIFY POWER RECOVERY AST
Fortran Call:
CALL PWRUP (sub)
sub = name of a subroutine to be executed upon power recovery.
The PWRUP subroutine will effect a
CALL sub (no arguments)

sub is called as a result of a power recovery AST (Asynchronous System
Trap), and therefore may be controlled at critical points by using the
DSABLE and EN ABLE AST recognition directives.
Macro Call:
SPRA$

fast]

ast = Ast service routine entry point address

SPECIFY RECEIVE AST

SRDA$

Fortran Call:
Not supported.
Macro Call:
SRDA$
ast

fast]
Ast service routine en try point address

SPECIFY SST VECTOR TABLE FOR DEBUGGING AID
Fortran Call:
Not supported.
Macro Call:
SVDB$

[adr],[Ien]

adr = Address of SST vector table
len = Length of (number of entries in) table in words

A-14

SVDB$

Directive Summary - Alphabetical Order

SPECIFY SST VECTOR TABLE FOR TASK

SVTK$

Fortran Call:
Not supported.
Macro Call:
SVTK$

[adr], [len]

adr = Address of SST Vector table
len = Length of (number of entries in) table in words

WAIT FOR SIGNIFICANT EVENT (only s-form supplied)

WSIG$S

Fortran Call:
CALL WFSNE
Macro Call:
WSIG$S

[err]

err = Error routine address

WAIT FOR LOGICAL "OR" OF EVENT FLAGS
Fortran Call:
CALL WFLOR (efnl,efn2, ... efnn)
efn

LIST of event flag numbers is 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

A-15

WTLO$

Directive Summary - Alphabetical Order

WAIT FOR SINGLE EVENT FLAG

WTSE$

Fortran Call:
CALL W AITFR (efn,[ids])
efn
ids

Event flag number
Directive status

Macro Call:
WTSE$ efn
efn = Event flag number

A-16

APPENDIX B

STANDARD ERROR CODES

The symbol definitions below are the directive status codes that are returned by the RSX-IIM
executive. To include these definitions in a MACRO-II program the following coding sequence
is used:
.MCALL DRERR$
DRERR$

,
; STANDARD ERROR CODES RETURNED BY DIRECTIVES IN THE DIRECTIVE
; STATUS WORD
IS.CLR
+00
EVENT FLAG WAS CLEAR
IS.SUC
+01
OPERA tfON COMPLETE, SUCCESS
IS.SET
+02
EVENT FLAG WAS SET

IE.UPN
IE.lNS
IE.ULN
IE.ACT
IE.lTS
IE.CKP

-01.
-02.
-05.
-07.
-08.
-10.

INSUFFICIENT DYNAMIC STORAGE
SPECIFIED TASK NOT INSTALLED
UN-ASSIGNEDLUN
TASK NOT ACTIVE
DIRECTIVE INCONSISTENT WITH TASK ST ATE
ISSUING TASK NOT CHECKPOINT ABLE

IE.AST
IE.LNL
IE.lDU
IE.lTI
IE.lLU
IE.lEF
IE.ADP
IE.SDP

-80.
-90.
-92.
-93.
-96.
-97.
-98.
-99.

DIRECTIVE ISSUED/NOT ISSUED FROM AST
LUN LOCKED IN USE
INV ALID DEVICE OR UNIT
INV ALID TIME PARAMETERS
INVALIDLUN
INVALID EVENT CGT.64.)
PART OF DPB OUT OF USER'S SPACE
DIC OR DPB SIZE INVALID

B-1

INDEX
ABORT TASK, 2-5
ABRT$, 2-5
Active task, 1-12
Address, DPB, 1-3
ALUN$, 2-59
ASSIGN LUN, 2-59
AST, 2-31, 2-39, 2-43, 2-67
AST cause, 2-41
AST entry point address, 2-32
AST queue, 2-30, 2-66
AST service entry point, 2-31
AST SERVICE EXIT, 2-44
AST service routine, 2-41
ASTX$S, 2-44
Attached devices, 2-30, 2-66
Asynchronous system trap, 2-31
Asynchronous system traps, 2-39

Blocked task, 1-13
BPT instruction, 2-56

CALL ABORT, 2-5
ASNLUN, 2-59
CANALL, 2-6
CANMT, 2-27
CLEFEF, 2-26
DECLAR, 2-28
DISCKP, 2-15
DSASTR, 2-47
ENACKP, 2-16
EN ASTR, 2-49
EXITIF, 2- 29
GETLUN, 2-61
GETMCR, 2-63
GETPAR, 2-17
GETTSK, 2-19
MARK, 2-31
PWRUP, 2-52
QIO, 2-67
RECEIV, 2-64
READEF, 2-33
READSW, 2-21
RECOEX, 2-65
REQUES, 2-8
RESUME, 2-1
RUN, 2-11
SEl'fD, 2-70

SETEF, 2-34
SUSPND, 2-14
WAITFR, 2-38
WFLOR, 2-36
WFSNE, 2-35
Calls, subroutine, 1-1
CANCEL MARK TIME REQUESTS, 2-27
CANCEL TIME BASED INITIATION REQUESTS, 2-6
Checkpointability, 1-6
Checkpointed task, 2-43
Checkpointing, 2-9, 2-12, 2-14, 2-55
CLEAR EVENT FLAG, 2-26
CLEF$, 2-26
Clock, line frequency, 1-7
Clock, programmable, 1-7
Clock queue entry, 2-13, 2-32
Clock tick, 2-11
CMKT$S, 2-27
Code, condition, 1-3
Code, directive identification, 1-2
Codes, error, 1-5
Condition code, 1-3
Conventions, directive, 1-4
CSRQ$, 2-6

DECLARE SIGNIFICANT EVENT, 2-28
DECL$S, 2-28
Default UIC, 2-9, 2-13
Device names, 1-4
Device unit, 2-61, 2-67
DIC, 1-2
DIC number, 1-8
DIR$, 2-14, 2-15, 2-16, 2-27, 2-28,
2-35, 2-46, 2-48
Directive categories, 2-2
Directive conventions, 1-4
Directive descriptions, 2-4
Directive identification code, 1-2
Directive implementation, 1-2
Directive names, 1-9
Directive parameter block, 1-2
Directive, QIO, 1-5
Directives, 1-1
Directive status word, 1-3, 2-1
$DIR macro, 1-9, 2-1
DISABLE AST REGOG NITION, 2-43, 2-47
DISABLE CHECKPOINTING, 2-15
Dormant task, 1-12

Index-l

DPB, 1-2, 2-14, 2-15, 2-16, 2-27,
2-28, 2-35, 2-46
$DPB$$, 1-9
DPB address, 1-3
DPB, I-word, 2-48
DPB, predefined, 1-10
DPB size, 1-8
DSAR$S, 2-47
DSCP$S, 2-15
DSW, 1-3, 1-5, 2-32
Dynamic control of task execution,
2-23
Dynamic memory, 2-12, 2-32, 2-35,
2-51, 2-53, 2-54, 2-68, 2-70

EFN, 2-23, 2-24
EMT other than 377, 2-41
EMT 377, 1-9, 2-1
EMT 377 instruction, 1-1
EN ABLE AST RECOG NITION, 2-43, 2-49
ENABLE CHECKPOIN1ING, 2-16
ENAR$S, 2-49
ENCP$S, 2-16
Error codes, 1-5
Error returns, 1-5
Error routine, user, 1-10
Event-associated directives, 2-23
Event flag, 2-29, 2-43, 2-67, 2-69,
2-70
Event flag group, 2-37
Event flag mask word, 2-32
Event flag number, 1-8, 2-23, 2-31,
2-38" 2-45
Event flags, 1-4,2-23,2-24
Examples of macro calls, 1-10
Execution, terminate, 2-5
EXIF$, 2-29
EXIT, 1-3, 1-9
EXITIF, 1-3, 1-9, 2-29
EXIT$S, 2-7

Fixed, 2-14
FLOATING POINT EXCEPTION, 2-45,
2-56
Form, $S, 1-9

Form, $C, 1-10
Forms, macro, 1-9
FORTRAN-IV, 1-4
FORTRAN subroutines, specialized,
1-4

General purpose registers, 2-41
GETADR, 1-5
GETLUNINFORMATION, 2-61
GET MCR COMMAND LINE, 2-63
G ET PARTITION PARAMETERS, 2-17
GET SENSE SWITCHES, 2-21
G ET TASK PARAMETERS, 2-19
GET TIME PARAMETERS, 2-22
$$$GLB, symbol, 1-10
Global symbols, 1-10
GLUN$, 2-61
GMCR$, 2-63
GPRT$, 2-17
GSSW$S, 2-21
GTIM$, 2-22
GTSK$, 2-19

Hardware trapping, 2-23

Informational directives, 2-2,
2-17
Installation, task, 1-12
Instruction, EMT 377, 1-1
Interrupt, 2-23
Interrupts, 2-39
Intra-task communication, 2-23
I/O and Inter-task communications
related directives, 2-3
I/O completion, 2-45
I/O request, 2-42, 2-67
I/O related directives, 2-59
I/O status block, 2-45, 2-67
lOT instruction, 2-56

Library, system macro, 1-1, 1-8
Line frequency clock, 1-7

Index-2

Logical unit number, 1-6, 1-8, 2-62,
2-68
Logical Unit Numbers, 1-4
LUN, 1-6

Macro calls, 1-8
Macro calls, examples of, 1-10
Macro, DIR$, 1-9
MACRO-II, 1-4
Macro forms, 1-9
Magnitude value, 1-7
Mapped systems, 2-18
MARK TIME, 2-31, 2-42
MARK TIME directive, 2-24
Mask word, 2-37
.MCALL, 1-8
Memory protect violation, 2-40, 2-56
MRKT$, 2-31

Names, device, 1-4
Names, partition, 1-4
Names, task, 1-4
Non-RSX EMT instruction, 2-56

Odd address error, 2-39, 2-56
ODT, 2-56
Offsets, symbolic, 1-10
I-word DPB, 2-48

Parameter, time, 1-7
Partition names, 1-4
PC of task, 2-32
Pointer, stack, 1-2
Power failure, 2-24, 2-53
Power recovery, 2-53
Power-up, 2-48
Power-up interrupt, 2-53
Predefined DPB, 1-10
Priority, 2-9, 2-12, 2-13, 2-23,
2-28, 2-39, 2-68
Privilege, 2-39
Processor status, 2-40

Program counter, 2-40
Program section, 1-9
Programmable clock, 1-7
P-section, 1-9
PS of task, 2-32
PWRUP, 2-52

QIO$, 2-67
QIOdirective, 1-5
QUEUE 110, 2-67
QUEUE I/O directive, 2-24

Race condition, 2-29, 2-66
Rate, tick, 1-7
RCVD$, 2-64
RCVX$, 2-65
RDAF$, 2-33
READ ALL EVENT FLAGS, 2-33
Ready-to-run task, 1-12
RECEIVE DATA, 2-64
RECEIVE DATA OR EXIT, 1-3, 1-9,
2-65
RECEIVE directive, 2-29
Receive queue, 2-30
Re-entrancy, 1-9
Registers, 2-40
REQUEST, 2-8
Reserved instruction, 2-56
Resources, 2-14
RESUME, 2-10, 2-14
Return values, 1-3
Returns, error, 1-5
RQST$, 2-8
RSUM$, 2-10
RTI, 2-40
RTT, 2-40
RUN, 2-11
RUN$, 2-11

$Cform, 1-10
Schedule time, 2-11
SDAT$, 2-70
SEND DATA, 2-70
SEND DATA directive, 2-24
SEND directive, 2-29

Index-3

SET EVENT FLAG, 2-34
SETF$, 2-34
Setting of an event flag, 2-24
$S form, 1-9
SFPA$, 2-50
Significant event, 2-25, 2-30, 2-31,
2-34, 2-66, 2-67, 2-70
Significant events, 2-23, 2-24, 2-39
Specialized FORTRAN subroutines,
1-4
SPECIFY FLOATING POINT EXCEPTION,
2-41
SPECIFY FLOATING POINT EXCEPTION
AST, 2-50
SPECIFY POWER RECOVER Y AST, 2-42,
2-52
SPECIFY RECEIVE AST, 2-42, 2-54
SPECIFY SST VECTOR TABLE FOR DEBUGGING AID, 2-56
SPECIFY SST VECTOR TABLE FOR TASK,
2-57
SPND$S, 2-14
SPRA$, 2-52
SRDA$, 2-54
SST, 2-39, 2-43
SST service routine, 2-40
Stack, 1-3, 1-9, 2-1, 2-31, 2-32,
2-40, 2-41, 2-45, 2-51, 2-53,
2-55, 2-67, 2-68
Stack pointer, 1-2
STD, 1-6
STOP, 2-7
Subroutine calls, 1-1
Subroutines, specialized, FORTRAN,
1-4
SUSPEND, 2-10, 2-14
Suspend task execution, 2-35, 2-36,
2-38
Suspended task, 2-14
SVDB$, 2-56
SVTK$, 2-57
Symbol, $$$GLB, 1-10
Symbolic offsets, 1-10
Symbols, global, 1-10
Synchronous system traps, 2-39
System macro library, 1-1, 1-8
System task directory, 2-28
System traps, 2-23, 2-39

Task, 1-4
Task activation, 2-8
Task Builder, 1-12
Task execution control, 2-2
Task execution control directives,
2-5
TASK EXIT, 2-7
Task installation, 1-12
Task names, 1-4
Task states, 1-12
Task status control, 2-2
Task status control directives,
2-15
Task synchronization, 2-23, 2-24
T -bit trap, 2-56
Terminate execution, 2-5
Terminate task execution, 2-29
Tick rate, 1-7
Time interval, 2-31
Time parameter, 1-7
Time unit, 1-4
Trap associated directives, 2-3,
2-39
TRAP instruction, 2-41, 2-56
Trap service routine, 2-39
Trap vector, 2-40

UIC, 2-9
Unmapped systems, 2-18
User error routine, 1-10

Value, magnitude, 1-7
W AITFOR directive, 2-25
WAIT FOR LOGICAL "OR" OF EVENT
FLAGS, 2-36
WAITFOR mask words, 2-41
WAIT FOR SIGNIFICANT EVENT, 2-35
WAIT FOR SINGLE EVENT FLAG, 2-38
WSIG$S, 2-35
WTLO$, 2-36
WTSE$, 2-38

Index-4

HOW TO OBTAIN SOFTWARE INFORMATION
SOFTWARE NEWSLETTERS, MAILING LIST
The Software Communications Group, located at corporate headquarters in
Maynard, publishes software newsletters for the various DIGITAL products.
Newsletters are published monthly, and keep the user informed about customer software problems and solutions, new software products, documentation corrections, as well as programming notes and techniques.
There are two similar levels of service:
The Software Dispatch
The Digital Software News
The Software" Dispatch is part of the Software Maintenance Service.
service applies to the following software products:

This

PDP-9/l5
RSX-llD
DOS/BATCH
RSTS-E
DECsystem-10
A Digital Software News for the PDP-ll and a Digital Software News for
the PDP-B/12 are available to any customer who has purchased PDP-ll or
PDP-B/12 software.
A collection of existing problems and solutions for a given software
system is published periodically. A customer receives this publication
with his initial software kit with the delivery of his system. This
collection would be either a Software Dispatch Review or Software Performance Summary depending on the system ordered.
A mailing list of users who receive software newsletters is also maintained by Software Communications. Users must sign-up for the newsletter they desire. This can be done by either completing the form supplied with the Review or Summary or by writing to:
Software Communications
P.O. Box F
Maynard, Massachusetts 01754
SOFTWARE PROBLEMS
Questions or problems relating to DIGITAL's software should be reported
as follows:
North and South American Submitters:
Upon completion of Software Performance Report (SPR) form remove last
copy and send remainder to:
Software Communications
P.O. Box F
Maynard, Massachusetts 01754
The acknowledgement copy will be returned along with a blank SPR form
upon receipt.
The acknowledgement will contain a DIGITAL assigned SPR
number.
The SPR number or the preprinted number should be referenced in
any future correspondence. Additional SPR forms may be obtained from
the above address.
All International Submitters:
Upon completion of the SPR form, reserve the last copy and send the remainder to the SPR Center in the nearest DIGITAL office. SPR forms are
also available from our SPR Centers.
PROGRAMS AND MANUALS
Software and manuals should be ordered by title and order number.
United States, send orders to the nearest distribution center.

In the

Digital Equipment Corporation
Software Distribution Center
146 Main Street
Maynard, Massachusetts 01754

Digital Equipment Corporation
Software Distribution Center
1400 Terra Bella
Mountain View, California 94043

Outside of the United States, orders should be directed to the nearest
Digital Field Sales Office or representative.
USERS SOCIETY
DECUS, Digital Equipment Computers Users Society, maintains a user exchange center for user-written programs and technical application information.
The Library contains approximately 1,900 programs for all
DIGITAL computer lines. Executive routines, editors, debuggers, special
functions, games, maintenance and various other classes of programs are
available.
DECUS Program Library Catalogs are routinely updated and contain lists
and abstracts of all programs according to computer line:
PDP-8, FOCAL-8, BASIC-8, PDP-12
PDP-7/9, 9, 15
PDP-II, RSTS-ll
PDP-6/10, 10
Forms and information on acquiring and submitting programs to the DECUS
Library may be obtained from the DECUS office.
In addition to the catalogs, DECUS also publishes the following:
DECUSCOPE

-The Society's technical newsletter, published bi-monthly,
aimed at facilitating the interchange of technical information among users of DIGITAL computers and at disseminating news items concerning the Society. Circulation reached 19,000 in May, 1974.

PROCEEDINGS OF
THE DIGITAL
EQUIPMENT USERS
SOCIETY

-Contains technical papers presented at DECUS Symposia
held twice a year in the United States, once a year
in Europe, Australia, and Canada.

MINUTES OF THE
DECsystem-lO
SESSIONS

-A report of the DECsystem-lO sessions held at the two
United States DECUS Symposia.

COPY-N-Mail

-A monthly mailed communique among DECsystem-lO users.

LUG/SIG

-Mailing of Local User Group (LUG) and Special Interest
Group (SIG) communique, aimed at providing closer
communication among users of a specific product or
application.

Further information on the DECUS Library, publications, and other DECUS
activities is available from the DECUS offices listed below:
DECUS
Digital Equipment Corporation
146 Main Street
Maynard, Massachusetts 01754

DECUS EUROPE
Digital Equipment Corp. International
(Europe)
P.O. Box 340
1211 Geneva 26
Switzerland

RSX-IIM Executive Service Reference Manual
DEC-ll-OMERA-A-D
READER'S COMMENTS
NOTE:

This form is for document comments only. Problems
with software should be reported on a Software
Problem Report (SPR) form (see the HOW TO OBTAIN
SOFTWARE INFORMATION page).

Did you find errors in this manual?

If so, specify by page.

Did you find this manual understandable, usable, and well-organized?
Please make suggestions for improvement.

Is there sufficient documentation on associated system programs
required for use of the software described in this manual? If not,
what material is missing and where should it be placed?

Please indicate the type of user/reader that you most nearly represent.
[] Assembly language programmer
[] Higher-level language programmer
[] Occasional programmer (experienced)
[] User with little programming experience
[]

Student programmer

[] Non-programmer interested in computer concepts and capabilities
Name

Date _ _ _ _ _ _ _ _ _ _ _ __

Organization _________________________________________
Street ___________________________________________
City ________________ Sta te ________ z ip Code _ _ _ _ _ _ __
or
Country
If you do not require a written reply, please check here.

[]

.------------------------------------------------------------Fold fIere------------------------------------------------------------

.----------------------------------------------- Do Not Tear - Fold IIere and Staple -----------------------------------------------

FIRST CLASS
PERMIT NO. 33
MA YNARD, MASS.
BUSINESS REPLY MAIL
NO POSTAGE STAMP NECESSARY IF MAILED IN THE UNITED STATES

Postage will be paid by:

Software Communications
P. O. Box F
Maynard, Massachusetts 01754