Digital PDFs

AA-DO18A-TE

August 1978

400 pages

Original

79MB

view download

OCR Version

25MB

view download

Document:	VAX/VMS System Services Reference Manual
Order Number:	AA-DO18A-TE
Revision:	0
Pages:	400
Original Filename:

OCR Text

dlifgliltall
i
i 0

VAX/VMS
System Services
Reference Manual
Order No. AA-DO18A-TE

11Nl
1nl
i
1

VAXII

August 1978

This manual describes the VAX/VMS system services.
It provides coding conventions, examples of how to

‘use system services, and detailed reference information
on the arguments required by each system service.

VAX/VMS
System Services
Reference Manual
Order No. AA-DO18A-TE

SUPERSESSION/UPDATE INFORMATION:

This is a new document for this release.

OPERATING SYSTEM AND VERSION:

VAX/VMS V01

SOFTWARE VERSION:

VAX/VMS VO1

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

digital equipment corporation - maynard, massachusetts

SRRt

"First Printing,

August

1978

The information in this document is subject to change without notice

~and should not be construed as a commitment by Digital Equipment
Digital Equipment Corporation assumes no respon51bility
Corporation.
for any errors that may appear in this document.

The software described in this document is furnished under a license
and may only be used or copied in accordance with the terms of such
license.

No responsibility is assumed for the use or reliability of software
on

The postage~prepaid READER'S COMMENTS form on the last page of this
document requests the user's critical evaluation to assist us in preparing future documentation.

The following are trademarks of Digital Equipment Corporation:

DIGITAL

DECsystem-10

DEC

DECtape

PDP

DIBOL

DECUS

EDUSYSTEM

PHA

UNIBUS

FLIP

RSTS

COMPUTER LABS

FOCAL

RSX

COMTEX

INDAC

DDT

LAB-8

TYPESET-8
TYPESET-11

DECCOMM

ASSIST-11

DECSYSTEM-20
RTS~-8

TMS-11
ITPS-10

VAX

VMS

SBI

DECnet

IAS

OMNIBUS
|

CHIP

6/79-14

MASSBUS

0S/8

equipment that is not supplied by DIGITAL or its affiliated companies.

CONTENTS

PREFACE

INTRODUCTION

CHAPTER

WHO CAN

USE

SYSTEM SERVICES

SYSTEM SERVICES:

PRIVILEGE

AND

PROTECTION

SUMMARY OF VAX/VMS

N
®
L4

co~Jound» W

]

CODING

FORTRAN

CODING

EVENT

- AST

FLAG

SERVICES

(ASYNCHRONOUS

LOGICAL NAME

U SO NG N
®

[]

Y S

SYSTEM TRAP)

SERVICES

INPUT/OUTPUT SERVICES
PROCESS CONTROL SERVICES
TIMER AND TIME CONVERSION SERVICES
CONDITION HANDLING SERVICES

MEMORY MANAGEMENT SERVICES
SYSTEM SERVICE
SADJSTK

DESCRIPTIONS

- ADJUST

OUTER MODE

STACK POINTER

$ADJWSL - ADJUST WORKING SET LIMIT

SALLOC - ALLOCATE DEVICE

- SASCEFC - ASSOCIATE COMMON EVENT FLAG CLUSTER
SASCTIM - CONVERT BINARY TIME TO ASCII STRING
SASSIGN - ASSIGN I/O CHANNEL

$BINTIM - CONVERT ASCII STRING TO BINARY TIME
$BRDCST - BROADCAST

4,19

SCREPRC

4,20

SCRETVA
SCRMPSC
$SDACEFC
$DALLOC

IN N

4.18

'$CANCEL - CANCEL I/O ON CHANNEL
SCANEXH - CANCEL EXIT HANDLER
SCANTIM = CANCEL TIMER REQUEST
SCANWAK - CANCEL WAKEUP
SCLREF - CLEAR EVENT FLAG
$SCMEXEC - CHANGE TO EXECUTIVE MODE
SCMKRNL
- CHANGE TO KERNEI. MODE
SCNTREG - CONTRACT PROGRAM/CONTROIL REGION
SCRELOG - CREATE LOGICAL NAME
.
SCREMBX - CREATE MAILBOX AND ASSIGN CHANNEL

CHAPTER

MACRO

SYSTEM SERVICES

HOW TO USE SYSTEM SERVICES

LWWWwWwwwwww

CHAPTER'

CALLING THE

WNDH
= PRI
D>
W IN = o

CHAPTER

SYSTEM SERVICES

4.15
4.16

4,17

4.21
4,22
4,23
4.24

CREATE PROCESS

- CREATE VIRTUAL ADDRESS SPACE
- CREATE AND MAP SECTION
- DISASSOCIATE COMMON EVENT FLAG CLUSTER
- DEALLOCATE DEVICE
|

SDASSGN - DEASSIGN I/O CHANNEL

iii

CONTENTS

(Cont.)

Page

$SDCLAST

4-57

DECLARE AST

SDCLCMH - DECLARE CHANGE MODE OR COMPATIBILITY

MODE

HANDLER

$SDCLEXH - DECLARE EXIT HANDLER

$SDELLOG - DELETE LOGICAL NAME
$SDELMBX - DELETE MAILBOX
SDELPRC - DELETE PROCESS'
SDELTVA - DELETE VIRTUAL ADDRESS SPACE
$DGBLSC - DELETE GLOBAL SECTION
SDLCEFC - DELETE COMMON EVENT FLAG CLUSTER
SEXIT - EXIT
"SEXPREG - EXPAND PROGRAM/CONTROL REGION
$SFAO - FORMATTED ASCII OUTPUT
SFORCEX - FORCE EXIT

SGETCHN- GET I/O CHANNEL INFORMATION

4-64
4-66

4-68
4-70
4-72
4-73
4-74
4-76

4-90

4-92
4-95

SGETMSG -

4-102

GET

4-97

MESSAGE

4-104
4-105

REQUEST AND WAIT

FOR EVENT
4-106

"FLAG

SILCKPAG SLKWSET $SMGBLSC SNUMTIM SOUTPUT
EVENT

LOCK PAGES IN MEMORY
|
LOCK PAGES
IN WORKING SET
MAP GLOBAL SECTION
|
CONVERT BINARY TIME TO NUMERIC TIME
QUEUE OUTPUT REQUEST AND WAIT FOR

4-107

4-109
4-111

4-114
4-116

FLAG

SPURGWS SPUTMSG -

4-117

PURGE WORKING SET
PUT MESSAGE

4-118

$QI0O - QUEUE I/O REQUEST
$QIOW - QUEUE I/O REQUEST AND WAIT FOR EVENT

4-124

FLAG

4-127

SREADEF - READ EVENT FLAGS

4-128
4-129
4-131
4-133

SRESUME - RESUME PROCESS

SSCHDWK - SCHEDULE WAKEUP
SSETAST

- SET AST ENABLE

SSETEF - SET EVENT FLAG

SSETEXV
- SET EXCEPTION VECTOR

4-134
4-135

SSETIMR - SET TIMER
SSETPRA - SET POWER RECOVERY AST
SSETPRI - SET PRIORITY

4-139
4-140

SSETPRN
SSETPRT
SSETRWM
SSETSFM

SET PROCESS NAME
SET PROTECTION ON PAGES
SET RESQURCE WAIT MODE
SET SYSTEM SERVICE FAILURE

4-137

4-142
4-143

,
EXCEPTION

SSETSWM -

SET PROCESS

SWAP

MODE

$SNDACC - SEND MESSAGE TO ACCOUNTING MANAGER
SSNDERR $SNDOPR -

4-145
4-146

MODE

4-147
4-148

SEND MESSAGE

ERROR LOGGER

4-153

SEND

OPERATOR

4-154

MESSAGE

SSNDSMB - SEND MESSAGE TO SYMBIONT MANAGER

4.76

4-62

SGETDEV - GET I/0O DEVICE INFORMATION
SGETJPI - GET JOB/PROCESS INFORMATION
SGETTIM - GET TIME
SHIBER - HIBERNATE
$INPUT - QUEUE INPUT

4-58

4-60

4-159

$SUSPND - SUSPEND PROCESS
STRNLOG - TRANSLATE LOGICAL NAME
SULKPAG - UNLOCK PAGES FROM MEMORY

4-169

SULWSET - UNLOCK PAGES FROM WORKING SET

4-175

SUNWIND -

UNWIND

CALL

STACK

4-171
4-173

4-177

CONTENTS

(Cont.)

Page

SUPDSEC - UPDATE SECTION FILE ON DISK

4-179

SYSTEM SYMBOLIC DEFINITION MACROS

A-1

USING SYSTEM SYMBOLS
STODEF MACRO - SYMBOLIC
‘'AMES
CODES
|

A-2

SWAITFR - WAIT FOR SINGLE EVENT FLAG
SWAKE - WAKE
SWFLAND - WAIT FOR LOGICAL AND OF EVENT FLAGS
SWFLOR - WAIT FOR LOGICAL OR OF EVENT FLAGS
APPENDIX

4-182
4-183
4-185
4-186

FOR I/O FUNCTION

SMSGDEF MACRO
- SYMBOLIC NAMES

A-2
FOR SYSTEM

MATLBOX MESSAGES

A-6

$PRDEF MACRO - SYMBOLIC NAMES FOR PROCESSOR
REGISTERS
SPRTDEF - HARDWARE PROTECTION CODE DEFINITIONS
SPSLDEF MACRO - PROCESSOR STATUS LONGWORD SYMBOL
DEFINITIONS
$SSDEF MACRO - SYMBOLIC NAMES FOR SYSTEM STATUS
CODES

A-7
A-8

A-8

PROGRAM EXAMPLES

B-1

APPENDIX

QUICK REFERENCE SUMMARY OF SYSTEM SERVICES

c-1

wn
-

APPENDIX

MACRO

FORMS

c-1

FORTRAN FORMS
SYSTEM SERVICE

c-2
c-3

MACROS

Index 1

INDEX

HHEERFOONOOMEeWNDHE
N O

How to Use This Book
FORTRAN Interpretation of MACRO Examples

Using Local Event Flags
Example
Example

of
of

a Common Event
an AST

Flag

Cluster

The AST Service Routine
Logical Name Table Entries

Synchronizing I/0 Completion
Example of Terminal Input and Output
Device Allocation and Channel Assignment
Example of Using Formatted ASCII Output Program
Mailbox Creation and I/0
Defining

Input

and Output Streams

for

W
>

|
-

Subprocess
w

FIGURE

WWWwWwWwWwwwuwwwwH
|
I

FIGURES

‘\\W/

A-T7

3-15

Process

Hlbernatlon

Example of an Exit Handler

3-16"

Image Exit and Process Deletion
Using a Termination Mailbox

3=-17

Timer

3-18
3-19

Requests
Search of Stack

Argument List
Handler

for

|
Condition Handler

and Arrays

Passed

Condition
‘

CONTENTS

(Cont.)

Page

FIGURES (Cont.)
FIGURE

3-20

Example

3-21
3-22
3-23
3-24
4-1

Unwinding the Call Stack
Layout of Process Virtual Address Space
Creating and Mapping a Private Section
Creating and Mapping a Global Sectlon
Format of Numeric Time Buffer
|

Condition

Handling

Routines

3-72

3=-75
3-78
3-86
~3-88
4-114

|
|
:

TABLES

TABLE

1-1

Event

1-2

AST

Flag

Services

1-3

Logical Name Services

(Asynchronous

System Trap)

1-4

Input/Output

Process Control Services
Timer and Time Conversion

1-7
1-7

Services

1-8
|
Services

1-10
1-12

Condition Handling Services

1-8

Memory Management

1-9

Change

2-1

1-5
1-6

1-7

1-6

SerVLces

Mode

1-13

Services

1-14

Services

FORTRAN

Arguments

for

System Services

Default

Device Names

Process

Identification

3-1

Summary of Event Flag and Cluster Numbers .

3-3

3-4

Process

Hibernation

3-5

Summary of Exception Conditions

3-6

Sample

3-2

Virtual

4-1

Arguments

4-2

Summary

4-3

How FAO

for
FAO

for

and

Address

I/0

3-5

Services

Suspension

3-31
.

4-4
4-5

Format of Accounting

4-7

Optlons

System Serv1ce

3-70
4-49
4-80

Field Lengths

and

|
Information

Log File Records

Request Types for Symbiont Manager Messages
for Symbiont Manager Messages

3-45
3-80

Directives

Output

f%,“'

3-=43

Arrays

Fill Characters
Item Codes for Job/Process

4-6

2-17

the $CRMPSC

Determines

1-15

4-82
4-100

4-151

(

4-163
|

4-165

)

PREFACE

This manual provides
detailed

usage

VAX/VMS system
languages that
languages

and

wusers

reference

the

VAX/VMS

information

services can
be
wused
produce native code for

operating

the

system

with

services.

only
in
programs
written
1in
the VAX-11/780 hardware.
These

are:

VAX-11

FORTRAN

VAX-11

MACRO

IV-PLUS
|

INTENDED AUDIENCE
This manual is intended for system and application programmers who
already familiar with VAX/VMS system concepts.
For an overview of
operating system and an introduction to some of the concepts
used

system

services,

STRUCTURE

This manual

see

THIS

is organized

Chapter 1
overviews

Chapter

contains

appendixes,

introductory
information:
various categories of system

the

services

describes

system
VAX-11

services.
MACRO, and

program

written

the

each

conventions

It discusses
tells how
to

VAX-11l

users
to use

Chapter

1n
understanding
them.
4

provides

used

‘alphabetical

order,

FORTRAN IV-PLUS.

how

the

system
o

reference

The

descriptions

for

code

ease

calls

symbolic

names

for

services

guide

new

each

work

and how

|
information

are

presented

reference.

frequently used

vii

in
a

‘

Appendix A lists the system—prOvided macro instructions
define

the macro forms for coding
<call
the
services
from

detailed

service.

it presents
services, and

category.

Chapter 3 contains‘usagé information intended

system

into four chapters and three

summarizes
)

Summary Description.

DOCUMENT

follows:

the VAX/VMS

are
the
‘in

system

that

constants.

Appendix B

contains

sample

programs

that

use

various

system

services.

- Appendix

summarizes
the

system-service

formats,

reference.

See Figure
1 for

illustration of how to

use

this

book.

Read Chapter 1 for an overview
of all services; decide which

service(s) you want to use.

Do you

understand the

Read Chapter 2 for

rules and conventions

coding conventions

for coding calls to

and examples.

system services?

Do you need
more information
about how a service or
group of services

works?

Read the section'of Chapter 3
that gives usage information
and examples of the services.

\
To code a call to a system

service, read the reference
description of the service
in Chapter 4.

Figure

How

Use This Book

viii

for

easy

ASSOCIATED

DOCUMENTS

The following documents are'prerequisite for
e

Users:

All

VAX/VMS
e

MACRO

Programmers:

VAX-11
VAX-11
¢

Summary Description

FORTRAN

MACRO Language Reference Manual
MACRO User's Guide
Programmers:

VAX-11 FORTRAN IV-PLUS Language Reference Manual
VAX-11

FORTRAN

IV-PLUS

User's Guide

The following documents, which are referred to

1in

this

useful:

VAX/VMS Command Language User's Guide

Introduction to VAX-1l

VAX-1ll Record Management Services Reference Manual

VAX/VMS I/0 User's Guide

DECnet-VAX User's Guide

also

For a complete list of VAX-11]
see the VAX-11l

each,

manual,

may

Record Management Services

documents,

Information Directory.

including

descriptions

CONVENTIONS USED IN THIS DOCUMENT
The following syntactical conventions are used in this manual:

Brackets

Horizontal ellipses (...) indicate:
(1) when
shown
1n
the
service call, that additional optional
system
a
of
format
an example,
(2) when shown in
arguments have been omitted;
a service but not
by
required
arguments
additional
that
pertinent to the example are not shown.

Vertical ellipses in coding examples indicate that

optional

code

([ ])

arguments.

not pertinent

system

the

service descriptions

example

are

not

indicate
~

lines

shown.

For

example:

)

keywords
show
format
Uppercase letters in a system service
letters show
lowercase
shown;
as
entered
must be
that
variable

data.

CHAPTER 1
INTRODUCTION

TO SYSTEM

SERVICES

System services are procedures that the VAX/VMS operating system
uses
to
control
resources
avallable
to
processes;
to
provide
for
communication among processes;
and to perform basic operating
system
functions, such as the coordination of input/output operations.

Although most system services are

used

primarily

by'

the

operating

system
itself
on
behalf
of logged-in users, many are availlable for
general use and provide
techniques
that can
be
used
1in
application
.
:
7
programs.
For
example,
when you
1log
1into
_ the system, the Create
Process system service 1s called to create a process on
your
behalf.

{

You
may, in turn, code a program
service to create a subprocess.

that

1.1

PRIVILEGE

WHO

CAN

USE

SYSTEM

SERVICES:

calls

the

Create Process
/

system

Many system
services
are
available
and
programs, but the use of some services must

AND PROTECTION

suitable
for
be restricted

application
to protect:

q’e, e

The

performance
of the

system

The integrity
of user proceSses

For example, because the creation
of permanent mailboxes
uses
system
dynamic
memory,
the
wunrestricted
use of permanent mailboxes could
decrease the amount of memory available to
other
users.
Therefore,
the
ability to create permanent mailboxes is controlled:
a user must
be specifically assigned the
privilege
to
use
the
Create
Mailbox
system service to create
a permanent mailbox.
|

The various controls and restrictions'applied'to.system service
are
described
system services

1.1.1

User

Dbelow.
The
tables in Section 1.2
note any restrictions on the use of

Privileges

and

usage

that summarize the specific services.

Resource Quotas

The system manager, who maintains the user authorization file for
the
system,
grants privileges to use protected system services.
The user
authorization file contains, 1n addition
to
profile
information
on
each user, a list of specific user privileges and resource guotas.
When you log into the system, the privileges and quotas you have
been
assigned
are
associated
with
the
process
created on your behalf.
These privileges
and quotas
are
applied
to
every 1image
that
the
process

executes.

INTRODUCTION TO SYSTEM SERVICES

When an image issues a call to a system service that is protected by
If you have been granted
the privilege 1list is checked.
privilege,
the specific privilege required, the image is allowed to execute the
otherwise, a status code indicating an error is
system service;
|

returned.

d a quota is
When a system service that uses a resource controlleby
called, the process's quota for that resource is checked. If the
quota

process has exceeded its quota, or if it has no

allotment,

error status code may be returned. In some cases, the process may be
see
placed in a wait state until the resource becomes available;
Section 2.1.5.4, "Special Return Conditions.”

1.1.2

Control by Group Association

and
coordinating
for
Some system services provide techniques
synchronizing the execution of different processes. These services
the
that is,
require cooperating processes to be in the same group;
group fields in the user identification codes (UICs)

must match.

for the processes

e events 1in
For example, event flags are used to post the occurrencof
a program and can be shared among cooperating processes. However, the
processes that share a cluster of event flags must be in the same

1.1.3

access

modes:

group.

Protection by Access Mode

A process can-

execute

at any

one

four

user,

The access modes determine a
or kernel.
supervisor, executive,
Each page has a
process's ability to access pages of virtual memory.
of access —type
the
specifying
it,
with
associated
code
protection
The VAX-11/780
read, write, or no access -- allowed for each mode.
Architecture Handbook provides additional information on access modes.
system
For the most part, user-written programs execute in user mode;
for
programs executing at the wuser's request (system services,

the

other

three,

«calls,

the

access

mode

example) may execute at one
access modes.

In some system service

checked.

privileged,

the

caller

1is

For example, when a process tries to cancel timer requests,

it can cancel only those requests that were issued from the same or
less privileged access modes.. For example, a process executing 1in
user mode cannot cancel a timer request made from supervisor,
executive, or kernel mode, which are more privileged access modes.

INTRODUCTION TO

1.2

SYSTEM SERVICES

SUMMARY OF VAX/VMS SYSTEM SERVICES

The following'
functional

each group.

sections

groups,
Each

with

table

summarize

the

tables

VAX/VMS

system

lists:

The full name of the service and the

The functions performed by
the
service,
based on privilege (where applicable).

Restrictions on the use of
is keyed as follows:

which

is alphabetized

None

in this

book.

short,

the service,

macro

with

XXX privilege

use

the

service

for

name

This

this

distinctions

if any.

indicates that no restriction

the

services

1listing the services that belong in

column

placed

function.

indicates the specific user privilege that is

required

use

the service
for

the

requested

_y;

function.

yyy quota

indicates the specific resource quota that

required to
function.

Access mode

use

the

service

for

the

indicates that this service uses
the
access
mode
of
the caller to determine whether the
caller can execute the function requested.

UIC protectibn

indicates

access

that

based

this

the

service

may

caller's UIC.

restrict

For detailed information about a restriction applied
specific

service,

see

that

service's description
|

requested

any

in Chapter

Chapter 3 provides additional information, including examples, on the
services listed

l1.2.1

in Tables

Event Flag

1-1

through

1-8.

Services

A process can use event flags to synchronize sequences
in a
program.
Event flag services clear,
and place a process in a wait state pending
flag or flags.

Table

1.2.2

1-1

AST

lists

the

event

flag

operations

set, and read event
the setting
of
an

flags,
event

services.

(Asynchronous System Trap)

Services

‘Process execution
can
be
interrupted
by
events
(such
as - I/0
completion)
for
the
execution
of
designated
subroutines.
These
software
interrupts
are
called
asynchronous
system
traps
(ASTs)
because
they
occur
asynchronously
to
process
execution.
System
services are provided so that a process can control
the
handling
of
ASTs.

Table 1-2 lists the AST services.

INTRODUCTION

1.2.3

SYSTEM

SERVICES

Logical Name Services

Logical name services provide a generalized technique for
maintaining
and
accessing
character
string
1logical
name
and equivalence name
pairs.
Logical names can provide-“device-independence for
system
and

application program input and output operations.

Table 1-3 lists the logical name services.

1.2.4

Input/Output Services

1/0 services perform input and output operations directly, rather than
through
the
file
handling
services of the VAX-11l Record Management
Services (RMS).
I/0 services:
®

Perform

)

Format output lines converting binary numeric values to ASCII

Create mailboxes

strings

logical

and

virtual

substituting

for

input/output operations

variable data

interprocess

o»‘ Perform network operations
e

strings

communication

Queue messages to system processes

Table 1-4 lists the 1I/0
additional
covered

1.2.5

in ASCII

1in

information

this

serVices.

aspects

The .following manuals provide
of

manual:

input/output

operations

not

Introduction

to VAX-11

VAX-11

VAX/VMS

DECnet-VAX User's Guide

Record Management Services

Record Management Services Reference Manual
I/0 User's Guide

Process Control Services

Process control services allow you to create,
execution

delete,

and control

the

processes.

Table 1-5 lists the process control services.

1.2.6

Timer

and Time Conversion Services

Timer services schedule program events for a particular time
of
day,
or
for
after
a specified
1interval
of time has elapsed.
The time
conversion services provide a way to obtain
and
format
binary time
values
for use with the timer services.
~
Table

1-6

lists

the

timer

and

time

conversion

services.

INTRODUCTION TO SYSTEM SERVICES

1.2.7

Condition Hahdling Services

receive
to
designated
Condition handlers are procedures that can be
control when a hardware or software exception condition occurs during
condition
services designate
Condition handling
image execution.
handlers for special purposes.

Table 1-7 lists the condition handling services.|
1.2.8

Memory Management Services

Memory management services provide ways to

the wvirtual

address

Allow an image to increase or decrease the amount of

virtual

space available to a program.

wuse

Included are services that:

memory available

Control

)

Create and
or

the paging

access

and

swapping of virtual memory

in memory

files

that contain shareable

data

code

Table 1-8 lists the memory management services.

1.2.9 Change Mode Services

Change mode services alter the access mode
of a .process
privileged
mode
to
execute particular
used primarily by the operating system.

Table 1-9 lists the change mode services.

routines.
|

These
|

services are

INTRODUCTION TO SYSTEM SERVICES
Table

1-1

‘Event Flag Services

Associate Common
Event Flag Cluster
(SASCEFC)

Restriction(s)l

(s)
Function

Service Name

Creates a
cluster

temporary common event

flag

TQELM

quota

PRMCEB privilege

Creates a permanent common event flag
cluster

Establishes association with an existing
common event

flag

Disassociate Common Cancels association with a common event
Event Flag Cluster

flag

Group association

cluster

None

cluster

(SDACEFC)

Delete Common Event Marks a permanent common event

cluster

Flag Cluster
(SDLCEFC)

Set Event

Flag

(SCLREF)

(SREADEF)

Turns off an event flag in a processFlocal

None

Turns off an event flag in ‘a common event

Group association

Returns the status of all event flags in

None

Returns the status of all event flags in

Group association

Places the current process in a wait state

None

Places the current process in a wait state

Group association

event

cluster

flag

cluster

cluster.

a process-local event flag cluster
a common event

Wait for Single
Event Flag
(SWAITFR)

None

cluster

Group association

flag

Read Event Flags

flag

Turns on an event flag in a common event
flag

Clear Event

PRMCEB privilege
Group association

Turns on an event flag in a process-local
event

(SSETEF)

flag

for deletion

flag cluster

pending the setting of an event flag in a
process-local event flag cluster

pending the setting of an event flag in a
common event flag cluster

Wait for Logical OR Places the current process in a wait state
pending the settlng of any one of a speciof Event Flags

(SWFLOR)

fied set of flags in a process-local event
flag

cluster

Places the current process in a wait state

pending the settlng of any one of a specified set of
flag

wait for

Logical AND
of Event Flags
(SWFLAND)

flags

Places the current process in a wait state

pending the setting of all specified
flags in a process-local event flag
cluster

Group association

1n a common event

cluster

None

Places the current process in a wait

state pending the setting of all specified
flags in a common event flag cluster

None

For an explanation of the terms used in this column, see Page 1-3.

Group association

TO SYSTEM SERVICES
INTRODUCTION
Table

1-2

AST (Asynchronous System Trap)

Services

Restriction(s)l

Service Name

Function (s)

Set AST Enable

Enables or disables the delivery of ASTs

Declare AST
(SDCLAST)

Queues an AST for delivery
-

Set Power Recovery

|[Establishes AST routine to receive control

None

(SSETAST)

AST (SSETPRA)

ASTLM quota
Access mode

ASTLM quota

following power recovery condition

For an explanation of the terms used in this column, see Page 1-3.

‘)

;

Create Logical
($SCRELOG)

Restriction(s)l

Function(s)

Service Name
Name

Table 1-3

Logical Name Services

nce
Places logical name/equivalename

pair in process logical name table

Places logical name/equivalence name
pair in group logical name table

Places logical name/equivalence name
pair

system logical

name

pair from process logical name table

‘

“>

~ Translate Logical
Name ($TRNLOG)
,

SYSNAM privilege

None

Removes logical name/equivalence name
pair from group logical name table

GRPNAM privilege
Group association

Removes logical name/equivalence name

SYSNAM privilege

Searches logical name tables for a specified
logical name and return its equivalence
name when the first match is found

‘None

pair from system logical name table

GRPNAM privilege
Group association

table

Delete‘Logical Name | Removes logical name/equivalence name
(SDELLOG)

Access mode

For an explanation of the terms used in this column, see Page 1-3.

INTRODUCTION TO SYSTEM SERVICES
Table 1-4
Input/Output Services

Restriction(s)

Function
(s)

Service Name

Ljij .

NSy B

Assign

I/0 Channel

(SASSIGN)

Deassign

Establishes

a path

for

Establishes

a path

for

network operations

Releases linkage

I/0 Channel

(SDASSGN)

Releases a path

for

I/0

request

None

NETMBX privilege

an I/0 path

Access mode
'

from the network

NETMBX privilege

Queue I/0 Request

Initiates
an input or output operation

Access mode2

Queue I/0 Request

Initiates an input or output operation and

Access mode2

SINPUT

Initiates virtual input operation and waits

Access mode?

Initiates virtual output operation and waits

Access mode2

Performs ASCII string substitution,

None

($QIO)

and Wait for
Flag ($SQIOW)

Event | causes the process to wait until it is
complete before continuing execution
for

SOUTPUT

completion

for completion

Formatted ASCII

Qutput

(SFAO)

and converts numeric data to ASCII
representation and substitutes in

Formatted ASCII

output

Allocate Device

‘Reserves a device for exclusive use by a-

None

"Reserves a spooled device for exclusive use

ALLSPOOL privilege

Deallocate Device

Relinquishes exclusive use of a device

- Access mode

Get I/0 Channel
Information

Provides information about a device to which
an I/0 channel has been assigned

" Access mode
'

Qutput with List
Parameter ($FAOL)

(SALLOC)

($DALLOC)

process

and

its

subprocesses

(SGETCHN)

Get I1/0 Device
Information

Provides information about a physical device
'

‘

None

($GETDEV)

Cancel I/0
on Channel

Access mode

Cancels pending I/0O requests}on a channel

’

(SCANCEL)

For an explanation of the terms used in this column, see Page 1-3.
Depending on the specific nature of the

require

the

PHY IO,

LOG_IO,

direct I/0 (DIOLM), buffer space

MOUNT

input

privileges,

(BYTLM), or AST limit

output

request,

the

service

or quotas for buffered I/0

(ASTLM).

may

(BIOLM),

INTRODUCTION TO SYSTEM SERVICES
~ Table 1-4 (Cont.)
~Input/Output Services

Restriction(s)l

Function(s)

Service Name

Creates a temporary mailbox-

BYTLM/Quota

Channel
" (SCREMBX)

Creates a permanent mailbox

PRMMBX privilege

Delete Mailbox

‘Marks a permanent mailbox for deletion

Create Mailbox
and Assign

(SDELMBX)
Broadcast

TMPMBX privilege

Sends a high-priority message to an

PRMMBX privilege

Access mode
None

assigned terminal

(SBRDCST)

Sends a high-priority message to a
nonassigned terminal or to all

OPER privilege

Controls accounting log file activity

OPER privilege

Writes an arbitrary message to the

None

Requests symbiont manager to initialize,

OPER privilege

Requests symbiont manager to delete or

Group association

terminals

Send Message to
Accounting Manager
(SSNDACC)

accounting log file

SendlMessage to

Symbiont Manager
(SSNDSMB)

'~ Send Message

Operator.

(SSNDOPR)

modify, or delete a printer or
batch job queue, or a device queue

change characteristics of a queued file.
Writes a message to designated operator (s)
terminal (s)

None

’

'Enables or disables an opefator's terminal,
sends a reply to a user request oOr initializes

OPER privilege

Writes arbitrary data to the system error

BUGCHK privilege

Returns text of systém error message from

None

Writes a message to the current output and

None

the operator's log file

Send Message
Error

Logger

(SSNDERR)

e
Get MessagG)
(SGETMS

Put Message

(SPUTMSG)

log

file

message file

error devices

e,gt .

n the terms used in this column, see Page 1l-3.
= For an explanatioof

INTRODUCTION TO SYSTEM SERVICES
1-5

Table

Process Control Services

Create Process
'

(SCREPRC)

Delete Process
(SDELPRC)

Suspend Process
(SSUSPND)

Restriction(s)l

Function(s)

Service Name

Creates a subprocess

PRCLM quota

Creates a detached process

DETACH privilege

Deletes the current process or a subprocess

None

Deletes another process in the same
group

GROUP privilege
Group association

Deletes any process in the system

WORLD privilege

Makes the current process or a subprocess
nonexecutable and unable to receive ASTs

None

Makes another process in the same group

GROUP privilege

a subsequent resume or

until

delete

request

nonexecutable and unablé to receive ASTs
subsequent

until

resume

delete

request

Makes any process in the system nonexecutable
and noninterruptible until
resume

Resume Process
(SRESUME)

delete

request

Restores executability of a suspended process in | GROUP privilege
Group association
the same group

Restores executability of any suspended process

WORLD privilege

Makes the current process dormant but able to

None

the

system

receive ASTs until

a subsequent wakeup
:

request

Wake

(SWAKE)

Restores executability of the current

process or

a hibernating subprocess

Restores executability of a hibernating process
in

the

same

group

Restores executability of any hibernating

process

Schedule Wakeup
(SSCHDWK)
Cancel Wakeup
(SCANWAK)

WORLD privilege

a subsequent

Restores executability of a suspended subprocess | None

Hibernate ($HIBER)

Group association

in the

None

GROUP privilege

Group association

WORLD privilege

system

Wakes a process after a specified time

interval or at a specific time?2

Cancels a scheduled wakeup request2

Exit (SEXIT)

‘Terminates execution of an image and

None

Force Exit

Causes image exit for the current process

None

($FORCEX)

returns

to command

interpreter

subprocess

Causes

image exit for a process in the same

group

Causes image exit for any process in the.

WORLD privilege

Designates a routine to receive control

None

Cancels a previously established exit handling

Access mode

Establishes a text name string to be used

None

system

Declare Exit
Handler
(sDCLEXH)

Cancel Exit
Handler
(SCANEXH)

Set Process Name
(SSETPRN)

GROUP privilege
Group association

when

‘

image exits

routine

identify

the current process

For an explanation of the terms used in this column, see Page 1-3.
Functions performed by these services are listed in detail in Table 1-6.

INTRODUCTION TO SYSTEM SERVICES
Table 1-5 (Cont.)
Process Control Services

Service Name
Set Priority
(SSETPRI)

| Restriction(s)l

Function (s)

Increases the execution priority for

any

ALTPRI privilege

process

Changes the execution priority for the current

None

Changes the execution priority for a process
7
in the same group

GROUP privilege
Group association

process or

a subprocess

Changes the execution priority for any

process

the

WORLD privilege

system

Set Resource Wait | Requests wait, or that control be returned
immediately, when a system service call
Mode (SSETRWM)

None

cannot be executed because a system
resource is not available

Get Job/Process

SN
)

Information
(SGETJPI)

Returns information about the current

process

None

Returns information about the current context
of other processes in the same group

GROUP privilege
Group association’

Returns information about any other process in

WORLD privilege

the

‘

system

For an explanation of the terms used in this column, see Page 1-3.

INTRODUCTION

|
Tlmer

Service

Table

and Time

Name

SYSTEM

SERVICES

1-6

Convers1on

Serv1ces

Restriction(s)l

Function
(s)

Get Time

Returns the date and time in sYstem_

(SGETTIM)

None

format

Convert Binary Time|Converts a date and time from system
to Numeric Time
format to numeric integer values
(SNUMTIM)
'

None

Convert Binary Time|Converts a date and time

from system

None

ASCII String
(SASCTIM)

Convert

format

ASCII

Converts

String
to Binary
Time (S$SBINTIM)

Set

Timer

string

an ASCII
‘
a

date

the

and

string

time

system date

(SSETIMR)

Timer

ASCII

time

{format

Requests

setting

event

queueing of an AST based
or delta time value

Cancel

and

Cancels

previously

issued

flag
an

timer

TQELM quota

absolute

requests

‘Access mode

Request

(SCANTIM)

Schedule Wakeup
($SCHDWK)

Schedules a wakeup for
or

hlbernatlng

the current process

ASTLM quota

subprocess

Schedules a wakeup for a hibernating
process in the same group
'

Cancel Wakeup
(SCANWAK)

GROUP privilege
ASTLM quota
]
Group association

Schedules a wakeup for any hibernating

WORLD privilege

process

~ASTLM quota

the

system

Cancels a scheduled
the current process
subprocess

wakeup request for
or a hibernating

Cancels a scheduled wakeup
for a hibernating process

the

same

None

request

GROUP privilege
Group association

group

Cancels a scheduled
for any hibernating
the system

wakeup request
process in

WORLD privilege

For an explanation of the terms used in this column, see Page 1-3.

Setting an event flag in a common event flag cluster requires

number;

timer

request with

an AST

requires

ASTLM quota.

association

based

group

SYSTEM SERVICE DESCRIPTIONS

$SETPRT
4.64

S$SSETPRT - SET PROTECTION ON PAGES

The Set Protection On Pages system service allows
an image running
a

process

Macro

change

the

protection

on
a page

range

°"in

pages.

Format:

$SSETPRT

inadr

,[retadr]

High-Level Language

,[acmode]

,prot

, [prvprt]

Format:

‘SYSSSETPRT(inadr , [retadr] ,[acmode] ,prot ,[prvprt])
inadr

|
address

~virtual
changed.

2-longword

;

the

starting

and

protection
addresses

ending

is to be
are
the

1s changed.
Only the virtual page number
address is used;
the low-order 9 bits are
|
|

virtual

addresses

mode

2-longword

S
behalf

array

receive

the

pages

that

|
which

the

had

the
their

|
request

starting

and

ending

protection changed.
~
being

made.

The

specified
access mode
1is maximized with the access mode of the
caller.
The resultant access mode
must
be
equal
to
or
more
privileged
than
the
access
mode
of the owner of each page in

address

acmode
access

containing

addresses
of
the
pages
on
which
1If the starting and ending virtual

same, a
single
©page
portion
of the virtual
ignored.
retadr

|
array

order

to change

the protection.

prot

new protection specified in bits 0 through 3 in the format of the
hardware
page
protection.
The high-order 28 bits are ignored.
Symbolic names
defining
the
protection
<codes are
1listed
in
Appendix
A,
Section
A.5
"S$PRTDEF Hardware
Protection Code
Definitions.TM
|
|
|
|

If the protection is specified as 0, the protection
kernel

read-only.

defaults

prvprt
address of a byte to receive the protection
previously
assigned
to
the last page whose protection was changed. This argument is
‘useful only when protection
for a single page is being changed.

4-143

SYSTEM SERVICE DESCRIPTIONS
SSETPRT

SET

PROTECTION

PAGES

Return Status:
SS$_NORMAL
Service

successfully

completed.

SS$_ACCVIO

The input'addréss array cannot;be read,
or the outpfit'address

An attempt was made to change the protection of a nonexistent

array
or
the byte to receive
be written, by the caller.

page.

the previous protection cannot

SS$_EXQUOTA

The process exceeded its paging file quota while changing
in a read-only private section to a read/write page.
SS$_IVPROTECT

The

specified protection code has a numeric

greater than

15.

SS$_LENVIO

o
A page in the specified
control region.

SS$_NOPRIV

A page

value

1is

range

system address

end

page

o
|
range
is beyond

the
»

3
|
of the program or
R

the

specified

SS$_PAGOWNVIO
|
.
Page
owner
violation.
An
protection on a page owned by

the

space.

o
o
|
=
attempt
was
made
to <change
a more privileged access mode.

the

Privilege Restrictions:
For pages in global sections, the new protection can
alter only
the
accessibility of the page for modes less privileged than the
owner of the page.

Resources Required/Returned:
If a
process
changes any
read-only
to
read/write,
file quota (PGFLQUOTA).

pages
1in
the service
'

a
private
section ' from
uses the process's paging
SRR
D
,

Note:

If:an error occurs while changing page protection,
array,

requested,

changed before
affected,

both

the

indicates

error

1longwords

the pages

occurred.
in

that were

pages

the return address

~-1.

4-144

the

return

successfully

have

been

array contain
a

INTRODUCTION TO SYSTEM SERVICES
Table 1-7

Condition Handling Services

Set Exception

Vector
($SSETEXV)

Restriction(s)l

Function
(s)

Service Name

Defines condition handlers to

Access

Set System Service | Requests or disables generation of a software

None

Failure Exception

exception condition when a system service

Unwind from

Deletes a specified number of call frames

None

Designates a routine to receive control

- Access mode

Mode

(SSETSFM)

Condition Handler
Frame (SUNWIND)
Declare
Mode

Change

Compatibility

Mode Handler
(SDCLCMH)

call

returns

an error

severe error

from the call stack following a
nonrecoverable exception condition

when change mode

to user

instructions

are encountered

Designates a routine to receive control
when change mode to supervisor

Access mode

Designates a routine to receive control
when compatibility mode exceptions

None

s encountered
are
instruction

occur

mode

receive control in case of hardwareor software-detected exception conditions

For an explanation of the terms used in this column, see Page 1-3.

INTRODUCTION TO SYSTEM SERVICES
1-8

Table

Memory Management Services

Service Name

Restriction(s)l

Function
(s)

Expand Program/
Control Region
(SEXPREG)

Adds pages at the
control region

Contract Program/
Control Region
(SCNTREG)

Deletes pages from
control region

end

the

end

program or

the

program or

Create Virtual

Adds pages to the virtual address space
available

Delete Virtual

Makes a range of virtual addresses

Address

unavailable

Space

None
’

Address Space
(SCRETVA)

None

image

None

image

($SDELTVA)

Create and Map
Section
(SCRMPSC)

Identifies a disk file as a private section
and establishes correspondence between virtual
blocks in the file and the process's virtual
address space
'

Access

mode

Identifies

Access

mode

code

a disk

data

file

containing

temporary

shareable

global

section

and establishes correspondence between virtual
blocks in the file and the process's virtual
address

space

Identifies a disk file containing shareable
or data as a permanent global section
and establishes correspondence between virtual
blocks in the file and the process's virtual

code

address

Map Global

File Writes
global
file

Section

(SMGBLSC)

privilege
mode

space

Identifies a disk file containing shareable
code or data as a system global section and
establishes correspondence between virtual
blocks in the file and the process's virtual
address space

Update Section
on Disk
(SUPDSEC)

PRMGBL
Access

modified pages of a private
section into the section

Establishes

correspondence

section

and

between a global
virtual address

process's

SYSGBL

privilege

Access

mode

Access

mode

UIC

protection

space

Delete Global
Section (S$SDGBLSC)

Marks a permanent global section for deletion
Marks

from

Page

(SLCKPAG)
1

For

for

deletion

that particular pages cannot be
of the process's working set

Allows previously locked
out of working set

from

(SPURGWS)

Lock

section

pages

paged

Removes all pages within a specified range

Purge Working
Set

system global

Specifies
paged out

Lock Pages in
Working Set
(SLKWSET)
Unlock Pages
Working Set
(SULWSET)

PRMGBL

Memory

the

current working

an explanation of

the

out

terms

privilege
mode

Access

mode

Access

mode

None

User privilege
Access mode

memory

used

SYSGBL
Access

set

Specifies that particular pages may not be
swapped

privilege

this column,

see Page

1-3.

INTRODUCTION TO

SYSTEM SERVICES

Table 1-8 (Cont.)
Memory Management Services

Service Name

Function (s)

Restriction(s)l

Unlock-Page in

Allows previously locked pages to be swapped

User privilege

Adjust Working Set
Limit (SADJWSL)

|Changes maximum number of pages that the
current process can have in its working set

WSQUOTA quota

Set Protection on
Pages (SSETPRT)

Controls access to a range of virtual
addresses
.
-

Access mode

Set Process Swap

Controls whether or not the current process

Memory

Mode

(SULKPAG)

($SSETSWM)

out of memory

can

swapped

out

the

balance

Access mode

PSWAPM privilege

set

For an explanation of the terms used in this column, see Page 1-3.

Table

1-9

Change Mode Services

Service Name

Function(s)

Restriction(s)l

Change to Executive|Executes a specified routine in executive

Mode

(SCMEXEC)

Change to Kernel
Mode

($CMKRNL)

Adjust Outer Mode
Stack

Pointer

mode

Executes a specified routine in kernel

mode

Modifies

the current stack pointer

less privileged

access mode

CMKRNL privilege

Access mode

for a

Access mode

(SADJSTK)

For

an explanation of

terms

used

this column,

CMEXEC privilege

Access mode

see Page

1-3.

CHAPTER 2
CALLING THE

SYSTEM

SERVICES

System service procedures are called
wusing
the
standard
VAX-11/780
procedure
calling
conventions.
The
programming
languages
that
generate VAX-11/780 native mode instructions
provide
mechanisms
for
coding = the procedure
calls.
These languages,
and
supporting
documentation, are listed in the Preface.

When you

arguments

<code
the

system

service

requires.

call,

you

When the service
completes
execution,
it
calling
program with a return status code.
the status code to determine the success or
call, so it can alt:r the flow of execution,

must

supply

whatever

returns
control
to
the
The caller should analyze
failure
of
the
service
if necessary.

This chapter provides all the information you need to

calls

If you are a VAX-11] MACRO programmer, you should read Section 2.1

for

system

services.

details
service

on
how
calls.

If you are a
Section
2.2
function

code

the macro

instructions
|

code
|

that generate

VAX-11
FORTRAN
1IV-PLUS
programmer,
you
for details on how to code subroutine CALL

references.

system

should
read
statements or

Each of these sections also discusses conventions for coding arguments
and methods of checking the successful completion of a system service.

CALLING

2.1

MACRO

THE

SYSTEM

SERVICES

CODING

System service macros generate argument lists and CALL instructions to
call
system services.
These macros are located in the system library

STARLET.MLB;
references

this

library

when you

assemble

searched
a

source

automatically

for

wunresolved

program.

Knowledge of MACRO rules for assembly language coding is required
for
understanding
the
material
presented
1in
this section.
The VAX-11
MACRO Language Reference Manual and
the
VAX-11
MACRO
User's
Guide
contalin the necessary prerequisite information.

2.1.1

Argument Lists

You can determine the arguments required by a system service from
the
service
description in Chapter 4.
The "Macro Format" for each system
service indicates the positional dependencies
and keyword
names
of
each argument as shown in the following sample:
SSERVICE
This

and

format

that

names
must

arga

,argb

indicates

requires

that

four

ARGA, ARGB, ARGC,
have the format:

,argc
the

,argd
macro

arguments,

and
|

ARGD.

name

ordered

The
|

the service

1is

SSERVICE

as shown and

with

keyword

argument
|

list

for

this
|

8 7

service

arga

argb

argc

argd

All arguments are longwords.
The first
1longword
in
the
1list
must
always
contain, in 1its low-order byte, the number of arguments in the
remainder of the list.
The remaining three bytes must be zeros.
Many

arguments
the
macro

system
formats

third arguments of
appear

services are optional;
these
by
brackets.
For example, if

SSERVICE

are

optional,

,[argb]

,[argc]

,argd

macro

indicated
the second and

format

would

as:

SSERVICE arga

If
you
omit
an
optional
argument
1in
instruction, the macro supplies a default

There

tha

are

two generic macro

Sname_G
Sname_S

forms

for

a
system
service
macro
value for the argument.

coding

calls

system

services:

CALLING THE SYSTEM SERVICES
MACRO

The

form

system

the

service

The

macro
1s

use

CODING

depends

how

the

argument

list

for

the

constructed:

$name G

form

requires you

to construct

argument

list

elsewhere in the program and spec1fy the address of this 1list
as

argument

create

this
form, you.
modifications
1if
the macro.

The

S$name_S
to

system

service.

1list

for

(A macro

each

can
use
the
same
necessary, for more

form requires you

system service

code

the

argument

in the macro

system

argument
than one
|

supply the

instruction.

push

provided

service.)

With

1list,
with
invocation of

arguments

the

The macro generates

the argument list onto
the
call
stack
during
execution.
With this form, you can use registers to
or to point
to arguments so you can write
re-entrant

program

contain

programs.

The

Sname_G macro

macro

form

according
services
registers

form generates

generates

CALLS

CALLG

instruction;

instruction.

The

the

services

are

Sname

called

to
the
standard
procedure
<calling
conventions.
System
save
all
registers except RO and Rl, and restore the saved
before returning control to the caller.
-

The following sections describe how to code system service calls using
each

2.1.2

The

these

macro

$name_G

Form

Sname
G macro

Sname_G

label

address

forms.

form

requires

single

operand:

label

You

can

the

use

$name

argument

$name

$name macro

label:

is:

argl,

macro

...

list.

create

the

argument

list.

The

format

,argn

label

symbolic

’

the

label

address of the generated
given as an argument in the

argument
list.
This
Sname_
G macro form.

1is

the

Sname
the

service macro

argl,...,argn
arguments
list.

name.
|

placed

successive

longwords

2.1.2.1
Specifying Arguments with the $name Macro
$hame
macro
to
construct an argument list for a
can specify the arguments in any of three ways:

By
be

using keywords
followed by an

argument.

the

,
argument.

- When you use
system service,

to describe the arguments.
equal sign (= ) and then by

the
you

A keyword
must
the value of the

CALLING THE SYSTEM SERVICES
MACRO CODING

In positional order,

~commas

optional

the

trailing

indicated

arguments

omitted

with

You can omit commas for

argument positions.

arguments.

and keyword names (you
3. Using both positional dependence
‘

list positional arguments first).

must

For example,vSSERVICE}may'have the"format:
arga

SSERVICE

Assume, for the purposes of this
ARGD

ARGA

example, that

and

ARGB

are

you to code numeric values and that ARGC and

require

that

arguments

,argd

,[argc]

,[argb]

require you to code addresses.

The two follow1ng examples show valid ways of coding a $name macro
construct an argument list for a later call to S$SSERVICE.

Using KeywordsJ

(Example l:

ARGR=0y ARGC=0y ARGA=1 s ARGI=MYARGD

$8EfFi'Uf[(le.f

LIST?

in Positional Order]
Specifying Arguments

IExample 2:

1y yyMYARGD

$SERVICE

LIST:

The argument list genefated in both cases 1is:
4

+ LONG

LIGT:

« LLONG

o LONG

+ LLONG

o LLONG

MYARGT

Note that all arguments, whether

keyword,

must

expressions

generate .LONG data directives.

coded

that

the
»

or
positional order

assembler
‘

can evaluate to
|

Example of $name and $name_G Macro Calls - This example shows
2.1.2.2
to the Read Event Flags (SREADEF) system
a call
code
can
how vyou
service using an argument list created by $name.

As shown in Chapter 4, the macro format of the $READEF system
SREADEF

efn

service

,state

The EFN argument must specify the number of an event flag cluster, and
argument must supply the address of a longword to receive
STATE
the
the contents of

the cluster.

These arguments might be specified

using

the

$name

macro

form

follows:

READLST!

$READEF EFN=1+8TATE=TESTFLAG

sARGUMENT LIST FOR $READIEF

This SREADEF Macro generates the code:
REATILST?: +LONG

SJ.ONG

]

LONG

TESTFLAG

sARGUMENT LLIST FOR $REANEF

CALLING

execute

the

SREADEF

THE

SYSTEM

MACRO

CODING

macro

now

SERVICES

requires

only

the

line:

call

the

Read

$READNEF
.G READLST

The

macro generates
service:

the

follow1ng

code

system

CALLG

Flags

entry point

2.1.2.3

\N,.,._/

] },/

form

Flags
-

RFAUIHI CE 3Y%$hFfiH+F

SYSSREADEF is the name of a vector to the

Event

system

service.

addresses

for

all

The

system

entry

linker

p01nt

automatically

services.

the

Read

resolves

the

Symbollc Names for Argument List Offsets - The $name_G

(used

with

the

$name

macro)

1is

especially

useful

macro

for:

Coding calls to system services that'have long argument lists

Services that

single

argument

may be

called

program,

with

repeatedly
the

same,

during

execution
the

same,

list

the

essent1ally

When you use this form,
you
can
symbolically.
Each
argument
1in
the

beginning

offset

the

list;

each
argument.
the arguments in a list, you
offset
(which
is
based on
macro format).

arguments

There

are

refer
to
arguments
in
the
1list
an argument list has an offset from
symbolic name is defined for the numeric

If you

do
the

two

use

the symbolic names to refer to
have
to remember
the
numeric
position of the argument shown in the

not

additional

advantages

referring

their

Your

code

If an argument list for a system service changes w1th
release of a system, the symbols will not change.

symbolic

names:

readable.

The offset names for all system service argument lists
concatenat1ng
the
service macro name with $_and the

the argument,

follows.

later

are
formed
keyword name

by
of

name$_keyword
where name is the
keyword argument.

macro

name

for

the

Slmllarly, the number of arguments
defined symbolically as:

system

required

service

and

keyword

partlcular

the

macro

1is

‘name$_NARGS
Symbolic
whenever

names
you

for argument
use

service.
For

example,

Symbolic

the

S$name

list
form

SREADEF macro

Name

READEFS$_NARGS
READEFS$_EFN
READEF$_STATE

offsets
are
of the macro

defines

the

defined
automatlcally
for a partlcular system

following

values:

Value

Number
Offset

of
of

arguments in
EFN argument

Offset

STATE

the
(4)

argument

list

(8)

(2)

CALLING THE SYSTEM SERVICES
MACRO

CODING

SREADEF system service call as follows:

FFN=1+STATE=TESTI

CERFATEF

REATNLLST @

value

for

TESTl

Later, the program may want to use a different

the service.

calling

argument

can be accomplished.

G READLST
SREATEF

replaces

The MOVAL instruction

address

the

with the address TEST2;

list

system service with the modified list.

2.1.2.4

STATE

the

The following lines show how this

STATE
TEST2y READLSTHREATEFS

MOVAL

argument

for

Thus, the SREADEF macro can be coded to build an argument list

the

$READEF

the SREADEF_G macro calls the

names

The $nameDEF Macro - You can also define symbolic

for

This macro
system service argument lists using the SnameDEF macro.
it merely defines the symbolic
does not generate any executable code;
For example:

names so they can be used later in the program.
$QTONEF

This macro defines the symbol QIO$ NARGS and symbolic
|

SQIO argument list offsets.

names

for the

You may need to use the $nameDEF macro if you code an argument list to
a system service without using the $name macro form, or if a program
refers to an argument list in a separately assembled module.

The $name_S Form

2.1.3

S macro call
The format of $name
S
$name_

argl,

...,

is:

argn

on the stack in reverse
The macro generates code to push the arguments
order.

The

instructions

actual

stack are determined as follows:

If the system service

either
is

used to place the arguments on the

requires

value

for

PUSHL instruction or a MOVZIWL to - (SP)

argument,

instruction

generated.

If the system service requires an address for an argument,

PUSHAB,

depending

PUSHAW,
on

the

is generated,
PUSHAL, or PUSHAQ instruction

context.

The -macro then generates a call to the system service 1in the format:
CALLS #n,@#SYSS$name

where n is the number of arguments on the stack.

CALLING THE SYSTEM SERVICES
CODING

MACRO

2.1.3.1

Specifying Arguments with

the

$name
S

Macro - When

you

use

the
S$name
S macro to construct an argument list for a system service,
you can specify arguments in any of three ways:
|
1.

By using keywords to describe
the
arguments.
All
keywords
followed by an equal sign (=) and then by the value
be
must

In positional order,

using

(positional

example,

for

arguments

ARGD

arga

omitted

positional

arguments must be

,[argb]

code

arguments

dependence
listed

indicated

You can omit commas for
|
and

first).

keyword

names

format:

,argd

example,

that

ARGA

and

ARGB

are

you to code numeric values and that ARGC and

require

you

the

,[argc]

the purposes of this

that

require

both

SSERVICE might have

SSERVICE

Assume,

with

argument positions.
the
1in
commas
optional trailing arguments.

3.
For

argument.

the

addresses.

The two following examples show valid ways of coding the $name_S macro
form

S$SERVICE.

call

Example l:

Using Keywords

MYARGI:

« BLKUW

*
.

$SERVICE.S ARGE=#0sARGC=0s ARGA=%1y ARGI=MYARGI

(Example 2:
MYARGD:

Specifying Arguments in Positional OrderJ

LONG

[]

$SERVICE.S #1y»sMYARGD

The argument list is pushed on the stack as follows:
FUSHAW

MYARGID

FLUSHIL.

#0O
0

FUSHL.

Note that all arguments, whether coded positionally or with
keywords,
must
be
valid
assembler
expressions, since they are used as source
operands in instructions.
Contrast this with the
arguments
for
the
Sname
argument
list,
which
the
assembler uses for data-generating
directives.

CALLING THE SYSTEM SERVICES
MACRO

2.1.3.2

Example of

constructs

S$name_
S

CODING

Macro

Call

Since

S$name_

macro

the argument list at execution time, addresses
and values

can be supplied using register addressing modes.
The SREADEF macro
used
in the example of the $name_ G form can be coded as follows u51ng
the Sname

form.

$RFAHPF S

EFN=#15TATE= (R10)

where R10 contains
the address of the longword to receive
of

the

flags.

status

This macro instruction is expanded as follows:
LISth

(R10)

FLISHI.

CALLS

2y BRESYSHSREADEF

2.1.4
The
for

_Conventions for Coding Arguments to System Services

arguments must
operand coding

be specified according
and addressing.

the macro

assembler

rules

The way'tovspecify a partlcular argumenf depends on: .
@

Whether the system service requires an address or a
value
as
the argument.
In Chapter 4, the descriptions of the arguments
following a system service macro format always
state
whether

the argument is an address or a value.

e¢

The

form

the

system

service

macro being

used.

The

expansions
of the $name and Sname S macros in the examples in
the preceding sections. showed the code generated by each macro
form.

you

are

in doubt

to whether

you have

argument
correctly,
you
can assemble
directive
to check the macro expansion.
Reference Manual for more details.

coded

value

Arguments that are optional to system
services
always
values, regardless of whether they are value or address
almost every case, an optional argument defaults
to 0.

When an argument 1s optional, the description of the
describes
used.

what

action

the

service

Address arguments may be optional

information;
1if the program does
omit the optlonal argument.
,

an address

the program with the .LIST MEB
See the VAX-1l1l MACRO Language

takes when

have default
arguments. 1In

argument always

the default

value

when

the

not requ1re

system
the

service

information,
|

returns

you

can

CALLING

THE

SYSTEM

MACRO

CODING

2.1.4.1
Conventions
for Coding
system services require ASCII text

SERVICES

Character
String
Arguments
name strings as arguments or

- Many
return

ASCII text name strings.
Character strings are identified
to
services
by
specifying
the
address
of a gquadword character
descriptor that has the format:
|
|
|
R

system
string

16 15

length

address'

length

is a word specifying the length of the string (in bytes).

address

is a longword contalnlng the address of the strlng

When

service

returns

character

string,

you must

supply

of
a quadword
character string descriptor that describes
and address
of an output
buffer
into
which
the string

written.
Optionally,
you can
to receive the actual length of

'Example'of

Coding

supply the
the string

Character

address of
returned

String Descriptor:

Logical
Name
(STRNLOG)
system
service uses
descriptors for both input and output:
it accepts a
input
and returns the equivalence name, if any, for

The following
translate the

example
logical

CYGNUSTIESE
o LLONG
10%3
20% 2

o L.ONG

10O%
ZCYGNUSY

R
3

The Translate

ATINRESS OF
STRING

THE

STRING
:

STESCRIFTOR

FOR

TRANSLATED

s THE

40% 30 %

s ILENGTH

« LONG

J04%

s ANNRESS

« BLKR

sNESCRTFTOR FOR CYGNUS LOGICAL NAME
LENGTH OF THE STRING
|

+ LLONG

404

coded

bits)
‘

character
string
logical name
for
the logical name.

NAMEDESC:

J0% 2

204$~-10%

address

the length
is to be

word (16

shows how these descriptors mlght
name CYGNUS.
.

LASCTT
.

the

THE

‘

OQUTFUT

RUFFER

THE

s THE RUFFER

RUFFER

NAMELENGTH?
+ BLLKW

sRECETVE

OUTHFUT

LENGTH

HERE

beRNI NG.S

LOGNAM=CYGNUSTIESC e

RGLLEN=NAMELENGTH
¢~

RELEBUF=NAMETESE

The

input string for

this

service“

call

1is

defined

the

1label

CYGNUSDESC.
The output string that is returned from the service will
be written into the 63-byte buffer defined in the
descriptor
at
the
label
NAMEDESC.
The
written in the word at

When an
string

output buffer
returned
1is

truncated,
(Status

2.1.5.)

and

codes

the

actual
length
of ‘the
the label NAMELENGTH.

returned

strlng

w1ll

1is provided for
a
character string,
and
the
1longer
than
the buffer, the string returned is

service

returned

returns a status code

system

services

are

indicating
discussed

that
in

fact.

Section

CALLING

THE

SYSTEM

MACRO

SERVICES

CODING

A Macro to Create Character String Descriptors: ‘Because
services
macro to

+MACRO

TIESCRIFTOR

LARELLS:
-

many‘

system

use
character
string
descriptors, you may want to write
create them.
The following example shows such a macro:

TEXT s PLARBEL L » PLAREL 2

e LLONG

L.AREL
2L AREL1

« LONG

LAREL1

+ASCYIY

/TEXT/

LARELZ:

JENDM

DESCRIFTOR

If this macro were
string
descriptor
follows:

used
for

in the example above to create
the
character
the
input
name CYGNUS, it might be coded as

CYGNUSTESC?:

DESCRIFTOR

Note that this macro,
Chapter
3
whenever
input.

<CYGNUS:

named DESCRIPTOR, is
a
character
string

used
in
the
descriptor is

examples
required

1in
for

2.1.4.2
Conventions for Coding Numeric Values - Many system
services
accept
numeric
values
for particular arguments.
In some cases, the
services check only the low-order portion
of
the
1longword
argument
they are passed.
These cases are:

Indicators.
System

Indicators can only

services

check

only

have

the

values

low-order

bit

these

‘arguments.

Event flag numbers.
through

255.

arguments.

these

Event flag numbers can have values of

System

services

check

only

the

low-order

byte

Access modes.
Access modes can have values of 0
through 3.
System services
check
only
the
low-order 2 bits of these
arguments.

When you code any of the

argument,

Note that many system services
resources,
and
thus
employ

use
access
a
special

modes
to
convention

access mode
mode
using

ACMODE).
You
or a symbolic

portion

their

the

argument

arguments (keyword
a
numeric
value

numeric

values,

Access
Mode

and

types

zeros.

symbolic

Numeric
Value

Kernel

The

above

should

names

Symbolic
Name
PSLSC

KERNEL

PSL$C_EXEC

Supervisor
User

2
3

PSLSC_SUPER
PSLSC_USER

symbolic

names

are

defined

in the

high-order

protect
system
for interpreting

can
specify
an
name.
The access

are:

Executive

the

SPSLDEF macro.

access
modes,

CALLING THE SYSTEM SERVICES
MACRO

CODING

Wwhen you specify an access mode the actual mode used is determined
after the service has compared the specified access mode with the
If the modes are
access mode from which the service was called.
less

the

different,

privileged access mode is always used.

Because

numeric value
this operation results in an access mode with a higher
(when the access mode of the caller is different from the specified

access mode), the access modes are said to be maximized.

can
you
mode,
Since much of the code you write will execute in user
and
0,
to
defaults
value
argument
The
argument.
mode
omit the access
when this value is compared with the current execution mode, the mode
3 for user mode, is used.
with the higher value,

Status Codes Returned from System Services

2.1.5

When a system service finishes execution, a numeric status value is
Successful completion 1is
always returned 1in general register RO.

low-order
The
indicated by a status code with the low-order bit set.
error.
the
of
severity
the
represent
together,
taken
three bits,
Severity code values ares:

Meaning

Value
0

Warning

Success

Error

Informational
Severe or fatal
Reserved

3
4
5-7

The remaining bits in
return condition.

issued

this

error

the low-order

word

classify

the

particular

The high-order word indicates that a system service

status code.

Each numeric status code has a unique symbolic name in the format:
SS$_code

where code
example,

mnemonic

describing

the

a successful return is indicated by

return

condition.

For

SS$_NORMAL
An example of an error return status code is:
SS$_ACCVIO

This status code indicates that an access violation occurred because a
service could not read an input field or write an output field.

You can obtain the symbolic definitions for status codes

assembly

Use the symbolic names for
the system macro $SSDEF.
by coding
‘time
the numeric
because
system status codes to check return conditions,
values for status codes may change with a later release of the system.

2.1.5.1 Information Provided by Status Codes - Status codes»'returhed

that is, they do not
information,
services may provide
system
by
completed
service
the
not
or
1indicate whether
Jjust
always
SS$ NORMAL is the usual status code indicating success,
"successfully.
For example, the status code SSS_BUFFEROVF,
but others are defined.

2-11

CALLING THE SYSTEM SERVICES
MACRO

which
longer

This

CODING

1is
returned
when
a character string returned
by a service
1is
than the buffer provided
to receive
it,
is a
success
code.

status

code,

however,

Warning returns, and some
have performed some part,

gives

the

program additional

information.

error returns, indicate that the service
but not all, of the requested function.

may

The

possible status codes that each service can return
are
described
the
individual service descriptions in Chapter 4.
When you are
coding calls to system services, read the descriptions of
the
return

with

status

codes

particular

determine

return

whether

you

want

the

conditions.

program

check

for

2.1.5.2
Testing
Return Status
Codes - To
test
for
successful
completion
following
a system service call, the program can test the
low-order bit of RO and branch
to an error checking
routine
if
this

bit

not

set,

RL.EBC

checking

specific

severity

for

sERROR

routine

levels.
illegal event

CMFW
Note

ROserrlabel

The error
checks

follows:

may

check

For
flag

return

for

RBIT ClLEAR

specific

values

the following

number error

condition:

for

instruction

$1S EVENT FLAG NUMRER TLLEGAL®

status

codes

the
high-order
services are always the

are

always

words

all

same,

you

need

only

Status

longword

status

values;

codes

check

however,

returned

by system
low-order word.

the

2.1.5.3
a

System Messages

program

contents

with
The

with

10%2

issue

RLEC

command

RUN,

a descriptive

shows

simple

message

error

When

R0r10$

sEXTT

the program

checking

the

completes

procedure:

RETLIRN

WITH

system
service <call,
the
ERROR.
The subroutine checks
the bit is clear, branches to a

subroutine

STATUS

BSBW
the

instruction
«calls
the
low-order bit in register
instruction
that °causes

and if
RET
the
program
to exit with the status
of RO preserved.
subroutine issues an RSB to return to the main program.

If the event flag cluster requested in this call
available

interpreter

execute
uses

yOCHECK REGISTER ©

RET

currently

you

interpreter

EFN=%64sSTATE=TEST

FSUCCESSy

Codes

command

ERROR

RSR

Following

the

status.

example

SREADNEF
.S

BRSRW

Generated

DCL

nonsuccessful

following

ERROR:

the

since

LOW

example,

1584 TLLEFCyRO

that

displays

the

process,

the

the message:

program

Otherwise
the
,
|

$READEF

exits

and

the

not

command

AOGYSTEM~F~UNASEFC v ufiafifimciat@d event flag cluster
The

keyword UNASEFC

SS$ UNASEFC.

in the message
|

corresponds
|

the
.

status

-c

code

CALLING THE SYSTEM SERVICES
MACRO

2.1.5.4

Conditions - Two

Return

Special

CODING

modes

process execution

affect how control 1is returned to the calling program when an error
|
occurs during the execution of a system service. These modes are:
o

Resource walt mode

‘o

System service failure exception mode

If you change the default setting for either of these modes 1n a
the program must handle the special return conditions that
program,
result. The next two sections discuss considerations for using these
-

modes.

Many system services require certaln system
Resource Wait Mode:
These resources include system dynamic
resources for execution.
Normally, when a system
memory and process quotas for I/O operations.

service

called and

required

resource

1is not available, the

a wait state until the resource becomes
This mode is
service completes execution.

process 1s placed in
the
Then,
available.

called resource wait mode.

However, in a time-critical environment, it may not

practical

1in these cases, you can choose to
desirable for a program to wait:
when a required resource 1is
+that
so
mode,
disable resource wait
unavailable, control returns immediately to the calling program with
resource wait
an error status code. You can disable (and re-enable)
mode with the Set Resource Wait Mode ($SETRWM)

system service.

How a program responds to the unavailability of a resource depends
very much on the application and the particular service that is being
the program may be able to continue
1In some instances,
called.
1In other instances, it
execution and retry the service call later.
may be necessary only to note that the program is being required to
|

walt.

When an

System Service Failure Excéption Mode:
the

execution

;

call.

code

error

occurs

during

the

return

to the
system service, control normally returns

next instruction in the calling program, which can

status

check

e success or failure of the service
the
in RO to determin
o
.

To detect and respond to system service call failures, you can use the
condition handling mechanism of VAX/VMS to respond to system service
a software exception condition
failures. Then, when an error occurs,
is generated, and control is passed to a condition handling routine.

This mode is called system service failure exception mode, and can be
(and disabled) with the Set System Service Failure Exception
enabled
Mode

($SETSFM) system service.

For example:

$$ETSFM@S’ENBFLG$#1

'This call enables the generation of exceptions when errors

errors

occur during execution of a system service
|

generated for warning returns).

severe

(exceptions are not

If you code a program to execute with this mode enabled, you can code
on condition handlers is
Information
a condition handling routine.

no
If
Services."
"Condition Handling
3.7,
in Section
provided
e exception occurs, and the
when an
routine is availabl
user-specified

the default ~condition
program was run with the DCL command RUN,
program to exit and displays descriptive
the
causes
handler
information about the exception condition.
2-13

CALLING

2.2

FORTRAN

If you
system

The

SYSTEM

A function reference

subroutine

CALL

programmer, you can code calls
FORTRAN language constructs:

statement

you

choose depends on whether you want the program to check
status
value
following
the
completion
of the system

return

service.

SERVICES

CODING

are a VAX-11l FORTRAN IV-PLUS
services using either of two

method

the

THE

check
for
success or

you

use

function

reference,
you can

specific values on return
failure of the request.

from

the

have

service

the

program

determine

the

The use of each of these methods is discussed in this section.
Knowledge

'is

VAX-1ll

required

The

VAX-1l

FORTRAN

for

FORTRAN

IV-PLUS

understanding

FORTRAN

IV-PLUS

IV-PLUS
User's

rules

for

FORTRAN

the material presented

Language
Guide

Reference

<contain

Manual

the

language

in this
and

necessary

coding

section.

the

VAX-11

prerequisite

information.

2.2.1

The Format for Calling System Services

You

can determine the arguments required by a system service from
the
service description in Chapter 4.
The "High Level Language Format" in

each system service description indicates
positional dependencies of its arguments.

SYSSSERVICE
-

(arga ,argb ,argc

,argd

the
For

service
example:

name

and

the

,arge)

This sample format indicates that the name of the service is $SERVICE,
and
that
1its procedure name is SYSSSERVICE.
SYSSSERVICE is the name
~0of a vector to the procedure that executes
the service;
the
entry
point
addresses for all system services are automatically resolved by

the

linker.

The

format

also

indicates

that

code

the

arguments

‘must
use

commas

Many

arguments

separate
to

the

system

$SERVICE requires

parentheses

five

following

the

arguments.

You

procedure

name,

arguments.

services

are

optional;

these

are

1indicated

in
the
format by brackets ([]).
For example, if the third and
arguments of $SERVICE are optional, the format would appear as:

SYSSSERVICE
If

you

the
is

could

omit

(arga ,argb

optional

absence

shown

above,

code

the

either

argument,

argument.

and

,[argc]

you

the

you

For

choose

,argd

fifth

,[arge])

musté;nclude a comma to

indicate

examplé,
if the format of

SSERVICE

omit the

optional

arguments,

vyou

following:

AEQLL SY&%mamm(arfiavarfihvyarfidv)

FEUBROUTINE CALL

inteder. . variahle=8YSSname(ardarardhyvaraddy )

'FUN(TTHN

Note

that

comma

tralllng

argument.

When

omit

value

you

required

optional

indicate

argument,

the

of_O.
2-14

the

absence

compiler

REFERENCE

each

supplies

optlonal

default

CALLING THE SYSTEM SERVICES
FORTRAN

.
|

CODING

2.2.1.1 Example of a Subroutine CALL - The following example
shows
how the Read Event Flags (SREADEF) system service might be called from

a FORTRAN program.

The

format

the

SYSSREADEF

SREADEF

(efn

system

service

shown

argument
must
of the flags in

These arguments
follows:

in Chapter

is:

,state)

The EFN argument must Specify the number of
STATE
status

might

supply the address
the cluster.

specified

INTEGERX4 TSTFLG

event

flag

variable

and

receive

the
the

subroutine

CALL

statement
|

I RECETVE STATLIS FROM READNEF

CALL
e

)

This

SYS$SREADEF
(ZVAL CL)»TSTFLGY

statement

requests

the

status

CALL

READ

EVENT

the

event

flag cluster 0 be returned in the variable TSTFLG.

The use of the %VAL
as
INTEGER*4 are
system services
1in

2.2.1.2

Example
reference,
you

service

correct

format.

name

Using the
preceding

can

FORTRAN

2.2.2,

Function

assign

INTEGER*4

same

FLAGS

flags

event

built-in function, and the
programming considerations

discussed
1in Section
System Services".

«\?’{‘,J

that

program.

"Conventions
|

for

Coding Arguments
|

Reference - When
vyou
use
a
function
the
return status value from the system

variable.

the

declaration
of
TSTFLG
for coding arguments to
These
considerations
are

You must also declare

function

value

the

_service

returned will be

arguments of the SREADEF system service
a function reference might be coded

example,

in the

shown in
follows:

the

INTEGERX4 TSTFLG»SYSSREADEFTCODE | QUTFUT AND STATUS OF READEF

’

TCONE = SYSSREATEF
(ZVAL (1) TSTFIL.GY | READ THE FILAGS
Again,

the variable

the

cluster.

INTEGER*4

TSTFLG

The

function

system

is declared
service

(external

receive

function

the

status

SYSSREADEF

reference)

For additional examples of function
references,
"Status Codes Returned from System Services."

flags

declared

see

Section

2.2.3,

CALLING THE SYSTEM SERVICES
FORTRAN

CODING

Conventions for COding Arguments to System Services

2.2.2

Arguments that
or

declared

are

expressed

variables

constants

must be

specified according to the VAX-11 FORTRAN IV-PLUS syntax
|

rules.

The way to specify a particular argument depends on:
®

Whether the service requlres an address or

(if the

The data type of the argument
address of

the

argument)

the

requires

the

a value

argument

service

format
The descriptions of the arguments following the system service
If the description does
always state whether an address is required.
not say "address," you must prov1de a value.

to
familiar
be
The argument descriptions contain terms that may not
Table 2-1 lists the terms that are used
you as a FORTRAN programmer.
in Chapter 4 to describe arguments and 1llustrates how these arguments
can

coded

a FORTRAN

program.

The following sectlons prov1de addltlonal detalls on value and address
argumencs.

CALLING

THE SYSTEM SERVICES

CODING

FORTRAN

Table 2-1

FORTRAN

Argum ents

Valid

for

Specifications

and

System

Services

Declarations

Argument

Type

Constant

byte

}

Variable

SyYS$name ($VAL (10) )

value

byte

SYS$name (10)

address

value

ABC

SYS$name (ABC+10)

ABC

INTEGER*2

DEF

INTEGER*2

SYS$name ($VAL (1234))

DEF

SYS$name (40000)
-

DEF

INTEGER*2

DEF

GHI

LOGICAL*4

SYSSname(%VAL(GHI+1234))

INTEGER*4

GHI

INTEGER*4

LOGICAL*4

SYS$nameKGHI+4000O)

SYSSname (JKL)
SYSSname ('ALPHA')

CHARACTER*15

For input

.
GHI

JKL (2)

EXTERNAL

NAME-

CHARACTER*15

arguments,

you

must

can
use

use

constants,

variables.

PROGA

variables,

NAME

SYSSname (NAME//'.DAT')

PROGA

SUBROUTINE

output

GHI

SYS$Sname (PROGA)

For

GHI

INTEGER*4

routine

Note:

DEF

SYS$name ($VAL (GHI) )

SYSSname (NAME)
mask

DEF

INTEGER*4 GHI

SYS$Sname (GHI)

character string
~descriptor

LOGICAL*2

INTEGER*4 GHI

LOGICAL*4

quadword
(64-bit value
2-longword array

SYS$Sname ($VAL (DEF+1234))

SYS$name (DEF+1234)

DEF

LOGICAL*ZADEF:

LOGICAL*4

longword
address

SYS$name (DEF)
-

ABC

SYS$name (ABC+10)

LOGICAL*2

value

SYSSname (ABC)

longword

LOGICAL*1

SYS$name (¥VAL (DEF) )

address

ABC

BYTE ABC

LOGICAL*Z

SYS$name (1234)

SYS$na
($VAL (ABC+10))
me

word

LOGICAL*1

SYS$name ($VAL (ABC) )

SYS$name ($VAL (1234))

BYTE ABC

LOGICAL*1

word

Expression’

BYTE ABC
LOGICAL*1

~entry

(Examples)

Oor expressions.

CALLING THE SYSTEM SERVICES
FORTRAN CODING

2.2.2.1

enclosing
the

Value Arguments - All value arguments must
the

indicated

value expression within the built-in function %VAL,

by
in

format:

%VAL(value_expression)

Values can be expressed as constants,
"
the following examples:
Argument

variables,

or expressions,
|

in
|

Meaning

$VAL (1234)

Constant wvalue

INTEGER*4 ABC

Declare variable

$VAL (ABC)

Use current value of variable

$VAL (ABC+1234)

Use current value of variable plus constant

Some arguments are designated in the service descriptions as:
Indicators

Access modes

Indicators are arguments
You
can
specify
these
however, system services

Access modes are used
protection;

that can have only one of two values, 0 or 1.
arguments as byte, word, or longword values;
check only the low-order bit of the argument.

the‘ operating

they can have

Access

Mode
Kernel

Executive
Supervisor
User

the

following

system

values:

provide

memory

Value
wWwMhHCO

The values can
be
specified
as
byte,
word,
or
1longword
values;
however,
system
services
check only
the low-order 2 bits
of these
arguments.
You can omit the access mode
argument
when
you
code
a
system
service
«call.
For
more
details
on
how system
services
interpret this argument, see Section 2.1.4.2, "Conventions for
Coding
Numeric Values."

2.2.2.2
Address Arguments - System services may require addresses
to
refer
to
either
input
values
or
output variables.
When you code

address arguments, you must consider how the
argument
is
wused
(for
input
or
output) and
the
data
type (that
1is, the length of the
argument) that is required.
Table 2-1 summarizes the data types
that
' system services can require and gives examples of valid coding.

2.2.2.3

Input Address Arguments - For input

address

arguments

that

refer
to
byte, word,
or
longword
values,
you
can supply either
constant values, variable names, or expressions in the system
service
call.

CALLING

THE

SYSTEM

FORTRAN

In all cases, if you
variable
data
type

supply a variable
must
be
equal
as follows:
|

‘required,

SERVICES

CODING

name
for
the
argument,
to or larger than the data
|

If a byte is required, use BYTE, INTEGER*2,
or INTEGER*4

If a word is required, use INTEGER*2 or INTEGER*4

longword

required,

use

INTEGER*4

If the address refers to a quadword

(64-bit)

must declare

array.

a properly dimensioned

When a service requires
"address
example:

EXTERNAL

This

"address

you must declare

YOU

entry

external
»

mask,"

the

procedure.

For

the

procedure

PROGA

for

input

argument

a .
;

serv1ce.

2.2.2.4
is

the

or 2-longword array,

FROGA

statement defines

system

must

routine,"

the
type

Output Address Arguments - For output address arguments,

declare

allocated

variable

for

the

receive

the

value

returned,

that

yeu

storage

output.

When a value is returned, you must declare a variable of the
required
length
to
receive
the
value.
For example, the Get Time (SGETTIM)
system service returns a quadword blnary time value.
You can
code
a
call to this service as follows:

INTEGERX4 SYSTIM(D)
+
¢

CALL SYS$GETTIM(SYSTTM)

2.2.2.5
system

Conventions for
Coding
Character
String
Arguments - Many
services require ASCII text name strings as input arguments or

return ASCII strings.
~argument in Chapter 4

For these arguments,
refers to a "character

the
description
of
string descriptor."

the

When a system service requires
the
address
of
a
character
string
descriptor for
an
input
argument,
vyou can code either a character
~constant in the system service call or you can provide the name
of
a
variable
that
has
been declared
as CHARACTER.
The VAX-11 FORTRAN
IV-PLUS

compiler

automatically

descriptor required

for the

generates

the

character

argument.

When

a system service requires
the
address
of
a
character
descriptor
to return a character string, you must provide the
a variable that has been declared as CHARACTER to receive the

Optionally,
receivethe

you
can
length of
Ry

.supply
the
name
of
the strlng returned.

string

INTEGER*2

|
string
name of
string.

variable

to
L

- CALLING

THE

SYSTEM

FORTRAN

Example

Coding

Character

String

SERVICES

CODING

Arguments:

The

Translate

Logical

Name
(STRNLOG)
system
service
requires
the addresses of character
string descriptors for both input and output arguments:
it accepts
a
logical
name
for
input and returns the equivalence name, if any, of
the logical name.
These
arguments
might
be
coded
as
follows
to
translate the logical name CYGNUS.
CHARACTERX63
INTEGERX2

CYGNAM

FRUFFER

CYGLEN

PHEET

DESCRTPFTOR

LENGTH

CAlL SYS$TRNLUBC’CYGNUS’?flYGLENgfiYGNfiM?pé)

system

service

completes,

variable

characters

the

places

the

and

places

the

name

string)

CYGNAM,

equivalence

2.2.2.6

Default Values for Optional

optional

they

value

are

system

services

or address

always

equivalence

is coded
aS"a
When the S$TRNLOG

name

length
the

string

(the

variable

to 0,

regardless

arguments.

the

number

CYGLEN.

Arguments- Arguments

default

TRANSILATE

'TthHIATF PYGNUC

In the above example, the input logical name, CYGNUS
character
constant
1in
the
system
service
<call.

character

FOR

HERE

that
of

are

whether

When an argument 1s optional, its description
always indicates what
action
the
service
takes
when
the default value
is used.
Address
arguments
are often
optional
when
the
system
service
returns
information;
if the program does
‘omit the optional argument.

not

requlre

Remember that you must always indicate
argument

2.2.3

entering

Status

Codes

comma.

Returned

from

the

1nformatlon,

ebsence
’

you

can

optional

System Services

When you code a system service call using a function call statement, a
status
code
from
the
system ‘service
is
returned as an INTEGER*4
function value.
The
low-order bit
of
this
10ngword'
indicates
successful or nonsuccessful completlon of the service.
|
The
the

low—order threenblts,
error.
Severity code

‘Value

represent

the

severity

Severity Level
Success
Error

Informational
Severe,

-7.

fatal,

Error

Reserved

The remaining bits‘classify the particular return condition,
‘operating

Warning

wdhhHO
Ok

taken together,
values are:

system component

that

issued

the

status

code.

and
o

the

CALLING
THE SYSTEM SERVICES
FORTRAN CODING

Each numeric status code has a symbolic name.in the format:
SSS_code.
where code
1s
a
mnemonic
describing
the
by:
a successful return is indicated
example,

return

condition.
.

For
.

SS$_NORMAL

An example of an error status code is:
SS$_ACCVIO

This status code indicates that
a service

<could

argument or write an output argument.

2.2.3.1

not

read

Information Provided by Status Codes - Status codes

1input

returnéd

by
system
services
may
provide
information;. that is, they do not
always Jjust 1indicate
whether = or
not
the
service
completed
‘successfully. SS$ NORMAL is the usual status code indicating success,
but others are defined.
For example, the status
code
SS$ BUFFEROVF,
which
is
returned
when
a character string returned by
a service 1is
‘longer than the buffer provided to receive it, is a
successful
code.
This
status
code,
however,
gives the program more information than

)

that provided by SS$_NORMAL.

Warning:returns, and some error returns, indicate that the service may
have performed some part, but not all, of the requested function.
The possible status codes that each service can return
are
described
‘with the
individual service descriptions
in Chapter 4.
When you are

)

coding calls to system services, read the descriptions of

the return

2.2.3.2

call

status
codes
to
determine whether you want the program to check
|
particular return conditions.

Testing Return Status Codes - When

you

code

for

system service using a function reference, you can follow the service
call with a logical test on the function value defined for the service
call,
where TRUE
indicates
successful
completion.
For example, a
SREADEF statement may be coded:
»
|

INTEGERX4 SYS$READEF
y TETFLGe T
I

! TD TEST REANEF SUCCESS

SYS$READEF (ZVAL.C1)» TSTFILG)

(.NOT.

GOTO 20000

Call,

ERROR

READEF AS FLUNCTION

TF FALSE

In the above example, the variable I is tested following the
call
to
the
SREADEF system 'service.
If
a nonsuccessful
status code 1is
returned, the program branches;
otherwise, it continues execution.

These statements may also be combinéd, for examplé:
INTEGERX4 8Y$$REAHEFyTSTFhG

’

FOTO TEST READEF SUCCESS

+
| J

IF C(.NOT. SYSSREATEF (ZVAL (1) s TSTFLGY) GOTD 90000
I

);

T PR

(! ,‘f\q’ H : 'g N gfi

o~ 7

L, e

A %"F

’

“'x"fl 5::“ 6{

2-21

@c‘”g W

‘\f -

ERROR

READEF

FATLS

CTT

]

(A, Wwepja%bz/. ,£:>

CALLING THE SYSTEM SERVICES
FORTRAN CODING
~

errors
particular
You can also code calls to services that check for
or, you may want to provide a GOTO
the function reference;
following

statement (as in the above examples)

checks

specific errors.

for

to branch

that

procedure

particular

The following example illustrates a program checking for a
error return from the $READEF system service:

ILODE
ATNEF
» TSTFLGy
INTEGERY4 SYSSRE
*

Gy TETFLG)
(ZMAL ADEF
= SYSSRE
TCODE
. TLLEFCY GOTO 90000
IF (ICONE JEQ. 884

The symbolic definitions for system status codes are maintained in the
If your program is going to test
default system library, STARLET.MLB.

Use these symbolic names whenever you code

values,
the

for return

tests

status

numeric values may change with a later release of

the

since

file

system.

Appendix A "System Symbolic Definition Macros" describes how to obtain
For more information on
system symbols.
for
the numeric values
INCLUDE files

symbols,

system

containing

see

VAX-1l1l

FORTRAN

execution

modes

the

IV-PLUS User's Guilde.

2.2.3.3

Special

Conditions - Two

Return

process

1is returned to the calling program when an error
affect how. control
These modes are:
occurs during the execution of a system service.

Resource wait mode

System service failure exception mode

If you choose to change the default sétting for either of these modes,

your program must handle the special return conditions that result.

certain system
require
system services
Many
Resource Wait Mode:
system dynamic
include
resources
These
execution.
for
resources
Normally, when a system
memory and process quotas for I/O operations.
1is not available, the
resource
required
1is <called and a
service
becomes
resource
the
wuntil
state
a wait
in
program 1is placed

available.

Then,

the

service

called resource walit mode.

completes

execution.

This mode 1is

practical or

'However, in a time-critical environment, it may not

in these cases, you can choose to
a program to wait:
for
desirable
such a condition occurs,
when
that
so
mode,
wait
ce
disable.resour
the <calling program with an error
immediately to
returns
control
You can disable (and re-enable) resource wait mode with
status code.
the Set Resource Wait Mode (SSETRWM) system service.

‘\Ye‘J/

for these specific return values, you must create an INCLUDE
|
|
define the symbol names as parameters.

CALLING THE SYSTEM SERVICES
FORTRAN

CODING

How a program responds to the unavailability

very

resource

depends

much on the application and the particular service that is being

called.
1In some instances,
the
program may
execution
and
retry
the service call later.

be
able
to continue
1In other instances, 1it

may be necessary only to note that the program is

being

required

‘System Service
Failure
Exception Mode:
System
service
failure
is returned to the caller in
exception mode determines whether control
or
<call,
service
system
a
the normal manner following an error in
whether
an
exception condition is generated.
System service failure
receives
program
the calling
exception mode is disabled by default;

control
following
an error.
It is recommended that FORTRAN programs
do not enable system service failure exception mode.
|
'

CHAPTER
HOW TO

This

chapter

presents

Event

AST

flag

USE

SYSTEM

background

and

usage

System Trap)
Logical name services
Input/output services

Process

Memory

information

control

time

services

conversion services

handling

management

services
services

Whenever

possible, coding examples (using VAX-11
familiarize
you with
the
system services and

examples
show

only

not

the

show

code

complete

and/or

programming

arguments

discussion.
In

some

example

The

the

examples

are

programmer, see
MACRO

examples.

complex

special

coded
Figure

examples,

numeric

3-1

for

their

are given
to
arguments.
The

pertlnent

rather,
to

keyed

they

particular

|
explanatory

symbol,

using VAX-11

MACRO)

sequences;

that are

using

on:

services

(Asynchronous

Timer and
Condition

SERVICES

for

MACRO.

text

the

example

explanatlon of

you are
how to

FORTRAN

interpret

the

HOW TO

USE

SYSTEM SERVICES

Notes:

In the MACRO example, a routine name and entry mask show
beginning
of executable code in a routine or subroutine;
FORTRAN, the routine and its entry mask are
defined
by
statement.

oUBROUTINE

The MACRO examples define input

character

string

the
1in
the

arguments

This is not necessary in FORTRAN;
DESCRIPTOR macro.
a
with
you can code an input character string directly in the system
service

call.

These three MACRO directives declare a 63-byte buffer for
an
CHARACTER*63
the
FORTRAN,
In
string.
character
output
declaration is all that is necessary.

The MACRO directive .BLKW
value.
This
declaration.

reserves

equivalent

word

the

for

output

macro

name,

FORTRAN

A MACRO programmer calls a system service by

INTEGER*2
.
|

which
does not have the "SYS" portion of the procedure name.
A macro name for a system
service
<call
has
an
S or
G
suffix.
Note
the
following
differences between MACRO and
FORTRAN in the manner of codlng arguments:

MACRO arguments are not placed

MACRO arguments
in the.

keyword

in parentheses.

examples

are

specified

name preceding the actual argument.

correspond
lowercase

with

These names

to
the
names
of
the
arguments
shown
1in
1in
the
system
service formats in Chapter 4.
FORTRAN arguments must be coded in the
positional
order
shown

in Chapter

No indication is given when
an
optional
argument
1is
omitted in a MACRO argument list that uses keywords; you
1in
argument
must code a comma when you omit an optional
FORTRAN.

The MACRO programmer uses a number sign character
indicate

equivalent

literal

to the

The MACRO examples

%VAL

wvalue

for

function

show a check

for

argument.

in FORTRAN.
an error

return

(#)

from

This is

system service with the BSBW instruction;
this is equivalent
to a FALSE logical test following
a
function
reference
in

FORTRAN.

Figure 3-1

FORTRAN Interpretation of MACRO Examples

"HOW TO USE

SYSTEM

SERVICES

IMACRO Examp1e|
CYGDES:

DESCRIFTOR

NAMDES:

LONG 20%-10%

SDESCRIFTOR FOR OUTFUT EBUFFER

10% ¢

VEBLKE 63

FOUTFUT BUFFER

NOMLEN!

JELKW 1@

sWORD TO RECEIVE LENGTH

204 ¢

<CYGNUS:

sDESCRIFTOR

FOR

STRING

LONG 10%@)

CYGNUS

(63 BYTES)

¢+

ORION:
@)

+WORDN O

JENTRY MASK FOR START OF ROUTINE

@ TRNLOG..S LOGNAM=CYGIES
s RSLLEN=NAMLEN» RSLBUF =NAMIES , -

O:rsrw

s TRANSLATE FROM GROUF TARLE

TARLE=#1

FCHECK FOR ERROR

ERROR

+ENII

IFORTRAN Equivalentl
SURROUTINE ORION@)

| FROCEDURE DRION

CHARACTER¥63 NAMIES
@)
INTEGERX2 NAMLEN
INTEGERX4

|OUTFUT BUFFER DESCRIFTOR
|

SYS$TRNLOG

IWORD TO RECEIVE LLENGTH
'DEFINE

SYSTEM

SERVICE

FUNCTION

¢
+

(1) 9 )
G(
s NAMIOES » ZUAL
NLO
CYGNUS’ » NAMLEN
©:comE = SYSHTR
©IF

(.NOT.

ICOLE)

GOTO 90000

| ERANCH

IF ERROR

ENI

Figure

3-1

(Cont.)

FORTRAN

Interpretation

MACRO

Examples

HOW TO USE SYSTEM SERVICES

3.1

EVENT

FLAG

SERVICES

Event flags are status posting bits maintained by VAX/VMS for
general
programming use.
Some system services set an
event
flag to indicate
the completion or the occurrence of an event:
the calling program can
test
the
flag.
For
example,
the
Queue I/0 Request (SQIO) system
service sets
an
event
flag
when
the
requested
1input
or
output
operation

completes.

Programs can use
functions:

event

flags

clearing

perform

specific

)

Setting or

Testing the current status of flags

Placing the current proceSs in
setting of a specific

Moreover,

variety

signaling
-

flags

walt

flag or a group of

event flags can be used

state

flags

'pending

in common by more than one

the

process,

Thus, if
long as the cooperating processes are in the same group.
as
you
have
developed
an
application
that
requires
the
concurrent
execution
of
several processes, you can use event flags to establlsh
communication among them and to synchronize their activity.

3.1.1

Event Flag Numbers and Event Flag Clusters

Each event flag has a unique decimal number;
event flag arguments
1in
system
service
calls refer
to
these numbers.
For example, if you
specify event flag 1 when you code a $QIO system service,
then
event
flag number 1 is set when the I/0 operation completes.

To allow manipulation of groups of event flags, the flags are
ordered
in
clusters,
with
32
flags in each cluster, numbered from right to
left, corresponding to bits 0 through 31 in a longword.
The
clusters
are
also
numbered.
The range of event flag numbers encompasses the
flags in all clusters:
event flag 0 is the first flag in
cluster
0,
event flag 32 is the first flag in cluster 1, and so on.
There

are

1l.

two

o0f

cluster:

A local event flag cluster can only be used internally
single
to

types

each

process.

Local clusters are automatically available

process.

A common event flag cluster

can

shared

cooperating

processes in the same group.
Before a process can refer to a
common event flag cluster,
it
must
explicitly
"associate"

with the cluster.

Association is described in Section 3.1.4,

"Common Event Flag Clusters.”

The ranges of event flag numbers and the clusters to which they belong
are summarized in Table

3.1.1.1

3-1.

Specifying Event Flag and Event

Flag

Cluster

Numbers - The

[

same
system
services manipulate flags in both local and common event
flag clusters.
Since the
event
flag
number
1implies
the
cluster
number,
vyou do not have to specify the cluster number when you code a
system service call that refers to an event flag.

HOW TO USE SYSTEM SERVICES
EVENT

FLAG SERVICES

Table

Summary of

3-1

Event Flag

and Cluster Numbers

|Event

Cluster

Number

|[Flag Numbers

Description

0-31

Restriction

Process-local event

32-63

flag clusters
general use

for

Event flags 24

through 31 are
reserved for
system

64-95

96-127

Assignable common
event flag

cluster

use

Must be associated
before use

When a system service requires an event
flag
cluster
number
as
an
argument,
vyou
need only specify the number of any event flag that is
in the cluster.
Thus, to
specify any number in the

3.1.2

read the
range 32

event flags
through 63.

in cluster

you

could

Examples of Event Flag Services

Local event flags are most commonly used with other
system
services.
For
example,
with
the
Set
Timer ($SETIMR) system service you can
request that an event flag be set at a specific time of day, or
after
a
spec1f1c
interval
of
time
has
passed.
If you want to place a
process

in a wait state

event

for

Single Event Flag

TIME?

flag

for

number

« BLKQ

for

specified. perlod of

the $SETIMR service,

(SWAITFR)

system service,

sWILL

CONTAIN

time,

you could

code

and then use the Wait

follows:

TIME

INTERVAL

WAIT

$HETIMR..SG EFN= lS?thYT[MTTMF

ySET THE TIMER

$WATTFR..S

UNTIL

EFN=$33

sWAIT

TIMER

EXFIRES

In this example, the DAYTIM argument refers to a time value.
Details
on
how
to obtain a time value in the proper format for input to this
service are contained in
Section
3.6,
"Timer and
Time
Conversion
Services."

3.1.2.1
a wait

)

Event Flag Waits - Three system services place the prbcess in

state pending

the

The Wait for
places
the
been set.

setting

an event

Single

Event

Flag

Logical

process

The Wait for

1in a wait

flag:

(SWAITFR)

state

Event

until

Flags

system

service

(SWFLOR)

systém

single flag has
|
|

service places the process in a wait state until
spe01f1ed group of event flags has been set.

The Wait for Logical AND of Event Flags
process
flags

1in

have

wait

been

set.

state

until

all

any one of

(SWFLAND) places
a

the:

specified group of

HOW TO USE SYSTEM SERVICES
EVENT FLAG SERVICES

Another

system service

that

accepts

event

flag

number

argument
1is
the Queue I/O Request ($QIO) system service.
Figure 3-2
shows a program that issues two $QIO system service
calls,
and
uses
the
SWFLAND system service to wait until both I/O operations complete
before it continues execution.
|

$Q10.5

EFN=#1,,..

@EsEu

ERROR

BSEW

ERROR

s ISSUE FIRST

QUEUE

I/0

jCHECK FOR ERROR

$CHECK

I/0 REQUEST

s ISSUE SECOND

$QI0..8 EFN=#2y..,

REQUEST

FOR ERROR

SWAIT UNTIL ROTH COMFLETE
$CHECK FOR ERROR

$WFLAND_S EFN=#1,yMASK=#"R0110
~
|
ERROR
ESEW

SCONTINUE EXECUTION

Notes:

The event flag argument is specified in
event

are

in cluster

each

$QIO

After both I/0 requests are successfully queued,
calls
the
Wait
system
service

completed.
corresponds

event

flag

flags

and

that

flags

service
number:

1is,

the

call,
the
the cluster

cluster

are

The

Figure

the

request.
~

program

for
Logical
AND
of Event Flags (SWFLAND)
to
wait
until
the
TI/O
operations
are

In
this
to a cluster

specifies which

3.1.3

flags

EFN
that

MASK

argument.
contains

argument

waited

for:

3-2

Using Local

Event Flags

Setting and Clearing Event Flags

The $SETIMR and $QIO system services clear the event flag specified 1in
the
system service
call before they queue the timer or I/0O request.
This ensures the integrity of the
event
flag
with
respect
to
the
process.
If
you
are
wusing event flags in local clusters for other
purposes, take care to verify the state of a flag before you use it.
The Set Event Flag (SSETEF)
and
Clear
Event
Flag
(SCLREF) . system
services
set
and
clear
specific
event
flags.
For example, the
following system service call clears event flag 32:

$CLREF.S EFN=$32
The SSETEF and $CLREF services return successful
status
codes
that
indicate
whether the flag specified was set or clear when the service
was called.
The caller can thus verify the
previous
state
of
the
flag, if necessary.
The codes returned are SS$_WASSET and SS$_WASCLR.
Event flags in common event flag clusters are all 1n1t1ally clear when
the
cluster
1is
created.
The next section describes the creation of
common event flag clusters.
|

these

Both of

HOW TO USE SYSTEM SERVICES
EVENT

FLAG SERVICES

Common Event Flag Clusters

3.1.4

Before any processes can use event flags in a common event flag
the Associate Common Event Flag
cluster, the cluster must be created:
Cluster (SASCEFC) system service creates a common event flag cluster.
Once a cluster has been created, other processes in the same group can
call SASCEFC to establish their association with the cluster, so they
can access

flags

1it.

wWhen a common event flag cluster is created, it must be identified by
a 1- to l5-character name string. All processes that associate with
the
the cluster must use the same name to refer to the cluster;
the
between
nce
corresponde
the
establishes
service
SASCEFC system
cluster name and the cluster number that a process assigns to 1it.

The following example shows how a process might create a common

event

flag cluster named COMMON CLUSTER and assign it a cluster number of 2:

CLUSTER?

‘

DESCRIFTOR <COMMON CLUSTER:

’

FCLUSTER NAME

$ASCEFC..S EFN=#6%5y NAME=CLUSTER FCREATE CLUSTER 2

Subsequently, other processes in the same gJgroup may associate with
this cluster. Those processes must use the same character string name
but the cluster numbers they assign do not
to refer to the cluster;
have

the

same.

The
Common event flag clusters are either temporary or permanent.
system service defines whether the
PERM argument to the SASCEFC
|

cluster is temporary or permanent.

Temporary

clusters:

Require an element of the creating process's quota for

Are deleted when all processes associated

gueue entries

nave

timer

(TQELM quota).

Disassociation

disassociated.

with

the

cluster

performed

can

the

PRMCEB

explicitly, with the Disassociate Common Event Flag Cluster
the image
when
implicitly,
system service, or
(3DACEFC)
|
exits.

Permanent clusters:

the

Require

Continue to

privilege.

deletion

<creating
exist

proceSs

have

they

are

explicitly

until

marked

with the Delete Common Event Flag Cluster

user
»

for

($SDLCEFC)

system service.

If cooperating processes that are going to use a common event flag
cluster all have the requisite privilege or quota to create a cluster,
the first process to call the $ASCEFC system service creates the
cluster.

HOW TO

USE

EVENT

3.1.5

SYSTEM

FLAG

SERVICES

Disassociating and Deleting Common Event Flag Clusters

When

a process
1issues the
service.
When

no longer needs access to a common event flag
cluster,
Disassociate Common Event Flag Cluster ($DACEF
C) system
all processes associated with a temporary
cluster
have
$DACEFC system service, the system deletes the
cluster.
If a

issued

process

does

system

performs

SASCEFC

exits.

Permanent

with

the

After

the
all

until

not

disassociate

implicit

itself

disassociation

.
however,

from

when

the

cluster,

image

that

|
must

explicitly

marked

for

the

called

deletion

Delete
Common Event Flag Cluster
(SDLCEFC) system service.
cluster has been marked for
deletion,
it
is
not
deleted
processes associated with it have been disassoc
iated.,

Example

Figure

3-3

and

clusters,

3.1.6

common

explicitly

shows

event

PEGASUS

Using

an
in

Common

example

flag

are

cluster.

the

same

Event

four
The

Flag

Cluster

cooperating

processes

named

ORION,

group.

that

CYGNUS,

LYRA,

Notes on Figuré 3-3:

Assume for this example that ORION is the
issue

the

creator

cluster,

t,»

S$ASCEFC

the

all

system

cluster.

event

flags

service,

Since

this

are

the
cluster:

descriptor

CNAME

for

the

process to

therefore

The argument NAME in the S$ASCEFC system
pointer

first

and

1is

newly

service

the

created

call

1is

name to be assigned
to the
1in this example, the cluster is named COMMON
CLUSTER.
This
service
call
associates
the
name
COMMON
CLUSTER with cluster 2, containing event flags
64 through 95.
Cooperating
processes CYGNUS, LYRA, and PEGASUS must
use the
same

G’
-~

character

string

name

processes

mask

CYGNUS,

Event

LYRA,

Flags

indicating

Process

ORION

can

the

hexadecimal

the

second,

this

continue.

and

service

that

The

fourth

mask

binary

flags

work
Wait

call

must
this

1110:

cluster.

The

flags

65,

executes,
and

associates

disassociates.

Process LYRA associates with
(with

PEGASUS.

system

event

equivalent

third,

CYGNUS

flag

referring

event

flags

process

LYRA

COMMON

CLUSTER.

done

For

Logical

specifies

be set

"XE

indicates

«cluster

before

example,

the

sets

the

cluster

the

range

flag

99,

96
it

with

refers

through
is

itself.

flag

the

that

must

setting

the

sets

instead
as

cluster

3
when

Thus,
fourth

bit

set

‘and

it
127).

process

LYRA,

cluster,
and

When all three event flags are set, Process
execution

cluster,

cluster, . but

Process PEGASUS associates with the
event

G’

Process
event

and

(SWFLAND)

the

set.

refer

The continuation of process ORION depends
AND

e’

calls

the

$DACEFC

'did not

specify

cluster,

the

COMMON

PERM

CLUSTER

system

argument
deleted.

3-8

waits

sets

ORION

service.

when

for

event

an
flag

continues

Since

created

ORION

the

HOW TO USE SYSTEM SERVICES
EVENT

FLAG

SERVICES

'rgrocess ORIONJ
CNAME:

DESCRIFTOR <COMMON CLUSTER: CLUSTER

NAME

@ $ASCEFC.S EFN=#645NAME=CNAME s CREATE COMMON CLUSTER

BSEW

ERROR

$WFLAND.S EFN=¥64sMASK=#"XE
RSEW

ERROR

@ $DACEFC.S EFN=%64

sCHECK FOR

ERROR

sWAIT FOR FLAGS 19253
|
y CHECK FOR ERROR
sNISASSOCIATE CLUSTER

rProcess CYGNUSJ
ORION_FLAGS?: DESCRIFTOR <COMMON CLUSTER> sCLUSTER NAME
¢

$ASCEFC.S EFN=%44yNAME=0RION.FLAGS

sCHECK FOR ERROR

ERROR
RSEW
$SETEF..S EFN=%#63
ERROR
RSRW

sSET EVENT FLAG 1
s CHECK FOR ERROR
SDISASSOCIATE

$DACEFC.S EFN=#64

| Process LYRA|
SHAREI DESCRIFTOR <COMMON CLUSTERX y CLUSTER NAME

€b$fi$GEFCMS EFN=£94 s NAME=SHARE
RSRW

ERROR

s ASSOCIATE WITH CLUSTER 3
y CHECK FOR ERROR
sOET FLLAG 3
s CHECK FOR ERROR
s NISALS0CIATE

.S EFN=§99
$SETEF
ERROR
RSEW
$NACEFC.S EFN=%#96

rPrdcéss PEGASUS |
CLUSTER?: DESCRIFTOR «<COMMON CLUSTER: sCLUSTER NAME
L4

$ASCEFC.LS EFN=#64yNAME=CLUSTER #ASSOCIATE WITH CLUSTER
s CHECK FOR ERROR
sWAIT FOR FLAG 1
sCHECK FOR ERROR

ERROR
BERUW
$WATTFR.LS EFN=#&0
ERROR
BORW

.S EFN=#&6
$SETEF

RERW

FRROR

S$NACEFCLE EFN=#&4

“

Figdre 3-3

s CONT INUE

FlLAG 2
s CHECK FOR ERROR
sNISASSOCTIATE
sHET

Example of a Common Event Flag Cluster

HOW

USE

SYSTEM SERVICES

3.2

AST (ASYNCHRONOUS SYSTEM TRAP)

Some

system

services

when

particular

asynchronously

execution,
trap

allow

(out

the

(AST).

process

event
of

trap

routine

that

Since

the

interrupt

with

mechanism
provides

that

request

occurs.

sequence)

interrupt
The

user-specified

SERVICES

handles

respect

called

transfer

the

event.

interrupted

the

asynchronous

system services that use the AST mechanism accept as
an
address of an AST service routine, that is, a routine to
control when the event occurs.

For

services

Queue I/Q Reguest ($QIO)

Set

Timer

($SETIMR)

Set

Power

Recovery

Update

Section

example,
1f you

the

argument
given

are:

specify

system

control

The
the

These

occurs

process's

AST

File

(SSETPRA)

Disk

(SUPDSEC)

Timer

($SETIMR)

code

Set

address of

routine

system

service,

executed when a

you

time

can

interval

explires, or at a particular time of day.
The service sets
the
timer
and
returns;
the
program
image
continues
executing.
When
the
requested
timer
event
occurs,
the
system
"delivers"
an
AST
by
intefrupting the process and calling the specified routine.
" The
to

following
use

sections describe

3.2.1

Example

detail

service

with

request

Figure

for

program

an AST

that

when

the

time

refers
in

system

When the call to the
continues execution.

G’

system

The timer expires at 12:00
to

and

how

S$SSETIMR system

occurs.

1nterrupts

the AST

service

execution
routine.

the quadword NOON,
time

this is done, see Section 3.6,
Services." The ASTADR argument
of the AST service routlne.

system

the

requests

noon.

contain

calls

timer event

rhe call to the $SETIMR system service
12:00

work

3-4:

The DAYTIM argument

how ASTs

an AST

Figure 3-4 shows a typical

Notes

them.

format.

"Timer
refers

and
to

which

at
must

details

Time

TIMEAST,

on how
Conversion

the

address
|

service

and

For

AST

completes,
|

notifies
the

process

the
and

The user routine TIMEAST handles the interrupt.

the

process

system.
gives

The

contro1

When the AST

routine
completes,
it
issues
a
RET instruction to
control to the program.
The program resumes execution
.p01nt at which it was 1nterrupted

return
the

HOW TO

AST

USE

SYSTEM

(ASYNCHRONOUS

NOON:

« BLKQ

LLIBRA:

WORD

SERVICES

SYSTEM TRAP)

SERVICES

SWILL CONTAIN 12300 SYSTEM TIME
sENTRY

MASK

FOR

LIERA

QflsSETIMF:,.S DAY TIM=NOONyASTADR=TIMEAST
BSRW

ERROR

Timer

sENTRY

’

yHANDLE

« ENII

FOR

Interrupt t’

RET

MASK

FOR

TIMER

AST

ROUTINE

REQUEST

s [IONE

LIRRA

Figure 3-4

3.2.2

$SET TIMER

s CHECK

TIMEAST¢
|
+ WORI
"

Access Modes

for

AST

Example
of an AST

Execution

Each request for an AST is qualified by the access mode from which the
AST
1is
requested.
Thus, if an image executing in user mode requests
notification of an event by means of an AST, the AST
service
routine
executes 1n user mode.
,
|

Since the ASTs you use will
not
need
to
be concerned

aware

some

considerations

3.2.3

system
are

almost always execute in user mode, you
with access modes.
However, you should

considerations

described

Section

for
3.2.6,

AST

delivery.

do
be

These

"AST Delivery."

ASTs and Process Wait States

A process that is in a walt state can be interrupted for the delivery
of
an
AST and the execution of an AST service routine.
When the AST
service routine completes execution, the process is
returned
to
the
wait state, if the condition that caused the wait is still in effect.

The following walit states may be interrupted:
°

Event

flag waits

Hibernation

Resource walits

and

page

faults

3.2.3.1
Event Flag Waits - If a process is waiting for an event
flag
and
1s
interrupted
by
an AST, the wait state is restored following
execution of the AST service routine.
If the flag is set
during
the
execution of the AST service routine (for example, by completion of an
I/0 operation) then the
process
continues
execution
when
the
AST
service routine completes.

Event flags are described
Services."

detail
'

1in

Section

3.1,

"Event

Flag

HOW TO

AST

USE

(ASYNCHRONOUS

SYSTEM

SERVICES

SYSTEM TRAP)

3.2.3.2
Hibernation - A process can place
the
Hibernate
(SHIBER) system
service.

interrupted for the delivery of an AST.

SERVICES

itself
This

in a wait state with
wait
state
can be

When the AST service

routine

completes
execution,
the process continues hibernation.
The process
can, however, "wake" itself in the AST service routine or be
awakened
by
another
process
or
as
the result
of a timer scheduled wakeup
request.
Then, it continues execution when the
AST service
routine
completes.

Process suspension 1s another form
of
wailt;
however,
a
suspended
process
cannot
be
interrupted
by
an AST.
Process hibernation and
suspension are described in Section 3.5, "Process Control Services."

3.2.3.3
Resource Waits and Page Faults - When a process is
executing
an
1image,
the
system
can place the process in a wait state until
a
required resource becomes available, or until a page
in
1its
virtual
address
space is paged into memory.
These waits, which are generally
transparent to the process, can also be interrupted for
the
delivery

(o8

of an AST.

.2.4 How ASTs Are Declared

Most ASTs occur as the result of the
completion of
an
asynchronous
event
initiated
by
a system service, for example, a SQIO or SSETIMR
request, when the process requests notification by means of an AST.
There is also a system service that creates
ASTs:
the Declare
AST
(SDCLAST) system service.
With this service, a process can declare an
AST only for the same or for a less privileged access mode.
You may find occasional use for the $DCLAST
programming
applications;
you
may
also
useful when you want to test an AST service

system
service
1in
your
find
the S$DCLAST service
routine.

3.2.5 The AST Serviéé Routine
An AST

service

routine must be a separate routine.

the AST with
a CALLG instruction;

The

system

calls

the routine must return using a RET

instruction.
If the service routine modifies any registers other
RO
or
R1l, it must set the appropriate bits in the entry mask so
the contents
of those registers are saved.

than
that

Since it is impossible to know when the AST service routine will begin
executing,
you must take care, when you code the AST service routine,

that the service routine does not modify any data or

the main procedure.

instructions used

AST

HOW TO USE

SYSTEM SERVICES

Argument

the

On entry to the AST service routine,
(AP)

SERVICES

(ASYNCHRONOUS SYSTEM TRAP)

points to an argument list that has the

format:

Pointer
~

8 7

AST parameter

PSL

The registers RO and R1l, the PC, and PSL in this list are those
were saved when the process was

that

interrupted by delivery of the AST.

The AST parameter is an argument passed to the AST service routine
so
that
it
can identify the event that caused the AST.
When you code a

call to a system service requesting an AST, or when you code a SDCLAST
system
service, you can supply a value for the AST parameter.
If you

do not specify a value,

Figure 3-5

it defaults

illustrates an AST service routine.

In this

example,

the

deliver

the

ASTs
are
created
by
the $DCLAST
system
service:
the
ASTs are
delivered to the process immediately, so that the service
routine
is
called following each SDCLAST system service call.

3.2.6

AST Delivery

When an AST occurs,
interrupt

+to

the

system

may

the process immediately.

any of the following conditions exist:

not be

able

An AST cannot be delivered if

An AST service routine is currently executing at the same

at a more privileged access mode.

ASTs are implicitly disabled
when
an
AST
service
routine
executes,
so
that
one AST routine cannot be interrupted by
another AST routine declared for the same
access
mode.
It
can,
however,
be
interrupted by an AST declared for a more

privileged access mode.

AST delivery is explicitly disabled for the access mode.
A process can disable the delivery of AST interrupts with the
Set AST Enable ($SETAST) system service.
This service may be

useful when a program
is executing a sequence of instructions
that

should

routine.

not

be interrupted for the execution of an AST
:

AST

HOW TO USE SYSTEM SERVICES

(ASYNCHRONOUS

SYSTEM TRAP)

SERVICES

The process is executing at an access
than
For

that

for

which

example,

the AST

user

mode

mode ‘more

privileged

declared.

AST

declared

the

result

until

the

program

a system service, but the program is currently executing at
a
higher access mode (because of another system
service
call,
for
once

example),
the AST
again executing in

1s not delivered
user mode.

If an AST cannot be delivered when the interrupt occurs,
the
AST
1is
queued
until the condition(s) disabling delivery are removed.
Queued
ASTs are ordered by the access mode from
which
they
were
declared,
with

those

declared

from more

privileged

access

modes
at the

the queue.
If more than one AST is queued for
an
access
ASTs are delivered in the order in which they are queued.

FEGASUS:

JWORD

sENTRY

$NCLAST.S ASTALDR=ASTRTNsASTFRM=%1

RET
0

REQL

10%

CMFL

F2 v 4CAF)

CMFL.,

104

sRETURN

194 CAF)

RBEQL

sENTRY

20%

CONTROL
MASK

sCHECK AST FARAMETER 1

$IF

GOTO

#CHECK FOR

sHANIILE

RET

104

FARM=2

sIF 2 GOTO 204

2068

MASK

sAST WITH FARM=2

WORD

the

3AST WITH FARM=1

$HCLAST..S ASTANR=ASTRTNsASTFRM=4%2

ASTRTN?:

front

mode,

FIRST

AST

sRETURN

sHANDLE

RET

SECOND

AST

SRETURN

¢+

JEND

FEGASUS

Notes:

The program PEGASUS calls
twice

routine,
for

(’

dqueue

ASTs.

ASTRTN.

However,

the
Both

Declare
ASTs

AST

specify

a different

system
the

service

AST service

parameter

passed

each call.

The first action that this AST routine takes is to check
AST
parameter,
delivered is the
the AST

so
that it
can determine if
first or second one declared.

parameter

Figure

determines
the flow

3-5

The AST

Service

the
The

execution.

Routine

the

AST being
value
of

HOW TO USE SYSTEM SERVICES
3.3

LOGICAL NAME

SERVICES

The VAX/VMS logical name services provide a technique for manipulating
and
substituting
character string names.
Logical names are commonly

used
. to specify devices or files for input or output operations.
You
can
code
programs
with
logical,
or
symbolic,
names
to refer to
physical
devices
or files,
and
then establish an equivalence,
or
actual,
name by issuing the ASSIGN
command
from the
command stream

- before

the

program execution.

logical name

results

When

the program executes,

the

substitution

the

reference

equivalence name.

This section describes how to use system services to establish logical
names
for
general
application
purposes.
For
specific details on
logical
name
usage
for
I/0O
system
services,
see
Section
3.4,
"Input/Output
Services"
in this manual, and the discussion of logical
names in the VAX/VMS Command Language User's Guide.

3.3.1

Logical

Logical name
characters.

Names

and

Equivalence Names

and equivalence name
You
can
establish

strings can have
a
maximum of
63
1logical
name
and equivalence name
|

pairs:

the

MOUNT

command

level,

with

the ALLOCATE,

ASSIGN,

DEFINE,

commands

In
a program, with the
Create
Logical
Name
($SCRELOG)
and
Create Mailbox and Assign Channel (SCREMBX) system services

For example, you could use the symbolic name TERMINAL to refer
to
an
output
terminal
1in
a program.
For a particular run of the program,
you could use the ASSIGN command
to
establish
the
equivalence
name
TTA2:.

To perform an assignment in a
program,
you
must
provide
character
string descriptors
for
the
name strings and use the $SCRELOG system
service as shown in the following example.
1In either case, the result

is the
same:
the
device name TTA2:.

1logical name TERMINAL
|

is equated to the physical

TERMINAL! DESCRIFTOR <TERMINAL:X:

sDESCRIFTOR FOR LOGICAL NAME

TTNAME: DESCRIFTOR <TTAZI>

SDESCRIFTOR FOR EQUIVALENCE

]

$CRELOG.S

TRLFLG=#2yLOGNAM=TERMINAL
y EQLNAM=TTNAME.

The TBLFLG argument in this example indicates the
number,
in
this
case, the process logical name

logical
name
table
table.
Logical name

tables and logical name table numbers are discussed
sections.

the
|

following

HOW TO USE SYSTEM SERVICES
LOGICAL

3.3.2

NAME

SERVICES

Logical Name Tables

Logical

name

and

logical

name

tables:

Process

Group

System

equivalence

name

palrs

are

maintained

1in

three

A process logical name table contains names used
exclusively
by
the
process.
A process logical name table exists for each process in the
system.
Some entries in the process logical name table
are
made
by
system
programs
executing
at
more
privileged access modes;
these
entries are qualified by the access mode
from
which
the
entry
was
made.
For
example,
1logical
names created at the command level are
supervisor mode entries.

The group logical name table contains names that cooperating processes

w"“'

in
the same group can use.
a name in the group logical

The GRPNAM pr1v1lege
name table.

requlred

to place

The

system logical name table contains names that all processes in the
system can
access.
This
table
includes the default names for all
system—assigned logical names.
The SYSNAM privilege is
required
to
place a name in the system logical name table.

Figuref3—6 illustrates some sample logical name table entries.
Notes on Figure

3-6:

This process logical name

. table

The group logical name table shows entries qualified by group
numbers;
only processes that
can access these entries.

‘}

‘,

G’
|

c’

equates

the

TERMINAL
to the specific terminal TTA2:.
are equated to disk file specifications:
were created from supervisor mode.
|

have

the

1logical

1ndlcated group number
|
|
.

In Group 100, the logical name TERMINAL

1is

equated

terminal
TTAl:.
Individual processes in Group
to refer
to
the
1logical
name
TERMINAL
do
individually assign it an equivalence name.

100
not

Group 200 has entries for logical names MAILBOX and
Other
processes in group 200
input or output operations.

can use

these

In Group 300, the logical name TERMINAL

1is

logical

equated

physical
device name TTA3:.
Note
for TERMINAL in the group
logical

that there are
name
table.

discrete
entries,
the group to which

qualified

since they are
they belong.

name

INFILE and OUTFILE
these logical names

The system logical name table contains the

the

that want
have to

DISPLAY.

names

for

the

number

two entries
These
are

the

default

physical

device
names
for
all processes in the system.
SYSSLIBRARY
and SYSSSYSTEM provide logical names for all users
to
refer
to the device(s) containing system files.

HOW TO

USE

LOGICAL

SYSTEM SERVICES
NAME

SERVICES

[Logical-Name Table for Process A (Group Number = 200)]"

Logical NameA

- Equivalence Name

AcCéss Mode

TERMINAL

ceeem>

TTA2:

User

INFILE

——————>

DM1: [HIGGINS] TEST.DAT Supervisor

OUTFILE

——?———>

DM1: [HIGGINS]TEST.OUT Supervisor

{Group Logical Name Tablel(’

)

Logical

Name

e,TERMINAL

Equivalence

Name

Group

Number

TTAl:

100

O 1A1LBOX

MB3:

o 200

DISPLAY

TERMINAL

200

@TERMINAL

j— >

TTA3:

300

lSystem Logical Name Tablel(’

Logical Name

Equivalence Name

SYSSLIBRARY

—-———- >

DBAO:[SYSLIB]

SYS$SYSTEM

—-----—->

DBAO: [SYSTEM]

Figure 3-6

Logical Name Table Entries

3.3.2.1
Logical Name Table Numbers - Each logical
number associated with it.
To place an entry in a
.

)

specify

SCRELOG

follows:

logical

system

name

table

service.

Table

Number

Process
Group
System

2
1
0

The TBLFLG argument defaults
logical name table.

number

The

with

1logical
~

to
a value

3.3.2.2
Duplication of Logical Names
can
contain
entries
for the
same

modes.

The group logical name

logical

name,

long

the

name
table
logical name

TBLFLG

name

table

that
|

argument

numbers

1is,

the

are as
-

system

- The process logical name table
logical name at different access

table can contain entries for

group

has
a
table,

numbers

are

different.

the

same

HOW TO USE SYSTEM SERVICES
LOGICAIL

NAME

SERVICES

all other cases, there can be
only
one
entry
for
a
particular
logical
name
1in
a
logical name table.
For example, if the logical
name TERMINAL is equated to TTA2:
in the process table
as
shown
1in
the
figqure,
and
the
process
subsequently equates the logical name
TERMINAL to TTA3:
the equivalence of TERMINAL to TTA2:
is
replaced

by
the
new
SS$_SUPERSEDE

equivalence
name.
The
successful
return status code
indicates that a new entry replaced an old one.

Any number of logical names can have

3.3.3

the

same equivalence name.

Logical Name Translation

When you refer to a logical name for
a
physical
device
1in
an
1I/0
service,
the service performs logical name translation automatically.
In

many

cases,

program

must

perform

the

logical

name

translation

obtain the equivalence name for a logical name.
The Translate Logical
Name (STRNLOG) system service searches the logical name tables
for
a
specified logical name and returns the equivalence name.
By

default,

that

the

order,

logical
entry

process,

and

names exist
1is

found

process logical
order

second,

the

name

and

table

following example
translate the loglcal

with

tables

are

returned.

group

table

user

mode

entries

searched,

shows a call to
name TERMINAL.

DESCRIFTOR

not

the entries

all

searched,

Thus

the process
are

matched

table

When

searched

first,

identical

searched.

<TERMINAL>»

the

$TRNLOG

FDESCRIFTOR

system

FOR

INFUT

yBUFFER DESCRIFTOR

«LONG

204104

y LLENGTH

+LONG

10%

s ADDRESS OF BUFFER

«BLKER

s BUFFER

204

TLEN?

the

TEQLDESC?

10% 3

system

found

the

supervisor

oOn.

The

TLOGDESC!

and

the process and group tables,

first,

access mode,
and

group,

first match

+EBLKW

FOR

service

LOGNAM

EQLNAME

RBRYTES

s ENIN OF RUFFER
s RECEIVE

EQLNAM

LENGTH

HERE

$THN!OF.°

the

logical

name

L.OGNAM=TLOGDESC » RSLLLEN=TLEN RSLEUF=TEQLDESC

table

entries

are

shown

Figure

3-6,

this

call
to
the $TRNLOG system service results in the translation of the
logical name TERMINAL.
The equivalence name string TTA2:
is
placed
in
the
output buffer
described
by
TEQLDESC.
The
length of the
equivalence name string is written into the word at TLEN.
Note

that

the

call

$TRNLOG..S

$TRNLOG might

coded

LOGNAM=TLOGLESC »RSLLEN=TEQLDIESCy RSLBUF=TEQLIDESC

Then, the output equivalence name string length
first word of the character string
descriptor.

then

used

follows:

input to

another

is'written
into
This
descriptor

the
can

system service.

3.3.3.1
Bypassing Logical Name Tables - To disable the
search
of
a
particular
1logical
name
table,
you
can code the optional argument
DSBMSK to the $TRNLOG system service.
This argument is
a
mask
that
disables the search of one or more logical name tables.
The format
of
the mask is described in the discussion of the $TRNLOG system
service
in Chapter 4.
|

HOW TO

USE

LOGICAL

3.3.3.2

SYSTEM
NAME

SERVICES

Logical Name and Equivalence

Name

Format

Conventions - The

operating system uses special conventions for logical name/equivalence
name assignments and translation.
These conventions
are
denerally
transparent
to
user programs;
however, you should be aware of the
programming considerations involved.
If a logical name
STRNLOG
will not

string is preceded with an underscore character (),
translate the logical name.
Instead, it returns the

‘status code SS$ NOTRAN, strips the underscore from
the
1logical
name
string,
then
writes
the
string
into
the
result
buffer.
This
convention permits bypassing logical name translation in I/O
services
when physical device name strings are specified.
At login, the system creates default logical name
table
process permanent files.
The equivalence names for these

example, SYSSINPUT and SYSSOUTPUT,
that contains the following:
Byte (s)

Contents

0
1

"X1B
“X00

(Escape

2-3

RMS

Internal

are

preceded with

character)
|

File

(IFI)

Identifier

This header is followed
by the equivalence name

entries
entries,

4-byte

string.

for
for

header

any

your
program
applications
must
translate
system—-assigned
1logical
names, the program must be prepared to check for the existence of this
header
and
then
to
use
only the
desired part of the equivalence
string.
For

example

how

"Complete Terminal

I/0

this,

see

Figure

3-8

1in

Section

3.4.7,

Example."

3.3.4

Recursive Translation

When a

translate

request

made

for

1logical

name

string,

the

STRNLOG system service searches the logical name tables only once.
1If
you structure a logical name table or tables such
that
1logical
name
equivalencies are several levels deep (that is,
that
an
equivalence
name is entered
in the table as a logical name with another equivalence
name,
and soO on), you may require recursive logical name translation.
Note that Figure 3-6 illustrates recursive entries:
the logical
name

DISPLAY

1is equated

the

string TERMINAL

name TERMINAL is equated to the
process
table.
The
S$TRNLOG
complete the translation of the
You

can

code

program

loop

device
system
logical
that

service
1s
reused as the input
SSS NOTRAN following the call to

that

~written

3.3.5

1logical

into

the

name

output

the

in the group table,

name
string
service
must
name DISPLAY.

TTA2:
be used

output

from

string

the

and -the
in
the
twice to

STRNLOG

string, and check for the status code
the
service.
SS$S NOTRAN
indicates

was found, and that the input string has been

buffer.

Deleting Logical Names

The Delete Logical Name (SDELLOG) system service deletes entries
from
a
logical
name table.
When
you code a call to the S$SDELLOG system
service, you can specify a single logical name to delete, or
you
can

HOW TO USE SYSTEM SERVICES
LOGICAL

~ specify
table.
process
mode:

that

you

image

SERVICES

want to delete all

logical names from a particular

For example, the following call deletes
logical name
table that were entered
|

$OELLOG.S

Logical

NAME

names

from
the
from user

TRLFLG=%#2

that were

running

Entries made

all
names
in the table

from

placed

the

process

logical

name

table

from

in user mode are automatically deleted
at image exit.
the

command

command 1interpreter;
deleted at image exit.

these

stream

are

placed

supervisor

mode

the

table

entries,

and are
|

the

not

HOW TO

3.4

USE

SYSTEM

SERVICES

INPUT/OUTPUT SERVICES

There

are

under

VAX/VMS:

two

methods

you

can

use

perform

input/output

VAX-11 Record Management Services (RMS)

I/0

VAX-11]

system

RMS

services

provides

device-independent
modification.

set

functions,

such

The I/0 system services permit you to
operating

system

directly

macros

for

general-purpose,

data

storage,
|

use

the

1I/0

retrieval,
|

resources

device-dependent manner.

I/0

also
I1/0

provide some specialized functions not available in
services
requires more knowledge on your part but

efficient

input/output

This section provides
services, including:

operations.

general

Assigning channels

°o

Queuing I1/0 requests

Allocating devices

Using

you

plan

RMS.
Using
can result
in

information

how

use

the

1I/0

services

for

mailboxes

functions,

I/O User's

for

write

example,

Assigning

Channels

Before

any

input

a channel must be
the

output

assigned

process

and

service

establishes

use

terminal

input

the

and

I/0

output

devicedependent I/0 routines,

Gulde.

3.4.1

device.

this

operation

the

The

can

device

Assign

done

to provide

I/O

Channel

see

operations.

the

VAX/VMS

physical

a path

device,

between

(SASSIGN)

path.

the

device,

which

and

the

address

code an

channel

input

may

word

receive the

number,

output

physical
and

you

device

name

channel

use

this

number.

channel

The

service

number

when you‘

request

TTNAME! DESCRIFTOR <TTARS:
. BLKW

name

logical name,

For example, the follow1ng lines assign an I/O channel to
the
TTA2. The channel number is returned in the word at TTCHAN.

TTCHAN:

the

system

When you code a call to the SASSIGN service, you must supply the
~of

returns

the

services

Examples are provided to show you how to
If

and

simple

operations

device

S TERMINAL DESCRIFPTOR

y TERMINAL

CHANNEIL

NUMRER

FAGETIGN..S DEUNfiMflTTNfiHFyPHAN*TTCHAN
To assign a channel to the current default input or output device,
- must first translate the logical name SYSSINPUT or SYSSOUTPUT with
Translate Logical Name ($TRNLOG) system service.
Then,
specify

equ1valence

name

returned

the

DEVNAM

argument

the

$ASSIGN

you

the
the

system

HOW TO USE SYSTEM SERVICES
INPUT/OUTPUT

SERVICES

serviCe.» This technique requires you tofinterpret header

preceding
the
equivalence
name
string
for
example of this technique, see Figure 3-8 later

information

these devices.
For
in this section.

For more details on how SASSIGN and other I/0 services handle 1logical
names, see Section 3.4.10 "Logical Names and Physical Device Names."

Queuing»I/O

3.4.2

Requests

All input and output operations in
VAX/VMS
are
initiated
with
the
Queue
I/O Request ($SQIO) system service.
$QIO gueues the request and
returns;
while
the
operating
system
processes
the
request,
the
program that issued the request can continue execution.
Required arguments to the $QIO

service

include

the

channel

number

to the device on which the I/O is to be done, and a function
assigned
code (expressed symbolically) that indicates the specific operation to
Depending on the function code, one to six additional
be performed.

parameters may be required.

For example,

the IO$ WRITEVBLK and

device-independent

used

<codes

IO$ READVBLK

read

function

codes

are

and write single records or

virtual blocks.
These function codes are suitable for simple terminal
1/0.
They
require
parameters indicating the address of an input or
output buffer and the buffer length.
A call to SQIO to write
a
1line
|
to a terminal might appear as:
$QI0..8

CHAN=TTCHANs FUNC=#I0$ _WRITEVRLK,
Fl=RUFADDRF2=RUFIL.EN

Function codes are defined for all supported device types, and most of
the codes
are device dependent, that is, they perform functions that

‘are specific
to
a particular
device.
The
SIODEF
macro
defines
The codes are summarized 1in
names for these function codes.
symbolic
all
on
details
Appendix A, "System Symbolic Definition Macros;" for
codes and an explanatlon of the parameters required by each,
function
see the VAX/VMS I/0 User's Guide.

3.4.3

Synchronizing I/0O Completion

The $QIO system service returns control to the calling program as soon
as
the
I/0
request
1is
queued;
the
status
code
returned in RO
To
successfully.
queued
was
request
indicates whether or not the
~ ensure proper synchronization of the I/O operation with respect to the
program,

the

program must:

Test»for_the completion of the I/0 operation

Test whether

Optional

arguments

the I/O operation

the

$QIO

itself completed

service

provide

successfully

techniques

for

synchronizing
I/O completion.
There are three methods you can use to
test for the completion of an I/O request:

o
®

Specify the number of an event flag to be set
completes

when

the
|

1/0

Specify the address of an AST routlne to be executed when the

"I1/0 completes

HOW TO USE SYSTEM SERVICES
INPUT/OUTPUT

the

which

block

status

I/O

Specify the address of an

SERVICES

system can place the return status when the I/O completes

Examples of using these three techniques are shown in Figure 3-7.

[Examplesl: Event Flagsj"
s ISSUE 18T I/0 REQUEST
y QUEUED SUCCESSFULLYT
y [IGSUE 2NDN I/0 REQUEST
s QUEUED SUCCESSFULLYT

EFN=#ls.s.
$QI0..S
ERRKOR
RSRW
$QI0.S EFN=fly e
ERROR
BSEW

$WAIT TIL EOTH DONE

©#UFLANDL.S EFN=%#0,MASK=4#"E110
Notes on Example

When you code an event
the

clears

the I/0 completes,

number

flag

argument,

event flag when it queues the I/O request.
the

is set.

flag

the program
In this example,

different event flag

issues

two

I/0

$QIO

When

requests.

is specified for each request.

system
($WFLAND)
Flags
Event
of
The wait for Logical AND
in a wait state until both I/O
the process
service places
The EFN argument indicates that the
operations are complete.
the
O0;
cluster
1in
both
are
flags
event
indicates the flags that are to be waited for.

MASK argument

|Example 2: An AST Routine]"
¢’$QIUMSv e v + P ASTANR=TTASTy ASTFRM=%1y .+
BSEW
.

TTAST?:

ERROR
|

+bKNH]()¢’

yAST SERVICE ROUTINE ENTRY MASK
v

RET

Notes on Example

31/0 WITH AST

y QUEUED SUCCESSFULLY?
sCONTINUE
‘

FsHANDLE

I/0

yEND

SERVICE

COMFLETION

ROUTINE

When you code the ASTADR argument to the $QIO system service,

1’

The SQIO system service call specifies the address of the AST
routine, TTAST, and a parameter to pass as an argument to the

the
system interrupts the process when the I/O completes and
passes control to the specified AST service routine.

AST service routine.
continues execution.

When $QIO returns control,
.
”

the
|

and

returns

When the I/0 completes, the routine TTAST is called,
responds to the I/O chpletion.

When this routine is finished executing, control

the process at the point at which it was interrupted.
Figure 3-7

Synchronizing I/0 Completion

process

HOW TO USE SYSTEM SERVICES
INPUT/OUTPUT SERVICES

[Exémple 3: The 1/0 StatUS‘Block]"
TTIOSR!

ELKQ 1@

©:010.5
BSRW

... IOSE=TTIOSEy
...

$ISSUE 1/0 REQUEST

ERROR

y QUEUED

10%:

$1/0 STATUS ELOCK

SUCCESSFULLY®T

y CONTINUE

TSTW

TTIU&B‘,

BREQL

10%

y IS 170 DONE YET®?
sNOy

LOOF

CMFW

TTIOSREy
#S55% NORMAL

y 170

SUCCESSFULT

sNOy

ERROR

ENEQIOLERR
o

yYESy

TIL

HANDLE

DONE

Notes

Example

"An I/O status block is a quadword structure that
uses

post

area must

the

status

defined

your

I/0

progranm.

the_syétem

operation.

The

guadword

TTIOSB defines tne I/0 status block for this‘ I1/0 operétion,
The

IOSB

argument

in the

$QIO

system

quadword.

SQIO clears the quadword when

When

the

continues

request

queues

successfully

execution.

The proCess polls the I/O status
word

still

contains

completed.

request

1In

the

example,

the

queued,

block.
I/O

the

operation
program

refers

I/0

(Cont.)

this

request.

the

program

the 1low-order
has

loops

complete.

Figure 3-7

3.4.4

this

service

not

vyet

until

the

Synchrdnizing I/0 Completion

1/0 Completion'Status

When an I/O operation
completes,
status
1in
the I/O status block,
status indicates whether
or
not

the
system
posts
the
completion
if one is specified.
The completion
the
operation
actually completed
successfully,
the
number
of
bytes that
were
transferred,
and
additional device-dependent return information.

The format

the

information

written

in the

16 15
count

IOSB

0
status

device-dependent information

is:

HOW TO USE SYSTEM SERVICES
INPUT/OUTPUT

The

SERVICES

first word contains a system status code

failure

the

operation.

The

all returns from system services;

successful completion.

status

for

codes

indicating the success or
used

example,

are

same

for

transferred

1in

indicates

The second word contains the number of~bytes actually
the

the

SS$_NORMAL

I/0 operation.

The second longword contains device- dependent return information.
To
ensure successful
1/0
completlon and
the
integrity
of
data
transfers,
the
IOSB should
be
checked
following
I/O
requests,
particularly for device-dependent I/O functions.
For complete details
~on how to use the I/0 status block, see the VAX/VMS I/0 User's Guide.

3.4.5

Slmpllfled Forms of the $QIO Macro

The SQIOW macro combines the functions of the $QIO and
the
Wait for
Single
Event
Flag
(SWAITFR)
system
services.
S$QIOW has the same
arguments as the $QIO macro.
It queues
the
1I/O
request,
and then
places the program in a wait state until the I/O is complete.

The SINPUT and SOUTPUT macros are a subset of the $QIOW

macro:

they

use
only
the
function
<codes
to
read
and write virtual blocks or
records (IO$_READVBLK and IO$_WRITEVBLK, respectively).
These
macros
provide
an efficient
and
easy
way
to
specify I/O for terminals,

"mailboxes,

line printers,

and

interprocess network

transfers.

When you code a $INPUT or S$OUTPUT macro, you must specify the
channel
on
which the I/0 is to be performed and the length and address of the
input or output buffer.
Optionally you can specify an event flag
to
be
set
when
the I/0
1is
complete and the address of an I/O status
block.

For

$INFUT

example:

‘

CHfiNflTTfiHfiNyLENGTH“INLEN?BUFFER*INBUF?EFNW#IrIUQB“TTIUSH

3.4.6

}Deassigning I/0 Channels

When a process no longer needs access to

I/O

device, it

should

release the channel assigned to the device by issuing the Dea551gn 1/0

Channel (SDASSGN)
$0AKSGEN..S

system service.

For

example:

CHAN=TTCHAN

‘This service call releases the terminal channel assignment acquired 1in
the S$ASSIGN example shown earlier.
The system automatically deassigns
channels for a process when the image that assigned the channel exits.

HOW TO USE SYSTEM SERVICES
INPUT/OUTPUT SERVICES

3.4.7

Complete

Terminal

I/0

Example

Figure 3-8 shows a complete sequence of input
and
output
operations
‘using
the
SINPUT
and
S$SOUTPUT macros to read and write lines to the
current default SYSSINPUT device.
Note that if the program containing
these
1lines 1is
executed
interactively,
the input/output is to the
current

terminal.

TTNAME:

DESCRIFTOR

TTCHAN?:

JELKW

TTIOSE!

JELKW

<8YS$INFUT:
@)

TTIOLEN?

s DESCRIFTOR

JRECEIVE

SFIRST WORD OF IOSEy

JELKW

$SECOND

JELKL

3SECOND

OUTLEN?!

JBLKL

INBUF:

LJELKE

80@

NLENS

LLONG

NADDR:

LONG

NAME

NAME ¢

+ BLKE

653

FOR TERMINAL

FLENGTH

CHANNEL

WORIy

NUMRER

GET

LONGWORD
OF

HERE

STATUS

LENGTH
OF

STRING

IOSE

3BUFFER TO READ INFUT

DEVIESCS

NAME

OUTFUT

s IESCRIFTOR
s BUFFER LLENGTH

sADDRESS

BUFFER

@+ TRNLOG..S LOGNAM=TTNAME y RSLLEN=NLEN» RSLEUF =[EVIESC
CMFE

NAMEs#"X1R

ENEQ

106

SURL.
AL

1042

sNOES

iNOy

#4 s NLEN
F4 » NADDIR

NAME

SKIF

RBEGIN

WITH

ESCAFE?

FOTHERWISEy SURTRACT 4 FROM LENGTH
sADD 4 TO ANDRESS

€,$HS8IGNwS DEVNAM=DIEVIIESCy CHAN=TTCHAN 3$ASSIGN CHANNEL.
BSEW

ERROR

$INFUT

CHAN=TTCHANsLENGTH=#80y
RUFFER=INRUF s IOSE=TTIOSE

BSREW

ERROR

CMFW

TTIOSEy #55% . .NORMAL.

BNEQ

T0.ERRK

"HOUZNL

TTIOLEN

s 170 SUCCESSFUL®

QOUTLEN

yERROR

NOT..
.

FGET LENGTH QUT OF I0SE

c,$DUTPUT CHAN=TTCHAN v LENGTH=0UTLENy RUFFER=INRUF »y IOSEB=TTIOSE
BSEW

ERROR

CMFW

TTIOSEy #55% .NORMAL

3 SUCCESSFULT

BNEQ

TOLERRK

s BRANCH

d>$HfiSSGNM8 CHAN=TTCHAN
RSRW

fl}

Figure

¢ DONEy DEASSIGN CHANNEL

number

3-8

Example

Terminal

character

string

SYSSINPUT and TTCHAN
assigned to 1it.

descriptor
a

word

and

Output

can

easlily

first word) and the
the second word).

check

length

for

the

receive

the

The IOSB for the I/O operations is
program

Input

3-8:

TTNAME is a
device

NOT

ERROR

Figure

Notes

for

structured

the

completion

input

string

logical
channel

that

status

(in

returned

the
the.

(in

HOW TO USE SYSTEM SERVICES
INPUT/OUTPUT SERVICES

G’

The string will be read into the buffer INBUF;

OQUTLEN

will

contain

the

length of

the

string

the

for

1longword

the output

operation.

(’

The

Translate

Logical

Name

(STRNLOG)

system

service

translates
the
logical
name
SYSSINPUT.
On
return
from
STRNLOG, the equivalence name is checked for a 4-byte header
beginning
with an escape character.
(This header is present
in all
process
permanent
files;
see
Section
3.3.3.2,
"Logical Name and Equivalence Name Format Conventions.")

If
this header 1is
present,
descriptor for the device name
input

SASSIGN

SASSIGN.

assigns

channel

the
program
modifies
the
returned so i1t can be used as

and writes

the

channel

number

TTCHAN.

(’

If the SASSIGN service

completes

successfully,

the

macro
reads
a line from the terminal, and requests
completion status be posted in the I/O status
block

S$SINPUT

that the
defined

at TTIOSB.

The process waits until the I/0 is complete,

then checks

the

(’

Next, the length

moved

the

c’

The program performs error checks:

first
word
1in the I/0 status block
If not successful,
the program takes

the

string

for a successful
an error path.

read

return.

1into

longword
at
OUTLEN.
This is necessary because the S$SOUTPUT
macro requires a longword argument, and the length field
of
the
I/0 status block is only a word long.
The SOUTPUT macro
writes the line just read to the terminal.

first, it ensures that the

SOUTPUT
macro
successfully
queued
the I/O request;
then,
when the request is completed, it ensures that
the
I/O
was
successful.

fl)

3.4.8
If

When all I/O operations on
channel

is deassigned.

the

channel

are
|

finished,

the

Canceling I/O Requests

a process must cancel

I/0

request

that has been gueued

but

not

yet completed, it can issue the Cancel I/O On Channel (SCANCEL) system
service.
All pending I/Q requests
1issued
by
the
process
on
that
channel

are

For example,

canceled.

the S$CANCEL system service can be called as follows:

$CANCEL
.S CHAN=TTCHAN
In this example, the S$CANCEL system service initiates the cancellation

all pending I/O requests
to the channel whose number

is located at

TTCHAN.

The SCANCEL system service returns after initiating
the
cancellation
of the I/0 requests.
If the call to $QIO specified an event flag, AST
service routine, or I/0
status
block,
the
system
sets the
flag,
delivers the
AST,
or posts the I/O status block as appropriate when
the

cancellation

is actually completed.

HOW

TO USE

SYSTEM

INPUT/OUTPUT
3.4.9

SERVICES

Device Allocatlon

Many I/0 devices are shareable;
that is, more than
one process
you
access
the
device
at
a
time.
Each process, by issuing a S$ASSIGN
service, 1s given a channel to the device for I/0O operations.
In

some

cases,

data
1s
exclusive

process

may

need

exclusive

SALLOC system service,
name specified can be:

A physical

device

)

logical

name,

generlc

device

you

specify

attempts

a logical
allocate

name,

for

name,

device

reserve

that

device

for

provide

device

SALLOC

MT:
attempts

translates

device

name

the

allocate

logical

equated

If you specify a
device
type,
number =-- S$SALLOC
specified
type.
generic names 1is

TAPE

S$SALLOC

physical

must

example,
the tape drive MTB3:

name,

name.

you

for'example,

dev1ce

the

for

example,

name,

If you spec1fy a phys1cal
specified dev1ce.

s S

Device allocation is normally accomplished from
the
command
streanm,
with
the
ALLOCATE
command.
A process can also allocate a device by
calling the Allocate Device (SALLOC) system service.
When
a
device
has
been
allocated by a process, only the process that allocated the
device and any subprocesses it creates
<can
assign
channels
to
the
device.
|
|

When you code the
name.
The device

use

not
affected
by
other processes.
use you must allocate it.
-

name

the

and

logical

generic

device name -- that is,
1f
vyou
specify
a
but
do
not
specify
a
controller
and/or
unit
attempts to allocate
any
device
available
of
the
More
information
on
the allocation of devices by
provided in Section 3.4.10.1.

When you specify logical names
or
dgeneric
device names,
you
must
‘provide
fields
for
the $ALLOC system service to return the name and
the length of the physical device that is actually allocated,
so
vyou
can provide this name as input to the $ASSIGN system service.

Figure 3-9 illustrates the allocation of a tape
the

logical

Notes

name

on Figure

"
-

3-9:

service

corresponding

character

refers
name

specified
o

The SALLOC system
device

device

TAPE.

string

the

<call

the

descriptor

buffer
device

requests

logical
LOGDEV.

provided

actually

name

allocation of a

TAPE,

The

receive

defined
by

argument

the

allocated,

physical

and

1its

the

DEVDESC

device
1length.

SALLOC
translates
the
1logical
name
TAPE
and returns the
equivalence name string
into
the
buffer
at DEVDESC.
It
writes the length of the string in the first word of DEVDESC.

1‘9

The $ASSIGN command uses the character string returned by the
SALLOC

requests

system
that

service

the

as the

channel

input

number

device

written

name

into

argument,

TAPECHAN.

and

HOW TO USE SYSTEM SERVICES
INPUT/OUTPUT

LOGIEV?!

DESCRIFTOR

DEVIESC $
JLONG
JLONG
104
LELKE
|
2068

<TAFE:

SERVICES

R0%-10%

sLOGICAL

10%
&4

NAME

FOR

TAFE

$DESCRIFTOR FOR FHYSICAL NAME
sLENGTH OF RUFFER
|
sADDRESS OF BUFFER
sGET FHYSICAL NAME RETURNED

TAFECHAN?

JELKW

s CHANNEL.

FOR TAFE

I1/0

$Al.L0OC..S DEUNAM=LOGDEV»FHYLEN=DEVDESCyFHYRUF=DEVIESC
RSRW

ERROR

RSEW

ERROR

$ASSIGN.S DEUNAM=DEVIESC CHAN=TAFECHAN

yCONTINUE

$0ASSGN..S CHAN=TAFECHAN
ESEW

ERROR

Figure

3-9

CHDALLOC.LS

G’

Device

before

than

y DEALLOCATE

and

the

channel

the

device.

device can

Implicit Allocation

one

process,

for

and

Channel

the

that

terminals

TAFE

Assignment

the $DASSGN system service
$DALLOC

The
channel
deallocated.

Devices

example,

I/0

Allocation

WITH

s DEASSIGN CHANNEL.

When I/0 operations are completed,
deallocates
the

3.4.9.1

DEVUNAM=DEVIDESC

deassigns

iASSIGN CHANNEL

cannot
and

system

must

line

shared

service

deassigned
|

printers,

more
do

not

have to be explicitly allocated.
Since they
are nonshareable,
they
are implicitly allocated
by the $SASSIGN system service when SASSIGN is
called to assign a channel
to the device.

3.4.9.2

Deallocation

allocated
device,
1t
Device (SDALLOC) system

When

the

program

should release the
service,
to
make

finished

device with the
it
available

using

Deallocate
for
other

processes as in this example:

C$OALLOC.S DEVUNAM=DEVIESC
The system automatically deallocates
image exit.

3.4.10

Logical

Names

and

Physical

When
can

devices

allocated
by an
-

image

Device Names

a device name is specified as input to an I/0O system service,
it
be
a physical device name or a logical name.
When an underscore
character
(_) precedes a device name string,
it
indicates
that
the
string is a physical device name string.
For example:
|

TTNAME:

DESCRIFTOR

<.TTE3::

HOW TO USE SYSTEM SERVICES
INPUT/OUTPUT SERVICES

Any string that does not begin with
an
underscore
1is
considered
a
logical
name,
even
though
1t
may
be a physical device name.
The
SASSIGN,
SDASSGN,
SALLOC,
and
SDALLOC
system
services
call
the
Translate
Logical Name ($STRNLOG) system service to search the logical
name tables.
The S$TRNLOG service searches
the
process,
group,
and
system
tables, in that order, and if it locates an entry is found for
the specified logical name, the
I/0
request
1is
performed
for
the

device

specified

1in

the equivalence name

string.

The search

is not

recursive.

If STRNLOG does not locate an entry for
the
logical
name,
the
I/C
service treats the name that is specified
as
a
physical
device
name.
When you code the name of an actual physical device in
a
«call
to
one
logical

of these services,
name translation.

code

When the SALLOC system service

the

underscore

returns

character

the device name of

bypass

the

the physical

device
that
has
been
allocated, the device name string returned 1is
prefaced with an underscore character.
When this name is used for the
subsequent
SASSIGN
system
service,
the
SASSIGN
service
does not
attempt to translate the device name.

If you use logical names in I/0 service calls, you
must
be
sure
to
establish
a
wvalid
device name equivalence before program execution.
You can do this by issuing an ASSIGN command from the command
stream.
Or,
the
program
can
establish
the equivalence name before the I/0
- service call with the Create Logical Name (SCRELOG) system service.
For details on how to create
"Logical Name Services."

and

use

logical
|

names,

see

Section

3.3,

3.4.10.1
Device Name Defaults - If, after logical name translation, a
device
name
string
in
an
I/O
system
service call does not fully
specify the device name (that 1is, device, controller, and
unit),
the

service
either
provides
default
values for
provides values based
on device availability.

nonspecified

fields,

The follOwing rules apply:
l.

The SASSIGN,
SDASSGN,
default values as shown

The $SALLOC system service treats the device name as a generic
device
name and attempts to find a device that satisfies the
components of the device name that are specified, as shown in
Table

3-2.

and SDALLOC
in Table 3-2.

system

services

apply

HOW TO USE SYSTEM SERVICES
INPUT/OUTPUT SERVICES

Table

Default

Final

3-2

Device Names

Device

Name
Defaults for

Device

Name
Specification

for

I/0O Services

|
Generic

Device

SASSIGN, SDASSGN,| Names Used
and S$DALLOC
by $ALLOC

DD:

DDAQ
on

(unit

controller

DDC:

DDCO:
(unit O
on controller
specified)

DDAN:

DDA :

DDen :
A)

(any available

specified

the

DDCn:
(any avalilable unit
the specified controller)
.

(unit.
specified on

DDeN:

controller

controller)

DDAN :

device

type

type)

(device of specified
and unit on any available

DDAN:

Key:

DD:

1is

the

C:
e
N:
ne

is
is
is
is

the controller specified
any controller
the unit number specified
any unit number

3.4.11

device

type

specified

Obtaining Information About,Physical Devices

In casesAwhere a generic (that is, nonspecific) device name is used in

an
I/0 service,
the
program
may
need to find out what device has
actually been used.
The Get I/O Channel Information ($SGETCHN)
system
~service
provides specific
information
about the physical device to
which a channel has been assigned.
(SGETDEV)
system
service
returns
identified by its device name.
The

unit
number
of
characteristics.

the

device,

The
Get
1I/0
Device Information
information about a device that is
information returned includes
the

well

additional

device

When you code the $GETCHN or SGETDEV service,
vyou
must provide
the
address
of
a
buffer
or
buffers
1into
which the system writes the
information.
The format of the buffer, and additional
details
about

these

services are given

information
‘Guide.

3.4.12

these

in Chapter

services

Details on the device-specific

return
is given

the VAX/VMS

1I/0

User's

Formatting Output Strings

When you are preparing output strings for a program, you may
heed
to
insert variable information into a string prior to output, or you may
need to convert a numeric value to an
ASCII
string.
The
Formatted
ASCII Output ($FAO) system service performs these functions.

HOW TO USE SYSTEM SERVICES
INPUT/OUTPUT SERVICES

Input

the

1.
|

$FAO

service

consists

of:

A control string that contains the fixed text portion of
the
output
and
formatting
directives.
The directives indicate
the position within the string where substitutions are to
be
made,
and
describe
the
data
type and length of the 1nput
values that are to be substltuted or converted.

2.
|

An output buffer to contain the
substitutions have been made.

string after

conversions
|

An optional argument indicating a word to receive

Parameters

Figure

length of

3-10

shows

the

formatted output

that provide

a call

output string for

arguments

the

SFAO

a SOUTPUT macro.

the

string.
for

system

and

final

the directive.

service

format

Accompanying notes briefly discuss

the input and output requirements of FAO.
Complete details on how
to
use
FAO, with additional examples, are provided in the description of
the SFAO system service
in Chapter 4.

"FQOST“t DESCRIFTOR <FILE !'AS DOES NOT EXIST: $FAD CONTROL STRING

JDESCRIFTOR FOR FAO OUTFUT

©FAODESC! (LONG FAOLEN-FADERUF
FADRUF!

JLONG
JEBLKE

FADRUF
80

FAOLEN!

LONG ©

i AINRESS OF RUFFER
OUTFUT BUFFER

JRECEIVE LENGTH OF FAD OUTFUT STRING

G’FILESPECI DESCRIFTOR <IMALIMYFILE.DAT: SDESCRIFTOR FOR FAQ FARAMETER
b

‘,$Pfiflmq CTRSTR=FAQSTR
s QUTL.EN=FAQLENy OUTRUF=FAQLIESCy
~
|

P1=#FILESFEC

BORW

ERROR

BEEW

lhIUh

oo s BUFFER=FAORUF »

$OUTFUT

Figure 3-10

Notes

yPARAMETER FOR FAO-

LENGTH=FAQLEN

Example of Using Formatted ASCII Output Program

on Figure 3-10:

FAOSTR provides the FAO control string.

(’

FAODESC

!AS is an example of

an
FAO
directive:
it
requires
an
1input
parameter that
specifies
the address of a character string descriptor.
When
FAO
1is
called
to format
this control string, !AS will be
substituted with the string whose address is specified.

buffer;

is a

write the

character

SFAO will write

1length

string
the

the

descriptor

string

final

into

for

the

the buffer,

formatted

string

output

and will

1in

low-order word of FAOLEN.
(A longword 1is reserved so that
‘can be used for an input argument to the S$OUTPUT macro.)

FILESPEC is a character string descriptor defining
string

for

the

FAO directive

!AS.

the
it

input

HOW TO USE SYSTEM SERVICES
INPUT/OUTPUT SERVICES

output
the
control string,
The call to $FAO specifies the
is the
and length fields, and the parameter Pl, which
buffer

address of

the string

for

descriptor

substituted.

the

string

vhen SFAO completes successfully, SOUTPUT writes

string:

'the
|

output

FILE DMALSMYFILE.DAT DOE$ NOT EXIST

3.4.13

Mailboxes

Mailboxes are virtual devices that <can be used for communication
between processes. Actual data transfer is accomplished by using RMS

4\‘

\x——-/’

//‘

to
is assigned
or I/0 services. When a mailbox 1is created, a channel
Other processes can then assign
for use by the creating process.
it
channels to the mailbox using the SASSIGN system service.

The Create Mailbox and Assign Channel ($CREMBX) system service creates
system service identifies a mailbox by a
SCREMBX
The
the mailbox.
The
name.
user—-specified logical name and assigns it an equivalence
n
where
MBn:
format
the
in
name
device
physical
a
1s
name
equlvalence
|
|
is a unit number.

Wwhen another process assigns a channel to the mailbox w1th the SASSIGN
identify the mailbox by its logical name.
it can
system service,
SASSIGN automatically translates the logical name.

The

process

can

1logical name (with ‘the
the
translating
by
name
the MBn:
obtain
Channel
1I/0
the Get
<call
can
it
or
service),
system
STRNLOG
Information (SGETCHN) system service to obtain the unit number and the
physical

device

name.

are
privileges
user
permanent;
or
Mailboxes are either temporary
bCREMBX enters the logical name and
create either type.
to
required
equivalence name for a temporary mailbox in the group logical name
The system deletes a temporary
of the process that created it.
table
mailbox when no more channels are assigned to 1it.

logical

name

and

equivalence

exist until

they

are

specifically

The S$CREMBX system service enters the

name for a permanent mailbox in the system logical name table.

Permanent mailboxes continue to

marked for deletion with the Delete Mailbox

(SDELMBX)

system service.

a
of processes communicating by means of
Figure 3-11 shows an example
notes explain some of the arguments that
The accompanying
mallbox.
the SCREMBX

system service

requires.

3-33

HOW TO USE SYSTEM SERVICES
INPUT/OUTPUT

SERVICES

ProceSs ORION
MELLOGNAM?!
MRBUFFER$

DESCRIFTOR

+BLKE

<GROUF100_MAILEROX:>
s INFUT

128

sMAILEROX LOGICAL
RUFFER

FOR

NAME

MAILROX

JBUFFER OF 128 RYTES

MBUFLEN? .LLONG
MEXCHAN?
. BLLKW

MBUFLEN-MRUFFER
1

MEXIOSR:
. BLKW
MERLEN?
+BLRKW
'
+RILKL.
OQUTLEN: .RLKL

1
1
1
1

NUMERER
s TOSE FIRST WORD (STATLS)
s JOSE 2ONDI WORD (L.ENGTH)
s REMAINDER OF T0OSE
s LONGWORD TO GET LLENGTH

ORTION?S

"MaR2yR3sR4:

sENTRY

+WORDY

READS

SRUFFER LENGTH
sMAILEROX CHANNEL

MASK

$CREMEX..S FPRMFLG=%#0yCHAN=MEXCHAN
» MAXMSG=MBUF . ENRUFQUO=%384» FROMSK=#"X0000 s LLOGNAM=MEL. OGNAM
RSERW

$QI0.5
|

BSEW

ERROR

CHAN*MBXCHAN!FUNC2#IO$~READUBLKrIOSB:MBXIDSBym‘a

ASTADR=MEXAST
y F1=MBUFFER y F2=MBUFLEN
ERROR

RET

MEXAST?! ,WORD O

(3 )

sAST ROUTINE ENTRY MASK

CMPW
MEXTOSEy#$5$.NORMAL $I1/0 SUCCESSFUL?
s BRANCH IF NOT
ASTERR
ENEQ
MOVZWL
MELENyOUTLEN
sMAKE LENGTH A LONGWORD
$OUTFUT + 4+ y BUFFER=MEBUFFERy LENGTH=0QUTLENY ¢+« »
|
ERROR
BSEW
*

Pl '

RET

[Process CYGNUS
MAILROX? DESCRIFTOR <GROUF100.MAILROX: §HQILBUX LAOGICAL NAME
MATLCHAN

s MATLEOX
VRLKW

OUTRUF!

JEBLKE

128

HRUFFER

OUTLEN?

oBLKL

WORD

“M<R2yR3y
R4

CYGNUS?!
~

FASEIGN.S

BSEW

RBSRW

NUMRER

GWILL

FOR

OUTFUT

CONTAIN

SENTRY MASK

DEUNAM=MATILEOX
s CHAN=MAILCHAN

MSG

LENGTH

DATA

MSG

|
$ASSIGN

CHANNEL.

ERROR

$OUTFUT

CHANNEL

CHAN=MATLCHANy BUFFER=0QUTRUF s LENGTH=0UTLEN»+
..

ERROR

RET

Figure 3-11

Mailbox Creation and I/0

HOW TO USE SYSTEM SERVICES
INPUT/OUTPUT SERVICES

Notes

Flgure

3 11:

Process ORION creates the mailbox and

number

MBXCHAN.

receives

the

channel»

This
PRMFLG argument
indicates
that
the
mailbox
is
a
temporary
mailbox.
The logical name 1is entered in the group
logical

name

table.

The MAXMSG argument limits the
size
of
messages
that
the
mailbox
<can
receive.
Note that the size indicated in this
example is the same size as the buffer (MBUFFER) provided for
the
$QIO request.
A buffer for mailbox I/O must be at least

as large as the

size

specified

in the MAXMSG argument.

When a process creates a temporary
mailbox,
the
amount
of
system
memory
that
1is
allocated for buffering messages 1is
subtracted from the process's buffer gquota.
Use
the
BUFQUO
argument to specify how much of the process quota you want to
be used for mailbox message buffering.

Mailboxes are protected devices.
By specifying a
protection
mask with the PROMSK argument, you can restrict access to the
mailbox.
(In this example, all bits in the mask are
clear,
indicating unlimited read and write access.)

~ After creating the

mailbox,

Process ORION

issues

$QIO

system
service, requesting notification of the completion of
I/0 (that is, the reception of a message) by means of an
AST
interrupt
(the
AST
service
routine
1s
at
MBXAST).
The
process can continue executing.
|

- When a message 1s sent to the mailbox, the AST is
delivered,
and
ORION responds to the message. ORION gets the length of
the message from the first word of the I/0
status
block
at
MBXIOSB
and
places it in the longword OUTLEN so it can pass
the length to $SOUTPUT.

Process CYGNUS assigns a channel to the
mailbox,
specifying
the
1logical
name
the
process ORION gave the mailbox.
The
SOUTPUT form of the $QIO system service writes a message from
the

output

buffer

provided

at OUTBUF.

HOW TO USE SYSTEM SERVICES
INPUT/OUTPUT SERVICES

- 3.4.13.1
System
Mailboxes - The
system
uses
mailboxes
for
communication
among
system
processes.
All system mailbox messages

contain, in the first word of the message, a constant that 1identifies
the
sender
of
the
message.
These
constants have symbolic names
(defined

in the

SMSGDEF macro)

the format:

MSG$_sender

The remainder
of the message contains variable information,
on

the

system component that

sending

depending

the message.

The format of the
variable 1information
for each
message
documented with the system function that uses the mailbox.

3.4.13.2

Mailboxes for Process Termination Messages - When a

type

1is

process

creates
another
process, it can specify the unit number of a mailbox
as an argument to the Create Process (SCREPRC) system service.
When

the
created
process 1s
deleted, the system sends a message to the
specified termination mailbox.
An example of how to create and use
a
termination
mailbox
1is
©provided
in
Section
3.5.7.2, "Termination

Mailboxes."

3.4.13.3
Mailboxes for System Processes - There are a
group
of
1I/0
services
that
are used internally by system processes to communicate
various kinds of information.
These services are:

'®

Send Message td Accounting Manager ($SSNDACC)

Send Message to Operator

Send Message to Symbiont Manager_($SNDSMB)

Details on the formats
provide
Chapter

are

given

in the

the

($SNDOPR)

messages

and

the

individual discussions of
|

information

these

they

services
|

1in

HOW TO USE SYSTEM SERVICES
3.5

PROCESS CONTROL SERVICES

A process
into
the

1s the primary execution agent in
VAX/VMS.
system,
the system creates a process for

program
the RUN

images.
command

You

also

can

particular

When you
to create

code

When
you
1log
the execution of

issue the DCL command RUN, you
can
another process to execute
an image,

program

that

creates

another

process

request

execute

image.

Process control services
or group of processes.

provide

techniques

for

controlling

process
-

included in this section are diséussions of:
®

vSubprocesses and detached processes

The execution context of a process

Process

)

Interprocess control

Process hibernation and suspension

Image

Process deletion and

3.5.1

creation

exit

and

exit

and communication

handlers

termination messages

Subprocesses and Detached Processes

A process is either
a subprocess or a detached process.
A subprocess
receives
a
portion
of
its
«creator's
resource
quotas,
and
must
terminate
before
the
<creator.
A
detached
process
is
fully
independent;
for example, the process the system creates for you when

you

log

is
a detached process.

The Cteate Process (SCREPRC) system service creates both
and

detached

processes.

The

ability

create

controlled
by
the
PRCLM
quota.
The
ability
processes
1is controlled by the DETACH privilege.

3.5.2

The

Execution Context of

The execution
It includes:

context
|

The image

The

that

process

defines
|
is

a process
:

the
|

system.
o

executing

input and output streams for

the

process

1is
detached

create
|

a Process

a process
|
|

the

subprocesses

image

executing

available

Disk and directory defaults for the process
System

resource quotas

and

user

privileges

process

When the system creates a detached proCess as the result of
it
wuses
the
system
execution context.

authorization

file

determine

the

process's
|

HOW TO USE SYSTEM SERVICES
PROCESS CONTROL SERVICES

For example; when you log into the system:
@

The process created for you executes the image known as login.

The terminal you

Your disk and directory

The resource quotas and privileges you have
been
granted
the system manager are associated with the created process.

output,

and error

authorization

are

using

stream for

file.

established

images

defaults

When you code the $CREPRC system service

the

input,

that the process executes.

are

taken

create

from

the

process,

define the context by specifying arguments to the service.

3.5.3

user
by

you

ProCess Creation

The following sections show examples of process creation and
describe
how
the
arguments
you code to the SCREPRC system service define the
context

the

process.

3.5.3.1
Defining an Image for a Subprocess to Execute - When you code
the IMAGE argument to provide the
use
service,
system
SCREPRC
the
process with the name of a program image to execute. For example, the
following
1lines
create
a subprocess to execute the program image in
the

file named LIBRA.EXE.

FROGNAME! DESCRIFTOR <LIERA:

$CREFRC.-S IMAGE=FROGNAME
In this example,
disk
current

IMAGE TO EXECUTE

y CREATE FROCESS TO'EXECUTE LIRRA

1is
specified;
the
service
uses
name
logical
performs
defaults,
the most
translation, uses the default file type of EXE, and locates
When the subprocess completes
file.
image
the
of
version
recent
execution of the image, the subprocess is deleted.
Process
deletion
is described

3.5.3.2

only
a file name
directory
and

in Section 3.5.7.

Input, Output, and Error Devices for Subprocesses - When

you

code
the SCREPRC system service you can provide equivalence names for.
the logical names SYSSINPUT, SYSSOUTPUT, and SYSSERROR.
These logical
name/equivalence
name
pairs
are
placed in the process logical name
table

for

the

created process.

HOW TO USE SYSTEM SERVICES

Figure 3-12 shows an example of
for

devices

SERVICES

CONTROL

PROCESS

defining

input,

error

and

output,

The notes indicate how these devices are

subprocess.

}

used.

y INFUT STREAM

INSTREAM: DESCRIFTOR <SUR_MAIL..EBOX:

QUTSTREAM: DESCRIFTOR <COMFUTE.QUT:>
FROGNAME?:! DESCRIFTOR <COMFUTE .EXE>

sOUTFUT STREAM
?IMAGE NAME

[
¢

EAM, - y CREATE FROCESS
NAME
s INFUT=INSTR
$CREFRC.S IMAGE=FROG
QUTFUT=0UTSTREAMy ERROR=DUTSTREAM

Notes:

The OUTPUT argument equates the equivalence name COMPUTE.OUT
All messages the program
name SYSSOUTPUT.
1logical
the
to
writes to the logical device SYSSOUTPUT will be written to
this

‘,

SUB_MAIL_ BOX

The INPUT argument equates the equivalence name

This logical name may
to the 1logical name SYSSINPUT.
represent a mailbox that the calling process previously
created with the Create Mailbox and Assign Channel ($SCREMBX)
system service. Any input the subprocess reads from the
logical device SYSSINPUT will be read from the mailbox.

file.

The ERROR argument equates the equivalence name COMPUTE.OUT
All system-generated error
to the logical . name SYS$SERROR.
1is the
Since this
messages will be written into this file.
the file
file as that wused for program output,
same
of all output produced
effectively contains a complete record
~

during the execution of the program image.

Figure 3-12 Defining Input and Output Streams for a Subprocess

The SCREPRC system service does not provide default equivalence names
if none are specified, entries in the group
for these logical names;
If,
or system logical name tables, if any, may provide equivalences.

while the subprocess executes, it reads or writes to one of these
logical devices and no equivalence name exists, an error condition
,

results.

You can code a program that creates a subprocess to share the
input,

output,

or error

devices

following steps are required:

the

creating

(STRNLOG)

logical

process.

system

service

The

Use the Translate Logical Name

Check whether the equivalence name returned contains system
(a 4-byte field beginning with an escape
information
header
name table entry was created by
logical
the
if
character);
If
it will contain this header.
interpreter,
the command
returned
string
the
of
length
the
adjust
there is a header,
and the address of the string returned by modifying these
fields in the character string descriptor of the resultant

obtain the current equivalence name for the logical name.

name

string.

HOW TO USE SYSTEM SERVICES
PROCESS'CONTROL

Specify
INPUT,

the

address

OUTPUT,

SERVICES

this descriptor

ERROR

arguments

when

service.

you

the

code

SCREPRC

the

system

This procedure is illustrated in the example below.
NIOESC:

yDESCRIFTOR FOR

NLEN?

+LONG

LENGTH

NADDR?:

L LONG

NAME

sADDRESS OF

NAME :

« BLKE

yOEVICE

INFUT:

DESCRIFTOR

<SYS$INFUT:

RETURNED

STRING

NAME

yLLOGICAL

RESULT

STRING

DEVICE

RETURNED

NAME

$TRNL.OG..S

LOGNAM=INFUT, RSLLFN"NLEN:RQ[BUF NDESC

BSERW

ERROR

CMFE

NAME
»
#7X1H

BNEQ
SURL

10
#4499y NLEN

F4y» NADDR

LO% 3

$CREFRC..S

When

the

subprocess

system

can
the

service

sFIRST

sALD

executes,
to

the

OQUTFUT:

the

assign

ESCAFET

ANDRESS

1logical

I/0O

DESCRIFTOR <SYS$0UTFUT:>
JRLLKW

device name

names

channel

operations
by spec1fy1ng
SYSSOUTPUT.
For example:

OUTCHAN?

the

then use RMS to open the file
subprocess can use the Assign

input/output
name

RYTE

sNOy DON'T ADJUST
ySURTRACT 4 FROM LENGTH

0+ + s INFUT=NDESCy OUTFUT=NIESCr o s o

SYSSOUTPUT
are
equated
logical input device.
The subprocess
writing.
Or,

s BRANCH IF ERROR

the

SYSSINPUT

and

creating process's

for
reading
and/or
I/O Channel ($ASSIGN)

+to

this

device

name

the

for

logical

$LOGICAL NAME DESCRIFTOR

s CHANNEL

NUMERER

OUTFUT

DEVICE

+
®

$ALBHIGN.S

DEVUNAM=0UTFUT
s CHAN=0UTCHAN

Logical name translation is
"Logical
Name
Services."

for

1/0

operatlons,

3.5.3.3
use

Disk

and
S$SCREPRC

the

image,

the

created

device

see

Directory‘Defaults
system

system

locates

process.

and

described in more detail in
Section
3.3,
For more information on channel a351gnment
Sectlon 3.4, "Input/Output Serv1ces."‘

The

directory

service
the

image

created

for
to

Created
create

file within

process

you explicitly specify
.a
specification
of
the
image
equivalence names, then those
of the created process.

device
and/or
file or
the

There

way

the

inherits

its creator.

Processes - When
vyou
a process to execute an

define

files

can

the

context

the

default

directory
in
the file
input,
output or error

located

w1th1n

the

~context
|

alternative

default

device

directory
at
process
creation.
The
created process
define an equivalence for the logical device SYS$DISK by

Create

current

and/or

can, however,
calling
the

Logical
Name
(SCRELOG)
system service.
1If the process is a
subprocess, you can define an equivalence name in
the
group
logical
name
table.
The
<created
process
can
also
set
its
own default
Rg

Default Directory control
routine.
For
routine, see the VAX-11 Record Management

the RMS
call this
Manual.

calling

how to
Reference

Services

directory
details

HOW TO USE
PROCESS

SYSTEM SERVICES

CONTROL

SERVICES

when
Controlling Resources of Created Processes - Ordinarily,
3.5.3.4
a subprocess, you need only assign it an image to execute
create
you
The
and, optionally, SYSSINPUT, SYSSOUTPUT, and SYSSERROR devices.

system provides default values for the process's privileges, resource

guotas,

and priority.

execution modes,

In some cases, you may want to

The arguments to the SCREPRC system
spec1f1cally define these values.
with
service that control these characteristics are 1listed below,
argument
the
see
details,
For
use.
their
considerations - for
in Chapter

descriptions of SCREPRC

£for the
1list
PRVADR - this argument defines the privilege
‘any process you create will have
created process. Normally,
by the
to you
the same privileges that have been assigned

may need to
circumstances, you
some
In
system manager.
must
but you
create a process that has a special privilege:
have the user privilege SETPRV to provide a subprocess w1th a
you do

privilege

may want to control how much of each quota you want
to
the
subprocess.
If
you
do
not
<code
this

‘argument,

subprocess.

have.

a
for
quota list
defines the
QUOTA - this <argument
a portion of its
receives
subprocess
a
Since
subprocess.
creator's quotas for timer queue entries, I/0 buffers, and so
on,
you
assigned

not

the

system

defines

default

quotas

<characteristics

of the created process,

.resource walt mode and process swap mode.

for

including

priority
BASPRI - this argument sets the base executlon
If not specified, it defaults to 2.
the created process.

you want a subprocess to have

priority

higher

the

some

control

STSFLG - the status flag is a set of bits that
execution

than

for
If

its

creator, you must have the user privilege ALTPRI to raise the

priority

3.5.3.5

level.

detached 'pr0cess

Detached Processes - The creation of a

the DETACH privilege controls the
‘primarily a system function;
The UIC argument to the SCREPRC
ability to create a detached process.
system service defines whether a process 1s a subprocess or a detached
identification
it provides the created process with a user
process;
If you omit the UIC argument, the SCREPRC system service
(UIC).
code
|
creates a subprocess that executes with your UIC.

Interprocess Control and Communlcatlon

3.5.4

Processes can be wholly 1ndependent, or they can be cooperatlve. ~ You
an application that requires the concurrent execution of
may develop
you may
things
discuss the
The following sections
many programs.

3.5.4.1

Restrictions on

Process

Creation

three levels of process control privilege:

The

creator

functions

for

of
that

subprocess can
subprocess.

consider when you develop such applications.

and

Control - There

always

1issue
|

are

control

HOW TO

USE

PROCESS

2. The GROUP privilege
functions

for

SYSTEM

Additional

for

privileges

for

example,

that

the

any

are

set

SERVICES

is required

other

processes

The WORLD privilege is
functions

SERVICES

CONTROL.

required

process

required

process's

issue

executing

the

issue

priority

same

control

group.

pfocess

system.

to perform some
base

process
the

control

specific

fUnctions,

level

higher

3.5.4.2
Process
Identification - In
the
examples
shown
in
preceding
sections,
the
subprocesses
are
not
identified:
created,

input
In

the

subprocesses

stream

specified,

many

cases,

execution
processes

of
that

however,

are
l.

execute

and
you

a subprocess
execute in the

one another or issue
must be identified.

There

than

requestor.

control

according

are

deleted

may

want

when
to

the

image

they

name

complete

able

the
once

the

execution.

control

the

after it has been created.
Or, detached
same group may want to communicate
with
functions.

1In

these

cases,

the

processes

two levels of process identification:
Process identification number (PID).
The
unique 32-bit number to a process when it

provide
the

the

system

PIDADR argument

returns

the

system assigns this
is created.
If you
SCREPRC
system service,

the

process

identification

specified.
You can
then
use the
number in subsequent process control
2.

Process

name.

process

name

©process
services.

the

location

identification

15-character

text

name
string.
You
can assign a name to a process by coding
the PRCNAM argument when you create it.- You
can
then
use
this
name
to
refer
to the process in other system service
calls.
For

example,

ORION:

you

might

DESCRIFTOR

code
a SCREPRC

system

service

<ORION:

ORIONID?

JLONG

follows:

s FROCESS

NAME

|
sFROCESS

|
RETURNED

$CREFRC..S PRCNANfiORIONpPIDADRzORIONIDr...
The

service

returns

the

process

identification

ORIONID.
Now,
you
<can
use
either the process
process identification (ORIONID) to refer to
this
system service calls.

A process can set or
(SSETPRN)

CYGNUS:

DESCRIFTOR

change

service.

its own name with

For

follows:

fT]
« + <

CYGNUS

system

TFRN..S

<CYGNUS:-

FRCNAM=CYGNUS

example,

the

a process

the

1longword

name (ORION) or the
process
in
other

Set

Process

can set

s NAME

its

Name

name

DESCRIFTOR

HOW TO

USE SYSTEM

PROCESS

Most of the process control
PIDADR arguments, or both.

CONTROL

SERVICES
SERVICES

services
accept
either
the
PRCNAM or
The process identification provides a more

efficient means of identifying a process.
Since it is only
in length, a system service can examine
it more quickly.

When

contains

the

PIDADR

the

obtain

argument

services

the

function,

process
as

return

long

coded
the

and

identification
as

you

know

the

process

the

for

specified

process

Table

the
the

by issuing

you

any

can

control

possible
services

performed

for

the

combinations of these
interpret
them,
see

3-3.

Table

Process

Thus,

name.

If neither argument is specified, the service
calling
process.
For a summary of
arguments and an explanation of how

address

identification.

longword

3-3

Identification

Process

ID | Process

Name

Address

Resultant

Action

Services

Specified? | Specified? | Contains:
no

-—

yes

zZero

process

yes

The

process

the
The

calling
process is used.
process identification
is

not

returned.

The process identification
the

<calling

and

returned.

| The

process

used
yes

identification

The

and

©process

yes

Zero

identification

process

the
process
returned.

name

used.

name

The

used

not

and

identification

‘\

1is

returned.

process

The

used

process
1identification
returned.
yes

yes

process

1id | The

process

used

and

identification

Process Naming within Groups:
Process names are always
their
group
number.
- The
system
maintains
a table
names,

and

when

PRCNAM

service,

the service

match

the

group

argument
is

searches

number,

and

for

specified

the process

fails

the

1is

returned.

name

qualified
by
of all process

process

specified

control

and

process

for

name

does not have the same group number.
This is true even if the calling
process has world control privilege:
to
execute
a
process
control
'service for a process that is not a subprocess and not in the caller's
group, the.requesting process must use
a process identification.

HOW TO USE SYSTEM SERVICES
PROCESS

CONTROL

SERVICES

Obtaining
Information
about
Processes:
The
Get
Job/Process
Information
(SGETJPI)
system service allows
a process
to obtain
information
about itself or another
process.
For
complete
details
the service description in
see
service,
system
SGETJPI
the
about
Chapter

Techniques for Interprocess

Communication:

that processes can communicate:
e

Common event flag

Logical

Mailboxes

Global

name

There

are several
|

ways

clusters

tables

sections

Common Event Flag Clusters:
Processes executing within the same group
can
use common
event flag <clusters to
signal
the occurrence or
completion of particular activities.
For
details
on
event
flags,
event
flag
clusters,
and an example of cooperating processes 1in the
same group using a common event flag,

see

Secton 3.1,

"Event

Flag

Services."

Logical Name Tables:
Processes executing in the same
group
can
use
the group
1logical
name
table
to
provide
member
processes
with
equivalence names for logical names.
At least one member of the group
must
have the user privilege
to place names in the group logical name
" table.
For details on logical names
and 1logical
name
tables,
see
Section 3.3, "Logical Name Services."

Mailboxes:
Mailboxes can be used as virtual input/output
devices
to
pass
information,
messages, or data among processes.
For details on
how to create and
use
mailboxes,
with
an
example
of
cooperating
processes using
a mailbox, see Section 3.4, "Input/Output Services."
Mailboxes may also be used to provide a creating process with a way to
determine
when and
under
what
<condition a created subprocess was
deleted.
See Section 3.5.7.2 for an example of a termination mailbox.

Global Sections:
Global sections are disk files containing
shareable
code or
data.
Through the use of memory management services, these
files can be mapped to the virtual address
space
of
more
than
one
process. _In
the
case
of
a
data file, cooperating processes
can
synchronize reading and writing the data in physical memory;
as
the
data
1is
updated, system
paging
results
1in the updated data being
written directly -back
into
the
disk
file.
Global
sections
are
described in more detail in Section 3.8.6, "Sections.”

HOW TO USE SYSTEM SERVICES
CONTROL

PROCESS

3.5.5

SERVICES

Process Hibernation and Suspension

process:
a
of
execution
There are two ways to temporarily halt the
by the Hibernate (SHIBER) system service, and
performed
hlbernatlon,
suspension, performed by the Suspend Process (SSUSPND) system service.

The process can continue execution normally only after a corresponding
or after a Resume
Wake (SWAKE) system service, if it is hlbernatlng,
Process (SRESUME) system service, if it 1s suspended.

Process hibernation and suspension are compared in Table 3-4.
Table

3-4

Process Hibernation and Suspension

Hibernation

Suspension
Can suspend self or another

Can only hibernate

process, depending on privilege

self

Reversed by S$WAKE

system service

Interruptible;
receive ASTs

can

‘Reversed by $RESUME system service
Noninterruptible;
ASTs

cannot receive

Cannot resume self

Can wake self

Can schedule wakeup

Cannot schedule resumption

at an absolute time
or at a fixed time
interval

Hibernate/wake

complete quickly;
require little
system overhead

Requires system dynamic memory
-

3.5.5.1
Process Hibernation - The hibernate/wake mechanism provides
an
efficient way to prepare an image for execution and then place it
in a wait state until it is needed.
When the wake request is
issued,
the

image

is reactivated with little delay or

For example, if you create a subprocess that

system overhead.

must

execute

the

same

function
repeatedly,
but must execute immediately when it is needed,
you could use the S$HIBER and S$SWAKE system services as shown in Figure
|
|
,
3-13.

There is a variation of the SWAKE
system service
that
schedules
a
at a fixed time or at an elapsed
process
hibernating
a
wakeup- for
(delta) time interval.
This is the Schedule Wakeup ($SSCHDWK)
system
service.
Using
the $SCHDWK service, a process can schedule a wakeup
for itself before issuing a SHIBER call.
For an example of how to use
the
$SSCHDWK
system
service,
see
Section
3.6,
"Timer
and
Time

Conversion Services."

HOW TO

USE

PROCESS

Process

SYSTEM

CONTROL

SERVICES
SERVICES

GEMINI

ORION: DESCRIFTOR <ORION:

;i SURFROCESS NAME

FASTCOMF:

y IMAGE

DNESCRIFTOR

<COMFUTE
. EXE:

"$CREPRCWF FRCNAM=0RIONy IMAGE=FASTCOMFy ..+
RSRW

ERROR

©sWAKE..S FRONAM=ORION
BSEW

$CREATE ORION

5 CONT INUE

s WAKE ORION

ERROR

SWAKE..S FRCNAM=0RION

sWAKE ORION AGAIN

ERROR

RSRW

Process~ORION]
FASTCOME@

JWORD

10% ¢

o(@

SENTRY MASK

$HIRER.S
BSEW

|
ERROR

i SLEEP

SFERFORM
» o

EtFe

10%

sRACK TO SLEEF

Notes:

Process GEMINI creates
image

name

The image FASTCOMP
SHIBER

system

process

repeat

initialized,

service.

specifying

the

—

issues

and

ORION

issues

the

SWAKE

request

for

ORION
continues
execution
following
the
S$HIBER
call.
When it finishes its job, ORION loops back
to

the

S$HIBER call

Figure

Hibernating

ORION,

At an appropriate time, GEMINI
ORION.
service

(ASTs),

the

FASTCOMP.

processes
long

can

as AST

3-13

and

to wait

Process

interrupted

delivery

1is

for

another

wakeup.

Hibernation

by Asynchronous

enabled.

The

System

process

can

Traps
issue

SWAKE for itself in the AST service routine,
and continue
execution
following the execution of the AST service routine.
For a description
of ASTs,
and how to use them,
see
Section
3.2,
"AST
(Asynchronous
System Trap) Services."

HOW TO USE SYSTEM SERVICES
PROCESS CONTROL SERVICES

;

3.5.5.2

Alternate Methods of Hibernation - Two additional

you can use to cause a process to hibernate are:

techniques

Code the STSFLG argument for the S$SCREPRC system service,
setting the bit that requesSts $CREPRC to place the created
is
process in a state of hibernation as soon as it
initialized.

Specify the /DELAY, /SCHEDULE, or /INTERVAL qualifiers of the
RUN

command

when

vyou

execute

the

1image from the command

stream.

When you use the first method, the creating program image can control,
the

system

services

the created process.

described here and in Section 3.6, when to wake
|

When you use the RUN command, the qualifiers listed above control when
the process will be awakened.

S$HIBER

If the image to be executed does not, itself, call the

system

service, the 1image 1is placed in a state of hibernation whenever it
issues a RET instruction. Each time it . is reawakened, it begins

executing

at its entry point.

If the image does call SHIBER, then it

begins executing at either the point following the call to SHIBER
at its entry point (if it issues a RET instruction) each time it
:
awakened.

or
is

If wakeup requests are scheduled at time intervals, the image can be
terminated with the Delete Process ($DELPRC) or Force Exit (SFORCEX)
system services, or from the command level, with the STOP command.
The S$DELPRC and S$FORCEX system services are described later in this
section. The RUN and STOP commands are described 1in the VAX/VMS
Command Language User's Guide.

These techniques allow you to code programs that can be executed a
single time, on request, or cyclically, depending on a particular set
of circumstances. Note that the program must ensure the integrity of
data areas that are modified during its execution, as well as the

status of opened files.

system
3.5.5.3 Suspension - Using the Suspend Process (SSUSPND)
a wait
into
process
another
or
itself
service, a process can place
more
Suspension, however, 1is a
state similar to hibernation.

A suspended process cannot be
pronounced state of hibernation.
eXxecution only after another
resume
can
and
ASTs,
by
interrupted
If
process issues a Resume Process (SRESUME) system service for it.
are
they
suspended,
was
it
while
process
the
for
ASTs were queued
delivered when the process resumes execution.

3.5.6'_Image Exit
When the image executing 1in . a process completes: normally, the
operating system performs a variety of image rundown functions. If
the image was executed by the command interpreter, image rundown
prepares the process for the execution of another image. If the image
was not executed by the command interpreter —-- for example, if it was
executed by a subprocess -- the rundown readies the process for
deletion.

HOW TO

USE SYSTEM

PROCESS

These exit activities are
abnormally, as a result of

CONTROL

also

any

SERVICES
SERVICES

initiated

the

when

image

completes

following:

Specific error conditions caused by
improper
specifications
when
a
process
was
created.
For
example, if an invalid
device name
is
specified
for
SYSSINPUT,
SYSSOUTPUT,
or
SYSSERROR
1logical
names,
or
if
an invalid or nonexistent

image name is specified, the error condition
context of the created process.

noted

within

the

An exception condition during execution of the
image.
When
an
exception
condition occurs, any user-specified condition
handlers receive control to handle the exception.
1If not,
a
system—-declared
condition
handler
receives control, and it
initiates exit activities for the image.
Condition
handling
is described in Section 3.7, "Condition Handling Services."

A Force
process

3.5.6.1

1Image
image
rundown
obtained while

Exit (SFORCEX) system
another process.

service

issued

behalf

the

Rundown Activities - The
operating system
functions that release system resources that

executing in

user

mode.

These

a
are

activities

performs
process

1listed

below.

handlers declared from user
the
exit
control blocks
are
described in Section 3.5.6.3.)

Common event flag clusters are disassociated.

User mode ASTs that are queued but have not been
deleted, and ASTs are enabled for user mode.

delivered

I/O channels are dea531gned and
on the channels are canceled.

I/0
-

Exit

All

dev1ces

allocated ’to

mode,

if any, are called, and
released.
(Exit handlers are
|

any

the

outstandlng
|

process

wuser

are

requests
-

mode

are

~deallocated.

Timerscheduled
canceled

Logical names
user
stream

)

mode
in

are

requests,
}
o

wakeup
o

in the process logical
deleted

supervisor

Exceptlon

vectors

handlers,

and

(logical

mode

are

declared

change mode

System

service failure

Memory

pages

process's
value.

including

occupied

working

not

the

limit

table

entered from

mode,

terminate

the

This

image

itself,

not,

however,

the

command

compat1b111ty

handlers
mode

1image

are

mode

reset.

disabled.

are

deleted

readjusted
|

3.5.6.2
The $Exit System Service - To initiate the rundown
described
above,
the system calls the Exit (SEXIT) system
behalf of the process.
In some cases, a process
can
call
occurs.

entered

are

deleted).

user

exception

set size
|

name

names

requests,

its

and

the

default

activities
service on
S$SEXIT
to
for example, if an unrecoverable error
recommended programming practice.

3-48

HOW TO USE SYSTEM SERVICES
SERVICES

PROCESS:- CONTROL

If you
The SEXIT system service accepts a status code as an argument.
use SEXIT to terminate image execution, you can use this status code

If an
argument to pass information about the completion of the image.
image does not call $SEXIT, the current value in RO is passed as the
o
status code when the system calls SEXIT.

This status code is used as follows:

The command interpreter uses the status code to display an
image
following
receives control
it
message when
error
rundown.

@
@

an exit handler, the status code
If the image has declared

written in the address specified in the exit control block.

If the process was created by another process, and the creator
specified a mailbox to receive a termination message, the
has
termination message when the
status code is written in the
process

1s deleted.

The use of exit handlers and termination messages requires
coding

detail

considerations.

below.

3.5.6.3 Exit Handlers image-specific cleanup
image uses system memory
that the data 1is not
error

additional

These considerations are discussed in greater
|

Exit handlers are routines that can perform
For example, if an
or rundown operations.
can ensure
to buffer data, an exit handler
lost when the image exits as the result of an

condition.

To establish an exit handling routine, you must set up an exit control
and specify. the address of the control block on the Declare
block,
Exit Handler (SDCLEXH) system service. Exit handlers are called using
you can provide arguments to the exit
standard calling conventions;
The first argument in the control
block.
control
exit
the
in
handler
block argument list must specify the address of a longword for the
system to write the status code from SEXIT.

\"Hfl—-/’

If an image declares more than one exit handler,

the

cbntrol

blocks

‘are linked together on a last-in, first-out basis. After an exit
the control block 1is
handler has been called and returns control,
Exit control blocks can also be removed prior
removed from the list.
to image exit with the Cancel Exit Handler (SCANEXH) system service.

Exit handlers can also be declared from system routines executing in
supervisor or executive modes. These exit handlers are also linked
together, and receive control after exit handlers declared

mode have been executed.

from

user

~ HOW TO USE SYSTEM SERVICES
PROCESS

Figure

3-14

shows.
an example

EXITELOCK $

STATUS?

(1)

exit

handling

+LONG

EXITRTN

AONG

LONG

SBTATUS

JBLKL

"M<R2sR3>

USES

s ADDRESS

ERROR

THIS

EXIT
ARGS

FOR

JAIDRESS

RECEIVE

CODE

FROM

MASK

FOR

FOINTER

HANDLER

5STATUS

sENTRY

HANDLER
STATUS

CODE

$EXIT

FEGASUS

$DECLARE EXIT HANDLER

RET

SEND OF MAIN ROUTINE

EXITRTNG
@ :WORD

"MuR2:

CMFL.
REQL.

STATUS » #55$_NORMAL
10%

SEXIT

HANDLER

FENTRY

MASK

s NORMAL. EXIT?
3 YESy FINISH

‘

10%3

sSYSTEM

s NUMBER

$OCLEXH.S DESELK=EXITELOCK@
ESEW

routine.

SEXIT CONTROL RLOCK

+WORD

of an

SERVICES

LONG

FEGASUS?:

CONTROL

iNO»

RET

CLEAN

s FINISHED

Notes:

€@

EXITBLOCK is the exit control
EXITRTN.
arguments

The

third

to be

passed;

1s
passed.
to store the
provided

This is
return
an

exit

block

for

the

exit

handler

longword
1indicates - the
number
of
1in this example, only
one
argument

the address of
status
code;
control

a longword for the system
this
argument
must
be

block.

The $DCLEXH system service call designates the address of the

G’

EXITRTN checks the status code.

exit
control
handler.

block,

EXITRTN
returns
condition.

Figure

3.5.6.4

Forced

Exit

3-14

For

in the process CYGNUS

CYGNUS:

DESCRIFTOR

Force
process to

executing

the

normal

handles

the

exit

exit,

error

Example

process.

example,

If this is

Otherwise,

The

EXITRTN

for

declaring

control.

provides

way

thus

< CYGNUS:

Exit

Handler

Exit

(SFORCEX)
system
initiate image rundown for

following

call

exit:

y FROCESS

$FORCEX

service

another

causes

the

1image

cause

the

image

NAME

$FORCEX..S FRONAM=LCYGNUS
The

SFORCEX

system

service

exit.

process CYGNUS

the

cannot be forced to
AST
delivery,
and
Section

3.2.

exit
how

uses

the AST mechanism
has

disabled

AST

delivery,

the

image

until CYGNUS reenables the delivery of
ASTs.
it is disabled and reenabled, is described in
|
3-50

HOW TO

USE

PROCESS

3.5.7

SYSTEM SERVICES

CONTROL

SERVICES

Process Deletion

Process

deletion

Deletion

completely

removes

command_ stream

contains

occurs

The

result

any

the

process

following

from

the

conditions:

LOGOUT

command

end-of-file.

image

the

specified

Delete

SCREPRC

exits.

A process issues a STOP command or

‘calls

system.

Process

(SDELPRC)

executes

system service.

image

that

When the system is called to delete a process as a result
of
any
of
the
above
conditions,
it
first locates all subprocesses, searching
hierarchically.
Then,
beginning with
the
lowest
process
1in
the
hierarchy, and
completing
with
the
topmost
process,
each of the
following are performed:
|
®¢

The image executing
1in
the
process
1is
run
down.
System
resources
are
released, and, if this is a subprocess, quotas
are returned to the creator of the process. The image rundown
that
occurs
during
process
deletion
1is
the
same as that
described in Section 3.5.6.1.
When
a
process
1is
deleted,

however,. the rundown releases all system resources, including
those acquired from access modes other than user mode.

Resource quotas
a

subprocess.

are

released

the creating process,

If the creating process specified
a
termination
mailbox,
a
message
indicating
that the process is being deleted is sent
to the mailbox.
For detached processes created by the system,
the

termination message

sent

to the

system

job

controller.

The cpntrbl region of the process's virtual address

All
system-maintained
deleted.

deleted.
(The control region consists of memory
used by the system on behalf of the process.)

Figure 3-15 illustrates
process deletion.

the

information

flow of

events
:

about
"

from

the

image

space

1is

allocated

and

process

exit

through

HOW TO

USE SYSTEM SERVICES

PROCESS

CONTROL

SERVICES

Image exit

Any

exit handlers

~ for user
mode?

Call them, In LIFO order,

‘using argument list in exit
control block

process using

the command
interpreter?

Call the Delete Process

(SDELPRC) system service
to delete the process

Did

Call the exit handler
declared by the

command interpreter”®

creator specify
a termination
mailbox?

\
Return to command

Send a termination message

interpreter to execute

to the mailbox specified by

the next image

the process’s creator

*This exit handler is declared

Deletion

from supervisor mode and is

complete

located during the normal
search for exit handlers.

Figure 3-15

Image Exit and Process Deletion

HOW TO USE SYSTEM SERVICES
PROCESS

CONTROL

SERVICES

3.5.7.1
itself

The Delete Process
System
Service - A
process
can
delete
or
another process at any time, depending on the restrictions
outlined in Section 3.5.4.1.
The
Delete
Process
(SDELPRC)
system
service
deletes
a process.
For example,
if a process has created a
subprocess named CYGNUS, it can delete CYGNUS as shown below:

CYGNUS?! DESCRIFTOR fiCYGNUS?

$DELFRC.S FRCNAM=CYGNUS
Since a subprocess is automatically
deleted
when
the
image
executing
terminates (or
when
the
command
stream for the

interpreter
the SDELPRC

reaches end-of-file), you do not normally
system service explicitly.

it
is
command
to
issue

need

As an alternative to deleting a process, you can use
the
Force
Exit
(SFORCEX) system service to force the exit of the image executing in a
process.
If the SFORCEX system service is
wused,
any
exit
handlers

that are declared

for

the

image

are executed during the

image

rundown.

Thus, if the process is using the command interpreter,
it
1is
not
deleted,
but
<can
run
another
image.
Moreover, since the SFORCEX
system service uses the AST mechanism, the exit cannot be performed if
the process being forced to exit has disabled the delivery
of ASTs.

3.5.7.2
Termination
Mailboxes - A termination
mailbox
provides
a
process
with
a way of determining when, and under what conditions, a
process that it has created is
being deleted.
The
Create
Process
(SCREPRC)
system
service
accepts the unit number of a mailbox as an
argument.
When the created process is deleted, the mailbox receives a
termination message.
|
The

first word

constant,

message.

the

MSG$ DELPROC,

termination

which

The remainder
of

the

message

indicates

message

contains

that

contains

the

1is a

system

symbolic

termination

accounting

information
used
by
the job controller,
and is in fact identical to
the first part of the accounting record sent to the system
accounting
log
file.
The complete format of the termination message is provided
with the description of the $CREPRC system service
in Chapter 4.

The

creating

process

can,

1if

necessary, determine

the

ptoéess

identification
of the process being deleted from the I/0O status block
posted when the message
1is
received
in
the
mailbox.
The
second
‘longword
of
the
IOSB
contains
the
process
identification of the
process that is being deleted.
Figure 3-16 illustrates a complete sequence of process creation,
with
a
termination
mailbox.
The
Create
Mailbox
and Assign
Channel
(SCREMBX) and Queue
I/0 Request ($SQIO) system services
are
described
in- greater detail in Section 3.4.
|
|

"HOW

USE

SYSTEM

PROCESS CONTROL
EXCHAN?

+ BLKW

SERVICES

FGET

EXITRUF§

CHANNEL

sDESCRIFTOR

« LLONG

ENDRUF-RBRUF

yLLENGTH

+ L.LONG

ERUF

s AIDRESS

+ BLKR

LDIREN.. LENbTH

s RUFFER

. BLKE
EXITMSG:

ACCHK. . TERMLEN

s RUFFER

. BLKW
MEXIOSE?
+BLKW
MERLEN?

y QUADWORD

yLENGTH

+ BLKL
- MEBFID?
ILYRAFID:?
«LLONG

yRECEIVES

¢
BERUF

NO.
FOR

MAILROX

INFO

BUFFER

RUFFER

FOR

MAILROX

MESSAGE

I/0 STATUS

RLOCK

ENDERUF
$

DESCRIFTOR

I-YREXE:

I/0

FID

FROCESS

DELETED

sGET FID OF SURFROCESS
s NAME OF IMAGE FOR SURFROCESS

SILYRA EXE

+
¢

()$C&EMme S CHAN=EXCHANy MAXMSG=%#120y FROMSK=#0
y CREATE

RUFQUO=%240

MAILBOX

BSEW

ERROR

HqBH

ERROR

RSEW

IMAGE=LYRFXEvFIDfiDR LYRAFID, -~
P oo
rCREATE SURFROCESS
HBXUNTmBBUF+DIB$N“UNIT s SFECIFY TERMINATION
|
EERROR

€©:GETCHN.-5 CHAN=:EXCHAN » thBUF=EXITRUF
s GET

MAILEBOX

INFO

@$CREFRC.. S

Q:nro-s

CHAN=EXCHANyFUNC #I10% _READVRIL.Ky
yQI0

MAILROX

MATLROX

ASTADIR=FX[TASTyIUQBuMBXIOSByFIhY[TM%va’=ACCSK_TERMLEN
ERROR

BESEW

sCONTINUE

EXECUTION

EXITAST!

RET

$AST

JWORD

CMFW
ENEQ

ENEQR
CMPL
BNER

TERMINATION

M50

y
#5554 NORMAL
MEXITOSE
20%

170 SUCCESSFULT
s RRANCH IF NOT

20%

FNOy

SOME THING ELSE

LYRAFIIy MEFID
20%

s I8 IT LYRAT
sNQy SOMERODY ELSE

sYESy

EXTTMEG+ACC$L“FINALTS #8554 NORMAL, sDELETED NORMALLY?

CMFL
*

FOR

» #MSGSDELFROC IS8 IT A TERMINATION MSGT
HACCEW
_MSGTYF
EXTTMEG

CMFW

REQL

ROUTINE

JENTRY MASK

sNOy

RETURN

TO ERROR IN LYRA
RESFOND

sAST ROUTINE FINISHED
sHANDLE AlLL OTHER CONDITIONS

RET

Figure

3-16

Using

Termination Mailbox

HOW TO USE SYSTEM SERVICES
PROCESS CONTROL

SERVICES

on Figure 3-16:
Notes

The

Create

service

Mailbox

creates

at EXCHAN.

and Assign

Channel

system

($CREMBX)

the mailbox, and returns the channel number

The Get I/O Channel Information (SGETCHN) system service
The information
returns information about the mailbox.
returned in the buffer can be referred to by the symbolic
|

offsets defined in the SDIBDEF macro.

The Create Process (SCREPRC) system service creates a process
and returns the process
to execute the image LYRA.EXE,

identification at LYRAPID. The MBXUNT argument refers to the
unit number of the mailbox, obtained from the buffer BBUF by
|

using the symbolic offset DIBSW_UNIT.

The Queue I/0 Request queues a read reguest to the mailbox,
specifying an AST service routine to receive control when the
mailbox receives a message and the address of a buffer to
receive the message. The information in the message can be
accessed by the symbolic offsets defined 1in the SACCDEF
macro.

The process continues executing.

' When a message is received in the mailbox,

the

AST

service

recelives control. Since this mailbox can
routine, EXITAST,
ess communication, the AST routine
interproc
other
for
used
be

checks:

1) for successful completion of the I/O operation by

that the message
2)
examining the first word in the IOSB,
is a termination message by examining the message
received

offset
the
type field 1in the termination message at
ACCSW MSGTYPE, 3) the process identification of the process

that has been deleted by examining the second longword of the
the completion status of the process by
IOSB, and 4)
examining the status field in the termination message at the
of fset ACCSL_FINALSTS.

In this example, the AST

service

routine

performs ~special

action when the subprocess is deleted. All other messages Or
error conditions cause a branch to the label 20S.

HOW

3.6

USE

SYSTEM

SERVICES

TIMER AND TIME CONVERSION SERVICES

Many applications
on
clock
time.

specific

time

require
In

the

day,

Schedule

the

setting

asynchronous
cancel

cancel

event

flag or

the

(AST)

for

current

that

has

for

wakeup

and

honored.

process,

has

process,

not

unique

ASCII string

Convert the time from system format to integer values

system

time

value

into

ASCII

been

64-bit

Convert

and

yet

string

describes the system time format and
the
services
examples of scheduling program activities u51ng the

that
timer

The System Time Format
maintains

the

current

64-bit

format.

The

time

_units

offset from the

o'clock,

absolute

Absolute
®

delta

times

can

also

system

time

specify

will

the

always

Binary

converts

time

string

24-byte

ASCII,

code

the

date

24-hour

number

and

time value

time,

can

a specific date
positive values.

clock)
in
100-nanosecond

which

00:00

to system services
expressed

and

time

as:

Time
in

address

time

current

value

date

and

time

day.

hours,

Delta

this

case

default

and Time
to

system

buffer.

$ASCTIM

the

ASCII

String

format

want

system

you

service

an
as

7his is the Smithsonian base date and

calendar.

(using

and

supply

The Current Date

Convert

time

binary

future
offset
(number
of
SO0
on) from the current time.
always expressed as negative values.

seconds,

are

is
always

which

time values passed

which

are

and
is

base

All

format.

times

minutes,

3.6.2

system

64- blt

date

value

Novembe
17,
r 1858.1

also

that

format

VAX/VMS

The

been

Timer

gueueilng

hibernating

the time

for

1interval.

Convert an ASCII string into the system time format

3.6.1

the

yet

based

events

services. .

‘You

not

Obtain the current date and time in an

This section
use it, with

must

time

the

request

The timer services require you to spe01fy
format.
Time conversion services:

system

activities

schedule

honored.

can

trap

request

pending

program

specified

request

wakeup

1image

system

pending

Schedule

after

services:
)

scheduling

VAX/VMS,

(SASCTIM)
ASCII string

obtain

the

system
and

current

follows:

time

for

service
returns the

the

time

astronomical

HOW TO USE SYSTEM SERVICES
TIMER AND TIME CONVERSION SERVICES

ATIMENOW ¢

JLLONG
+ LONG

+ BLRE

1043

20%$-10%
10%

o
|

FOR ASCII TIME
sIESCRIFPTOR
sLENGTH OF BUFFER
OF RUFFER
sADDRESS

324 BYTES RETURNED

3
20%
*

HASCTIM.S TIMBUFATIHENON:* y GET CURRENT TIME
TIMLEN:ATIMENUN

The strlng returned by the service in the buffer ATIMENOW~.has‘ the
-

format:

dd—mmm?yyyy hh:mm:ss.cc
the

where dd is the day of the month, mmm

month

3-character

alphabetic abbreviation), yyyy 1is the year, and hh:mm:ss.cc is the
The
time in hours, minutes, seconds, and hundredths of seconds.
string
the
of
length
the
place
to
system
the
TIMLEN argument requests
returned in the first word of the descriptor.

The current time can also be obtained in system format
system

Time

($SGETTIM)

buffer.

For example:

TIMES?

+ BLKQ

service,

the

Get

‘

s RUFFER FOR TIME

with

which places the time in a qguadword

yGET TIME

$GETTIM..S TIMADR=TIME

This call to SGETTIM returns the current date and time system format
in the quadword buffer TIME.

3.6.3

Obta1n1ng an Absolute Time in System Format

The converse of the $ASCTIM system service 1s the Convert ASCII Strlng
to Binary Time (SBINTIM) system service. You provide the service with
the time in the ASCII format shown above, and the service converts the
string to a time value in 64-bit format. You.can then use this
returned value as input to a timer scheduling service.

When you code: the ASCII strlng buffer, you can omit any of the f1elds,
and the service uses the current date or.‘time value for the field.
Thus, if you want a timer request to be date 1ndependent you = could
format the input buffer for the SBINTIM service as shown below. The
two hyphens that are normally embedded in the date field must be
.
included; at least one blank must precede the tlme f1eld
ANOON 3

BNOON ¢
.

9ASCII 1“ NODN

DESCRIPTDR i*“ 13300.00.00;

LERLRKA
S

s RUFFER FUR BINARY 12

!NUON

SEINTIM_S TIMRUF=ANOONsTIMADR=ENOON

$CONVERT TIME

\@.ww“ ,

When the SBINTIM service completes,. a 64-bit time value
"noon today" is returned in the quadword at BNOON.

representing

HOW TO
TIMER

3.6.4

Obtaining

AND

a Delta

USE
TIME

Time

SYSTEM SERVICES
CONVERSION

System

SERVICES

Format

The $BINTIM system service also converts ASCII strings to
delta
values
to
be
wused as input to timer services.
The buffer for
time ASCII strings has the format:
dddd

hh:mm:ss.cc

The first field, indicating
if you are codlng a "today"

the number of
delta time.

The following example shows how to
delta time in system format.
ATENMIN:

time
delta

DESCRIFTOR

RTENMIN?
L BLKQ

use

days,

the

must

S$BINTIM

00:10:00,00

service

yASCIT
-

specified

TEN

y BUFFER

obtain

MINUTES

FOR

RINARY

TEN

FMINUTES

+
¢

$BINTIM.S
You

can

using

also

two

specify

MACRO

100-nanosecond
1l

TIMRUF=ATENMINy TIMAIR=BTENMIN

second

approximate

.LONG

units.
= 10

directives

The

delta
to

values

represent a

arithmetic

million
* 100

time

iCUNUERT‘TIHE

based

assembly

time value

the

nanoseconds

JLONG

“10*1900*1000*5?“1

The value 10 million 1s expressed

Note

that

the

delta

time

value

yFIVE

. In

terms

1l00-nanosecond

time

values,

3.6.5

T1mer Requests

Timer

requests

queued,

that

expiration
process

10*1000*1000

this

that

with

the

Set

1s,

they

are

ordered

The

have

pending

TQELM
in

Timer

quota
this

than

time

request

processed,

)

The

number

you

flag

a delta

you

can

do not

time

the

flag
specify an

the
a

maximum

longword.

minutes.

system

service

according

number

specify

Depending

elther

event

are
their

entries

queue.

value.

specify

processing

controls

expressed

(SSETIMR)

for

timer

limited

When you code the SSETIMR system service, you can
absolute

for readability.
|

are

can

somewhat

made

times.

can

units

SECONDS

negative.

If you use this notation, however, you

number

FIVESEC:

formula

For example, the following statement defines a delta time value
seconds:

time,

terms

both

to be

set

event

flag,

on
of

when

either

how you

the

want

the

follow1ng

the

time
explres.
system sets event

The address of an AST service routine to be executed when the
time

Optionally,
request.

necessary.

expires.

you
You

The

can
can

specify
wuse

request

this

request

identification

1dent1f1cat10n

passed

for

cancel

the

timer

request,

AST

service

HOW
TIMER

routine,
routine

Figure
ASTs.

TO USE

AND

TIME

SYSTEM

SERVICES

CONVERSION

SERVICES

1f one 1is specified, as the AST'parameter'so the AST service

can

identify

the

timer

3-17 shows examples
Event
flags
and

detail in Section 3.1,
detail in Section

request.

of timer requests
wusing
event
flag
services are

event
flags
described in

and
more

"Event Flag Services." ASTs
are
described
1in
"AST (Asynchronous System Trap) Services."

3.2,

Example 1l: Setting an Event Flag

WATTIME¢

LONG

~10X1000%X1000%30y -1

$30 SECOND WAIT TIME

"$SETIMRwS EFN=%4yDAYTIM=WAILTIME
BSRW

ERROR

ESEW

ERROR

$SET TIMER
|

¢,$WAITFRMS EFN=%4

sWAIT 30 SECONDS
-

]

B
+

Notes

Example

1l:

(1}

The call to $SETIMR requests that event flag 4 be set

t’

The Wait for

seconds

(expressed

Single

places
the
process
set.
When the timer
continues

the

guadword WAITIME).

Event

Flag

(SWAITFR)

system

1in a wait state until the event
expires, the flag is set and the

execution.

Figure 3-17

;

Timer Requests

service
flag is
process

HOW TO
TIMER AND

Using

USE

SYSTEM SERVICES
CONVERSION SERVICES

TIME

Example

ANOON:

DESCRIFTOR <-- 12:00:00.00:>

BNOON:
- WRBLKQ

an AST Service

Routine

5ASCII NOON

s RINARY NOON

@ +EINTIMN.S TIMRUF=ANOON
RSEW

TIMADR=ENQON

§CONVERT TIME

ERROR

$SETIMR..S

DAYTIM= BNUON!fiSTADR“fiST&LRU!REGIDT#1”

ERROR

RSRW

ASTSERV

+ WORI

CMFL.
REQL.

SENTRY MASK

s CHECK AST FARAMETER
GO TO NOON ROUTINE

s SERVICE NOON REQUEST

1042

#12s40AF)
10%

RET

The call to S$BINTIM converts the
12:00

used

noon

1nput

system

the

format.

ASCII

The

string

representing

value returned in

BNOON

will

SSETIMR system service.

The AST routine spec1f1ed in

the

S$SETIMR

request

called
when
the timer expires, that is, at 12:00 noon.
The
REQIDT argument identifies
the timer
request.
The
process
continues
execution;
when
the
timer
expires,
it
1is
interrupted by the delivery of the AST.
Note
that
1if
the
current
time
of
day
1s
©past
noon,
the
timer
expires
immediately.

‘,

This AST service routine checks the parameter passed

the

REQIDT

that

must

AST

service

argument

service

the

and

12:00

determines,

noon

routine

completes,

point

interruption.

Figure

3-17

timer

the

1in

this

request.

process

example,
When

continues

the

execution
at

: ’w:a-—.fi-/

on Example

Notes

the

(Cont.)

Timer

Requests

3.6.5.1
Canceling Timer Requests - The Cancel Timer Request ($SCANTIM)
system
service cancels
timer
requests
that
have
not
yet
been
processed.
The
entries
are
removed
from
the
timer
queue.
Cancellation is based on the request identification given in the timer

request.

For

3-17,

Figure

example,

to cancel

you would

code:

the

request

illustrated

in Example

If you assign the same identification to more than one timer
request,
all
requests
with
that
identification
are canceled.
1If you do not
specify the REQIDT argument, all your requests are canceled.

‘).—..,.../ w

FCANTIM..S REQIDOT=#12

HOW TO USE SYSTEM SERVICES

‘_

TIMER

AND

3.6.6

Scheduled Wakeups

Figure
period

3-17

showea

time

for

process

CONVERSION

SERVICES

a process placing itself in
wusing the $SETIMR and $WAITFR

to make

hibernates

TIME

itself

1ssuing
reversed by

inactive

wait
state for
a
services.
Another way

hibernating.

the

©process

Hibernate
(SHIBER)
system
hibernation is
a wakeup request,
which
«can
be
immediately with
the
SWAKE
system
service,
or scheduled
Schedule Wakeup (SSCHDWK)
system service.
The

follow1ng

prior

example
hibernating:

shows

process

schedullng

ATENSE
! DESCRIFTOR
C <0 00:00:10.,00%
RTENSEC ¢

wakeup

effected

with

for

the

1itself

;10 SECOND WAIT TIME

JRLKR

service:

sRINARY

TEN

SECONDS

$BINT[H S5

TIMRUF=ATENSECy TIMADR= BTFNSFC

y CONVERT

$SCHIOWK.S

DAYTIM=RTENSEC

ySCHEDULE

$HIBER .S

Hibernation
"Process
can

wakeup

Control

wake

processes

wakeups.

specify

and

3.6.6.1

the

when

wakeup

for

that

another

activity

you

code

request

pending
Cancel Wakeup

but

The

example shows

SSCHDWK

CYGNUS,

system

minute
and
every minute

and

system

the

service

yet

the

thus,

fixed

can

3.5,

process

cooperating
and

scheduled

service,

you
can
1ntervals.

time

Scheduled wakeup

processed

scheduling

of wakeup

cancellation

example

specifies

of one minute;
are canceled.

~CYGNUSE

« LLONG

Section

hibernation

SECONDS

requests

that

canceled w1th

the

service.

subsequent

this

system

repeated

WAKE

TEN

privileged

process;

$SCHDWK

been

an
interval
time
until the requests

DFQCR[FTOR

INTERVAL :

not

(SCANWAK)

following

process,

have

detail

suitably

using

Canceling Scheduled Wakeups -

are

CYGNUS?

Note

a wakeup

synchronize

Moreover,

that

described

Services."

schedule
can

are

y SLEEF

TIME

the

delta

for

wakeups.

The

time

one

wakeup

repeated

sFROCESS NAME
sDELTA

~1OX1000X1000%460y~1

requests

s ONE

TIME

MINUTE

FECHIWK..S

FRONAM=CYGNUSyDAYTIM=INTERVAL
s REFTIM=INTERVAL

$CANWAK..S PRCN&H%CYGNUS‘

3.6.7
The

Numeric

and ASCII

Convert Binary Time
converts
'a time in the
service returns each of

hour,

y CANCEL WAKEUFS

Time
to Numeric
Time
($SNUMTIM)
system
service
system format into binary integer values.
The
the components of the time (year, month,
day,

and
so
on)
1into a separate word of
SNUMTIM system service and the format of the
described in Chapter 4.

seven-word

information

buffer.

The

returned

are

HOW TO USE SYSTEM SERVICES

TIMER AND

TIME

CONVERSION

SERVICES

When you need the time formatted into ASCII for inclusion in an output
string,
you
can use the $ASCTIM system service.
The $ASCTIM service
accepts as an argument the address of a
quadword
that
contains
the
time in system format and returns the date and time in ASCII format.
If you want to include the date and time in a
character
string
that
contains
additional data,
you can format the output string with the
Formatted ASCII Output (SFAO) system service.
The $FAO system service
converts
binary
values to ASCII representations,
and substitutes the
results in character strings according to directives
supplied
1in
an
input
control
string.
Among these directives are !%T and !%D, which
convert a gquadword time value to an ASCII string
and
substitute
the
result
in an output string.
For examples of how to do this, see the
discussion of

$FAO

in Chapter

HOW TO USE

3.7

SYSTEM SERVICES

CONDITION HANDLING SERVICES

Exceptions
interrupt

are

hardware-

the

execution

things as arithmetic overflow
or
opcode

operand

software~detected
image.

Exceptions

underflow

conditions

are

conditions,

caused

that
such

reserved

faults.

Condition handlers are procedures

that

are

given

control

when

exception
condition occurs.
If you determine that a program needs to
be informed of particular exception conditions so that it can
perform
corrective
action, you may want to code a condition handling routine.
This routine, or condition handler, then
receives
control when
any
type of exception occurs.
|
If an exception occurs, and no condition handler exists,
the
default
condition
handler
established
by
the
command interpreter is given
control.
This handler issues a descriptive message
and
performs
an
exit on behalf
of the image that incurred the exception.
This section describes how the condition handling mechanism
works, and explains how to write a condition handler.

3.7.1

Types

in VAX/VMS

of Exception

Exception conditions can be generated
by:
e

Hardware

Software

System

service

failures

Hardware—-generated exceptions always result
special
action
1f
program
execution
1s
hardware exceptions is given
in Table 3-5.

in conditions that
to
continue.
A

require
list of
|

\._//

Some software routines can generate exception conditions;
these
may
be
warning
or
error
conditions.
(These
software
<conditions are
documented with the descriptions of any software that cause them.)
Software exceptions can also occur
when
an
error
oOr
severe
error
status 1s returned from a call to a system service.
You can choose to
handle error returns from
system
services
by
using
the
condition
handling
mechanism
rather than other error checking methods.
If you
want exceptions generated by service failures, you must enable
system
service
failure
exception
mode
with the Set System Service Failure
Mode (SSETSFM) system service.
For example:
$SETSFM..S

ENRFLG=%1

System service failure exception mode is initially disabled,

" be enabled or disabled at any time during

the execution of

and

may

image.

HOW

USE

CONDITION

SYSTEM

SERVICES

HANDLING

SERVICES

3.7.1.1
Change Mode and Compatibility Mode Handlers - There
are
two
types
of
hardware
exception
that
can be handled in a special way,
bypassing
the normal condition handling mechanism
described
1in
this
chapter.

These

are:

Traps caused
by
change
supervisor instructions

Compatibility mode

mode

wuser

change

mode

faults

You can use the Declare Change
Mode
or
Compatibility
Mode
Handler
(SDCLCMH) system
service
to establish procedures to receive control

when one of

3.7.2

these conditions occurs.

in Chapter

described

$DCLCMH

system

service

1is

How to Specify Condition Hahdlers

You can establish condition handlers
of

The

an exception
1.

two ways:

receive control
o

By specifying the address of the
handler in the first longword of

By establishing exception

Vector

(SSETEXV)

system

The first of these methods
condition
handler
for
a

entry mask
a procedure

vectors

service

the

event

of
a
<condition
call frame

with. the

is
the
most
common
way
particular
1image.
It
1s

efficient way in terms of declaration.

Set

Exception

to
specify
a
also the most

You only have to use a

single

move address instruction to place the address
of the condition handler
in the longword pointed to by the current
frame
pointer
(FP).
For
example:

MOVAL

HANDLER
y (FF)

Each procedure on the call stack can declate a condition handler.
The SSETEXV system service allows
you
to
specify
addresses
for
a
- primary
exception
vector,
a
secondary exception vector, and a last
chance exception vector.
Vectors may be
specified
for
each
access
mode.
The primary exception vector 1is reserved for the debugger.

An address of 0, in the first longword of a proCedure call
in an exception vector,

the

respective vector

3.7.3

frame,

indicates that no condition handler exists
call

frame.

for

The Exception Dispatcher

When an exception condition occurs, control is'passed to the operating
system's

exception

dispatching

routine.

The

exception

dispatcher

HOW TO USE SYSTEM SERVICES
CONDITION HANDLING SERVICES

searches for a condltlon handling routlne using the

following

order:

The primary exception vector for the access mode at which the
program was executing when the exception occurred.

The secondary exception vector for the access mode

The condition handler address specified in the procedure call
stack
of
the access mode at which the program was executing

the program was executing when the exception occurred.

when the exception occurred.
Call frames on
the
stack
scanned backwards, using the saved frame pointer in each
frame to refer to the previous call frame.

which

are
call

The last chance exception vector for the access mode at which
the program was executing when

the exception occurred.

The search
1is
terminated
when
the
dispatcher
finds
a
condition
handler.
If
the
dispatcher
cannot find a user-specified condition
handler, it calls the default condition
handler
established
by
the
command
interpreter,
1if
the
1image
was
initiated
by
the command
interpreter.
The default
handler
1issues
a
messade
and
either
continues
program
execution
or performs
an
exit on behalf of the
process, depending on whether the condition was a warning or an error
condition, respectively.
|
The search can also be terminated when the dispatcher detects a
saved
frame
pointer containing
a
0
(that
1is, it reaches the end of the
stack), or when an access
violation
occurs.
In
these
cases,
the
system
performs
an exit for the process, with the return status code
SS$ NOHANDLER indicating "absence of condition handler" (for a 0 frame
p01nter)
or
SS$_ACCVIO
indicating
"bad
stack"
(for
an
access

violation).

Figure 3-18 1llustrates the exception dlspatcher s search of the
stack

for

an exceptlon handler.

call‘

HOW TO

USE

CONDITION

SYSTEM

HANDLING

SERVICES
SERVICES

0
FP
|
P

Condition
Occurs

rocedure

FP
Procedure

B
]

HANDLERA |
P

Procedure

Condition

Handler Found

Figure

3-18

Stack

for

Condition

Handler

Notes on Figure 3-18:
1.

The

illustration of the

sequence:

Procedure

‘called

Procedure
handler.

«call
A

stack

called

Procedure

indicates

Procedure
A

the

and

established

calling

Procedure
a

condition
|

An exception condition occurs while Procedure
C is executing.
The

exception

dispatcher

searches

for

condition

After

checking
for
a
condition
handler
exception
vectors
(assume
that none has
this process), the dispatcher looks at the

Procedure

condition
the

call

(FP)

C's

call

handler
frame

Procedure

condition handler,

has
for

frame.

value

been specified.
Procedure B by
C's
call
frame.

handler.

declared
1in
been specified
first longword
0

indicates

The dispatcher
using the frame
Again,

and locates Procedure A's call

that

locates
pointer

finds

frame.

The dispatcher locates and'gives control
to HANDLERA.

the
for
of

HOW TO USE SYSTEM SERVICES

CONDITION

3.7.4

HANDLING

SERVICES

The Arqument List Passed to a Condition Handler

When the dispatcher finds a condition handler, it passes control to it
The argument list passed to the condition
a CALLG instruction.
using
of
addresses
handler is constructed on the stack and consists of the

these arguments
arrays, as illustrated in Figure 3-19;
argument
two
are described in detail in Sections 3.7.4.1 and 3.7.4.2.

Signal Array

condition name

first signal argument
Argument
rgument List
List

additior
additional arguments for

condition handler,

2
address of signal array
address of mechanism array

if any

PC
PSL

‘

Mechanism Array

establisher frame
depth

- R1T

You can define symbolic names to refer to these arguments using the
SCHFDEF macro instruction. The symbolic names are:
Symbolic Offset

CHF$L_SIGARGLST

CHF$L_MCHARGLST
CHF$L_SIG_ARGS

CHF$L_SIG_NAME

Figure 3-19

Value

Address of signal array

Address of mechanism array
Number of signal arguments

Condition name

CHF$L_SIG_ARG1

First signal-specific argument

CHFSL_MCH_ARGS

Number of mechanism arguments

CHF$L_MCH_FRAME
CHF$L_MCH_DEPTH
CHF$L_MCH_SAVRO

Establisher frame address
Frame depth of establisher
Saved register O

CHF$L_MCH_SAVRI1

Saved register 1

Argument List and Arrays Passed to Condition Handler

3-67

HOW TO USE SYSTEM SERVICES
CONDITION

HANDLING

3.7.4.1
Signal Array Arguments - The
describing the exception condition.
These

SERVICES

signal

array

contains

values

are:
1.

Condition

name —-- the
exception
condition.
symbolic definitions,

Additional

arguments

condition.
Table
provided with each

symbolic

value assigned to the specific
The
possible
conditions,
and their
are listed in Table 3-5.
|

—--

specific

information

relating

3-5
also
shows the additional
exception condition.

PC -- the program counter
at
the
time
of
Depending
on the type of exception (fault or
be the address of the instruction that caused
or the following instruction, respectively.

PSL -- the processor

status

exception.

3.7.4.2
context
1.

longword

the

arguments

the
exception.
trap), this can
the
exception,

the

time

the

Mechanism Array Arguments - The mechanism array describes the
in which the condition occurred.
The arguments supplied are:
Establisher frame -the
call frame that

the address

handler

Figure

Procedure

address.

3-18,

the frame pointer (FP) register image of
established the condition handler.
This

the
For

this

1longword
example,

argument

points

the

condition

that

incurred

display

frame number
handler,

the

stack

the

<call

local

condition
1s

as shown
frame
for

variables

the procedure

relative

exception.

follows:

the

The

that

frame

depth

the

handler, if the
the procedure.

1is

established
the

procedure

determined

Meaning

-3

Condition

chance exception vector

-2

Condition

the

call

that
established
the
condition
are at known offsets from the FP of

Depth
-- the

Depth

the

'This value can be used to
procedure
variables

containing

handler

was

established

the

1last

©primary

exception vector

-1

Condition handler was established in the secondary
exception vector

Condition handler was
that was

active

Condition

the

frame

when

established
the

handler

was

that

was

exception

established

active

the

frame

occurred

by
when

the

caller

of
exception

occurred

Condition handler was established by the caller‘of

‘the
caller of the
exception occurred
and

on.

3-68

frame
,

that was

active when

the

HOW TO USE SYSTEM SERVICES

CONDITION

For example,
the

depth

the

HANDLING

call

argument

stack

passed

SERVICES

shown

HANDLERA would

Figure

have

3-18,

value

The condition handler can
use
this
argument
to
determine
whether
it
wants to handle the condition.
For example, the
handler

may not

want

did

occur in

the

not
--

the

handle

the

establisher

contents of

condition

the

condition

exceptlon

condltlon

frame.
when

the

occurred.

Rl -- the contents of

occurred.

3.7.5

After

Courses

of Action

for

the condition handling

exception,

can

take

one

the

Condition Handler

routine
the

determines

following

the

courses

nature

action:

the

Continue

- The condition handler may or may
not
be
able
to
£fix
the
problem
but the program can continue execution.
The handler
places the return status value SS$ CONTINUE in RO and
1issues

RET

instruction

return control

the dispatcher.

The

exception dispatcher returns control to
the
procedure
that
incurred
the
exception,
at the instruction that caused the
exception.
If the exception was
a
fault,
the
instruction

that

caused
it is reexecuted;

the exception was a trap,

control 1is returned
at the instruction following the one that
caused
1it.
(In the case of a trap, the instruction causing
the trap can sometimes
be
re-executed
by
subtracting
the
length of the instruction from the PC in the signal array.)
Resignal
The

handler cannot

that
1t
does not
SS$ RESIGNAL in RO

control

fix

the

problem,

this

condition

one

handle.
It places the return status value
and issues a
RET
instruction
to
return

to the exception dispatcher.

The dispatcher resumes

its search for a condition handler, using
the
search
order
described
above.
'If it finds another condition handler, it
passes control to that routine.
Unwind

The condition handler cannot fix the problem,
and
execution
cannot continue using the current flow.
The
handler
issues
the Unwind Call Stack (SUNWIND) system service to unwind
the
call stack.
Call frames may then be removed from the
stack
and

to
Examples

sections.

the

flow of

SUNWIND

these

execution modified,

service.

three

situations

are

depending

shown

on the arguments

the

following

HOW TO USE SYSTEM SERVICES
CONDITION

HANDLING SERVICES

Table

Summary of

Condition

Name/Type

3-5

Exception Conditions

Explanation

SS$_ACCVIO

Additional Arguments

Access violation

(Fault)

Reason for access

violation.

This is a

mask with the format:
Bit 0

= type of

access violation

page
code

table entry
protection
did not permit intended

POLR, P1LR,
violation

access

Bit

SLR

length

page table entry reference
0 = specified
wvirtual
address

not accessible

Bit

0
1l

associated page
not accessible
intended access

table

entry

read
= modify

Virtual
address
attempted
'

which

access

was

SS$_ARTRES
(Trap)

Reserved arithmetic trap

None

SS$_ASTFLT
(Fault)

Stack invalid during
attempt to deliver an
AST

1.
2.
3.

Stack pointer value when fault occurred
AST parameter of failed AST
Program counter
(PC)
at - AST delivery

Processor

5.
6.

SS$ BREAK

Breakpoint

(Fault)

encountered

instruction

interrupt

delivery

status longword (PSL)
interrupt

Program counter

(PC)

have been deliveredl
Processor

to which AST

status longword

(PSL)

AST would have been deliveredl

AST
would

to which

None.

SS$ CMODSUPR

Change mode to supervisor

Change mode code.

SS$ CMODUSER '|
'
" (Trap)

Change mode to user
instruction encountered

The possible values are
Change mode code.
-32768 through 32767.

instruction encountered?

(Trap)

The possible values are

-32768 through 32767.

in the signal array are not included in this argument list.
The PC and PSL normally included

If a change mode handler has been declared for user or supetvisor

The stack pointer of the access mode receiving .this exception is reset to its initial value.
Change

Mode

Compatibility

Mode

Handler

control when the associated trap occurs.

modes

with

the

Declare

($DCLCMH) system service, that routine receives

HOW TO USE SYSTEM SERVICES

CONDITION

Table

HANDLING

3-5

SERVICES

(Cont.)

Summary of Exception Conditions

Condition

Additional Arguments

Explanation

Name/Type

Type of compatibility exception. The possible

Compatibility mode

SS$ COMPAT

condition

can

only

when executing in

compatibility mode.

occur

0 = Reserved instruction execution

1 = BPT instruction executed

2 = IOT instruction executed
3 = EMT instruction executed
4 = TRAP instruction executed
5 = Illegal instruction executed
6 = 0dd address fault
7

TBIT

Decimal overflow

SS$_FLTDIV

Floating/decimal divide by zero

None

Floating overflow

None

Floating underflow

None

Integer divide by zero

None

SS$ INTOVF

Integer overflow

None

SS$_OPCCUS

Opcode reserved to customer

None

SS$ _OPCDEC

Opcode reserved to Digital

None

SS$_PAGRDERR

Read error occurred during

(Trap)

SS$_FLTOVF
(Trap)

trap

None

SS$_DECOVF
(Trap)

values are:

This exception

exception.

(Fault)

SS$_ FLTUND
(Trap)

SSS_INTDIV
(Trap)

‘

(Trap)

(Fault)

fault

an attempt to read a faulted

This is

Translation not valid reason.
a mask with the format:

page from disk

Bit

Bit 1 = page table entry reference
address
virtual
0 = specified
,

not valid

1 = associated page

table

entry

not valid

/,f

Bit 2 = intended access
=

read
= modify

0
1

SS$_ RADRMOD

Attempt to use a reserved

None

SS$ ROPRAND

Attempt to use a reserved

None

SS$_SSFAIL

System service failure (when

Status return from system service (RO)

exception mode is enabled)

mechanism array)

SS$_SUBRNG

Subscript range trap

None

SS$ _TBIT

Trace bit is pending following

(Fault)

addressing mode

operand

fault

occurs.

‘

an instruction

If a compatibility

Compatibility

(The same.value is in RO of the

system service failure

Mode

mode

Handler

handler

has

been

None

declared

with

the

Declare

Change

Mode

(SDCLCMH) system service, that routine receives control when this

HOW TO USE SYSTEM SERVICES
CONDITION

3.7.6

Example

HANDLING

Condition Handling

SERVICES

Routines

Continuing

and

Resignaling

Figure 3-20
shows
two
procedures,
A
and
B,
that
have
declared
condition
handlers.
The
notes describe the sequence of events that
would occur if a call to a system service failed during the
execution
of

Procedure

FGMAS S

+WORD

MOVAL

HfiNDLERAp(FP)"V

$SETHFM..S

CALLG

sENTRY

MASK

sDECLARE CONDITION

s HANDLER

ENBFLG=¥%1

s ENARLE

|
SSFAIL

sEXCEFTIONS

ARGLISTyPGHB‘a

s CALL FROCEDURE R

HANDLERA¢
« WORD

"MaR2

sENTRY MASK
|

MOV

y OF

CHF$L..SIGARGLST(AF) R4
|
|

#S5S5$_
yCHF$L
SSFAIL
_SIG_NAME (R4)

RNEQ

10%

sNO

e
-

MOVZUWL.

JWORD

sENTRY

‘

s OF

CHF $L..SIGARGLST(AF) yR4
|

sGET

BREAK y CHF $L..SIG . NAME (R4)

BNEQ

LO%

sNOy

- 3YESy

#5S$ . CONTINUEsRO

MOVZWL #58%.RESIGNAL »ROE)

Figure 3-20

ADNDR

s RREAKFOINT
GO

SIGNAL.

FAULT?

RESIGNAL

HANDLE

s SIGNAL

EXCEFTION

CONTINUE

SRETURN TO DISFATCHER

$SIGNAL RESIGNAL
yRETURN

DISFATCHER

Examplé of Condition Handling Routines

MASK

HANDLERE

y ARGS

CHMFL

RET

MASK

sENTRY

"MIR2yR3IvR4

MOVL

RET

DISFATCHER

s HANDILER

MOVZWL

RESIGNAL.

“-— Hustem service failure mccur5¢,

EXCEFTION

sDNECLARE CONDITION

+ WORD

104 ¢

CONTINUE

sRETURN

sRETURN
TO

HANDLERBy(FP)"

s SIGNAL

y SIGNAL

"MIR2yR3r R4

MOVAL.
|

RESIGNAL
SSFAIL

sDISFPATCHER

F55% RESIGNAL yRO

RET

HANDILERE

- GO

s EXCEFTION
#SS$_ _CONTINUE RO

RET

FGME::

ySYSTEM SERVICE

s HANDILLE

MOVZUWL.

SIGNAL

sFAILURE®

104

\\h

CMFL.

HANDLERA

sGET ADIDR
y ARGS

HOW TO USE SYSTEM SERVICES

CONDITION HANDLING SERVICES

Notes on Figure 3-20:

Procedure

'HANDLERA.

executes

and

handler

establishes condition

HANDLERA is set up to respond to exceptions caused

by failures in system service calls.

B.
During its execution, Procedure A calls Procedure

Procedure B establishes condition handler HANDLERB.
is set up to respond to breakpoint faults.

HANDLERB
|

While Procedure B 1is executlng, an exceptlon condition occurs
caused by a system service failure.

The exception d1spatcher searches the exception vectors for a
(assume there are none defined), and then
condition handler
HANDLERB is <called with the
stack.
call
the
searches
|

condltlon SS$ SSFAIL.

Since HANDLERB only handles breakp01nt faults, it places the
return value SS$ RESIGNAL 1in RO and returns control to the
exception dispatcher.

- The exception dispatcher resumes its search for a
handler

HANDLERA

and calls HANDLERA.

handles

the

system

service

failure

condition
exception,

corrects the condition, and the return value SS$_CONTINUE in
RO, and returns control to the exceptlon dlspatcher.

The d1spatcher returns control to Procedure B, and
of

Procedure

system service

resumes

failure.

the

execution

1nstruct10n following the

HOW TO

USE

CONDITION

only

the

Stack

third course of action a condition handler can
procedure call stack.
The unwind operation is
be

used
<calling
requires the

when

sequence

control
sequence.

the

The

Call

SERVICES

and

SUNWIND

system

unwind
should
procedure
in

must

exact

point

service

which

accepts

two

The depth to which the unwind
1,

the

control

optional

The address of
is

a location

complete,

is to occur.

to receive

service
calling

return.

arguments:

«call stack is unwound to the caller
that caused the exception condition
If
. the
unwind is to the caller's caller, and so on.

to
and

be restored to an earlier
Moreover,
use of the SUNWIND system
condition handler to
be
aware
of
the

calling
the

take is
complex,

If the

depth

1is

of the procedure
depth is 2,
the

control when

the

unwind

that is, a return PC to replace the current PC
in the call frame of the procedure that will receive
control
when all specified frames have been removed from the stack.
If no arguments are
performed
to
the

condition

handler

returneto
d

- Note

that

the

this

supplied

«caller

that

address

the

issuing

specified

default

SUNWIND

service,
procedure
that

the

and

the
in

S$SUNWIND
the

normal

unwind

service.

return

case

the

established

for

Control

that

unwinding.

results.

~During the actual unwinding of the
examines
each
frame
1in the call
has been

~calls

argument

declared.

the

handler

the

with

signal

«call
stack,
the
unwind
stack to see if a condition
handler has been declared, the unwind
the

array.

this
condition,
it
can
operations required. After
removed

from

the

code
When

SS$ UNWIND
in
a

condition

the

handler

stack.

specifically

any

interpret

returns

status

the

control

values.

SS$

the

routine
handler
routine
name

with

called

any
procedure-specific
cleanup
handler returns,
the
call
frame
is

Thus, in Figure 3-21, HANDLERB may be called a second time,
unwind
operation.
Note
that
HANDLERB does not have to

merely

condition

perform
the

1is

procedure.

Figure 3-21 illustrates an unwind situation and describes some of

possible

the

UNWIND

condition;

the unwind procedure,

the

RET

during the
be able to

instruction

which does not check

The
the

Unwinding

SERVICES

\‘

3.7.7

SYSTEM

HANDLING

HOW TO USE SYSTEM SERVICES

CONDITION

HANDLING

SERVICES

0
FP

Procedure
D

[

-t

P
Procedure

HANDLERB
FP

Procedure
B

)

0
FP

Procedure
A

Notes:

no
that
Assume
shown.
as
1s
stack
call
The procedure
are declared for the process and that the
vectors
exception
Procedure
exception condition occurs during the execution of
D.

Since neither Procedure D nor Procedure C has
condition handler, HANDLERB receives control.

established

no
with
system service
SUNWIND
the
1issues
HANDLERB
If
«call frames for B, C, and D are removed from
the
arguments,
1itself),
HANDLERB
for
the stack (along with the call frame
Procedure A receives
to Procedure A.
returns
control
and
control at the point following

its call to Procedure B.

If HANDLERB issues the SUNWIND system
service
specifying
a
of 2, call frames for C and D are removed, and control
depth
returns

Procedure

Figure

3-21

Unwinding

the

Call

Stack

HOW TO

USE SYSTEM SERVICES
HANDLING SERVICES

CONDITION

3.7.8

Multiple Exception Conditions

It is possible
for a second
exception
condition
to
occur
while
a
condition handler
or
a
procedure
that
it
has
called
is
still
executing.
In this case, when the exception dispatcher searches for a
condition
handler,
it
skips the frames that were searched to locate
the first handler.
|

The search for a second handler terminates in the same mannerv'as

~initial

search,

described

in Section

3.7.3.

the

If the SUNWIND system service is issued by the second active condition
handler,
the
depth of the unwind is determined according to the same
rules followed in the exception dispatcher's search of the stack:
all
frames that were searched for the first condition handler are skipped.

vector,

that

handler

established

must

handle

exception

\""ta-»//

or secondary
condition.

in the primary
the additional

If an exception occurs during»the execution of a

HOW TO USE SYSTEM SERVICES
3.8

MEMORY MANAGEMENT

SERVICES

The
VAX/VMS
memory
management
routines
map
and
control
the
relationship
between
physical memory and a process's virtual address
space.
These activities are, for the most part, transparent
to vyou,
as a user, and to your programs.
However, you can in some cases, make

a program more efficient by explicitly controlling its virtual
usage.

Memory management

services

allow you

to:

Increase or decrease
process's program or

Control the process's working set size
and
the
swapping
pages between physical memory and the paging device

Define disk
the

file

the virtual address
control region

memory

files containing data or

into

the

process's virtual

space available

shareable

address

images and

of
map

space

This section discusses the services that provide
these
capabilities.
However,
before
vyou
use
any
of these services, you should have an
understanding of the VAX-11l memory
structure
and
memory
management
routines.
Where pertinent, virtual memory concepts related to the use
of particular services
are
discussed
1n
this
section.
For
more
background information, see the VAX/VMS Summary Description.

3.83.1

Increasing Virtual Address

Space

The virtual address space of a process

The program

1s divided

into two regions:

(P0)

region contains the

image

<currently

The control

(Pl)

region contains the

information

the control

region.

being

executed.

maintained

by the system on behalf of the process.
It also contains
user stack, which is located at the
1lower-addressed
end
-

Figure 3-22 illustrates the layout of a process's virtual memory.
initial

the
of

The

size of a process's virtual address space depends on the size

the image being

executed.

To facilitate memory protection and mapping, the virtual address space
is
subdivided into
512-byte
units
called
pages.
Using
memory
management services, a process can add a specified number of pages
to

the
end
of
either the program region or the control region.
Adding
pages to the program region provides the process with additional space
for
image execution;
for example, for the dynamic creation of tables
or data areas.
Adding pages to the control region increases the
size
of
the
user
stack.
(The
user stack can also be expanded when the
image

linked.)

The maximum size to which a process can increase its address space
controlled by an entry

in the system authorization file for

1is

the user.

HOW TO
MEMORY

USE SYSTEM
MANAGEMENT

SERVICES
SERVICES

Virtual

Address

00000000

PROGRAM REGION

| |

(PO)

direction of

groyvth

Iength —————— t——-—— —

3FFFFFFF
40000000

CONTROL REGION

(P1)

length—

—

—T —

|
o

direction of
growth

TFFFFFFF
Figure‘3+22

'3.8.2

Layout of Process Virtual Address Space

Increasing and Decreasing Virtual Address Space

The Expand Program/Control Region (SEXPREG) system service adds
pages
to
the
end
of
either the program or control region, and optionally
returns the range of virtual addresses of the new pages.
For example,
if
you
want to add four pages to a process's program region, you can

code a call to the SEXPREG system service as follows:

BREGSFACE $

+ BLKL.

FRETURN START AND END OF NEW FAGES

$EXFREG..S FAGONT=%#4 RETAIR=RBEGSFACE s REGTON=%0 §GET 4 FAGES
To add the same number of pages
specify REGION=#1l.

the

control

region,

you

would

When pages. that have been added at the end of a region are
no
1longer
needed,
they
can be deleted with the Contract Program/Control Region
(SCNTREG) system service.
As for the SEXPREG service,
you
code
the
number of pages you want deleted and the region:
,
’
$CNTREG..S

Note that the

FAGCNT=#4yREGION=#0

REGION

argument for

both

services
1s
optional;
if
not specified,
deleted from the program region,
by default.

3-78

the

S$EXPREG

the pages

are

and

S$SCNTREG

added

to or

HOW TO USE
MEMORY

SYSTEM SERVICES

MANAGEMENT

SERVICES

The SEXPREG and SCNTREG services can only add or delete pages from the
end of a particular region.
When you need to add or delete pages that
are not at the end of these regions, you can use
the
Create Virtual
Address
Space
(SCRETVA)
and
system services.
For example,

Delete Virtual Address Space (SDELTVA)
if you have used
the
S$EXPREG
service
twice to add pages to the program region, and want to delete the first
system
S$SDELTVA
range of pages, but not the second, you could use the
service as shown in the followiling sequence:

REGSFACEA?
BREGSFACER:

«RBLKL
«RLKL

2
2

s START AND END' OF FIRST AREA
ySTART AND END OF SECOND AREA

$EXFREG..S PAGCNT$#4yRETADR#BEGSPACEArREGIUNzio

s FOUR FAGES

ERROR

RSEBUW
]

$EXFREG.S PAGCNT=#3yRETAIR=BEGSFACERyREGION=%#0

THREE FAGES

ERROR

BSRW
+

$DELTVA_S INADR=REGSFACEA SDELETE FIRST4 FAGES
ERROR

BERW

In the above example, the first call to SEXPREG adds four pages to the
program
region;
the
wvirtual addresses of the pages are returned in
the 2-longword array at BEGSPACEA. The second call adds three
pages,
and
returns
the addresses
at BEGSPACEB.
The call to $DELTVA deletes
the

first four pages

3.8.2.1
SEXPREG

that were

added.

Input Address Arrays and
Return Address
system
service
adds
pages to a region,

normal direction of growth for the region.
if requested, indicates the order in which

If the program

If the control
region
1is
expanded,
the
starting
address is higher than the ending virtual address.

is lower

The return address
array,
the pages were added:

)

address

region

Arrays - When
the
it adds them in the

expanded,

the

than the ending virtual

starting‘ virtual

address.

virtual
-

Conversely, the direction
of
contraction
with
the
SCNTREG
system
a higher to a lower address in the program region and
1is from
service
from a lower to a higher address in the control region.

The addresses returned indicate the first'byte in the first page added
or deleted and the last byte

in the last page

When input address arrays are
specified
for
Virtual
Address
Space
system
services

added or deleted.

the
Create
or
Delete
(SCRETVA
and
SDELTVA,

‘respectively), these services add or delete pages beginning
address

specified

with

the

the first longword and ending with the address

specified in the second longword.

HOW TO USE SYSTEM SERVICES
MEMORY

MANAGEMENT

SERVICES

The order 1in which the pages are added or deleted does not have

since

the

these

normal

services

low-order

bits

contain

indicate

the

direction

only

bits

the

byte

add

byte

growth

delete

for

the

whole

region.

pages,

they

the specified virtual address

address).

The

virtual

Moreover,

1ignore
returned

Table 3-6 shows some sample virtual addresses that might be
as input to S$CRETVA or S$SDELTVA and shows the
all pages are successfully added or deleted.

‘Table

return

1010

1670

1000

17FF

1450

1451

1400

15FF

1450

1400

7FFECO010

- Pl

if
.

Arrays

Output Array
Start
~
End

Region

‘specified

address arrays,

3-6

Sample Virtual Address

Input Array
Start
End

the

(the low-order
9

addresses

addresses.

TFFECI1FF

Number

Pages

15FF |
7FFECO000

1
1

Note that if the input virtual addresses are the same, a
single
page
is added or deleted.
The return address array indicates that the page
was added or deleted in the normal direction of growth for the region.

3.8.3

Page Ownership
and Page Protection

Each page
in
a
process's
virtual
address
space
1s
owned
by
a
particular access mode.
The owner 1is the access mode that created the
page.
For example, pages in the program region initially provided for
the
execution
of
an
1image
are owned by user mode.
Pages that the
image creates dynamically are also owned by user mode.
Pages
1in
the
control
region,
except
for the pages containing the user stack are
normally owned by more privileged access modes.
'
Only the owner of a page can delete the page or otherwise
affect
1it.
The
owner of a page can also indicate, by means of a protection code,
the type of access that each access mode will be allowed.

The Set Protection on
Pages
($SETPRT)
system
service
changes the
protection
assigned
to
a page or group of pages.
The protection 1is
expressed as a code that indicates the specific type of access
(none,
read-only,
read, or write) for each of the four access modes (kernel,

executive,

supervisor,

privileged access mode

user).

Only the owner access mode

can change

the protection

for

a page.

When an image attempts to access a page that is protected against
the
access attempted, a hardware
exception, called an access
violation,
occurs.
When an image calls a system service, the service
determines

whether an access violation would occur when the
1image
attempted
to
read or write a page
it
1is
not
privileged
to
access.
If so, the
service returns the status code SS$ ACCVIO.
|

HOW TO USE SYSTEM SERVICES
MEMORY

MANAGEMENT

SERVICES

Since the memory management services add, delete, or modify a
single
page
at a time, one or more pages can be successfully affected before
an access violation is detected.
1If the RETADR argument is
specified

the

service

call,

the

service

+returns

the addresses
of pages

actually affected before the error.
If no pages are affected, that
is,
1f
an
access violation would occur on the first page specified,
the service returns a -1 in both
longwords
of
the
return
address
array.

the RETADR argument

3.8.4

Working

not

specified,

information

returned.

Set Paging

When a process is executing an image, a subset of its pages resides
in
physical
memory;
these
pages are called the process's working set.
The working set 1ncludes pages 1in both
the
program
region
and the
control

reglon.

When’the image refers to a page that is
not
in
memory,
a hardware
fault
occurs,
and
the
page
1s
brought into memory, replacing an
existing page in the working set.
If the page that
1s
going to
be

replaced
has
been
modified
during the execution of the image, that
page is written onto a secondary storage
device, called the
paging
device.
When
this
©page
1s
needed
again, it is brought back into
memory, again replacing a current page from
the
working set.
This
exchange of
pages between
physical memory and secondary storage is
called

paging.

The paging
However,

of
1if

a process's working
a

program

that are heavily used

very

are

being

set

transparent

large,

i1f pages

paged

and

the

in the

out

image

frequently,

the

overhead
required
for
paging may decrease the program's
Some system services allow a process,
within
1limits,
to

these

potential

problems:

The

The Purge Working Set
from the working set.

Adjust

Working

Set Limit

increases the maximum number
in its working set.

($PURGWS)
|

($ADJWSL)

pages

that

system
|
B AT R
eg =

pages

efficiency.
counteract

system

a process
|

service

can

removes
»

have

page

e,
",

The Lock Pages in Working Set f$LKWSET) g¥stem
a page

process.

program

the working%wset
jine? F1gible

service
makes
for paging.

The initial size o0of
a
process's
working
set
1s
defined
by
the
process's
working
set default (WSDEFAULT) quota. - Since some programs
may have larger memory requirements than others, a program
can
call
the
S$SADJWSL
system
service
to
dynamically
increase the process's
working set limit.
When the additional pages are no longer needed 1in
the
working set, the program can call the SADJWSL service to decrease
‘the working set limit.
Or, it can call the $SPURGWS system service
to
remove pages no longer in use from the working set.

When the system pages a
process's
working
set,
the
pages
1in
the
working
set are
paged on
a first-in, first-out basis.
Under some
circumstances, an image may not want certain pages
to be paged out
at
all;
then,
it can
1lock
them
1in the working set.
As long as the
process's working set is in memory, these pages cannot
be
paged
out
until
they are
exp11c1tly unlocked with the Unlock Pages in Working
Set (SULWSET) system service.

HOW TO

USE

MEMORY

MANAGEMENT

SYSTEM SERVICES
SERVICES

Process Swapping

3.8.5

The operatlng system balances the needs of all the processes that
are
currently executing,
providing
each
with
the
system resources it
requires on
an
as—-needed basis.
The
memory
management
routines
balance
the
process's
memory
requirements.
Thus,
the sum of the

working sets for all processes that are currently
in
is

called

the

balance

physical

set.

memory

When a process whose working set is in memory becomes
1i1nactive -- for
example
to
wait
for
an
I/O
request or to hibernate -- the entire
working set may be removed from memory to provide
space
for
another
process's working set to be brought in for execution.
This removal
of
a process's working set is called swapping.
When a process is swapped
out
of the balance set, all of the pages
of its working set (modified
and unmodified pages) are swapped, including any pages that were
J=on
in the working set.
locked

It is possible for a high-priority process to lock its entire
working
set
in the balance set.
While pages can still be paged in and out of
the working set, the
process
remains
in
memory
even
when
it
1is
inactive.
To
lock itself in the balance set, the process issues the

Set Process Swap Mode

(SSETSWM)

system service.

For

example:

ESETSWM.S SWEFLG=#1
This call to SSETSWM disables process swap mode.
Swap mode
can
also
be
disabled
by setting the appropriate bit in the STSFLG argument to
the Create Process (SCREPRC) system
service.
A
user
privilege
1is
required, however, to alter process swap mode.

at ?fbyfi,wn_
Another way th
Pages

1in

Memory

A lock pages

in memory

sSystem service.

memory with this\servi «w””e page remains

is with

the

Lock

when

the

When a page 1is locked in
memory

even

remainder
of
the process 's working set is swapped out of the balance
set.
This system service has limited applicability, but may be useful
in
special
circumstances, for example, for routines that perform I/O
operations to slow devices
or graphics devices.

Pages locked in memory can be unlocked with the Unlock Pages in Memory
(SULKPAG)
system
service.
issue both of these services.

3.8.6

The

user privilege PSWAPM

required

Sections

Sections are disk files or portions of disk files containing
data
or
code
- that
can be brought into memory and made available to a process
for manipulation
and
execution.
Sections
are
either
private
or
shared:

Private sections are accessible
only
by
the
process
creates
them;
a
process
can define a disk data file
section,
map
1t into
1its
wvirtual
address
space,
manipulate

1it.

Global sections can be shared by more than one proceSs.

that
as a
and
A

One

copy
of
the
global section resides in physical memory, and
each process sharing it refers to the same
copy.
A
global
section
can contain shareable code or data that can be read,
or read and
written,
by
more
than
one
process.
Global
sections
are
either
temporary or
permanent,
and
can be
defined for use within a group or on a system-wide basis.

HOW TO

USE

SYSTEM

SERVICES

MEMORY

MANAGEMENT

SERVICES

When pages in sections are paged out of memory during image execution,
are

written

secondary

they

storage,

The

use

back

sections

1into

the

involves

The

creation

and

1informs

the

section

normal
two

file,

rather

than

onto

case.

distinct

operations:

section defines a disk
system what portions of

file

the

as
file

a
section
contain the

section.
2.

The

mapping

process

blocks

Create

and

file and

address

Map

section

makes

establishes

in the

virtual
The

and

the

section

available

between

virtual

creates

and/or

the correspondence

specific addresses

the

process's

space.

Section

(SCRMPSC)

system

service

maps
a
private section or a global section.
Since a private section
1s
used
only
by
a
single
process,
creation
and
mapping
are
simultaneous operations.
1In the case of a global section, one process
can

create

permanent

can
map to it.
one operation.

The

following

each

and

global

and

requirements

3.8.6.1

case,

global

process

sections

section

can

also

describe

are

for

described

the

use

not

creating,

considerations
that

sections

and

create
|

are

map

and

global

processes

section

and using

sections.

both

private

additional

followed

Creating Sections - The steps involved

sections

notes

in -section

creation

Opening or creating the disk file containing the section

Defining

which

wvirtual

blocks

the

file

Opening
it must

the

characteristics

the Disk File be opened using

the

existing
SECFAR:

specification

file
$FAR

the

Before
RMS.

section

file

can

The following example shows the file access block
channel

comprise

Defining

3.8.6.2
section,

sections.

section

and

other

a global

mapping,

common

first,

it;

map
|

for

the

$CRMPSC

FNM=<GECTION. TST>yFOP=UFQ

#FILE

used

(FAB),

system

reading:

OPEN macro,

service

open

|
ACCESS

RBLOCK

¢+

$OFEN

FAaR=SECFAR

FCRMFSC.LE

CHAN=SECFAR+FARSL..8TVr
.\,

The file options (FOP) parameter indicates that
the
file
is
to
be
opened
for user I/0;
this option is required so that RMS assigns the
channel using the access mode of the caller.
RMS returns the
channel
number

channel

number

which

file

accessed

specified

the

input

(CHAN

argument).

Create

and

write
(SQIO)

wvirtual
blocks
system service.

map

The

section

same

channel

operations.

the

to
It

section

the

number
can

file

offset

FABSL

$CRMPSC

can

also

with

used

the

STV;

system

for
to

Queue

this

service

multiple
read

I/0

and

Reguest

HOW TO USE

MEMORY

SYSTEM SERVICES

MANAGEMENT

SERVICES

The file may be a new file that is to be created while it is in use as
a
section.
In this case, use the $CREATE macro to open the file.
1If
you are creating a new file, the file access block (FAB) for the
file
must specify an allocation quantity

(ALQ parameter).

SCREATE can also be used to open an existing‘file;

if the

file

does

not exist,
it
will be
created.
The following example shows the
required fields in the FAB for the conditional creation of a file:
GELFAER:

5L
s ALQR=A s FAC=PUT
GLORA
« TGTH
FNM=<

$FAR

s GRT:
UROy
CFOF=SCIF

$(hffiTr FAaR=GRLFAR

When the $CREATE macro is invoked, it creates the file

1if

GLOBAL.TST

The CBT (contiguous-best-try)
currently exist
not
does
file
the
Although it
option requests that if poss1ble, the file be contiguous.
is
not
required that section files be contiguous, better performance
can result

i1f

they are.

3.8.6.3
Defining the Section Extents - Once the file 1is
successfully
opened, the
S$CRMPSC system
service can
create a section from the
entire file, or from only
certain
portions
of
1it.
The
following
arguments
to SCRMPSC define the extents of the file that comprise the
section:

PAGCNT

VBN (virtual block number).
This argument defines the number
of the virtual block in the file that is the beginning of the
section.
It is an optional argument;
1f not
specified
it
defaults
to 1l;
that 1s, the first virtual block in the file
is

3.8.6.4

the

(page

count).

This

argument

1is

required;

indicates
the
number
of virtual blocks in the file.
blocks correspond to pages in the section.

the beginning

the

section.

Defining the Section Characterlstlcs - The FLAGS

SCRMPSC

system

characteristics:

service

defines

the

How the pages of the section are to be treated when they

is to create a private section)

'global

into physical memory or when a process

The pages

1in a

--read/write or

section can be:

section
refers

section

Whether it is a private section
copied

argument

follow1ng

)

default

These

(the
\

are

them.

read-only

—-created as demand-zero pages or as copy-on-reference pages,
depending on how the processes are going to use the section
~and whether
the file contains any data (see Section 3.8.6.8,
"Section Paglng")

HOW TO

USE

SYSTEM

MEMORY MANAGEMENT

SERVICES

3.8.6.5
Defining Global Section Characteristics global
section,
it
must be assigned a character

argument)

mapping

that other

processes

<can

identify

If the section
is a
string name (GSDNAM

1it.

when

they

are

The FLAGS argument specifies the type of global section:

Group

temporary

Group

permanent

(the

System

temporary

System

permanent

default)

Group global sections can be shared only by processes

executing

A temporary gldbal section 1s automatically deleted when no
are

mapped

1it.

processes

Permanent global sections remain 1n existence even when
no
processes
mapped
to them.
They must be explicitly marked for deletion with the
Delete Global Section ($DGBLSC) system service.

with

the
same
group
number,.
The
name o0of
a
group
global section is
implicitly qualified by the group number
of the process
that
created
it.
When other processes
map to it, their group numbers must match.

The user privileges PRMGBL and SYSGBL
group
global
sections,
or
system
permanent)
, respectively.
A system global section
system.
|

Optionally,

can

be
,

made

are required to create permanent
global '"sections
(temporary
or

available
|

a process creating a global section

all

processes in
|

can

specify

protection
mask
(PROT argument), restricting all access
access (read, write, extend, delete) to other processes.

3.8.6.6

Mapping Sections - When you code the $CRMPSC

system

a
a

the

file

type
|

service

to
create
and/or
map
a section, you must provide the service with
a
‘range of virtual addresses (INADR argument) into which the section 1is
to

mapped.

If you know specifically which pages
the
section
should be
mapped
into, you provide these addresses in a 2-longword array.
For example,
to map a private section of 10 pages into virtual pages 10 through 19
of the program region, specify the input address array as follows:
MAFRANGE ?

|
LONG

7X1400

+LONG

TX2300

s ADDRESS

(HEX)

0OF

FAGE

#ADRDRESS

(HEX)

OF FAGE

'The addresses specified do not have to be currently in

the

prOcess's

virtual
address
space.
The SCRMPSC system service calls the Create
Virtual Address Space (SCRETVA) system service to create the
required
virtual
address
space
before mapping
the secion.
If you code the
RETADR argument, the service returns the range of addresses
actually
mapped.

You do not need to know explicit addresses to provide an input address
range.
If you
want the section mapped into the current end of the
program region, you can use the $SEXPREG
system
service
to
add
the
pages at
the
end
of
the program region and use the return address

array from SEXPREG as input to the $CRMPSC system service.

3-85

HOW TO

USE

SYSTEM

SERVICES

MEMORY

MANAGEMENT

SERVICES

You can also obtain the address
of the
next
available
page
1in
the
region by
calling
the
Get Job/Process Information (SGETJPI) system
service.
The SGETJPI service returns an address you can use
for
the

starting
address
1in
in the program region
many

pages

mapped
a

the

the range.
You then provide a very high address
as the ending address:
S$CRMPSC creates only
as

necessary

return

map

address

the

section,

array.

The

and

returns

following

the

example

addresses

shows

such

macro.

For

sequence:

GETVADR: .WORD

JWORD

jLENGTH

JFI$_FREFOVA

FITEM

BUFFER

IDENTIFIER

{LLONG

MAFRANGE

s AIDRESS

LONG

;NOT

NEEDED

LONG

JEND

MAFRANGE ¢

JELKL
LONG

JPI

EUFFER
|
LIST

sFIRST FREE FO FAGE

1
"X1FFFFFFF

RETRANGE:
+EBLKL

sVERY

LARGE

ADDRESS

sGET

RETURN

ADDRESS

RANGE

¢
¢

$OETIFILS

ITMLST=GETVADIR

$CRMFSC..S8

INADR=MAFRANGE
y RETADR=RETRANGEy + ..

The item code JPI$ FREPOVA is

complete
details
on
how
to
service description in Chapter
Once
the
or

section

pages
labels

has

been

sFINDI

defined
use
4.

the

FIRKST

Figure

3-23

the

SGETJPI

successfully mapped,

using a base register
defining
offsets
of

and
an

FAGE

S$JPIDEF

system

the

predefined
absolute

structure.
-

FREE

service,

image

<can

symbolic
program

|
shows

example

section.

SECFAR! 4FAR

“X1400

|
+ L.LONG
- RETRANGE $

"X2300

<creating

and

mapping

+ BLKL
ENDRANGE$

+ BLLKL

"'$UPEN
BSEW

yFIRST

FAGE

yLAST FAGE
|

s FIRST

FAGE

yLAST

FAR=5ECFAR

FOFEN HBECTION FILE

FAGE

MAFFED

ERROR

‘9$CRMPSCm$ INADR=MAFRANGE
y - 3 INFUT ADDRESS ARRAY
-

RETADR=RETRANGE
yFAGONT =44

§0UTFUT

s MAFF

FOUR

ARRAY
FAGES

'i%FLfiGQfl#SEG$HMNRT s READ/ZWRITE SECTION
CHAN=SECFAR+FARSL
.STV
BSEW

¢’fiDUL

ERROR

RETRANGE yRé&

Figure 3-23

« LLONG

refer

the

offset names
section
or

FNMmiSECTIUN.TST%?FOP%UFOrFfiCmPUT

MAFRANGE $

see

s CHANNEL

NUMRER

sFOINT TO START OF SECTION

Creating and Mapping a Private Section

process

HOW TO USE SYSTEM SERVICES
MEMORY MANAGEMENT SERVICES

Notes on Figure 3-23:

defined

in the

file

The OPEN macro opens the section file

(’

The S$CRMPSC system services uses the addresses specified at
to specify an input range of addresses into Wthh
MAPRANGE

access

block

SECFAB;

argument
PAGCNT
The
the section will be mapped.
that only four pages of the file be mapped.

requests

rThe FLAGS argument requests that the pages in the section be
The symbolic flag definitions for this argument
read/write.
are defined 1in the $SECDEF macro.

field

(FAC parameter)

access

Note that the file

in the FAB also indicates that the file

is to be opened for writing.

that

hen SCRMPSC completes, the addresses of the four pages
were

mapped

are

returned

output address array at

the

The address of the beginning
RETRANGE.
which serves
6,
in register
placed
section.

of
as
~

1is
the section
a pointer to the

that <creates a global
3.8.6.7 Mapping Global Sections - A process
Then, other processes can
can map to it when it creates it.
section
map it by calling the Map Global Section ($MGBLSC) system service.

it must specify the global
- When a process maps a global section,
section name assigned to the section when it was created, whether it
is a group or system global section, and whether it de51res read-only
The process may also specify:
or read/write access.
®

the
indicating
(IDENT argument),
A version identification
version number of the global section (When multiple verisons
the
exist) and whether more recent versons are acceptable to
process.

)

A relative page number (RELPAG argument),'specifying the page
the beginning of the section, to begin
to
relative
number,
only
use
can
processes
1In this way,
mapping the section.

Additionally, a process can map a
a section.
of
portions
and
range
address
a particular
into
section
piece of a
different piece of the section into the
a
subsequently map

same virtual addresses.

Cooperating processes can both
create and map the same global

issue a
section.

§$CRMPSC system service to
The first process to call

the service actually creates the global section;

subsequent

attempts

to create and map the section result only in mapping the section for
SS$ CREATED indicates
The successful return status code
the caller.

that the section did not already exist when the $SCRMPSC system service
If the section did exist, the status code SS$NORMAL is
was called.
returned.

of a global section,
Figute 3-24 shows an example of the creation
a second process mapping the section.

and

HOW

USE

‘MEMORY

SYSTEM

SERVICES

MANAGEMENT

SERVICES

LProcess ORIONW
GERL.CLUSTER

,
DESCRIFPTOR
GRLSET
= &5

- GBLWAIT

GLORALSEC?

NESCRIFPTOR

GRLFAG!

$FAR

y COMMON EVENT FLAG CLUSTER NAME

<GLORAL_.CLUSTER:

yFLAG

NUMBER

sFLAG

NUMRER

TO WAIT

yGLLOBAL

ASSOCIATE

AND

SET

FOR

SECTION NAME

<GLOBAL_SECTION:

FNM=<G
« TST> s FOF=<UFQyC
LOB
IF AL
sy CRT >y AL.Q=4y FAC=FUT

$ABCEFC.S

BSRW

EFN=#GBL
» NAME=GRLCL
SET
USTER

ERROR

FLAGO=#GECPM_WRTISECSM_GRL.y « + »

BSEW

ERROR

$SETEF .S

EFN=#GRLSET

ySET

COMMON

EVENT

FLAG

|Process CYGNUS}

CLUSTER?

DESCRIFTOR

GELSET =
GELWAIT

< GLORAL..CLUSTER:

3CLUSTER

SECTIUNI

NAME

DESCRIFTOR {GLOBQLMSECTION} ySECTION NAME
o
-

ERROR

SWALTFR..S

BSRW

EFN=#GRLSET

ERROR

SMGELSC..5 INfiHRmMfiPRfiNGEyRETHHR*RETRANGEyW

FLAGE=#SECSEM..G
y - $GLORAL
RL SECTION
GHIONAM=SECTION FSECTION NAME
|

HSRW

ERROR

Figure 3-24

Creating and Mapping a Global Section

Notes on Figure 3-24:

The processes ORION and CYGNUS are in the same

~process
-

first

associates

named

GLOBAL

their

use of the section.

ORION

CLUSTER
to

creates

the

specifying

flags

(SECSM_GBL)

and

address
number
are

the

arrays,
arguments
same

use

global

that

that
the

with

common event

section

indicate

1is
page

common event

are

not

shown;

shown

Figure

parameter

procedures
3-23.

global

Input
and

for

cluster

synchronize

GLOBAL

read/write.
count

flag

flags
to

named

that

group. - Each

SECTION,

section

and

output

the

channel

coding

them

HOW TO USE SYSTEM SERVICES
MEMORY MANAGEMENT

G’
-

SERVICES

The process CYGNUS associates -with the

common

event

flag

ORION sets
cluster and waits for the flag defined as GBLSET.
To map
section.
the
creating
completed
has
it
this flag when
specifies the input and output address
CYGNUS
the section,
and
arrays, the flag indicating that it is a global section,
The number of pages mapped is
the global section name.
always the same as that specified by the creator of the
|

‘

sectlon.

3.8.6.8 Section Paglng - The first time that an image executlng in- a
process refers to a page that was created during the mapping of a
sectlon, the page 1is copled into physical memory. The address of the
page in the process's virtual address space is mapped to the physical
normal paging can occur;
During the execution of the image,
page.
however, pages 1in sections are not written onto secondary storage
Rather, 1if
devices when they are paged out, as is the normal case.
file
section
the
into
back
written
are
they
modified,
been
have
~they

on disk.

The next time a page fault occurs for the page, the page

brought back from the section file.

In the case of global sectlons, more than one process can be mapped to
the

same physical pages.

These pages are paged out, and written back

to the disk file defined as the sectlon, only when

currently mapped to them.

If the pages

copy-on-reference

section

pages

treated differently.

when

are

defined as

processes

are

pages or

demand-zero

the section was created, the pages are
-

If the call to $CRMPSC requested that pages in the sectlon beg treated
as demand-zero pages, these pages are initialized to zeros when they
If the file is either a new.
are first brought into physical memory.
or a file that is being
section
a
as
created
being
1is
file that
completely rewritten, demand-zero pages provide a convenient way of
initializing

the pages.

If the call to S$SCRMPSC requested that pages in the section be
copy-on-reference pages, each process that maps to ‘the section
receives its own copy of the section, on a page-by-page basis from the
file, as it refers to them. These pages are never written back into
the

;

section file.

3.8.6.9 Readlng

prov1de

data files

and Wr1t1ng

Data Sections - Read/write

sections

way for a process, or cooperating processes, to manipulate

in virtual memory.

The sharing of
synchronization

global sections may involve application-dependent
For example, one process can create and
techniques.

map to a global section in read/write status;

other processes can map

to it in read-only status, and interpret data wrltten by the first
Or,~ two oOr more processes can write to the section
process.
concurrently. - (In this case, the application program must prov1de the
necessary synchronization and protection.)

When a file that has been mapped as a section is written back to disk,

its version number is not incremented but the revision number is. A
full dlrectory listing indicates the revision number of the file and

the date and time that the file was last updated.

When the file
or unmap, the

file

defined

HOW TO

USE

SYSTEM

SERVICES

MEMORY

MANAGEMENT

SERVICES

has been
section.

updated, the
The section
section.

process or processes
is then written back

can
into

release,
the disk

3.8.6.10
Releasing and Deleting Sections - A process unmaps
a section
by
deleting the virtual addresses in its own virtual address space to
which
it has mapped the
section.
If
a
return
address
range
was
specified
to
receive the virtual addresses of the mapped pages, this
- address range can be used as input to the Delete Virtual Address Space

(SDELTVA)

system

$OELTUVALS

When

service.

For

example:

INADR=RETRANGE

process unmaps a private section, the section is deleted;
that
all
<control
information maintained by the system is deleted.
A
temporary global section is
deleted
when
all
processes
that
have

is,

deleted

until

Delete

Global

Section

deleted

when

more processes
are mapped.

have

they

unmapped

are

it.

Permanent

specifically
($DGBLSC)

marked
system

global
for

sections

deletion

service;

then,

are

not

with

the

they

are

that deleting the pages occupied by a section does not delete
section file,
but
rather cancels the process's association with

the

'\, L{”J

mapped

Note

file.
'Moreover,
section
and
no
are written back
When

the
when a process deletes pages mapped to
a
read/write
other processes are mapped to it, all modified pages
into the section file.
|
|

all

which

channel

processes mapped
the
section
was

can be deassigned.

deassign
the
for example:

channel

FOALSON.S

3.8.6.11
normally

to a section have
mapped from their

The process

(with the
|
|

deleted
the
pages
into
virtual address space, the

that created

Deassign

I/0O

the

Channel

section

system

CHAN=GRLFAR+FARSL..STV

Checkpointing
not updated on

Sections disk until

Since
read/write
the physical pages

paged

sections
they

occupy

out, or until
all
processes
referring
to
the
section
unmapped 1t, a process may have to ensure that all modified pages
been successfully written back into the section file.

The Update Section File on Disk ($UPDSEC)

modified

pages

service
1is

1in

described

3.8.6.12 Image
An
1image
file

section

into

in Chapter

Sections
that

position-independent

- Global
going to
code.
|
is

the

sYstem service

disk

file.

The

writes

SUPDSEC

follows:
1.

are
are
have
have

the

system
-

sections
be

can contain shareable code.
defined as a section must contain

The operating system uses global sections to implement shareable
as

can

service),

code

The object module containing code to be shared is
1linked
to
produce
a
shareable 1image.
The shareable image is not, in
itself, executable.
It contains a series of sections, called
image sections.
|
o
,

HOW

MEMORY

A user

links

SYSTEM

SERVICES

MANAGEMENT

USE

SERVICES

private

object modules

with

the

shareable

image

to produce
an executable image.
Only image section descriptor
records from the shareable image file are bound
with
the
image sections from the user's-.code.

For

The system manager uses
the
INSTALL
command
to
create
a
permanent global section from the shareable image file maklng
the image sections available for sharing.

When

the

user 'runs

the

executable

automatically maps the global sections
command into the virtual address space

details

how

create

and

identify

link them with private object modules,
Manual.
For information on installing

them

available

Manager's

Guilde.

for

sharing as global

1mage,

the

system

created by the INSTALL
of the user's process.

shareable

images,

and

how to

see the VAX-1l1l Linker Reference
shareable
1images
and making

sections,

see

the VAX/VMS System
|

CHAPTER

SYSTEM

SERVICE

DESCRIPTIONS

This chapter describes each
of
the VAX/VMS
system
services.
The
services
are
presented
1in
alphabetical order, by their abbreviated
names.

Each system service descrlptlon consists of the following

categories,

applicable:

‘as

Format:

Macro

Shows the macro
name, with
all
keyword arguments
positional order.
Spaces
between
arguments
are
readability, and are not part of the macro syntax.

High-Level

Language

1listed
present

in
for

Format:

Shows the procedure name and a generalized format for calling the
service
from a high-level language, with all arguments listed
in
positional order.
Spaces
between
arguments are
present
for
readability, and are not part of the statement syntax.

arguments...

Describes each

Return

the

arguments.

Status:

Lists the possible return status codes from the service
with
an
explanation
of the return condition.
The successful returns are

" listed
severe
status

first, in alphabetical order,
followed
by
warning
error return status codes also in alphabetical order.
codes are severe errors, unless otherwise indicated.

Three severe errors may occur for all
with each service description.
These
SS$_ACCVIO
|
The argument
SSS

INSFARG
Not enough

SS$_ILLSER
An invalid

list

cannot

services
are:

read

arguments were

supplied

system

was

service

and

the

called.

are

not

listed

callere

the

and
All

service.

SYSTEM

DESCRIPTIONS

Notes any user privileges required to
request
a particular function of the
restrictions applied to the service.

execute the
service, or

service
or
to
any access mode

Resources Required/Returned:
Lists any system resources or process quotas used by the service,
or returned to a process as
a result of service execution.

‘Notes:

- Contain

the

important
covered in
references

'fine

print'

the

service

description.

information
©pertaining
to
the
service
that is
one of the other headings is given here,
as
well
to related services or additional information.

All

not
as

Restrictions:

- v

Privilege

SERVICE

SYSTEM

SERVICE

DESCRIPTIONS

$ADJSTK
4.1

S$ADJSTK

- ADJUST OUTER MODE

STACK POINTER

The Adjust Outer Mode Stack Pointer system service modifies the
stack
pointer
for
a
less privileged access mode.
This service is used by
the operating system to modify a stack pointer for a
1less
privileged
access mode after placing arguments on the stack.

Macro

Format:

SADJSTK
High-Level

[acmode]

Language

,[adjust]

,newadr

Format:

SYSSADJSTK ([acmode]

,[adjust]

,newadr)

acmode

access mode

for

which

the

stack

|
pointer

adjusted.

adjust
signed adjustment value.
The contents of the longword
addressed
by
the
NEWADR
argument are adjusted by the amount specified in
the low-order 16 bits of this argument.
The
result
1is
1loaded
into the stack pointer for the specified access mode.

If not spécified, or specified as 0, the stack pointer is

‘with

the

address

specified

loaded

the NEWADR argument.

- newadr
address of a longword to
receive
the
updated
value.
If
the
longword
contains a nonzero value, then that value is updated by
the ADJUST
pointer.

argument

value
A

and

the result

loaded

.‘\

If the longword contains a 0, the
current
value
pointer is updated by the ADJUST argument value.

Return

into

the

stack

Status:

SS$_NORMAL

Service

successfully

SS$_ACCVIO
The longword to store
the new stack segment

completed.

the updated stack pointer or a
portion
cannot be written by the caller.

SS$_NOPRIV
The specified access mode
calling access mode.

equal

privileged
.

than

|
the

SYSTEM

SERVICE

DESCRIPTIONS

SADJSTK - ADJUST OUTER MODE STACK POINTER

Combinations of zero and nonzero values for the
ADJUST
and the NEWADR longword provide the following results:
If

the

ADJUST

argument

specifies:

And the longword

addressed by
NEWADR contains:
0

address

argument

The stack
pointer

is:

hot changed
loaded with the
address specified

adjusted by the
specified value

value

‘a value

address

loaded with the
specified address,
adjusted
by the
specified value

" In all cases, the updated stack pointer value is written into the
by NEWADR.

addressed

longword

SYSTEM SERVICE DESCRIPTIONS

$ADJWSL
4.2

S$ADJWSL

- ADJUST WORKING

SET LIMIT

The Adjust Working Set Limit system service changes the current
1limit
of
a process's working set size by a specified number of pages.
This
service allows a process to control the number of
pages
resident
1in
physical memory for the execution of the current image.

Format:

Macro

SADJWSL

High-Level

[pagcnt]

Language

, [wsetlm]

Format:

SYS$ADJWSL
( [pagent]

, [wsetlm])

pagcnt

number of pages to adjust the current maximum working
set
size.
A
positive
value 1increases
the
maximum
working set size;
a
‘negative value decreases
it. 1If not specified, or
specified
as
0,
the current working set size limit is returned in the address
specified by the WSETLM argument, if that argument is coded.
wsetlm

~address of a longword to receive the new working set
or
the current working set size limit, if the PAGCNT
not specified.

Return

size
limit
argument is

Status:

SS$_NORMAL
Service

successfully

completed.

SS$_ACCVIO
The longword to receive
written by the caller.

Resources

the

new worklng

set

size limit

cannot

Required/Returned:

The initial value of a process's working set size
1is
controlled
by
the working set default quota (WSDEFAULT).
The maximum value
" to which it may be increased is controlled
by
the
working
set
limit quota

If a program attempts
system-defined
upper

returned.

(WSQUOTA).

to adjust the working
and
lower
limits,

The working set size is adjusted

minimum
size
allowed;
the
size to verify the change.

caller

set size
no error

can check

the

beyond
the
condition is

maximum

new worklng

set

For more details on memory management concepts and additional services
that
help
a
process
control
paging and swapping, see Section 3.8,
"Memory Management Services."

SYSTEM

SERVICE

DESCRIPTIONS

$ALLOC
4.3

SALLOC

- ALLOCATE

DEVICE

The Allocate Device system service

reserves a device for exclusive use

by
a process and its subprocesses.
No other process can allocate the
device or assign channels to it until the
image
that
called
SALLOC
exits
or explicitly deallocates the device with the Deallocate Device
(SDALLOC)

Macro

system

service.

Format:

$ALLOC

High-Level

devnam

Language

, [phylen]

,[acmode]

Format:

SYSSALLOC (devnam
devnam

,[phybuf]

, [phylen]

, [phybuf]

, [acmode])

address of a character string descriptor pointing to the device
name
string.
The string may be either a physical device name or
a logical name.
1If the first
character
1in
the
string
1is
an
underline
character(_), the name 1is considered a physical device
name.

Otherwise,

performed
name,
of

and

however,

the

host

single

level

logical

the equivalence name,
cannot

contain

node

name

if any,
name

translation

is used.

unless

the

The

final

name

is that

allocated

device

system.

phylen

address of a word
name string.
phybuf
address

receive the

length

the

to
receive
device.
The
underline

character

string

descriptor

the
physical
device name
first
character
1in
the

character

(_).

pointing

the

buffer

string of the allocated
string
returned
is
an

acmode
|
A
access mode to be associated
with
the
allocated
device. - The
specified
access
mode
1is maximized with the access mode of the
caller.
Only
equal
or
more
privileged
access
modes
can
deallocate the device.

Return

Status:

- SS$_NORMAL
Service

SS$_BUFFEROVF

successfully

completed.

Service
successfully
completed.
overflowed the buffer provided, and

The
has

physical
name
been truncated.

returned

SS$_ACCVIO
|
The device name string or
string descriptor
or
physical
name
buffer
descriptor
cannot
be
read,
or the physical name buffer
cannot be written, by the caller.
|

SYSTEM SERVICE DESCRIPTIONS
$ALLOC - ALLOCATE DEVICE

SSS .DEVALLOC

" Warning.

Or,

)

The device

attempt

is already
allocate

allocated
unmounted

another

shareable

process.

device

failed

because other processes had channels as51gned to the device.

SS$_DEVMOUNT
The
specified
allocated;

device
1is
currently
mounted
the devi
is a mailbox.
ce

or,

and

cannot

SS$_IVDEVNAM
No

device

contains

name string was specified
invalid characters.

SS$_IVLOGNAM
The device

name

string

The

device

the

has

length

of 0,

remote

node.

characters.

SS$_NONLOCAL
Warning.

device

has

name

string

than

SS$_NOPRIV
An

attempt

was

made

allocate

spooled

device

requesting process does not have the required privilege.

SS$_NOSUCHDEV
Warning.

Privilege
A

The

specified

device

and

the

,
does

not

exist

the

host

system.

Restrictions:

user

privilege

required

allocate

spooled

device.

‘\."/

Notes:

“

—

When

process

service to

terminal
allocated to
2.

For

allocation
~

or
the

the

example
of

"Input/Output

of how to
devices

Services."

Assign

channel

I/O
a

line

printer,
process.

This service can only
on the host system.

calls

assign

use
by

used

Channel

(SASSIGN)

nonshareable

dev1ce,

the

device

allocate

devices

system
such

implicitly

that

this service, and a
description
of
generic
device names,
see Section

exist

the
3.4,

SYSTEM SERVICE DESCRIPTIONS

SASCEFC
SASCEFC - ASSOCIATE COMMON EVENT FLAG CLUSTER

4.4

The Associate Common Event Flag Cluster'system service causes a
be associated with a process
to
flag «cluster
event
common
a process-local
execution of the current image and assigned
If the named
use with other event flag services.
for
number
the
suitable privilege,
does not exist but the process has

Format:

Macro

efn

SASCEFC

High-Level

,name

Language

,[prot]

,[perm]

Format:

, [prot]
(efn ,name
SYSSASCEFC
efn

cluster.

the

creates

,[perm])

associated.

number of any event flag in the common cluster to be

The flag number must be in the range of 64
2

name

named

for the
cluster
cluster
service

through 127

and 96

for

cluster

through 95 for cluster

a character string descriptor pointing to
address of
cluster.
the
for
string
text name
15-character
associate

to
1s

issuing

process

implicitly qualified by the group number of the

the

1the
The name

request.

prot

- protection indicator controlling group access to the common event
0 (the default) indicates that any
‘A value of
<cluster.
flag
value
A
process in the creator's group may access the cluster.

with
perm

indicates that access is restricted to processes executing
creator's UIC.

the

permanent indicator.
cluster

If perm is equal to
‘

is marked permanent.

If perm is equal to 0, the cluster is

default value.

the
»

tempdrary;
|

common

event

this

1is

the

read

Return Status:
SS$_NORMAL

Service

successfully completed

SS$_ACCVIO

The cluster name string or string descriptor cannot
the

caller.

SS$- EXQUOTA

The process has exceeded its timer queue entry quota;

this quota

controls the creation of temporary common event flag clusters.

SSS

INSFMEM

the
complete
T Insufficient system dynamic memory is available to
the
with
mode
wait
resource
disabled
has
process
the
and
service
Set Resource Wait Mode

(SSETRWM)

4-8

system service.

SYSTEM

SASCEFC

SERVICE

ASSOCIATE

DESCRIPTIONS

COMMON

EVENT

FLAG CLUSTER

event flag number was specified.
The
cluster
the range of event flags 64 through 127.

1in

5S$_IVLOGNAM

The cluster name string has a length of

0 or

has

characters.

SSS

permanent

number

than

NOPRIV
The process
cluster

SS$_ILLEFC
An illegal
must

|
3
|
elther does
not
have
the
privilege
cluster;
or,
the
protection applied
its creator prohibits association.

»
to
<create
a
to an existing

Privilege Restrictions:
The

user

common

Resources

privilege

event

PRMCEB

required

create

flag-cluster.

permanent

Required/Returned:

Creation
process's

of
temporary
common
quota for timer queue

event
entries

a permanent cluster does not effect
restored
to
the
<creator
of
the

associated

with

the

cluster

have

flag
clusters
uses
the
(TQELM);
the creation of

the

quota.
when

<cluster

The
all

disassociated.

quota

1is

processes

Notes:

When

that

cluster's

process

reference

cluster

associates

count

either

Flag

Cluster

image

exit.

with

common

reference

count

is decreased

when

explicitly with

(SDACEFC)

clusters

reference

count

system

process

O0;

//
\

flag

cluster

processes

first

SASCEFC

need

not

does

not

concerned

Common

implicitly,

deleted

Delete

creates

the

already

with

when

clusters

named

the

state

event

flag

order

for

all

which

event

cluster

common event

Event

common

event

exist,

which

their

Common
”

cooperating

process

executes

they

call

flags

the

in'

service.

newly—created

SASCEFC

with

flag cluster

the

same

: .disassociates

the

number

. associating

with

its

For an example of the

services
that
Services."

must

- 3. If a process has already associated a cluster number
~

the

Event

create
the
cluster.
The
first process to call
creates the cluster and the others associate with
it

initial

common

The

‘

regardless

The

disassociates

permanent

Slnce thlS service automatlcally

cluster,

automatically

flag

Disassociate

explicitly marked for deletion with the
Flag Cluster ($DLCEFC) system service.

event

increased

servigce,

are

goes

the

Temporary

1is

event

first
|

see

the

assignment

call

service

before

service

flags,

with

issues another

number,

its

second.

then

<cluster

from

S$SASCEFC system

manipulate

and

Section

descriptions
3.1, "Event
-

Flag

SYSTEM SERVICE DESCRIPTIONS

SASCTIM
S$SASCTIM - CONVERT BINARY TIME TO ASCII STRING

4,5

The Convert Binary Time to ASCII String
system
service
converts
an
64-bit system time format to an ASCII
from
time
delta
absolute or
2,
The formats of the strings returned are described in Note
string.
below.

Format:

Macro

SASCTIM

,timbuf

[timlen]

,[timadr]

,[cvtflg]

High-Level Language Format:

SYSSASCTIM([timlen] ,timbuf ,[timadr] ,[cvtflg])

timlen

1length

address of a word to receive the

timbuf

address of a character string descriptor pointing to

the

buffer

The buffer length specified in

receive the converted string.

string

output

the

returned.

the descriptor, together with the CVTFLG argument, controls
information is returned.

See Note 3,

below.

—

what

timadr

address
If no
address of the 64-bit time value to be converted.
specified as 0 (the default), the current
1is
or
specified,
is
an
A positive time value represents
date and time are returned.
absolute
time.
A
negative time value represents a delta time.
If a delta time is specified, it must be less than 10,000 days.
|

cvtflg

conversion indicator.
A value of 1 causes only the hour, minute,
second,
and hundredth of second fields to be returned, depending
causes
default)
A value of 0 (the
on the length of the buffer.
‘the full date and time to be returned, depending on the length of
the

Return

buffer.

Status:

SS$_NORMAL

Service successfully completéd;

SS$_IVTIME

The specified delta time is equal to or greater than 10,000 days.

Notes:

The SASCTIM service executes at the access mode of the caller
and does not check whether address arguments are accessible
Therefore, an access violation causes an
before it executes.
if the input time value cannot be read or
exception condition
the output buffer or buffer length cannot be written.

SYSTEM SERVICE DESCRIPTIONS
- CONVERT BINARY TIME TO ASCII STRING
SASCTIM

The ASCII strings returned have the following formats:

2.
N

Absolute Time:

Delta Time:
.

Field

(Bytes)

mmm

month

JAN,

FEB,

MAR, APR,

MAY,
SEP,

JUN,
OCT,

JUL,
NOV,

VYYY

1
4

hyphen
year

1858 - 9999

blank

hyphen

hour

00 - 23

minutes

00 - 59

hundredths

00 - 59

.colon

e
SS
e

1
2
1

colon
seconds
period

CcC

AUG,
DEC

|
00 - 59

seconds

0000 - 9999

number of

dddd

)
/

Range of wvalues

day of month|1l - 31

Contents

)

dddd hh:mm:ss.cc

Length

dd-mmm-yyyy hh:mm:ss.cc

days

‘

Some p0551ble comblnatlons of buffer length specification and
CVTFLG arguments, and their results, are shown below:

Buffer Length| CVTFLG
Argument
Specified

|
Time Value

-Information
Returned

date and time

Absolute

| |

date

time

)

Absolute

Delta

days and time

time

For an example of the SASCTIM system service, see Section 3.6,

and Time Conversion Services."
fi’ fi;;"
fla::
M. ”*‘fig§OFi £y
PN \u,u

f: # t%*RSi g?@?A
£}
B8 w1

§
ey

éfi@

%
5@ '?- W_’_\:&
f} g::" o
E[Y g‘;
f BV
O [3g“?£,
St _%””B e

"Timer

:@%.»} flmfifi? .

"E;;A
1‘& "
‘g ) j?":‘
%{ il
1

gfgfigémk,j{m’ mfl-e

mL ®

SYSTEM SERVICE DESCRIPTIONS

\‘u/:

SASSIGN
4.6
The
I1/0

S$SASSIGN

- ASSIGN

I/0O

CHANNEL

Assign I/0 Channel
channel
so
that

device, or
network.

system service (1) provides
input/output operations can
establishes a logical link with
a

(2)
|

a
device
with
an
be performed on the
remote
node
on
a

Macro Format:
SASSIGN

devnam

High-Level Language

,chan

,[acmode]

, [mbxnam]

Format:

SYS$ASSIGN(devnam

chan

devnam

, [acmode]

, [mbxnam])

address
name

character

string.

a.logical

string

name.

If
character

underline
name.

The

Otherwise,

performed

and

the

string

descriptor

may

the

first

(),

the

single

name

name,

channel

function

the

chan

to
network.

address

mode is maximized with
operations on the channel can

privileged

access

any,

dduble- CQlon
and

the

device

name

string

physical

an
device

translation

used.’

(¢:),

the

performs

system

access

channel

number

with

the

channel.

the

access

assigned.

associated

access

name

receive
R

mode

logical

device NETO:
-

a word

acmode
access

the

physical

in
the
considered a

level
of

If the device name contains
a

pointing
a

character

equivalence

assigns

either

only

mode

of
performed

modes.

The

the

from

specified

caller.

1I/0

equal

and

mbxnam
address of a character string descriptor pointing to the
logical
name string for the mailbox to be associated with the device, if
any.
The mailbox receives status
information
from
the
device
driver, as described in Note 2, below.
|
An

Return

address

implies

no mailbox;

this

the

default

value.

Status:

5S$_NORMAL
-

Service

successfully

SS$_REMOTE
Service successfully
with the target on a

completed.

N
completed.
A
remote node.

.
logical

|
1link

is
:

established

SS$_ACCVIO
The

device or mailbox name string or string descriptor cannot
read, or the channel number cannot be written, by the caller.

|
be

"SYSTEM SERVICE DESCRIPTIONS
SASSIGN

SS$_DEVALLOC
Warning.

The

SS$_DEVNOTMBX
A mailbox
mailbox.
SSS

device

ASSIGN I/O

allocated

been
-

spe01f1ed

|
for

v
name

has

EXQUOTA

CHANNEL

another

process.

.
that

device
'
,

The target of the as51gnment is on a remote node and the
has
insufficient
block.

SS$_INSFMEM
The target

- insufficient

SS$_ IVDEVNAM
No

qguota

a551gnment is

on a

system dynamic memory

allocate

and

complete
the

process

a network

o
node

remote

control

there

reguest.

was specified or the device or mallbox name string
contains invalid characters.
1If the device name is a target on a
remote node, this status code indicates that the Network
Connect
Block has an invalid format.

SS$

device

the

buffer

not

name

IVLOGNAM
The device
than

mallbox

‘
name

|
string

characters.

has

length

has

SS$_NOIOCHAN
No

SSS
-

I/O

channel

NOLINKS
No logical

1is

network llnks

SS$_NOPRIV
The

avallable

are

assignment.

avallable.

process does

not

have

operations.

SS$

for

NOSUCHDEV
Warnlng

the

privilege

The

SS$_NOSUCHNODE
The specified

o
specified

network

device

node

perform

network

\
|
mailbox does

is nonex1stent

|
not

exist.

‘
unavailable.

SS$_REJECT
The

network

remote
confirm

connect

node;
could

was

- or,
the
be issued.

rejected

by NSP

target

1image

the

exited

partner

before

the

connect

Resources Required/Returned:
System dynamic memory
remote

system.

1is

required

the

target

dev1ce

SYSTEM SERVICE DESCRIPTIONS
$SASSIGN - ASSIGN I/O CHANNEL

For

details

on how

operations,

see

use

S$ASSIGN

the DECnet-VAX

can

mailbox,

send messages

the

containing

status

cases:

following

the

target

network

reception

is on a
connect

message

For

the

dialup,

input.

network,

the
initiate,

may
indicate
whether the line is

the

that

unsolicited

down.
device

the

printer

details

returned,
see

line

printer,

the

message

indicates

offline.

the

VAX/VMS

message
I/0

format

User's

and

the

information

Guide.

Channels remain assigned until they are explicitly deassigned

with

the

until

the

Deassign

image

The

SASSIGN

not

check

details

VAX/VMS

I/0

see

how

the

operations

restrictions

the
examples

establishes

whether

For

operations,

I/O Channel (SDASSGN) system
assigned the channel exits.

that

service

input/output
protection

For

information

If the device is a terminal, a message indicates

hangup,

Guide.

Only the owner of a device can associate a mailbox
with
the
device
(the
owner
1is
the
process
that has allocated the
device, either implicitly or explicitly).
Then,
the
device

~driver

in conjunCtion with network

User's

Section

how

to
may

the

system

Guide.

$ASSIGN

3.4,

path

the
be

User's

use

caller

actually

device.

controls

~
the

access

device,

can

applied

service,

but

does

perform

Privilege
device
to

and

drivers.

devices,

see

|
assign

"Input/Output

channels

Services."

for

input/output

\..vu’

SYSTEM

SERVICE

DESCRIPTIONS

$BINTIM
4.7

SBINTIM - CONVERT ASCII

STRING
TO BINARY TIME

The Convert ASCII String to Binary Time
system
service
converts
an
ASCII
string
to an absolute or delta time value in the system 64-bit
time format suitable for 1nput to the Set Timer (SSETIMR) or
Schedule
Wakeup ($SSCHDWK) system services.

Macro

Format:

SBINTIM

High-Level

timbuf

Language

,timadr

Format:

SYSSBINTIM (timbuf

,timadr)

timbuf
address

of a

character

containing
the
required formats

delta

tlmadr
address
64-bit

Return

SS$

time

string

absolute
or
of the ASCII

spe01f1ed

a quadword

that

descriptor

pointing

the

buffer

delta
strings

time
to be converted.
The
are described in the Notes,

it must

receive

less

than

10,000

the

converted

days.

time

1in

format.

Status:

NORMAL
Service

successfully

completed.

SSS$_ IVTIME
The syntax of the specified ASCII
component 1s out of range.

string

is invalid,

the

time

Notes:
1.

The

SBINTIM

and

does

before it
exception
cannot be

service
not

check

executes

at the

access mode

whether

address

arguments

are

the

caller

accessible

executes.
Therefore, an access violation causes an
condition if the input buffer or buffer descriptor
read or the output buffer cannot be written.

- SYSTEM SERVICE DESCRIPTIONS
- CONVERT ASCII STRING TO BINARY TIME

$SBINTIM

‘The

required

ASCII

Absolute Time:
Delta

Time:

‘
|
Field

input

strings

have

the

format:

dd-mmm-yyyy hh:mm:ss.cc

dddd

"Length
(Bytes)

hh:mm:ss.cc

Contents

day

hyphen

mmm

month

|
Range of values

month|l

Required

syntax

JAN,

FEB,

MAR,

APR,

|MAY,

JUN,

JUL,

AUG,

SEP,

OCT,

NOV, DEC

hyphen

Required

VYVY

year

1858

blank

Required syntax
or more blanks)

hh
:

2
1

hour
colon

minutes

e
SS

1
2

colon
seconds

|Required
00 - 59

syntax

period

Required

syntax

hundredths

syntax

9999

00 - 23
Required
00

(one
,

syntax

- 99

of seconds

dddd

-4

number

0000

days

(1n

- 9999

24-hour
units)

The following syntax rules apply to the codlng of
input

string:

the

fields

For
the

absolute time values, the
S$BINTIM
service
supplies
current system date and time for nonspecified fields.
fields
the
must be

can

date

and

truncated.

punctuation
specified.

time

can

omitted,
periods)

the

ASCII

Any

Trailing

the

omitted.

leading fields

are

(hyphens,
blanks,
colons,
For example, the string

--12:00:00. 00

results

For delta

absolute

tlme

t1me

values,

of 12:00

the

SBINTIM

seconds.

the

current

service

day.

defaults.

nonspecified
fields
to
0.
Trailing
fields = can
be
truncated.
If leading fields are omitted from
the
time
value,
the punctuation (blanks, colons, perlods) must be
specified. For example, the string
0
~

results
®

::10

delta

time of

For both absolute and delta time values, there
number
of
leading
blanks,
and
any
number
between fields normally delimited
by
blanks.

there can be
t1me f1elds.

embedded

blanks within elther

can be any
of blanks
However,

the

date

SYSTEM SERVICE DESCRIPTIONS

$BRDCST
4.8

$BRDCST -

BROADCAST

‘The
Broadcast
terminals.

system

service

writes

message

one

or more

Macro Format:
SBRDCST

High=Level

msgbuf,

Language

[devnam]

Format:

SYSSBRDCST(msgbuf

[devnam])

msgbuf

address of a character string descrlptor p01nt1ng to the text of
the
message
to be broadcast.
The maximum length of the message
is 250 bytes.
»
o
devnam

address of a character strlng descrlptor p01nt1ng to the name
of
the
terminal
that is to receive the message.
The string may be
either a physical device name or a logical name.
If
the
first
character
1in the string is an underscore character (_ ), the name
is considered a physical device name.
Otherwise,
a single
level
of
1logical
name. translatlon 1s
performed and the eqguivalence
name,

any,

used.

If this argument is omitted,
is

broadcast

to all

or specified as 0,

then the

If the first longword in the descriptor contains a 0,

sent

all

terminals

that

are

SSS

currently

NORMAL
Service

successfully

completed.

SS$_DEVOFFLINE
The specified terminal
reception, has enabled
SS$

Status:

SS$_ACCVIO
|
|
The message buffer or
buffer
descriptor,
string or string descriptor, cannot be read

the message

allocated

processes.

. Return

message

terminals.

the
device
by the caller.

|
is offllne, has disabled broadcast message
passall mode, or is not a terminal.

EXQUOTA

The process has exceeded its buffer space quota and has
resource
wait
system service.

SS$_INSFMEM
Insufficient
request
and

mode

with
.

the

Set Resource Wait Mode

system dynamic memory 1s
the process has disabled

Set Resource Wait Mode

name

(SSETRWM)

disabled

(SSETRWM)

available to
complete the
resource wait mode with the

system service.

SYSTEM SERVICE DESCRIPTIONS
$SBRDCST - BROADCAST

SS$_NOPRIV
The process does not have
SS$_NOSUCHDEV

Warning.
receive

the privilege

to broadcast messages.

The specified terminal does not

exist,

broadcast

the message.

cannot

Privilege Restrictions:

The user privilege OPER is required to

message

This
service
requires
system
dynamic
memory,
and
uses
process's
buffered
I/0
byte
count quota (BYTLM) to buffer

the
the

that

than

one terminal,

allocated

or to broadcast a message to a terminal

any other

user.

Resources Required/Returned:

message while

the

service

executes.

Notes:

The service does not return control to the caller

The
message
immediately,

specified

terminals

have

received

the

until

broadcast message.

all

1is displayed
at
all
specified
terminals
regardless of the current state of the terminal
(reading or writing).
Each terminal is then returned to
the
state
1t
was in prior to the reception of the message.
The

message is preceded and followed by

carriage

return/line

feed.

However,
is not

a terminal cannot receive a broadcast message
if it

in use-as an

interactive

terminal.

SYSTEM SERVICE DESCRIPTIONS

$CANCEL
4.9

SCANCEL
- CANCEL I/O ON CHANNEL

The Cancel
requests
requests

Macro

I/O On Channel

on
that

system

service

a
specific
channel.
are queued as well as

cancels

all

pending

1I/0

1In general, this includes all I/0
the request currently in progress.

Format:

SCANCEL

chan

High—Level Language Format:
SYSSCANCEL (chan)
chan

|
number

Return

the I/O

channel

which

I/0

.
is

|
canceled.

Status:

SS$_NORMAL
Service

successfully

completed.

SSS _EXQUOTA

The

process has
exceeded
disabled
resource
wait

(SSETRWM)

system

its

quota

mode

with

»
for

the

direct

Set

service.

I/0
and
Resource Wait

has
Mode

SSS INSFMEM
-

Insufficient

system

1/0,

process

and

the

Resource Wait

SS$_IVCHAN
An invalid

~\o...//

number

Mode

dynamic

has

(SSETRWM)

channel

was

larger than

memory

disabled

system

spec1f1ed
the

number

available

resource

wait mode

cancel

with

the

Set

service.

that
of

is,

channel

channels

number

available.

0
|

SS$_NOPRIV
The

specified channel is not
privileged access mode.

ass1gned

was

assigned

from

'Privilége Restrictions:
I1/0 can be canceled only from an access mode

privileged
than
the access mode
assignment
was made.

Resources

The

from which

equal
the

original

channel

system

dynamic

Required/Returned:

Cancel
and

memory

I/0

Channel system service
process's direct I/0

uses the

requires
limit

(DIOLM)

quota.

SYSTEM SERVICE DESCRIPTIONS

- CANCEL I/O ON CHANNEL
SCANCEL
Notes:

driver
is canceled, the
When a request currently in progress
Actual cancellation may or may not
notified immediately.
is
of the
state
on the 1logical
occur immediately depending
occur, the same action as
cancellation does
When
driver.
that taken for queued requests is performed:

The speCified event flag 1s set.

The first word of the I/O status block,

The AST,

set

to SS$_CANCEL.

if specified,

if specified,
|

1is

1is queued.

actual
the
and
Proper synchronization between this service
requires the issuing process to
requests
I/0
of
canceling
note
then
and
wait for I/0 completion in the normal manner
that the I/0 has been canceled.

If the I/0 operation is a virtual I/0 operation
involving a
disk or tape ACP, the I/O cannot be canceled.
1In the case of
a magnetic tape,
however,
cancellation
may
occur
1if
the
device

driver

1is

hung.

Outstanding I/0 requests are automatically canceled
at
exit.

image

additional
and
service
system
$CANCEL
the
of
an example
For
that perform device-dependent I/0
system services
information on
operations, see Section 3.4, "Input/Output Services."

SYSTEM SERVICE DESCRIPTIONS

SCANEXH
4.10

S$CANEXH

CANCEL EXIT HANDLER

The Cancel Exit Handler system service deletes an exit
control
block
from
the 1list
of control blocks for the calling access mode.
Exit
- control blocks are declared by
the
Declare
Exit
Handler
($SDCLEXH)
system service,
and are queued according to access mode in a last-in
- first-out order.
,
o
)

Macro

Format:

SCANEXH

[desblk]

High-Level Language Format:
SYSSCANEXH
( [desblk])
desblk
address

the

‘canceled.
blocks

Return

are

control

not

describing

specified,

canceled

for

the

exit
specified
as 0,

current

the

access

handler
all exit

to be
control

mode.

Status:

SSS_NORMAL

Service successfully

SS$

block

ACCVIO

~ The first longword
longword

read by
control

a previous

the caller,
block cannot

SS$_NOHANDLER
- Warning.

completed.

the

exit

control

exit control

block

or
the
first
1longword
be written by the caller.

the

4
The

exit

handler

specified

does

the

first

in the list cannot

not

exist.

preceding
-

SYSTEM SERVICE DESCRIPTIONS

SCANTIM
4.11

S$SCANTIM - CANCEL TIMER REQUEST

The Cancel Timer Request system service
cancels all
or a
selected
subset
of
the
Set
Timer
requests previously issued by the current
image executing in
a process.
Cancellation is based
on
the request
identification
specified
1in
the Set Timer (SSETIMR) system service.
If
more
than
one
timer
request
was
given
the
same
request
identification,

they

are

all

canceled.

'Macro Format:
SCANTIM

[regidt]

,[acmode]

High-Level Languagé Format:
SYSSCANTIM([reqidt]

, [acmode])

reqidt

request identification of the timer request(s) to be canceled.

value of
be

(the default)

indicates

that all

requests are

canceled.

acmode

access mode of the request(s) to be
maximized
with the access mode of
requests issued from an access mode
than

Return

timer

the

resultant

access

mode

are

canceled.
The access mode is
the caller.
Only those timer
equal to or
less
privileged
canceled.

Status:

5S$_NORMAL

Service

Privilege

successfully

completed.

Restrictions:

Timer requests can be canceled only from access modes equal to or
more privileged than the access mode from which the requests were

~issued.

Resources Required/Returned:
Canceled timer requests are restored
timer queue entries (TQELM quota).

the

process's

quota

for

Note:

OQutstanding timer requests are automatically canceled

image

exit.

For

example

the

$CANTIM system ‘service,

information
on
timer scheduled
Time Conversion Services."

requests,

see

Section

and

3.6,

additional
"Timer

and

SYSTEM SERVICE DESCRIPTIONS

$CANWAK
4.12

S$CANWAK - CANCEL WAKEUP

The Cancel Wakeup system service removes all scheduled wakeup reguests

for a process from the timer queue, including those made by the caller
or by other processes.
Scheduled wakeup requests are
made
with
the
Schedule Wakeup (SSCHDWK) system service.
.
,

Macro

Format:

SCANWAK

[pidadr]

, [prcnam]

High-Level Language'Format:

SYS$CANWAK([pidadr] , [prcnam])
pidadr

address of a longword containing the
process
identification
the process for which wakeups are to be canceled.

prcnam

address of a character string descrlptor pointing to the
process
name
string.
The process name is implicitly qualified by the
group number of»the process issuing the cancel wakeup request.
If neither

a process

identification nor

a process name

scheduled wakeup requests for the caller are canceled.

how the service
- 3-3.
Table 3-3

Return

SS$

specified,

interprets the PIDADR and PRCNAM arguments, see
is in Section 3.5, "Process Control Services."

Table

Status:

NORMAL
Serv1ce

successfully

completed

SSS_ACCVIO
|
The process name string or
the process identification

SS$_IVLOGNAM

The process name
characters.

string descriptor cannot be
read,
cannot be written; by the caller.

string has a

length of

has

than

SSS NONEXPR

Warning.
The specified process does not
process identification was specified.

SSS

1is

For details on

NOPRIV The process does not
spec1f1ed process.

have

the pr1v1lege

exist,

to cancel

wakeups

1invalid

for

the

SYSTEM

SERVICE

DESCRIPTIONS

'SCANWAK - CANCEL WAKEUP

Privilege Restrictions:
User

privileges

are

required

cancel

scheduled

wakeup

requests

for:

®
e

Other processes in the same group'(GROUP privilege)
| Any other process in the system (WORLD privilege)

Resources Required/Returned:
Canceled wakeup
(ASTLM).

requests

are

restored

quota

the

process's

AST

1limit

Notes:

Pending wakeup requests

This service bnly cancels

automatically canceled at

scheduled;
1t does
Wake Process (SWAKE)

issued

image exit.

wakeup

the

current image

requests

that

not cancel wakeup requests
system service.

‘are

have been

made

For an example of the $CANWAK system service, see Section 3.6,

with the

"Timer

and
Time Conversion
Services." For
more
information on
process
hibernation and waking, see Section 3.5, "Process Control Services."

SYSTEM SERVICE DESCRIPTIONS

$CLREF
4.13

$CLREF - CLEAR EVENT FLAG

The Clear Event Flag system service
common event flag cluster to 0.

Macro

sets

event flag
|

1local

event

flag

was

event

flag

was

Format:

SCLREF

efn

High-Level Language Format:
SYSSCLREF (efn)

efn

the event

flag

to be cleared.

number

Return

Status:

SS$_WASCLR

Service successfully
previously 0.

SS$_WASSET
Service

completed.

The

specified

completed.

The

specified

|
successfully

‘previously 1.

- 88$ ILLEFC
An

illegal event

flag number was specified.

SS$ UNASEFC
The process
is not associated
specified event flag.

with

the

c¢luster

<containing
|

the
|

Note:

For an éxample of the $SCLREF system
"Event

Flag

Services."

servide,
|

see

Section.

3.1,

SYSTEM SERVICE DESCRIPTIONS

4.14

E
MODE
$CMEXEC- CHANGE TO EXECUTIV

The Change to Executive Mode system service allows a process to change
its access mode to executive, execute a specified routine, and then
return to the access mode in effect before the call was issued.
Format:

Macro

High-Level

,[arglst]

routin

SCMEXEC

Language

Format:

SYS$CMEXEC(routin , larglst])
|

routin

arglst

address of the argument list to be supplied to

Return

any.

the

address of the routine to be executed in executive mode.
-

routine,
:

1if

Status:

SS$_NOPRIV

The process does

not

have the

privilege

to change

mode

executive.

"All other values returned are from the routine executed.
Privilege Restrictions:

A process can call this service if:
®

It has the user privilege CMEXEC.

)

It is currently executing in either executive or kernel mode.

Note:

The $CMEXEC

system

service

uses

standard

procedure

calling

If no
conventions to pass control to the specified routine.
a
contains
(AP)
pointer
argument
the
specified,
is
argument list
0, unless it 1is modified by the caller. The routine must exit

with a RET

instruction.

SYSTEM SERVICE DESCRIPTIONS

$CMKRNL
4.15

TO KERNEL MODE
SCMKRNL - CHANGE

The Change to Kernel Mode system service allows a process to change
its access mode to kernel, execute a specified routine, and then
return to the access mode in effect before the call was issued.
Format:

Macro

SCMKRNL

routin

,[arglst]

High-Level Language Format:

SYSSCMKRNL(routin , [arglst])

routin

in kernel mode.
address of the routine to be executed
|

arglst

address of the argument list to be Sfipplied to

the

1if

routine,

any.

Return

Status:

SS$_NOPRIV

"\1\-*//

to change mode to kernel.
The process does not have the privilege

All other values returned are from the routine executed.
Privilege Restrictions:

A process can call this service if:

It has the user privilege CMKRNL.

@ It is currently executing in either executive or kernel mode.
Note:

The SCMKRNL system service uses standard procedure calling
If no
conventions to pass control to the specified routine.
a
contains
(AP)
pointer
argument
the
specified,
is
list
argument
0, unless it 1is modified by the caller. The routine must exit
with a RET instruction.

SYSTEM

SERVICE

DESCRIPTIONS

$CNTREG
4.16

SCNTREG

CONTRACT

PROGRAM/CONTROL

REGION

The Contract Program/Control Region system service deletes
a specified
number
of pages from the current end of the program or control
region
of a process's
virtual
address
space.
The
deleted
pages
become

inaccessible;

Macro

any

references

them

cause

access

violations.

Format:

$CNTREG

High-Level

pagcnt

Language

,[retadr]

,[region]

Format:

SYSSCNTREG (pagcent
pagcnt

,[acmode]

, [retadr]

, [acmode]

, [region])

number
or

pages

control

the

and

—
mode

specified

from

the

current

array
to

ending

receive

page

the

program

the virtual addresses
deleted area.

end

page

acmode

the

access

caller.

deleted

,
2-longword

starting

access

region.

retadr
address

owner

mode

1is

the

pages

maximized

with

deleted.

the access

mode

The

the

region

indicator.

program

region

indicates

that

(PO

value

region)

the

control

region

contracted.

Return

(the
to

default)

indicates

contracted,

(Pl

and

region)

that

the

a value

be
—

Status:

Service

completed.

successfully

./”’

SS$_NORMAL|

SS$_ACCVIO
The

return

address

- 8S$_ILLPAGCNT
|

The

array

cannot

written

|
the caller.

specified

page

count

was

less

than

SS$_PAGOWNVIO
A

page

access

the

mode.

specified

range

owned

privileged

SCNTREG

SYSTEM SERVICE DESCRIPTIONS
- CONTRACT PROGRAM/CONTROL REGION

Notes:

If an error occurs while deleting pages,

the

return array,

requested, indicates
the pages that were successfully deleted
before the error occurred.
1If no pages
were
deleted,
both
longwords in the return address array contain a -1.
-

The S$CNTREG system service can delete

pages

only

from

current
end
of the process's program or control region.
delete a specific range of pages in either
region,
use
Delete Virtual Address Space ($SDELTVA) system service.

the

To
the

\-1"/

For an example of the SCNTREG system service and additional details
on
page
<creation
and
deletion,
see
Section
3.8.2,
"Increasing
and
Decreasing Virtual Address Space."
-

SYSTEM SERVICE DESCRIPTIONS

SCRELOG
4.17
The

$CRELOG
- CREATE LOGICAL NAME
Create

Logical

Name

equivalence
‘table.
the new

Macro

system

service

inserts

a logical

name
1into
the
process,
group, oOr
If the logical name already exists 1n
the
definition supersedes the old.

name

and

1its

system logical name
respective table,
-

Format:

SCRELOG
High-Level

[tblflg] ,lognam ,eqlnam',[acmode]

Language Format:

SYSSCRELOG ([tblflg]

,lognam

,eglnam

,[acmode])

tblflg

logical

name table

table

(this

‘and

1is

indicates

lognam
address

number.

the

default

process

character

name string.

A value

value),

logical

string

indicates

name

descriptor

(}Ay#Lr &496;>

the

table.

the

system

group

table,

pointing

the

1logical

eglnam
address

equivalence

character

name

string.

string

descriptor

pointing

the

acmode
access

mode

Access

modes

table.

mode

Return

associated

only

qualify

The

specified

access

the

caller.

with

mode

logical
1in

name

table

the process

maximized

entry.

logical

with

the

name

access

Status:

SS$_NORMAL

Service successfully completed.
~specified logical name table.

SS$

the

names

SUPERSEDE
Service successfully completed
A
a previous equivalence name in the

new

name

was

entered

the

new equivalence name
replaced
spe01f1ed logical name table.

SS$_ACCVIO
name

strlng

SS$_INSFMEM

Insufficient system
group

exceeded
code

1is

mode

with

system

dynamic
1logical

memory
name

its

limit for process
only returned if the

the

Set

Resource Wait

strlng

descriptor
|

available

allocate

table

entry

the

process

logical

name

table

process

has

disabled

Mode

($SSETRWM)

entries.
resource

system

a
has

The
wait

service.

\"‘%‘/ .

The logical name or equivalence
cannot be read by the caller.

SYSTEM

SERVICE

DESCRIPTIONS

SCRELOG - CREATE LOGICAL NAME
SS$_IVLOGNAM

The logical name or
has

than

SS$_IVLOGTAB

An invalid

logical

SS$_NOPRIV

equivalence name

string has
a length
of 0,

characters.

name

table

logical

name table.

number

was

specified.

The process does not have the privilege to place an entry in
specified

the

Privilege Restrictions:
The user privileges GRPNAM
entries
in
respectively.

the

and

system

SYSNAM

and

are"required'

group

logical
|

name

place
tables,

Resources Required/Returned:
l.

Up to
5 pages of memory are available
in the
of
a
process's
virtual address
process logical name table.

Creation of
name tables

space

control/‘region

store

names

the
-

logical names for the group
and
requires system dynamic memory.

system
|

1logical

Note:

Logical names can also be created from the command
the

‘For
name

ASSIGN,

examples of

DEFINE,

the

translation

Services."

ALLOCATE,

$CRELOG
and

and

MOUNT

system service,

deletion,

see

stream,

with

commands.

and

Section

details
3.3,

logical

"Logical

Name

SYSTEM

SERVICE

DESCRIPTIONS

$SCREMBX
4.18

$CREMBX
- CREATE MAILBOX AND ASSIGN CHANNEL

The Create Mailbox and AsSign Channel system service creates a virtual
mailbox
device
system provides

Macro

named
MBn:
and
the unit number, n,

assigns
when it

an I/0 channel to it.
creates the mailbox.

The

Format:

[prmflg]

SCREMBX

[acmode]

High-Level

Language

,chan

,[promsk]

,[bufquo]

,[maxmsg]

,[lognam]

Format:

SYSSCREMBX([prmflg] ,chan , [maxmsg] ,[bufquo] ,[promsk]
, lacmode]

prmflg

,[lognam])

permanent indicator.

value

indicates

that

permanent

mailbox
1is
to
be
created.
The logical name, if specified, 1is
~entered in the system logical name table.
A
wvalue
of 0 (the
default)
1indicates a
temporary
mailbox.
The logical name, if
specified, is entered in the group logical name table.
|
chan
address

a word

maxmsg

receive

the

channel

number

assigned.

number indicating the maximum size of messages that can be
sent
to
the mailbox.
1If not specified, or specified
as 0, the system
provides a default value.
|
|
bufquo
number

bytes

system

dynamic

memory

buffer
messages
sent
to the mailbox.
"this value must be less than
or
equal
quota.
If not specified, or specified
a default value.

that

can

used

For a temporary mailbox,
to
the
process
buffer
as 0, the system provides

promsk

numeric

value

The mask

representing

contains

four

the

4-bit

protection mask

the

mailbox.

fields:

WORLD

for

GROUP

OWNER

SYSTEM

Bits read from right to left in each field, when clear,
that
read,
are granted

write,
extend and delete privileges,
to the particular category of user.

Only
read
protection.

and

If
are

not

write privileges

meaningful

indicate

that

for

order,

mailbox
|

specified,

granted

are

all

specified

users.

as
|

4-32

read

and

write

privileges

$SCREMBX

SYSTEM SERVICE DESCRIPTIONS

CREATE MAILBOX AND ASSIGN

CHANNEL
|

acmode

access mode to be
associated
with
the
channel
to
which
mailbox is
assigned.
The
access
mode
is maximized with
access mode

the

caller.

lognam

the
the

address of a character string descriptor pointing to the
logical
name
string
for the mailbox.
The logical name 1is entered into
the group logical name table (if it is a
temporary
mailbox)
or
the system logical name table (if it is a permanent mailbox).
1In
either case, the MBn:
name is entered as
the equivalence
name.

(the

first

character

the

equivalence

name

string

1s an

underline character [_]).
Processes can use the logical name
assign I/0 channels to the mailbox.

Return Status:
SS$ NORMAL

/l’

Service

successfully completed
,

SSS$_ SUPERSEDE

Service successfully completed.
A new equivalence name
replaced
a previous equivalence name for the mailbox logical name.

SS$_ACCVIO

The logical name string or strlng descrlptor cannot be
- the channel number cannot be written, by the caller.

SS$_EXQUOTA

read,

\./,

The process has exceeded its buffered I/0 byte count quota.
|

SS$_INSFMEM

Insufficient system dynamic¢ memory

1is avallable to

complete

the

service.

SS$_IVLOGNAM

The logical name strlng has a length of 0 or

has

characters.

SSS_NOIOCHAN |
No I/O channel

SS$ NOPRIV

o
avallable

The process does not

for

than

either

assignment.
|

have

the privilege

temporary or a permanent mailbox.

<create

Privilege Restrictions:

required
PRMMBX are
‘The user privileges TMPMBX and
temporary and permanent mailboxes, respectively.

create

SYSTEM

SERVICE

DESCRIPTIONS

SCREMBX - CREATE MAILBOX AND ASSIGN CHANNEL
Resources
1.

Required/Returned:

System dynamic memory is required for
device
logical

data
name

base
table,

for
if a

the

the
mailbox
logical name

When a temporary mailbox is created,

allocation

and for an entry
is specified.

the

process's

the

buffered

I/0
byte
count
(BYTLM)
quota
1is
reduced by
the amount
specified in the BUFQUO argument.
The size
of
the
mailbox
unit
control
block,
and
the
1logical
name
(if
one
1is
specified) are also subtracted from the quota.
The quota
is
returned to the process ‘when the mailbox is deleted.

Notes:

After a mailbox is created,'the creating
processes

can

assign

Assign I/0 Channel
maintains

assigned

additional

(SASSIGN)

reference

channels

system

count

a mailbox;

the

count

process

and

service.

the

The

number

other

calling
of

decreased

the

system
channels

whenever

channel is deassigned with the Deassign I/0 Channel (SDASSGN)
system service or when the image that
assigned
the
channel
exits.
If
it
1s
a
temporary mailbox, it is deleted when
there are no more
channels
assigned.
Permanent
mailboxes
must
be
explicitly
marked
for
deletion
with
the Delete
Mailbox ($DELMBX) system service.
A mallbox
however,

1s
be

treated
mounted

shareable

are

assigned sequentially

(from

a maximum

numbers
unit 1.

have

65,535)

been

used,

increasing
as

the

unit number

by
calling
service.

Channel
|

Default values
quota
(an
determined

Get

for

cannot,

I/O

they

are

wunit

numbers

system

created.

starts

When

numbering

A process can obtain the
the

device;

allocated.

Mailboxes
all unit
again at

For
see

as
or

the

Information

the maximum message

size

created

mailbox

(SGETCHN)
-

system

and

buffer

the

appropriate
multiple
of
the
message size) are
for a specific system during system generation.

an example of mallbox creatlon
Section 3.4.13, "Mailboxes.

and

1nput/output operations to
|

it,

SYSTEM

SERVICE DESCRIPTIONS

$CREPRC
4.19

SCREPRC

- CREATE PROCESS

The Create Process system service allows a process to
create
another
process.
The created process can be either a subprocess or a detached
process.

A detached process is a fully-independent procéss.

‘For

example,

the

process
that
the
system
creates
when a user logs in is a detached
process.
A subprocess, on the other hand, is related to
1ts
creator
in
a
tree
1like
structure;
it
receives a portion of the creating
process's resource quotas
and
must
terminate
before
the
creating
process.
The
specification of the UIC argument controls whether the

created process is a subprocess or a detached process.

Macro Format:
_

SCREPRC

[pidadr] ,[image]
,[input] ,[output] ,[error]
, [prvadr] ,[quota] ,[prcnam] ,[baspri] ,[uic]
, [mbxunt]
,[stsflg]

High-Level Language Format:

SYSSCREPRC
([pidadr] ,[image] ,[input] , [output]
[prvadr]

; [mbxunt]

,[quota]

,[prcnam]

,[baspri]

, [error]
,[uic]

,[stsflg])

pidadr

- address of
a
number
image

input

longword

assigned

the

receive

the

created process.

process

identification

|
|
|
address of a character string descriptor
pointing
to
the
file
specification
of
the
image
to
be
activated
1in
the created
process.
The image name can have a maximum of 63 characters.
|

address
of
equivalence

a
character
name
string

SYSSINPUT in the
equivalence name
output

string
descriptor
pointing
to
to be associated with the logical

logical name table for the created process.
string can have a maximum of 63 characters.

the
name
The

address
of
a
character string
descriptor
pointing
to
the
equivalence
name
string
to be associated with the logical name
SYSSOUTPUT in the logical name table
for
the
created
process.
The equivalence name string can have a maximum of 63 characters.
error

address
of
a
character
string
descriptor
pointing
to
equivalence
name
string
to be associated with the logical
SYSSERROR in the logical name table for the created process.
equivalence name string can have a maximum of 63 characters.
prvadr

the
name
The

address of a 64-bit mask
defining
privileges
for
the
<created
process.
The mask is formed by ORing bit settings corresponding
to specific privileges.
The SPRVDEF macro defines the
following
symbolic names for the bit settings:

SYSTEM SERVICE DESCRIPTIONS
$SCREPRC - CREATE PROCESS
Name

Privilege

PRVSV_ALLSPOOL
PRVSV BUGCHK

Allocate
Make bug

PRVSV_DETACH

- Create

PRVSV CMEXEC
PRV$V_CMKRNL

a spooled device
check error log entries

Change mode
Change mode

PRVSV DIAGNOSE

detached

Diagnose

PRV$V_EXQUOTA

to executive
to kernel

Exceed quotas

PRVSV_GROUP
PRVS$SV GRPNAM

Group
~Place

name

process
name in

control
logical

group

table

PRV$V_LOG_IO

Perform logical

PRVSV MOUNT

Issue

PRVSV NETMBX

Create
-

I/O operations

volume

QIO

All
IO

PRVS$V PRMCEB
-

processes

for

which

accounting

operator

Perform

privileges

physical

I/0

operations

Create permanent common
event flag clusters

PRVSV_PRMGBL
PRVSV_PRMMBX

Create
Create

permanent global sections
permanent mailboxes

process

PRVSV_PSWAPM

Change

PRVSV_SETPRI

Set

PRVSV_SETPRV
PRVSV_SYSGBL
PRVSV SYSNAM

Set any process privileges
Create system global sections
Place name in system

PRVSV_TMPMBX

Create temporary

PRVSV_VOLPRO

Override

PRVSV_WORLD

World

this privilege,
of the creating
have

are

the mask
process,

not

of a list
process.

specified as 0,
resource quotas.
The format of
quota
values
quotas, their

granted

volume

address

priority

maillboxes
protection

control

is required to
grant
a
process
any
one's own.
If the caller does not have
1is minimized with the current privileges
that is, any privileges the creator does
but

error

the

system

code

supplies
default
o
o

returned.

values
S

for

|
-

the

the quota list and
considerations
for
specifying
are
described
1in
Section
4.19.1.
The specific
defaults, and their minimum values, are
1listed
in

status

:
values
assigning
resource
gquotas
to
the
If no address is specified, or the address is

Section 4.19.2.
prcnam

swap mode

process

SETPRV
than

qguota

address
created

any

logical name table

The user privilege
privileges
higher

not

done

PRVSV_OPER
PHY

mount

Create a network device

PRVSV_NOACNT

PRVSV

processes

devices

character

string

descriptor

pointing

l15-character
process.
The

process
process

name
string to be assigned
name is implicitly qualified

number

of the

caller,

if
a

‘number

the UIC argqument,

subprocess

to
to
by

the created
the
group

created,

a detached process

created.

the

group

baspri
|
numeric value indicating the base priority to be assigned to
the
created
©process.
The priority must be in the range of 0 to 31,
where 31 is the highest priority
level
and
0
1is
the
lowest.
Normal
priorities
are
in
the
range
0
through
15,
and
time=-critical priorities are in the range
16 through 31.

SYSTEM SERVICE DESCRIPTIONS
If

not

specified,

$CREPRC

- CREATE

PROCESS

the

priority

for

base

the

created

process

1is

The user privilege ALTPRI is required to set
a
priority
higher
than
one's own.
If the caller does not have this privilege, the
specified base priority is compared with
the
<caller's
priority
and the lower of the two values is used.
uic

numeric value representing the user identification code (UIC)
of
the
created
process.
This
argument
also indicates whether a
process
is a

subprocess or
a detached process.

If not specified, or specified as 0 (the default),
it
1indicates
that the created process is aflsggprpcess,
the subprocess has the
same UIC

the creator.

If a nonzero value is specified it indicates

process

detached

process.

The

that

the

specified

created

value

1is

1nterpreted as a 32 bit octal number, with two l6-bit fields:
bits
bits

0-15 member number
16-31 group number

The user privilege

DETACH

1is

required

<create

detached

process.

mbxunt

unit number of a mailbox to receive a
termination
message
when
the
created
process 1s deleted.
If not specified, or specified

as 0 (the default), the system sends no termination message when
it
deletes
the process.
The format of the message is described
in Note

below.

stsflg

32-bit status
process.
The
Bit

flag indicating options selected
for
the
created
flag bits, when set, have the following meanings:

Meaning

0
1
2
3
4
5

Disable resource wait mode
Enable system service failure exception mode
Inhibit process swapping (PSWAPM privilege required)
Do not perform accounting (NOACNT pr1v11ege requ1red)
Batch (non-interactive) process
Force process to
hibernate
before
it
executes
the
image
‘
Provide detached process executing
LOGIN image
with
authorization
file attributes of the creator;
do not
check authorization file

Process is
a network connect object (NETMBX
required)

8-31

Return

‘

Reserved.

These

bits must

privilege

Status:

SS$_NORMAL
Serv1ce

successfully

completed

SS$_ACCVIO
|
|
The caller
cannot
read
a
specified
1input string
or
string
descriptor,
the
privilege
1list,
or
the quota list.
Or, the
caller cannot write the process identification.

SYSTEM

SERVICE

SCREPRC -

DESCRIPTIONS

CREATE

PROCESS

SS$_DUPLNAM

The process
name
within that group.
SS$

specified

duplicates

EXQUOTA
The

process has
subprocesses.
quota

value

exceeds

the

exceeded

specified
creator's

its

for

SS$_INSFMEM
Insufficient

service

SS$

and

Resource

system

dynamic

the

process

Wait

Mode

IVLOGNAM
The specified
characters.

process

the

disabled

(SSETRWM)

has

for
|

the

«creation

quota

memory

has

name

quota

corresponding

deductible and the remaining
less than the minimum.

SS$

already

specified

Set

one

quota;

for

the

or,

subprocess
the

creator

available

resource

quota

would

service.

length

complete

wait mode

system

creation

has

with

the

than

IVQUOTAL
The

quota

list

not

the

proper

format.

SS$_IVSTSFLG
A

SS$

reserved

status

flag

was

set.

NOPRIV

The caller has violated one of the privilege restrictions

listed

below.

Privilege

Restrictions:

User privileges
are required to:

Create detached processes (DETACH privilege)

Set a created subprocess's base priority
own

(ALTPRI

higher

than

one's

privilege)

3. Grant a process user pr1v1leges that the caller does»not have
(SETPRV privilege)

Disable
either
process
swap
accounting
functions
(NOACNT

mode
(PSWAPM
privilege)
privilege)
for
the
created

process

Resources
l.

Create

network

connect

object

(NETMBX

privilege)

Required/Returned:
The number

of subprocesses
that
a
process
controlled by the subprocess quota (PRCLM);
is returned when a subprocess is deleted.

The

Create

memory.

Process

system

service

requires

can
create
the quota amount

system

dynamic

SYSTEM SERVICE DESCRIPTIONS
$SCREPRC

When

subprocess

CREATE

created,

PROCESS

certain

the

quotas

granted

to it either specifically or by default are deducted from the
quotas of the creator, and may be returned
to the
creator
when
the
subprocess
1is
deleted.
Sections 4.19.1 through
4.19.3

describe

how

quotas

creation.

are

determined

process

Notes:

Some error conditions are
not
detected
until
the
created
process
executes.
These
conditions
1include an invalid or
nonexistent
image;
invalid
SYSSINPUT,
SYSSOUTPUT,
or
SYSSERROR
1logical
name equivalences;
and inadequate quotas
or insufficient privilege to execute the requested image.

If a mailbox unit is specified, the mailbox is not used until
the
<c¢reated
process
actually
terminates.
At that time, a
SASSIGN system service is
1issued
for
the
mailbox
in
the
context
of the terminating process and an accounting message
is sent to the mailbox.
1If the
mailbox
no
longer
exists,
cannot be assigned, or is full, the error is treated as if no
mailbox had been specified.
|
The message is sent before the process rundown
is
initiated
but
after
the
process
name has been set to null.
Thus, a
significant interval of time can occur between the sending of
the
termination
message
and
the
final
deletion
of
the
process.

To receive the message, the caller must issue a read
to
the
mailbox.
When the I/0 completes, the second longword of the
I/0 status block, if one is specified, contains
the
process
identification of the deleted process.
|

Symbolic names for offsets of fields within
the
accounting
message are defined in the $ACCDEF macro.
The offsets, their
symbolic names, lengths, and the contents
of each
field
are
listed below.
,

Offset

Name

ACC$W_MSGTYP

Length

Contents

word

MSGS$_DELPROC

word

ACCSL_FINALSTS

longword

not used
Exit status

ACCSL_PID -

longword

Process

longword

Not

ACCSQ TERMTIME

quadword

Current

code
identification

used

time

format
|

bytes

Account
-

'ACCST USERNAME

52
56
60

bytes

longword

|
|

ACCS$L_CPUTIM

|
|

system
process

termination

ACCST ACCOUNT

process,

User

CPU

name
blank

name,

time

for

filled

blank

wused

filled

process,
-

l10-millisecond units

ACCSL_PAGEFLTS

ACCSL_PGFLPEAK
ACCSL _WSPEAK
ACCSL_BIOCNT

the

longword

longword
longword
longword

Number

page

faults

incurred
by the process
in its lifetime
Peak paging file usage
Peak working set size
Count
of
buffered
1I/0
operations
performed by
‘the

process

SYSTEM SERVICE DESCRIPTIONS
SCREPRC

Offset

Name

ACC$L;DIOCNT' |

CREATE PROCESS

Length

Contents

longword'

Count
the

ACCSL_VOLUMES

ACCS3Q LOGIN
-

ACCSL_OWNER

direct . I/0
performed

process

longword

Count

quadword

by the process
Time in system

format
that process logged in

longword

Process

The length of the
termination
constant ACCSK_TERMLEN.
3.

operations

volumes mounted

identification

owner

message

equated

the

All subprocesses created by a process must
terminate
before
the
creating
process can be deleted.
1If subprocesses exist
when
their
<c¢reator
1s
deleted, they
are
automatically
deleted.

For examples of subprocess creation, termination mailboxes, and system
services
that
control
the
"Process Control Services."

4.19.1

execution of processes,

see Section

Format of the Quota List

The system defines
A guota limits the

specific resources that are controlled
use of a particular system resource by

The quota list addressed
by the QUOTA argument of the

SPQLDEF macro

defines

symbolic

names

for

the quotas

by
quotas.
a process.

$SCREPRC

system

in the

format:

service
<consists
of consecutive quota values contained
each preceded by a byte that indicates the quota type.

The

3.5,

longwords,

PQLS type
The quota list is terminated
example, a quota list may be
QLIST:

JBYTE

by
the
specified

FQL$_.FRCLM

«LONG 2
|
JEBYTE FQRL$.ASTLM
LONG 6

+RBYTE

4.19.2

FPQAL$_L.ISTEND

type
as:

code

y o LIMIT

¥
5
vy
y

NUMBER

For

SURFROCESSES

MAX = 2 SURFROCESSES
LIMIT NUMBER OF ASTS
MAX = &6 OUTSTANDING ASTS

END

QUOTA

LIST

Quota Descriptions

The individual quota types are described below.
indicates

PQLS_LISTEND.
o

the

characteristics

Each description also

the quota:

Minimum value.

A process cannot be created if

Default value.

If the quota list does not specify

have

following

for

a quota equal

particular

default value.

to or

quota,

greater

the

than

system

this minimum.

assigns
.

the

does

not

value

process

this

SYSTEM SERVICE DESCRIPTIONS
SCREPRC - CREATE PROCESS

Deductible/Non-deductible.
When
a subprocess is created, the
~value specified for a deductible quota is subtracted from the
current
gquota value
of
the
<creator..
These
quotas
are
returned
to
the
<creating
process
when
the subprocess is
deleted.

Non-deductible

Quotas are
process 1s

quotas

never deducted
created.

from

are

the

not

subtracted.

creator

ASTLM
TAST limit.

This quota
AST routines specified
address and the number
issued.

detached

listed
are
not
necessarily
they are, however, the values

Section 4.19.3 describes how these characteristics

may

affect

quota

restricts

in
of

both the number
of
outstanding
system service calls that accept an AST
scheduled wakeup requests that
can
be

,‘

PQL$

a
-

Note that the minimum and default values
those
provided
at
your installation;
recommended for general use.

assignments.

when

“\

Minimum:
Default:

2
10

Non—~deductible
PQLS

BIOLM

"Buffered I/O limit.
system-buffered

This quota limits the number of

I/0 operations.

A buffered

which uses an intermediate buffer from
the
than a buffer specified in a process's $QIO
Minimum:

I/0

outstanding

operation
is

system
request.

pool
|

one

rather

Default:

Non-deductible

\\-\c./

PQL$

BYTLM
“Buffered I/0 byte count quota.
This quota limits the
amount
system
space that can
be
used to buffer I/0 operations or
create temporary mailboxes.

of
to

Minimum:
1024
10240
Default:
Deductible

PQLS

CPULM
“CPU time
of CPU

11m1t
This
time used by

gquota can be used to limit the total amount
a process.
If the quota is specified as 0,

there

is no CPU time limit;

have

unlimited

process

CPU

unlimited

time

the creating process,
itself

1in order

limited

CPU
when

Minimum:
Default:

Deductible

time,
the
0
0

the

must

created

time.

If specified, the CPU time limit must be
milliseconds.
This quota is consumable;
been used, the process
is deleted.
If
creator

however,

to grant

the amount
of time

subprocess

specified in units of 10
when the time limit has
a
subprocess 1is given

used 1is not

deleted.

returned

the

SYSTEM SERVICE DESCRIPTIONS
SCREPRC - CREATE PROCESS

PQLS$

DIOLM

“Direct I/0 quota.
This quota limits the
number
of outstanding
direct
I/0
operations.
A direct I/0 operation is one for which
the system locks the pages containing the associated
I/O
buffer
in memory for the duration of the I/O operation.
.
2
Minimums:
Default:
6
Non-deductible

PQLS_FILLM

Open file guota.
This quota
process can have open at one
Minimum:
Default:
Deductible

PQLS

limits
time.

the number of

files

that

2
20

PGFLQUOTA

“Paging file quota.
This gquota limits the number
of pages
can be used to provide secondary storage
in the paging file
process's

that
for a

execution.

Minimum:
256
Default:
10000
Deductible
PQLS$ PRCLM

Subprocess quota.
process

can

Minimum:
Default:
Deductible

PQLS

This quota

limits

the

number

subprocesses

create.

0
8

TQELM

Timer gqueue entry qguota.
This quota limits both
the
number
timer
gueue
requests
a
process can
have outstanding and
creation of temporary common event flag clusters.
Minimum:
Default:

Deductible

of
the

0
8

PQLS$S WSDEFAULT

Default working

set

size.

This quota defines

the

number

of pages

in the default working set for any image executed by the process.
The maximum
size
that can
be specified for
this
quota
1is
determined by the working set size quota.
10
Minimum:
Default:
100
Non-deductible
PQLS

WSQUOTA

“Working set size quota.
This quota limits the maximum
size
to
which
an image
<can expand its working set size with the Adjust
Working Set Limit ($SADJWSL) system service.
Minimum:
10
Default:
200
Non-deductible

SYSTEM SERVICE DESCRIPTIONS
$CREPRC

4.19.3

Values

CREATE PROCESS

Quota Values

specified

the quota

list

are

not

necessarily the quotas that
The $CREPRC system
the
gquota
values

actually be assigned to the created process.
will
service performs the following steps to
determine
that will be assigned:
1.

It constructs
a default quota
created,

assigning

the

list

default

It reads the specified quota
corresponding
items
1in the

contains
multiple
entries
specification is used.

for

values

the
for

list, if any,
default list.
for
a
quota,
,

subprocess
The

resulting

being

1t
for

the quota

resulting

that

1is

value

the

compared

subprocess

with

If a detached
not compared
Moreover, the
value exceeds

deductible

from

the creator will

quota. required.
returned and the

compares
the guota

the
and

created:

value 1s

returned
and

the

the
list
last

only

the

current

the
corresponding
quota .of
the creator.
exceeds the creator's quota, the status code
is

being

qguotas.

and
updates
If the quota

For each item in the updated
quota 1list,
quota value with the minimum value required
uses the larger value.

process
all

the

still

not

have

created.

quota,

<creator's

value

1If the value
SS$_EXQUOTA

it
quota

least

deducts

the

and

verifies

the

minimum

If not, the status code SS§_EXQUOTA
subprocess is not created.

process 1s created, the
resulting
wvalues
are
with
the
<creator's, nor are gquotas deducted.
service does not check that a
specified
guot
the maximum allowed by the system.
|

SYSTEM

SERVICE

DESCRIPTIONS

$CRETVA
4;20

SCRETVA - CREATE VIRTUAL ADDRESS SPACE

The Create
to

Virtual

process's

Address

virtual

image.

Macro

Space

address

system
space

service

for

the

adds

range

execution

the

pages
current

Format:

SCRETVA inadr ,[retadr]
‘High-Level

Language

,[acmode]

Format:

SYSSCRETVA (inadr

,[retadr]

,[acmode])

inadr
address of a 2-longword array containing the starting and
ending
virtual
addresses
of
the pages to be created.
If the starting
and ending virtual addresses are the
same,
a
single
page
is
created.

Only

addresses
-

retadr

wvirtual

the

address of
virtual

the

used;

page

low-order

number

bits

portion

the

virtual

are

ignored.

the

starting and

ending

a 2-longword

addresses

array

the

receive

pages actually

created.

acmode
access

mode

access

mode

and

protection

for

maximized

the

with

new
the

protection
of the pages is read/write
mode and those more privileged.

Return

pages.

caller's

for

the

The

specified

access

mode.

The

resultant

access

return

address

Status:

SS$ NORMAL
Service

successfully

completed.

SS$_ACCVIO
The input

address

array

written,

has

exceeded

its

paging

file

working

set

1limit

cannot

array

cannot

the

read,

o
or

the

caller.

SS$_EXQUOTA
The

process

quota.

SS$_INSFWSL
The

process's

accommodate

the

SS$_NOPRIV
A

SS$

increased

size

the

page

the

not

virtual

large

enough

address

space.

specified

range

in the specified

range

the

system

address

space.

PAGOWNVIO

~ A page

deleted
that

because
the

owned

already
a

caller.

exists
privileged

and

can

access

not
mode

be
than
|

SS$_VASFULL
The

process's
virtual
address
available in the page tables for

4-44

space
is - full;
no
the requested pages.

space

1is

'SYSTEM SERVICE DESCRIPTIONS

SCRETVA - CREATE VIRTUAL ADDRESS SPACE

\..__9"'/

Resources Required/Returned:

The processes paging file quota (PGFLQUOTA) and working set limit
the increased
guota (WSQUOTA) must be sufficient to accommodate
size of the virtual address space.

Notes:

Pages are created starting at the address
first

longword

INADR and

ending

the

with

contained

the

1location addressed by the parameter

the

second

longword.

The

ending

address can be lower than the starting address. The return
address array indicates the byte addresses of the pages

\\\m/'

created.

If an error occurs while creating pages, the return array, 1if
requested, indicates the pages that were successfully created
before the error occurred. If no pages were created, both
longwords of the return address array contain a -1.

Each page to be created is first deleted,’if
then reinitialized to a demand-zero page.

The Expand Program/Control Regilon

(SEXPREG)

also

necessary,

adds

pages

and
a

For additional details on page
process's virtual address space.
"Increasing and Decreasing
3.8.2,
Section
see
,
deletion
and
creation

Virtual Address Space.”

SYSTEM SERVICE DESCRIPTIONS

$CRMPSC
4.21
The

SCRMPSC
Create

use

and

CREATE
Map

global

correspondence

Section

section

between

caller's

wvirtual
service maps it.

arguments

SCRMPSC

are

system

under

what

Macro

Format:

AND MAP

system

the

, [chan]

the

file

Table

virtual
addresses
in
which the section is to
virtual
addresses
are
virtual

the

low-order

page number

this

not mapped.

bits

argument
is

retadr

4-1

ignores

arguments.

,[flags]
, [vbn]

the

how

it,

,[gsdnam]

,[prot]

,[acmode]

,[pagent]

,[flags]

, [vbn]

are

not

array

the

and

,[ident]

,[pfc]

,[gsdnam]

,[ident]

,[prot]

,[pfc])

starting

and

,
containing

the

ending

the
©process's virtual address space into
be mapped.
If the
starting
and
ending
the same, a single page is mapped.
Only

portion

of
ignored.

the

virtual

specified,

specified

addresses

used;

the

section

starting and

ending

address of a 2-longword array to receive the

virtual

addresses
actually mapped.

the

pages

into

which

acmode
access

for
the

summarizes

passed

, [acmode]

,[chan]

2-longword

the

file
makes

pages

arguments

inadr
a

and

, [pagcnt]

;[retadr]

r lrelpag]

disk

Format:

SYS$CRMPS
([1i
C nadr]

address

optionally

the section already exists, the
actual operation requested, certain

requires

,[retadr]

» lrelpag]

and

optional.

interprets
it

identifies

section

blocks

circumstances

High-Level Language

service

private

space.

Depending

required

[inadr]

virtual

address

service

SCRMPSC

SECTION

the

section was

mode

mapping.
The
the caller.

the

owner

access

mode

the

pages

maximized

created

with

the

during

access

the

mode

flags
mask

defining the section type
and
characteristics.
Flag
bit
settings
may
be
ORed
together to override default attributes.
The $SECDEF macro defines symbolic names for the flag bits in the
mask.
Their meanings,
and the default values they override, are:

Flag

Meaning

SECSM_GBL
SECSM_CRF
SECSM_DZRO

Global section
Pages are copy-on-reference
Pages are demand-zero pages

SECSM_WRT
SECSM_PERM

Read/write
Permanent

SECSM_SYSGBL

System global

Default

section
section

4-46

Attribute

Private section
Pages are shared
Pages are not zeroed
- when copied
Read-only
Temporary
Group

global

section

SYSTEM

SCRMPSC
gsdnam
address of a
l5-character
global
by the

ident

SERVICE

DESCRIPTIONS

CREATE AND MAP SECTION

character string descriptor p01nt1ng to
the
1to
text name string for the global section.
For group

sections,
group

the

number

global
of

the

section name is
process creating

implicitly
the

global

qualified
section.

address of a quadword indicating-the version number of
section,
section,

global

and,
for
processes
mapping
to
an
existing
the criteria for matching the identification.

global

The

version number is in the second longword.
The version number
contains
two fields:
a minor identification in the low-order 24
bits and a major identification in the high-order 8 bits.
Values
for
these
fields
can be assigned by installation convention to

differentiate
is
spec1f1ed

versions of global sections.
If no version
number
when a section is created, processes that specify a
number when mapping cannot access the global section.

version

‘The first longword

specifies,

Value/Name

Match

Criteria

0
1

SECSK_MATALL
SECSK_MATEQU

Match
Match

all versions of the section
only if major and minor 1dent1f1cat10ns

SECSK_MATLEQ

matching
they can

«criteria.
The
be specified, and

wvalid
their

its

values,
meanings

1low-order

symbolic
are:

bits,

names

the

by which

match

Match

if the major identifications are
equal
and the minor identification of the mapper is
less
than
or
equal
to
the
minor
identification of the global section

The

match control field is ignored when a section is created.
no
address is specified, or is specified as 0 (the default),
version number and match control fields default to O.

relpag
relative

page number within
to
be mapped.
If

section
default),

virtual

the

block

global

section

file.

chan

the

the
not
1s

section of
specified,
mapped

~number

file

must

the

the first page in
or specified as 0

beg1nn1ng

with

the

1If
the

the
(the
first

channel

which

the

file

with

has

been

accessed.
The
macro;
the file
options parameter (FOP) in the FAB must indicate a user file open
(UFO
keyword).
The access mode at which the channel was opened
must be the same or less privileged than the access mode
of
the
caller.

have

been

accessed

RMS

SOPEN

pagcnt

number

‘

pages

the

section.

The

specified

page

count

1is

virtual block number in the file that marks the beginning of
section.
If
not specified, or specified as 0 (the default)
section is created beginning with the first virtual block
in
file.

the
the

compared
with
the number of pages in the section file;
1if they
are different, the lower value is used.
1If the page count is not
specified,
or
specified
as
0
(the
default)
the size of the
section file is used.
»
vbn

the

SYSTEM SERVICE DESCRIPTIONS
$SCRMPSC - CREATE AND MAP SECTION

numeric value representing the protectlon mask to be
section.

the global

applied

tc
»/

prot

WORLD

GROUP

The mask contains four 4-bit fields:
7

OWNER

SYSTEM

indicate

to left in each field, when clear,
"Bits read from right
read, write, execute, and delete privileges,

that

are granted to the particular category of user.

Only read and

wrlte pr1v1leges are meaningful for global section

pfc

protection.

If not specified, or specified as 0,

are granted

Return

write

read and

privileges

all users.

cluster
fault
page
many
how
‘indicates

for

fault occurs

page

in that order,

size
cluster
the
specified,
If
are to be brought into memory when a

size.
pages
a

s1ngle page.

Status:

SS$NORMAL

Service successfully completed.

The

specified

already existed and has been mapped.

SS$_ CREATED

Service successfully completed.

global

section

The specified global section did

not previously exist and has been created.

SS$_ ACCVIO

—

The input address array
or
the
global
section
name
or
name
cannot be read, or the return address array cannot be
descriptor
written,

SS$_ ENDOFFILE

Warning.
the

the

caller.

end of-file.

SSS$_ GPTFULL

There is no more room in the system global page
page table entries for the section.

table to

SS$_ GSDFULL

There is no more room in the system space allocated
control

SS$_ EXQUOTA

The

1nformat10n for global

process

exceeded

copy-on-reference
SS$_ INSFWSL

beYond

The starting virtual block number spec1f1ed

logical

1its

‘

file

quota

‘

creating

whlle
-

pages.

to maintain

sections.

paging

set

The
process's
working
set
1limit 1is
not
large
accommodate the increased size of the address space.

enough

SYSTEM SERVICE DESCRIPTIONS
SCRMPSC

Arguments

- CREATE

for

AND

Table 4-1
the SCRMPSC

Create and

SECTION

System Service

Create and

Map Global

Section

INADR

Optional2

Required

RETADR

Optional

ACMODE

Optional

Argument

FLAGS

SECSM_GBL
SECSM_CRF
SECSM_DZRO
SECSM_WRT
SECSM_PERM
SECSM_SYSGBL

Map Private

Required
Optional
Optional
Optional
Optional
Optional

Ignored
Not used
Not used
Optional
Not used
Optional

-—
Optional
Optional
Optional
Not used
Not used

Required

Not

- IDENT

Optional

Not used

- RELPAG

- Optional

‘Optional

Not used

CHAN

Required

PAGCNT

Required

VBN

Optional

PROT

Optional

Not used

PFC

Optional

GSDNAM

MAP

The Map Global Section ($MGBLSC)

system service

maps

global section.
2
If the SCRMPSC system service is called to create,
global section, the global section must be permanent.

SSS$_ IVCHAN
An

invalid

channel

or a number

SS$_ IVCHNLSEC
The channel

number

larger

number

was

than

spe01f1ed

specified,

that

used

but

not

map,

channel

the number of channels

existing
a

number

available.

currently active.

SS$_ IVLOGNAM
The specified global section
‘than 15 characters.

name

has

length

SS$_IVSECFLG
Either
a
An invalid flag has been spe01f1ed
been set, or one requiring a user privilege.
SS$_IVSECIDCTL
The match
invalid.

control

field

the

global

section

of 0,

reserved

has

flag

has

identification

1is

SYSTEM SERVICE DESCRIPTIONS

SCRMPSC

CREATE

AND MAP

SECTION

SS$_NOPRIV
The process does not have the privilege to create
section or a permanent group global section.

a system global

A page 1in the input address range is'in the system address space.
The

specified channel

privileged

access

SS$_PAGOWNVIO

A page

in the

privileged

does not exist or

specified

access

input address

are no entries - available

range

is owned

1in

the

system

process's

global
-

SS$_VASFULL

mode.

table.

The

from a

SS$_SECTBLFUL
There

was assigned

mode.

virtual

address

space

1is

full;

section
-

space

available in the page tables for the pages created
to contain the

mapped

Privilege

global

Restrictions:

The user
section;
global

Resources

section.

privilege SYSGBL 1is required to create a
system
global
the PRMGBL privilege 1s required to create a permanent

section.

Required/Returned:

The
process's
working set
1limit
quota
(WSQUOTA)
must
be
sufficient
to
accommodate
the
increased
size
of the virtual
address space when mapping a section.
If the section
pages
are
copy-on-reference,
the
process must also have sufficient paging
file quota (PGFLQUOTA).
»

Notes:

When the S$SCRMPSC system service maps a section, it calls
the
Create
Virtual Address Space (SCRETVA) system service to add
the pages specified by the INADR argument
to
the
process's
virtual
address
space.
The specified virtual addresses can
be in the program (PO) region or the control (Pl) region.
If a global section is of an
obtain the virtual address of

program

control

region

unknown
size,
a
process
can
the first available page in its

from

the

Get

= Job/Process

Information
(SGETJPI)
system
service
and
use the
returned as the starting address in the input address
The ending address may be a very high address (if the
is to be mapped in the program region) or a very low

address
array.
section
address

TM TM

(if
mapped
in
the
control
region).
The
SCRMPSC system
service returns the virtual addresses of the pages created in
the
RETADR
argument,
if
specified. The section is mapped
from a low address to a high address, regardless
of whether
the section is mapped
in the program or control region.

SYSTEM SERVICE DESCRIPTIONS

$CRMPSC

CREATE AND MAP

SECTION

If an error occurs during the mapping of
a global
section,
the
return
address array, if specified, indicates the pages
that were successfully mapped when the error occurred.
If no
pages were mapped,
contain -1.

both

longwords

the

return

address

array

If the global section
is permanent, it is not deleted
if
mapping

operation

For examples of
the
sections, see Section

fails.

<creation
and
mapping
3.8.6, "Sections."

private

and

the

global

SYSTEM SERVICE DESCRIPTIONS

4,22

S$DACEFC - DISASSOCIATE COMMON EVENT FLAG CLUSTER

The Disassociate Common Event Flag Cluster system
calling process's assocliation with a common event

Macro

service releases
flag cluster.

the

Format:

SDACEFC

High-Level

efn

Language

Format:

SYSSDACEFC (efn)

number

any

event

flag

the

common

cluster

The
flag
number
must
be
1in
the range
cluster 2 and 96 through 127 for cluster 3.

disassociated.
through 95 for

—'/S

efn

Return

Status:

SS$_NORMAL
Service

successfully

SS$_ILLEFC
An illegal event flag
in the range of event

completed.

number was specified.
flags 64 through 127.

The

|
number

|
must

Notes:

The
count
of
processes
associated
with
the
cluster
1is
decreased
for
each
process
that
disassociates.
When the
image that
associated
with
a
cluster
exits,
the
system
performs
an implicit disassociate for the cluster.
When the
count of processes associated with a temporary cluster
or
a
permanent
cluster
marked
for
deletion reaches
=zero, the
cluster is automatically deleted.

If a process 1ssues this service
specifying
an
cluster
with
which
it
1s
not
associated,
completes successfully.

For an example of the S$DACEFC system service and
creation
and
association
of common event flag
3.1.4, "Common Event Flag Clusters.”

event
flag
the
service

a description of
the
clusters, see Section

SYSTEM SERVICE DESCRIPTIONS

'$DALLOC
4.23

The

SDALLOC - DEALLOCATE DEVICE

service

system

Device

Deallocate

previously

deallocates

by the issuing process
use
Exclusive
device.
allocated
relinquished and other, processes can assign or allocate the device.

Macro

Format:

[devnam]

SDALLOC

High-Level

Language

,[acmode]

Format:

LOC
( [devnam]
SYSSDAL

, [acmode])

M’

devnam

device

the

to
address of a character string descriptor pointing

a physical device name or
The string may be either
string.
name
1is an
string
the
1in
If the first character
a logical name.
device
physical
a
considered
is
name
the
(_),
underline character

name. Otherwise, a single level of logical name translation 1is
performed and the equivalence name, if any, is used. The final
name, however, cannot contain a node name unless the name 1s that
-

of the host system.

the
by
allocated
devices
all
If no device name is specified,
access modes equal to or less privileged than that
from
process
specified

are deallocated.

acmode

access mode
performed.
the

Return

caller.

Status:

SS$_NORMAL
e,

on
behalf
of
which
the
deallocation
is
to
Dbe
The access mode is maximized with the access mode of

Service

successfully completed.
|

SS$_ACCVIO

The device name string or string descriptor cannot be read by the
caller.

SS$_DEVASSIGN

SS$_DEVNOTALLOC
Warning.

process

The device is not allocated to the requesting process.

SS$_IVDEVNAM

No device name string was specified or
contains

the

because

The device cannot be deallocated
Warning.
still has channels assigned to it.

invalid characters.

SS$_IVLOGNAM

The device name string has a length of 0
characters.

the

device

has

name

string

than

SYSTEM

SERVICE

DESCRIPTIONS

SDALLOC - DEALLOCATE DEVICE
SS$_NOPRIV
~ The

device

SSS$_NOSUCHDEV
|

Warning.

Privilege

was

The

allocated

specified

from

device

does

privileged

not

exist

access

mode.

the

host

system.

Restrictions:

allocated device can be deallocated
equal
to
or more privileged than the
original allocation was made.

only

from

access

mode

access

from

modes

which

the

Notes:

process

cannot

deallocate

device

any

time.

If,

time of deallocation, the issuing process has one or
channels
assigned
to
the
device,
the
device

the

more I/O
remains

allocated.

The system automatically deallocates all

allocated
If

user

mode

image

devices

attempt
is made to deallocate
a
but no operation is performed.

mailbox,

additional

returned
For

device

example

allocation,

how

see

use

this

Section

service

3.4.9,

that

were

exit.

and

"Device Allocation."

success

notes

- SYSTEM SERVICE

DESCRIPTIONS

$DASSGN
4.24

$DASSGN
- DEASSIGN I/O CHANNEL

The Deassign I/0
acquired
(SASSIGN)

Macro

Channel

for
input/output
system service.

system

service

operations

releases

with

the

Assign

I/0

channel

I/O Channel

Format:

SDASSGN

High-Level

chan

Language

Format:

SYSS$SDASSGN (chan)
chan
number
of

Return

the

I/0O

channel

deassigned.

Status:

SS$_NORMAL
Service

successfully

SS$_IVCHAN
An

invalid

number

channel
0

completed.

number
a

was

number

~available.

specified;

that

1larger

than

the

assigned,

was

1is,

channel

number

channels

SS$_NOPRIV
The

channel
is not
privileged access mode.

assigned

from

Restrictions:

An I/0 channel can be deassigned only from an access
mode
equal
to
or
more
privileged
than
the
access
mode
from which the
original channel assignment was made.

Privilege

specified

Notes:

When a channel is deassigned,
the channel are canceled.
If
channel, the file is closed.

If a mailbox was associated with the device when the
was
assigned, the linkage to the mailbox is cleared
are

any outstanding I/O requests on
file is open on the specified
|

channels

assigned

the

channel
if there

mailbox.

If the I/O channel was assigned for a network operation,
the
network
1link
1is
disconnected.
For
more
1information
on
channel assignment and deassignment for
network
operations,
see the DECnet-VAX User's Guide.
|

SYSTEM SERVICE DESCRIPTIONS
$SDASSGN - DEASSIGN I/O CHANNEL

I/O channels

an
example
information
on
Channels."”

are

of
the
<channel

a
1is

automatically deassigned at image exit.
$DASSGN
system
assignment,
see
.

service
Section

and
3.4.1,

additional

"Assigning
,

For

specified channel is the last channel
assigned
to
that
has
been marked for dismounting, the device
dismounted.

If the
device

SYSTEM

SERVICE

DESCRIPTIONS

\“wv“"!

SDCLAST
4.25
The

~$DCLAST
Declare

AST

DECLARE AST
system

service queues

less
privileged
access
mode.
For
supervisor mode can declare an AST for

Macro

AST

for

the

calling
or

for

example, a routine executing in
either supervisor
or user mode.

Format:

SDCLAST

High-Level

astadr

Language

,[astprm]

, [acmode]

Format:

SYSSDCLAST(astadr , l[astprm] , [acmode])
astadr
address

the

entry mask

the

AST

service

routine.

astprm

value

passed

the

AST

routine

argument,

if any.

acmode
‘access

|
mode for which the AST is to
be
declared.
This
access
mode
1s
maximized
with
the
access
mode
of the caller.
The
resultant mode is the access mode for which the AST is declared.

Return

Status:

SS$_NORMAL
Service

successfully

completed.

SS$_EXQUOTA
The

SSS

process

has

INSFMEM
Insufficient
service

its

system dynamic

and

the

process

Resource Walt Mode

AST

limit

memory

has

disabled

(SSETRWM)

quota.

available

resource

wait

,
|
complete

the

mode

the

w1th

system service.

“

Set

exceeded

Resources

Required/Returned:

The

Declare

AST

memory.

system

service

requires

system

dynamic

This service.uses the process's AST limit guota (ASTLM).

Note:

The
AST

S$DCLAST system service does
service
routine.
If
an

address of

AST "service

For an example of the
conventions
for
AST
System

Trap

(AST)

specified

routlne

glven

$DCLAST
service

Services."

not validate the address
of
the
1illegal address, for example, an
access

v1olatlon occurs

when

the

control.

system
service
and
notes
and
coding
routines, see Section 3.2, "Asynchronous
-

SYSTEM SERVICE DESCRIPTIONS

$DCLCMH
4.26

$DCLCMH - DECLARE CHANGE MODE OR COMPATIBILITY MODE HANDLER

system
Handler (SDCLCMH)
Mode
Declare Change Mode or Compatibility
the address of a routine to receive control when
establishes
service

(1) a Change Mode to User or Change

trap occurs,

(2)

Mode

instruction

Supervisor

a compatibility mode fault occurs.

rFormat:

SDCLCMH

High-Level

addres

Language

,[prvhnd]

,[typel

Format:

SYSSDCLCMH (addres

, [prvhnd]

, [typel])

addres

address of a routine to receive control when a change
mode trap
or
a
compatibility mode fault occurs.
An address of 0 clears a

previously declared handler.
prvhnd

address of a longword to receive

declared
type

handler.

the
|

address

previously

mode
change
If specified as 0 (the default), a
type indicator.
declared for the access mode at which the request is
is
handler
1is
handler
compatibility mode
a
1,
If specified as
issued.
declared.

Return

Status:

SS$_NORMAL

Service successfully completed

.SS$_ACCVIO

The longword to receive the address of the previous
handler cannot be written by the caller.

change
|

mode

Notes:

A change mode
handler
provides
users
with
a
dispatching
mechanism
similar to that used for system service calls.
It
be
to
mode
supervisor
1in
executes
allows a routine that
The change mode handler is declared
user mode.
from
called
1in
is then executing
when the process
from superv1sor mode;
user mode and issues a Change Mode to Supervisor 1nstruct10n,
1in
executes
and
control,
the change mode handler recelves
supervisor mode.

system
Compatibility mode handlers are used by the operating
bypass normal condition handllng procedures when an image
to
executing in compatibility mode incurs a compatibility mode
exceptlon.

\\»....../’

Macro

SYSTEM SERVICE DESCRIPTIONS

$SDCLCMH - DECLARE CHANGE MODE OR COMPATIBILITY MODE HANDLER
3.

When the change mode or compatibility mode handler receives
to the change mode code
the stack pointer points
control,
specified in the change mode instruction or the compatibility
On exit, the handler must remove the
exception type code.
code from the stack, then relinquish control with an REI
-

instruction.

A change mode handler can
supervisor modes.

be
|

declared

only
|

from

user

SYSTEM SERVICE

DESCRIPTIONS

$SDCLEXH
4.27 SDCLEXH
The Declare
routine
to
occurs

(SEXIT)

Macro

EXIT HANDLER

Exit Handler system service
describes
an
exit
handling
receive control when an image'exits.' Image exit normally
the image currently executing in a process returns control

when

the

- DECLARE

operating
system.
Image
exit may also occur when
or Force Exit (SFORCEX) system services are called.

the

Ex1t

The

exit

Format:A

desblk

SDCLEXH

High—Level Language Format:

desblk
-

address

control

block

control
has

the

block describing
format:

the

exit

handler.

| forward link
exit handler address

address to store reason for exit

additional arguments

for exit handler,

if any

The

Return

system fills

in the

first longword.

Status:

SS$_NORMAL
Service

successfully

completed.

SS$_ACCVIO
The
the

first longword
caller.

SS$_NOHANDLER
Warning.
or,

the

No exit handler
address specified

exit

control

control
is 0.

block

cannot

address

was

written by

specified;

N’

SYSSDCLEXH (desblk)

SYSTEM SERVICE DESCRIPTIONS

SDCLEXH - DECLARE EXIT HANDLER

The
Exit handlers are described by exit control blocks.
operating system maintains a separate list of these control
The
blocks for user, supervisor, and executive modes.
SDCLEXH system service adds the description of an exit
handler to the front of one of these lists. The actual list
by the
to which the exit control block is added is determined
access mode of

the caller.

This service can only be called from
executive modes.

user,

supervisor,

and
|

At image exit, the exit handlers declared from user mode are
they are called 1in the reverse order from
called first;
which they were declared.

it must be
Fach exit handler 1is executed only once;
The exit
again.
executed
be
can
it
before
ed
redeclar
handling routine is called as a normal procedure with the
argument 1list specified in the 3rd through nth longwords of
is the address of
the exit control block. The first argument
indicating the
code
status
a longword to receive a system

reason for exit;

the system always fills

before calling the exit handler.
3.

The Cancel Exit Handler (SCANEXH)

"block from the list.

For an example of an exit control

block

this longword

removes an exit control
and

description

the

action the system takes when an image exits, see Section 3.5.6, "Image

sz~

_\-..«/.

Exit."

SYSTEM SERVICE DESCRIPTIONS

SDELLOG
4.28
The

SDELLOG
Delete

DELETE

LOGICAL

NAME

Logical

Name

system

name

service

from

deletes

the

process,

group,
|

equivalence
table.

logical

name

system

and

its

logical

name

Macro Format:
SDELLOG

High-Level

[tblflg]

Language

,[lognam]

, [acmode]

Format:

SYSSDELLOG ([tblflg]

, [lognam]

, [acmode])

tblflg
logical name table number.
A value of 0 (the default)
the
system
table,
1 indicates the group table, and 2
the process table.
|
‘
lognam
address
name

pr1v1leged

character

string.

string

omitted,

delete

indicates
indicates

the

descriptor

pointing
1logical
names

all

specified

table

are

the

logical
process is
deleted.
the

acmode
access

The

mode

associated

with

the

specified

process

logical

access
only the

name

table

entry.

mode is maximized with the access mode of
the caller;
1logical
name
entered
at
the
resulting
access
mode is deleted.
This argument is used only for deleting
names from the process logical name table.

Return

SS$

Status:

NORMAL
Service

successfully

completed.

ACCVIO
The

ldgical

the

caller.

name

string

descriptor

cannot

read

SS$_IVLOGNAM
The

logical

name

strlng

has

length

table

number

was specified.

characters.

name

than

NOLOGNAM
Either (1) the specified logical
name
does
not
exist
1in
the
spec1f1ed
logical
name table, or (2) the specified logical name
exists in the process logical name table but the entry
was
made
from

SS$

logical

has

privileged

access

mode.

NOPRIV
The

the

process

does not have the privilege
specified logical name table.

delete an

entry

from
S——"

SSS

IVLOGTAB
An invalid

SSS

SYSTEM SERVICE DESCRIPTIONS

$DELLOG

- DELETE

LOGICAL NAME

Privilege Restrictions:
The user privileges GRPNAM and
names

from

the

respectively.

group

SYSNAM

and

are

system

required
logical

name

delete
tables,

Resources Required/Returned:
1.

Deletion of a logical name from the
returns

When a

table,

storage

logical

the

name

number

group

system dynamic memory.
is deleted

bytes

from the process

the control

system

table

logical

name

region of the

process's virtual address
space
required
to
maintain
table
entry
become available for other process logical
table entries.
|

Logical names can be deleted
DEASSIGN

from the command

the
name

stream with

the

are qualified
exit.

command.

Names in the process logical name table that
user mode are automatically deleted at image

For an example
of the $DELLOG system service and additional details on
logical name creation and translation, see Section 3.3, "Logical Name
Services."
|

SYSTEM SERVICE DESCRIPTIONS

$SDELMBX
4,29

$DELMBX

The Delete
deletion.

-~ DELETE

Mallbox
system
service
The
actual
deletion of

logical name a551gnment
to the mailbox.

Macro

MAILBOX

occur

when

marks
a
permanent
mailbox
for
the mailbox and of its associated

I/0

channels

are

asSigned'

Format:

SDELMBX

chan

High-Level Language Format:
SYSSDELMBX (chan)

number

Return

e
channel

the

|
assigned

the

o
mailbox.

chan

Status:

SS$_NORMAL
Service

successfully

completed

SS$_DEVNOTMBX
The

SS$

specified

channel

not

IVCHAN

" An invalid channel number
number

assigned

was

number

mailbox.

specified,
larger

that

than

available.

the

is,

channel

number

channels

SS$_NOPRIV
The specified

channel

does

the

not

access

have

mode of

from which

Privilege

the

not

privilege
caller

channel

was

assigned
to

delete

less

to
a

device,

permanent

privileged

than

the

process

mailbox,
the

the

access mode

assigned.

Restrictions:

The user
mailbox.

PRMMBX

A mailbox can be deleted'only from an access mode equal to or
more
privileged
than
channel was assigned.

the

required

access

mode

delete

from

which

permanent

the mailbox

\w/’

privilege

4-64

SYSTEM SERVICE DESCRIPTIONS
$DELMBX - DELETE MAILBOX

Notes:

Temporary mailboxes
reference

count goes

are
to

automatically

deleted

when

their

zero.

The $DELMBX system service does not deassign the channel
er the
must deassign
The call
if any.
assigned by the caller,
system
($DASSGN)
channel with the Deassign I/0 Channel
service.

For information on the creation and

3.4.13,

"Mailboxes."

use

mailboxes,

‘'see 'Section

SYSTEM SERVICE DESCRIPTIONS

$DELPRC
4.30

S$DELPRC

- DELETE

The Delete Process
another process.

Macro

PROCESS

system

service

allows

process

delete

itself or

Format:

SDELPRC

High-Level

[pidadr]

Language

, [prcnam]

Format:

SYSSDELPRC ([pidadr]

, [prcnam])

pidadr
address of a longword containing
the process to be deleted.
prcnam

the

process

identification

address of
a character string descriptor pointing to the
process
name
string.
The
process
name is implicitly qualified by the
group number of the process issuing the delete.

If neither a process identification nor a process name
is
specified,
the caller is deleted and control is not returned.
For details on how
the service interprets the PIDADR and PRCNAM arguments, see Table 3-3.
Table 3-3 is in Section 3.5, "Process Control Services."

Return

Status:

SS$_NORMAL
Service

successfully

SS$_ ACCVIO
The process
the process

completed

name string or
identification

string descriptor cannot be
read,
cannot be written, by the caller.

system dynamic memory is available to
complete
service
and the process has disabled resource wait mode with
Set Resource Wait Mode (S$SSETRWM) system service.

the
the

SS$_INSFMEM
Insufficient

SS$_NONEXPR
Warning.
process

|
|
»
The specified process does not
identification was specified.

exist,

invalid

SS$_NOPRIV
The

process does

process.

not

have

the

privilege

delete

the

specified

SYSTEM SERVICE DESCRIPTIONS
$SDELPRC

- DELETE PROCESS

Privilege Restrictions:
User privileges are required to delete:

Other processes in the same group (GROUP privilege)
Any process in the system

(WORLD privilege)

Resources Required/Returned:
1.

The Delete Process system

service

requires

system
|

memory.

dynamic

subprocesses

are

When a subprocess is deleted, a terminaticn message

sent

message still exists and the creating process has

access

Deductible

resource

quotas

granted

returned to the creator when the subprocesses are deleted.

1its

provided

creator,

that

the mailbox to receive the

is sent before the
The termination message
"the mailbox.
thus, the <creator may receive
final rundown is initiated;
the message before the process deletion is complete.

a
Due to the complexity of the required rundown operations,
significant time interval occurs between a delete request and
Process
The Delete
the actual disappearance of the process.
immediately after initiating the
returns
however,
service,
issued
If subsequent delete requests are
rundown operation.
return
requests
the
deleted,
being
currently
process
a
for
immediately with a return status code indicating successful
|

completion.

For a cOmpleté list of the actions performed by
deletes

process,

"Process Deletion.”

see

Sections

3.5.6,

the

"Image

system .when

Exit"

and 3.5.7,

SYSTEM SERVICE DESCRIPTIONS

SDELTVA
4.31
The

S$DELTVA - DELETE -VIRTUAL ADDRESS SPACE
Delete

Virtual

addresses

from

Address Space

process's

system

virtual

service

address

completion of the service, the deleted pages
references
to them cause access violations.

Macro

deletes

space.

are

range

Upon

successful

inaccessible;

any

Format:

SDELTVA

1inadr ,[retadr]

,[acmode]

High-Level Language Format:
SYSSDELTVA (inadr
inadr

address of

, [retadr]

,[acmode])
-

2-longword

array containing

the

starting and

ending

virtual
addresses
of
the pages
to be deleted. If the starting
and ending virtual addresses are the
same,
a
single
page
is
deleted.
Only
the
wvirtual
page number portion
of the virtual
addresses 1s used;
the low-order 9 bits are ignored.
:
retadr
address

virtual

2-longword

addresses

acmode

array

the

pages

actually

the

specified

caller.

‘whether

Return

the

access

The

mode

resultant

caller

can

the starting

and

ending

deleted.

access mode on behalf of which
The

receive

the

service

is maximized

access

with

mode is

actually delete

the

performed.

access

used

specified

mode

)

determine

pages.

Status:

SS$_NORMAL
Service

successfully

SS$_ACCVIO

completed.

The input address array cannot be read,
array cannot be written, by the caller.

SS$- NOPRIV
A page

the

specifiéd

the

return

address

;

|
range

the

system

address

space.

by
an
caller.

access

mode

SS$_PAGOWNVIO
A page in the specified range is owned
privileged than the access mode of the

Privilege
Pages

Restrictions:
can

privileged

only

than

deleted

the

from

access mode

access

the

modes

owner

equal

the

pages.

) \./ ’

SYSTEM SERVICE DESCRIPTIONS

SDELTVA - DELETE VIRTUAL ADDRESS

SPACE

Notes:

The SDELTVA system service
deletes
pages
starting
at
the
address
contained
in the second longword of the INADR array
and ending at the address in the first
1longword.
Thus,
if
the same address array is used for the Create Virtual Address
Space (SCRETVA) as for the S$DELTVA system service, the
pages
are
deleted
1in
the
reverse
order
from
which they were
created.

If any of the pages in the specified range have already
been
deleted
or
do
not
exist,
the service continues as 1f the
pages

3‘

were

successfully

deleted.

If an error occurs while deleting pages, the return array, if
requested, indicates the pages that were successfully deleted
before the error occurred.
If no
pages
are
deleted,
both

‘longwords in the return address array contain a -1.

example
of
the
S$DELTVA
system
service
and
additional
an
information
on
page
creation
and
deletion,
see
Section
3.8.2,
"Increasing and Decreasing Virtual Address Space."
A

For

SYSTEM SERVICE DESCRIPTIONS

$DGBLSC
4.32

$DGBLSC - DELETE GLOBAL SECTION

The Delete Global Section system
global
section
for
deletion.

section
section

Macro

service marks
The
actual

takes place when all processes
have deleted the mapped pages.

that

an
existing
deletion
of

have

mapped
!

permanent
the global

the

global

The

only

Format:

$SDGBLSC

High-Level

[flags]

Language

,gsdnam

,[ident]

Format:

SYSSDGBLSC([flags]

,gsdnam

,[ident])

flags
mask

1ndicating

global

section

characteristics.

significant
bit
wused for the deletion of global sections is the
group/system flag.
If this
argument
1is
spec1f1ed
as
0
(the
default),
it indicates that the global section is a group global
section;
if specified as SEC$M _SYSGBL,
it
indicates
a
system
global section.
|
gsdnam
address

of a
l15-character

group

character

text

global sections,

qualified

the

string

name

group

of
the

the

descriptor

global

number

the

ident
address
section

of
to

a quadword
delete and

pointing to
the
1section to be deleted.

section

name

caller.

The

first longword
can

global

The ver51oh number

two fields:
a minor identification in the low-order
a major identification in the high-order 8 bits.

matching
they

implicitly

indicating the version number of the
the matching criteria to be applied.

The version number is in the second longword.
contains
bits and

For

criteria.
be

specifies,
The

specified,

and

the

valid

values,

their

meanings

1low-order
symbolic
are

bits,

the

names by which
listed below:

Value/Name

Match

Criteria

0
1

SECSK_MATALL
SECSK_MATEQU

Match
Match
match

all versions of the section
only if major and minor identifications

SECSK_MATLEQ
|

|
Match if the major identifications are
equal
~and the minor identification of the mapper is
less

than
or
identification of

equal

the

global

If no address is specified,
or is specified
the version number and match control fields

the

minor

section.

as 0
(the
default to

default),
O.

SYSTEM SERVICE

DESCRIPTIONS

SDGBLSC - DELETE GLOBAL SECTION
Return

Status:

SS$_NORMAL
Service

successfully

SS$_ACCVIO
The global

section
identification field

completed

name
or
cannot be

name
descriptor
or
read by the caller.

.
section

the
B

SSS$_IVLOGNAM
The global section
characters.

SS$_IVSECFLG
An invalid

been
SS$

/I'
N

has

length

has

than

flag has been specified.
Either a
or one requiring a user privilege.

reserved

flag

has

IVSECIDCTL

The
SS$

set,

name

section

identification match

NOPRIV
The caller does not
section,
or does
section.

SS$_NOSUCHSEC

Warning.

The

have
not

control

field

1is

1nva11d

the privilege to delete a
have read/write access to

|
specified global

section does

system
global
a group global
|

not exist.

Privilege Restrictions:
The user privileges SYSGBL and
system and permanent global

PRMGBL

sections,

are

required

respectively.

delete

Notes:
1.

After a global section has
been marked
for
process
that
attempts to map it receives the
status code SS$ NOSUCHSEC.

For

Temporary global sections are automatically deleted
count of processes using the section goes to 0.

when

the

This service does
not
unmap
a
section
from
a
process's
virtual address space.
When a process no longer requires use
of a section, it can unmap the section by calling the
Delete
Virtual
Address Space (SDELTVA) system service to delete the
pages to which the section is mapped.

information on

3.8.6,

deletion,
any
warning return

"Sections."

the

creation

and
‘

use

sections,

see

Section

SYSTEM SERVICE DESCRIPTIONS

$DLCEFC
4.33

$DLCEFC - DELETE COMMON EVENT FLAG CLUSTER

The Delete Common Event Flag Cluster system service marks a
permanent
common
event
flag
cluster
for
deletion.
The cluster is actually
deleted when no more processes are associated with it.

Macro Format:
SDLCEFC

name

High-Level Language Format:
SYSSDLCEFC (name)
name

address of a character string descriptor pointing to
the
1to
15-character
text
name
of the cluster.
The name is implicitly

qualified

Return

by the group number

the

caller.

Status:

SS$_NORMAL
Service

successfully

SS$_IVLOGNAM

The

cluster

name

completed.

string has

SS$_NOPRIV

The process does not have

Privilege

length of

characters.

common

event

flag

cluster.

the privilege

0,
|

has

delete

than

permanent

Restrictions:

The user privilege PRMCEB is required to delete permanent
event

flag

clusters.

common

Notes:

The SDLCEFC system
service
does
not
perform
an
implicit
disassociate request for the caller.
A process disassociates
with a cluster by calling the Disassociate Common Event
Flag
Cluster
($SDACEFC)= system
service.
The system performs an
implicit disassociate for the cluster at image exit.

If the cluster has already been deleted or
the $DLCEFC service

does

not

returns the status code SS$ NORMAL.

For an example of creating and using a common event flag
Section 3.1.4, "Common Event Flag Clusters.”

exist,

cluster,

see

SYSTEM SERVICE DESCRIPTIONS

SEXIT
4.34 S$EXIT - EXIT
The Exit system service is used by the operating
system to
1initiate
image rundown when the current image in a process completes execution.
Control normally returns to the command interpreter.
,

Macro

Format:

SEXIT

[code]

High-Level Language Format:
SYSSEXIT ([code])
code
\\’//

longword
value
to
be
saved 1in
the
process
header
as
the
completion
status
of
the current image.
If not specified in a
macro call,
a value of 1 1s passed as the completion code.
This
value
can
be tested
at the command level to provide conditional
command execution.

Return

Status:

this service because
rather,
an exit to
-

control
1is
the command

No status codes are returned by
not
returned
to
the
caller;
interpreter is performed.
|

Note:

For a complete list of the actions taken by the system
exit,

see

Section

3.5.6,

"Image

Exit."

1image

SYSTEM SERVICE DESCRIPTIONS

$SEXPREG
4.35

S$EXPREG - EXPAND PROGRAM/CONTROL REGION

The Expand Program/Control Region
number

region

for

new

the

virtual

pages

execution of

the

system service

process's

current

program

image.

adds

region

Expansion

the current end of that region's virtual address space.

Macro

control
occurs
at

Format:

"SEXPREG

High-Level

pagcnt

Language

,[retadr]

,[acmode]

,[region]

Format:

SYSSEXPREG (pagcnt

, [retadr]

,[acmode]

,[region])

pagcnt

number

control

retadr
-

specified

pages

add

the

current

end

the

'
program

region.

address

of
a 2-longword

virtual

addresses

acmode

access mode

the

array
pages

and protection

for

receive

actually

the

starting

and

ending

added.

new

pages.

The

specified

access mode 1is maximized with the access mode of the caller.
The
protection of the pages is read/write for
the
specified
access
mode and more privileged access modes.
»

region
|
E
region indicator.
A value of 0 (the default) indicates that
the
program
region
(PO
region)
1s
to be expanded.
A value of 1
indicates that the control region (Pl region) is to be expanded.

Status:

SS$_NORMAL
Service

successfully

SS$_ACCVIO
|
The return

address

SS$_EXQUOTA
The process

completed.

|
array

exceeded

1its

cannot

written

paging

file

the caller.

quota.

SS$_ILLPAGCNT

The

specified

page

count

was

less

than

SS$_INSFWSL
|
The
process's
working
set
1l1limit
1s
not
1large
accommodate the increased virtual address space.

SS$_VASFULL
The

process's

available

virtual

address

space

the process page table

for

1is

the

full;

enough

no
space
requested regions.

1is
N

Return

SYSTEM SERVICE DESCRIPTIONS

SEXPREG - EXPAND PROGRAM/CONTROL REGION

Resources Required/RetUrned:

The process's paging file quota (PGFLQUOTA) and working set limit
guota

(WSQUOTA)

size of

must be sufficient to accommodate the increased

the virtual

address space.

Notes:

The new pages, which
process,

were

inaccessible

previously

are created as demand-zeroO pages.

the

Because the bottom of the user stack is normally 1located at
the end of the control region, expanding the control region
is equivalent to expanding the user stack. " The effect is to
increase the available stack space by the specified number of
pages.

The starting address returned is always the first available
therefore, the ending address
page in the designated region;
when the control region
address
starting
the
than
is smaller
is expanded and is larger than the starting address when the
program region is expanded.

the return address
If an error occurs while adding pages,
the pages that were
indicates
if requested,
array,
If no pages
‘successfully added before the error occurred.
both longwords of the return address array
were added,
|
i
contain a -1.
The information returned in the 1location addressed by the
RETADR argument, if specified, can be used as the input range
to the Delete Virtual Address Space (SDELTVA) system service.
Pages can also be deleted with the Contract Program/Control
Region

For

example

information

(SCNTREG)

the

creating

em
. service.
syst

S$EXPREG system

and

deleting

service

pages,

"Increasing and Decreasing Virtual Address Space."

see

and

additional

Section

3.8.2,

SYSTEM SERVICE DESCRIPTIONS

$FAO
4.36

$FAO - FORMATTED ASCII OUTPUT

The Formatted ASCII

ASCII

characters

string.

can

Output

Convert

service

returns

the

used

to:

Insert variable

system

and

binary

character

values

converts

converted

string

into

the

data

ASCII

binary

into

output

and

Sections 4.36.2 through 4.36.5 provide
syntactlcal
valid FAO directives and parameters, and examples of

into

output

string

representations

decimal, hexadecimal, or octal equlvalents
results into an output string.

Macro

values

characters

their

substitute

the

notes,
lists
using FAO.

Format:

SFAO
- High-Level

ctrstr ,[outlen]
Language

SYSSFAO (ctstr

,outbuf ,[pl]

,[p2]

..., [pn]

Format:
, [outlen]

,outbuf

,[pl]

,[p2]

..., [pPn])

ctrstr

string.

The

output

string

character

control

and FAO

string

descriptor

consists
directives.

outlen

address

string

word

pointing

string

recelve

|
the

returned.

the

fixed

actual

1length

control

text

the

|
the

address

output

outbuf

address

buffer.
buffer.

character

The

fully

string descriptor p01nt1ng to
the
formatted output string is returned

output

this

pl - pn

directive parameters contained in longwords.
Depending
on
the
directive,
a
parameter
may be a value that is to be converted,
the address of the string that is to be inserted, or a length
or
argument

Return

count.

corresponding

Each

the

control

string

may

require

The
formatted
output
has been truncated.

string

parameters.

Service

successfully
overflowed the output

SSb

Status:

SS$_BUFFEROVF

SSb

directive

parameter

NORMAL
Service

successfully

completed.
buffer

and

completed.

BADPARAM
An

invalid

directive

was

specified

the

FAO

control

strlng.

SYSTEM SERVICE DESCRIPTIONS
$SFAO - FORMATTED ASCII OUTPUT
Notes:

for

all

ifa symbolic address is specified, it must be preceded
a pound sign (#) character or loaded into a register.

with

The $FAO_S macro

(Pl

parameters

form

through

uses

on the $FAO macro
A maximum of 20.parameters‘¢an be specified
are required, use
ers
paramet
20
than
more
If
instruction.
|

the $FAOL macro.

instruction

PUSHL

Pn) coded on the macro instruction;

the

The $FAO system service executes at the access mode

caller and does not check whether address arguments are
access
an
Therefore,
accessible before 1t executes.

if an input field
violation causes an exception condition
Note
written.
be
cannot
field
output
an
or
read
be
cannot
that an access violation can occur if an invalid length 1is
specified for an argument, or if an FAO parameter 1s coded
|

1“

.\\et y

incorrectly.

SFAOL - Formatted ASCII Output with List Parameter

4.36.1

an
The Formatted ASCII Output with List Parameter macro provides
alternate way to specify input parameters for a call to the $FAO
system service.

Format:

Macro

,outbuf ,prmlst

SFAOL ctrstr ,[outlen]
High-Level Language Format:

SYSSFAOL (ctrstr ,[outlen]

,outbuf ,prmlst)

ctrstr

address of a character string descriptor pointing to the control
The control string consists of the fixed text of the
string.

outlen

address of a word to receive the

actual

length

outbuf

string returned.

to
address of a character string descriptor pointing

buffer.

The

prmlst

fully

output string and conversion directives.

the

output

the

output

formatted output string is returned in this
|

address of the parameter list of
through Pn.

longwords

be used
|

Pl
-

that already exists in
The parameter list may be a data structure
to be extracted.
es
are
a program and from which certain valu

Return Status:

Same as for S$SFAO system service.

SYSTEM

$SFAO

4.36.2

SERVICE

DESCRIPTIONS

FORMATTED ASCII

OUTPUT

FAO Directives

FAO

directive

has

the

format:

)

!DD
!

(exclamation

indicates

are

2-character

perform.

parameters

must

Optionally,

Each

the

following

character

FAO

directive.

indicating

the

action

may

SFAO.

uppercase

require

All

one

directive

that

FAO

codes

input

for

FAO

letters.

a directivevmay include:

An output field length

repeat

code

the

as an

directive

call

specified

that

interpreted

repeat

count

coded

follows:

,":

mark)

Characters

In (DD)

where
the

decimal

specified

value

number

instructing

FAO

parameters.

repeat

the directive

for

An output field,length is specified as follows:
!1engthDD
where

"length" is
resulting
from a
output string.

A directive may
shown below:

a decimal
directive

contain

value

into

both

instructing

field

repeat

FAO to
"length"

count and

place

the
characters

output

the

1length,

!n(lengthDD)

counts

using

must

contain

the

for

the

one

length

the specified

4.36.3
An

output

(number

FAO

character

‘required

repeat

count,

the

field

The

code

the

length

wvalue.

specified with a

required;

each

Parameter

any

only

"X21)

variables,

value.

output

repeat.‘count,
string

will

have

and
be

numeric

If
parameter passed to
FAO
specified for an output field

may

specified

absolute

contain

length

String

string

(ASCII

must

parameter

may

place

count.

length.

directives.

lengths

parameter

Control

control

field

sign)

a variable output

only

- FAO

and

specified

length,

length

Processing
and

restriction

the

control

may

1is

contain

the

string.

in the output string, the directiv1!
e

any

wuse

number

literal

the

provides an escape.

\\___/’

Repeat

SYSTEM SERVICE DESCRIPTIONS
$FAO

FORMATTED ASCII

When FAO processes a control string,

OUTPUT

each character that is

of a directive is written into the output buffer.

not

part

When a directive 1is

encountered, it is validated;
if it is not
a
wvalid
directive,
FAO
terminates
and
returns
an
error
status code.
If the directive is
valid, and if it requires one or more parameters, the next consecutive
parameters specified are analyzed and processed.
FAO reads parameters from the argument list;
it does
not
check
the
number of
arguments
it
has
been
passed.
If there are not enough
parameters coded in the argument list, FAO will continue reading
past
the end of the list.
It is your responsibility, when coding a call to
SFAO, to ensure that
there
are
enough
parameters
to
satisfy the
requirements of all the directives
in the control string.
|

4.36.4

Summary of FAO Directives and Output Field Léngth Defaults

Table 4-2

required

summarizes the FAO directives,

by each directive.

and

1lists

the

parameter
(s)

Table 4-3 summarizes how FAO determines

the length of each output field in the control string as it
processes
directives
and
substitutes
character
strings in the control string
while formatting the output buffer.
-

.,iV3

- : PP

;

Examples
in Section 4.36.5 describe in more detail how to use FAO.

SYSTEM SERVICE DESCRIPTIONS
SFAO
- FORMATTED ASCII OUTPUT
Table 4-2

Summary of FAO Directives

Directive

Function

Paraméter(s)l'

Character String Substitution
'AC

Inserts
-

counted

ASCII string

‘Address
the

contain

IAD

Inserts an ASCII

IAF

Inserts
Replaces

ASCII
!AS

string

an ASCII
all

string;

nonprintable

codes with periods

Inserts

an ASCII

first

the

string;

byte

the

must

length

Length of string

Address

Length of

Address

string

(.)

string

Address

of quadword
character string
descriptor pointing
to the string
-

Numeric ConverSion (zero-filled)
Value
ASCII

Converts

IOW

Converts

byte to octal
word to octal
a longword to octal

1 XB

Converts

I XW
XL

Converts
Converts

a word to hexadecimal
a longword to hexadecimal

1ZB
1ZW

Converts
Converts

an
an

172L

Converts an unsigned decimal

10B

For

byte

hexadecimal

to be converted
representation

byte

conversion,

word

FAO

uses

only

the low-order byte or
word of the longword
parameter

Numeric

Conversion

unsigned
unsigned

decimal
decimal

byte

word
longword

(blank-filled)

!UB
1UW
UL

Converts an unsigned decimal
Converts an unsigned decimal
Converts an unsigned decimal

byte
word
longword

!SB
I SW
I1SL

Converts a signed decimal byte
Converts a signed decimal word
Converts a signed decimal longword

Value
ASCII

to be converted
representation

For byte or
conversion,
the

word

word
FAO uses

low-order

the

byte

only

or.

lonagword

parameter

If a variable repeat count and/or a variable output field length is
specified
with a
directive,
parameters
indicating
the
count and/or length must precede other parameters
required by the directive.

SYSTEM SERVICE DESCRIPTIONS
SFAO

FORMATTED ASCII

OUTPUT

Table 4-2 (Cont.)
Summary
of FAO Directives

Directive

Function

Parameter(s)l

Output String Formatting

Inserts new:line (CR/LF)

None

Inserts a tab
Inserts

form

feed

Inserts an exclamation mark

1%S

13T

Inserts the letter
S if most recently
converted numeric value is not 1

Inserts the system time

Address of a guadword time

value to be converted to
ASCII. If 0 is specified,
the current system time is
used.

Inserts the system date and time

1%D
In<
1>

Defines output field width of n
characters. All data and
directives within delimiters are leftjustified and blank-filled within
the

output

Reuses last parameter

Skips the next parameter

in the list

None

in the list

If
a variable repeat count and/or a variable output field length is

required

\, R -

times

directive,

string n

Interpretation

Parameter

field

in the
Repeats the specified character

In*c

None

parameters

indicating

the directive.

the

specified

with

count and/or length must precede other parameters

SYSTEM SERVICE DESCRIPTIONS

SFAO

FORMATTED ASCII
Table

OUTPUT

4-3

How FAO Determines Output Field Lengths and Fill

‘Default Length

Action

When

Explicit

Output

Field

Length

Output Field

Longer

than Default

Byte

(zero-filled)

ASCII

Word
Longword

4
8

(zero-filled)
(zero-filled)

justified
filled to

Conversion
/Substitution Type
Hexadecimal

’

Octal
Byte
Word
Longword

,
(zero-filled)

]
right-

and blankthe specified

6 (zero-filled)
11 (zero-filled)

filled to the default
output field length then
blank-filled to specified

As many characters
as necessary

ASCII result is rightjustified and blank-filled

ASCII

result

truncated
left

the

specified

length

As many characters
as necessary

- Length

of
character

input
string

Signed and unsigned
decimal output fields
are

with

completely

filled

asterisks(¥*)

ASCII result is rightjustified and zero-filled
to

ASCII String
Substitution

than Default

Hexadecimal or octal
output is always zero-

Unsigned Zero-filled
Decimal

Shorter

length

Unsigned

Action When Explicit
Output Field Length is

S
result

length
Signed or
Decimal

Characters

the

specified

length

ASCII string is leftjustified and blank-filled
to the specified length

ASCII string
truncated on
right

is
the

SYSTEM SERVICE DESCRIPTIONS

SFAO

4,36.5

FORMATTED ASCII

OUTPUT

FAO Examples

following

Each of the examples on the

an FAO

control

repeat

count,

output

‘repeat

count,

output

variable

repeat

shows

pages

string with several directives, parameters defined as input for the
The
strings.
directives, and the calls to SFAO to format the output
numbered examples

1llustrate.

!AC,

SFAO macro,

!!, and

~field

length

!AD, and

!AS,

SFAO macro,

!/ directives

directives,

!AS

SFAO macro, !UL, !XL, !SL directives

4.,

S$FAOL macro,

!UL, !XL, !SL directives

SFAOL macro,

!UB,

SFAO macro, !XW, VZW, -

SFAOL macro,

field

!SB directives

!XB,

length

directives,

!%S,

directives,

!AS,

!UB,

(repeat character),

count

SFAO macro,

!n*c

SFAO macro,

!%D and !%T

SFAO macro,

!< and

10.

(with variable

(with

repeat count)

(define

!%D directives

output
field

field
width),

1lengths),

In*

and

!UL

!AC,

directives

"Results”.
the heading
wunder
Each example is accompanied by notes,
show the output string created by the call to $FAO and
These notes
The
describe in more detail some considerations for using directives.
where
places
all
in
(A)
characters
delta
show
strings
output
sample

'FAO output contains multiple blanks.

Each of the examples refers to the following output fields
fields are not shown in the data areas for each example):
FAODESC: .LONG

. LONG
FAOBUF: .BLKB
FAOLEN: .BLKW

. BLKW

FAOBUF
80
1

‘

(these
»

OUTPUT BUFFER DESCRIPTOR

; ADDRESS OF BUFFER
; 80-CHARACTER BUFFER
'RECEIVE LENGTH OF.OUTPUT
; RESERVE WORD FOR $QIO

by a
followed
be
These examples assume that each call to $FAO will
call to $QIO or to SOUTPUT to write the output string produced by FAO.
the
that
require
$OUTPUT macro)
the
The $QI0 system service (and
an extra word 1is
therefore,
length be specified as a 1longword;
the
of
length
the
receive
to
provided following the word defined
output string returned by S$FAO.

SYSTEM SERVICE DESCRIPTIONS

SFAO

CONTROL.

WINKENS

STRING

AND

DESCRIFTOR

ASCIC

BLINKEN?

INFUT FARAMETERS
FOR

EXAMFLE

<1/8ATLORS:

1Al

'A%

/NOI/

NODLENS

.« LONG

NODL.EN-NOI

FCONTROL

STRING

?COUNTEH AGCITIT STRING

<RLLINKEN:>

+ALKCTT

1AC

/WINKEN/

DESCRIFTOR

NOI:

CALL

OUTPUT

SLEEFSTRI

FORMATTED ASCII

‘\!_fl"‘“

Example

CHARACTER
yASCTIT

STRING

DESCRIFTOR

STRING

s LENGTH

ASCII

STHRING

$FAO

$FAQ.E CTRSTR=SLEEFSTRy OUTLEN=FAQLENy QUTRUF=FAQDESC y -

F* L=

W INKEN F2=$RLINKEN
s F3=NODLLEN » F4=4NOD

Results:

SFAO

writes

the

output

string

CORZCLFESATLORSD WINKEN

The
as

!/ directive
<CR><LF>)

The

IAC
that

the

address

requires

(P2

carriage

the

sign

its

return/line

counted

required

used

feed

the

character

ASCII

string

specify the

$FAO

macro

requires

(Pl

parameter,

pushes

the
'

address

a character

requires

(P3

(shown

the

contents.

argument) .

!AD directive
be substituted

NOD

address

(#)

instruction

than

directive

descriptor

output.

PUSHL

rather

The !AS

‘The

terminal

number

FAOBUF:

BLINKEN

provides

directive

argument) ;

for

into

two parameters:
the length of
the
argument), and its address (P4 argument)
.

string

LExample 2i

CONTROL STRING AND INFUT FARAMETERS FOR EXAMFLE 2

NAMESTR ¢ DESCRIPTUR ZUNABLE TO LOCATE 13(8a8)1
15>
JONESS

DESCRIFTOR <JONES:

s CONTROL. STRING

s NAME

DESCRIFTOR

HARRIS:

DESCRIFPTOR

< HARRIS:

¥y NAME

DESCRIFTOR

WILSON:

DESCRIFTOR

<WILSON:

s NAME.

DESCRIFTOR

CALL

$FAOQ

$FAD.LS

CTRETR
» OUTLEN=FAQLEN»
=NAMES
OUTRUF =FAQNESC
TR
s~

F1=dJONES
s P2=#HARRIS y F3=%WIL.SON
Results:

'$FAO writes

the output

string

into FAOBUF:

UNABLE
TO LOCATE JONESAAAHARRISAAMWILSONAA!
The

!3(8AS)

(addresses

directive

of
left-justifies

field
The

length

contains

character

each string
specified).

directive

supplies

string

into

a
repeat
count:
3
parameters
descriptors)
are
required.
SFAO
field of 8
<characters
(the
output

literal

the output.

SYSTEM SERVICE DESCRIPTIONS

$SFAO - FORMATTED ASCII OUTPUT

that
If the directive were specified without an output field length,fields
is, 1f the directive had been,specified as 13(AS), the 3 output

would be concatenated, as follows:

UNABLE TO LOCATE JONESHARRISWILSON!

{Examples 3, 4, and EJ
5 CONTROL STRINGS AND INFUT PARAMETERS FOR EXAMFLES 3 4 AND 5
SCONTROL STRING (LONGWORD CONVERSION)
LONGSTR?
DESCRIFTOR SUALUES UL (DECY

BYTESTR?S
VALLS

VALD?:
YAL3:

XL (HEX)

181 (STGNETD=

sCONTROL STRING (RYTE CONVERSTION)

NESCRIFTOR <VALUES 'UE (DEC) !XB (HEX) !8E (SIGNEID:

JONG

LLONG
JLONG

5 CALL TO $FA0

SDNECIMAL 200

200

300
~400

s IECIMAL 300
SNEGATIVE 400

(EXAMFLE 3D

$F A0S CTRQTRWLUNGSTRvUUTBUFxFHUDESCyUUTLENflFfiflLENVW_
Fi=VAL1yFR2=UAL2yF3=VAL3

Results:

SFAO writes the output string:

VALUES 200 (DEC)Y 0000012C (HEX) —~400 (SIGNEID

The longword value 200 is converted

decimal,

300 1is

wvalue

the

converted to hexadecimal, and the value -400 1is converted to insigned
the
decimal. The ASCII results of each conversion are placed
-

appropriate position in the output string.

ters and 1s
Note that the hexadecimal output string has 8 tcharac
length for
output
defaul
the
1is
This
zero-filled to the left.
|
|

hexadecimal longwords.

CALL TO $FAD

(EXAMFLE 4)

$FAOL_S CTRETR=LONGSTRy OUTRUF=FAODESCy OUTLEN=FADLENy~
FRMLST=VAL1

Results:

SFAO writes the output string:

VALUES 200 (DEC)Y 0000012C (HEX) -400 (SIGNED)

The results are the same

the

results

example

However,

the call, the
instead of the S$FAO macro, and coding each parameter on and
FAO reads
s,
longword
tive
consecu
of
list
the
to
$SFAOL macro points
from the list.

SYSTEM SERVICE DESCRIPTIONS

'$FAO
y

CALL

$FA0

FORMATTED ASCII

OUTPUT

(EXAMFLE
3)

$FAQL..S

CTRSTR=RYTESTRs OUTLEN=FAOLENy QUTEUF=FAQDESC s~

FRMLST=VAL1
Results:

SFAO

writes

the

output

string:

UALUESEOO (DECY 2C (HEX)

112 (SIGNEIN

The
the

input parameters are the same as those for
Example
4.
However,
control
string
(BYTESTR)
specifies
that byte values are to be
converted.
FAO uses the low-order byte
of
each
longword
parameter
passed
to
it.
The high-order
3 bytes are not evaluated.
Compare
these results with the results of Example 4.

Example 6]

i CONTROL STRING FOR EXAMFLE
6
MULTSTR?

DESCRIFTOR <HEX$

3 CALL TO FAO

!2(6XW)

$FAD.S

ZERO-DECE

12(-)12(7ZW)%

CTRSTR=MULTSTRyOUTLEN=FAOLENs QUTRUF=FAODESC » ~

F1=410000F2=49999

Results:

- FAO

writes

Each

output

ZERO-DNECE

!2(6XW)

the

directives

lengths.

low-order

length

First,

word

specified

is
of hexadecimal

width
the resulting ASCII
The !repeat
over

string:

HEXIAAARZ7T1OAANZZOF

output

the

FAO

the
2

00100000009999

and

!2(7ZW)

performs

contain

the

!XW
parameters

numeric

characters

longer
conversion, so

word
strings.

than

counts
twice,

passed.

The

the

spaces

two

parameters;

then,

uses

the

same

there

are

blanks

between

the

output

two

the

and

using
output

default output field
are
placed
between

directive causes FAO to back up over
the
parameter
count
1is specified with the directive, so that FAO

12ZW
directive.
The
1ZW
directive
causes
zero-filled to the specified length, in this

Thus,

repeat

directive

1list.
A
skips back

parameters

output

example,
fields.

for

string

the

characters.

SYSTEM SERVICE DESCRIPTIONS
$SFAO

FORMATTED

ASCII

OUTPUT

Example 7J
3

CONTROL

STRING AND

INFUT

FARAMETERS FOR

ARGSTR?! DESCRIFTOR «!1AS RECEIVED
LISTA:

LISTR:

ORION

« LONG

+ LONG
+ L.LONG
«LLONG

10
123
210

LONG

LYRA

+ LONG
+ LLONG

1
255

1UR ARGIZS!

L CALIRD

y ALIIDRES OF NAME STRING
-

y MUMRER

y ARGUMENT
y ARGUMENT
s ARGUMENT

ARGS

y NUMBER OF ARGS
s ARGUMENT 1

DESCRIFTOR «ORION:

yFROCESS NAME

I.YRA:

DESCRIFTOR

y FROCESS

CALLS
TO

LLIST

sADDRESS OF NAME STRING

ORION:

1
2
3

<LYRAX

IN LIST

NAME

FAO

S ————

¢'j‘

JLONG

EXAMFLE

$FAQL..S

CTRETR=ARGSTR
s OUTLEN=FAOLENy OUTBUF=FAQDESC» -

FRMLST=L.ISTA

$FAOLWS'CTRSTRWQRGSTRrUUTLEN@FQULENrUUTBUFxFfiODESCyM

FRMLST=L.ISTH

Results;

Following the first call to SFAOL shown above, FAO writes

the

output

string:
ORION

Following

RECEIVED

the

ARGSIAAALO

second call,

123

210

FAO writes

the output

string:

LYRA RECEIVED 1 ARGIAADSS
In

each

the

examples,

the

PRMLST

argument

points

different

parameter
list;
each
1list
contains,
in
the
first longword, the
address of a character string descriptor. The second longword
begins
an
argument list, with the number of arguments remaining in the list.
The control string uses this second longword twice:
first
to
output
the
value
contained
1in the longword, and then to provide the repeat
count to output the number of arguments in the list (the !directive
indicates that FAO should reuse the parameter).
|

The !%S directive provides a conditional plural.
When the last
converted
has
a
value
not
-equal to 1, FAO outputs an "S";
value is a 1 (as 1in the second example), FAO does not output an
The

output

value

field

converted,

length defines
to

provide

a width

spacing

between

characters
the

output

for

each

fields.

value
if the
"S".

byte

SYSTEM SERVICE DESCRIPTIONS

$SFAO
Example
s

FORMATTED

ASCII OUTPUT

CONTROL

STRING

FOR

EXAMFLE

TIMESTRS DEfiCRiPTUH TEEEKE ONOW IS 1EDS
s

CALL

$FAO0

$F50m$ CTH&TR*TIMESTRyOUTLEN%FAULENvUUTBUFflFfiDHEQCy@
Frfadgk(y

Results:

FAO writes

the

output

NOW

198

string:

dcd-mmm-wuwy

hhimmiss.
oo

where dd-mmm-yyyy 1s the current day, month, and year, and hh:mm:ss.cc
is
of

the current
seconds.

time

The 15*> directive
characters

directive,

into

FAO

in
'

requests

the

also

day

output

writes

hours,

FAO

string.
space

minutes,

write

Since

after

the

seconds,

five

there
>

and

hundredths

greater
a

space

characters

than

(>)

after the
output.

The !%D directive requires the address of a quadword time value, which

must
be
1in the system time format.
However, when the address of the
time value is specified as 0, FAO uses the current
date and time.
For
information
on
how
to
obtain
system
time
values 1in the required

format, see Section 3.6, "Timer and Time Conversion Services."
For
a
detailed
description
of the ASCII date and time string returned, see
the discussion of the Convert Binary Time to
ASCII
String
(SASCTIM)
system service in this chapter.
|
|

Example

s CONTROL STRING FOR EXAMFLE 9
DAYTIMSTR: UESCRIFTOR <DATES: !11%D
8% TIMES I5%T>
3 CALL TO FaO

$FAU_q CTRETR=DAYTIMSTR s OUTLEN= FfiULENyUUTBUT»FfifiDFH(yw
|

Pi“#OvFB”# y [ 3=%0

Results:

FAO

writes
NDATE :

the

output

string:

dd~mmm~uwwsuummwTIMEt

In this example, ahn output length of 11 bytes is
specified
with
$D
directive,
so that FAO truncates the time from the date and
string, and outputs only the date.
.

The !#* directiv

requests

repeated
the
number
P2 is specified as 5,

that

the

underline

character

(_)' be

of times specified by the next parameter.
Since
5 underlines are written into the output string.

The !%T directive normally returns the
full
system
time;
in
example,
the
I5%T
directive provides an output length for the
only the hours and minutes fields of the time string are written
the

output

buffer.

the
time
,

this
time;
1into

SYSTEM SERVICE DESCRIPTIONS
SFAO

FORMATTED ASCII

OUTPUT

rgiample 10]
#

CONTROL

STRING AND FARAMETERS

FOR EXAMFLE

NIDTHSTRf DESCRIPTOR ~/125<VAR: !AC VAL? 'UL!>TOTALS!7UL”
VARINAME:? +ASCIC /INVENTORY/Z
=
VAR1?
+ LONG
334
VARITOT? « LONG
6394
VARZNAME: .ASCIC /SALES/
VARZ2?
+ LLONG
280
VARZTOT ¢ + LONG
107350
#

CALLS

FUARIARLE 1 NAME
¥y CURRENT VALUE
sVUAR 1 TOTAL.

sVAR 2 NAME
s CURRENT VALUE
sVAR 2 TOTAL

sFAQD

$FAD.S CTRSTRMWIDTHSTR?OUTLENwFAOLENvOUTBUFmFfiDDEfifiim
F1=#VARINAME » F2=VAR1 »F3=VARLITOT

$FAD0.S CTRSTR=WINTHSTRy OUTLEN=FAOLENy QUTRUF=FADDESC, -

F1=#VARZNAME y F2=VAR2y F3=VAR2TOT

\\-_/

|
Results:

Following the first call to FAO shown above,
|

string:

FAO

writes
~

the
|

output

VAR: INVENTORY VAL! 334AATOTAL:AAAGSSA

After the second call, FAO'writes the output string:
VAR?!

SALES

val.t

280AAAAAATOTAL
T AALQ750

The !25< directive requests an output field width
of
25
characters;
the
end
of
the
field is delimited by the !> directive.
Within the
field defined in the example above are two directives,
!AC
and
!UL.
The
strings
substituted
by these directives can vary in length, but
the entire field always has 25 characters.

The !7UL directive formats the longword passed
argument)
field.

and

right-justifies

the

result

in
|

each

example

7-character
.

(P2

output

SYSTEM SERVICE

DESCRIPTIONS

$FORCEX
4.37

S$FORCEX - FORCE

EXIT

The Force Exit system service causes
an Exit
call

to be

(SEXIT)

issued on behalf of a specified process.

system

service
|

Macro Format:

Language

,[prcnam]

,[code]

Format:

SYSSFORCEX ([pidadr]

,[prcnam]

,[code])

pidadr

process

identification

‘\

address of a longword containing the
the process to be forced to exit.

High-Level

[pidadr]

\«_.//

SFORCEX

prcnam

address of a character stflng descriptor pointing to the
process
name
string.
The
name
is implicitly
qualified by the group
number of the process issuing the force exit request.
code

longword completion code value
If not specified, a value
of 0

to be used as the exit
parameter.
is passed as the completion code.

If neither a process identification nor a process name
1is
specified,
the caller is forced to exit and control is not returned.
For details

on how the service interprets the PIDADR

Table 3-3.

Table 3-3 is

in Section 3.5,

and

PRCNAM

arguments,

see

"Process Control Services."”

Return Status:
SS$ NORMAL

Service

|
successfully completed.

SS$_ACCVIO

The process name strlng or string descriptor cannot be
read,
the process identification cannot be written, by the caller.
SS$_NONEXPR

Warning.
The specified process does not
process identification was specified.

SS$_NOPRIV

The process does not have

So$

exist,

1invalid

the privilege to force an exit for

the

specified process.
INSFMEM

Insufficient system dynamic memory is available to
complete
the
service
and the process has disabled resource wait mode with the
Set Resource Wait Mode (SSETRWM) system service.

SYSTEM SERVICE DESCRIPTIONS
SFORCEX - FORCE EXIT

Privilege Restrictions:

User privileges are required to force an exit for:

°
e

Other processes in the same group (GROUP privilege)
Any other’process'in the system (WORLD privilege)

Resources Required/Returned:

The Force Exit system service requires system dynamic memory.
Notes:

exit
The image executing in the target process followsrsnormal
have been
For example, if any exit handle
procedures.
gain control before the actual exit occurs.
they
ed,
specifi
Use the Delete Process ($SDELPRC) system service if you do not
,

p—

want a normal exit.

mode
When a forced exit is requested for a process, a user
The AST routine
AST is gqueued for the target process.
by
actually causes the Exit system service call to be issued user
used,
is
ism
mechan
AST
the
Because
.
process
the target
exit
mode ASTs must be enabled for the target process, or no called
that
process
The
led.
re—enab
are
ASTs
occurs until
SFORCEX receives no notification that the exit is not being
performed.

es successfully 1if a force
3. The SFORCEX system servicein complet
effect for the target process but
exit

is already
request

the exit is not yet completed.

explanation of
For an example of the $SFORCEX system service, and anexits,
see Section
image
an
when
system
the
by
the actions performed
|

3.5.6,

"Image Exit."

SYSTEM

SERVICE

DESCRIPTIONS

$GETCHN
4.38

SGETCHN
-~

GET

I/O

CHANNEL INFORMATION

The Get I/O Channel Information
about

device

information

which

an
optionally

are

SYStem

I/0 channel
returned:

service
has

been

The

The secondary device Characteristics

most

primary

<cases

identical.
following
@

device

the

two

However,

the

secondary
@

the

are

device

has

characteristic

provide

different

associated
those
of
the

sets

spooled

the

are

those

device,

are

those

the

of
the

intermediate

characteristics

the

the
device

associated

primary

device

spooled

contain

information

mailbox,
assigned

are

the

primary

and

the

mailbox.

characteristics

and

the

secondary

device.

'Ifthe device represents a logical link on
secondary

Macro

sets

are

characteristics

sets

two

characteristics

those

information

Two

characteristics

cases:

If
the
device
characteristics

returns
assigned.

the

information

network,

about

the

link.

Format:

$GETCHN chan

,[prilen]

High-Level Language

,[pribuf]

r [scdlen]

,[scdbuf]

Format:

SYS$GETCHN (chan

, [prilen]

,[pribuf]

,[scdlen]

,[scdbuf])

chan
number

the

I/O

prilen

channel

assigned

receive

the

device.

address

word

characteristics.

length

©of

the

primary

- pribuf
-

address

that

1s
to
address of 0

character

receive
(the

scdlen
address

string

the
default)

'
of a
word
characteristics.

descriptor

primary
implies

receive

pointing

device
that

the

to
the
buffer
characteristics.
An
buffer is specified.

1length

the

secondary

scdbuf
address of a character string desériptor pointing to buffer
1s

receive

(the

the secondary device characteristics.
An
default)
implies that no buffer is specified.

that

address

SYSTEM SERVICE DESCRIPTIONS

$SGETCHN - GET I/O CHANNEL INFORMATION
Return Status:

|
|
SS$_BUFFEROVF
information returned
Service successfully completed. The devicebeen
truncated.
has
and
ed
provid
(s)
buffer
the
owed
overfl
SS$_NORMAL

Service successfully completed.

1length

or a buffer or buffer
A buffer descriptor cannot be read,
|
.

SS$_ACCVIO

cannot be written, by the caller

|
that 1s, a channel
An invalid channel number was specified,
number of 0 or a number larger than the number of channels

SS$_IVCHAN

available.

SS$_NOPRIV

The specified channel is not assigned, or
more privileged access mode.

was assigned

from

Privilege Restrictions:

be performed only on
The Get I/O Channel Information service can
are equal to or more
that
modes
s
acces
from
and
els
assigned chann
the original channel

privileged than the access mode from which
assignment was made.

service returns
The Get I/O Device Information (SGETDEV) system
ation system
Inform
l
Channe
I/0
Get
the
as
ation
inform
the same
service.

4.38.1

Format of Device Information

mation in a
ces return infor
$GETDEV system servi
The SGETCHN and Dbuffe
SDIBDEF macro
the
in
ed
defin
names
lic
symbo
r.
user-supplied

of the buffer.
represent offsets from the beginning
DIBSK_LENGTH.

buffer is defined in the constant

The length of the

The field offset names, lengths, and contents are listed below.

DIBSB_DEVCLASS
DIB$B_TYPE

DIBSW_DEVBUFSIZ

DIBSL DEVDEPEND
DIBSW_UNIT

DIBSW_DEVNAMOFF
DIBSL PID

DIBSL OWNUIC
DIBSW_VPROT

DIBSW_ERRCNT
DIBSL_OPCNT
DIBSW_VOLNAMOFF

DIBSW _RECSIZ

NN NS

DIBSL_ DEVCHAR

Length (bytes)

IO N0

Field Name

Contents

Device characteristics
Device class
Device type

Device buffer size

Device dependent information
Unit number
Offset to device name string
Process identification of device owner
UIC of device owner

Volume protection mask
Error

count

- Operation count

PO RO

Note:

Offset to volume label string

Blocked

record

size

(valid

for

magnetic tapes when DIBSW_VOLNAMOFF is
nonzero)

4-93

SYSTEM SERVICE DESCRIPTIONS

SGETCHN
The

device
buffer
as

offsets

For

name

string and
counted
ASCII

from

Any fields

the

beginning

inapplicable

further

details

device-dependent

Guide.

GET I/0 CHANNEL
volume

label
strings and

the

string

must

buffer.

to a particular

information

INFORMATION

are
returned
in
the
located by using their
|

device are

returned

contents

this

returned,

buffer,

see

the

- VAX/VMS

as zeros.
and

1I/0

User's

SYSTEM SERVICE DESCRIPTIONS

SGETDEV
4.39

SGETDEV - GET

I/0 DEVICE

INFORMATION

The Get I/0 Device
Information
system
service
returns information
about
an I/0
device.
This service
allows
a
process
to obtain
information about a device to which the process
has
not
assigned
a
channel.
It
returns
the
same information
as the Get I/O0 Channel
Information (SGETCHN) system service, as described in Section 4.38.

Format:

Macro

SGETDEV devnam

High—-Level

Language

, [prilen]

,[pribuf]

,[scdlen]

,[scdbuf]

Format:

SYSSGETDEV(devnam , [prilen]

,[pribuf]

,[scdlen]

,[scdbufl])

devnam

address of a character string descriptor pointing to
the
device
name
string.
The string may be either a physical device name or
a logical name.
If the first
character
in
the
string
1s an
underline character (_), the name is considered a physical device
name.
Otherwise, a single level of logical name
translation
1is

performed and

the equivalence name,

prilen

address
of
a
word
characteristics.

receive

if any,

the

is used.

1length

the

primary

pribuf

address of a character string descriptor pointing to
the
buffer
that
1is
to
receive
the
primary
device
characteristics.
An
address of 0 (the default) implies that no buffer is specified.
|

scdlen

address of
a word
characteristics.

receive

the

1length

the

secondary

scdbuf

‘address of a character string descriptor pointing to buffer
that
is
to
receive the secondary device characteristics.
An address
of 0 (the default) implies that no buffer is specified.

Return Status:
SS$_BUFFEROVF

Service successfully completed.
The device information
returned
overflowed the buffer (s) provided and has been truncated.

SS$_NORMAL

Service

SS$

ACCVIO

successfully completed.

A buffer descriptor cannot be read,
cannot be written, by the caller.

a buffer or buffer

1length

SYSTEM SERVICE DESCRIPTIONS
SGETDEV - GET I/O DEVICE INFORMATION

SS$ IVDEVNAM

No device name was specified,
invalid

the

device

name

string

has

characters.

SS$_IVLOGNAM

The device name string has a length of 0

has

than

characters.

SS$_NONLOCAL
|
Warning.

SS$_NOSUCHDEV

Warning.

~
The device

is on

remote

system.

The specified device does not exist on the host system..

SYSTEM SERVICE

DESCRIPTIONS

SGETJPI
4.40

SGETJPI

- GET JOB/PROCESS

INFORMATION

The Get Job/Process Information system
service
provides
accounting,
status, and identification information about a specified process.
Format:

Macro

$SGETJPI

,[pidadr]

,[prcnam]

,itmlst,,,

High-Level Language Format:l
SYSSGETJPI(, [pidadr]

,[prcnam]

,itmlst,,,)

pidadr
\\\—n/g

address of a longword containing the
the process for which

‘

process

information 1is requested.

address of a character

prcnam

identification

string descriptor

15-character process name string.

pointing

The process name is implicitly

gqualified by the group number of the process

issuing the request.

itmlst

address of a list of item descriptors that describe the
specific
information requested
and
point
to
buffers
to
receive
the
information.
The format of the
1list
1is
described
1in
Section

4.40.1.

The

item codes

are

listed

in Table

4-4.

" If neither a process identification nor a process name
1is
specified,
information about the calling process is returned.
For detalils on how
the service 1nterprets the PIDADR and PRCNAM arguments, see Table 3-3.
Table 3-3

Return

SSS

in Section 3.5,

"Process Control Services.'

Status:

NORMAL
Service

successfully completed

SS$_BADPARAM

The item list contains an invalid
identifier;
or,
the
<caller
requested
information
that
1is not in the process control block
about

another

process.

SS$_ACCVIO

The

item list cannot be read,

cannot be written,

the

caller.

the

buffer

SS$ IVLOGNAM

The process name string has a length of 0,

1length

or has

buffer

than

characters.

The first, fifth, sixth,

argument list are not used;

and

seventh

they are

arguments

reserved

for

the

future use.

$GETJPI

SYSTEM SERVICE DESCRIPTIONS

$GETJPI
SS$_NONEXPR

Warning.
process

GET JOB/PROCESS

The specified process does not exist,

identification was

specified.

SS$_NOPRIV

The process does not have the
about

Privilege

INFORMATION

the

specified process.

priVilege

‘

obtain

invalid

information

Restrictions:

" User privileges are required to obtain information about:

Other processes in the same group (GROUP privilege)

Any other ptocess in the system (WORLD privilege)

‘Note:

When a process requests
information
about itself,
information
contained
in
the
PCB,
in the process header, or in the control
region of the process's virtual address space can be obtained.
When a process requests information about another
information contained in the PCB can be obtained.

4.40.1

Format of Item List for

S$GETJPI

process,

only

System Service

The item list used for input to the $GETJPI system service consists of
one

this

list

more
has

consecutive

the

item descriptors.

Each item descriptor

format:

16 15

item code

buffer length

buffer address

return length address

buffer

length

length of the buffer to receive the specified

buffers
reserved
to
receive
information
unless otherwise indicated in Table 4-4.
item code
symbolic name defining
symbolic names have the

|
the
information
format:

information.
All

should

longwords

returned.

The

JPI$_code

These symbolic names are defined
in the $JPIDEF macro.
are

listed

in Table

4-4.

The codes

SYSTEM

SERVICE

DESCRIPTIONS

SGETJPI - GET JOB/PROCESS INFORMATION
buffer

address

address of the buffer to receive the spec1f1ed
information.
I1f
the buffer
1is
too small for the requested information, S$GETJPI
truncates

1it.

return length address
- address of a word
to
returned.
If
this

receive
address

the
1length
1is
specified

of
as

terminated

the
0,

information
no length is

returned.

The

list of

item descriptors must

or a longword of 0.

item code

All buffers are zero-filled on return, if necessary.
For

example,

process
GETLIST:

item list can

identification
.WORD

coded

and process

name

as
of

FLENGTH

+WORD

JFI$_FID

s REQUEST

+LONG
+LONG
+WORD
+WORD
«LLONG

GETFID
O
'
13
JFIS
. _FRCONAM
GETFROCNAM

+LONG

+BLKE

135

|
-

obtain

the

RUFFER

FII

yREQUEST FROCESS NAME
s ADDRESS TORECEIU& NAME

FANDRESS TO RECEIUL LENGTH
SENDN

GETFID: .RLKL 1
GETFRCNAM:

GETLIST

yRETURN FID HFRF
yR&TURN FROCESS
fRETURN

LENGTH

NAMF HRhF

FADDRESS TO RECETVE FID
sOON/T NEED LENGTH RETURN
|
SLENGTH OF BUFFER

+ LONG FRCNAM.LEN

FRCNAM_LEN?
+BLKW

follows

a process:

<
PRO(LSS

NAME

SYSTEM SERVICE DESCRIPTIONS

SGETJPI

Item

GET

JOB/PROCESS

INFORMATION

Codes for

Table 4-4
Job/Process

Information

Item .
Identifier

Type

Location

|Information

JPIS$S_ ACCOUNT

string

|control

|Account name string (l1-8 characters)

JPIS$S APTCNT

value

|PCB

Active page table count

JPI$ ASTACT

value

(PCB

Access modes with active ASTs

JPIS ASTCNT

value

PCB

Remaining AST quota

JPIS$ ASTEN

value

PCB

Access modes with ASTs enabled

JPI$_ASTLM

value

|PHD

AST

JPI$ BIOCNT

value

PCB

Remainihg buffered I/0 quota

JPIS$ BIOLM

value

PCB

>Buffered I/0 limit quota

JPIS$ BUFIO

- value

|PHD

Count of'process buffered 1/0 0pefations

JPIS$ BYTCNT

value

|PCB

Remaining buffered I/0 byte'couht quota

JPI$

value

|PCB

Buffered
I/0 byte

JPI$ CPULIM

- value

|PHD

Limit on process CPU time

JPIS_CPUTIM

value

PHDA

Accumulated CPU timé (in 10-millisecond tics)

JPIS$ CURPRIV

value

|PHD

Quadword mask of process's current privileges

JPIS$ DFPFC

value

|PHD

Deféult page fault cluster size

JPI$ DFWSCNT

value

|PHD

Default working

JPI$_DIOCNT

value

[PCB

Remaining

JPI$ DIOLM

value

|PCB

Direct

JPIS_DIRIO

value

|PHD

Count of direct I/0 operatibns for process

JPI$ EFCS |

value

PCB

Local event flags 0 through 31

JPI$ EFCU

value

|[PCB

Local

JPI$_EFWM

value

|PCB

Event flag wait mask

JPI$_EXCVEC

address|control

BYTLM

limit

Returned

59r6203>
|

quota

I/O

count limit quota

set

direct

Data

I/O

size
quota

limit quota

event

flags

|Address of a

32 through

1list

following
order:
vectors for kernel

exception

vectors

primary

and

secondary

mode;

primary

and

in ,the

exception
secondary

exception
vectors for executive mode;
primary and
secondary exception vectors for
supervisor
mode;
primary
and
secondary - exception vectors for user
mode

JPI$ FILCNT

value

PCB

Remaining open

file

JPIS$ FILLM

value

PHD

Open file quota

JPIS$_ FINALEXC

address|control

quota

|Address of a list of final
kernel,

executive,

exception

supervisor,

then

mode

vectors

value

PHD

First free page at end of program region

JPI$ FREP1VA

value

PHD

First free page at end of control region

column:

virtual

address

space

region

PCB

indicates that the

information is in the process control block

PHD

indicates

information

that

the

4-100

process

header

the

process's

control

\\\._,_/

control indicates that the information is in the

Location

the

for

access

JPIS$ FREPOVA

user

SYSTEM SERVICE DESCRIPTIONS
SGETJPI

GET JOB/PROCESS
Table

Item Codes

Item

Data

for

Information

Type

Location | Information

JPI$ GPGCNT

value

PCB

Global page éount in working_setA

JPIS$_GRP

value

PCB

Group number of UIC

value

control

Process
delta

;

(Cont.)

4-4

Job/Process

Identifier

JPIS LOGINTIM

INFORMATION

Returned

execution

time

time;

returned

64-bit

system

value

JPIS$ MEM

value

PCB.

Member number of UIC

JPIS$ OWNER

value

PCB

Process identification of process owner 1| 6503;)

JPIS$ PAGEFLTS

value

PHD

Count of page faults

JPI$ PGFLQUOTA | value | PHD

Paging

JPI$_PID‘

value

PCB

Process identification

JPIS$ PPGCNT

value

PCB

Process page count in wotking set

JPIS_PRCCNT

value

PCB

Count
of

JPIS_PRCLM |

~value

PHD

Subprocess quota

JPIS_PRC}NAM

string| PCB

file quota

supprocesses

Process name (1-15 characters)'

‘fi‘?t C:HC,)

JPI$ PRI

value

PCB

Current process priority

JPIS PRIB

value

PCB

Process's

JPI$_PROCPRIV

value | control |Quadword mask of process's default privileges

JPIS STATE

value

PDB

Process state

JPIS_STS

value

PCB

Process

JPI$ TMBU

value | PCB

Termination mailbox

JPI$ TQCNT

value

PCB

Remaining timer queue entry quota

JPI$ TQLM

value

PHD

Timer queue entry quota

JPI$ UIC
JPI$ USERNAME

value PCB
string| control

Process's UIC
User name string (1—12 characters)

JPIS$ VIRTPEAK

value

control

Peak

JPI$ VOLUMES

value

control

|[Count of’curréntly mouhted volumes

JPIS WSAUTH

value

PHD

Maximum authorized working set

JPI$_ WSPEAK
JPIS_WSQUOTA

value | control [Working set peak
value | PHD
Workingvset size qfiota
value
PHD
Pchess's current working set size

JPIS _WSSIZE

the

Location

base priority

status

virtual

address

control indicates that the information is in the
PCB
PHD

TYH-

indicates

unit number

‘112 (30‘1-)
5'“1. (902 P

size

column:

virtual address space
indicates that the information

that

the

information

is
is

0548314

in
in

control

region of

the process control
the process header

~7§£§4 ARE
4-101

block

the

process's

[«msqfi’fi

Cogq33H

SYSTEM SERVICE DESCRIPTIONS

$SGETMSG
4.41

S$SGETMSG

GET MESSAGE

The Get Message system service transfers a

message

file

the

<caller's

operating

system
to
identifications and to

Macro

buffer.

retrieve
prepare

messages
to

output

message

from

This

service

based

the

system

is used by the
unique.
message

them.

Format:

$SGETMSG

Aigh-Level

msgid

,msglen

Language

Format:

SYS$GETMSG (msgid

,bufadr

,[flags]

,msglen ,bufadr

,[outadr]

,[flags]

,[outadr])

msgid
identification
the

system

the

high-order

the

message

file

bits

has

system

msglen
of

word

bufadr
address

character

receive

that

can

flags

the

receive

longword

the

length

string.
256

The

defining
meanings are:

message

Value

the

content.

Include

‘Include

not

Include

argument
wvalue

message

not

Include

this

in
in

codes.

the

string

pointing

maximum

size

returned.

the

any

buffer‘

message

The

bits

~
the

mask

and

their

Meaning

If
to

status

message
contained

bytes.

Each

identification,

|
string descriptor

message

returned

mask

Bit

retrieved.

address

unique

not

text

include

message

text

message
include

omitted

15, that is,
are returned.

all

4-102

identifier

indicator

severity

facility
include

message

identifier
message

severity
include

indicator

name

facility

name

MACRO service
flags are set

call, it
defaults
and all components

SYSTEM

SERVICE

SGETMSG

DESCRIPTIONS

GET

MESSAGE

outadr

4-byte

array

receive

address

the

following

values:

Byte

Contents

Reserved

Count of FAO arguments associated with message
User-specified
value in message; if any

Reserved

Return Status:
SS$_BUFFEROVF

Service successfully completed.
the

buffer

provided,

and

The string

has been

SS$_MSGNOTFND
Service successfully completed.
The
an associated message in the file.

SS$ NORMAL
Service

4.41.1

Message

system

codes

overflowed

message

code does

not

have

symbolic

names

|
successfully

completed.

Formats

The messagé identifications
status

returned

truncated.

returned

services,

When all bits in
in the format:

correspond

system

RMSS$ code

for

the

argument

FLAGS

the
for

example

messages,

and

components,

RMS

are

set,

$GETMSG

SS$ code

for

from

on.

returns

string

facility—-severity-msgcode message-text

where:
facility

identifies the component of the operating system

severity

For

is the severity code (the low—order three bits

the

status

code)

msgcode

message-text

is the text of the méssage

example,

the

the unique message

MSGID

argument

identifier

specified

MSGID=#SS$_DUPLNAM

SGETMSG

returns

the

string:

3SYSTEM-F-DUPLNAM,

duplicate

process

4-103

name

as:

SYSTEM

SERVICE'DESCRIPTIONS

4.42

SGETTIM

The Get
64-bit

GET

SGETTIM
TIME

Time

system service
format.
The
time
system base time.

the

Macro

furnishes the
current
system
time
in
is maintained in 100-nanosecond units from

Format:

SGETTIM

timadr

High-Level Language Format:
SYSSGETTIM (timadr)
timadr
-

address

64-bit

Return

|
a

quadword

that

receive

format.

the

«current

time

Status:

SS$_NORMAL
Service

successfully

SS$_ACCVIO

completed.

The quadword to receiv
the
e time cannot be written by the caller.

Note:

For

details

Time

example

the

$GETTIM

on
the
system time
Conversion Services."jg

system

format,

service,

see

5?@;
AT.

4-104

Section

‘and

additional

3.6,

"Timer

and

)

SYSTEM SERVICE DESCRIPTIONS

$SHIBER
4.43

SHIBER - HIBERNATE

s 1inactive
itself
es
to make
oc
The Hibernate system service allows a pr
upted, for
interr
be
can
it
that
sO
system
the
" but to remain known to
e-event
or-wak
wait-f
a
is
to receive ASTs.” A hibernate request
example
the
with
s
proces
ating
hibern
a
for
issued
When a wake 1is
request.
system
K)
(SSCHDW
Wakeup
le
Schedu
a
of
result
a
or
e
servic
SWAKE system
at the instruction following
service, the process continues execution
the Hibernate call.

Macro Format:l
$SHIBER_S

{/'

High-Level Language Format:

SYSSHIBER

Return

Status:

SS$_NORMAL

Service successfully completed.

Notes:

balance

set

A hibernating process can be swapped out of the

be
The wait state caused by this system service if can
the
(1)
(AST)
trap
system
ronous
asynch
an
by
pted
interru
or
access mode at which the AST is to execute is eqgual to ate
hibern
the
which
from
mode
access
the
than
eged
more privil
request was issued and (2) the process is enabled for ASTs at

if it is not locked into the balance set.

that. access mode.

on, the system
When the AST service routine completes executi
on the process's
re—executes

the

S$HIBER system

service

behalf. If a wakeup request has been issued for the process
during the execution of the AST service routine (either by
itself or another process), the process resumes execution.

"Otherwise, it continues to hibernate.

If one or more wakeup requests are issued for the process
while it is not hibernating, the next hibernate call returns
No
immediately, that is, the process does not hibernate.
count is maintained of outstanding wakeup requests.

additional information
For an example of the SHIBER system service and"Proces
s Hibernation and
3.5.5,
n
on process hibernation, see Sectio
s, see Section
request
wakeup
ed
schedul
of
example
Suspension." For an
/
3.6.6, "Scheduled Wakeups."
1

" _S" macro form
oOnly the

provided

service.

4-105

for

the

Hibernate

system

SYSTEM

SERVICE

DESCRIPTIONS

SINPUT
4.44

S$SINPUT - QUEUE

INPUT REQUEST AND WAIT FOR EVENT FLAG

The S$INPUT macro is a simplified form of the

Wait

for

virtual

for

I/0

Macro

Event

Flag

($SQIOW)

input

operation
completion.

using

system

the

Queue

service.

I0$ _READVBLK

1I/0
This

function

Request
macro
code

and

queues

wailts

Format:

$INPUT

chan

,length

,buffer

,[iosb]

,[efn]

chan

the

I/O

channel

read.

length
length

assigned

the

device

from

which input

the

input buffer.

buffer

number

address

iosb

the

input

buffer.

|
address

efn

quadword

I/O

status

The

|
the event flag to be
default is event flag 0.

The

SINPUT

for

the

number

block.

set

when

the

request

complete.

coded

Note:

only

one

form,

form.
but

call.

the
|

Queue
|

I/0

included

as
the

Required/Returned,

Request ~ (SQIO)
|

system

service.

Resources

must

See the deséription

Restrictions,

not

\“

Privilege

Notes:

must

Status,

Arguments

" S"

Return

Additional

has

macro

Sname_S

4-106

SYSTEM SERVICE DESCRIPTIONS

SLCKPAG
4.45

SLCKPAG

LOCK PAGES

IN MEMORY

The Lock Pages In Memory system service locks a page or

range of pages

in
memory.
The
specified virtual pages are forced into the working
set and then locked in memory.
A locked page is not swapped with
its
working
set.
These pages are not candidates for page replacement and
in this sense are locked in the working set as well.

Macro

Format:

SLCKPAG

1inadr

,[retadr]

,[acmode]

High-Level Language Format:

SYS$LCKPAG(inadr , [retadr]. , [acmode])
inadr

»
address

2-longword

array

containing

the

starting

and

ending

virtual addresses of the pages to be locked.
If the starting and
ending virtual addresses are the same, a single page
1is
locked.
Only
the virtual page number portion of the virtual addresses is
used;
the low-order 9 bits are ignored.

retadr
address
virtual

of a 2-longword array to receive the starting
addresses of the pages actually locked.

and

acmode
|
access mode of the locked pages.
The specified
access
maximized
with
the
access
mode of the caller.
The
access mode
mode of the

Return

must be equal
owner of each

ending

mode
1is
resultant

to or more privileged than
the
page in order to lock the page.

access

Status:

SS$ WASCLR

Service

successfully

previously

completed.

All

the

completed.

least

specified

pages

were

unlocked.

SS$S_WASSET
Service successfully
pages was previously

locked

one

the

specified

in memory.

SS$_ACCVIO
1.

The input array
written, by the

A page
exist.

the

cannot be
caller.

specified

read,

range

the

output

1inaccessible

array

cannot

does

pages

that

not

SS$_LCKPAGFUL
The

system-defined

locked

maximum

in memory

has

limit

been

the

number

reached.

can

‘

SS$_NOPRIV
The

process

does

not

have

the

privilege

4-107

lock

pages

memory.

SYSTEM SERVICE DESCRIPTIONS

SLCKPAG

Privilege
1.

LOCK

PAGES

PSWAPM

1is

MEMORY

Restrictions:

The user privilege

required

lock

pages

1in

Mmemory.

The access mode of the
privileged than the
being locked.

caller

access
|

must

equal

to or

mode of the owner of the pages
|
B
o

Notes:.

If more than one page is'being locked, and it 1s necessary to

determine
locked,

specifically

which

had

pages

been

the pages should be locked one at a time.

previously

if
If an error occurs while locking pages, the return array,
indicates the pages that were successfully locked
requested,
both
If no pages are locked,
before the error occurred.
a -1.
longwords in the return address array contain

Pages that are locked in memory

can

unlocked

With the

Locked
from Memory (SULKPAG) system service.
Pages
Unlock
|
pages are automatically unlocked at image exit.

4-108

SYSTEM

SERVICE

DESCRIPTIONS

SLKWSET
4.46

SLKWSET - LOCK PAGES IN WORKING SET

The

Lock
specify

Pages

replaced

in Working Set
system
a
group of pages that

that
the

working

set.

working
set if they are
do not become candidates

The

not
for

service
allows
are heavily used

specified

already there
replacement.

pages
and

are

a
process
to
should never be

brought

locked

into
that

the
they

Macro Format:
SLKWSET

inadr

, [retadr]

, [acmode]

High—Level Language Format:
SYSSLKWSET (inadr
inadr

address of

, [retadr]

2-longword

,[acmode])
-

array containing

the

virtual

addresses of the pages to be locked.
If the
ending virtual addresses are the same, a single page
Only
the virtual page number portion of the virtual

used;

the low-order

retadr
address
virtual

bits are

Return

owner

equal

each

ignored.

to or more privileged
page in order to lock

than

the

and

1is
locked.
addresses is

and

acmode
access mode of the locked pages.
The specified
access
maximized
with
the
access
mode
of the caller.
The
must

ending

starting

|
of a 2-longword array to receive the starting
addresses of the pages actually locked.

access mode
mode of the

starting and

ending

mode
is
resultant

the
page.

access

Status:

SS$_WASCLR
Service successfully
previously unlocked.

SS$_WASSET
|
Service successfully
pages was previously

completed.
|

All

completed.

least

locked

the

the
-

specified

one

working

pages

were

.
specified

the

set.

SS$_ACCVIO

The

input address array cannot be

array

page

cannot

the

written,

specified

the

range

read,

caller.

inaccessible

SS$_LKWSETFUL
The

nonexistent.

working set is full.
If any more
pages
are
will
not
be
enough
dynamic pages available to

execution.

page

|
in

locked,
continue

SS$_NOPRIV
A

locked

there

the output address
,

the

specified

|
range

is in

4-109

the

system

address

space.

SYSTEM SERVICE DESCRIPTIONS
SLKWSET - LOCK PAGES IN WORKING SET

‘Privilege

Restrictions:

The access mode of

‘than

the

the caller must be equal

access mode

the

owner

to or more privileged

the pages

being

locked.

Notes:

If more than one page 1is being locked, and it is necessary to

determine
specifically
which
pages
had
been
locked, the pages should be locked one at a time.

previously

If an error occurs while locking pages, the return array,
1if
requested,
indicates the pages that were successfully locked
before the error occurred.
If
no
pages
are
locked,
both
longwords in the return address array contain a -1.
|
3.

Pages that are locked in the working set can be unlocked with
the Unlock Page from Working Set (SULWSET) system service.

For an explanation of the relationship between a process's working set
see Section 3.8,

"Memory Management

space,

address

virtual
1its
and
Services."

4-110

SYSTEM SERVICE DESCRIPTIONS

- SMGBLSC
4.47

$MGBLSC

- MAP GLOBAL

SECTION

The Map Global Section provides
a process with access to

global

section.

Mapping

a global

section

correspondence between pages in the process's
and the physical pages occupied by the global

virtual
section.

existing

establishes
address

the

space

Format:

Macro

SMGBLSC

High-Level

inadr ,[retadr]
r [relpag]

Language

,[acmode]

,gsdnam

,[ident]

Format:

SYSSMGBLSC
(inadr ,[retadr]
|

,[flags]

,[acmode]

,[flags]

,gsdnam

,[ident]

, [relpagl])

inadr

address of a 2-longword array containing the starting and
ending
virtual
addresses
1in
the
process's virtual address space 1into
- which the section
is to be mapped.
The
pages
can
be 1in
the
program (PO) region or the control (Pl) region.
If the starting
and ending virtual
addresses
are
the
same,
a
single page
1is mapped. Only the virtual page number portion of
the virtual addresses is used;
the low-order 9 bits are ignored.

retadr

address of a 2-longword
virtual
addresses
of

array to receive
the
pages
into

the starting and
ending
which
the
section was

actually mapped.

acmode

access mode indicating
mapping.
The
access
the

flags

—

the owner of the pages created during
the
mode 1s maximized with the access mode of

caller.

mask defining the section type
and
characteristics.
Flag
bit
settings
can
be
ORed
together to override default attributes.
The flag bits for the mask are
defined
in
the
S$SECDEF
macro.
Their meanings, and the default values they override, are:

Flag

Meaning

SECSM_WRT

Map section read/write

SECSM_SYSGBL

gsdnam

address of

System global

a character

15-character
the

section

_Map section read-only
Group global

string descriptor pointing

text name string for the global section.

global sections,
by

Default Attribute

the global

group number

the

section name

caller.

4-111

implicitly
|

section

the

For group
qualified

ident
address
section

SYSTEM

SERVICE

$MGBLSC

MAP

SECTION

of a guadword indicating the version number of the
and the criteria for matching the identification.

The version number
contains

two

bits

and

The

first

in the second longword.

fields:

a major

-matching
they can

minor

identification

longword

specifies,

the

1in

the

global

The version number
in

the

high-order

low-order

bits.

1ow order

<criteria.
The wvalid
values,
be specified, and their meanings

Value/Name

bits,

the

symbolic names by which
are listed below:

Match Criteria

SECSK_MATALL

Match

all

SECSK _MATEQU
|
SECSK_MATLEQ

Match
match
Match

only

DESCRIPTIONS

GLOBAL

versions
of
if

the

major

the

and

major

section

minor

identifications

are

equal

and the minor identification of the mapper is
less
than
or
equal
to
the
minor
identification of the global section
If no address is specified, or is specified
as 0
(the
the version number and match control fields default to
relpag

relative

|
page

mapped.

not

global

section

section.

Return

the

within the

specified
mapped

section

the

specified as

beglnnlng

with

the

|
page

3
to

(the default),

the

first

wvirtual

block

Status:

SS$_NORMAL
Service
SS$

number

default),
0.

ACCVIO

~ The

|
successfully

input

descriptor
return

completed.

address
or

array,

section

address

array

the

global

identification
cannot

written,

its

paging

SS$_EXQUOTA
The

section

field
by

name

cannot

read,

the

caller.

file

quota

name
or

the

|
process

exceeded

copy-on-reference

SS$_INSFWSL
The
process's
accommodate

the

pages.

|
working

set

increased

SS$_IVLOGNAM
The global section
characters.
-

name

|
1limit

virtual

has

|
a

creating

1is

not

address

length

1large

enough

space.

has

more
|

than

identification

SS$_IVSECFLG
A

SS$

reserved

flag

was

set.

IVSECIDCTL

~ The match control fleld of the global
invalid.

sectlon

4-112

'SYSTEM SERVICE DESCRIPTIONS
- MAP

SMGBLSC

GLOBAL

SECTION
-

SS$_NOPRIV

~ The file protection mask specified when the global section was
the access or the type of access requested by
created prohibits
|
the caller.
A page in the input address range is in the system address space.

SS$_NOSUCHSEC

Warning.

The specified global section does not exist.

SS$_PAGOWNVIO

A page in the specified input address range is owned

privileged access mode.

SS$

VASFULL

1is
no space
1s full;
~ The process's virtual address space
the
contailn
to
created
pages
the
for
tables
page
the
available in
mapped global

section.

Privilege Restrictions:

The privilege to map a global section,

and

whether

may

mapped read/write or read-only, is determined by the protection
mask assigned to the global section when it was created.
Resources Required/Returned:

The

process's

be
must
(WSQUOTA)
set limit gquota
accommodate the 1increased size of the virtual

working

sufficient

file quota

(PGFLQUOTA).

If the section pages are
address space when mapping a section.
have sufficient paging
also
must
process
the
copy-on-reference,

Notes:

When the SMGBLSC system service maps
the Create Virtual Address
calls

1t
a global section,
(SCRETVA) system
Space

service to add the pages specified by the INADR
the process's virtual

address space.

'If the global section is of an unknown size,

argument

the process

can

obtain the virtual address of the first available page in the
Job/Process
Get
the
from
region
program or control

use the address
and
system service
(SGETJPI)
Information
The ending address may be
returned as the starting address.
address (if the section is to be mapped in the
a very high
the
in
(if mapped
a very low address
program region) or
system service returns the
SCRMPSC
The
control region).
RETADR
the
<created 1in
pages
the
of
virtual addresses
The section is mapped from a low
specified.
if
argument,

address to a high address, regardless of whether the

section

global

section,

is mapped in the program or control region.

If an error occurs during the mapping of
the

return

address array, if specified,

indicates the pages

If no
that were successfully mapped when the error occurred.
array
address
return
the
of
longwords
both
mapped,
were
pages
contain -1.

For an example of the SMGBLSC system service, and additional details
on global section creation and use, see Section 3.8.6, "Sections."

4-113

SYSTEM SERVICE DESCRIPTIONS

J/,

SNUMTIM
4.48

SNUMTIM - CONVERT BINARY TIME TO NUMERIC TIME

The Convert Binary Time to Numeric Time
system
service
converts
an
absolute
or
delta
time
from
64-bit
system
time format to binary
integer date and time
values.
The
numeric
time
1is
placed
in
a

user—-specified

buffer

illustrated

Figure

4-1.

16 15

month of year

year since O

hour of da;/

day of month

second of minute

minute of hour

hundrédths of second

Figure 4-1
Macro

Format of Numeric Time Buffer

Format:

SNUMTIM

timbuf

,[timadr]

High—Levei Language Format:
SYSSNUMTIM (timbuf

timbuf
address

, [timadr])

7-word

information.

buffer

receive

the

date

and

time

timadr
address

64-bit

time

value

specified, or specified as 0, the
positive time value represents an
value indicates a delta time.

Return

converted.

current system
absolute time.

not

time is used.
A
A negative time
|

Status:

SS$_NORMAL
Service

|
successfully

SS$_ACCVIO
The

64-bit

specified

|
time

value

cannot

SS$_IVTIME
The

completed.

specified

cannot
written,

|
delta

be read,
or
by the caller.

the

numeric

|
time

equal

4-114

buffer

greater

than

10,000

days.

SYSTEM SERVICE DESCRIPTIONS
SNUMTIM - CONVERT BINARY TIME TO NUMERIC TIME
Note:

If a delta time is specified, the year and month fields of the
The day field contains the
information returned are zero.
1t must be
integer number of days specified by the delta time;
|

less than 10,000 days.

4-115

SYSTEM

SERVICE

DESCRIPTIONS

OUTPUT

REQUEST AND WAIT

4.49

$SOUTPUT

QUEUE

[

‘

$SOUTPUT
FOR EVENT

FLAG

The $OUTPUT macro is a simplified form of the Queue
I/0
Request
and
Wait
for
Event
Flag
($QIOW) system service.
This macro performs a
virtual output operation using the
IO0$ WRITEVBLK
function
code
and

waits

for

I/0O

Macro

Format:

completion.

SOUTPUT

chan

,length

,buffer

,[iosb]

,[efn]

chan

number
of
1s

the

I/O0

channel

assigned

the

device

which

output

written.

length
length

the

output

buffer.

buffer
address

the

address

quadword

output

buffer.

iosb

|
I/O

status

efn

block.

|
number

the

event

The

default

The

S$OUTPUT macro

flag

event

flag

set when

the

request

complete.

Note:

for
macro

Return

the

$name_S

only one
form,

form.

but

" S"

Arguments must

must

not

coded

included

call.

Status,

Additional

has
macro

the
-

Privilege

Restrictions,

Resources

Required/Returned,

Notes:

See the description
service

for

the

Queue

details.

4-116

I/O

Request

(SQIO)

system

SYSTEM SERVICE DESCRIPTIONS

SPURGWS
4.50

SPURGWS

The P urge
from

its

- PURGE WORKING SET

s remove pages
Working Set system service enables a procesto

current working set to reduce the amount of physical memory

occupied by the current image.
Format:

Macro

SPURGWS

High- Level

1nadr

Language

Format:

SYSSPURGWS (inadr)

e’

‘inadr

s a 2-longword array containing the starting and ending
addresof
virtual addresses of the pages to be potentially purged from the
‘working set. The SPURGWS system services locates pages within
this range that are in the current working set and removes them.
If the starting and ending virtual addresses are the

same,

only

used;

the

that

single

te purging.
1s a candidafor

page

page number portion

low—-order 9 bits are

Return

the

ignored.

virtual

addresses

Only the virtual

Status:

SS$_NORMAL

Service successfully completed.

SS$_ACCVIO

The input address array cannot be read by the caller.

Note:

a range
of pages from 0 through 7FFFFFFF. The image continues executing,
and pages that are needed are brought back into the working set

To purge the entire working set, the caller can specify
|

as the page faults occur.

4-117

SYSTEM

SERVICE

DESCRIPTIONS

\\\,,.-4/

$SPUTMSG
$SPUTMSG- PUT MESSAGE

4.51

The

Put Message system
output routine used by

service 1s a generalized message formatting
the operating system to write 1nformatlonal

error

messages to

processes.

Macro

Format:

$PUTMSG

High- Level

user

msgvec

Language

,[actrtn]

and
and

,[facnam]

Format:

SYSSPUTMSG (msgvec

,[actrtn]

,[facnam])

msgvec

address

message

identifications
associated with
vector

argument

of messages
each message,

described

vector

to
be
if any.

Section

4.51.1,

that

lists

the

message

output
and
FAO arguments
The format of the message
below.

actrtn

address

the

entry

receive
control
receives control
actually

written

specified

action

mask

during
after a
to

(the

user-specified

message processing.
message is formatted

the

wuser.

default),

action

The
but

address

indicates

routine

action
before

that

routine
it
1is

specified,

there

1is

routine.

facnam
address
name

a
be

character
wused

string
the

descriptor
first

pointing
only

message

the

facility

formatted

SPUTMSG.

If not specified,'the default facility name associated
~message

Return

used

1in

the

with

the

first message.

Status:

SS$_NORMAL
Service

successfully

completed.

Note:

The $PUTMSG system service disables
executing

prevent

recursive

AST

entry.

4-118

delivery

while

1is

SYSTEM

SERVICE

DESCRIPTIONS

SPUTMSG - PUT MESSAGE

Format

the

Message Argument Vector

4.51.1

- The

general

Messages
(RMS

format

.with

status

a message

facility

codes)

vary

argument

codes of
from

the

basic

vector

either 0

1is

shown

(system status

below.

codes)

format.

16 15

message flags

argument count

first message identification

message flags

FAQO count

FAQO arguments
-1

next message identification

argument

count

"—

specifies

the

total

number

longwords

the

message

vector.

message flags
specifies a mask defining the portions of the
message(s)
to
be
requested
from
the
S§$GETMSG
system service.
If not specified,
SPUTMSG calls S$GETMSG requesting that all fields in
the
message
text
be
returned.
If
a
mask
1s
specified, it is passed to
SGETMSG
as the FLAGS argument.
The bits in the
mask
and
their
meanings

are:

Bit

Value

|
=

Meaning
-

Include

0
1

3
|

not

Include

not

Include

not

Include

not

must

for
FAO

system

return

status

message

identifier
identifier

level

indicator

severity

facility

message

severity

include

first message identification
32-bit numeric value that
message.
Messages
can

message

text

message

include

Bits
4 through

text

include

level

indicator

name

facility

name

zeros.

uniquely

identifies the first, or only,
symbolic names defined

be identified by
codes, RMS status

codes,

count

on.

number
vector.

FAO arguments,
The

identifiers
system)

has

and

FAO

which

(RMS).

associated

any,

argument

for

specified
as
'in the message

FAO

the

count

facility

1If

the

code

the

message

4-119

1is

message

arguments,

0, unless
vector.

that

with

FAO

required

1is
any

other

argument

all

than

other

identifier

the

for

message
message

facility

count

the

must

final

(the
code

item

SYSTEM

SERVICE DESCRIPTIONS

SPUTMSG flags

new

mask

for

subsequent

the

FAO arguments...
FAO

S$GETMSG

flags,

defining a new

default

for

all

messages.

arguments

required

TM e

message

PUT MESSAGE

the

message.

next message

identification...
|
identification of next associated message, if messages are linked
1n
a series.
S$SPUTMSG returns the first message with the percent

sign

(%)

after

prefix

the

in front of

first

message

the message.

series

By convention,

are

prefixed

with

messages

a hyphen

.
(=)
Message identifications for
system status codes,
system
exception
condition values, and RMS status codes are handled as follows:
1.

the status code
facility
code
of

a system message
0), neither an FAO

(that
1is,
it
argument count

arguments can
be
specified.
Each
1longword
(following the first message identification)
is
additional message identification.

If the message
number
(for
message must
the
message
arguments

identification is a system

the

message

1in
the
treated

exception

example, SS$_COMPAT), the FAO
immediately follow the message
vector.
SPUTMSG
determines

from

has
a
nor FAO

1list
as an

message

arguments for the
identification in
the count of FAO

number.

Note

that the format of the message argument
vector
for
an
exception
condition
status
code is identical to the signal
array argument list passed to a condition
handler
when
the

system signals
If
it

an exception

condition.

the message identification is an
has
a
facility
code
of
1),

longword

following

argument

count.

the

This

status

longword

RMS
you

code

status code (that 1is,
must specify a second

1in

place

is reserved

for

the

an RMS

FAO

status

value (STV) for those RMS messages that
have
status
wvalues
associated
with
them.
If the status code has no STV value
associated with it, SPUTMSG
1ignores
the
second
1longword.
SPUTMSG
uses
the STV value as an FAO argument or as another

1ldentification,
humber.

depending

the

value-

No FAO arguments can be specified for RMS status
specified,
identifiers.

$PUTMSG

The following example shows
SPUTMSG to output:

complete message
ABORT

argument

associated

with

codes.

additional

vector

the
|

RMS

that

message

requests
|

system

status
|

code

The complete message associated with the system

Status

code

RMS$ _FNF

LLONG

+LONG
LONG

SG$_ARORT
RMS$.FNF

YARGUMENT

yARORT MESSAGE
sFILE NOT FOUND

COUNT

+LONG

y [GNORET

MESSAGE
—y

VECTOR?

)

The
SSS

a message

them

the

$FUTMOG..8

MOHGVEC=VECTOR

4-120

treats
|

message
message

SYSTEM SERVICE DESCRIPTIONS
SPUTMSG - PUT MESSAGE

When this message vector has been processed,
the
following
messages
are
written to the current SYS$OUTPUT device (and to SYSSERROR, if it

is different):

ASYSTEM-F~-ARORTy
~RHS~E*FNF: file

4.51.2

abort
mot found

Using the $PUTMSG System Service

SPUTMSG retrieves a message from the system message
file
by
calling
the
Get
Message
(SGETMSG) system service and formats the message by
calling
the
Formatted
ASCII
Output (SFAO)
system service,
if

necessary.
If
the
«caller
specifies
an
action routine to receive
control, the action routine
1is
<called
before
S$SPUTMSG
writes
each
formatted
message
to
the
process's
current output device.
If the
process's error device is different than the
output
device,
S$PUTMSG
writes

the message

4.51.2.1

the

error

SGETMSG Processing

device

- The

as well.

SGETMSG

system

service

returns

message
string
based
on the numeric status code value passed to it.
The content of the string returned
depends
on
the
flags,
1if
any,
specified
in
the
message argument vector.
You can request that the
message include or not include
the
facility
name,
severity
level,
message
code, or text.
The following example shows a message vector
that requests only the text portion of the message associated with the
|
system status code SS$_DUPLNAM:

VECTOR:

WORD
1
JWORD

"ROOOI

JLONG

8S8%_DUPLNAM

If this message vector is specified for a

outputs

the message:

durlicate

Frocess

call

$PUTMSG,

$SPUTMSG

name

SGETMSG uses the facility code in the message identification to obtain
the
facility name
string
to
1insert
1in
a message.
Each system
component has a unique code.
The facility code is contained 1in
Dbits
16
through 27 of the message identification.
For example,
the system
has facility code of 0, the command interpreter is .1, the debugger
1is
2,

and

on.

You can override the fac111ty name
to $PUTMSG
For example:

FAC:

DESCRIFTOR <HELLO:

VECTOR?

LONG

+LONG

specifying

the

FACNAM

1
SOHS.NOFRIV

SFUTMSG..S HSGUEC%VECTDRvFfiCNfiM%FfiC
This call

SPUTMSG

results

the message:

ZHELLU*F*NOPRIU: ro erivilede for attemeted oreration

4-121

argument

SYSTEM SERVICE DESCRIPTIONS
$SPUTMSG - PUT MESSAGE

You can modify a facility code
in
a
message
calling SPUTMSG by changing bits 16 through 27.
status code can be specified as follows:
JLONG

1identification
before
For example, a system
»
|

JZR14615S5%. code

In this example, the facility number 2
1is
1inserted
1in
the
message
identification.
You
<can
override the facility name string DEBUG in
the message by specifying message flags
1in
the
argument
vector
to
suppress
the
facility
name,
or
you can use the FACNAM argument to

SPUTMSG

specify an alternate

facility name.

This technique allows you to use shared system message codes that have
associated
the

FAO

message

When

arguments.

you

modify

the

facility

cannot

specify

FAO

arguments.

contains

identifications,
you

a message

identification

SGETMSG

places

message

string.

the

string

NONAME

not

place

unknown

the

number
in
|

facility

name

code,
in

the

4.51.2.2 S$FAO Processing
- If the string returned by S$GETMSG contains
any
FAO directives,
and
1f the facility code is other than
0 or 1,
$PUTMSG calls the SFAO system service to format the message.
$PUTMSG

calls

SFAO

with

message

argument

The FAO
message

argument

the

argument

count, 1f any,
that defines the

file

count

and arguments

specified

for a
message
message text.

1s
The

associated

the

1indicated
in
the
message text itself

contains embedded FAO directives.
You can examine the message
determine
the
arguments
required
by FAO.
For example, the

text

vector.

with

the

system

status

code

SHRS BEGIN

text to
message

defined

as:

IAS beéinning
requires
the
address
of
a
character
string descriptor
to “the text to be substituted in place of the FAO directive
(For details on how to use FAO, and how to specify arguments for
FAO directives, see the description of the $FAO system service.)

code.

The

argument

status

following

count

code

and

output a system
shared message
that
with it, you must change the facility

example shows

argument,

message

output

the

vector,

message

including

associated

the

FAO

with

the

SHR$ BEGIN.

VECTOR:

WORD

LWORD
+LONG

NAME. $

TRO0OL
20161
SHR$ BEGIN

LONG

«LONG

NAME

LESCRIFTOR

<FUTMSG

s MESSAGE

FIL.AGS

sMESSAGE

TDENTIFICATION

FFAD

ARGUMENT

yFAQ

ARGUMENT

COUNT

tests:

When $PUTMSG is called with this message vector, it displays the line:
FUTMS0G

Note

that

allow

flags in
facility

tests

the

besinming

facility

code

1in

specification

the message

identification

of FAO arguments;

and

the second word of the
vector
suppresses
name, severity level, and message code.

4-122

that
the

modified

the message
printing

To use S$SPUTMSG to access and/or
has
FAO
arguments
associated

———

IAS.

other

This text
pointing

SYSTEM SERVICE DESCRIPTIONS
SPUTMSG - PUT MESSAGE

4.51.2.3 The Action Routine - The action routine, if any, 1s called
as a normal procedure each time a message is formatted, but before it
is actually output. The action routine receives as an argument the
address of a character string descriptor pointing to the formatted
message. The action routine can access the message text, scan it,
file or device, modify it, and so on.
write it to a user-specified
On return from the action routine, $PUTMSG examines the completion
code from the routine specified in Register 0. If the completion code
indicates success (any odd numeric value), $PUTMSG outputs the message
to the current output and error devices. If the completion code
indicates non-success (any even numeric value), SPUTMSG does not
|
output the message.

4-123

SYSTEM

SERVICE

DESCRIPTIONS

$Qlo
4.52

$QIO
- QUEUE I/0 REQUEST

The Queue

I/O Request

operation
by

specific

which

device.

can
1.

system service

queueing

Control

synchronize

returns

I/O

the

completes.

address

Walt for

Poll the specified

The

event

the

I/0

flag

and

request

specified

I/0

event

status

block,

,chan

,func

,[iosb]

,[Pl] I[Pz]

r[p3]

:[P4]

issuing

process

three

output
a

ways:
is

execute

when

set.

for a completion status.

specified,

are

cleared

before

|
,[astadr]

r[pS]

,[astprm]

I[P6]

SYSSQIO([efn]

,chan

,func

,[iosb].,[astadr]

» [P1]

,[p2]

,[p3]

,I[p4]

event

flag

number
If not

the

specified,

number

channel

, [astprm]

,I[p5]

,I[p6l)
set

that

defaults

A
completion.

request

chan
request

the

I/0

function

assigned

directed.

func

performed.

The

the

device

which

the

|
and modifier

code

1is

bits

that

specify

expressed

the

operation

symbolically.

For

reference

codes are listed in Appendix A. Complete
function
the valid
fi%fim’f- purposes,
éx}{
details
on
1I/0 function codes and parameters required by
.

each

iosb

are

address

documented

a quadword

completion

the

VAX/VMS

I/0O

User's

Guide.

I/O status

status.

block

that

astadr

receive

final

address

executed
executes

the

entry

when

the

mask

I/O

access

of
an
completes.

mode

requested.

from

AST
service
1If specified,
which

the

routine
the AST

$QIO

parameter

passed

the

4-124

AST

service

to
be
routine

service

astprm

AST

)

Language Format:

efn

with

the

routine that

input

associated

$QIO0

I/0 status block

queued.

channel

one

flag

High-Level

AST

Macro Format:
[efn]

immediately

completion

Specify

I/0

initiates

request

routine.

was

)

SYSTEM SERVICE DESCRIPTIONS
$QIO - QUEUE I/0 REQUEST

to pob

optional device- and function-specific I/0 request parameters.

depending on
The first parameter may be specified as Pl or P1lV,
a value,
whether the function <code requires an address or
the default,
is
Pl
If the keyword is not used,
respectively.
that is,

the argument is considered an address.

P2 through Pn are always interpreted as values.
Return

Status:

SS$_ NORMAL

completed.

Service successfully

‘successfully queued.
SS$_ABORT

A network logical

packet

was

parameters

for

regquest

I/0

The

link was broken.

SS$_ACCVIO

The I/0 status block cannot be written by the caller.

This

also

may

code

status

returned

device-dependent function codes are incorrectly specified.
%

SSS EXQUOTA

~ The process has exceeded 1its buffered I/O quota, direct I/0
quota, or buffered I/0 byte count quota and has disabled resource

system
($SETRWM)
wait mode with the Set Resource Wait Mode
service. Or, the process has exceeded its AST limit quota.
|

SS$_ILLEFC

An illegal event flag number was specified.
»

SS$_INSFMEM

the
complete
service and the process has disabled resource wait mode with the
- Set Resource Wait Mode (SSETRWM) system service.
Insufficient system dynamic memory is available to

SS$ IVCHAN

a channel
that 1is,
= An invalid channel number was specified,
number of 0 or a number larger than the number of channels
|
|
|
|
available.
-

SS$_NOPRIV

a more
l does not exist, or was assignT ed from
T
~ The specified channe
mode.
privileged access

SS$

UNASEFC

~ The process is not associated with
specified event flag.

the

cluster

containing
|

the

Privilege Restrictions:

The Queue I/O Request system service can be performed only on
assigned I/0 channels and only from access modes that are equal
to or more privileged than the access mode from which the
original channel assignment was made.

4-125

SYSTEM SERVICE DESCRIPTIONS
$QIO - QUEUE I/O REQUEST
Resources
1.

Required/Returned:

Queued

I/O

(BIOLM)

requests

byte count
specified,
System

use

direct

the

1I/0

process's

(DIOLM);

(BYTLM) quota;
and, if
the process's AST limit

dynamic

memory

1is

required

without

queuing an

I/O

is set

request.

for

buffered

process's

construct

memory may

the

I/0

buffered

I/0

routine

an AST service
quota (ASTLM).

queue
the I/0O request.
Additional
a device-dependent basis.

The specified event flag

quota

the

data

base

required

service

terminates

The I/0 status'block has the format:
31

16 15

count

0
status

device-dependent information

status

is
byte

the completion

count
is the

number

status

bytes

the

I/O

actually

request.

transferred.

device and function dependent information
varies according
to
the
device
and
performed.
The information
function code is documented

Guide.

Many

services

length

return

the

data

Function

codes

argument

specifications
services
are
requests,

for

character

string

returned

the

system

$QIO

word

the

$SOUTPUT

system

in
to

longwords.
be
used

If
as

longword

should

data and
provided

service
service)

write

caller.

the

LENGTH

require

length

(and

lengths
returned
input
parameters

reserved

the

ensure

by
for

other
$QIO

that

4. For information on performing input and output operations

error

For

operation
being
returned for each device and
in the VAX/VMS
1I/0
User's

occurs

network,

when

see

the

$QIO

reads

DECnet-VAX

examples

the

length.

User's

Guide.

of the $QIO system service, including the
use
of
event
service routines, and an I/O status block, see Section 3.4,
"Input/Output Services."
.

flags,

AST

4-126

SYSTEM SERVICE DESCRIPTIONS

4.53
The

SQIOW - QUEUE I/O REQUEST AND WAIT FOR EVENT FLAG
Queue

the $QIO
can

Macro

I/0

and

used

Request

SWAITFR
when

and

Wait

(Wait

for

Event

Single

program must

Flag

Event

wait for

system

Flag)

I/0O

High-Level

,[p2]

Language

,[p3]

,[p4)

,[p5]

SYSSQIOW([efn]

,chan ,func

,[iosb]

I[Pl]

r[pz] :[P3]

r[P4]

number

specified,

not

the

,[p6]

Format:

,[astadr]

r[pS]

~
event

;[astprm]

r[p6])

|
flag

that

defaults

set

chan
number of the I/0 channel
request is directed.

a551gned
.

the

request

‘
|
device

completion.

which

the

function code and modifier bits that'specify the operation to
performed.

completion.

[efn] ,chan ,func ,[ioSb] ,[astadr]‘,[astprm]

lpll

efn

combines.

services.

Format:

SQIOW

func

service

system

The

code

expressed

symbolically.

iosb

,
address

quadword

I/0

status

mask

block

that

receive

final

completion status.
astadr
address of the
executed
when
executes

the

|
entry

the

I/O

access

an
AST
service
completes. 1If specified,

mode

from

which

the

routine
the AST

SQIO

to
be
routine

service

was

requested.
astprm

AST

parameter
to be passed

the AST

completion

routine.

to pb6

optional device- and function- spec1f1c I/O request parameters.

Return Status, Privilege

‘Notes:

the

description

the

Resourcéé“”Required/Returned,

$QIO system

See

Restrictions,

4-127

service for

details.

SYSTEM

SERVICE DESCRIPTIONS

SREADEF
4.54

SREADEF

READ EVENT

The

Read

Event

Flags

event

flags

Macro

system service returns
local

common

the

current

status

cluster.

event

flag

the

cluster

all

flag

Format:

SREADEF
High-Level

efn ,state

Language

Format:

SYSSREADEF
(efn

,state)

efn

FLAGS

number
number

|
of
of

specifies

any
0

event

flag

through

cluster

within
31

and

specifies

cluster

read.

through

status

all

forth.

state.

address of a
flags in the

longword
cluster.

receive

the

current

event

Refurn Status:
|

SS$_WASCLR

Service

successfully

completed.

The

completed.

The

specified

event

flag

1is

clear.

SS$_WASSET

Service successfully

SS$ _ACCVIO
The longword
flags in the

SS$_ILLEFC
~An

event

flag

set.

that is
cluster

to receive the current state
of
cannot be written by the caller.

all

event

illegal

event

SSS_UNASEFC
The process

flag

number

was

is not associated
event flag.

specified.

with

specified

4-128

the

<cluster

containing

the

SYSTEM SERVICE DESCRIPTIONS

$RESUME
SRESUME - RESUME PROCESS

4.55

The Resume Process system service causes a process previously
suspended by the Suspend Process ($SUSPND) system service to resume
execution, or cancels the effect of a subsequent suspend request.
Format:

Macro

[pidadr]

SRESUME

High-Level

Language

, [prcnam]

Format:

SYSSRESUME([pidadr] , [prcnam])
pidadr

address of a longword contalnlng the
the process

to be

process

identification

resumed.

prcnam

to
1the
address of a character string descriptor pointing to
The process name is implicitly
15-character process name string.
resume
the
qualified by the group number of the process issuing

request.

If nelther a process identification nor a process name 1is specified,
the resume request is for the caller. For details on how the service
interprets the PIDADR and PRCNAM arguments, see Table 3-3. Table 3-3
is in Section 3.5,

"Process Control Services."

Return Status:
SS$_NORMAL

Service successfully completed.
|

SS$_ACCVIO

read,
The process name string or string descriptor cannot be
the process identification cannot be written, by the caller.

SS$ _IVLOGNAM

The specified process name has a length of 0, or has more than 15
.

characters.

SS$_NONEXPR

Warning.

The specified process does not

process identification was specified.

SS$NOPRIV

exist,

The process does not have the privilege to resume

- of

the

specified process.

4-129

the

an
|

invalid

execution

SYSTEM SERVICE DESCRIPTIONS
$RESUME - RESUME PROCESS

.Privilege Restrictions:
privileges

are

processes

required

)

Other

Any other process

If one or more resume
not
suspended,
a

the
in

same

the

resume

execution

group

(GROUP privilege)

system

requests are
subsequent

(WORLD

of:

privilege)

issued for
suspend

a process
request

immediately, that is, the process is not suspended.
maintained of outstanding resume requests.
see

Section

No count

3.5.5,

"Process

suspension

that
1is
completes

\.\

For more information on process
Hibernation and Suspension."

e’

User

4-130

SYSTEM SERVICE DESCRIPTIONS

$SCHDWK
S$SCHDWK - SCHEDULE WAKEUP

4,56

a
The Schedule Wakeup system service schedules the awakening of
1in a state of hibernation with the
itself
that has placed
process
a
for
A wakeup can be scheduled
Hibernate (SHIBER) system service.
Optionally, the request
specified absolute time or for a delta time.
can specify that the wakeup is to be repeated at fixed intervals.
Format:

Macro

[pidadr]

$SCHDWK
High-Level

Language

, [prcnam]

,daytim

, [reptim]

Format:

"SYSSSCHDWK ( [pidadr] ,[prcnam] ydaytim ,[reptim])
pidadr

address of a longword containing the
the process

to be

process

1identification
|

awakened.

prcnam

1- to
address of a character string descriptor pointing to the
15-character process name string. The process name is implicitly
qualified by the group number of the process issuing the schedule

wakeup

request.

daytim

the
1in
time
expiration
the
containing
address of a quadword
A positive time value indicates an
format.
time
64-bit
system
awakened.
absolute time at which the specified process is to be
time value indicates an offset (delta time) from the
negative
A
current

time.

reptim

1in
address of a quadword containing the time interval (expressed
1If not
delta time format) at which to repeat the wakeup request.
1is
specified, it defaults to 0, which indicates that the request
not to

‘

repeated.

specified,
1is
If neither a process 1dent1f1cat10n nor a process name
For detalils on how
scheduled wakeup request is for the caller.
the
the service interprets the PIDADR and PRCNAM arguments, see Table 3-3.

Table 3-3 is in Section 3.5, "Process Control Services."
Return_Status:

SSS_NORMAL

Serv1ce

successfully completed
|

SS$_ACCVIO

string
or
The expiration tlme, repeat time, process name string
or the process identification cannot
cannot be read;
descriptor
be written,

~—

SSS

EXQUOTA

the

caller.

The process has exceeded

its AST limit quota.

4-131

SYSTEM SERVICE DESCRIPTIONS
SSCHDWK

SS$

SCHEDULE WAKEUP

INSFMEM

" Insufficient system dynamic memory is

available

to allocate. a

timer queue entry and the process has-disabled resource wait mode
with the Set Resource Wait Mode ($SETRWM) system service.

SS$_IVLOGNAM
The process
characters.
SS$
-

name

time or
current

has a

length

of 0

has

than

|
was

IVTIME
The specified
equal

string

delta

greater

absolute
time.

repeat
than

time

10,000

plus

was

days.

delta

positive
Or,

repeat

time

SS$ _NONEXPR
Warning.
The specified process does not
process identification was specified.

value,

absolute

1is

exist,

expiration

less

than

the

|
invalid
|

SS$_NOPRIV
The

process
request for

Privilege

does

the

not have
specified

the
pr1v1lege
process.

schedule

wakeup

Restrictions:

User

privileges

are

required

schedule

wakeup

requests

)

Other processes
in the same group (GROUP privilege)

Any other process in the system (WORLD privilege)

Resources

for:

Required/Returned:

scheduled wakeup request uses
the
<caller's
AST
1limit
(ASTLM)
and
requlres
system dynamic memory to allocate
a

queue

entry.

gquota

timer

Notes:

If one or more scheduled wakeup requests
are
issued
for
a
process
that 1s
not
hibernating,
a
subsequent hibernate
request by the target process completes immediately, that is,
the process
does
not hibernate.
No count is maintained of

outstanding
2.

wakeup

requests.

Scheduled

wakeup

requests

can
be
service.

canceled

with

that

the

|
have

Cancel

not

yet

Wakeup
|

For an example of the $SCHDWK system service, and
how
to
format
a
system
time
value for input

been

system

for
information
to this service,

Section
3.6,
"Timer
and
Time
Conversion
Services."
‘information
on .process
hibernation
and
waking,
see
"Process Control Services."

- 4-132

processed

(SCANWAK)

on
see

For
more
Section 3.5,

SYSTEM SERVICE DESCRIPTIONS

$SETAST
SSETAST - SET AST ENABLE

4.57

The Set AST Enable system service enables or disables the delivery

ASTs for the access mode from which the service call was issued.
~

Format:

Macro

SSETAST

enbflg

High-Level Language Format:
SYSSSETAST (enbflg)
enbflg

the

AST enable indicator. A value of 1 enables AST delivery for
calling access mode.

Return

A value of 0 disables AST delivery.

Status:

SS$_WASCLR

Service successfully completed.

AST delivery was previdusly‘

disabled for the calling access mode.
SS$_WASSET

Service successfully
enabled

for

completed.

AST

the calling access mode.

delivery

was

previously
4

Notes:

mode,

the

system

.keeps

When an image 1s executing in user

If an AST is queued for an access mode that has disabled AST
system cannot deliver ASTs to less privileged
delivery, the
access modes until the access mode reenables AST delivery.

If a higher access
ASTs enabled for all higher access modes.
1its
mode disables AST delivery, it should reenable ASTs for
own access mode before returning to a lower access mode.

of
wusage
the
delivery and
For additional notes on AST
Section 3.2, "Asynchronous System Trap (AST) Services."

4-133

ASTs,

see

SYSTEM SERVICE DESCRIPTIONS

$SETEF
4.58
The

$SETEF
Set

Event

common
flag

SET EVENT FLAG
Flag system service
flag cluster to 1.

event

are

Macro

made

sets
Any

an event flag
in
processes waiting

a
for

local
or
the event

runnable.

Format:

SSETEF

efn

High-Level Language Format:
SYSSSETEF (efn)
efn

‘
number

- Return

the

event

flag

set.

Status:

SS$_WASCLR

Service successfully
previously O

SS$_WASSET
Service successfully
previously 1.
SS$ ILLEFC
An illegal
SS$

flag

The

specified

The

specified

flags

not

event

an example of

event

and

the

flag

was

event

flag

was

containing

the

|
was

number

specified.

‘

process

event
-

|
completed.

UNASEFC
The

For

event

completed.

associated

with

the

cluster

flag.

$SETEF

event

system service

flag

clusters,

Services."

4-134

and

see

Section

information
3.1,

"Event

on
Flag

SYSTEM SERVICE

DESCRIPTIONS

$SETEXV
S$SETEXV - SET EXCEPTION VECTOR

4.59

The Set Exception Vector system service assigns
cancels
or
vector
exception
an
to
address
assigned

vector.

condition handler
a
an address previously

Macro Format:
SSETEXV

High-Level

[vector]

Language

,[addres]

,[acmode]

,[prvhnd]

Format:

,[acmode]

,[addres]

SYSSSETEXV ([vector]

,[prvhnd])

vector

that the
indicates
default)
A value of 0 (the
vector number.
A value of 1 indicates the
be modified.
to
is
vector
primary
that
A value of 2 indicates
secondary vector is to be modified.
a last chance exception vector is to be modified.

addres

condition handler address.
If not specified, or specified as
O,
it
indicates
that
there
1s
no
condition handler or that the
vector is to be canceled.
If an address is specified, it 1is
the
address of the entry mask of the condition handler.
-

acmode

access mode for which the exception vector 1is
to
be
modified.
the caller is maximized with the specified
of
access mode
The
|
access mode to determine which vector to modify.

prvhnd

to receive the
address of a longword

vector.

Return

contents

the

contents

the

Status:

SS$ NORMAL
Service

successfully

completed.

SS$_ACCVIO

The longword that is to receive
vector

cannot
be written by

the

the caller.

Privilege Restrictions:

process

privileged

cannot

modify

access mode.

vector

4-135

associated

with

SYSTEM SERVICE DESCRIPTIONS
SSETEXV - SET EXCEPTION VECTOR

Exception handlers are normally
call

declared

the

procedure'

chance

éxception

stack.

The primary exception vector and the

1last

vector
are
used
by
the
system
debugger.
The
interpreter uses the last chance exception vector.

User mode exception vectors

Condition handling, and

are described

conventions

4-136

canceled

for

in Section 3.7,

routines,

are

coding

image

command

exit.

condition

handling

"Condition Handling Services."

SYSTEM SERVICE

DESCRIPTIONS

$SETIMR
4.60

SSETIMR - SET TIMER

The Set Timer system service allows a process to schedule
the
setting
of
an
event
flag
and/or the queuing of an AST at some future time.
The

time

for

delta

time.

Macro

Format:

the event can be

$SSETIMR

High-Level

[efn]

,daytim

Language

Format:

specified as an absolute

,[astadr]

a
'

,[reqgidt]

SYSSSETIMR([efn]',daytim , [astadr]
efn

time

,[reqidt])

" event flag number of the event flag to set when the time interval
expires.

If not specified,

daytim

it defaults

address of the quadword expiration time.
A positive
time
value
indicates
an
absolute
time at which the timer is to expire.
A
negative time value indicates
an offset
(delta time)
from
the
current time.
|
|
)

astadr

called
of the entry mask of an AST service routine to be
address
when the time interval expires.
If not specified, 1t defaults to
0,

indicating

no AST is

be queued.

reqidt

number indicating a request identification.
If not specified, 1t
defaults to 0.
A unique request identification can be specified
in each set timer request;
or the
same
1identification
can
be
given
to.related timer requests.
The identification can be used
later
to cancel the timer request(s).
If an AST service
routine
is

Return

specified,

the. identification

is passed
as

the AST parameter.

Status:

SS$_NORMAL

Service
SS$

ACCVIO

successfully

- The expiration time

completed.
.

cannot be

read by

the

caller.

SS$_EXQUOTA

The process exceeded its quota for timer entries or its AST limit
quota.
Or,
there
1is
insufficient
system
dynamic
memory to
complete the request and the process has disabled
resource
wait
mode with the Set Resource Wait Mode (SSETRWM) system service.,

SS$ _ILLEFC

An illegal event flag number was specified.

4-137

SYSTEM SERVICE DESCRIPTIONS
SSETIMR

SSS

INSFMEM

‘

~ Insufficient dynamic memory

SET

timer

SS$ _IVTIME
|
.
The specified absolute expiration time has already passed,

or was

gqueue

entry and

available

(SSETRWM)

The process is not associated with

Resources

1.
2.

event

system service.

the

cluster

containing

the

flag.

Reqguired/Returned:

The Set Timer system service requlres dynamic Memory.
The Set Timer

system

timer gqueue entries

specified,

allocate

resource wait mode with

SS$_UNASEFC

specified

the process has disabled

the Set Resource Wait Mode

specified

TIMER

service

(TQELM)

the process's AST

The access mode of

the caller

request

AST.

and
of the

uses

and,

the

limit quota

1is

process's

if an AST service

the

(ASTLM).

access

quota

routine

mode

for

1is

the

The Convert ASCII String
to
Binary
Time
($SBINTIM)
system
service converts
a
specified
ASCII string to the gquadword
time format required as input to the SSETIMR service.

For examples of the $SETIMR system service, see

Section

3.6,

"Timer

and
Time
Conversion
Services."
For
an
example
of an AST service
routine, see Section 3.2, "AST (Asynchronous System Trap) Services."

4-138

SYSTEM SERVICE DESCRIPTIONS

4.61

SSETPRA - SET POWER RECOVERY AST

The Set Power Recovery AST system service establishes a routine to
receive control wusing the AST mechanism after a power recovery 1s
detected.

Format:

Macro

SSETPRA

astadr

, [acmode]

High-Level Language Format:

SYSSSETPRA (astadr

, [acmode])

R ——

astadr

An
address of the entry mask for a power recovery AST - routine.
for
ation
notific
AST
recovery
power
that
s
indicate
0
of
address
the process is disabled.

acmode

access mode at which the power recovery AST routine 1is to
The specified access mode is maximized with the access
execute.

mode of the caller to determine the access mode to use.
Return Status:
|

SS$_NORMAL

Service successfully completed.
|

SS$_EXQUOTA

AST reqguests.
its quota for outstanding
The process exceeded

Resources Required/Returned:

1limit

quota

l. The AST parameter contains the amount of time that the

power

The SSETPRA system service uses the

process's

(ASTLM) .

AST

Notes:

was off,

in hundredths of seconds.

Only one power recovery AST routine can be specified for a
The AST entry point address is cleared at image
process.
exit. A power recovery AST routine is executed only once;
it must specifically re-establish itself to receive control
for multiple power recovery conditions.

The entry and exit conventions for the power recovery AST
routine are the same as for all AST service routines. These
1in Section 3.2, "Asynchronous
conventions are described
System Trap

(AST) Services."

4-139

SYSTEM

SERVICE

DESCRIPTIONS

$SETPRI
4.62
The

SSETPRI
Set

The

SET

Priority

system

scheduler

which

executable

Macro

Format:

SSETPRI
High-Level

PRIORITY
service

changes

uses

the

base

processes

are

[pidadr]

Language

,[prcnam]

a
process's
base prlorlty
priority to determine the order in

run.

yPri

, [prvpri]

Format:

SYSSSET
( [pidadr]
PRI

, [prcnam]

,pri

,[perri])

pidadr
address of
priority is

the

process

identification

the

set.

process

whose

prcnam

address of a character string descriptor
pointing
l15-character process name string.
The process name

qualified

priority
pri

|
new

number

the

process

a
1- to
implicitly

issuing

the

set

The

new

base

priority

priority
Normal

by the group
request.

contained

priorities

time-critical

are

priorities

established

bits

priority

priority
is used.

the

in the

value

for

through

are

If the specified priority is
and
1f
the caller does not

process's

the

process.

of
0

‘through

range

through

range

the

argument
15,

higher than the
caller s
have the privilege to set

higher

than

its

own,

and

31.
prlorlty,

the

the
.

target

caller's

prvpri

address

of a longword to
specified process.

the

receive

the

base

priority
.

If neither a process identification nor a process name
is
the
set
priority
request is for the caller.
For details
service

Table

interprets

3-3

1is in

the

PIDADR

Section

3.5,

and

PRCNAM

"Process

arguments,

Control

see

specified,
how the
Table
3-3.
on

Services."

Return Status:
SSb

SS$

NORMAL
Service

successfully

ACCVIO
The

the

completed

process

written,

name

strlng

or strlng descrlptor cannot be
read,
or
identification or previous priority longword cannot
by the caller.

4-140

SYSTEM SERVICE DESCRIPTIONS
SSETPRI

SET PRIORITY

|
SS$ IVLOGNAM
The process name string has a length of 0, or has
characters,

SS$_NONEXPR

Warning.

.
than 15
|

The specified process does not

was specified.
process identification

SS$_NOPRIV

The process does not have the

privilege

priority for the specified process..

exist,

set

the

invalid

specified

Privilege Restrictions:

’/’,

User privileges are required to:

the

same

group

Change the priority for other processes

em
,
| s in the syst
for any | other- proces
prio
thevil
ge pri
Chan
)
egerity
(WORLD

(GROUP privilege)

Set any process's priority toa value greater than one's
initial base priority (ALTPRI privilege)

own

Note:

s effect
A process's base priority remainin

changed or until the process is deleted.

4-141

until -specifically
_

SYSTEM SERVICE DESCRIPTIONS

$SETPRN
4.63 S$SETPRN - SET PROCESS NAME
-

The

Set Process Name system service
change its own process name.

Macro

allows

process

establish

Format:

SSETPRN
High-Level

[prcnam]

Language

Format:

SYSSSE
( [prcnam])
TPRN
prcnam

address

character

l5-character
qualified
or

Return

process

by the

specified

string

name

descriptor

string.

group
0,

number of
the process's

pointing

to
the
1to
process name is implicitly
caller.
If
not
specified,

The
the

current

name

deleted.

Status:

SS$_NORMAL
-

Service

successfully

completed.

SS$_ACCVIO
‘The
the

process name
caller.

string

|
cannot

descriptor

SS$_DUPLNAM
The

specified

within

that

process

name

group.

duplicates

one

already

read

|
specified

SS$_IVLOGNAM
The

specified
characters.

process

name

has

length

has

than

Notes:

A process name remains in effect until
or

until

the

Process

names

processes

can

also

process

provide

executing

deleted.

identified

with

identification
the

same

functions,

see

and

Section

system

3.5,

group

changed

mechanism
number.

for

Processes

process identifications.

For an example of the $SETPRN system serVice,
identification

specifically

services

"Process

Control

4-142

and details

process

process
Services."

control

providing

SYSTEM SERVICE DESCRIPTIONS

S$SETRWM - SET RESOURCE WAIT MODE

4.65

The Set Resource Wait Mode system service allows a process to indicate
what action a system service should take when it lacks a system
resource required for

its execution:

the
When resource wait mode is enabled (the default mode),
service waits until a resource 1is available and then resumes

execution.

returns
When resource wait mode is disabled, the service
code
status
a
immediately with
caller
the
to
control

is unavallable.
indicating that a resource

Format:

Macro

[watflg]

SSETRWM

High-Level Language

Format:

TRWM
( [watflg])
SYSSSE

watflg

indicates that
(the default)
0
A value of
wait indicator.
this is the initial setting for
resources are to be awaited;
A value of 1 indicates that failure status
resource wait mode.
should be returned

Return

immediately.

Status:

SS$_WASCLR

was

Resource

walt

mode

Resource

wailt

mode

was

quotas

are

If resource wait mode is disabled, it remains disabled

until

Service

successfully

completed.

previously enabled.
SS$_WASSET

Service

successfully

previously disabled.

completed.

Notes:

'2.

The

following

system

resources

affected by resource wait mode:

and

process

System dynamic memory

Direct I/0 quota

Buffered I/O quota (BIOLM)

Buffered I/0 byte count limit (BYTLM)”

(DIOLM)

it is explicitly reenabled or until the process is deleted.

4-145

SYSTEM

SERVICE

DESCRIPTIONS

$SETSFM
4.66
The

SSETSFM - SET SYSTEM SERVICE.FAILURE'EXCEPTION MODE
Set

whether

System

Service

= software

Failure

Exception

exception

error status code 1s returned from a
system
service failure
exceptions

explicitly
call.

test

for

successful

Mode

system

generated

when

system service
are disabled;

completion

service

controls

error

severe

call.
Initially,
the caller should

following

system

service

Macro_Format:

SSETSFM

High-Level

[enbflg]

Language

Format:

SYSSSETSFM([enbflg])
enbflg
|
enable indicator.
A value of 1
indicates
that
failure
exceptions
are
to
be
generated.
A
default) disables their generation.

Return

system
service
value of 0 (the

Status:

SS$_WASCLR

Service

successfully'

previously

disabled.

completed.

Failure

completed.

Failure

exceptions

were,

SS$ WASSET

Service

successfully

previously

enabled.

exceptions
-

were
|

Notes:

When enabled,
only

SSETSFM

system

access

mode.

mode remains
image exits.

can

enabled,

enabled

until

originated
be
called,
system

from

user mode.
however,
from

service

explicitly

failure

disabled

The

any

exception

until

the

failure exceptions are enabled, a condition handler can be
specified
in
the first longword of the procedure call stack
or with the Set Exception Vector
(SSETEXV)
system
service.
no

system

image

condition
handler

exit

handler

array.

specified

used.

This

and

then

displays

The argument list provided
code

For an
format

<call

service
service

SS$_SSFAIL

the

condition

the

condition

the

user,

handler

exit

default
the

status.

condition handler
name

causes

argument

has
the

the

signal
~

explanation and examples of condition
of
the
argument lists passed to the

handling
condition

handler

may

the
a

and

take,

“

discussion of the appropriate actions a condition
see Section 3.7, "Condition Handling Services."
=

routines,
handler,

/‘

2.,

system service failure exceptions_areVgenerated,

the

e’

4-146

SYSTEM SERVICE DESCRIPTIONS

$SETSWM
SSETSWM - SET PROCESS SWAP MODE

4.67

The Set Process Swap Mode system service allows a process to control
r can be swapped out of the balance set. Once a process 1is
whetheit
locked in the balance set, it cannot be swapped out of memory until it
,

is explicitly unlocked.
Format:

Macro

SSETSWM

[swpflg]

High-Level Language Format:
'SYSSSET
( [swpflgl)
SWM

swpflg

swap indicator. A value of 0 (the default) allows the process to
this is the initial setting for swap mode. A value
be swapped;

of 1 inhibits swapping.

Return

Status:

SS$_WASCLR

Service successfully completed.
locked

SS$S_WASSET

Service
locked

in the balance set.

The process was

not

previously

was

previously

successfully

in the balance
'

SS$_NOPRIV

completed.

set.

The

process

The process does not have the privilege to alter its swap mode.

Privilege Restrictions:

d alter process swap mode.
The user privilege PSWAPM is requireto
- Notes:

1.
2.

in the balance set it
If a process is locked

remains

locked

Specific'pages of a process's virtual address

space

can

until explicitly unlocked or until the process is deleted.

locked

(SLCKPAG)

the

balance

system service.

set

4-147

with

the Lock Pages in Memory

SYSTEM SERVICE DESCRIPTIONS

- $SNDACC
4.68

$SNDACC

The

Send

log

message

Macro

SEND MESSAGE

Message

accounting
data

Accounting

activity

into

the

TO ACCOUNTING MANAGER

and

Manager

allows

accounting

log

system

process

service

write

controls

arbitrary

file.

Format:

SSNDACC

msgbuf

, [chan]

High-Level Language Format:
SYS$SSNDACC (msgbuf
msgbuf
address

, [chan])

character

buffer.

The

types

described

number

the

string

descriptor

of message

Section

4.68.2,

pointing

and

the

mailbox

the

buffer

message

formats

are

receive

the

below.

chan
of

reply.

Return

(the

channel

assigned

channel

default),

number

to
is

indicates

specified,

that

specified

desired.

Status:

SS$_NORMAL
Service

|
|
successfully completed.

SS$_ACCVIO
The

message

buffer

descriptor

cannot

caller.

SS$

read

the

than

254

BADPARAM
The

specified message

has

length

not

has

mailbox.

characters.

SSS

DEVNOTMBX
The

channel

specified

SS$ _INSFMEM
Insufficient
service

Set

SSS

and

system
the

dynamlc

process

Resource Wait Mode

IVCHAN
An invalid
number
of
available.

assigned

memory

has disabled

(SSETRWM)

resource

wait

system

1
channel
0
'or

available

complete

the

mode

the

with

serv1ce.

number
was
specified,
a number
larger
than

that
1is,
the number

a
of

channel
channels

SS$_NOPRIV
The

caller

Privilege

does

not

have

write

access

the

spec1f1ed

mallbox.

Restrictions:

The

user

enable

privilege
or

OPER

disable

required

accounting.

4-148

create

new

log

file

$SNDACC

SYSTEM SERVICE DESCRIPTIONS
-

SEND MESSAGE

TO ACCOUNTING MANAGER

Resources Required/Returned:
- The Send Message to Accounting
system dynamiC memory.

Manager

system

service
,

requires

Note:

The'general»précedure for coding a call to this service
the

following

Construct the message
the first word of the

Call the $SNDACC systemvservice.

Check

the

"successful

4.68.1

1involves -

steps:

buffer
buffer

return status
completion.

and place its
descriptor.

code

from

the

final
|

service

length
|

1in

ensure

Issue a read request to the mailbox specified, if any.
When
the read completes, check that the operation was successfully
performed.

The Accounting Log File

‘users to disable or enable all accounting or accounting for particular
types

jobs.

By default, the system writes a record into the
accounting
1log file
whenever
a
Job
terminates.
Termination
records
are
written for
interactive
users,
batch
jobs,
non-interactive
processes,
login
failures,
and print jobs.
The $SNDACC system service allows users to
write additional data into the accounting log
and
allows
privileged

Table 4-5 lists the fields
portions
of the accounting

4.68.2

in the accounting record
and
notes
which
record are written for each type of job.

Format of Messages Sent

The SACCDEF macro defines symbolic
within
the accounting record, and

the Accounting Manager

names for the message
job type record codes

types, fields
for selective

accounting.

A message buffer for a message to
word
defining the message type.

the accounting manager begins with a
Some message types require that data
follow the message type code in the buffer.
The
message
types
and
data, if any, required by each are listed below.
|

ACCSK_INSMESG
Insert an arbitrary message

in the accounting log file.

The

message
code
1is followed with any arbitrary data.
when the
message is inserted in the accounting log file,
the
default
header precedes the user-specified data.
2.

ACCSK_NEWFILE

Requests that the current log file be closed and a
created.
Operator privilege is required to
file.
No data is required for the message.

4-149

create

new
a

new

file

log

SYSTEM SERVICE DESCRIPTIONS
$SNDACC
- SEND MESSAGE TO ACCOUNTING MANAGER
ACCSK_ENABACC

Enables accounting for all
is

required

the

message.

enable

types of jobs.

accounting.

Operator privilege

No data

1is

required for

ACCS$K_DISAACC

Disables accounting for all types of job.
is

required

to disable accounting.

Operator privilege

No data

required

for

the message.

ACCSK_ENABSEL
Enables accounting
for
certain
types
of
privilege
1is required to selectively enable
message type code must be
followed
by
one

indicating

the

type

job

job.
Operator
accounting.
The
or
more
bytes

for which accounting:is

to be

enabled:

dee

Job Type

ACC$SK_BATTRM

Batch

ACCSK_INSMSG
ACCSK_INTTRM

Arbitrary messages
Interactive
job

ACCSK_LOGTRM
ACCSK_PRCTRM
ACCSK_PRTJOB

The list of job type
containing 0.

job

codes must be

terminated
|

with

byte

ACC$K_DISASEL

Disables

accounting

for

<certain

types.

job.

Operator

privilege is required to selectively disable accounting.
The
message type code 1is followed
by one or more bytes indicating
the types of job for which accounting is to be disabled.
The
codes are listed above, under ACCSK ENABSEL.

4-150

SYSTEM

$SNDACC

SERVICE

SEND MESSAGE

DESCRIPTIONS

TO ACCOUNTING MANAGER

"Table 4-5

))/,1

Format of Accounting Log File Records

Accounting Log File Record Headerl
Offset | Field Name

Length

Contents

0
2
4
8
12
16
24
32

word
word

Record type code
Length of data message
|Final exit status
|Process identification
|Job identification
|System time at job termination
Account name (blank-filled)
User name (blank-filled)

ACCSW_MSGTYP
ACCSW_MSGSIZ
ACCSL_FINALSTS
ACCSL_PID
ACCSL _JOBID
ACCSQ TERMTIME
ACCST ACCOUNT
ACCST USERNAME

|longword

longword
longword
|quadword
8 bytes
|12 bytes

Job Information2
Offset | Field Name

“

ACC$L CPUTIM

Length

Contents

longword

|CPU time in 10-millisecond units

|System time

48
52
56
60
64
68

ACCSL_PAGEFLTS
ACCSL PGFLPEAK
/ACCSL_WSPEAK
ACCSL_BIOCNT
ACCSL -DIOCNT
ACCSL_VOLUMES

ACCS$Q LOGIN

quadword

ACCSL _OWNER
ACCSK_TERMLEN

longword
|Process identification of process's owner
constant | Length of non-batch job termination message

at login

- Batch Job Accounting Information3
Offset | Field Name

Length

84
92

|8 bytes.
|Job name (blank-filled)
»
16 bytes | Queue name (counted ASCII string)
constant | Length of termination record for batch

ACCST
JOB NAME
ACCST_JOB_QUE
ACCSK _JOB_LEN

Contents

jobs

Printer Job Information4
Offset | Field Name

Length

Contents

- ACCSL_PAGCNT

longword | Symbiont page count

52
56
60
68
76

User

Offset | Field Name

Length

Data

Contents

ACCST _USER_DATA| 132 bytes'User data written to accounting file
ACCSK_INS LEN
|

Present

in all

Présent

types

constant | Length of
record

interactive,

log

file

user-written accounting

file

log

records.

non-interactive process,

and

batch

Jjob

termination

messages.

Present only

in batch

job termination records.

The record contains default
Present only in printer job termination records.
header record and CPU time followed by the data listed below.

Present

in user-written messages.

4-151

SYSTEM SERVICE DESCRIPTIONS

$SNDACC - SEND MESSAGE TO ACCOUNTING MANAGER
4.68.3

Format of Response

If
a mailbox
the

specified,

format:

the

accounting manager

returns

a message

Bits

Contents

0-15

MSGS ACCRSP indicates that the message is
from the

accounting
the

manager.

S$MSGDEF macro.)

a ,response'

(This symbolic name
|

16-31

32-63

Status code indicating the success of»the operation.

the

defined

from Accounting Manager

mailbox

cannot

insufficient
buffer
the mailbox no longer

handle

the

message

(elther

space,
or because a message 1is too
exists when the reply 1is sent, the

’because

long),
or
response

of
1if
1is

lost.

Status Codes_Returned
SS$_NORMAL
Request

the Mailbox:
|
performed.

successfully

JBCS_ACMINVOP

invalid

JBC$_NOPRIV .
The process
operation.

operation was
-

does

not

have

requested.
|
the privilege

perform the

Thése_status codes are defined in the SJBCMSGDEF macro}

4-152

requested

SYSTEM SERVICE DESCRIPTIONS

$SNDERR
4.69

SSNDERR - SEND MESSAGE TO ERROR LOGGER

The Send Message To Error Logger system service
writes an
arbitrary
message
to the system error log file.
The user-specified message is
preceded by the date

and

time.

Format:

Macro

$SNDERR msgbuf
High-Level

Language

Format:

SYSSSNDERR (msgbuf)

msgbuf

address of character string descriptor p01nt1ng to the message to
be inserted in the system error log flle.
,

Return

SS$

Status:

NORMAL

Service successfully completed

SS$_ACCVIO
e’

The message buffer or buffer descriptor cannot

read

the

caller.

SS$_INSFMEM

Insufficient system dynamic memory 1is available to
complete
the
service
and the process has disabled resource wait mode w1th the
Set Resource Wait Mode ($SSETRWM) system service.

SS$_NOPRIV

The process does not have

the BUGCHK pr1v1lege.

Priv1lege Restrlctlons.
The user pr1v1lege BUGCHK 1is requlred to send a
error

log

file.

message

the

Resources Required/Returned:

The Send Message To Error Logger system service
dynamic memory.

4-153

requires

system

SYSTEM SERVICE DESCRIPTIONS

$SNDOPR
4,70

$SNDOPR -

SEND MESSAGE

TO OPERATOR

The Send MesSage To Operator system service allows a process to send a

message
to
one
or more terminals
and optionally receive a reply.

Macro

designated

operators

terminals
o

Format:

$SNDOPR msgbuf

, [chan]

High-Level Language

Format:

SYSSSNDOPR (msgbuf
msgbuf
address
buffer.

, [chan])

character
The

described

number

the

types
Section

string

descriptor

pointing

of
message
and
4.70.1, below.

the

|
message

the

buffer

formats

are

chan

is
to
implies

Return

channel

be
sent,
no mailbox

assigned

if
any.
unit.

the

mailbox

channel

number
-

descriptor

cannot

which

the

(the
|

reply
default)

Status:

SS$_NORMAL
Service

successfully

SSS_ ACCVIO
»
The message buffer
caller.
SS$_BADPARAM
The specified

message

completed.

buffer

has

not

length

|
be

has

read

the

|
than

128

bytes.

SS$_DEVNOTMBX
The channel

spe01f1ed

SS$ DEVOFFLINE
There is no

operator

assigned

designated

to a mailbox.

receive

messages.

- SS$_INSFMEM
Insufficient system dynamlc memory 1s available to
complete
service
and the process has disabled resource wait mode with
Set Resource Wait Mode (SSETRWM) system service.
SS$_IVCHAN
An invalid
number

channel
0

number
a

was

number

specified;
larger

than

that
the

the
the

1is,

<channel

number

channels

avallable.

SS$

NOPRIV
The process does not have the
operator,
the
process
does

specified mailbox,
privileged

access

the

privilege to send a message to
not
have read/write access to

channel

mode.

was

assigned

from
|

4-154

the
the

SYSTEM SERVICE DESCRIPTIONS
$SNDOPR - SEND MESSAGE TO OPERATOR
Privilege Restrictions:

Send Message To
The user privilege OPER is required to issue the
as an operator's
al
termin
a
Operator system service to enable
initialize the
or
t,
reques
user's
a
cancel
or
to
terminal, reply
-

operator communication log file.

Resources Required/Returned:

The Send Message
dynamic memory.

Note:

system

Operator

requires

service

system

The general procedure for using this service is as follows:
final

1length

its
Construct the message buffer and place
ptor.

1Issue the $SNDOPR system service.

Check the return status

When
specified, 1if any.
1Issue a read request to the mailbox opera
tion was successfully
the read completes, check that the

the first word of the buffer descri

successful completion.

code

from

the

service
|

ensure

performed.

4,70.1

Operator Communication

to implement the REQUEST and REPLY
This service is used by the system
ns between users and operators.
icatio
" commands, which provide commun
an operator's console by issuing

al as
An operator establishes a terminfying
the types of message that will be
the REPLY/ENABLE command, speci
ges " to the operator with the
handled. Users can then send messa
|
REQUEST command, optionally requesting replies.
the
Messages are displayed on a specified operator's terminal in

\\_—a/ .

format:

'Opcom ——— time - User=*username’ ACNT#“account“
COrcom —— XXk REPLY-ID = n KkKX]

Oscom —— messadge—-texd

‘

t act
. ive until the

rator request is kep
a rep
ds.uested, the ope |
If rat
or lyresisponreq
ope
4.70.2

SSNDOPR Message Types and Message Formats

for operator
The SOPCDEF macro defines symbolic n names
status codes.

offsets within messages, and retur

4-155

mesSsage

types,

SYSTEM

SSNDOPR —

The

S$SNDOPR

system

Code

service

“

SERVICE

DESCRIPTIONS

SEND MESSAGE

handles

five

TO OPERATOR

types

of message:

Type of Request

OPCS%RQ_RQST

vRequest operator functions

OPCS_RQ_CANCEL Cancel a user request

OPCS_RQ_REPLY’ Reply te user request

Each

OPC$S_RQ TERME

Enable

OPC$_RQ_LOGI

Initialize log file

message

4.70.2.1

type

128

has

bytes,

terminal

Offset

different

including

OPCS _RQ _RQST

operator's

terminal

OPC$B+MS_TARGET

operator S use

format.

message

Constructs

(REQUEST

The

maximum

length

text.

message

command).

Length

OPCSB_MS_TYPE

for

The

displayed

message

format

any

is:

Cohtents

| byte -

OPCS RQ ROST idehtifies

message

3»bytes’

Mask

indicating

receive
to

the

create

which

message.

the

mask

the

type - of
|

operators

The

will

symbolic

names

are:

OPCSM NM CENTRL Central operator

OPCSMNM
_DEVICE Device status
OPCSMNM
_DISKS
Disk operator
OPCSM_NM_TAPES
Tape operator

,OPCSM NM PRINT

Printer

OPCS$M NM OPERl

information

operator

System manager-defined

.«

operator

functions

OPC$M_NM_ OPERI12

OPCSL_MS

RQSTID

OPCSL_MS TEXT

Longword

0-120

bytes

4.70.2.2
OPC$_RQ CANCEL
be canceled.
The

message

except

format

that:

User-specified message'identification
be used for replylng

Notifies

120

bytes of

message

operator

that

’

the

same

for

The

message

type

The

message

has

the

message
|

field
no

must

message

contain
text.

4-156

text

request,

type
|

OPC$_RQ_CANCEL

OPCS$S_RQ RQST
|

SYSTEM SERVICE DESCRIPTIONS

E OPERATOR
$SSNDOPR - SEND MESSAGTO

4.70.2.3 OPC$ _RQ_REPLY - Constructs a reply to a user request
The message format is:

command) .

Contents

Offset

Length

OPC$SB_MS _TYPE

byte

OPC$_RQ REPLY

OPC$W_MS_STATUS

word

Return status:

identifies

Request
Request
Request
Request

word

Unit number of terminal

Device name (counted ASCII string)

Reply message text,‘if,any- |

. :

OPC$L_MS_OTEXT. -=

terminal
4.70.2.4 OPCS$S_RQTERME - Enables a
is:
format
message
The
.
command)
NABLE
(REPLY/E
Length

Contents

OPC$B_MS_TYPE

byte

OPC$_RQ_TERME

OPC$SB_MS_ ENABL
OPCSL_MS_MASK

3 bytes
longword

OPC$W_MS_OUNIT

word

OPCST_MS_ONAME

4.70.2.5

completed
denied
pending
canceled

is directed

_Offset

Identlflcatlon of message to which reply

OPC$L_MS_RPLYID iGngword

OPCST_MS_ONAME

type

the

message

OPC$_ RQSTCMPLTE
OPCS$_RQSTABORT
OPCS$S_RQSTPEND
OPC$ RQSTCAN

OPC$W_MS_OUNIT

(REPLY

identifies
o

message

for

operator= use

the type of
|

Masks defining the type of messages for
which the terminal is enabled
Unit number of terminal

Device name (counted ASCII string)

OPC$_RQLOGI - Initializes the log file of operator messages

(REPLY/LOG command).

The message format is:

Offset

Length

Contents

OPC$B_MS_TYPE

byte

$
RQ LOGI
OPC

7 bytes

Ignored

OPC$W_MS_OUNIT

word

Unit number of terminal

OPC$T;MS_ONAME

identifies

the

type

message

Device name (counted ASCII string)

4-157

SYSTEM

SERVICE

DESCRIPTIONS

$SSNDOPR - SEND MESSAGE TO OPERATOR
4.70.3

Format

When the

operator

specified

mailbox

Offset

OPCSB

TYPE

Response
replles

the

from
to

Operator
message,

Communication Manager
the

format:

Length

Contents

word

MSGS OPREPLY

symbolic
SMSGDEF macro.

OPCSW_MS_STATUS

word

Return

OPCSL_MS RPLYID

longword

Identification
is

indicates

response

This

placed

that

the

to an operator's

name

1is

the

0-128

mallbox

message

spe01f1ed

(either

message

Status

Codes

bytes

too

because

defined

made

receive

message

(specified

the

insufficient

big),

the

message

Returned

Mailbox:

1in

the

status.

Up to 128 bytes
from reply

message

request.

for

1in

which

user

message)

OPCSL_MS TEXT

the

message

cannot

buffer

'text

handle

Space

the

request

taken

because

the

lost.

OPCS _NOPERATOR
Success.

There

was

OPC$_RQSTCMPLTE
“Success.

enabled

Operator

The

operator

completed

the

message.

request

will

|
perform

the

request

" The operator could not satisfy the request.

OPCS$_RQSTCAN
caller

the

OPCS _RQSTABORT

The

receive

The

OPC$_RQSTPEND
Success.

operator

canceled

the

request.

4-158

when

possible.

SYSTEM

SERVICE DESCRIPTIONS

$SNDSMB
4,71

SSNDSMB - SEND MESSAGE TO SYMBIONT MANAGER

The Send Message To Symbiont Manager system service

used

the

operating system to queue user's print files to a system printer or to
queue command procedure files for detached job execution.
requests:

Symbiont manager
®

Create

and

delete

queues

)

Add or

delete

Change

the attributes of

Start and

files from a queue

files

in a queue

restart dequeuing

Macro Format:
msgbuf

SSNDSMB

High-Level

Language

,[chan]

Format:

SYS$SNDSMB (msgbuf
msgbuf

, [chan])

address of a character string descriptor pointing to the
message
buffer.
The
buffer formats
and
the
types of
messages are
described in Section 4.71.1, below.

chan

number of the channel assigned to
the mailbox
to
receive
the
reply.
If no channel number is specified, or if it is specified
as 0 (the default), it indicates that no reply is desired.

Return

Status:

SS$ _NORMAL
Service

|
completed.

successfully

SS$_ACCVIO

" The message buffer
or buffer descriptor
caller.

SS$_BADPARAM

cannot

read

the

than

200

The specified message has a length of 0

has

characters.

SS$_DEVNOTMBX

The specified channel

SS$_INSFMEM

|
is not assigned to a mailbox.
|

" Insufficient system dynamic memory is available to
complete
the
service
and the process has disabled resource wait mode with the
Set Resource
Wait Mode (SSETRWM) system service.

4-159

$SNDSMB
SS$

IVCHAN
An invalid

SYSTEM SERVICE DESCRIPTIONS
- SEND MESSAGE TO SYMBIONT MANAGER
|

number of
available.
SS$_NOPRIV
The caller

channel

number

does

not

was

specified;

number

have

larger

write

that

than

access

the

to the

:
1is,

channel

number

channels

Spec1f1ed mailbox.

Resources Required/Returned:
The Send Message To

Symbiont

Manager

system service

system dynamic memory.

Privilege

Restrictions:

There
®

are

The

two

user

levels

privilege

privilege
OPER

1is

involved
required

symbiont

queues, to modify job gqueues for other
priority of a job within a queue.

requires

control:

manipulate

users,

A process can manipulate any jobs owned by processes
group.

device

increase

the

its

Note:

The

general

Construct the message
the first word of the

procedure

the

for

$SSNDSMB

using

buffer
buffer

and place its
descriptor.

follows:

final

1length

1in

Issue

Check the return status

ensure

4.,

TIssue a read request to the mailbox specified, if any.

When

successful

the

read

system

service

service.

code from

completion.

completes,

check

performed.

4.71.1
type.

the

service
|

operation

was

successfully

Format of Messages Sent to Symbiont Manager
Each

fields,

that

the

Messages are variable-length,
and

additional
The

this

and

request

type

can

followed

their

- can

formats depend on the

require

from

options.

Some

request

additional data

options

require

data.

general

message

format

is:

request [queuename] [devname] [fileid] [dirname]
[filename] [jobid] [jobname] [option[opdata]]
request

16-bit field indicating the
request
type.
The
SSMRDEF
defines symbolic
codes for each request in the format:

macro

SMRSC_code

Valid request codes,

and required and optional fields for

for

each,

are

listed

Table

4-6.

4-160

fields

$SNDSMB

SYSTEM SERVICE DESCRIPTIONS

queuename

SEND MESSAGE

SYMBIONT MANAGER

l6-byte queue name.
The length of the name must be
byte.
A
qgueue name can be a physical device name
LPAO:), a logical name (for example, SYSSPRINT), or
name string, such as BATCH or AFTERS.
|

in the first
(for example,
a
designated

Some

for

request

SMRSK MERGE.

types

requlire two
|

Jgueue

names,
|

example

devname

l6-byte field containing the name of the device on which the file

resides.
The
1length
of
the
device name must be in the first
byte.
The device name 1is returned by RMS
as
a
counted
ASCII
string
in
the NAMST DVI field of the auxiliary name block (NAM)
|
when the file 1is opened.
fileid

6-byte file identification.
RMS returns the file
in
the
auxiliary
name
block
(NAM)
beginning
NAMSW_FID when the file is opened.

dirname
6-byte

the

o
returned by RMS

directory name
offset NAMSW _DID.

filename

20-byte field containing the name of
first byte in the field must contain

jobid

in the

name

a file to
be
the length.

1identification
at
the offset

block
|

(NAM)

queued.

The

16-bit job header identifying the job.
The jobid is returned
1in
the message queued to the mailbox on completion of the operation.

jobname

8-byte

blank-filled ASCII

name

string.

option
byte indicating an
optional
parameter
SSMRDEF
macro
defines
symbolic
names

for
for

the
the

|
request.
The
options in the

format:

SMOSC option

Valid options for each request type are listed in Table 4-6.
options,

and any data required by each,

opdata

any data required

Syntax

the

are listed

in Table

The

4-7.

specified option.

Notes:

Fields
within
the
message
buffer
must
be
placed
in
~consecutive
positions
in
the
buffer,
with no intervening
‘blanks.

The message length passed to the service indicates the
total
length
of
the
buffer.
If a byte of binary 0's follows an
option or its required data, the message scan is
terminated.
Therefore, fixed-length message buffers can be used, with a 0
indicating termination of the option list.

4-161

SYSTEM SERVICE

DESCRIPTIONS

$SNDSMB
- SEND MESSAGE TO SYMBIONT MANAGER
The

following example

system

shows

1npu t message

buffer

for

the

$SNDSMB

service:
y MESHAGE

BUFFER

SMRER.ADDFIL

sREQUEST

TYFE

ADDLIST@

«WORD

ADD

DEV?

« BLLKR

s MOVE

DEVICE

NAME HERE

CFILID?

+ BLKW

s MOVE.

FILEID

HERE

FILEN?

+ BLKE

s MOVE

FILENAME

OF TS

« BLKE

s LEAVE

+ L.LONG

ADNDESC-ADDLIST

« LLONG

ADDLTST

sDESCRIFTOR FOR MESSAGE
y LENGTH OF RUFFER
y ADNRESS OF RUFFER

ADDESC

ROOM

FOR

FILE

4-162

C(COUNTET

HERE
10

$SNISME..S MSGRUF=ANDESC sADD

FILE

QUEUE

OFTIONS

STRING)

SYSTEM SERVICE DESCRIPTIONS
- SEND MESSAGE TO SYMBIONT MANAGER
$SSNDSMB
Table 4-6
Request Types for Symbiont Manager Messages

SMRSK_ABORT

Stops printing the current
file and skips to the
next

SMRSK ADDFIL

SMRSK ALTER

Required

Function

Request

Data

Valid Options

queuename

SMOSK_REQUEUE

devname

SMOS$SK_COPIES

fileid
dirname
filename

SMOSK_BRSTPAG
SMOSK

queuename

SMO$K_FORMTYP
SMO$K_HOLD
SMOSK_JOBCOPY
SMOSK_JOBNAME
SMOSK JOBPRI
SMOSK LOWER

file

Adds a file

to a job

Changes attributes of a

previously queued job and
the

requeues

jobid

job

DELETE

SMO$K DOUBLE
SMOSK FLAGPAG
SMOSK_NOBRSTPAG
SMOSK_NOFEED
SMOSK NOFLAGPAG
SMOSK _PAGCNT
SMO$K_PAGHDR

SMOSK NOLOWER

SMOSK RLSTIM
a

queue

SMR$SK ASSIGN

Directs

SMR$K_CLSJOB

Closes

SMR$K_CREJOB

Creates a job

queuename

None

[devname]

specific device

the job

None

SMOS$K_FORMTYP
SMOSK_HOLD
SMOSK_JOBPRI
SMOS$K_RLSTIM

queuename

SMOSK_FORMTYP
SMOSK_HOLD
SMOSK_JOBCOPY

SMOSK_JOBPRI
SMO$K LOWER
SMO$K NOLOWER
SMOS$K_PARAMS
SMOSK_RLSTIM

SMR$K DELETE

Deletes a device queue

SMR$SK_ENTER

Enters a file in a
queue for a device

1
2

queuename

None

queuename
devname
fileid
dirname
filename

SMOSK_BRSTPAG
SMOSK_COPIES

SMO$K_DELETE
SMOSK_DOUBLE
SMOSK_FLAGPAG
SMOS$K_FORMTYP
SMOS$K_HOLD
SMOSK_JOBCOPY
SMO$K_LOWER
SMO$K_NOBRSTPAG
SMOS$K_NOFEED
SMOS$K_NOFLAGPAG
SMO$K_NOLOWER
SMOSK_PAGCNT
SMO$K_PAGHDR
SMOSK_JOBPRI
SMOSK_RLSTIM

The dirname field is required only if file is to be deleted after proqessing.
The filename field is optional; it can be used for informational purposes.

4-163

$SNDSMB

SYSTEM SERVICE DESCRIPTIONS
- SEND MESSAGE TO SYMBIONT MANAGER

Request

Types

Request

Table 4-6
(Cont.)
for Symbiont Manager

Function

SMR$SK INITIAL

Initializes or
a

Messages

Required

reinitializes

Data

Valid

queuename

Options

SMOS$SK CURFORM

queue

SMOSK

DEFBRST

SMOSK_DEFFLAG
SMOS$K DETJOB

SMOSK DISWAP
SMOSK GENDEV
SMOSK GENPRT
SMOSK INIPRI
SMOSK JOBLIM
SMOSK NODEFBRST
- SMOSK_NODEFFLAG
SMOSK NOGENDEV
SMOSK

NOGENPRT

SMOSK NOTRMDEV
SMOSK

SMRSK_JUSTIFY

Issues
feed

SMRSK_MERGE

Deletes jobs from second

‘

queue

and

form

places

- gueuename
-

them

queuenamel

SMR$K PAUSE

Temporarily
operation

SMRSK_REDIRECT

Redirects second queue to
first

SMRSK RELEASE

Releases

SMR$SK_RMVJOB

Removes
a

SMR$SK START

current
B

queuename

[queuename
held

job

None

queuenamel

queue

printing

None

queuename

first queue
suspends

None
]

hardware

for

]

queuename

jobid3

job

from

TRMDEV

jobid

None
None

- None

queue

Enables printing

a device,

resumes

printing

device,

queuename

paused

restarts printing

stopped

SMOSK_CURFORM
SMOS$K DEFBRST

SMOSK DEFFLAG

device

SMOSK DETJOB

SMOSK_GENDEV
SMOSK_GENPRT
SMOSK NEXTJOB
SMOSK NODEFBRST
SMO$K NODEFFLAG
SMOSK NOGENDEV
SMOS$SK NOGENPRT
SMOSK NOTRMDEV
SMOSK PAGNUM
SMOSK TOPOFILE
SMOSK TRMDEV
SMR$K _STOP

Stops
(for
to

SMRSK

SYNCJOB

printing
a

batch

job,

device

queuename

PAUSE)

Waits

for

complete

batch

job

gueuename

[jobid]4

1
2

is
4

The

dirname

field

The

filename

A jobid is optional;
released.

Either

the

jobid

[jobname]

only

file

optional;

can be

required

field

None

equivalent

used

deleted

for

after

processing.

informational purposes.

1if specified as 0 or'not\specified, the first job in queue
the

jobname

must

specified.

4-164

'SYSTEM SERVICE DESCRIPTIONS

- $SNDSMB - SEND MESSAGE TO SYMBIONT MANAGER
Table

4-7

Options for Symbiont Manager Messages
Data

Required

Function

Option

SMOS$SK_BRSTPAG:

Specifies that a burst page
should be printed

None

SMOSK_COPIES

Specifies the number of
copies of the file to

Number

of copies

byte)

Type of form (1 byte)

SMO$K_CURFORM

Defines form type currently

SMO$K_DEFBRST

Specifies that queue prints

None

SMOSK_DEFFLAG

Specifies that queue prints

None

SMO$K DELETE

Deletes file after printing

None

SMO$K DETJOB

Defines gqueue as a detached

None

SMO$K_DISWAP

Disables swapping of all

None

SMO$K_DOUBLE

Double—spacés printer output

None

SMO$K FLAGPAG

Specifies that a flag page
should be printed

SMOSK_FORMTYPE

Specifies

SMO$K_GENDEV

Defines

the

queue

SMOS$K GENPRT

Defines

the

queue

on printer

by default

burst page

by default

flag page

(batch)

job

batch

queue

in queue

jobs

the form type

None

form

Type‘Qf

None

(1 byte)

generic device queue

generic printer

file

queue

SMOSK HOLD

' Holds job until specifically

None

released

Specifies initial priority

Priority

SMOS$K_JOBCOPY

Specifies a repeat count
for the entire job

Repeat count

SMO$K_JOBLIM

Specifies maximum number

Number

SMO$K_JOBNAME

Specifies the job name

Counted ASCII

SMOSK JOBPRI

Specifies priority for
|
queuing of a Job

Priority

SMOSK _LOWER

Specifies that printer
must be equipped with uppercase and lowercase characters

None

Terminates current job and
start printing with next

None

SMO$K_ INIPRI

SMO$K_NEXTJOB

batch

jobs

job

in batch queue

job

4-165

(1 byte)

h
15
throug

range:

(1 byte)

jobs

byte)

range:

string

bytes)

(1 byte)
through 31

$SSNDSMB

SYSTEM SERVICE DESCRIPTIONS
-

SEND MESSAGE

Option

Specifies that
should be

SMOSK_NOGENDEV

None

default

printer

flag

does

default

feed

Specifies
should be

for

None

output

that

flag

page

the

None

device

Disallows generic printing
the

None

printed

Disallows generic spooling

None

page

Cancels automatic

SMOSK_NOGENPRT

generate

form

SMOSK NOFLAGPAG

burst

specified

None

device

SMOSK_NOLOWER

Specifies that
printer is not

lowercase
required

None

SMOSK_NOTRMDEV

Specifies that
not a terminal

device

None

SMOSK PAGCNT

Specifies the number
pages to print

SMO$K_PAGHDR

Prints file specification on
the

SMOSK_ PARAMS

SMO$K REQUEUE

SMOSK_RLSTIM

SMO$K_SPCCNT

SMOSK_ TOPOFILE

Places
printer

each

1is

Number

output

parameters

pages
(1 word)

None

page

for

One

counted

ASCII

strings terminated by
0 (maximum length of
all strings is 63 bytes)

aborted
job

line

back

None

into

queue

Specifies time
a held job

Binary absolute time value |

release

(quadword)

Restarts current job
backspacing or forward
spacing pages

Signed l6-bit
specifying
plus or minus

Restarts current job at top
of

SMOSK TRMDEV

top

Specifies
batch job

the

Data

printed

Specifies that
not

SMOSK_ NOFEED

Required

Specifies that printer
does not generate burst
page

SMOSK NODEFFLAG

Messages

Function

page

SMOSK_NODEFBRST

SYMBIONT MANAGER

Table 4-7 (Cont.)
for Symbiont Manager

Options

SMOSK NOBRSTPAG

file

Specifies
terminal

None

that

device

4-166

1is

None

integer
page

count

SSNDSMB

- 4.,71.2

SYSTEM SERVICE DESCRIPTIONS
- SEND MESSAGE TO SYMBIONT MANAGER

Format of ResponSe from Symbiont Manager
the symbiont

If a mailbox is specified,
information:

following

manager

returns

the

Contents

Bits

the
from
is
the message
MSG$ SMBRSP indicates that
symblont manager.
(This name is defined in the S$MSGDEF

0-15

macro.)

l16-31

jobid

32-63

status code indicating the success of the operation.

of
because
(elther
message
the
handle
cannot
the mailbox
If
or because a message is too long), or 1if
space,
buffer
insufficient
is
response
the mailbox no longer exists when the reply is sent, the
lost.

Status Codes Returned
JBCS_NORMAL
Serv1ce

in Mailbox:

successfully completed.

JBCS ILLDEVNAM

The device name specified has more

than 15

characters.
|

JBCS_ILLDEVTYP

"The symbiont manager cannot create a queue for

the

device

type

specified.
JBC$

ILLFILNAM

“The fllename specified has more than 19

characters.

JBCS_ INVREQ

TAn 1nva11d request type was spec1f1ed

JBC$_NOOPENJOB

“There is no outstanding open print job for the caller.
|

JBC$_NOPRIV

"The process does not have the privilege to perform the

requested

operation.
JBCS

NOQUEHDR

“The symbiont manager has

space

header.

JBCS

NOQUESPACE

“The

specified dev1ce queue

1is

full.

JBC$_NOSUCHJOB

The specified record was not a print job.

JBC$_NOSUCHQUE

There is no queue for

JBCS_QUENOSTOP

“The specified queue

the specified device.

is still

active.

4-167

allocate

dJueue

SYSTEM

$SNDSMB

JBCS

SMINVOPR
“The request
to

start

SERVICE

DESCRIPTIONS

SEND MESSAGE
TO SYMBIONT

MANAGER

o
type
queue

spec1f1ed
that

was

is 1llegal
already

or,

attempt

started.

JBCS_ SMINVOPT

"A specified option is invalid for the request type.

JBCS_SMINVREQ

TAn 1nvalld request type was spe01f1ed

JBCS

SMZEROJOB
TA job was

JBCS

that

SYMBDSAB
The symbiont manager

status

codes

are

1is

had no

files

it.

disabled.

defined

the

These

released

4-168

SJBCMSGDEF macro.

was

made

SYSTEM

SERVICE

DESCRIPTIONS

$SUSPND
4,72

$SUSPND

SUSPEND

PROCESS

The Suspend Process system service allows a process to suspend
or

another

otherwise

.Macro

©process.

suspended

executed

until

another

process

cannot

resumes

1itself

receive

ASTs

deletes

it.

Format:

SSUSPND

High-Level

[pidadr]

Language

, [prcnam]

Format:

SYS$SUSPND
( [pidadr] , [prcnam])
pidadr
address
the

of a longword containing
process to be suspended.

prcnam

|
the
|

address

character

l5-character

process

‘qualified

the group

identification

string

name

process

descriptor

string.

number

pointing

The process

the

process

name

issuing

the
is

implicitly

the suspend.

If neither a process identification nor a process name
1is
specified,
the
caller
1is
suspended.
For details on how the service interprets
the PIDADR and PRCNAM arguments, see
Table
3-3.
Table
3-3
is
1in

Section

Return

3.5

"Process

Control

Services."

Status:

SS$_NORMAL
Service successfully

completed.

SS$_ACCVIO
|

The

process

read,

SS$_INSFMEM
|
Insufficient system dynamic memory is available to
complete
service
and the process has disabled resource wait mode with
Set Resource Wait Mode (SSETRWM) system service.

the
the

process

name

string
or

identification

SS$_IVLOGNAM
The specified
characters.

process
|

string

cannot

name

has

descriptor

written,

length

SS$_NONEXPR

Warning.
The specified process does not
process 1identification was specified.

SS$_NOPRIV
The target
requesting
privilege.

|
process

was

not

process

does

not

created

have

4-169

group
.

cannot

the

caller.

has

exist,

the

world

caller

process

than

invalid

and

the

control

SYSTEM SERVICE DESCRIPTIONS
SSUSPND

SUSPEND PROCESS

Privilege Restrictions:

Other processes in the same group (GROUP privilege)

Any other process in the system

User privileges are required to suspend:

(WORLD privilege)

Resources Required/Returned:

Suspend

The

Process

system

service requires

memory.

system

dynamic

Notes:

The suspend process system service completes successfully

suspended
a
set,
Unless it has pages locked in the balance
removed from the balance set to allow other
can be
process

the target process

processes

The

Resume

execute.

suspended

is already suspended.

Process

process

(SRESUME)

system

service

one

suspension,

see

continue.

allows

resume

Section

3.5.5,

a
suspended,
requests are issued for a process that is not
completes 1mmed1ately, that 1is,
request
suspend
subsequent
1is maintained of
No count
the process is not suspended.

outstanding

For

resume requests.

information

process

"Process Hibernation and Suspension.”

4-170

SYSTEM SERVICE DESCRIPTIONS
STRNLOG
STRNLOG - TRANSLATE LOGICAL NAME

4.73

es the 1logical name
The Translate Logical Name system service search
s an equivalence name
return
and
name
tables for a specified logical
l name tables are
logica
system
and
group,
s,
string. The proces
|

searched in that order.

user-specified buffer;

Macro Format:
STRNLOG

returns

match

string

The first

e ol

1into

string

equivalence

the

the search is not recursive.

lognam ,[rsllen] ,rslbuf ,[table] , [acmode] ,[dsbmsk]

High-Level Language Format:

SYSSTRNLOG (lognam , [rsllen] ;rslbuf , [table] ,[acmode]v,[dsbmsk])
.

lognam

name

logical

address of a character string descriptor pointing to the
,

string.

rsllen

address ofa word

equivalence name string.

receive

the

length

rslbuf

the

translated

ng to the Dbuffer
address of a character string descriptor pointiname
string.
lence
equiva
which is to receive the resultant

table

l name table
address of a byte to receive the number of the oflogica
tes that
indica
0
value
in which the match was found. A return
1
table;
name
l
logica
system
the
1n
found
the logical name was
table.
s
proces
the
indicates the group table, and 2 indicates
|

which the
address of a byte to receive the access mode ed from
byte 1is
this
in
receiv
Data
made.
was
entry
table
logical name
2, the
table
in
found
was
valid only if the logical name match

acmode

process logical name table.

|
of particular
mask in which bits set to 1 disable the search
logical name
system
the
set,
is
0
logical name tables. If bit
l name
logica
group
the
set,
is
1
bit
if
ed;
search
table is not
l name
logica
s
proces
the
set,
is
table 1is not .searched; if bit 2

dsbmsk

table is not searched.

as 0 (the default),
If no mask is specified, or is specified
three logical name tables are searched.

4-171

all

SYSTEM SERVICE DESCRIPTIONS
$TRNLOG - TRANSLATE LOGICAIL NAME
Return

Status:

SS$_NORMAL
Service

placed

successfully

the

completed.

output

The

equivalence

buffer.

name

SS$_NOTRAN
Service
was

successfully

placed

1in

the

completed.
output

SS$

was

The

buffer

found.

string

input

because

‘logical
no

name
string
equivalence name was

ACCVIO

~ The logical name string or
the

output

cannot

1length,

output

written,
by

string descriptor cannot be
buffer,

the

caller.

name

string

the

resultant

the

string.

table

access

read,
mode

SS$_IVLOGNAM
-

The

specified

than

logical
characters.

SS$_RESULTOVF
The

buffer

I
has

length

has

=zero,
|

receive

smaller

field

than

string

has

length

Note:

the
first
character
of
underline
character
(), no

the

underscore

modified
For

example

"Logical

Name

character

string

is
returned

the

$TRNLOG

Services."

a
specified
1logical
name
is
an
translation is performed.
However,
removed
from
the
string
and
the

the

system

output

service,

4-172

buffer.

see

Section

3.3,

SYSTEM SERVICE DESCRIPTIONS

SULKPAG
'4.74

SULKPAG - UNLOCK PAGES FROM MEMORY

The Unlock Pages from Memory system service releases the page lock on
a page or range of pages previously locked in memory by the Lock Pages
in Memory

Macro

service.

($LCKPAG)

Format:

SULKPAG

,[retadr]

inadr

,[acmode]

High-Level Language Format:
SYSSULKPAG (inadr
inadr

,[acmode])

, [retadr]
|

address of a 2-longword array containing the starting and ending
virtual addresses of the pages to be unlocked. If the starting
ewwiswWW,i

wwpag
and ending virtual addréSSéSWaYEWWthe”WsamefWWansinglethe
virtual
unlocked.

Oonly

addresses is used;

the

virtual page number portion of

the low-order 9 bits are ignored.

retadr

ending

address of a 2-longword array to receive the starting and

virtual addresses of the pages actually unlocked.
,

acmode

access

The specified

access mode of the locked pages.

mode

maximized with the access mode of the caller. The resultant
access mode must be equal to or more privileged than the access
mode of the owner of each page in order to unlock the page.

Return Status:

SS$ WASCLR
Service successfully completed.

At least one

the

specified

pages was previously unlocked.

SS$ WASSET

Service successfully completed.

previously locked.

All of the specified pages

were

SS$_ACCVIO

The input array cannot be read, or the output array cannot be

A page in the specified range is

written,

by the caller.

or
1inaccessible

does

not

exist.

Privilege Restrictions:

The user privilege PSWAPM is required to lock or unlock pages

The access mode of the
privileged

from memory.

than

the

<caller

access

that are to be unlocked.

4-173

must

equal

mode of the owner of the pages

SYSTEM SERVICE DESCRIPTIONS

SULKPAG

UNLOCK

PAGES

FROM MEMORY

Notes:
If

than

unlocked,
If

one

the

the pages

error

return

occurs

array,

successfully
were

Locked

while

unlocked

multiple

requested,

both

before

are

the

automatically

deletes

the

pages.

4-174

one

pages

are

indicates
the

1longwords

-1.

pages

system

should

unlocked

unlocked,

contain

the

page is being unlocked and it
is
specifically
which
pages had been

determine

error
of

time.

being

unlocked,

pages that were
occurred.
1If no pages

the

unlocked

necessary
previously

return

image

address

array

"exit,

when

SYSTEM SERVICE DESCRIPTIONS

SULWSET
$ULWSET - UNLOCK PAGES FROM WORKING SET

4.75

The Unlock Pages from Working Set system service allows a

process

that were previously locked in the
page
for
candidates
and become

pages
group of
wunlocked
to be

a
that
specify
are
working set

replacement like other working set pages.
Format:

Macro

1inadr

SULWSET

,[retadr]

,[acmode]

High-Level Language Format:

SYSSULWSET (inadr , [retadr]
inadr

,[acmode])

ending
address of a 2-longword array containing the starting and
If the starting
of the pages to be unlocked.
addresses
virtual
1is
page
single
a
same,
the
are
address
and ending virtual

Only

unlocked.

addresses is used;

the

virtual page number portion of the virtual

the low-order 9 bits are ignored.

retadr

address of a 2-longword array to receive the starting and

virtual addresses of the pages actually unlocked.
acmode

access mode on behalf of which the request is

belng

ending

made.

The

specified
access
mode
is maximized with the access mode of the
caller.
The resultant access mode
must
be
equal
to
or
more
privileged
than
the
access
mode
of the owner of each page in
order

Return

unlock

the

page.

Status:

SS$_WASCLR

Service successfully completed.

pages was previously unlocked.

At least one

SS$_WASSET

Service successfully completed.
All of
~ previously locked in the working set.

the

specified

the specified pages

were

SS$_ACCVIO

The

input array cannot be

A page in the specified range
exist.
|

written,

SS$_NOPRIV

A page

the

caller.

in the specified range

read,

1is

4-175

the output array cannot be

1inaccessible

does

in the system address space.

not

SYSTEM

SULWSET
Privilege

SERVICE

UNLOCK

DESCRIPTIONS

PAGES

FROM WORKING

SET

Restriction:

The

access

than

the

mode

access

the

caller

mode

unlocked.

must

the

owner

equal
of

the

pages

that

privileged
are

Notes:

than

one

determine
unlocked, the
If

the

error

return

page

pages

being

occurs

array,

should
while

successfully unlocked
were
unlocked,
both

contain

specifically

unlocked

which
be

unlocked

multiple

and

pages
one

had
at

been
a

necessary

previously

time.

pages are
being
unlocked,
indicates the pages that were
before the error occurred.
If no pages
1longwords
1in the return address array

requested,

-1.

4-176

SYSTEM SERVICE

DESCRIPTIONS

SUNWIND
4.76

SUNWIND - UNWIND CALL STACK

a condition handling
system service allows
The Unwind Call Stack
stack to a specified depth.
call
the procedure
unwind
to
routine
a new return address can be specified to alter the flow of
Optionally,
execution when the topmost call frame has been unwound.
Format:

Macro

SUNWIND

High-Level

[depadr]

Language

, [newpc]

Format:

ND
( [depadr]
SYSSUNWI

, [newpc])

depadr

is
to which the stack
address of a longword indicating the depth
A depth of 0 indicates the call frame that was
unwound.
be
to
of
caller
the
indicates
active when the condition occurred, 1
indicates the caller of the caller of the frame,
2
frame,
that
as 0 or less, no unwind occurs;
If depth is specified
and so on.
1is
address
no
If
returned.
1is
code
status
successful
a
frame
the
of
caller
specified, the unwind is performed to the
that established the condition handler.

newpc

address to be given control when the unwind is complete.

Return

Status:

SS$ NORMAL

~ Service successfully completed.

SS$

ACCVIO

7 The call stack is not accessible to the caller.
is

detected

This

condition

when the call stack is scanned to modify the return

address.

SS$ INSFRAME

There are insufficient call frames to

SS$_NOSIGNAL

Warning.

condition.

SS$_UNWINDING

Warning.

wunwind

the

specified

active

for

exception

depth.

signal

'currently

An unwind is already in progress.

4-177

SYSTEM

SUNWIND

SERVICE

DESCRIPTIONS

UNWIND

CALL

STACK

Note:
The actual unwind
return
addresses

is
1in

not
performed
immediately.
the call stack are modified so

condition handler returns, the unwind
each frame that 1s being unwound.

procedure

Rather,
that when

the
the

called

from

1is

call

\\fi__//

For an explanation
of condition handling and an example of
SUNWIND, see Section 3.7, "Condition Handling Services."

4-178

SYSTEM SERVICE DESCRIPTIONS

SUPDSEC
4.77

SUPDSEC -

UPDATE

SECTION

FILE

DISK
.

The Update Section File on Disk system
service
writes
all
modified
pages
1n
an
active
private or global section back into the section
file on disk.
One or more I/O
requests
are
queued,
based
on
the
number of pages that have been modified.
-

Macro

Format:

SUPDSEC

1inadr ,[retadr]
,[acmode]
, [astadr]
,[astprm]

,[updflg]

,[efn]

,[iosb]

High-Level Language Format:
SYSSUPDSEC (inadr
/,
SN

, [retadr]

, [astadr]

inadr

,[acmode]

,[updflg]

,[efn]

|
address

,[iosb]

,[astprm])

|
of
a

2-longword

array

containing

the

starting

and

ending

virtual
addresses
of
the
pages to be potentially written back
into the section file.
The SUPDSEC system service locates
pages
within this range that were modified and writes only the modified
pages (with
contiguous
pages,
if
convenient)
back
1into
the
section file on disk.

the

starting

and

single
page
1is
number portion of
bits are ignored.
retadr
address

ending

virtual

a candidate
the virtual

2-longword

array

virtual
addresses of the
in the first I/0 request.

addresses

for writing.
addresses is

first

receive

and

last

are

Only
used;

the

starting

pages

same,

the virtual page
the low-order 9
|

queued

and

ending

for

writing

acmode
|
access mode on behalf
of which the
service
1is
performed.
The
specified
access
mode
1is maximized with the access mode of the
caller.

the

The

caller

resultant

can

actually

access

mode

write

the

used

determine

whether

pages.

updflg

update
0

indicator

(the

for

default),

read/write global

all

read/write

pages

sections.
in

the

global

specified

section

are

updated in the section file on disk, regardless of whether or not
they
have
been
modified.
1If specified as 1, it indicates that
the caller 1s the only
process
that
is
actually
writing
the
global
section,
and
that
only
those pages that were actually
modified by the caller are to be written.
'

iosb

efn
number

specified,

not

event

flag

address of

a quadword

completion

status

set

defaults

when

I/0O
the

when

status

block

section

4-179

the

section

file

updated.

file

that

has

been

receive

updated.

the

SYSTEM SERVICE DESCRIPTIONS
SUPDSEC - UPDATE SECTION FILE ON DISK
astadr
address

executed
the
the

the

entry

~
mask

when

the

section

AST

service routine
section file update

AST

parameter

file

AST

has

service

been

executes at the
was requested.

passed

the

access

1If

mode

service

specified,
from

which»

AST

routine

updated.

astprm

|
of

routine.

Return Status:
SS$

NORMAL
Service

|
successfully

|
completed.

One

I/0

queued.

SS$_NOTMODIFIED

Service

completed.

pages

SS$_EXQUOTA
The process

exceeded

event

flag

flag was

' SS$_NOPRIV

the

output

address

its

AST

limit

quota.

number

was

specified.

page

the

specified

SS$_PAGOWNVIO

range

the

SS$_UNASCEFC

process

specified

event

system

address

space.

by an
caller.

access

mode

A page in the specified range is owned
privileged than the access mode of the

The

address

illegal

SS$_IVSECFLG
An invalid

input

no I/O requests

|
has

SS$_ ILLEFC

the

queued.

SS$_ACCVIO
|
|
The 1input address array cannot be read,
array cannot be -written, by the caller.

that had been modified;

not

associated

with

the

cluster

containing

the

flag.

Privilege Restrictions:

” Only pages that are owned
by the calling
access

mode

can

updated.

less
|

privileged

Resources Required/Returned:

and,
quota

direct

I/0O

1limit

if the ASTADR argument
(ASTLM).

Disk

system

(DIRIO)

specified,

service

queue

the

requires
I/O

the

request;

the process's AST

limit

N —_——

process's

The Update Section File

A\,

successfully

range were section pages
were

|
were

requests

4-180

SYSTEM SERVICE DESCRIPTIONS

SUPDSEC

UPDATE

SECTION

FILE

DISK

Notes:

The

SUPDSEC

the

system

service

scans

pages

starting

the

address
contained
in
the
first
1longword
of the location
pointed to by the INADR argument and ending with the
address
in
the
second
longword.
Within
this
range,
pages
are
candidates for
being
updated
based
on
whether
they
are
read/write
pages
that were modified.
Unmodified pages that
share a cluster with modified pages are
also
written.
The
ending address can be lower than the starting address.

longwords
case,

SUPDSEC

system

service

returns

error,

in the return address array contain a -1.

I/0 completion

not set,

not

posted.

no AST

indicated,

is delivered,

that

is,

the

both

1In this

event

flag

and the I/O status block

1is

‘

Proper use of this service requires the caller
completion
of
the
status from SUPDSEC.

to synchronize

wupdate request
by
checking the return
If
SS$ NOTMODIFIED
1s
returned,
the

"caller
can continue.
If SSS NORMAL is returned, the caller
should wait for the I/0 to complete and then check the status
returned

in the

When all

I/0

filled

The

status

is complete,
as

block.

the

I/0

status block,

follows:

first word

~output

I/0O

specified,

contains

the

completion

request.

status

—

the

If an error occurred in the I/O request, the first bit in
the
second 'word
1s
set
1f a
hardware write
error
-

occurred.

1if

The

second longword contains

first page

that was

the virtual

not written.

4-181

address

the

SYSTEM

SERVICE

DESCRIPTIONS

SWAITFR
4.78

SWAITFR - WAIT

FOR SINGLE

EVENT FLAG

The Wait for Single Event Flag system service tests a

specific

flag
and
returns
1immediately
1f
the
flag is
process 1is placed in a wait state until the event

Otherwise,
is set.

Macro

set.
flag

event
the

Format:

efn

SWAITFR

High-Level

Language

Format:

SYSSWAITFR (efn)
|

efn
number

Return

the

event

flag

for

which

wait.

Status:

SS$_NORMAL
Service

successfully

completed.

SS$ ILLEFC
An

1illegal

event

flag

number

was

SS$_UNASEFC
The process 1s not associated
specified event flag.

specified.

with

the

cluster

'
the

containing

Note:

The

walt

state

asynchronous

caused
system

this

trap

the AST executes 1s less than
which the wait was issued and
at

that

access

resumes

can
(1)

the

or equal to the
(2) the process

interrupted
access

mode

by
at

access
mode
is enabled for

which

from
ASTs

mode.

When the AST service
routine
repeats the S$WAITFR request.
process

service

(AST)

execution.

completes
execution,
the
system
If the event flag has been set, the
|
|

4-182

' SYSTEM SERVICE DESCRIPTIONS

SWAKE
4.79

SWAKE

- WAKE

The Wake system service activates
a process that has placed itself
a

state

Macro

hibernation with

the

Hibernate

(SHIBER)

system

service.

Format:

SWAKE

High-Level

[pidadr]

,[prcnam]

Language Format:

| SYSSWAKE([pidadr]

, [prcnam])

pidadr
address

of a longword containing
process to be awakened.

the

process

1identification

prcnam

address of a character strlng
name
string.
The
name
1s

descriptor p01nt1ng to
implicitly
qualified

number of

the

process

issuing

the
process
by the group

wake.

,{\

If neither a process identification nor a process name
1is
specified,
the
wake
request
1is for the caller.
For details on how the service
interprets the PIDADR and PRCNAM arguments, see Table 3-3.
Table
3-3
is in Section 3.5, "Process Control Services."
|

Return Status:
SS$_NORMAL
Service

successfully completed.

SS§_ ACCVIO
The
the

process
process

name string or
identification

’

string
cannot

descriptor cannot be
read,
be written, by the caller.

SS$_IVLOGNAM

The specified process name string has a length of 0 or
than

has

characters.

SS$_NONEXPR
Warning.
The specified process does not
process identification was specified.

exist,

invalid

SS$_ NOPRIV
The

process

does

not

have

the

privilege

wake

the

process.

Privilege Réstrictions:

User privileges are required to wake:
@

Other

Any

processes

other process

the
in

same

the

group

system

4-183

(GROUP

(WORLD

privilege)

specified

SYSTEM SERVICE DESCRIPTIONS
SWAKE

- WAKE

Notes:

If one or more wake requests are 1issued for a process that is
"not
currently
hibernating,
a
subsequent hibernate request
completes
1mmediately,
that
1is,
the
process
does
not

“hibernate.

count

1is

maintained

of outstanding wakeup

requests.

A hibernating process can also be awakened with the
Wakeup

(SSCHDWK)

system

For an example of the SWAKE system service and
3.5,

"Process

discussion
Control

the

Services."

Section

see

mechanism,

hibernate/wake

Schedule

service.

4-184

SYSTEM SERVICE DESCRIPTIONS

SWFLAND
4.80
The

$WFLAND - WAIT FOR LOGICAL AND OF EVENT FLAGS

Wait for Logical AND

Event Flags

system

service

allows

process
to specify a mask of event flags for which it wishes to walt.
All of the indicated event flags within a specified event cluster must
be
set;
otherwise,
the process is placed in a walit state until they
‘
|
are all set.
Macro Format:
efn

SWFLAND

,mask

High-Level Language
SYSSWFLAND
(efn

number

mask

,mask)

any event

flag within

32-bit mask in which bits set
within

Return

the cluster

that must be

the

Service

being used.

indicate the

set.

event

flags

successfully completed.

SS$_ILLEFC

cluster

Status:

SS$_NORMAL

efn

Format:

illegal event flag number was specified.

SS$_UNASEFC

The process is not associated with
specified event flag.

the

;

|
cluster

containing

the

Note:
The wait state caused by this service can be interrupted
by
an
asynchronous
system
trap
(AST) if (1) the access mode at which
the AST is to execute is less than or equal
to the
access
mode
from which the wait was issued and (2) the process is enabled for
ASTs at that access mode.

When the AST service :routine
repeats
all set,

completes

the
SWFLAND
request. If the
the process resumes execution.

execution, the system

specified event

flags

For an example of the SWFLAND system service, see Section 3.1,
Flag

Services."

4-185

are

"Event

SYSTEM

SERVICE

DESCRIPTIONS

SWFLOR
i

4.81
The

SWFLOR - WAIT FOR LOGICAL OR OF
Wait

for

Logical

OR of

Event

EVENT FLAGS

Flags

system

service

tests

the

event

flags
specified
by a
mask
within
a specified cluster and returns
immediately if any of them is set.
Otherwise, the process
1is placed
in a wait state until at least one of the selected event flags is set.

Macro

Format:

SWFLOR

High-Level

efn

,mask

Language

Format:

SYSSWFLOR (efn

,mask)

number

event

any

flag

within

the

cluster

set

1nd1cate

being

|
used.

mask

32-bit mask
interest.

Return

in which

bits

the

event
|

flags

Status:

SS$_NORMAL
Service

SS$

successfully

ILLEFC
An illegal

event

completed.

flag

number

was

spec1f1ed

' SS$_UNASEFC
The

process

specified

event

not

associated

with

flag.

the

cluster

containing

the

Note:
The wait state caused
asynchronous
system

by this service can be
trap
(AST) if (1) the

the AST is to execute is less than
from which the wait was issued and

ASTs

that

access

interrupted
by
an
access mode at which
or equal to
the
access
mode
(2) the process is enabled for

mode.

When the AST service
routine
completes
repeats
the
S$SWFLOR request.
If any of
set, the process resumes execution.

4-186

execution,
the
system
the event flags has been

/’

S~ )

APPENDIX

SYSTEM SYMBOLIC DEFINITION MACROS

This appendix summarizes system-provided macros that define symbolic
values for use with system services, and lists the symbols defined by

~each macro.

The macros listed in this appendix are:
Symbols Defined

- Macro

for

I/O function codes

SIODEF

Symbolic names

SMSGDEF

Symbolic names to identify mailbox message senders

SPRDEF

Internal processor

$PRTDEF

Symbolic names for hardware protection codes

SPSLDEF

registers

field
and
mask
(PSL)
longword
status
Processor
definitions, and symbolic names for access modes

$SSDEF

Symbolic names for

system status codes

The symbolic définitions generated by each of these macros are listed
Definitions generated by the following macros
on the following pages.
manual (consult the Index for page number
this
in
elsewhere
are listed
references).

Macro

Symbols Defined

SACCDEF

Accounting manager

termination

request type

and

message

codes

and

accounting

process

record

information offsets

SCHFDEF

Condition handler argumeht offsets

SDIBDEF

Device information buffer offsets

$SJBCMSGDEF

Job controller

SJPIDEF

Job/process informatipn request type codes

SOPCDEF

Operator communication manager request

SPQLDEF

Quota types for process creation quota list

SPRVDEF

User

SSECDEF

Attribute flags for private/global section

$SMRDEF

Symbiont manager request type and option codes

buffer offsets,

return status codes

and return status codes

codes,

type

privileges

and mapping

A-1

creation

SYSTEM

A.1

USING

SYSTEM

SYMBOLIC

that

calls

for

any

library, _STARLET.MLB,

system

STARLET.Mfor
LB

these

the

symbols.

macros,

macro

When

the

procedure:

Create

the

macro

a source program
automatically
searches

value.
numeric

To
obtain
a
order, use the

1list
of
following

with

$roIEF

contains

assemble

assembler

file

you

definitions.

Each symbol name has a unique numeric
symbols,
1in
alphabetic order and in

MACROS

SYMBOLS

The default system macro

definitions

DEFINITION

the file

type

MAR

containing

the

lines:

GL.ORAL

» EENTI

where xx is the prefix of the macro defining the symbols
need,

for

Assemble
$

where

the

file

MACRO

$SSDEF

with

all

linker

create

the

A.2

SIODEF

‘The
are

function
grouped

requested.

symbols
more

than

numeric

MACRO

named

defined
one

values

SYMBOLIC

For

your

macro

for

file:

file
containing
defaults to MAR.

assembler,

file-name.MAP,
the
in

FOR

macro,

the

same

than

one

I/O

requesting

the

contains a list
numeric

assembly

set

FUNCTION

modifiers defined
devices for which

convenience,

the

file-rname

NAMES

codes and function
according
to the

listed.

full map

LINK/MAF/FULL/ZNOEXE

the

can specify

obtain

also

command:

is the file name of the
call.
The input file type

The linker map file,

are

MACRO

vyou

file-rmame

macro

the

S$MSGDEF.

Link the object module created by the
the

You

file-name

SXXDEF

example

arguments

order.
source

file

definitions.

CODES

in the SIODEF
macro
the I/0 operation is

(Pl,

P2,

and

on) ,

SYSTEM SYMBOLIC DEFINITION MACROS
A.2.1

Terminal Driver

Modifiers

Arguments

Functlons

IOS$SM NOECHO

Pl - buffer address

I05 READVBLK

I0$~ READLBLK
I0$” READPBLK
'I0$_READPROMPT

IOSM CVTLOW
IOSM NOFILTR
IO$M_TIMED

P2 - buffer size
P3 - timeout
P4 - read terminator

block

address

IOSM PURGE

P5 - prompt string
P6

'10$ WRITEVBLK
I0$ WRITELBLK
I0$ WRITEPBLK

prompt

10$M_TRMNOECHO
:

string

buffer sizel

I0$M CANCTRLO
IOSM ENABLMBX
IOSM NOFORMAT

P1 - buffer address
P2 - buffer size
P3 - (ignored)

P4 - carriage control

specifier?

I0$ SETMODE
I0$_SETCHAR

Pl - characteristics
buffer address

I0$_SETMODE!IO$M_HANGUP
I0$_SETCHAR!IOS$SM_HANGUP

(none)

IOSM DSABLMBX

buffer addressi

P2
P3
P4
P5

(ignored)
speed specifier
fill specifier
parity flags

I0$ SETMODE!IO$M CTRLCAST | P1 - AST service

routine address

I0$ SETMODE ! IO$SM_CTRLYAST

IOS SETCHAR!IOSM CTRLCAST | P2 - AST parameter
IOS$S SETCHAR!IO$M CTRLYAST | P3 - access mode to
deliver AST
T

%Only for I0$ READPROMPT

Only for IO$ WRITEBLK and IO$ WRITEVBLK

A.2.2

Disk Drivers

Modifiers

Arguments

Functions

I0S$READVBLK | Pl - buffer address
I0$ READPBLK

I0$_WRITEVBLK

P3- disk address

TOS$M_INHRETRY

IOSM INHSEEKL
-

I0$M_DATACHECK

I0OS_READLBLK | P2 - byte count
I0$_WRITELBLK
I0$_WRITEPBLK

I0S$SINHRETRY
|
|

I0S_SETMODE
I0$ SETCHAR

Pl - characterlstlc buffer
address

I0$_CREATE
10S_ACCESS

Pl - FIB descriptor address | IO$M_CREATEZ
IOSM_ACCESS?
P2 - file name string

IOS_DEACCESS
IO$_MODIFY
IOS DELETE

‘

address
P3 - result string length
P4

address
result string descrlptor
address

attribute

address

list

lOnly for IO$ READPBLK and IO$ WRITEPBLK
3Only for I0$ CREATE and IOS$ ACCESS
" CREATE
Only for IO$

and I0$

DELETE
A-3

IO$M DELETE
-

.,___
P

SYSTEM SYMBOLIC DEFINITION MACROS
A.2.3

Magnetic

Tape

Drivers

Functions

Arguments

I0$_READVBLK

Modifiers

|Pl - buffer address

IO$_READLBLK
I0$_READPBLK

|P2

byte

IO$M_DATACHECK

count

IOSM_INHRETRY
IOSM_REVERSEL

I0$_WRITEVBLK

IO$M_INHEXTGAP?2

I0$ WRITELBLK
I10$_WRITEPBLK
I0$ SETMODE
105 _SETCHAR

10$_CREATE
10$_ACCESS

Pl - FIB descriptor address
P2 - file name string

IO$_DEACCESS
I0S MODIFY
105 _ACPCONTROL

characteristics
address

address

result

string

length

string

descriptor

result

address
P5

| IO$M CREATES
TOSM_ACCESS
IOSM DMOUNT'

attribute

I0OS_SKIPRECORD|P1

I0$S_MOUNT

IOSM_INHRETRY
IOSM_INHEXTGAP

address
P4

I0S SKIPFILE

buffer

list

skip

tape

skip

records

address

marks

IO$SM_INHRETRY
IOSM_ INHRETRY

- (none)

I0$_REWIND
IO$_REWINDOFF

(none)

'I0$_WRITEOF

(none)

IO$M_INHRETRY
IOSM NOWAIT

IOSM_ INHEXTGAP

IO$M_ INHRETRY

IOS_SENSEMODE.
Only

read functions
for write functions

Only
Only

for

A.2.4
-

IO$M_INHRETRY

for

Only

(none)

for

IO$ CREATE and
I0$ ACPCONTROL

IO$ ACCESS

Line Printer Driver

Functions

Arguments

I0OS _WRITEVBLK | P1
I0$_WRITELBLK | P2
IOS_WRITEPBLK
P3
|

buffer address
buffer size
(ignored)

carriage

Modifiers

(none)

control

specifierl

I0S$ SETMODE

I0S$_ SETCHAR

Pl - characteristics buffer
address

lonly for 10$_WRITEVBLK and IO$ WRITELBLK

(none)

SYSTEM SYMBOLIC DEFINITION MACROS
A.2.5

Card Reader

Driver

‘Functions

Arguments

Modifiers

IO$_READLBLK
I0$ READVBLK

Pl
P2

buffer address
byte count

IO$M_BINARY
IO$M_PACKED

IOS

characteristics

(none)

I0$ READPBLK
SETMODE

I0S$_SETCHAR

buffer address

I0S _SENSEMODE | (none)

A;2.6

Mailbox Driver
Functions

Arguments

Modifiers

I0S_READVBLK

Pl - buffer

address

I0S_READLBLK

size

10$~_ READPBLK

buffer

IOSM NOW

I0$_WRITEVBLK
I0$_WRITELBLK
I0$_WRITEPBLK

I0$_WRITEOF

(none)

I0$_SETMODE!IOSM_READATTN | P1 - AST address
IOS _SETMODE!IOSM_WRTATTN

A.2.7

DMCll

- AST parameter

Driver

Functions

Arguments

~Modifiers

I0S_READLBLK

Pl - buffer address

I0S_READVBLK

P6 - diagnostic buffer? | IO$M_ENABLMBX?

I0$_READPBLK

- I0$_WRITELBLK

P2 - message size
-t

- characteristics

I0$_SETCHAR
IO$_SETMODE!IO$M_ATTNAST

I0OS_SETCHAR!IOSM ATTNAST

buffer
Pl

- AST

IO$_SETCHAR!IO$M_STARTUP

service

(ignored)

AST

I0$_SETCHAR!IOS$M_SHUTDOWN
I0OS SETMODE!IOSM_STARTUP

address

routine address

IO$ _SETMODE!IOSM_SHUTDOWN | P1 -

access

characteristics

block address

- characteristics

block

address

(ignored)

receive

messag e

blocks

%Only for IOS$S READLBLK and I0$ READPBLK
3Only
Only

for

mode

Pl
|

IOSM_NOWl

I0$_WRITEPBLK
I0$_WRITEVBLK

I0$_SETMODE

IOS$M_DSABLMBX

IOSREADPBLK and I0$ WRITEPBLK
IO$ WRITELBLK and I0§$WRITEPBLK

SYSTEM SYMBOLIC DEFINITION MACROS
A.2.8

ACP

Interface Driver

Functions

I0$_CREATE
I0S_ACCESS

. Modifiers

Arguments

Pl - FIB descriptor address
P2 - file name string

IO$M CREATEL
I0SM_ACCESS1

- I0$_DEACCESS
address
I0$ MODIFY |P3 - result string length
I0S DELETE
I0S ACPCONTROL|P4

address

result

string

attribute

|
descriptor

address

I0$_MOUNT

IO$M_DELETE?2
IO$M_DMOUNTS3

list

address

(none)

lOnly
for I0$ CREATE and IO$ ACCESS
2
Only for IO$ CREATE and IO$ DELETE

only for I0$ ACPCONTROL
A.3

SMSGDEF MACRO - SYMBOLIC NAME S FOR SYSTEM MAILBOX MESSAGES
Symbolic Name
MSGS

Meaning

TRMUNSOLIC

Unsolic ited
Unsolic ited

MSGS$STM CRUNSOLIC
MSGS DELPROC

MSGS$_SNDSMB
MSGS

DEVOFFLIN

Send to

process

symbiont

manager

Device

offline
- Termina 1 hangup
Device online

MSG$ TRMHANGUP
MSGS_DEVONLIN
MSGS OPRQST

Operato r

MSGS$ OPREPLY
MSG$_SMBINI
MSGS$__SMBDON

Operato r

Symbiont

Symbion t

request

initiated

MSGS_XM_DATAVL

Data

finished
accounting manager
av ailable (DMC-11)

MSGS~_XM_ATTN

MSGS INIOPR
MSG$_ABOOPR

Unit

attention

Abort

MSGS

Pause

printing
printing

MSG$

SNDACC

Send

MSG$~_XM_SHUTDN

MSGS

DISCON

MSG$_ EXIT

MSGS$_INTMSG
MSGS$ PATHLOST

MSGS$ PROTOCOL
MSGS REJECT
MSGS THIRDPARTY
MSG$_TIMEOUT

has

Unit sh utdown

(DMC-11)

Initiat e file printing

SUSOPR

MSGS RESOPR
MSGS$ DELSMB
MSGS SMBRSP
MSGS$ ACCRSP
MSGS ABORT
MSGS$ CONFIRM
MSGS_CONNECT

iil

Delete

terminal data
card reader data

file

Resume printing a file

Symbiont should delete itself
Symbiont response
Accounting manager response
Network partner aborted link
Network

connect

Network

inbound connect initiate
partner disconnected-hangup
partner exited prematurely
interrupt message; unsolicited

Network
Network

Network

confirm

path lost to partner
protocol error

Network

connect reject
third party disconnect

Network

connect

Network

timeout

data

SYSTEM SYMBOLIC DEFINITION MACROS

A.4

SPRDEF MACRO - SYMBOLIC NAMES FOR PROCESSOR REGISTERS
Symbolic Name
PRS

KSP

PR$_ESP
PR$_SSP
PRS_USP
PR$ ISP

PRS$ POBR

PR$TM POLR
PRS P1BR

PRS P1LR
PRS$ SBR
PRSTM SLR
PR$_PCBB

PRS_SCBB
PR$ _IPL
PR$ ASTLVL
PRS_SIRR
PR$_SISR
PR$S_MAPEN
PR$_TBIA

PRS

TBIS

PRS ICCS
PR$_NICR
PR$_ICR
PRS TODR

PR$_RXCS

PRS_RXDB
PR$_TXCS
PR$_TXDB
PR$_ACCS
PR$_ACCR
PRS_WCSA
PRS_WCSD
PRS SBIFS

PR$_SBIS

PRS

SBISC

PRSTM SBIMT
PR$_SBIER
PR$_SBITA
PR$_SBIQC
PR$_SID

A.5

|
Kernel stack pointer
Executive stack pointer

~Supervisor stack pointer
User stack pointer
Interrupt stack pointer
PO base register
PO limit register
Pl base register
Pl limit register

System base register
System limit register

Process control block base register
System control block base register

Interrupt priority level register

AST

level

~ Software
Software

interrupt request register
interrupt summary register

Mapping enable register
Translation buffer invalidate

all

Translation buffer invalidate single
Interval clock control status register
Interval clock next interval register
Interval clock interval count register
|
Time of day register
Console receiver control status register
Console receiver data buffer register
Console transmit control status register
Console transmit data buffer register
Accelerator control status register

Accelerator reserved

WCS address register
WCS data register
SBI fault status register
SBI silo register
SBI comparator register
SBI maintenance register
SBI error register

SBI timeout address register
SBI gquadword clear register
System identification register

SPRTDEF - HARDWARE PROTECTION CODE DEFINITIONS

Symbolic Name

Meaning

PRT$C_NA

PRTSC_KR

PRT$C_KW
PRT$C_ER
PRT$C_EW
PRTSC_SR
PRTSC_SW
PRT$C_UR
PRT$C_UW
PRTSC_ERKW

PRT$C_SRKW

PRTSC_SREW
PRT$C_URKW
PRTSC_UREW
PRT$C_URSW

access

Kernel read only
Kernel write
Executive read only
Executive write
Supervisor read only

Supervisor write

User
User

read only
write

Executive read; kernel write
Supervisor read; kernel write
Supervisor read; executive write
User read; kernel write
User read; executive write
User read; supervisor write
A-T7

SYSTEM

A.6

SYMBOLIC

DEFINITION

MACROS

S$PSLDEF MACRO - PROCESSOR STATUS LONGWORD SYMBOL DEFINITIONS
Symbolic

Name

Meaning
TBIT

PSLSV_TBIT

PSL$S_TBIT

enable

Length

field

TBIT enable

field

PSLSM_TBIT

Mask

PSL$S_IV

Length of integer overflow field
Mask for integer overflow field

PSLSV_IV
PSL$M

for

Integer

PSL$V_FU

TBIT

enable

overflow

field

‘Floating undefined field
Length of floating undefined field
Mask for floating undefined field
Divide by zero field
Length of divide by zero field

PSL$S_FU

PSLSM_FU
PSLSV_DV

PSL$S_DV
PSL$M_DV
PSL$V_IPL

Mask

for

divide

zero

Interrupt priority

PSL$S_IPL

Length

PSL$V_PRVMOD
PSL$S_PRVMOD

interrupt
processor

Length
of

PSL$V_CURMOD

Current

PSL$S_CURMOD
PSLSV_IS

Length

stack

PSL$S_IS

Length

PSLSM_IS

Mask

PSLSV_FPD

First part done
Length of first

PSLSM_FPD

Mask

PSLSV_TR

Trace

for

mode

current

Interrupt

PSL$S_FPD

priority
mode

processor

interrupt

trap

mode

field

field
mode

field

interrupt

first

field

previous processor

processor

for

field

stack

field
part done

part

pending

done

field

fleld
field

field

Length of trace trap pending field

PSL$S_TR

PSLSM_TR
PSL$V_CM

Mask

for

trace trap

pending

field

Compatibility mode field
Length of compatibility mode fleld
Mask for compatibility mode field

PSLSS_CM

PSL$M_CM

Symbolic Names for Access Modes

A.7

The

Name

Access

Mode

PSLSC_KERNEL

Kernel

PSLSC_EXEC
PSLSC_SUPER
PSLSC_USER

Executive

$SSDEF MACRO

$SSDEF macro

return

status

column,

below,
Type

Supervisor
User

SYMBOLIC NAMES

FOR SYSTEM STATUS

instruction defines
codes

and

indicates

Number
WO

Symbolic

for

one

symbolic names

exception

the

follow1ng

Meaning

warning

Successful completion
Warning return

Error

return

Severe

error

Condition

Exception

success

condition

return

condition

CODES

for

system service

names.

The

"Type"

SYSTEM SYMBOLIC

Status Code

SSS

ABORT

SSS$S”ACCONFLICT

SSS

Condition
Condition

ARTRES

sSevere

Warning
Severe

Warning
warning
Warning

SS$_BADFILEVER

SS$_BADIMGHDR

Severe

Warning

SS$_BADIRECTORY
SS$_BADPARAM

Severe

SS$_BADSTACK

SS$_BEGOFFILE
\\-v/’

Abort

Severe

SS$~_BADFILEHDR
SS$_BADFILENAME

SS$_BLOCKCNTERR

SS$_BREAK
SS$ BUFBYTALI

SS$_BUFFEROVF
SS$_BUGCHECK

SS$_CANCEL

Bad file header
Bad file name syntax
Bad file version number
Bad image header
Bad directory -file format
Bad parameter value

Block

count error

encountered

during

exception dispatch
Beginning of file

Breakpoint

instruction

fault

Severe

Device does not support
byte-aligned transfers

success

Output buffer overflow
Internal consistency failure
I/0 operation canceled
Channel usage interlocked
CLI forced exit
Change mode to supervisor trap

success
success
success

success
success

Severe

SS$__DATACHECK
SS$__DATAOVERUN
SS$_DEBUG

1is

fault

Warning
Warning
Condition

severe

CONTROLC

space

Bad attribute control list
Bad file header checksum
Syntax error 1in escape sequence

stack

Warning
Condition
Condition
Condition

SSS$STM CONTROLO
SSS$TM CONTROLY
SSS$TM CREATED
SS$_CTRLERR

AST

Bad

Warning

SS$_CONTINUE

File access conflict
Access violation
Access violation
MTAACP's virtual address
|
full
Reserved arithmetic trap

Severe

SS$_CHANINTLK
SS$ CLIFRCEXT
SS$_CMODSUPR
SS$_CMODUSER
SS$_COMPAT

Severe

Condition

SS$_BADESCAPE

.‘\-

Meaning

Severe

SS$_ASTFLT
SS$_BADATTRIB
SS$_BADCHKSUM

SS$

Type

warning

SS$TM ACCVIO
SS$ ACCVIO
SS$_ACPVAFUL

DEFINITION MACROS

Severe

Warning
Condition

Change

mode

user

Compatibility mode

trap

fault

Continue
execution
at
point
of
condition
;
Operation completed under CRTL/C
Output completed under CTRL/O
Operation completed under CTRL/Y
File did not exist;
was created
Fatal

controller

Write check error
Data

error

overrun

Command

interpreter

debugger

signal

Condition

Decimal overflow
Device active

SS$_DECOVF
SS$_DEVACTIVE
SS$_DEVALLOC

Warning

SS$_DEVALRALLOC

Device already
another user

success

Device

SS$_DEVASSIGN

Warning

job
Device

SS$_DEVFOREIGN

SS$ DEVICEFULL
SS$ DEVMOUNT

SS$~_DEVNOTALLOC
SS$ DEVNOTMBX"

Severe

Warning
Severe

allocated

already allocated

Device
Device
Device
Device
Device
Device

not allocated
not mailbox
not mounted

not

Device

SS$_DIRFULL

Warning

Directory 1is full
Fatal drive error
Duplicate file name
Duplicate process name

SS$_DUPLNAM

Severe

Warning
Severe

this
:

Severe

SS$__DRVERR
SS$_DUPFILENAME

has channels assigned
is mounted foreign
|
full - allocation failure
1s already mounted

SS$ DEVNOTMOUNT
SS$_DEVOFFLINE

Severe

to
|

in configuration

SYSTEM

Code

MACROS

Type

Meaning

SSS_ENDOFFILE
SS$ ENDOFUSRLBL

Warning
Warning

End
End

SS$_FCPREADERR

Warning

File

SS$_FCPREPSTN
55$_FCPREWNDERR
555 _FCPSPACERR
SS$_FCPWRITERR
SS$_FILACCERR

Warning
Warning
Warning
Warning
Severe

processor read error
File processor reposition error
File processor rewind error
File processor space error
File processor write error
Magnetic tape file access

.
,
SS$_FILALRACC
5S$ FILELOCKED

Severe
Warning

non-blank
File already accessed on
File is deaccess locked

SSS$TM
_FILESEQCHK

Warning

SSS_EXQUOTA

SS$_FILENUMCHK

Severe

Warning
Severe

SS$_FILNOTEXP

Severe

SS$_FLTDIV
SS$_FLTOVF
SS$_FLTUND

SS$_FORMAT
SS$_GPTFULL
SS$_GSDFULL
SS$

HANGUP

of
of

file reached
user labels

Exceeded guota

Warning

SS$ FILESTRUCT
SSS$ FILNOTACC

SSS$” FILNOTCNTG

|
channel

File ID file number check

File ID file sequence number check

Unsupported file structure level
File not accessed on channel

Severe

File is not contiguous as required
File not expired

~Condition
Condition
Condition

Floating/decimal divide
Floating overflow
Floating underflow

Severe
Severe
Severe

Invalid media format
Global page table full
Global
section
descriptor

Severe

full
Data

zero

table
|

set

hang-up

SSS” HEADERFULL

Warning

SS$_ILLBLKNUM
SS$ _ILLCNTRFUNC
SS$_ILLEFC

Severe
Severe
Severe

Illegal
Illegal
Illegal

logical block number
ACP control function
event flag cluster

~Severe

Illegal

I/0

SS$ IDXFILEFULL

SS$

ILLIOFUNC

SS$_ILLLBLAST

File header full

Warning

Index file full

Warning

Illegal

function

wuser

code

label

block address
Illegal page count
" Illegal sequential

AST

Severe
Severe

SS$_ILLSER

Severe
Warning

Illegal

service

call

number

Illegal

read

user

labels

SS$_INCVOLLABEL
SS$S INSFARG

Severe
Severe

Incorrect volume label
Insufficient call arguments

SS$_INSFWSL
SS$ INTDIV

Severe
Condition

Insufficient working set
Integer divide by zero

ILLUSRLBLRD

SS$_ILLUSRLBLWT
SSS INSFMEM
SSSZINSFRAME

Warning

Illegal write of user

Severe
Severe

SS$_INTOVF

Condition

SS$

IVADDR

Severe

SS$_IVCHNLSEC

Insufficient dynamic memory
Insufficient call frames to unwind

Severe

Invalid

channel

SS$_IVDEVNAM
SS$ IVGSDNAM
SSS IVLOGNAM

Severe
Severe
Severe

section
Invalid
Invalid
Invalid

device name
global section
logical name

SS$_IVPROTECT
SS$ IVQUOTAL

Severe
Severe

Invalid
Invalid

page protection
quota list

SS$:IVLOGTAB

SS$ IVSECFLG

Severe
Severe

IVSECIDCTL

SS$_IVSSQR
SS$_IVSTSFLG

Severe
Severe
Severe

address

Invalid I/0 channel

for

create

and

map

|
name

Invalid logical name table number
code

Invalid process/global section
flags

SSS

limit

Integer overflow
media

Severe

labels

Invalid

SS$_IVCHAN

control

|
parameter
operation

SS$_ILLPAGCNT
SS$_ILLSEQOP

SSS

DEFINITION

Status

SYMBOLIC

Invalid

section

Invalid
Invalid

system
status

match control

identification
service
flag

request

SYSTEM

SYMBOLIC

Status Code

Type

SS$_IVTIME
SS$”_LCKPAGFUL

Severe

DEFINITION MACROS
Meaning
Invalid time

No more pages

can

locked

1in

memory

- 6S8$

LENVIO

SS$ LKWSETFUL
SS$_MBFULL
SS$_MBTOOSML

SS$_MCHECK
SS$_MEDOFL

SS$”MSGNOTFOUND
SS$_MTLBLLONG
'§SS$ MUSTCLOSEFL

SS$_NOAQB

SS$_NODATA
SS$_NOHANDLER

'SS$” NOHOMEBLK
SS$_NOIOCHAN
SS$_NOLINKS

SS$_NOLOGNAM
SS$_NOMBX

Severe

Address space length violation
Locked portion of working set
full

Warning
Severe

Mailbox full
Mailbox is too

Severe

Detected

Severe

Medium offline

success
severe

“Warning
Severe
Severe

Warning
Warning
Severe
Severe

Severe

small

hardware

for

1is
-

request

error

Message not in system message file
be
Magnetic tape volume label can

no more than six characters
Must close file
ACP queue header not found
Mailbox empty
No condition handler found
Home block not found on volume
No I/0 channel available
No slots in logical 1link vector
No logical name match

Severe

No associated mailbox for

SSS_NOMOREFILES

Warning

SSS_NONEXPR

SSS$_NONLOCAL

Warning
Warning

SS$_NOPRIV

Severe

No more files
Nonexistent drive
Nonexistent process
Nonlocal device
No privilege for attempted
operation

inbound

connects

SS$_NONEXDRV

. SS$ NORMAL

SS$” NOSIGNAL
SS$” NOSOLICIT
SS$_NOSUCHDEV
SS$

NOSUCHFILE

SSS$” NOSUCHNODE
SS$ NOSUCHSEC
SS$” NOTAPEOP
SS$”NOTFILEDEV
SSS NOTINTBLSZ
SS$_NOTLABELMT

SS$_NOTMODIFIED
SS$_NOTNETDEV
SS$_NOTRAN

SS$_NOTSQDEV

Severe

success

Warning
Severe

Warning
warning

Normal successful completion
No signal currently active
Interrupt message not solicited
No such device available
No

such

file

Warning

Specified node does not exist
No such (global) section

Severe

tape

operator

Severe

Device is not file-structured
Block size is greater than 2048

Severe

Not

labeled

severe

Success
Severe

success
severe

tape

No section pages were modified
Not a network communication device
No string translation performed
Not sequential device
Opcode reserved to customer fault
Opcode reserved to DIGITAL fault
|
Operation incomplete

SS$_OPCCUS
SS$_OPCDEC
SSS$” OPINCOMPL

Condition
Condition

- Page

owner

SS$_PAGRDERR
SS$ PARITY

Condition

Page

read

Severe

Parity error
Partial escape

SS$__PAGOWNVIO
SS$TMPARTESCAPE
SS$_PFMBSY
SS$TM

RADRMOD

SS$ REJECT

sSevere

Severe

Condition
Severe

SS$_REMOTE

success

SS$_RESIGNAL
SS$ _RESULTOVF
SS$_ROPRAND

Warning

SS$_SECTBLFUL
SS$_SSFAIL
SS$”SUBRNG

violation

error

Page fault monitor 1in use
Reserved addressing fault
Network connect rejected
on
completed
Assignment

" remote

node

Severe

Condition
Severe

‘COndition

Condition

Resignal condition to next handler
Resultant string overflow
Reserved operand fault

Section table

(process/global)

full

System service failure exception
Subscript

A-11

range

trap

SYSTEM

Status

SS$

Code

SUPERSEDE

SSS$STMTAPEPOSLOST
SS$__TBIT
SS$

TIMEOUT

SS$”TOOMANYVER
SS$_TOOMUCHDATA

SYMBOLIC

DEFINITION

MACROS

Type

Meaning

success

Logical name superseded
Magnetic tape position lost
Tbit pending fault

Severe

" Condition
Severe

Device

Warning

Too

Severe

Too

timeout

many

higher file
much optional or

versions
1nterrupt

msg

data

SS$_UNASEFC

Severe

Unassociated

SSS_UNSAFE

SS$_UNWIND
SS$_UNWINDING
SS$_VASFULL

sSevere

Drive

Warning
Warning

Unwind currently in progress
Unwind already 1n progress
Virtual address space full

SS$_VECINUSE

Severe

AST

Severe

Volume

Warning

Waiting

Success

Successful

SS$_VOLINV
SS$_WAITUSRLBL
SS$_WASCLR
SS$_WASECC

Severe

event

flag

cluster

unsafe

vector

already

enabled

1invalid

for

user

state

labels

was

clear

transfer;

data

check
success
Severe

Severe

Previous state was set
Write lock error
Wrong ACP for device

s, -

SS$_WASSET
SSS_WRITLCK
SS$_WRONGACP

APPENDIX

PROGRAM EXAMPLES

are
following pages
the
on
The sample programs presented
useful
any
perform
not
do
s
program
self-documenting. Note that these
work: they are intended only to illustrate how to call various system
|

services.

LTITLE
Br @A»

+IDENT

s @y

$ASSIGN

SYSTEM

SERVICES

TEST

(Assidn

I/0 Charnel)

> P

$OUTFUT (form of Queue [/0 Reauest and Wait For Event Flag)
$NUMTIM (Convert Rimarwe Time to Numeric Time)

> Er >

$RINTIM (Cormvert ASCII String to Rinary Time)
$SETIMR

(Set

Timer)

$WAITFR (Wait for Single Event Flag)
$READEF (Read Event Flads)
$SETFRN (Set Frocess Name)

WP G
Mr

/01/

ORION uses the following suwustem services:

This samrle srodgram illustrates?

WEs NP W NP OSSP WP B> Er 6 > 6> P E> NP > TP NP g3 gy WEr Q> E» > > S>> Ey W u»

J," N
N

ORION

1. Assidrning an I1/0 charnnel to a terminal and writing messades

to the termimal. The device name 1% srecified by the lodical name
termirnal. Before ORION is rumy the logical mname must he assigned
an

eauivalence

device

name.

2, Using the $NUMTIM sustem service to firnd out whether the
current time is bhefore or after noorn. A call to $SETIMR is
made cornditionallwy if the time is rrior to noor.

Z, How to obtain a delta time value 1in the suystem Fformat to use
. as inrut to the Set Timer ($SETIMR) sustem service.
4, Calls to the Set Timer sustem Service.

d by 3 wait for the
A. Event flag — The $SETIMR call 1is followe
calls
srecified event fladg. When the Limer exsiresy the srodram
flad
event
the
of
status
current
the
s
disrlaw
and
$READEF
Coecluster.

l.
E. AST routime — ome AST routine is for a delta time interva
either
In
time.
te
absolu
an
for
is
)
The other (conditional
casey the srodram continues exwecution and will nhe interrurted
when the timer recuests are srocessad,

ter

m =romerts for a charac
5. An examle of terminal insut. The srogHra
s.
strimng to bhe used as Lhe process Name of the current Froces
e.
servic
sustem
N
$SETFR
the
to
inrut
3%
name
this
Thern it uses

PROGRAM

EXAMPLES

AGE

JORTTL

SYMROLS

library

calls

AND DATA AREAS

y
y

Macro

¥
$IOQ%E

SOSTNEF
SREADEFDEF

;

slefime

I/0

ylefine

suystem

furnction

status

codes

slefine

offsets

for

values

$READNEF

Local

macros

defined

srivate

macro

;

library

NESCRIFTOR

+MACRO

tGernerate

DESCRIFTOR

CLLONG
«LLONG

LARELL

LAREL1L:

+ASCIITI

NTEXTN

character

strind

descrirtors

TEXTyPLAREL1y?LLARELZ

LAREL2-LAREL
1L

LARELZ2:
cENDM

NESCRIFTOR

MESSAGE

TMACRO

|
MESSAGE
$OUTFUT

RSEW

;

$0utfiut

messades

formatted

FAO

CHAN=TTCHANss BUFFER=FAQRUF y LENGTH=FAOLEN
,

FRROR

+ ENIIM

MESSAGE

,PSECT

RODATAs NOWRT y NOEXE

+SBTTI.

Read-0nly

Data

Areas

Local

Read/Write

;

MER

LTET

TTNAME:

lats

DESCRIFPTOR <TERMINAL:-

Terminmal

lodical mame

;
.
5 FAO conmtrol strings and data for timer (AST and event flag) tests
ASCNOON!

DESCRIFTOR <-- 12:00:00.00x

TENSEL: LNESCRIFTOR <0 00100310

NISFLLAYEFN?

DESCRIFTOR <CLUSTER 2 CONTENTS:

TIMSTRS
NOONMSG:

sNoorn im ASCII format

sTernn seconds delte time im ASCII format

tNisrlayw cluster contents
:

iNisrlay messade after event flad wait

NESCRIFTOR <V /TIMER ENTRY FROCESSEDs
LASCIC

SECMSGDESCT

CLUSTER 2 o=

iNiserlay messade at noon

/IM YOUR TIME AST ROUTINES

DESCRIFTOR <1 /TIME AST ROUTINES:

TWENTY{ L.ONG

wlO*lOOO*lQOO*Rwal

IT’S NOON. ../

ilisrlaw message from AST routine

DELTA TIME

1XT>

20 seconds delte time

PROGRAM EXAMPLES

+FAGE
’
y

Arnnouncement

messadges

FAOSTR

sMaster

corntrol

sNames messade

NESCRIFTOR <!/0RION: 1AC =

string

Arnauncement messadges and lengths for outrutting

’

HELLOS:

LASCII

HELLOLEN:

+LLONG

/HELLO...MY

NAME

HELLOLEN~-HELLD

TIMERMSG:
+ALBCTIT

JREGINNING

TIMERLEN:?
« LONG

TIMERLEN~-TIMERMSG

S
EFNWATITMSGE
+ASCTI

EFNWAITLEN:
«LONG

ASTWAITMSEG
I
+ASCT
|
ASTWATITLEN?S
« LONG

/TIMER SET:

FROMFT?

ASCII

FROMFTLEN:?
+ L.ONG

/TIMER SETF

ERRSTR

TOERRSTR

AST

IN 20 SECONDS/

inrut

JENTER 1-1% CHARACTER NaME FOR FROCESS:/
FROMFTLEN-FROMFT

Error messasge control

WAIT TEN SECONDG/

ASTWAITLEN-ASTWAITMSG

y
¥

TESTS.s./

TIMER

EFNWAITLEN-EFNWATTMS0

Fromet for terminal

ORION.../

strings

formats error messadge if a swsltem service fails

formats error messadge if 170 fails

BADNASTHTR fmrmats’error messadge if error in ALT routine

ERRSTR:

DESCRIFTOR <! /SYSTEM SERVICE ERROR AT AFF. XL RQ==1 XL

IOERRSTR

NESCRIFTOR <1/1/0 ERRORS TOSE ! XW>

RADASTSTR

NESCRIFTOR <RAD AST FARAMETER

WAKEUF?!

.« ./
.ASCII /AWARENET

WAKEUFLEN?:

JL.ONG WAKEUFLEN-WAKEUF

«FAGE

FSECT
+SRTTIL.
¥

TUL>

RWDATAYROYWRTyNOEXE
Read arnd Write DNata Areas

i Read/write data
y

y
y

Fao COhtPOletPififi ard buffer for 2ll arnnouncement messages

PROGRAM EXAMPLES

FAODESC:

sDescrirtor for FAOQ outrut buffer

«LONG

80
FAORUF

sAddress

FAORUF:

.EBLKER

yFAOD

FAOQOLEN!

.WORD

+WORD

sLendgth of fimal stringy a3lwaus
yNeed londword for $OQUTPUT

LONG

buffer

Buffer to format»messases from AST routiney 3 serarate out#ut buffer

ensures

that

writtern

into

if the AST is delivered while another messadge is beind
the FAQ outrut buffery no date or messade will be lost.

FASTDOESC:
|
+ LONG
«LLONG

slescrirtor

for

FAOQO

FASTRUF
0

s FAO buffer
sLength of fimnal

sNeed

Receive charnmnel

rmumber assidgned to terminal

FASTRUF¢
FASTLEN:

BLKR
WORD

londword

buffer

strindy

for

alwaus

$0UTPUT

and

I/0 status here

+WORT

outrut

TTCHAN:

EBLKW

TTIOSH!

channel

3 IOSR

termimal

for

+ BLKW
. BLKUW

sReturn

status

sLendgth

+BLKL

s levice

char

ineut

1/0

TTLEN!

sTerminal

list

Tor

$NAME 6

form

sustem

service

call

Argument

READLST?

EFN=32y8TATE=EFNTEST

$READEF

to obts im fnumeric values of comronents of time. Since
the only field of interest is the hours fieldy the remainins

GW>

Buffer

BrF

fields i the huffer are nmot formatted.

TIMES:

RLKW

sYears

HOURS:

+ELKW
+ELKW

sCurrent time
sRemainder of

Buffer for terminal ing ut
$SETFRN syustem service)

NAMEDESC:
«LLONG
«L.ONG

ar g

NAME ¢

Tor

create

inrut

daw

in hours
buffer

descrirtor

for

sllescrirtor setur
yInitial size of buffer

NAME
13

yAddress of buffer
yName string here

timer

tests

b 3]

Fields

+«BLKE

(will

monthy

NOON ¢

+ BLLKQ

jwill

contain 12:00 rnoon in skstem format

TEN:?

«BLKQ

iWill

contain

10 second deltas time

PROGRAM EXAMPLES

+ LONG

)

ifleceive status of event flads

.ONG

iStatus after timer test

E»

EFNTEST2:

«r Wur

Longword to save FC om entrw to error handling subroutine

SAVEFC:

BLKL

+ FAGE

ORION?

LSETTL

TEST TIMERS WITH EVENT FLAGS AND ASTS

JFSECT

TIMEREXEyNOWRT

WORD

“MoR2yR3IsRAyRIyRE

sEntre maskhk

Cr &>

Assign an I1/0 channel to the Hevice srecified by the lodical .name
TERMINAL and issue a messade indicating we’re off and running
lo mot serform normal error checking here! insteady let the
command intersrreter issue 8 messade nhaserd orn the status in RO

SEF

if the charmel assidgnment fails.

SETUF

RET

1LO0% 4

E
CHAN
TNAM
y CHAN=TT
$ASSTIGN_S DEUNAM=T

RI.LES

RO»1O%

sA11 okawsy continue

s0therwise exit with status in RO

’$0UTPUT’CHAN*TTCHAN9BUFFER=HELLU:LENGTH:HELLULEN,
'
|
'
ERROR
RSEW

-r

Call Read Event Fladgs to det status_of event flads before bedinning 2
tests and use FAD to outrut the contents of local event flad cluster
F READLST
.G
$READE

$FAO0_S

CTRSTR*DISPLQYEFNrUUTBUFzFAOUESC!DUTLEN=FADLEN7*
F1=EFNTEST

MESSAGE

Arnnounce start of timer tests

’

TIMETEST?

$OQUTFUT CHANxTTCHfiNrBUFFERmTIHERMSGrLENGTHfiTIMER| LEN

-r

w»

BSEW

it is currentls AM or FM. If
Call $NUMTIM to find out if the
AM (anu time)r we’ll call
is heing run in
the srodram
when the time rolls over
AST
an
via
us
$SETIMR to notifw
to afternoon. If it’s already FMy skis this settindg of
the

timer.

RSRUW

> >

CMFW
RGEQ

ERROR

$NUMTIM..S TIHBUF@TIMES

EFNTEST:

ERROR

HOURS » #12
104

sRefore or afternoon?
saftery skir setting timer

g'rewrefienting 12 noon
Fall through heret! format ASCII-fitrin
call $SETIMR with
and
format
time
rd
into sustem auadwo
e timer recuests.

the address of AST service routine to handl

PROGRAM

EXAMPLES

$BINTIM.S TIMBUF=ASCNOONs, TIMADR=NOON
BSRW

ERROR

$QETIMR..S

RSERW

yGet bihafu rnoomn time

sError

check

DAYTIM:=NDON;ASFAHh TIMEAST yREQINT:=%#12

ERROR

check

formatted

into

yCet

bimary

Nowr

get

delta

time

secornds

A»

sError

10%3

SRINTIM..S

TIMANIR=TEN

Announce

ERROR

Wwait

flag

for

sError

event

flad

and

outrut

cluster

sError check
$Set timer (tern

and

waits

then

delta

time

:
seconds)

check

read

the

its contents

$QUTFUT CHANxTTCHAN,BUFFERmEFNNAITHSGrLENGTH=EFNUAITLEN
SWAITFR..S

EFN=%33

Now

ERROR

wait

sError

check

Urdate BPSQment list for $READEF and thern call it with new address

a@>

RSERW

disklaw

write

the

cluster

contents

MOVAL

into.

When

the

comeleter

format

messade

and

cluster.

FFNTFSTE;REQDL9T+REQUEF$ STATF

S$READEF .G
ESEW

REAILST

FERROR

$FAD_S

sError

check

CTRSTR=TIMSTRy QUTLEN=
=FAOLENy QUTBUF
F1=EFNTEST2

BSBU

ERROR

sError

MESSAGE

=FAQODESCy
~

check

€Cr

Announce setting of timer with AST inm 20 seconds (using

alternate

Q»r

‘

and

method

coding

delta

time).

Therny

set

timer

©cr

continue.

$OUTFUT

CHAN=TTCHANs RUFFER=ASTWAITMSGy LENGTH=ASTWAITLEN

$SETIMR_S DAYTIM=TUENTYyASTADR:TIMEASTrREGIUT:#EO

RSRW

ERROR

sError

+« FAGE
3

Is&ue

Frrocess

name.

rromet
anc

for

then

terminal

use

the

inrut!

character

request
string

check

rname

for

entered

the current
the

RIINAME
¢
$0UTFUT

CHAN=TTCHAN»» RUFFER=FROMFTy LENGTH=FROMFTLEN

BSEW

ERROR

sError check

$INPUT_CHAN“TTCHAN!BUFFER“NAMErLENGTHflNAMEDESC!_
»

T
T
g RPN Ry

RSEW

I0SE=TTIOSR

ERROR

PPOCPSb

1\\—/

> >

RSEW

event

TIMBUF=TENSEC

RBSEW
ERROR
.
$SETIMR.S EFN=#33yDAYTIM=TEN

cRuadword

PROGRAM EXAMPLES

31/0 successful®

TTIOSE» #58% . NORMAL

$FA0.S

CTR8TR=I0OERRS3 TRy QOUTLEN=FAULLN:OUTBUF FAODESCy -

MESSAGE

BRW

MOVZUWL

10%12

CHFW

BREQL

10%

F1=TTIOSK

RINAME

€0 on

sGo trw a3dain

sUrdate descristor lensgth

TTLENyNAMEDESC

$SETFRN..S FRCONAM=NAMEDESC

BSEW

iYesy

ERROR

iSet #rocess name

: Hibhernate. Whern ORION is run interactivelw» the terminal is dormant.

5 Whern the AST for the Set Timer service is deliveredy ORION

5 will awsken long enough to execute the AST service routine and
then

resume execution.
|

;

5 IF ORION is rum in a8 subrrocessy wakeurs can be scheduled for
5 delta time intervals. Each time it is awakeneds ORION disrlaus a3
5 messade and then resumes hibernating.
y

HIR?

$HIRER..

sFor now

EUF AKEUFLEN
» LENGTH=W
AN R=WAK
s RUFFE
$OUTFUT CHAN TTCH
BRRE

HIR

RET

+ FAGE

TIMEAST?

LSETTL AST ROUTINE TO HANDLE TIMER ENTRIES

+WORT

CHMFL
REQL.

#12+4 (AF)
104

REQL
BRW

20%
30%

CMFL.

#2094 (AF)

sEntry mask for timer AST routine

3Is it moomn AST?
;Yesy g0 do it

$3Ts it delta time ASTT

|
|
iYesy do do that
sNeithery issue error messade

5 Format messade for noorn AST

hat
TM)

10%¢

CTRSTR:FAOSTR,OUTBUFnFASTUESCrOUTLENmFASTLENrP1=iNO0NMSG

$FAD..S

sError check
F FASTLEN
y LENGTH=
TRU
S
FFER=FA
CHANyRU
CHAN=TT
$OUTFUT
sError chechk
ERROR
BSEW
ERROR

BESRW
RET

’

i Format messadge for 20 second AST

20% ¢

$FAD.S CTRSTR= %ELMSGDFSC;OUTBUF-FASTHESC y OUTLEN=FASTLEN FLl=#TWENTY

F=FASTLEN
s LENGTH
$OUTFUT CHAN=TTCHANy BUFFER= FASTRU
RET

3 Format messadge if srurious AST

J0%:

$FAD.S

CTRSTR=RANASTSTR» QUTLEN=FfiSTLENvUUTBUFFfiSTDESCv

UFFASTLEN
s LENGTH=
BUFFER=FASTR
$QUTFUT CHAN= TTC»HAN
Fl=4(AF)

RET

. FAGE

Error handling routine! checks status code irm RO.
If low bit sety returns to mainline routine. Otherwises

disrlavs approximate FC and RO when sustem service call
encounters an error and issues RET that causes imade exit.

C> W

LSETTL ERROR HANDLING ROUTINE

B-7

PROGRAM EXAMPLES
ERROR

BLLRC

ROs»10%

RSE

s If

errory

i0therwisesy

branch
continue

y Use FAO to format output Error messadge
1043

MOV

(SF)»SAVERL

$FAD.S

CTRSTR=ERRSTRsOUTLEN=FAOLENyOUTRUF=FAQDESC
-

F1=5AVEFCyF2=RO
.

ENDe

BLEC

ROYEND

$OUTFUT

CHAN=TTCHANyBUFFER=FA
y LENGTH=FADOL
QRUF
EN

RET

+ENI

ORTION

PROGRAM EXAMPLES

LTITLE CYGNUS SYSTEM SERVICES TEST FROGRAM
/01/

+ IDENT

CYGNUS

examrles of the following system services?

shows

$TRNLOG
$ASSIGN
$NCLEXH
$CREMEBX

Translate Lodical Name
Assidgn I/0 Channel
leclare Exit Handler
Create Mailbox

$CREFRC

Create

$FAQ
~
$QI0
$CRELOG

Frocess

Formatted ASCII Dutwut
Queue 1/0 Request
Create Losical Name

Wake Frocess
Set Sustem Service Fallure E"cept1on Mode
Wait for Sindle Event Fladg

$WAKE
SSETSFM
$WAITFR

lelete Lodgical

$DELLOG

$NASSGN —~ Neassidn

This
1.

samrle

Device Information

Get 1/0 Channel

S$GETCHN

erodram

Name

I/0 Channel

illustrates:

Assigning a channel to the current outrut device bu translating

the lodgical mame SYS$OUTFUT.

lleclaring an exit handler to receive control at image exit.
The exit handler ensures that the imade exits in a8 graceful
manner.

Creatindg

ohtain

Creating

mailbox
the yrnit

and using the $GETCHN sustem service
number.

a subrrocess

and using the mailbox created as a8

termination mailhox. Whern the subrrocess terminatesy an

AST

service routime interrrets the messade.
D
be

Flacing names in the dgrour logical name table.

Waking a hibermating subrrocess. The subrrocess created bw this
mrogram ~laces itself in hlbernatlon after detting started.
Whern awakenedy it translates the logical names rlaced in the
grour logical

name table.

«FAGE

Sustem macro defimitions recuired by CYGNUS

SSSDEF

sTiefine status codes for returns

SMSGDEF

sDefine names for mailbox messades

$ACCIEF

shefine names for terminastion messade

sTNefine I/0 functions codes for $QI0

$I0DEF

iNefine names for auota list

$FQLIOEF

Mefine names for device information huffer

Local

macros?

DESCRIFTOR to define inrut character string descrirtors for
system service calls

_ar

-y

«»

$OIRDEF

MACROD

DESCRIFTOR

LAREL1!

JASCII

LAREL2:

+« ENIIM

«LLONG
+LLONG

EL
1y PLARELZ
TEXTy PLAR

LAREL2~-L.AREL.1
L.ARBEL1

A\TEXTA

TESCRIFTOR

PROGRAM EXAMPLES

MESSAGEy

outrul

messades

formatted

FAO

+MACRO

MESSAGE

$OUTFUT

CHAN=TTCHAN»RUFFER= FAOBUFrLENGTH FAOLEN

« ENDIM

RSERUW
MESSAGE

ERROR

Local

macro!

GRFNAME»

rairs

drour

error

the

lodical

checlking

.MACRO

lodgical

name

table

name/ecuivalence
with

$CRELOG

GRFNAME

name

and

LOGICAL »EQUAL

$CRELOG..S
BSEW

+ ENIIM

mlace

TRLFLG= il;lOGNAM LDGICALyEGLNAH
=EQUAL

ERROR

GRFNAME

Read/only

data

areass

Wr u>

. FAGE

LFSECT

RODATAYyNOWRT
y NOEXE

SLLIST

MER

’ Descriptor for ineut lodgical name
DUTFUT:

DESCRIFTOR

<S8YS£QUTFUT>

r Buffers forAannouhdement meésafieg and lengths
HELLO?!
DESCRIFPTOR
HELLOLEN:
«LONG

<CYGNUS...HELLO:

HELLOLEN-HELLO

RYE :

LASCII

BYELEN:

JLONG

/CYGNUS

EXIT'HQNDLER.‘./

RBYEILLEN-RBYE

’

Caormtrol

strindgs

counted

ASCII

for

outrglt

strinds

messastes

insert

formatted

messades

FID

IXL>

FAQ

and

sssociated

FRCSTR?
NDESCRIFTOR

<LYRA

CREATEDy

ASTERRSTR ¢

DESCRIFTOR

IOERR:

IDERR:

sdisrlay

.ASCIC

ASCIC

< !/MAILEBROX

‘I/0 ERROR’

/RAD MSG

~H/GFURTOUS

‘

HAS

1AC

! XW:-

DONESTR

iMsilbox

.
PRDCESS ID

DESCRIFTOR

<!/LYRA

COMPLETED:

BADEXSTR
Y
HF%PRIFTOR

SI/ZEXTIT

DUE

messade

DELETION

TIME

not

termination

MAILBOX}

STATUS

ERROR

1XT>

VXL

[Ilescrirtor

define

mname

image

subrrocess

3170 error in AST routine

FIDERRSTR?
NESCRIFTOR

IN/

MESSAGE

FID

for subrerocess

execute.

messade

PROGRAM EXAMPLES

LYRAEXE?

DESCRIFTOR

TM
SLYRAGEXE

for
Quotz list for subrrocess: defines minimal cuotas recquired.
for the subrrocess to execute and ensures that the creatindg
have sufficient auotas to continue.

image will

+1.ONG
+RYTE

102 4
FQL $ FIIL.M

+LLONG
+BYTE
+ LONG

3
FQI. $..FGFLAUOTA
256

y0ren file auota

jPaging file auota

FQl. ¢ _FRCL.M

s Subrrocess quota

+-ONG
+BYTE

1
FQL. . . TQELM

sTimer queue auota

«LONG

+BYTE

FQL. % L ISTENID

Er
Er

«RBYTE

Logical
Note

rmame rairs for dgrour table.
the names ifilr@cursive i the tatle.

name/equi valence
of

orne

that

ORION?

HUNTER

DESCRIFTOR
NESCRIFTOR

SORTION:
SHUNTER:

FEGASUS IDESCRIFTOR

FEGABUS

HORSE¢
lLYRA?

NESCRIFTOR SHORSE>
NESCRIFTOR
DESCRIFTOR

SLYRAX

HARFS
CYG?
- SWAN

NESCRIFTOR
NESCRIFTOR

“0YGNUS?:

S OWANE

NUCK:

LESCRIFTOR
NESCRIFTOR

SUGLY DUCKILING:=
SFATRY TALE!

TALE?

=
LHARF

E»

. FAGE

Read/write

\\\«..._/

sRuUffer quota

FQL. % _RYTLM

+RBYTE

QLIST:

data

areas

RWOATAyROsWRTyNOEXE

JFSECT

TTCHAN: JELKW

mnumber oft terminal

sChannel

3 ODutrut buffer to receive rhusical termimnal name
&

TTNAME:

LONG

+BLKE

sMaximum lodgical name lensgth

}

'finescriptor lendgth
sAddress of buffer

TTADDR! .LONG

Termination

blochk

control
|

EXITRLOCK?
+ BLKL

+ LLONG

EXITRTN

« LONG
|
+BLRKL
ERRFC:
STATUSt .BLKL

STATUS
1
1

}Address of routine

« LONG

$Exit control block
s Suystem uses this for rointer

iNumber of arsuments for handler

$Address to store status
Store PC (if error).
;Status code at exit

: Fields used for termination mailbox creationr messade huffering
?

PROGRAM EXAMPLES
EXCHAN:

EBLKW

sCharmmnel

EXITRUF:
+LLONG

REUF $
ENDERUF
2

nmumber

jlescrirtor

ENDRUF-BRUF

rlLength

+LONG

BRUF

sAaddress

« BLKL

DIREN_ILENGTH
3 1/0

MEXTOSE:

Status

MELEN?:

RBLKW

MBFPID:

BLKL

+ RLLKR

mailbo

block

I/0

yLength

oreration

yFID

rrocess

datas

buffer

5Buffer

EXITMSG:

charnel

buffer

status

+ BLKW
.

for

comrletion
here

deleted

for mailbox messade

Receive

FID

Qf'fiubprocess

here

ACCER_TERMLIEN

LYRAFII:
v BLI\L

Duteut

buffers

Tor

strinsgs

formatted

FAOD

«FAGE

FAODESC¢

sllescrirtor

+ LONG

FAORUF:
FAOLEN:

Need

y80-character

+ LONG
.BLKE

FAORUF
80

sAddress
sBuffer

+BLKW

sReceive

« BLKW

iNeed

serarate

¥ that

data

for

FAO

doesn’t

buffers
dget

for

use

clobbered

AST

lendth

londword

routimne

outerut

buffer

here

for

$QIO0

ensure

asunchronously

FASTDESC:
+L.LONG
+ LONG

ilength
yAddress

FASTERUF
{ . RLKR

sBuffer

FASTLEN?
. BLKW

yGet

+« RLKW

s Need

+ PAGE
+FSECT

CODEYEXEsRDOyNOWRT

+WORD

lendth
lonsgword

current outrut device. If the imade is run interactivelus
its eauivalence nmame 1s sustem-definedy and will contain
3 4-byte header. The #=rogram must check for the header and

name

SYS$0OUTFUT

descrirtor so the device mname will

find

be valid

name

urdate

for callindg $ASSIGN.

lodical

mask

Firsty

the

translate

$QIO0

sEnmtry

for

CYGNUS?

$TRNLOG..S LOGNAM=0UTFUT
y RSLLEN=TTNAME » RSLEBUF=TTNAME

RSBRW
CMFR

ERROR
TT»#"X1E

sFirst

ENEQ

10%

siNory

SURL
ADNL

¥4y TTNAME
¥4y TTADDR

sSubtract
sAdd 4 to

bute

escareT

shead

4 from lensgth of name
address in descrigstor

p
e

Call

suyccessful

ALl

80
FASTRUF

$ASSIGN to

asssidgn an

initislization

I/0 chanmel

and

issue messade verifwing

PROGRAM EXAMPLES

TNAME
» CHAN=TTCHAN
$ASSIGN.S DEVNAM=T

10$:

ERROR

RSRW

sError chechk

$0UTFUT CHAN=TTCHANs BUFFER=HELLOy LENGTH=HELLOLEN
ERROR

RGRW

®»

Ileclare exit handler to do cleanur orerations

$OCLEXH.S

DESRLK=EXITRLOCK

ERROR

BSEW

Create 2 mailbox for subrrocess termimation messader then
got the unit rumber of the mailbhox by doing 3 $GETCHN

MAILEOX?:

»FROMSK=#0
=#120»
RUFQUO=%#240
$CREMEX..S CHAN=EXCHAN»MAXMSG

BRSEW

ERROR

BSEW

ERROR

Create the subrrocess. Since the lodical name SYS$OUTFUT
has alreadys been trarmslateds the same equivalence name can be
given to LYRA a3s its logical outrut device.

LYRA will bhe able to assidgn a3 chamnel to this device as well.,
The MEXUNT argument srecifies the name of the mailbox Just
createds the mailbox will receive a messade when LYRA exits,

WS Er

T»

$GETCHN..S CHAN=EXCHANyFRIBUF=EXITRUF

FROCESS

$CREFRC..S IMAGE=LYRAEXEsFIDADR=LYRAFIDy~MEXUNT=REUF+QIB$W_UNITy

BRSEW

T
AME
» QUOTA=QLIS
OUTFUT=TTN
ERROR

If okavr format amn outrut messadge showing the rrocess 1ede oo

$FAO0_S CTRSTR=FRCSTRyOUTLEN=FAOLEN» QUTRUF=FAODESC» BSEW

Fl=LYRAFID
ERROR

BSEW

ERROR

Queue an I/0 reauest to the mailbox with an AST
to receive notification whern LYRA comrletes.

@»

‘6
r

=FAORUF
s _LENGTH=FAQOLEN
$0UTFUT CHAN=TTCHANyERBUFFER

$QI0.S

EFN=#4,CHAN=EXCHANsFUNC=%#I0%_REAIVELK,~-

RSEW

F1=EXITMSGF2=%120
ERROR

ASTADR=EXITASTy IOSR=MEXIOSE -

NS> W

+FAGE

in the grous lodical name table using the macro GRFPNAME.
Flace names
It will be LYRA‘s tasks when awakenedy to translate these

.
names and disrlawy the results at the terminal.
Note that tramslation of the mame CYGNUS will recuire
recursive translation.

PROGRAM EXAMPLES

FUT NAMES

GRFNAME

ORION»HUNTER

GRFNAME

FEGASUS»HORSE

GRPNAME

LYRA»HARF

GRENAME

CYG»SWAN

GRFNAME

SWAN»IIUCK

After rslacind names in the tabley
to

rerform

the

lodgical

name

wake LLYRAy

who has been hiberhatins:

tramslation.

“r

GRENAME DUCK
s TALE

$WAKE._S FIDADR=LYRAFID

RSRUW
5

Call

ERROR

erogram DRACO
EALLS

¥0yIIRACO

RET

¥All

in Charster 4)

finished

w»

+FAGE

AST

w@r E>

(test of FAD examrles

In this
hut the

service

the

mailbox

€
>

That

the

I/0

That

the

messade

routine to read the termination mailbom.
examrley only one messade is actually e'Pected
srodgram Performs all the followlns checlks?

That

the

rrocess

heing

routine

enables

comrleted

successfully.

the

mailbox

deleted

rrocess

term1nat1on

subrrocess

service

call
does

failsy an excesrtion condition will occur. CYGNUS
not declare a condition handlery so the imade

will

This
mode

rertinent

error

forced

handling

sustem

device!

terminaster

information

about

and
the

service

the

failure

sustem

excertion

will

disrlaw

condition.

|
WORD

Q
SSETSFM_S

IOSE

sEntry
ENRFLG=%#1

ensure

maskhk

sEnable

that

I1/0

comrleted

SSFAIL

excertions

successfullw

w> W

excertion

service

EXITAST:

Check

messadge.

created.

the

CMFW

MEXIOSEy %5 8$ ~.NORMAL

sCheck

BREQL

20%

yOk.ayyr

CTRSTR=ASTERRSTR
s~

yO0therwisey

$FA0..S

that

OUTLEN=FASTLEN OUTRUF=FASTIESC~
Fl1=%I0ERR,

»1/0

FP2=MEXI0OSR

1/0

was

format

successful
error

msd

error

vlisrlaw

IOSE

$OUTFUT

CHAN=TTCHANy BUFFER=FASTRUF y LENGTH=FASTLEN

ERW

a0%

Checlk

sReturn

messadge
rrocess

ture

field

termination

inm

mailboy

messadge.

message

ensure

that

the

messade

PROGRAM EXAMPLES

CMFW

20%:

REQL.

$FA0..8

» #MSGS$ _IELFROC Check messade identification
HACCHW.
. MSGTYF
EXTTMSG
g0 on

yOlagy

20%

t0therwiser

CTRSTR=ASTERRSTR

QUTLEN=FASTLEN
Fl=fIDERRy -~

format error messade

QUTRUF=FASTIOESCy FID error
$Invalid
~

FR=EXTTMSG+HACCHW. . MEGTYH iFrint messadge twre code
$QUTFUT CHAN=TTCHANy RUFFER=FASTRUF » LENGTH=FASTLEN
s Revturn
Wle)
BiW
’

} Comrare the second longword im the I0SER with the FID returned
$ bw $CREFRC to ensure that the termination messade is for LYRA.
¥

2062

CHMFL

LYRAFIDyMBFID

RRW

40%

ENEQ

35%¢

$FAQ_S

I5%

sLYRA deletion®
‘

CTRSTR=FIDERRSTRy-

sYesy

4d0 on

s0therwisery

OUTLEN=FASTLENy QUTRUF=FASTDESC»~

format error messade

jllisrlay spurious FID
Fl=MRFID
$0UTFUT CHAN=TTCHANs RUFFER=FASTRBUF y LENGTH=FASTLEN
sReturn

S0%

RRUW

’

5 Format am outrut messade indicating LYRA’s final exit status
$ and the time of dawg at which LYRA terminated.
y

40% ¢

$FAQ_S CTRSTR=DNONESTRy -

sFormat messade telling of LYRA‘s demise

QUTLEN=FASTLEN QUTRUF=FASTIOESC» -

F1=EXITMSGH+ACCSLFINALSTSy —~
FR=fEXITMSGHACCHQR TERMT IME

sGet status code
sand time of deletion

$0UTFUT CHAN=TTCHANy RUFFER=FASTRUF s LENGTH=FASTLEN
sNisahle excertions
,
$SETSFM.S ENRFLG=#0

S0% ¢

sReturn

RET

«FAGE

This is the exit handler for CYGNUS. It receives control
5 when CYGNUS exitsy either normallyy or 38 8 result of

error

EXTTRTNG

condition.

JEntre mask
|
,
O
JWORD
$0UTFUT CHAN=TTCHANy RUFFER=RYEy LENGTH=RYELEN
ESEW

ERIL.RS
¥

ERROR

STATUS»20%

siNormal exity continue

If erraory formal error messadge using ardgument list in

y emit corntrol

10%:

bhlock

$FAD.E CTRSTR=RADEXSTRy QUTLEN=FAQLENy QUTRUF=FAODESCy FP2=ERRFC
F1=8Ty ATUS

RSEW

ERROR

$OUTEUT CHAN=TTCHAN» BUFFER=FAQRBUF v LENGTH=FAOLEN

Common code for both mormel and error exit! wait for subrrocess
to terminate (if it hasn’t alreadw)y then delete all names
from the drour logical name table.

PROGRAM

20%3

SWAITFR..S

ESRW

304¢ ¢

EXAMPLES

EFN=%#4

sWait

for

termination

ERROR

$OELLOG..S

TELFLG=#1

slelete

BSEW
ERROR SOASSGN..S CHAN=EXCHAN

211

BORW

ERROR

|
rleassidn
.

MOVIL.

STATUSYRO

sRestore

RET

Exit

messadge

names
A

mailbox

saved

with

chanrel

status

code
|

+ FAGE
4

Common

status

error

code
rrodram.
If

control

if
is

that

routine.

This

successy

returns

errorsy

exit

the

routine

routine
FC
cam

to
is

checks

the

mainlimne
rlaced

format

and

the

|
exit

disrlaw

messade,
|

RILLRC

RO»10%

RGSE

MOVL
RET
+ENIN

ROy

there

block

error

ERROR ¢

1Lo%d

handling

(SF)YyERRFC
-

iCheck status code

jLow hit
yStore
RET

CYGNUS

sety

g0 bhack

will

cause

imade

exit

PROGRAM EXAMPLES
LYRA Sustem
/01/

LTITLE
INENT

Test

Services

e A1

LYRA shows examrles of the following sustem services$

T NI

$TRNLOG ~ Translate lLogical Name
GASSIGN ~ Assign I/0 Channel
~ Hibhernate
$HIRER

R NP G

- Formatted ASCII Outrut with List Farameter

$FADL

LYRA is the subrrocess created bw CYGNUS, After assidning a

I WH NP

l its current outeut devicer LYRA hihermates. Whern awakened
chanmeto
hy CYGNUS» LYRA tramslates the losiical names rlaced i1n the grour
logical name table bw CYGNUSy and disrlaus the results of the

WEa

translations on the terminal.

Whern LYRA exitsy a termination messade is sent to the

a2y

mailbox srecified bw CYGNUS.
_

Macro

librare calls

sNefine system status values

N’

$SSTNEF
,

Local

macros

DESCRIFTORy constructs insut character string descrirtors

LARELLIY
LAREL2:

« EENTIM

MESSAGE

. LONG
LONG

LASCIT

AREL]
2LEL
LAR
L
LAREL

NTEXTA

NESCRIFTOR

to outerut messades FTormatted L F i,

LMACRO

MESSAGE

L ENTIM

MESSAGE

SOUTHUT CHAN%TTCHAN»BUFFERMF&L&ZTa!fl!GTHnF&' DLEN
ERFEOR
RSRUW

“.

/¢ .

TLARELZ
LyREL
TEXTy PLA

DESCRIFTOR

LMACRO

CFAGE

CERTTL Swumbhols and dats aress
‘

;

Locsl

data

JESECT

y
» NOEXE
ATA
RODNOWRT

MER

Logical name of lodgical outrut device

WS> W

AIST

DESCRIFPTOR <SYS$OQUTFUT.:

Aniniouancement

messades

QUTFUT:

HELLLLOS

+ASCIT

HELLOLENS

- LLONG

/LYRAZ INITIALIZING...AND SO TO SLEEF/
HELLOLEN-HELLO

PROGRAM

EXAMPLES

WAKEMEG

‘

+ASCITI

/LYRA!

. L.ONG

WAKELLEN-WAKEMSG

WAKELEN?

;

OKAY»

WILL

IO LOGICAL

NAME

TRANSLATION.../

FAQD

control

string

for

lodgical

name

oulrut

messade

LOGNAMSTR

HESCRIPTDR_{!/LYRAI’!AS
7

Error

messadge

corntrol

VA8

string

ERRSTR¢
LDESCRIFTOR

SYSTEM

SERVICE

ERROR

AFF.

XL RO=1XL:>

<!P/LYRA!

Lodgical

names

Lranslated

;

ORTONLOG
NESCRIFTOR

<0ORION:-

CYGNUSLOGE

DESCRIFTOR

<CYGNUS:

DESCRIFTOR

<l.YRAX

LYRALOG?

FEGASUSLOG!

NESCRIFTOR

<FEGASUS:

FAGE

Read/write

‘

data

JSECT
7.

anfiTHyRHyNRTyNDEXE

UU}PQt

buffer

for

811

outrut

formatted

bwe

FAD

”éww

FAOLEN:

.WORD

)

ilength

+WORD

sNeed

+ LONG

«L.ONG

FAQRUF

RLKE

fimal

londword

FAQLESC¢

FAORUF?!
#
y

Word

receive

chanmel

rmumber
of terminal

DUTCHAN?

« BLKW

Buffers

routime

maintain
thaet

LOGRUFA:

BUF A
LOGRUFE?

- LONG
«L.ONG
+ BLKE

JLONG

J.ONG

63
BUFA
63

lodical

rerforms

RUFE

name/ecuivalence

lodgical

rame

name

tramslation

strindy

for

rairs

alwaus

$QUTFUT

PROGRAM EXAMPLES
- RUFE?

« BLKR

653

LOGLEN:

+LONG

lendgth of equivalence name

sSave
.

Farameter

;

list for

call
|

to FAOL

{(used b translate
:

routine)

TLIST:

TEQLNAM

SAVER3:
§

TLLOGNAM ¢

+LONG

. ONG
.LONG

O
0

sAddress of lodgical mname descrirtor

;Address of eauivalence descristor
sSave register contents for switch

:
i

Longword to store the FC when 3 swustem service call results in an
ervice call.
error. LYRA checks the low bit of RO following each se
IF sets LYRA continuess otherwises it saves the FC amd branches
to an error handling routine that disrlaus the saved PC and the

'
3
5
$

of RG.
contents

;

JONG

FERRFC

+FAGE

SETTL

FPSECT
LJENARL
LYRAZ

+WORD

5For address of SSFAIL

Ready and hibhermate
CODEsEXEyRIOsNOWRT
LGSR
|

“MIR2sRIyR4sREyRE:

sEntre mask

Assign charmel to device referred to by lodgical mame

5 SYS$OUTFUT. This name was slaced in the lodical name
5 tabhle hw CYGNUS (it is also CYGNUS’s lodgical outrut device).

20% 1

0UTFUT
» CHAN=0UTCHAN
$ASSIGN..S DEVUNAM=

3061

sExit with status if ASSIGN falls
RET
$0QUTFUT CHAN=0OUTCHAN> BUFFkR HELLOy LENGTH=HELLOLEN

RILES

ROs30%

40% 3

ROs40%
RLLEBS
30%yERRIFC
MOVAL
ERROR
BRW
$HIRER..S
RO»30%
BLERS
y ERRFC
40%
MOVAL
ERROR
BRW

SO% 3

$OUTFUT CHAN=OUT(HANyBUFFFR wfihEMSGyLENGTH wfihELEN
BLES
MOVAL
EBRW

ROs60%
S50% yERRFC
- ERROR

3
60%
.

i When awskenedr bedin translating lodical names. To translate the
s namesy rlace address of a logical name descrirtor in R2 and then
; g0 to the subroutine that rerforms the translation. Rereat for

} each lodgical meme to translate.
¥

MOVAL.
JER

MOVAL
JSE

MOVAL.
JER
MOVAL
JSR

ORIONLOGYR2
TRANSLATE

CYGNUSLOGYR2
TRANSLATE

LYRALOGYR2

TRANSLATE
FEGASUSLOGYR2
TRANSLATE

PROGRAM EXAMPLES

ALl

Fimishedr

returnm

\,.—v" ’

RET

« FAGE

wa»

erntry

CCBRTTL
+ENARL

uses!

Subroutine
LLSE
this

address

tramslate

and

s=rint

lodgicsal

names

subroultines

logical

mame

translate

R3I

hold

address

final

result

buffer

hold

address

intermediate

huffer

- TRANSLATE
¢

MOVAL
MOVAL

LOGERUFAYR3
LOGRUFE
R4

'Get

addresses

bhuffers

Imitial

translation

=laces

resultant

ecuivalence

riame

buffer

rointed

y
10%:

$TRNLOG.S

BLERS

LLOGNAM=(R2) yRSILLLEN=LOGLENyRSLRUF=(R3)

RQ:30%

MOVAL

10$yERRFC

BRW

ERROR

Flace

y
¥

descrirtor
then there

length

ecuivalence

rrovide

translation until

mame

first

word

as inrut for mnext tramslation. IFf
was no recursion of mname. If moty

inrut

and

outrut

descrirtors

SS$_NOTRAN
is

for

of descrirtor

use

this

translation

and

rereat

returned.

30% ¢

EARAF I

MOVZWL
LOGLENs (R3)
sFix lendgth in buffer
$TRNLLOG..S LOGNAM=(R3) yRSLLEN=LOGLENyRSLRUF=(R4)

RLLES

KO»40%

MOVAL

304 yERRFC

BRW

ERROR

CHMFW
REQL.

ROy #5554 NOTRAN
0%

MOVL.
MOWVL

R4sR3
SAVER3 R4

MOVZUWL

#63y (R4)

sRestore

BRE

30%

sTre

MOVL.

R3sSAVER3

sFimal®
yYury g0

Frrint

s0therwiser

switch

|
'

)

|
length

adain

’

y
5

and

SS$_NOTRAN is returnedy
urdate redisters to

Flace addresses
and call FAO to

S90% 3

|
H0% 8

MOVL

R2y TLLOGNAM

MOWVL.
$FAOL..S
ELLRS

R3y TEQL.NAM
‘
N
CTRSTR=LOGNAMSTRy QUTLEN=FAOLENyOUTRUF=FAODESCyFRMLST=TILLIST
‘
‘
ROy 60%

MOVAL
ERW

S0%y ERRFC
ERROR

$OUTFUT

CHAN=QUTCHAN

BLLES

RO»70%

MOVAL

50% yERRFC

RRW

ERROR

MOVL.
MOWVL.

63y LOGRUFA
63 LOGRUFR

RSE

of lodical mame and ecuivalence rmames in FAO rarameter
format outrut messadey then outrut the messade.

BUFFER=FAQORUF y LENGTH=FAOLEN

3To

B-20

main

routine

list

PROGRAM EXAMPLES

FAGE

Error

handling

routine

L-E I

2 4

LORTTL

This routine uses the saved FC armd RO to format a messasefidéscribing_
the conditions under which a8 call to 8 sustem service failed.

- ERROR?

$FA0.S
:

CTRSTR=ERRSTRyQUTERUF=FAODESCy OUTLEN=FAOLENYy-

Fl=ERRFCyF2=R0O

$OUTFUT CHAN=QUTCHANy BUFFER=FAORUF y LENGTH=FAOLEN
'

RET

« ENTI

LLYRA

APPENDIX

OF SYSTEM SERVICES
QUICK REFERENCE SUMMARY

MACRO FORMS

'C.1

$name;G Form

c.1l.1
Format:

label

S$name_G

label

address of argument list;
|

Sname macro form.

Sname

1list

may

created

with

Format:

Macro

$name argl ,...

label:
label

argument

,argn

symbolic address of the generated argument list.

name

macro

name.

argl—-argn

arguments to be placed in successive longwords in the argument
A longword of zeros 1is generated for a nonspecified
list.
in positional order,
argument. Arguments can be specified (1)
with commas indicating no specified arguments; or (2) using
keyword = argument.
specified

in any order.

keywords

are

used,

arguments

can

Argument List Offset Names:

The Sname macro automatically defines symbolic names for argument
1ist of offsets. The offset names can also be defined with the
$Sname DEF.

The symbolic names defined are:

name$_NARGS

number of arguments in list.

name$_keyword

t list.
symbolic name for offset of each argumenin

QUICK

C.1l.2

REFERENCE

SUMMARY

SYSTEM

SERVICES

$name_S Form

Format:

Sname_S
argl

argl

,...

,argn

argn

arguments

for

macro

instruction.

Arguments can be specified
indicating

C.2

keywords

FORTRAN

C.2.1

(1)

nonspecified
are

used,

in positional order,

with

commas

arguments, or (2) using keyword=argument.
arguments can be specified in any order.

FORMS

Procedure

Call

Format:

call
argl

‘SYSSname(argl,,;,argn)

argn

arguments

for

system

Arguments must be

coded

keywords.

Commas

argument,

including

C.2.2

service

must

trailing

macro

instruction

strict positional

wused

arguments.

order,

indicate
the
|

without

absence

Function Reference

Format:

code

SYSSname (argl,...argn)

"Arguments

system

must

service

coded

function

described

must

above.

be defined

The

code

INTEGER*4

and

the

variables.

QUICK

—

C.3

SYSTEM

Adjust

Outer

SERVICE

Mode

SADJSTK
acmode

REFERENCE SUMMARY

SYSTEM

SERVICES

MACROS

Stack

Pointer

[acmode]
=

,[adjust]

,newadr

access mode to»adjust stack pointer for

adjust

16-bit signed adjustment value

newadr
=

address of longword
to store updated value

Adjust Working

Set Limit

SADJWSL

[pagcnt]
number

pagcnt

, [wsetlm]
of

Number

pages
to

add

pages

subtract

working

set

(if

negative).

set

(if

address of longword to receive'hew working set limit,

wsetlm

/J,.

©positive).

from working

current

working set

limit

pagcnt

not

specified.

"«

Allocate

Device

SALLOC devnamu,[phylen]/,[phybuf]

‘\-\Yv—/‘(

devnam

address
of
descriptor

device
|

, [acmode]

name

logical

name

phylén

address

phybuf

address of physical name buffer descriptor

acmode

access mode associated with allocated device

Associate

Common

SASCEFC
efn

Event

efn
=

Flag

,name

word

receive

length

,[prot]

name

,[perm]

number of any.evént flag in the cluster with which to
of

the

text

name

address

prot

protection indicator for the
0 -> default, any process in
1l -> only owner's UIC

physical

Cluster

assoclate

perm

string

permanent indicator
0 -> temporary cluster
1 -> permanent cluster

e=3

string

descriptor

cluster
group

QUICK REFERENCE

SUMMARY
OF SYSTEM SERVICES

[timlen]

timlen

address of a word
inserted into the

timbuf

address
of
a
quadword
descriptor
buffer to receive the converted time.

timadr

address of the quadword
be converted to ASCII.

cvtflg

conversion indicator
0 -> return full date
1l

Assign

,timbuf

return

,[timadr] ,[cvtflg]

to receive the
output buffer.

converted

number

—

SASCTIM

characters

describing

Convert Binary Timer to ASCII String

the

containing
the 64=bit time
If 0, use current time.

and time
time only

I/0 Channel
SASSIGN

devnam

address of

,chan

device

descriptor

chan

address

acmode

access mode

- mbxnam

address
mailbox

, [acmode]

of word

, [mbxnam]

name

receive

associlated

1logical

channel

with

number

string

assigned

string

descriptor,

)

$SBINTIM

timbuf

address of string descriptor for ASCII time string

timadr

address
value

Absolute

time

,timadr

quadword
|

strings

are

receive
|

specified

the

64-bit

binary

time

format:

dd-mmm-yyyy hh:mm:ss.cc'

)

Delta time strings are specified“in the format:

dddd hh:mm:ss.cc
Broadcast

SBRDCST

msgbuf
devnam

msgbuf

channel

of mailbox logical name
associated with device

Convert ASCII String to Binary Time

name

, [devnam]

address of message buffer string descriptor
terminal

device name string descriptor.
If 0, send
all
terminals.
If
first
word
1in

message
to
‘descriptor is
terminals.

send

message

all

allocated

OF SYSTEM SERVICES
QUICK REFERENCE SUMMARY

Cancel I/0 on Channel
chan

SCANCEL

chan = number of the channel on which I/0 is to be canceled

Cancel Exit Handler
[desblk]

SCANEXH
desblk

address of exit control block describing exit handler
to be deleted.

If 0,

delete all.

Cancel Timer Request
, [acmode]

SCANTIM

[regidt]

reqgidt =

request identification for request

- acmode

If 0,

canceled.

requests canceled.

all

access mode of requests to be canceled

Cancel Wakeup
[pidadr]

SCANWAK

address of

pidadr

process

identification

which wakeups are to be canceled

process

for

address of process name string descriptor

prcnam

Clear

, [prcnam]

Event Flag

Change

SCLREF

efn

to Executive Mode

SCMEXEC

)

number of event flag to be cleared

routin

, [arglst]

executed

address of the routine to be

arglst

Change

address of

argument

routine

1list

1in executive

mode

be
|

supplied

to Kernel Mode

SCMKRNL

routin ,[arglst]

routin

address,of routine to be executed in kernel mode

arglst

address of argument list to be supplied to routine

the

QUICK

Contract

REFERENCE

Program/Control
SCNTREG

pagcnt

SUMMARY OF

SYSTEM

SERVICES

Region
,[retadr]

,[acmode]

,[region]

pagcnt = number of pages to be deleted from end of region
retadr

address
of
addresses of

acmode = access mode

2-longword
array
to
receive
virtual
starting and ending page of deleted area

for

which

region = region'indicator
0
1l

->
->

program
control

(fij v g T
A

Create

Logical

(P0)
(Pl)

region
region

,lognam

,eglnam

1is performed

quf

RSN

Name

SCRELOG
tblflg

service

[tblflg]
=

logical

name

system

group

process

table

, [acmode]

number

(default)
table
table

lognam = address of 1ogica1 name string descriptor
eglnam

address

acmode

access

mode

Create Mailbox

and Assign

SCREMBX

[prmflg]

equivalence
for

logical

name string
name

descriptor

(process

table

only)

Channel
,chan

,[maxmsg]

,[bufquo]

,[promsk]

,[acmode]

, [lognam]

prmflg = permanent flag
0
1l

->
->

temporary mailbox
permanent mailbox

chan

address

of word

maxmsg

= maximum message

(default)

receive

size

channel

that may be

assigned

received

by mailbox

bufquo = number of bytes of dynamic memory that can be used to
buffer

promsk

mailbox messages

protection mask

for

mailbox

acmode = access mode of created mailbox

lognam = address of logical name string descriptor for mailbox

QUICK REFERENCE SUMMARY OF SYSTEM SERVICES

Create

Process

SCREPRC

,[mbxunt]

,[uic]

, [prcnam]

, [quotal

, [prvadr]

, [baspri]

, [output]

, [input]

, [image]

[pidadr]

, [error]

1longword

1in

which

pidadr

address

image

address of string descriptor

input

address of string descriptor

created process

identification of

,[stsflg]

for

return

process

image name

for

SYSSINPUT

1logical

output

address of string descriptor for

SYSSOUTPUT

1logical

error

address of string descriptor

SYSSERROR

1logical

name

for

name

prvadr

address of quadword privilege 1list

quota

address of guota list

prcnam

address of string déscriptor for process name

baspri

base priority

uic

user identification code.

mbxunt

mailbox unit for

stsflg

~status_and mode flag bits

to set for

(0-31)

new

process

(macro

Bit

Meaning

SN oo
wh = O

default

disable

‘

1If 0, create a‘subprocess

termination message

resource wait mode

enable system service failure exception mode

inhibit process swapping
disable accounting messages
batch

process

cause created process to hibernate
allow login without authorization file check
process is a network connect object

Create Virtual Address Space
SCRETVA
inadr

retadr

acmode

inadr

,[retadr]

,[acmode]

address of 2-longword array containing

starting

ending virtual address of pages to be created

and

address of a 2-longword array to receive starting'and

ending virtual address of pages actually created

access

mode

for

the - new

pages

(protection

read/write for acmode and more privileged modes)

QUICK REFERENCE SUMMARY OF SYSTEM SERVICES
Create

and Map Section

SCRMPSC

[inadr]

,[retadr]

[ident]
» [pfc]
inadr

, [acmode]

,[relpag]

,[chan]

, [flags]

,[pagcnt]

address
of 2-longword array containing
virtual addresses of space into
to

,[prot]

starting
and
section

ending

, [gsdnam]

,[vbn]

which

mapped

retadr = address
of

2-longword

actually mapped

array

receive

addresses

acmode = access mode of owner of pages
flags

section

characteristics

Flag

Meaning

SECSM_GBL
SECSM CRF
SECSM_DZRO
SECSM_WRT
SECSM_PERM
SECSM _SYSGBL

Global section
Copy-on-reference pages
Demand zero pages
Read/write section
Permanent section
System global section

gsdnam = address of global'section name string descriptor
ident

address
and

match

quadword

containing version

control

relpag

relative page

chan

number

channel

identification

,
within

on which

section
file

|
to

begin

mapping

is accessed

pagcnt = number of pages 1n section.
vbn

virtual

block

number
of

prot

protection

pfc

= page fault cluster

beginning

section

mask

size

Disassociate Common Event Flag Cluster
efn

SDACEFC
efn

number of
any
disassociated

event

flag
\

1in

the

<cluster
o

Deallocate Device
SDALLOC

[devnam]

,[acmode]

devnam = address of device
deallocate
acmode

access

all

name

string

descriptor.

devices.'

mode associated

with

device

QUICK REFERENCE SUMMARY OF SYSTEM'SERVICES
Deassign I/0 Channel
chan

$DASSGN

= number of channel to be deassigned

chan
Declare

AST

SDCLAST " astadr

,[acmode]

,[astprm]

astadr

address of entry mask of AST routine

astprm

value to be passed to AST routine as an argument

acmode

access mode for which the AST is to be declared

Declare Change Mode or Compatibility Mode Handler

,[typel]

,[prvhnd]

SDCLCMH

addres

mode handler
address of change mode or compatibility

prvhnd = address

longword

address

type

handler type indicator

receive

handler

0 -> change mode handler for current mode

1 ->

compatibility mode handler

Declare Exit Handler
SDCLEXH - desblk

desblk = address of exit control block‘containing:
8 7

forward link

)

‘

exit handler address

address to store reason for exit

additional arguments
for exit handler,
if any

QUICK

Delete

Logical

SDELLOG

[tblflg]

tblflg

logical name
0 -> system

,[lognam]

group

process

address of
delete all

chan

table

number

logical

string
descriptor.
specified table.

name

(process

table

only)

channel number

assigned to the mailbox

Process

[pidadr]

pidadr

, [prcnam]

address of

longword

process

address

prcnam

Virtual

Address

containing process

deleted

string

process
to

descriptor

for

identification

process

name

Space

inadr ,[retadr]

inadr

address of 2- longword array containing
starting
ending virtual addresses of pages to delete

Global

ending

addresses

access

mode

for

pages

which

receive

actually

service

1is

starting

deleted

[flags]

,gsdnam

group

performed

, [ident]

global

SECSM_SYSGBL

section

system global

section

gsdnam

address of global section name string descriptor

ident

address
and

Event

SDLCEFC
name

and

type
of section

Common

and

Section

$DGBLSC
flags

[écmode]

address of 2-longword array to

acmode

of-

deleted.

SDELTVA

retadr

Delete

, [acmode]

chan

SDELPRC

Delete

SYSTEM SERVICES

Mailbox

SDELMBX

Delete

logical name
names in the

access mode

acmode

Delete

SUMMARY

Name

»lognam

Delete

REFERENCE

match

Flag

quadword contalnlng

version

control

1dent1f1cat10n

Cluster

name

address
cluster

text

name

C-10

string

descriptor

permanent

QUICK REFERENCE SUMMARY OF SYSTEM SERVICES
Exit

[code]

SEXIT
code

longword to be saved in process header as

status of current image

completion

(macro default = 1)

Expand Program/Control Region
, [retadr]

,[region]

,[acmode]

SEXPREG

pagcnt

number of pages to add to end of specified region

retadr

2-longword
address of
starting
addresses of

virtual
receive
array to
of expanded
and ending pages

region

acmode

access mode

region

the

new pages

indicator

0 -> expand program
1 -> expand program

(P0)
(Pl)

region
region

Output

Formatted ASCII

,I[p2]...[pn]

,outbuf ,[pl]

SFAO

ctrstr , [outlen]

ctrstr

address of string descriptor for ASCII control string
address of word

outlen

1in

which

store

output

string

length

| outbuf

\
\

pl...

address of output buffer string descriptor
=

variable number of arguments to FAO

‘Formatted ASCII Output With List Parameter
ctrstr

SFAOL

)

,[outlen]

,outbuf

,prmlst

‘ctrstr = address of string descriptor for control string
outlen = address of word to receilve output string length

|
.

"Force

outbuf

address of output buffer string déscriptor

prmlst

address of a list of longword parameters

Exit

SFORCEX

[pidadr]',[prcnam] , [code]

pidadr

address of process identification of

prcnam

forced

"address of process name string descriptor for
process

code

process

to exit

longword completion status for exit service

forced

QUICK REFERENCE SUMMARY OF SYSTEM SERVICES
Get

I/O

Channel

Information

SGETCHN

chan

number
of

,[prilen]

,[pribuf]

a channel

,[scdlen]

assigned

,[scdbuf]

the

device

prilen = address of word to receive length of primary buffer
-

pribuf

= address of primary buffer

scdlen

scdbuf

address

word

address

secondary

descriptor

receive

length

buffer

secondary

buffer

descriptor

Get I/0 Device Information
SGETDEV

devnam

address
of
descriptor

prilen

, [prilen]

,[pribuf]

device

address
of word

,[scdlen]

name

receive

,[scdbuf]

logical

length

name

primary

string

buffer

pribuf = address of primary buffer descriptor
scdlen = address of word to receive length of secondary buffer
scdbuf = address of secondary buffer descriptor

Get Job/Process Informatioh
SGETJPI

,[pidadr]

, [prcnam]

;itmlst

- pidadr = address of process identification
prcnam

itmlst

address

process

address

a list

name

string

descriptor

item descriptors

First, and fifth through seventh arguments,are reseryéd
Get

Message

SGETMSG
msgid

msgid ;msglen ,bufadr ,[flags] , [outadr]
= identification of message to be retrieved

msglen'= address
returned

word

receive

bufadr = address of buffer descriptor
string

length
buffer

of
to

string'
receive

QUICK REFERENCE SUMMARY OF SYSTEM SERVICES

flags

= flag bits for message content (macro default = 15)
Meaning

Bit

Value

1
0

Include text
Do not include

1
0

Include component
Do not include component

2
3

text

Include identifier
Do not include identifier
Include severity
Do not include severity

1
0
1
0

outadr = address of 4-byte array to receive
Contents

Byte

0
1
2
3

Reserved
Count of FAO
User value
Reserved

arguments

Get Time

timadr

SGETTIM

timadr = address of'a gquadword to receive 64-bit Current
|

value

time

Hibernate

SHIBER_S

SINPUT Macro

SINPUT chan ,length ,buffer

chan

,[iosb]

,[efn]

= number of the channel on which I/0 is to be performed

lehgth = length of the input buffer
buffer = address of the input buffer

iosb

efn |
Lock Pages

= address of quadword I/O status block

= event flag to walt onv(default»=0)

in Memory

$LCKPAG

inadr

,[retadr]

,[acmode]

starting

and

retadr = address of 2-1ongword array to receive addresses

inadr

of 2-longword array containing
= address
ending addresses of pages to be locked

pages actually locked

acmode

= access mode to check against the owner of the pages

QUICK REFERENCE SUMMARY OF

Lock

Pages

Working

Set

SLKWSET

inadr

address of 2-longword array
ending virtual addresses of

retadr

Global

,[retadr]

,[acmode]

address
of a 2-longword

acmode’

Map

SYSTEM SERVICES

ending

virtual

addresses

access

mode

containing
pages to be

array

starting
locked

receive

pages

checked

against

,[acmode]

, [flags]

and

starting
actually locked

the

page

and

owner

Section

- SMGBLSC

inadr ,[retadr]
, [relpag]

ygsdnam

address of 2-longword array containing

inadr

ending
retadr

addresses

address
addresses

of
of

,[ident]

pages

2-longword

array
mapped

pages

starting and

mapped
to

receive

virtual

acmode

access mode of owner of mapped pages

flags

flags overriding default section characteristics

Flag

Meaning

SECSM_WRT
SECSM_SYSGBL

Read/write section
System global section

gsdnam

address

ident

address of quadword
and match control

relpag

Convert Time

relative

global

page

section

name

containing

descriptor
version

identification
|

number

within

global

section

to Numeric

SNUMTIM
timbuf

timadr

timbuf
=

address

of a
information

7-word

address

quadword

U,
Buffer

,[timadr]

use

buffer

receive

numeric

current

containing

the

64-bit

time.

time

format:

time

16 15

month of year

year since 0

hour of day

day of month

second of minute

minute of hour

hundredths of second

1If

QUICK REFERENCE SUMMARY OF SYSTEM SERVICES
SOUTPUT Macro

$OUTPUT
chan

chan, length, buffer,

[iosb], [efn]

= channel on which I/0 is directed

length = length of the output buffer

buffer = address of the output buffer

iosb

= address of quadword I/O status block

efn

= event flag number to wait

(default = 0)

Purge Working Set
SPURGWS

inadr

1nadr

= address of 2-longword array containing

ending addresses of pages to be removed

starting

and

Put Meséage
SPUTMSG msgvec ,[actrtn] , [fEacnam]
msgvec = address of message argument vector

actrtn = address of entry mask of action routine
. facnam = address of facility name string descriptor
Queue

I/0 Request

) \_—4"/

$QIO

[efn] ,chan ,func ,[iosb] ,[astadr] , l[astprm]
,I[p2]

,I[p3]

,I[p4]l

,[p5]

,I[p6]

sQIow

,[pll

efn
chan
func

= number of event.flag'to set on completion
= number‘of channel on which I/O is directed
= function code specifying action to be performed

iosb

= address of quadword I/O status block to receive final
completion status information

astadr = address of entry mask of‘AST routine
astprm = value to be passed to AST routine as argument
pl...

= optional device- and function-specific parameters

Queue I/0 Request and Wait for Event Flag

See QIO for argument description

QUICK REFERENCE SUMMARY
OF SYSTEM SERVICES
Event

Flag

SREADEF
efn

efn

,state

event flag number of'any flag in the

<cluster

read

flags

1in

the

cluster

Process

SRESUME

[pidadr]

, [prcnam]

pldadr

address of process

identification of

resumed

process

name

string

[pidadr]

pidadr

address of process identification of

, [prcnam]

,daytim

, [reptim]

proceSS

prcnam

address of process name string descriptor

daytim

address

guadword

containing

time

reptim

address

gquadword

containing

repeat

to Dbe

to wake
time

interval

Enable

enbflg

enbflg
=

AST enable indicator
0 => disable ASTs for
1l

Event

enable

ASTs

for

event

flag

number

caller
caller

at
at

current
current

access
access

mode
mode

Flag

SSETEF
efn

Set

descriptor

SSCHDWK

SSETAST

Set

Wakeup

awakened

AST

\\\.—//

Schedule

process

address

prcnam

Set

address of a longword to receive current state of all

state

Resume

efn
=

flag

set

Exception Vector

SSETEXV

[vector]

vector

vector number
0 -> modify primary vector
1l -> modify secondary vector
2

addres

,[addres]

modify

exception

last

,[acmode]

chance

handler

, [prvhnd]

vector

address

indicates

deassign

vector)

acmode

prvhnd

access

address

mode

for

which

longword
C-16

vector

set

receive

handler

,‘\—/ J

Read

OF SYSTEM SERVICES
QUICK REFERENCE SUMMARY

Set Timer

‘)

SSETIMR

,daytim ,[astadr]

[efn]

to set when timer expires

= event flag

efn

,[regidt]

daytim

address of quadword containing 64-bit time value

astadr

address of

regidt

request identification of this timer request

entry mask of AST

routine

Set Power Recovery AST

SSETPRA astadr , [acmode]

)

astadr

address of power

acmode

access

mode

recovery AST routine

AST

Set Priority
, [prcnam]

[pidadr]

SSETPRI

priority

set

new

base

background,

priority
16

- 31

for

are

process

the

time-critical

0 - 15

are

address of longword to receive previous base priority

prvpri

Process

for

address of process name string descriptor

prcnam

Set

, [prvpri]

address of process~identification of process

pidadr

pri

,pri

Name

SSETPRN

[prcnam]

prcnam = address of the process name string descriptor

Set Protection on Pages
SSETPRT

inadr

,[acmode]

,[retadr]

,prot

,[prvprt]

= address of 2-longword array containing
virtual

ending

protection

addresses

for

starting

pages

and

change

and
starting
retadr = address of 2-longword array containing
addresses of pages which had their protection
ending
changed

returned

acmode

= access mode of

prot

= new protection

request

prvprt= address of byte to
last page

changed

receive

protection

QUICK

Set

Resource

Wait

SSETRWM
watflg

Set

System

SUMMARY

SYSTEM

Mode

wailt indicator

wait

return

Service

SSETSFM

Failure

for

resources

failure

status

_[enbflg]
=

enable

indicator

disable

generate

generation
service

~
g
exceptlons on

failures

exceptions

for

failures

Process

Swap

SSETSWM
swpflg

Send

Message

service

[swpflg]
=

swap
0 ->

enable

disable

indicator

Accounting

swapping

msgbuf

msgbuf =

address

chan

number of channel

Error

(lock

balance

set)

Manager

$SNDACC

Message

system

Mode

, [chan]
of

message

~Send

immediately

Mode

system

Set

SERVICES

[watflg]
=

enbflg

REFERENCE

buffer

string

assigned

descriptor

mailbox

receive

Logger

SSNDERR msgbuf
msgbuf

Send

Message

address

message

buffer

string

descriptor

Operator

$SNDOPR

msgbuf

address
of message buffer string desCriptor

chan

number
reply

Message

Symbiont

SSNDSMB

msgbuf

address

chan

number
reply

, [chan]

channel

assigned

mailbox

receive

Manager

, [chan]
of

message

channel

buffer

string

assigned

descriptor

mailbox

receive

QUICK REFERENCE SUMMARY_OF SYSTEM SERVICES
Suspend

Process

$SSUSPND

[pidadr]

, [prcnam]

pidadr

address

process

suspend

Translate

Logical

-~ STRNLOG

process

name

string

lognam

, [rsllen]

,rslbuf

,[table]

,[acmode]

lognam

address of logical name String descriptor

Arsllen

address of word to receive length of
address

result

table

address

byte

acmode

address

of byte
to
table only)

table

"Bit

Pages

Set

string

buffer

to receive

disable

name

descriptor

logical

receive

,[dsbmsk]

resultant

rslbuf

dsbmsk

Name

(process

name

access
.

table

mode

number

entry

mask

Meaning

not search

system

not

group

not

process

From Memory

SULKPAG

inadr

address

ending

Unlock

process

descriptor

string

Unlock

of
|

address

prcnam

identification

,[retadr]
of

,[acmode]

2-longword

virtual

array

addresses

containing

of pages
to

starting

and

unlocked

retadr

address of a 2-longword array to receive starting and
ending virtual addresses of pages actually unlocked

acmode

access mode to check against the owner of the pages

Pages

From Working

SULWSET
inadr

inadr

, [acmode]

virtual

addresses

pages

starting
unlocked

and

address of a 2-longword array to receivevstarting and

ending
acmode

,[retadr]

address of 2-longword array containing

ending
retadr

Set

virtual

addresses

pages

actually

unlocked

access mode to check against the owner of the pages»

" QUICK REFERENCE SUMMARY OF SYSTEM SERVICES
Unwind

Call

Stack

SUNWIND

[depadr]

, [newpc]

depadr = address of number of logical frames

stack

newpc

change

Update Section File
SUPDSEC

flow

unwind

call

on Disk

inadr ,[retadr]
,[acmode]
, lastadr]
,[astprm]

,[updflg]

,[efn]

inadr

address of 2-longword
ending
addresses
of
written
B

array containing
the
pages
to

retadr

address of 2-longword
the
first
and
last

array
page

starting
and
be potentially

to receive
gqueued
1in

request

,[iosb]

addresses
the first

of
I/O

acmode
= access
mode
performed

behalf

which

the

'service

1is

updflg = update indicator
for writable global sections
->
->

write
write

efn

number of
updated

10sb

address

all
all

read/write pages in the section
pages modified by the caller

event
B

flag
-

of quadword

I/O

set

when

status

the

section

file

block

0
1l

astadr = address of entry mask of an AST service routine

astprm = AST parameter to be passed to the AST service routine

Wait for Singie Event Flag
SWAITFR

efn

event

SWAKE

[pidadr]

flag

number

event

wait

for

Wake

,[prcnam]

pidadr = address of process identification of

~awakened

process

prcnam = address of process name string descriptor

Dbe

QUICK REFERENCE SUMMARY OF SYSTEM SERVICES

Wait for Logical AND of Event Flags
SWFLAND

efn
mask

efn

,mask

= event flag number of any flag within the cluster
32-bit mask of

flags

that must be set

Wait for Logical OR of Event Flags
SWFLOR

efn

,mask

efn

event flag number
of any flag within the cluster

mask

32-bit mask of

flags,

any of which must be set

INDEX

SACCDEF macro,
process termination message
offsets, 4-39
symbols defined, 4-149

SLCKPAG format, 4-107
SLKWSET format, 4-109
SMGBLSC format, 4-111
SMSGDEF macro, A-7

SADJWSL format, 4-5

SnameDEF macro, 2-5

SADJSTK format, 4-3

symbolic names defined,

A-7

$name_G form of system service

SALLOC format, 4-6

SASSIGN format, 4-12

macro, 2-3
example, 2-4
$name_S form of system service

SCANCEL format, 4-19
SCANEXH format, 4-21
SCANTIM format, 4-22

SNUMTIM format, 4-114
SOPCDEF macro, 4-155
symbols defined, 4-155

SCHFDEF macro, 3-67
SCLREF format, 4-25
SCMEXEC format, 4-26
SCMKRNL format, 4-27
SCNTREG format, 4-28

example, 3-25
format, 4-116
SPQLDEF macro, 4-40
symbols defined, 4-41
SPRDEF macro, A-7

SASCEFC format, 4-38
SASCTIM format, 4-10

macro, 2-6
example, 2-8

SBINTIM format, 4-15
SBRDCST format, 4-17

SOUTPUT macro,

SCANWAK format, 4-23

SCRELOG format,
SCREMBX format,
$CREPRC format,
SCRETVA format,
SCRMPSC format,
SDACEFC
SDALLOC
SDASSGN
SDCLAST

format,
format,
format,
format,

symbols defined, A-7
$PRTDEF macro, 4-143
symbols defined, A-7
SPRVDEF macro, 4-36
symbols defined, 4-36
SPSLDEF macro, A-8
symbols defined, A-8
SPURGWS format, 4-117
SPUTMSG format, 4-118
$SQIO format, 4-124

4-30
4-32
4-35
4-44
4-46

4-52
4-53
4-55
4-57

SDCLCMH format, 4-58

SQIOW,

SDCLEXH format, 4-60

$SINPUT and $OUTPUT forms, 3-25

$SDELLOG format, 4-62

format, 4-127

$SDELMBX format, 4-64

$READEF format, 4-128
SRESUME format, 4-129

SDELPRC format, 4-66
$SDELTVA format, 4-68

SSCHDWK format, 4-131
SSECDEF macro, 4-46

$DGBLSC format, 4-70
SDIBDEF macro,
symbols defined, 4-93
|
SDLCEFC format, 4-72
SEXIT format, 4-73
SEXPREG format, 4-74
SFAO format, 4-76
SFAOL format, 4-77
SFORCEX format, 4-90
SGETCHN format, 4-92
'SGETDEV format, 4-95
SGETJPI format, 4-97
SGETMSG format, 4-102
SGETTIM format, 4-104
SHIBER format,

- symbols defined, 4-46, 4-112

~ SSETAST format, 4-133
SSETEF format, 4-134
SSETEXV format, 4-135
SSETIMR format, 4-137
SSETPRA format, 4-139
SSETPRI format, 4-140
SSETPRN format, 4-142
SSETPRT format, 4-143
SSETRWM format, 4-145
SSETSFM format, 4-146
SSETSWM format, 4-147

4-105

SINPUT macro,

example, 3-25
format, 4-106

SIODEF macro, 3-22
symbols defined, A-6

$JBCMSGDEF macro, 4-152,

SJPIDEF macro, 4-98
symbols defined, 4-100

4-167

SSMRDEF macro, 4-160
symbols defined, 4-163
SSNDACC format, 4-148
SSNDERR format, 4-153
SSNDOPR format, 4-154
SSNDSMB format, 4-159
S$SSDEF macro, 2-11
symbols defined, A-8

$SUSPND format, 4-169

Index-1

INDEX

STRNLOG
SULKPAG

format,

4-171

format,

4-173

(Cont.)

AST (Cont.),
delivery, 3-13
disable/enable

SULWSET format, 4-175
SUNWIND format, 4-177
SUPDSEC format, 4-179
SWAITFR format, 4-182
SWAKE format, 4-183
SWFLAND

SWFLOR

format,

access
power

service

4-185

modes,

buffer

|
information,

summary,

3-56

format,

I/0

completion,

used with

4-15

3-10

1-3

synchronize

3-23

modes,

3-12

3-13

services,

Access

4-139

routine,

example,

4-186

time,

4 133

3—12

recovery,

general

Absolute

dellvery,

execution,

|
,
services,

timer

3-58

1-2

example,

conventions
for coding,

3-60

2-10,

2-18

effect

on AST delivery,
symbolic names defined,

3-14

A-8

file, 4-148
of records, 4-151
interface driver I/O
function codes, A-6

format
ACP

Balance

set, 3-82,
swapping, 3-82

Broadcast

Addresses,

($BRDCST)
service, 4-17

virtual, 3-79
Adjust Outer Mode Stack Pointer
(SADJSTK) system service,
4-3
Adjust Working

(SADJWSL)

Limit

system

service,

4-5

increase working
Allocate Device

service,

example,

Cancel
.

set

size,

(SALLOC)

device,
for

Cancel

system

Cancel

4-6
|

Cancel

AST service

routine,
system services,
format, 2-2

3-12

passed

3-67
Arguments,

2-17

summary,

Arrays,

Card

2-17

for

handlers, 3-68
virtual address,

ASSIGN

command,

Assign

I/O Channel

system

example,

3-15

(SASSIGN)

serv1ce,

4-12

Associate Common Event Flag
Cluster ($ASCEFC) system
service, 4-8

examples,
AST,

3-7,

3-9

reader

($CANWAK)

system

4-23

wakeup

requests,

driver

1/0

3-61

func-

1-5

executive,

kernel,

(SCMEXEC)

4-26

4-27

system service,

4-26

Change

Kernel

system

Mode

service,

(SCMKRNL)

4-27

Channel

assignment, 3-21, 4-12
mailboxes, 4-32
‘
Character string descriptor,
2-18
FORTRAN

4-57

example,

(SCANTIM)

'Change to Executive Mode

3-10

declare,

4-19

4-22

3-60

summary,

condition

|
3-80

Request

tion codes, A-5
Change mode,
|
handler, 3-64, 4-58
services,

lists

4-21

($SCANCEL)

3-27,

service,

Wakeup

cancel

condition handler,

- FORTRAN coding
argument

Timer

service,

for

Channel

3-27

examples,

2-2

(SCANEXH)
3-49,

service,

system

3-28,
list,

I/O On

example,

3-29

Handler
service,

system

4-6

Allocation,
Argument

Exit

system

3-81

system

Set

4-147

Accounting

3-14
Index-2

coding,

MACRO

coding,

macro

2-18

2-9

generate,

2-10

INDEX

(SCLREF)

Clear Event Flag

svystem service,

(Cont.)

Create

Process

service,

4-25

examples,

example,
3-6

(SCREPRC)

3-38

event flag, 3-4
Common event flag cluster,
4-8

4-44

3-7,

for process communication,

3-44

Compatibility mode handler,
4-58

Date,

Condition handler, 3-63
courses of action, 3-69
‘declare on call stack, 3-64
example of condition handling
routines, 3-72
search of

call

stack,

Condition handling

system format, 3-56
|
Deallocate Device ($SDALLOC)
system service, 3-29, 4-53
Deassign I/O Channel (SDASSGN)

system

3-66

services,

general information,

3-63

example,
Declare

1-5

4-28

,
“

disk

Conventions

for coding,

access

2-11

to
2-8

FORTRAN,

system services,

3-57,

system

Delete

- Delete

4-64

Process

($SDELPRC)

3-53,

Virtual

example,

system

4-66

Address

Space

system service,

Section

common event flag clusters,
3-8, 4-72
mailboxes, 3-33, 4-64

(SCRMPSC)

4-46

processes,

(SCRELOG)
4-30

3-15

4-68
Delivery,

Create Mailbox and Assign

AST,

Channel ($CREMBX)
service, 4-32
3-34,

3-54

system

3-53,

timer requests,
virtual address

3-86

Create Logical Name
systém service,

3-78

Delete,

4-114

system service,

examples,

3-40

Flag

4-68

3-57

example of mapping a section,

example,

Event

(SDELTVA)

Convert Binary Time to Numerlc
Time (SNUMTIM) system
- -service,

process,

Common

service,

4-10

Create and Map

system

2-8, 2-14
and directory
for

service,

3-58

Convert Binary Time to ASCII
String (SASCTIM) system
example,

for

Delete Logical Name (S$SDELLOG)
system service, 4-62
Delete Mailbox (SDELMBX) system

2-16

Time (SBINTIM)
service, 4-15

service,

Compatl—

Cluster (SDLCEFC) system
service, 4-72
Delete Global Section ($SDGBLSC)
system service, 4-70

2-11

Convert ASCII String to Binary
examples,

3-50

created

Delete

MACRO,

Mode

services,

4-78

arguments

Change

arguments

string,

modes,

3-14

example,
Default,

4-60
3-77

contract, 4-28
expand, 4-74
‘FAO,.

system

bility Mode Handler (SDCLCMH)
system service, 4-58
Declare Exit Handler (SDCLEXH)
system service, 4-60

example,

Control

4-55

3-25

Declare AST (SDCLAST)
service, 4-57

Contract Program/Control Region
(SCNTREG) system service,
3- 78
Control block,
exit handler,
Control region,

service,

example,

3-63
summary,

Create Virtual Address Space
|
(SCRETVA) system service,

Clusters,

3-64,

system

4-35

4-66

3-60, 4-22
space, 3-78,

3-13
|

enable/dlsable, 4-133
Delta time, 3-56
how to specify, 3-58

Index-3

INDEX

DESCRIPTOR macro,

Event flag

2-10

general information,

character string,
FORTRAN coding, 2-19
MACRO coding, 2-9
Detached process, 3-41
compared with subprocess,

allocate,

3-28,

4-6

assign I/0 channel,
3-31

physical names vs.

1-3,

3-4

summary, 1-3
setting, 4-134

used with I/O. services, 3-23
used with timer services, 3-58

example, 3-59
“waits, 3-5, 3-11

3-21,

deallocate, 3-29, 4-53
information, 4-92, 4-95
names,

(Cont.),

services,

Descriptor,

3-37
Device,

(Cont.)

4-12

Exception, 4-146
caused by system service
failure, 4-146

conditions,

logical

3-63

3-70
dispatcher, 3-64
summary,

names, 3-29
Directive (FAOQO),

vectors, 3-64, 4-135
Exit (SEXIT) system service,

format, 4-78
summary, 4-80

4-73

cause image exit,
Exit, 4-90

Disassociate Common Event Flag
Cluster (SDACEFC) system
service, 4-52
3-7

example,

Disk driver I/0O function codes,

forced, 4-90
handler, 4-60
cancel, 4-21

A-3

control block

Dispatcher,
exception,

example, 3-50
image exit, 3-47

3-65

DMCl1l driver I/O function codes,

3-48

format,

4-60

Expand Program/Control Region
(SEXPREG)

A-5

system service,

4-74

example,

E
Equivalence names,

3-15

Error,

cause exception condition,
2-13

checking,
FORTRAN, 2-22
MACRO, 2-12
logger,
send message to,
messages,

FAO,

3-31,

4-76

control string,
directives,

summary,

2-11,

stream defined for process,
Event flag, 3-4
clearing, 4-25
clusters, 3-4
common clusters, 3-7
associate, 3-7, 4-8
create, 3-7, 4-8
delete, 4-72
disassociate, 4-52
read status of, 4-128

4-80

Force Exit (SFORCEX)
service, 4-90

2-20

4-78

examples, 4-83
format, 4-78

|
4-153

obtain text, 4-102
output, 4-118
return status codes,

3-39

3-78

system

contrast with process
deletion, 3-53
Formatted ASCII Output (SFAO)
system service, 4-76
|
examples, 3-32, 4-84
Formatted ASCII Output with
List Parameter (S$FAOL)
-macro, 4-77
example, 4-85
FORTRAN,

coding system service calls,
2-14,

2-15

function reference, 2-15
procedure call, 2-15

Index-4

' INDEX

(Cont.)

Function codes for I/0 operations,
summary,

3-22
A-3

2-15

$QI0 system service, 4-124
$SQIOW system service, 4-127

cancel,

4-92

example,

3-54

Get I/0O Device Information
(SGETDEV) system service,
4-95

Get Job/Process Information
(SGETJPI) system service,

obtain information,

used for process control,
3-86

Get Message

(SGETMSG)

summary, l1l-4
status block, 3-24,

group and system, 3-85
mapping, 3-87, 4-46, 4-111
temporary and permanent, 3-85
3-16

logical name table,

exit, 3-47, 4-73
compared with process
deletion, 3-55
exit handlers, 3-49
forced, 3-50,
rundown, 3-48

3-53

3-53,

4-90

conventions for coding,

2-10,

force exit,

3-50,

2-18
Input,

stream defined for process,

3-16

number,

4-126

Indicators,

4-70

3-21

Image,

service, 4-102
Get Time (SGETTIM) system
service, 3-57, 4-104
Global sections, 4-70
creating, 4-46
deleting,

4-95

general information,

system

defined, 3-82

4-92

example, 3-26
function codes,
how used, 3-22
summary, A-3
mailboxes,
example, 3-34
services,

4-97

3-39

terminal I/0, 3-26
virtual blocks, 4-106

qualify process names, 3-43
restrict system service
use,

4-19

assign, 3-21, 4-12
deassign, 4-55
obtain information,
device,

Get I/0 Channel Information
(SGETCHN) system service,

Group,

3-27,

channels,

3-44,

I/0,

Function reference, 2-15
FORTRAN system service call,

1-2

Line printer driver I/O

change mode, 4-58
compatibility mode, 4-58
condition, 3-63
exit, 3-49, 4-60
cancel, 4-21
Hibernate (SHIBER) system
service, 4-105
example, 3-46
Hibernation, 3-45

compared with suspension,
3-45

schedule wakeup,

function codes,

A-4

system service,

4-107

Lock Pages in Memory (SLCKPAG)

Handler,

3-61

Lock Pages in Working Set
(SLKWSET) system service,
4-109

increase program efficiency,
Lock

3-81
pages,

memory, 3-82
working set, 3-81
Logical names, 3-15
create, 4-30
example, 3-15

Index-5

INDEX

Logical names

(Cont.)

(Cont.),

delete,

3-19,

4-62

process

permanent

files,

3-19

Open,

general

information,

summary,

tables,

1-4

example,

for

tion,

use

to,

4-154

Output,

3-18,

4-171

services,

process

format

3-29

character strings,

formatting with

communica-

stream defined

3-44

3-39

virtual

blocks,

4-118

4-116

Owner,

of memory

tape

function

driver
codes,

Mailbox driver
codes,
Mailboxes,

example

I/O
A-4
Page,

4-32

define

creation

for

used

process

and

Map

for

process

termination
(SMGBLSC)

system

service,

4-111

Mapping,

global

set

3-54

Section

3-87°

3-87
sections,

3-87,

4-46,

FAO,

4-109

|
services,

general

information,

summary,

unlock

3-77

l1l-5

pages,

2-12,

system status

3-41

use

4-140

1-1

Process,

services,

general
- summary,

creation,
example,
2-5

Numeric time buffer
4-114

4-159

|
system services,

control

NARGS

3-13

defined for process, 3-41,
4-35
required for process control

4-102

output,
. 4-118

routine,

creating and mapping, 4-46
Privilege,
defined by access mode, 1-2

Messages,

codes,

service

queue,

set or change process,
Private sections, 3-82

4-173

associated W1th

A-7

4-78

manipulate,
Priority,

4-107,

management

4-143

names,

Parameter,

2-11
3-82,

change,

Paging,

for AST

Memory,
-

pages,

3-85

sections, 3-89
working set, 3-81

sections, 3-83, 3-85
Maximize access mode,

lock

symbolic

4-111

definition,

in section,

define in section, 3-85
lock in memory, 4-107
lock in working set, 4-109
protection,
-

communica-

Global

example,
-

I/0,

3-44

message,

3-85

demand-zero,

tion,

3-77,

copy-on-reference,

3-34
used

3-80

4-32
4-64

page,

I/O function

A-5
3-33,

creating,
deleting,

4-76

$FAO, 3-31
for process,

system messages,

Magnetic

3-83

send message

translation,
used

for

Operator,

3-17

I/0O

file

section,

3-15

3-16

used by

disk

services,

1nformatlon,

3=-37

l1l-4

4-35
3-42

deletion,

3-51,

3-55

4-66
compared with image exit,

format,

Index-6

INDEX V(Cont.)

RMS

|
Process (Cont.),
- detached process, 3-37
on,
identificati3-42
logical name table, 3-16
name,

(Record Management Services),
3-21

3-83

open file for mapping,

3-42

qualified by group number,
3-43

set or change,

4-129

4-140

set or change priority,
subprocess, 3-37
suspend, 4-169

Schedule Wakeup ($SCHDWK)
system service, 4-131
cancel wakeups, 3-61, 4-23
|
example, 3-61
Search of call stack,
exception dispatcher, 3-66
Sections,

4-39

Processor registers,
symbolic names, A-7
Processor status longword,

deleting,

symbolic field definitions,

Program region, 3-77, 3-78
4-28

3-78
|

Protection,
page, 4-143

Purge Worklng
service,

Put Message
service,

system

(SPURGWS)
4-117

($PUTMSG)

system

4-118

3-90

examples,
global,

3-83,
|

3-86

4-70

deleting,

contract,

3-82

checkpoint, 3-90, 4-179
creating, 3-83, 4-46
defining extents, 3-84

termination message format,

example of expanding,
expand, 4-74

B-1

Sample programs,

4—142

obtain information, 4-97
permanent files, 3-19
resume after suspension,

mapping, 3-87, 4-111
mapping, 3-85, 4-46
paging,

3-89

private, 3-82, 4-46
unmapping, 3-90

using to share data, 3-89
Send Message to Accounting
Manager ($SNDACC) system

service, 4-148
Send Message to Error Logger B
($SNDERR) system service,
4-153

Send Message to Operator

Q
Queue I/0 Request

($QIO)

system

service, 4-124
example, 3-22

Queue I/0 Request and Wait for
Event Flag
service,

Quotas,

($QIOW)

system

4-127

4-40

4-154

Send Message to Symblont

AST,

3-12

Set AST Enable

(SSETAST)

Set Event Flag

(S$SSETEF)

service,

system service,

(SSETPRA)

4-128

4-139

quotas, 1-1, 4-40
wait mode, 2-13
set or change, 4-145
'Resume Process ($RESUME) system

obtain system messages,

system

(SSETEXV)

3-64,

4-135

Set Power Recovery AST

Resource,

4-129
service,
Return status codes,
FORTRAN coding, 2-20
MACRO coding, 2-11

4-133

4-134

3-6,

Set Exception Vector

Read Event Flags (SREADEF)
system service,

system

Manager (SSNDSMB)
service,; 4-159
Service routine,

system service,

summary,

system service,

($SNDOPR)

4-103

Set Priority
service,

system service,
|

(SSETPRI)

system

4-140

Set Process Name

(SSETPRN)

system service,

4-142

Set Process Swap Mode

($SETSWM)

svstem service, 4-147
example, 3-82
Set Protection on Pages
(SSETPRT) system service,
4-143

A-8

Index—7

INDEX

Set

Resource

Walt

(SSETRWM)

Mode

system service,

4-145
Set

(Cont.)

Termination mailbox,

System

Service

Faillure

(S$SSETSFM)

system service,

4-146

Timer (SSETIMR)
service, 4-137
example with AST,

example with
3-5
examples,

flag,

Timer requests,

(S$SSUSPND)

4-169

cancel,

3-47

hibernation,

"Translate

Logical

Name

service,

set,

status

Unlock

Pages

from Working

(SULWSET)
A-2

4-175
Unwind Call
system

A-7

example,

codes,

use in error checking, 2-11
Synchronize I/0 completion,
I/0 status block (IOSB), 3-24
logical

name table,

System

service

failure

Stack

3-16

Update

4-146

4-177

call

Section

stack,

File

User privileges,

MACRO,

codes,

form,

Virtual address
3-78, 3-79

function

A-3

Terminal, 3-21
assign channel, 3-21
broadcast messages to,

1-1

Sname macro, 2-3
Sname_G form, 2-3

3-16

Sname_S

I/0O

4-179

logical name,
driver

3-74

Disk

(SUPDSEC) system service,

VAX-11

Set

3-75

coding system service

Table,

)

(SUNWIND)

service,

exception mode, 3-63
exception condition, 2-13
change,

system service,

Unwinding the

A-9

System

system service,

4-173

4-160

4-159

page protection, A-7
processor registers,

4-171

‘Unlock Pages from Memory
(SULKPAG)

to,

3-18,

Terminal

(STRNLOG)

4-171
|

swapping,

from balance

B
|

logical name,

3-82

)

Translate,

Symbolic names, 2-11
obtain numeric values,

3-58

4-135

system

format of messages,

set

3-56

3-60,

setting,

3-82

summary,

|
4-114

general information,
summary, 1-4

3-38

3-82
Symbiont manager,

system

3-61

format,

and time conversion
services, 3-56

service,

message

4-15

integer

Timer

3-82

send

4-15

system format, 3-56
~ obtain, 4-104

disallow process
process

buffer,

binary

values,

mode,

Swapping,

buffer

Process

disable,

time

convert

deletion, 3-53
example of creating,

Swap

format,

3-10

event

compared with
3-45

4-39

system

Subprocess,

system

3-53

SASCTIM, 3-57
convert to ASCII, 4-10
convert to binary, 3-57,

3-60

Suspension,

format,

absolute

Stack pointer,
modifying, 4-3

Suspend

message

ASCII

2-13

Set

3-54

Time,

Exception Mode
example,

example,

add

and

add

pages,

delete

calls,

2-6

space,
~

3-77,

addresses,

4-44,

3=-79

4-74

delete

pages, 4-28, 4-68
layout, 3-77, 3-78
mapping sections into, 3-85
specifying arrays, 3-80

4-17

Index—-8

;
|

)

INDEX

)
.

VV -

Wait for Logical AND of Event
Flags (SWFLAND) system
service, 4-185
examples, 3-6, 3-9
Wait for Logical OR of Event
Flags (SWFLOR) system
service, 4-186

Wait for Single Event Flag
~

(SWAITFR) system service,
4-182
example, 3-9
.
Wait,

event flag,
I/0, 3-25

3-5

(Cont.)

wait (Cont.),

resource wait mode, 2-13
set or change, 4-145
o
Wake (SWAKE) system service, 4-183
example, 3-46
a hibernating process,
Wakeup
|
3-46
timer scheduled, 3-61,
cancel, 4-23
Working set, 3-81
lock pages, 3-81
paging, 3-81
purge, 4-117
size,

changing, 3-81, 4-5
unlock pages, 4-175

Index-9

4-131

~—

VAX/VMS
System Services
Reference Manual

AA-DO18A-TE

READER'S

COMMENTS

This form is for document comments only.
DIGITAL will
use comments submitted on this form at the company's
discretion.
If you require
a written reply and are
eligible to receive one under Software Performance
Report (SPR) service, submit your comments on an SPR

NOTE
:

form.

Did you find this manual understandable, usable,
suggestions

for

improvement.

Did you find errors in this manual? If so,

and well-organized?
|

specify the error and the

page number.

Please

indicate

OOy

Please cut along this line.

Please make

the

Assembly

type of

language

Higher-level

reader

that you most nearly

programmer

language programmer

Occasional programmer

(experienced)

User with little programming experience
Student programmer
Other

(please

specify)

Name

Date

Organization
Street

City.

State

'
-

Zip Code
or

Country

represent.

- — — — DoNotTear-FoldHereandTaper'; —_ - - = — —_ —

NoNecessary
Postage || >

if Mailed in the |

United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

RT/C SOFTWARE PUBLICATIONS

TW/A14

DIGITAL EQUIPMENT CORPORATION

1925 ANDOVER STREET

- — —

Do Not Tear - Fold Here

—

— —

—

—_—

—

— —

01876

—

— _—

—]

Cut Along Dotted Line

TEWKSBURY, MASSACHUSETTS

dlilgliltlall

PRINTED IN USA