Digital PDFs

AA-H784A-TE

March 1980

193 pages

Original

8.4MB

Document:	VAX/VMS Real-Time User’s Guide
Order Number:	AA-H784A-TE
Revision:	000
Pages:	193
Original Filename:

OCR Text

VAX/VMS
Real-Time User's Guide
Order No. AA-H784A- TE

March 1980

This manual discusses VAX/VMS features of interest to real-time users. It also
provides programming examples illustrating certain important or complex
features.

VAX/VMS
Real-Time User's Guide
Order No. AA-H784A-TE

SUPERSESSION/UPDATE INFORMATION:

This is a new document for this release.

OPERATING SYSTEM AND VERSION:

VAX/VMS V02

SOFTWARE VERSION:

VAX/VMS V02

:~~~~~c.~ment,

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

-digital equipment corporation . maynard, massachusetts
-

--··-··"·'" ___

.,. ._,,_._._

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

@) 1980 by Digital Equipment Corporation

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

DIGITAL
DEC
PDP
DECUS
UNIBUS
COMPUTER LABS
COMTEX
DDT
DEC COMM
ASSIST-11
VAX
DECnet
DATATRIEVE

DECsystem-10
DECtape
DIBOL
EDUSYSTEM
FLIP CHIP
FOCAL
IND AC
LAB-8
DECSYSTEM-20
RTS-8
VMS
IAS
TRAX

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

CONTENTS

Page
PREFACE
CHAPTER

vii
l
1.1

l. 2
l. 2 .1
l. 2. 2
l. 2. 3
l. 2. 4
l. 2. 5
l. 3
1.4
l. 4 .1
1.5
l. 5 .1
l.n
l.fi.l
i. n. 2

CHAPTER

2.1
2. l. l
2.1.2

REAL-TIME NEEDS AND VAX/VMS FEATURES
OTHER VAX/VMS TOOLS
Condition Handling
Device Allocation
SYSGEN Parameter Selection
User Authorization File Entries
Networks
REAL-TIME DEVICES
USER PRIVILEGES FOR REAL-TIME APPLICATIONS
Privilege Masks
PROCESS QUOTAS
Resource Wait Mode
PROCESS PRIORITY
Significance of Process Priority
Adjusting the Base Priority
CONTROLLING THE PROGRAM EXECUTION
ENVIRONMENT

1-2
1-4
1-4
1-4
1-5
1-5
1-5
1-5
1-'1

1-7
1-7
1-9
1-9
1-10
1-11

2-1

2.2.4

PROCESS CREATION
Subprocesses and Detached Processes
Real-Time Uses of Detached Processes
and Subprocesses
Create Process System Service
RUN (Process) Command
PHYSICAL MEMORY CONTROL
Adjusting the Working Set Limit (SADJWSL)
Keeping Pages in the Working Set ($LKWSET)
Keeping Pages in Memory ($LCKPAG)
Keeping the Process in Memory ($SETSWM)

COMMUNICATING AND SHARING BETWEEN PROCESSES

3-1

3.1
3. l. l
3 .1. 2
3. l. 3

COMMON EVENT FLAGS
Creating and Associating with Clusters
Setting Event Flags
Waiting for Event Flags
MAILBOXES
Creating a Mailbox
Other Mailbox Services
Example Using a Mailbox
ASYNCHRONOUS SYSTEM TRAP SERVICE ROUTINES
System Services with AST Service Routine
Arguments
Access Modes and AST Delivery
HIBERNATION AND SUSPENSION
Example 1: Wakeups as Needed

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

2. l. 3
2.1.4
2.2

2.2.l
2.2.2
2.2.3
CHAPTER

1-1

3.2
3.2.l
3.2.2
3.2.3
3.3
3.3.l

3.3.2
3.4
3.4.l

iii

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

2-n
2-n

2-7
2-8

3-n

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

CONTENTS

Page

CHAPTER

3.4.2
3.5
3.5.l
3.5.2
3.6

Example 2: Wakeups at Fixed Intervals
GLOBAL SECTIONS
Creating and Mapping a Global Section
Other Section-Related System Services
SHAREABLE IMAGES

3-15
3-15

PERFORMING I/O OPERATIONS

4-1

4.1

OVERVIEW OF THE VAX/VMS I/O SYSTEM
Queue I/O Request System Service
Ancillary Control Processes
Device Drivers
I/O Posting Routine
USER INTERFACE TO THE I/O SYSTEM
VAX-11 RMS Features of Interest to
Real-Time Users

4-1

4 .1.1
4 .1. 2
4 .1. 3

4.1.4

4.2
4.2.1

4.3

USING THE QUEUE I/O REQUEST SYSTEM SERVICE

INTERRUPT-GENERATED I/O
MAPPING I/O SPACE
Page Frame Number (PFN) Mapping
4.5.1
Programming Conventions for Addressing
4.5.2
Device Registers
4.6
CONNECTING TO AN INTERRUPT VECTOR
Interrupt Priority Levels
4.6.1
Performing the Connect-To-Interrupt
4.6.2
4.6.3
The Connect-To-Interrupt Driver
The Interrupt and AST Service Routines
4.6.4
Queue I/O Request System Service for
4.6.5
Connect-To-Interrupt
Conventions for Process-Specified Routines
4.6.6
4.6.7
Programming Language Constraints
Process-Specified Device Initialization
4.n.8
Routine
Process-Specified Start I/O Routine
4.6.9
Process-Specified Interrupt Service Routine
4.6.10
Process-Specified Cancel I/O Routine
4.6.11
4.n.12
Real-Time Applications Examples
4.6.12.1 Example 1: KWll-W Watchdog Timer
4.6.12.2 Example 2: ADll-K, AMll-K; A/D Converter
with Multiplexer Connected to the UNIBUS
4.n.12.3 Example 3: KWll-P Real Time Clock and
ADll-K Converter Connected to the UNIBUS
4.4

4.5

CHAPTER

3-11

3-12
3-14

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

4-f)
4-7
4-8

4-10
4-11
4-11

4-12
4-13

4-14
4-15
4-18

4-19
4-20
4-20
4-21

4-21
4-22
4-23

4-24

4-2()

USING SHARED MEMORY

5-1

5.1
5.2
5.3

PREPARING MULTIPORT MEMORY FOR USE
PRIVILEGES REQUIRED FOR SHARED MEMORY USE
NAMING FACILITIES IN SHARED MEMORY
ASSIGNING LOGICAL NAMES AND LOGICAL NAME
TRANSLATION
HOW VAX/VMS FINDS FACILITIES IN SHARED MEMORY
USING COMMON EVENT FLAGS IN SHARED MEMORY
USING MAILBOXES IN SHARED MEMORY
USING GLOBAL SECTIONS IN SHARED MEMORY
Create and Map Section System Service

5-1
5-2
5-2

5.4
5.5
5. f)

5.7
5.8
5.8.1

5-3
5-5
5-5

5-f)
5-7
5-8

CONTENTS

Page
PRIVILEGED SHAREABLE IMAGES

CHAPTER

6.1
6 .1.1
6 .1. 2

()-1

6-3
11-4

6.3
() • 4
6.5

CODING THE PRIVILEGED SHAREABLE IMAGE
Change-Mode Vector
Entry Point to the Privileged Shareable
Image
Kernel-Mode
Executive-Mode Dispatcher
Enabling and Disabling User Privileges
LINKING THE PRIVILEGED SHAREABLE IMAGE
Specifying Protection for the Image or
Clusters
INSTALLING THE PRIVILEGED SHAREABLE I~AGE
USING THE PRIVILEGED SHAREABLE IMAGE
PROGRAM LI STINGS

PROGRAM EXAMPLES

7-1

6.1.3
6.1.4
6.2
6.2.l

CHAPTER

n-1

DATA ACQUISITION AND MANIPULATION
7.1
Application Overview
7 .1.1
LABIO System Details
7 .1. 2
7.1.2.1
Shared Data Base
7.1.2.2
Common Event Flag Clusters
7.1.2.3
Mailboxes
7.1.2.4
Connecting to an Interrupt Vector
7 .1. 3
Typical LABIO User Program Loqic
Program Listings
7 .1. 4
AIRLINE RESERVATION SYSTEM
7.2

6-2
t;-3
n-3

n-4
<1-5
fi-5

6-5

7-1
7-1
7-3
7-3
7-3
7-4
7-4
7-4

7-5
7-45

LOCKING A RESOURCE

A-1

A. l
A.1.1
A.2
A.2.1

USING AN EVENT FLAG
Shared Memory Considerations
USING A QUEUE
Shared Memory Considerations

A-2
A-4
A-4
A-n

LPAll-K CONSIDERATIONS

B-1

B.l
B.2
B.3

RESOURCES, CONFIGURATION, AND PERFORMANCE
THROUGHPUT AND RESPONSE-TIME REQUIREMENTS
PARAMETERS FOR DATA ACQUISITION CALLS

B-1
B-2
B-3

APPENDIX

VAX-11 BLISS-32 PROGRAM EXAMPLE

C-1

APPENDIX

REAL-TIME OPTIMIZATION CHECKLIST

D-1

APPENDIX

Index-1

INDEX

FIGURES
FIGURE

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

()-1

Using a Mailbox to Communicate
Access Modes and AST Delivery
Physical Address
Two VAX-ll/780s Attached to an MA780
Using a Shared Memory Mailbox
Change-Mode Vector Format

3-7
3-9
4-7
5-1

5-7
n-2

CONTENTS
FIGURES (Cont.)

Page
FIGURE

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

Event Flag Lock Logic
Event Flag Lock Example
FIFO Queuing Policy
LIFO Queuing Policy

A-2
A-3
A-5
A-7

TABLES
TABLE

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

A-1

Real-Time Needs and VAX/VMS Features
Summary of Process Quotas
Subprocess versus Detached Process
Features for Communication, Synchronization,
and Sharing
Summary of Event Flag Clusters
Temporary versus Permanent Mailboxes
Hibernation versus Suspension
Global Sections versus VAX-11 RMS
Two Methods of Creating a Lock

1-3
1-8
2-2
3-1
3-2
3-5
3-10
3-13
A-1

PREFACE

MANUAL OBJECTIVES
The VAX/VMS Real-Time User's Guide describes VAX/VMS features of
interest to real-time application programmers.
It describes in
general terms functions common to a variety of real-time applications
and explains the specific VAX/VMS feacures available to perform these
functions. This manual also contains numerous examples,
including
coding segments and complete programs, to illustrate certain important
or complex features.

INTENDED AUDIENCE
This manual
is
intended
for
programmers
writing
real-time
applications.
You are assumed to have substantiaJ programming
experience and some knowledge of basic VAX/VMS
concepts
(see
"Associated Documents" in this preface).
The programming examples are in VAX-11 MACRO and VAX-11 FORTRAN. Each
example, however,
is designed to be as meaningful as possible for
programmers using any other VAX-11 language.

STRUCTURE OF THIS DOCUMENT
This manual covers a variety of topics, usually proceeding from less
complex to more complex material. Wherever appropriate, this manual
relates a topic to other topics discussed elsewhere in the manual.
Chapter 1 introduces the manual.
It summarizes the real-time features
covered in the manual, describes other features of possible interest
and refers to appropriate documentation, and explains some significant
concepts.
Chapter 2 discusses ways to control the program execution environment,
including creating subprocesses and detached processes and affecting
the allocation of physical memory.
Chapter 3 covers mechanisms for communicating between cooperating
processes, synchronizing their activities, and sharing data and code.
Chapter 4 discusses real-time I/O, including
connecting to a device interrupt vector.

mapping

I/O

space

and

Chapter 5 discusses the use of software facilities located in
multiport
(shared) memory -- specifically common event flag clusters,
mailboxes, and global sections.

vii

Chapter 6 explains privileged shareable images, a vehicle that
you, in effect, to write your own system services.
Chapter 7 provides sevfrral
accompanying explanations.

complete

proqramminq

allows

examples

with

The appendixes present supplementary information.
Appendix A shows
how to use a common event flag or a queue as a mutual exclusion
{mutex} semaphore to lock a resource.
Appendix
B
discusses
programming and design considerations for users of the Laboratory
Peripheral Accelerator (LPAll-K}. Appendix C provides a programming
example in VAX-11 BLISS-32. Appendix D is a checklist of optimization
techniques for real-time users.

ASSOCIATED DOCUMENTS

The following manuals explain the VAX/VMS
concepts
prerequisite knowledge for readers of this manual:
•

;:ire

that

The VAX/VMS §umn.:i9fl_____g~~-C::-~ i pt ion___ _ll_r]_cL__g__J.os~9.;:_y explains the
major components of the VAX/VMS system and defines significant
terms.

The VAX-11/780 Technical Summary (order number EA-159n3-20)
• de
r i bes--the ___maJo·r- -componerlfs and features of the VAX/VMS
SC

system.
The following manuals provide more detailed
concepts and features described in this manual:

treatment

major

•

The VAX/V~_§____ §y_~-~~-~---fvli!.!::19.~l:-~.5-___ Q_~J~t~ discusses the system
generation
(SYSGEN}
utility, the user authorization file
(UAF), system tuning, and the DISPLAY utility.

•

The VA?YY.1':1_§_ ~ystem $_e~v1. £e:_~_ Re~~r-~_r:i~e _Mcinual provides tutorial
chapters on many topics covered in-- TfiTs manual. It also
explains the format and requirements for each system service.

•

The VAX/VMS I/O User's Guide discusses I/O programming
detail, --rn-clud:i.ng ch·a-pte-rs --c;-11· several real-time devices.

•

The VAX/VMS Guide ~o Writinq ~_Devi~e Driver explains how to
write your owncrevic_e__ d-river_a.nCf___
detailed information
on VAX/VMS I/O.

Incfucfes-

The user's guide for each programming language provides information on
using VAX/VMS features and capabilities with that language.
The following handbooks provide information on VAX-11 architecture and
hardware:
•

The VAX-11 Architecture Handbook

{order

introduceS_____ vl\·x::1-1~·-sy-sTem·---~-a-rC-hi tecture,

number

EB-17580-18)

exp la ins addressing

modes, and presents the native-mode instruction set.
•

The VAX-11/780 Hardware Handbook
(order number EB-17835-18)
e xpla i n_s____ vAx--=r1 ha rd ware ---eTemen ts I inc ludi nq the high-speed
synchronous backplane
interconnect
(SBI),
the
central
processor unit,
intelligent console subsystem, MASSBUS and
UNIBUS subsystems, main memory, and memory management.
This
handbook also includes an appendix explaining restrictions on
program references to I/O space.

viii

CONVENTIONS USED IN THIS DOCUMENT

The system service formats and coding example conventions
are
consistent with those used in the VAX/VMS_§_y!?te~__ _§_ervices Reference
Manual:
Convention

Meaning

UPPERCASE

Uppercase letters in a system service format
material that must be entered as shown.

show

lowercase

Lowercase letters in a system service format
variable data.

show

[

Brackets in a system service
optional argument.

]

format

indicate

Horizontal ellipsis in a coding example indicates
that additional arguments necessary for the system
service call but not pertinent to the example are
not shown.
Vertical ellipsis in a coding example indicates
that lines of code not pertinent to the example
are not shown.

CHAPTER 1
INTRODUCTION

"Real-time" is a term whose meaning varies with specific applications.
However,
in most scientific,
industrial, and commercial real-time
applications, one or both of the followinq are critical needs:
•

High throughput

•

Fast response

Applications for which high throughput is essential require the
continuous processing of large amounts of data. An example of a
throughput-intensive application is signal processing, which is used
in
speech
research,
electrocardiogram and electroencephalogram
research, vibration analysis, and music synthesis.
As
another
example, a stream of data points is required for many of the
qualitative and quantitative methods used in
gas
and
liquid
chromatography,
mass
spectrometry,
automatic
titration,
and
colorometry.
In all of these throughput-intensive applications,
the
primary
requirement is to obtain some number of data points equally spaced in
time. Some further computation is done, perhaps later, on the data
collected.
In other real-time applications, fast response to individual events is
the most critical requirement. A typical example that requires fast
response is a closed-loop control system. In such a case, some event
must be identified as soon as possible; a decision is then made and
an output variable is updated. For example, before a jet engine is
tested, sensing instruments connected to a processor running a control
program might be placed on and near the engine. After the engine is
started, the control program must be able to detect, analyze, and
correct any abnormality within a few milliseconds -- for instance, by
shutting off the engine before an explosion occurs. Applications for
which response time is a critical factor include process monitoring
and control, synchronous communications, and stimulus-response testing
in biological and psychological research.
If response time is critical, the designer must ensure that the
application has all the resources it needs immeoiately whenever it
needs them. These resources include:
•

CPU time, the availability of which is affected
priority and, perhaps, interrupt latency

•

Memory, which can be controlled
(see Chapter 2)

•

I/O bandwidth,
configuration

which

1-1

several

determined

process

system

services

the

hardware

INTRODUCTION

These two real-time requirements, high throuqhput and responsiveness,
are sometimes interrelated.
For example, if your application must
collect large amounts of data quickly and if the data acquisition is
to be triggered by an external event, you need both fast response and
high throughput.
Specific real-time applications might involve the following
programming activities:

types

•

Controlling the program's execution environment, which might
require
communicating
between
programs
and
creating
subprocesses or detached processes

•

Using the Queue I/O Request system service
achieve faster response and gr~ater throughput

•

Coordinating programs
running
on
multiple
including the sharing of multiport memory units

directly,

processors,

Real-time users often employ sophisticated means to make the system
respond best to their special processinq needs. The VAX/VMS system
provides tools to meet these needs.

L 1

REAL-TIME NEEDS AND VAX/VMS FEATURES

From its inception, the VAX/VMS system has heen designed to meet the
real-time
processing
needs of a wide user base.
The VAX-11
architecture provides the necessary hardware foundation with its high
I/O
bandwidth,
interrupt · responsiveness,
32-bit
processinq
capabilities,
and
real-time
peripheral
interfaces.
These
architectural features are described in the hardware documentation for
your system (see the Preface). This manual will focus on software
features.
Its approach is to identify functions common to a variety
of real-time applications, discuss these functions conceptually, and
show how specific VAX/VMS features can be used to perform these
functions.
You are assumed to be familiar with basic VAX/VMS concepts, which are
defined in the '{_AX_{VM~ _____§~~~---p~_f3_9._:1'.:JPt:i()n _?Q_<:l_ __g~oS§.?_r:y. Do not,
however, confuse the VAX/VMS term "process" (the program image and the
software context in which it executes) with "process" in its generic
sense (a sequence of events), as in "industrial process-control
applications." Most instances of the word "process" in this manual
refer to the image and its context; any other use will be clearly
identified.
Table 1-1 summarizes common real-time needs and the features or
capabilities available with VAX/VMS to meet these needs. Each feature
listed is documented in the VAXjV~S__§_y~!_-~m_.§..E:_!'."_Y_Lc;:es__ B_~[~_r__e_n_9._~----~9.D~9.J_
unless another manual is specified. The goal of the present manual is
to organize and highlight aspects of special interest to real-time
users.

1-2

INTRODUCTION

Table 1-1
Real-Time Needs and VAX/VMS Features
Real-Time Need

VAX/VMS Feature

Perform an operation
with or after another
operation

Process
($CREPRC)
Use the
Create
service to create a subprocess or
detached process
Use the RUN command
to
create
a
subprocess or detached process (see the
VAX/VMS_Command L9-nquage User's Guide)

Change the availability
of a process for
scheduling

Use the Set Priority ($SETPRI) service

Keep critical code or
data highly accessible

Use the Adjust Working Set
($ADJWSL)
system service to adjust the amount of
physical memory a process is entitled to
use
Use the Lock Pages in Memory
($LCKPAG)
system service to keep paqes in physical
memory
Use the Lock Pages in Working
Set
($LKWSET)
system service to keep pages
in physical memory as long as
the
process is in memory
Use the Set Process Swap Mode
($SETSWM)
system service to keep all or part of a
process in physical memory
Use the Create and Map Section ($CRMPSC)
system
service to map a file into
process address space

Perform I/O quickly or
for special purposes

Use the Queue
system service

I/O

Request

($QIO)

Map I/O space
(usinq
the
$CRMPSC
service) and/or connect to a device
$QIO
(using
interrupt
vector
the
service)
Write your own device driver
(see the
VAX/VMS
GuJ__q~ ______ !:_C?_~ __ Wr it i ng __~___ pevi ce
Driver)
Synchronize a process
with an external event
or program

Set and wait for event flags
Code and declare asynchronous system
trap (AST} service routines
Connect to a device interrupt vector
Cause processes to hibernate or suspend,
and to awaken when needed
(continued on next page)

1-3

INTRODUCTION
Table 1-1 (Cont.}
Real-Time Needs and VAX/VMS Features
Real-Time Need

VAX/VMS Feature

Share code or data
between processes

Use the
Create
and Map
Section
($CRMPSC} system service to create and
map a global section
Use shareable images (see
Linker Reference Manual}

the

VAX-11

Send messages to other
processes

Use mailboxes ($CREMBX system service
creates mailbox; RMS or I/O system
services read and write messages}

Use multiport memory
(memory shared by
multiple processors}

Use common event flag clusters, global
sections, and mailboxes located in a
shared memory unit

Use special-purpose
system services

Write privileged
(see Chapter 6}

shareable

images

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

1.2

OTHER VAX/VMS TOOLS

There are other VAX/VMS tools which may be of interest to some
real-time users, but which are outside the scope of this manual.
Brief descriptions of these tools follow, with references to other
manuals for detailed information.

1.2.1

Condition Handling

A condition handler is a procedure that is given control when an
exception occurs.
An exception is an event that is detected by the
hardware or software and that interrupts the execution of an image.
Examples of exceptions include arithmetic overflow or underflow and
reserved opcode or operand faults.
If you want to handle any or all exceptions yourself, you must code
and declare a condition handler. Information on condition handling is
available in the VAX/VMS Syste~~_rvices Reference Manual, the VAX-11
Run-Time Library Reference Manual, and the language user's guides.

1.2.2

Device Allocation

You can allocate and deallocate devices from within your program with
the Allocate Device
(SALLOC) and Deallocate Device (SDALLOC) system
services. Allocating a device reserves it for exclusive use by the
requesting process.
The VA~/VMS System Services Reference Manual
explains the $ALLOC and $DALLOC system services.

1-4

INTRODUCTION
1.2.3

SYSGEN Parameter Selection

There are a number of parameters to the SYSGEN utility whose values
affect the paging, swapping, and scheduling operations of the system.
All of these parameters have default values that DIGITAL has selected
as suitable for a wide range of users; however, real-time users may
wish to modify certain parameters or experiment with different
combinations of parameters.
The VAX/VMS System Manager's g~ide
discusses major SYSGEN parameters and provides some guidelines for
selecting their values.
That manual also discusses a number of
parameters in relation to system tuning.

1.2.4

User Authorization File Entries

The user authorization file (SYSUAF.DAT) includes entries within each
record to determine the base priority (PRIORITY), initial working set
limit (WSDEFAULT), maximum working set limit (WSQUOTA), and privileges
for that user's processes.
The VAX/VMS System Manager's Guide
explains the user authorization file entries.

1.2.5

Networks

A VAX/VMS system can be connected in a communications network to other
DIGITAL processors with the same or different operating systems. The
family of software products supporting these networks is called
DECnet.
You can use DECnet to share files and communicate between
programs on different processors; however, for faster performance you
can use one of the real-time devices mentioned in Section 1.3. For
information on the use of DECnet, see the DECnet-VAX User's Guide and
the DECnet-VAX System Manager's Guide.

1.3

REAL-TIME DEVICES

The following
applications:

devices

are

especially

suited

for

•

Laboratory Peripheral Accelerator (LPAll-K)

•

Parallel Communications Link (PCL)

•

32-bit Parallel SBI Interface (DR780)

•

Synchronous Communications Line Interface (DMCll)

•

Multiport Memory (MA780)

real-time

This section discusses several of these devices only briefly.
For
detailed
information on using the MA780, see Chapter 5.
For
information on the other devices, see the VAX/VMS I/O User's Guide and
the appropriate hardware documentation.
The LPAll-K controls analog-to-digital
(A/D)
and digital-to-analog
(D/A)
converters, digital I/O registers, and real-time clocks.
Appendix B discusses programming and design considerations for LPAll-K
users.
The DR780 can be used to link user devices to a processor or
processors to each other. The DR780 provides a very high-speed 32-bit
wide interface to the VAX-11 Synchronous Backplane Interconnect (SBI).
1-5

INTRODUCTION
The DMCll and the MA780 are used primarily to link processors.
The
MA780 offers memory-access speed and greater capabilities, but the
DMCll is suited for data transmission between processors separated by
a great distance.
The DIGITAL Data Communications Message Protocol
(DDCMP) programmed into the DMCll's microprocessor ensures data
integrity.

1.4

USER PRIVILEGES FOR REAL-TIME APPLICATIONS

To protect the integrity of the system, VAX/VMS restricts certain
functions or operations to processes with the appropriate user
privileges. Each process starts with a set of privileges established
in one of the following ways:
•

For each user who logs in, privileges are designated by the
system manager in the user's entry in the user authorization
file.

•

For each created process, privileges are
specified
or
defaulted in the PRVADR argument to the Create Process
($CREPRC) system service or the /PRIVILEGES qualifier to the
RUN command.

You can change a process's privileges in two ways:
at the command
level with the SET PROCESS/PRIVILEGES command and at the program level
with the Set Privileges ($SETPRV) system service.
Most timesharing users need and are given only a limited set of
privileges. Real-time users, however, are normally given considerably
more privileges, because they need them to perform certain functions.
Any privileges required for functions discussed in this manual are
documented here or in the VAX/VMS System Serv_~£~~--~~_!erence_ Manual.
Some of the privileges of special interest to real-time users
follows:

are

Privilege

Meaning

ALTPRI

Set process base priority higher than user's own base
priority
Bypass all UIC-based protection checks
Change mode to executive
Change mode to kernel
Exceed certain quotas
Control processes in user's own group
Place entries in qroup logical name table
Perform logical I/O operations
Perform operator functions
Map to section by physical page frame number
Perform physical I/O
Create permanent common event flag clusters
Create permanent global sections
Create permanent mailboxes
Change process swap mode
Grant process privileges other than own
current
privileges
Perform certain functions in memory shared by multiple
processors
Place entries in system logical name table and create
system-wide qlobal sections
Access resources as if you have a system
user
identification code (UIC)
Control any process in the system

BYPASS
CMEXEC
CMKRNL
EX QUOTA
GROUP
GRPNAM
LOG IO
OPER
PFNMAP
PHY IO
PRMCEB
PRMGBL
PRMMBX
PSWAPM
SETPRV
SHMEM
SYSNAM
SYSPRV
WORLD

1-6

INTRODUCTION
The VAX/VMS System ...~~-!1-9.9_~r 's
privileges in greater detail.

1.4.1

Guide

explains

these

and

the

other

Privilege Masks

User privileges are stored in a quadword
(~4-bit)
mask,
in which
specific bits correspond to specific privileges. The operating system
actually maintains four separate privilege masks for each process:
•

AUTHPRIV - Privileges that the process is authorized to
enable, as designated by the system manager or the process
creator. The AUTHPRIV mask never changes during the life of
the process.

•

PROCPRIV - Privileges that are designated as permanently
enabled for the process. The PROCPRIV mask can be modified by
the Set Privileges
($SETPRV)
system service or the SET
PROCESS/ PRIVILEGES command.

•

IMAGPRIV - Privileges that
with.

•

CURPRIV - Privileges that are currently enabled. The CURPRIV
mask can be modified by the Set Privileges ($SETPRV) system
service or the SET PROCESS/PRIVILEGES command.

the

current

image

installed

When a process is created, its AUTHPRIV, PROCPRIV, and CURPRIV masks
have the same contents.
Whenever a system service must check the
process's privileges, it checks the CURPRIV mask. When a process runs
a known image, the privileges that the image was installed with are
enabled in the CURPRIV mask. Whenever an image exits,
the PROCPRIV
mask is copied to the CURPRIV mask.

1.5

PROCESS QUOTAS

To prevent a process from monopolizinq or overusinq certain resources,
VAX/VMS enforces a number of quotas (limits) on each process. These
quotas can be adjusted for each process. The system manager can set
quotas for each user in the user authorization file (UAF), and the
creator of a detached process or subprocess can specify quotas with
the QUOTA argument to the Create Process ($CREPRC) system service (see
Section 2.1.3) or with qualifiers to the RUN command
(see Section
2.1.4). Default values are used for any quotas not specified.
Each quota is deductible, pooled, or nondeductible:
•

A deductible quota value is subtracted from its creator's
current value when a subprocess is created and returned to the
creator when the subprocess is deleted.

•

A pooled quota is shared by a detached process ana all its
descendent subprocesses. Charges against a pooled quota value
are subtracted from the current available total as the
resource is used and are added back to the total when the
resource is not being used.

•

A nondeductible quota is established and maintained separately
for each detached process and subprocess.

The VAX/VMS System Services Reference Manual
information on process ·quotas:1-7

contains

detailed

INTRODUCTION

Table 1-2 lists each process quota, its function, the defaults used
for the user authorization file (UAF) and for process creation, and
the minimum value. The table also indicates whether the quota is
deductible, pooled, or nondeductible.
Table 1-2
Summary of Process Quotas
----

UAF
Process
Default Creation
Value
Default

Min.
Value

Quota

Functionl

AST queue
limit (ASTLM)

Limi ts the sum of AS Ts and
sche du led wake-up requests that
can be pending for a process at
one time (N)

Buffered I/O count
limit (BIOLM)

Limi ts the number of I/O operatio ns that the process can have
buff ered in system memory (N)

Buffered I/O byte
Limi ts the number of bytes that
count limit (BYTLM) the process can use for system
buff ered I/O operations (P)

409(.)

8192

1024

CPU time limit
(CPUTIME)

CPU time limit in mi 11 i seconds
(0 means no limit) (D)

Direct I/O count
limit (DIOLM)

Li mi ts the number of I/O op eratio ns that the process can have
buff ered in process address
spac e (N)

Open file limit
(FILLM)

Lirni ts the number of files thC'lt
the process Ci'ln hnve open at. one
time (P)

Paging file
quota (PGFLQUOTA)

Limi ts the number of pages that
the process can use in the system
pagi nq file (P)

10000

20Ll8

25f-\

Subprocess creation Limi ts the number of subprocesses
limit (PRCLM)
that the process can create (P)

Timer queue entry
limit (TQELM)

Default working set Sets the initial working set
size (WSDEFAULT)
size for the process (N)

150

100

Working set size
limit (WSQUOTA)

200

120

Limi ts the sum of timer queue
entr ies and temporary common
even t flag clusters that the
proc ess can have at one time (P)

Limi ts the size to which the
proc ess's working set size can
be e xpanded (N)
- -- ---- ""------------

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

- - - - - L . _______ --------J....__ ___________ ,_, ___

1. After each "Function" description is a letter in parentheses
indicating whether the quota is deductible
(D), pooled (P), or
nondeductible (N).

1-8

INTRODUCTION
Resource Wait Mode

1.5.l

By default, a process enters resource wait mode whenever it needs but
cannot obtain system dynamic memory or a resource controlled by any of
the following quotas:
•

Direct I/O limit (DIOLM)

•

Buffered I/O limit (BIOLM)

•

Buffered I/O byte count limit (BYTLM)

(If any other resource controlled by a quota is unavailable, the
process receives the SS$ EXQUOTA error status code.) Resource wait
mode places the process in
wait state until the resource becomes
available.

In a real-time environment, however,
it may not be practical or
desirable for a program to wait.
In these cases, you can choose to
disable resource wait mode for the process, so that when a required
resource is unavailable, control returns immediately to the calling
program with an error status code. You can disable resource wait mode
with the Set Resource Wait Mode (SSETRWM) system service.
How a program responds to the unavailability of a resource depends
very much on the application and the particular system service that is
being called. In some instances, the program may be able to continue
execution and retry the service call later. In other instances, it
may be necessary only to note that the program is beinq required to
wait.

l.n

PROCESS PRIORITY

At any given time, each process has a priority that affects how it
runs relative to other processes in the system. Process priorities
can range from 0 through 31, with O through 15 designated as
timesharing priorities and ln through 31 designated as real-time
priorities.
The "base priority" of a process refers to its minimum priority.
You
can adjust a process's base priority with the Set Priority system
service or the SET PROCESS/PRIORITY command.
The priority that
affects process operations is its current priority
(or simply,
priority), which the system dynamically adjusts for timesharing
processes.
The system handles timesharing and real-time priorities in different
ways.
For processes with timesharing base priorities (0 through 15),
the system dynamically adjusts the priority accordinq to the process's
state and other factors.
The actual priority of a timesharing process
at any given time might be as much as 7 higher than its base priority.
However,
the system will never raise a priority in the timesharing
range to a real-time level. Furthermore, the system does not alter
the priority of a process with a real-time base priority (lo through
31) •

1-9

INTRODUCTION
When you log in, your initial base priority is determined by a value
in your record in the user authorization file. When you create a
subprocess or detached process,
its initial base
priority
is
determined by the specified or default value for the BASPRI argument
to the Create Process ($CREPRC) system service or for the /PRIORITY
qualifier on the RUN command. To find out the base priority of your
process, you can use the SHOW PROCESS command.

1.6.l

Significance of Process Priority

The priority of a process can affect
•

How quickly it is scheduled
(that is,
process) after it becomes executable

becomes

the

current

•

Whether it will be interrupted by the
process

scheduling

another

•

Whether it will be swapped out of the balance set
system needs the physical memory for another process

•

How quickly its queued I/O requests are serviced by
driver

if
a

the

device

The VAX/VMS scheduler always selects the highest-priority process from
among those that are eligible to execute, that is, processes that are
"computable" (process state) and in the balance set.
(Conditions that
can cause a process not to be executable include waiting for an event
flag to be set or a resource to become available, or being in a state
of
hibernation or suspension.)
If a lower-priority process is
executing and a higher-priority process becomes executable, the
lower-priority process is interrupted and the higher-priority process
receives control of the processor.
If the working set requirements of all processes in the balance set
exceed the system's available physical memory, the VAX/VMS swapper
process is activated to "outswap" one or more processes: that is, to
save certain information and the working set of each process to be
swapped out and to free its memory pages for use by other processes.
A real-time process requiring fast response, however, should not be
swapped out.
In selecting a process for outswapping,
VAX/VMS
considers the process's state and quantum value in addition to its
priority. Therefore, if you must guarantee that a real-time process
will not be swapped out, disable swapping for the process with the Set
Process Swap Mode ($SETSWM) system service (see Section 2.2.4).
The VAX/VMS system also uses process priority as the basis for
ordering I/O requests queued to a driver.
That is, the system
initiates a queued I/O request issued by a higher-priority process
before it initiates one for the same device issued by a lower-priority
process.
Because the VAX/VMS operating system's own processes normally have
priorities of 16 or lower, real-time users must ensure that one of
these system processes is not blocked from execution if its operation
is needed by a real-time process. For example, if several real-time
processes are in the system, a priority-22 process performing disk
file I/O can be blocked by a compute-bound priority-17 process that is
preventing the disk ACP (which might be priority 11)
from executing.
If an operating system process needs to perform functions for a
real-time process, you might have to raise the priority of the
system's process.

1-10

INTRODUCTION
Adjusting the Base Priority

1.6.2

Raising process priority can decrease the time required for a program
to run to completion. Programs running in real-time processes have
more predictable execution times, because the process usually waits
only for the completion of requests that it initiates;
it does not
spend time wating for lower-priority processes to execute.
The higher the process's priority is set, the less likely it is the
process will have to wait.
However, you must use discretion in
raising priorities, because as you increase the number of real-time
processes
executing
concurrently, you potentially decrease the
effectiveness of each priority designation.
User privileges are required to set the priority of any process other
than your own or to raise the priority of any process (including your
own) higher than your own base priority.
The following
user
privileges enable you to perform the indicated functions:
•

The GROUP privilege allows you to change the priority of other
processes in your group.

•

The WORLD privilege allows you to change the priority
other processes in the system.

•

The ALTPRI privilege allows you to set the priority of any
process whose priority you have privilege to change (see GROUP
and WORLD privilege explanations) higher than your own base
priority.
If you do not have the ALTPRI privilege, you can
set the priority of any process whose priority you have
privilege to set only equal to or lower than your own base
priority.

any

There are two ways to change the base priority of a process:
•

At the command level with the command:
$ SET PROCESS/PRIORITY=n

•

At the program level with the Set
service

Priority

($SETPRI)

system

The Set Priority system service is probably more useful to real-time
programmers than the SET PROCESS/PRIORITY command, because the system
service enables you to set process base priorities dynamically
according to the program's logic.
This service has the following
general formats:
MACRO Format

$SETPRI [pidadr], [prcnam], pr i, [prvpr i]
High-Level Language Format

SYS$SETPRI ( [pidadr], [prcnam], pri, [prvpri])
The VAX/V~~---~~-1:-~.!!]_----~-~! v i_~_~_§_ ___R~J~_~..!!_g_~-- _r.1i!JJQ9 l
explanation of the Set Priority system service.

1-11

has

detailed

CHAPTER 2
CONTROLLING THE PROGRAM EXECUTION ENVIRONMENT

The VAX/VMS system gives you considerable control over the execution
context
of your applications, provided you have suitable user
privileges. Each application runs in the context of one or more
processes and can control that context in the following ways:
•

Create processes
(subprocesses or detached
divide the work into related segments

•

Set each process's
responsiveness

•

Control each process's use of physical memory

base

priority

processes)

achieve

real-time

You can use these features to ensure that all components of a
real-time application receive adequate processor time and physical
memory when they need them.
Process base priority is discussed in Section 1.6.
Process creation
and control of physical memory are discussed in this chapter.
The DISPLAY utility allows you to monitor system activity, and thus to
obtain information that can guide you in usinq features discussed in
this chapter.
The VAX/VMS System~··· Manag~r's Gui_de__ explains the
functions and operation of the DISPLAY utility.
The Get llob/Process Information ($GET.JP!) system service can also be
used to obtain information about one or more processes. The VAX/VMS
System Services Reference Manual explains the
Get
Job/Process
Information
system
service,
including the "wild card" process
searching capability.

2.1

PROCESS CREATION

Real-time applications are often divided into a number of programs.
Each program might run concurrently with one or more others, and each
might run conditionally (for example, only when certain events occur).
The VAX/VMS system allows you to create processes to run these
programs.
These created processes can be subprocesses or detached
processes, depending on your purpose and user privileges.
You can create either type of process with the Create Process
($CREPRC)
system service or with the RUN command, although real-time
applications frequently create subprocesses with the SCREPRC system
service and detached processes with the RUN command (often within a
command procedure at the start of the application).
Section 2.1.3
discusses the $CREPRC system service, and Section 2.1.4 discusses the
RUN (Process) command.
2-1

CONTROLLING THE PROGRAM EXECUTION ENVIRONMENT
2.1.1

Subprocesses and Detached Processes

Subprocesses and detached processes are treated the same by the
scheduling and swapping components of the operating system. For
example, each process of either type has a base priority that the
system uses in scheduling processes, allocating CPU time, and deciding
which process to swap out if necessary. Both types of process are
shown in the displays generated by the SHOW SYSTEM command and the
DISPLAY utility.
Subprocesses and detached processes differ, however, in their degree
of independence from their creator and in the privileges and quotas
required to use them. Table 2-1 summarizes the major differences
between a subprocess and a detached process.
Table 2-1
Subprocess versus Detached Process
-----------·------·----

Detached Process

Subprocess

resources

and

Shares creator's resources
and its deductible and
pooled quotas

Has
own
quotas

Must terminate before its
creator; automatically
terminated when its
creator is deleted

Termination is independent
of its creator's

No privilege required to
create a subprocess

DETACH privilege
to
create
a
process

Number of subprocesses
is limited by creator's
PRCLM quota

Number of detached processes is limited only by the
system's
maximum
total
process
count
(SYSGEN
parameter MAXPROCESSCNT)

Can access devices allocated
by its creator

Must allocate devices it
needs
to
reserve
for
exclusive use

required
detached

A process does not need GROUP privileqe to use system services or
commands that affect any subprocess it creates (for example, to change
the subprocess's priority).
A process does need GROUP or WORLD
privilege, however, to affect a detached process
(GROUP if the
detached process is in its group, otherwise WORLD).

2-2

CONTROLLING THE PROGRAM EXECUTION ENVIRONMENT
Real-Time Uses of Detached Processes and Subprocesses

2.1.2

Real-time applications often create detached processes to perform
highly privileged functions and subprocesses to perform functions
requiring little or no privilege.
Isolating privileged code as a
detached process makes it easier to debug and affords greater
protection for the system as a whole. Once it is created, a detached
process is more insulated than a subprocess from any errors its
creator may incur, because a detached process terminates independently
of its creator's termination, whereas a subprocess is automatically
deleted under the following conditions:
•

If the subprocess was created by a process that is using the
command interpreter
(for example, by the process created for
you at login time), the subprocess is deleted when its
creating process logs out.

•

If the subprocess was created by a process that is not using
the command interpreter (for example, by another subprocess or
a detached process executing a single image), that subprocess
is deleted when its creator is deleted.

A process can explicitly delete itself or, if it has suitable
privilege, another process by using the Delete Process ($DELPRC)
system service. The WORLD privilege allows you to delete any process
in the system;
the GROUP privilege allows you to delete other
processes in your own group.

Create Process System Service

2.1.3

The Create Process ($CREPRC) system service gives you program-level
control over the creation of subprocesses and detached processes. For
example, you might simply create a process at the beginning of the
program and control that created process's activity through the
hibernation or suspension mechanisms (see Chapter 3).
On the other
hand, you might need to test values within your program or wait for
some external event before creating another process.
In any case,
process creation is relatively ti~e consuming, and therefore should be
used prudently in real-time programs •.
The Create Process system service has the following general formats:
MACRO Format
$CREPRC [pidadr], [image], [input], [output], [error],
[prvadr], [quota], [prcnam], [baspri], [uic],
[mbxun t] , [s tsflg]
High-Level Language Format
SYS$CREPRC ( [pidadr], [image], [input], [output], [error],
[prvadr], [quota], [prcnam], [baspri], [uic],
[mbxunt], [stsflg])
The following arguments
real-time users:

•

$CREPRC

are

special

UIC - Determines whether the created process is a
(no UIC specified -- UIC same as creator) or
process (UIC specified).

2-3

interest

subprocess
a detached

CONTROLLING THE PROGRAM EXECUTION ENVIRONMENT
•

PRVADR - Allows you to specify privileges for the created
process.
To give the created process any privilege the
creator does not have, you must have the SETPRV privilege.

•

BASPRI - Allows you to specify a base priority for the created
process. To assign the created process a base priority higher
than the creator's own, you must have the ALTPRI privilege.

•

STSFLG - Allows you to specify various options for the created
process.

For a detailed explanation of the Create Process system
the VAX/Vf'1.§_§_y~_:t._~!fl Send ces Re~ere__nce ~-~!1~-~-~.

2.1.4

service,

see

RUN (Process) Command

The RUN command creates a subprocess or detached process to run a
specified program if you enter any of the process-related command
qualifiers (that is, any qualifier other than /DEBUG or /NODEBUG).
The general format for the RUN command to create a subprocess or
detached process is listed as follows:
$ RUN/command-qualifiers

program-file-spec

Each of the process-related command qualifiers is optional, although
you must enter at least one.
The presence of the /UIC command
qualifier determines whether the created process is a detached process
(qualifier specified) or a subprocess (qualifier not specified). The
process-related command qualifiers and their default values are listed
below.
Default (if applicable)

Qualifier
/[NO]ACCOUNTING
/AST LIMIT=quota
/[NOTAU+i'HORIZE
/BUFFER LIMIT=quota
/DELAY=delta time
/ERROR=file-spec
/FILE LIMIT=quota
/INPUT=file-spec
/INTERVAL=delta-time
/IO BUFFERED=quota
/IO-DIRECT=quota
/MAILBOX=unit
/MAXIMUM WORKING SET=quota
/OUTPUT=file-spec
/PRIORITY=n
/PRIVILEGES=privilege-list
/PROCESS NAME=process-name
/QUEUE LIMIT=quota
/[NO]RESOURCE WAIT
/SCHEDULE=absolute-time
/[NO]SERVICE FAILURE
/SUBPROCESS LIMIT=quota
/[NO]SWAPPING
/TIME LIMIT=limit
/UIC=uic
/WORKING_SET=default

/ACCOUNTING
10 (outstanding ASTs)
10240 (bytes)
20 (files)
~

(outstanding requests)
(outstanding requests)

200 (pages)
(same as creator)
(same as creator)
(null name)
8 (outstanding timer
/RESOURCE_WAIT
/NOSERVICE FAILURE
8 (subprocesses)
/SWAPPING
O (that is, no limit)
200 (pages)

2-4

que~e

requests)

CONTROLLING THE PROGRAM EXECUTION ENVIRONMENT
The /UIC, /PRIVILEGES, and /PRIORITY qualifiers serve the same
purposes as the UIC, PRVADR, and BASPRI arguments to the Create
Process system service (see Section 2.1.3).
The VAX/VMS Command Language User's Guide has a complete
of the RUN command and the process-related qualifiers.

explanation

You may want to include RUN commands for process creation in command
procedures.
The following example shows a command procedure that
prompts for information and then creates a subprocess.
$INQUIRE DEVICE "Device name"
!Specify input device
$INQUIRE TEST "Test name"
!Specify program to be run
$INQUIRE INTERVAL "How often should it be reported?
(O:mm:ss)"
$RUN/PROCESS NAME='TEST'/PRIORITY=l9/INPUT='DEVICE'/OUTPUT=OPA0:/INTERVAL='INTERVAL'
'TEST'

2.2

PHYSICAL MEMORY CONTROL

Physical memory is one of the ~ost valuable system resources to a
real-time user.
Programs execute faster when the code and data they
need at any given instant are already in memory and do not need to be
retrieved from disk storage.
In brief, VAX/VMS memory management operates in the following way.
The pages of a process that are currently in physical memory (usually
a subset of all the process's pages) constitute that process's working
set.
The maximum number of physical memory page frames a process can
occupy is determined by its current working set limit.
When the
number of page frames in use reaches the working set limit and the
process needs additional pages, the system pages the process against
itself.
That is, the system releases pages in the working set
(placing each one on the free page list or the modified page list) and
then reads the pages it needs from disk or finds them in memory (on
the free page list or the modified page list).
If and when the
working set requirements of all processes in the balance set (that is,
processes currently in memory) exceed the available physical memory,
one or more lower-priority processes are swapped out (temporarily
removed from the balance set) and their page frames are made available
for use by other processes. For more detailed information on VAX/VMS
memory management, see the VAX/VMS Summary Description apd Glossary or
the VAX-11/780 Technical Summa_I..Y.
For information on parameters to
the SYSGEN utility affecting memory management, see the VAX/VMS System
Manager's Guide.
Several system services allow you to control the operating system's
allocation of physical memory to the process. The following services
are most pertinent to real-time manipulation of physical memory:
•

Adjust Working Set Limit ($ADJWSL)

•

Lock Pages in Memory ($LCKPAG)

•

Lock Pages in Working Set {$LKWSET)

•

Set Process Swap Mode {$SETSWM)

The subsections that follow give brief descriptions and general
formats for these services. For more detailed information, see the
VAX/VMS System Services Reference Manual.

2-5

CONTROLLING THE PROGRAM EXECUTION ENVIRONMENT
2.2.1

Adjusting the Working Set Limit ($ADJWSL)

The Adjust Working Set Limit ($ADJWSL) system service allows you to
increase or decrease the maximum number of physical memory pages your
process can occupy. You can also use this system service to find your
current working set limit.
(You can change and find out your working
set limit at the command level with the SET WORKING SET and SHOW
WORKING SET commands.)
The VAX/VMS system normally performs automatic working set adjustment.
However, automatic working set adjustment is inhibited for all
processes if you specified WSINC=O to the SYSGEN utility, and
automatic working set adjustment is inhibited for a given process if
the process has a real-time priority (Hi through 31) or if the
process's working set default value is equal to its working set quota
(maximum) value.
The VAX/VMS System Manager's . Guide
explains
automatic working set adjustment a-nd the--SYSGEN parameters-that affect
its operation.
One of the simplest forms of memory management is to change the
working set limit at different points in your program. Large programs
usually proceed in phases;
for example, a program might perform a
heavily
I/0-bound
setup
phase,
then
settle
into localized
compute-bound processing, then do discontiguous array processing, and
so forth.
If your code has definable phases, you may want to call the
$ADJWSL system service at logical points to increase or decrease the
working set limit.
Another use of this system service is to prevent the excessive paging
activity that occurs when a program runs in too small a working set.
You should avoid excessive use of this system service, however,
because it incurs overhead for your process and perhaps for other
processes in the system.
No user privilege is required to use the $ADJWSL system service.
However, you cannot set a process's working set limit lower than the
system's minimum limit (determined by the SYSGEN parameter MINWSCNT)
or higher than the process's maximum working set size (determined by
its WSQUOTA entry in the UAF or specified when the process was
created).
The Adjust Working Set Limit system service has the following
formats:

general

MACRO Format

$ADJWSL [pagcnt], [wsetlm]
High-Level Language Format

SYS$ADJWSL([pagcnt], [wsetlm))

2.2.2

Keeping Pages in the Working Set ($LKWSET)

The Lock Pages in Working Set ($LKWSET) system service allows you to
specify that a page or range of pages should not be replaced in the
working set, perhaps because these pages are heavily used or because
the code in them must gain control and execute quickly whenever it is
needed. If the specified pages are not already in the working set,
they are brought into memory if necessary and locked in the working
set. Pages locked in the working set remain so until they are
unlocked by the Unlock Pages from Working Set
($ULWSET) system
service.
2-fi

CONTROLLING THE PROGRAM EXECUTION ENVIRONMENT
Pages locked in the working set can be removed from physical memory,
however,
if their process is swapped out (that is, if the process's
working set is removed from the balance set). To prevent this from
happening, use the Set Process Swap Mode ($SETSWM) system service to
disable swapping (see Section 2.2.4).
Locking pages in the working set is normally sufficient to guarantee
that their contents are accessible, especially if swapping is disabled
for the process. However, in a few cases you may need to lock the
pages in memory using the Lock Pages in Memory ($LCKPAG) system
service (see Section 2.2.3), to guarantee that the physical location
of the contents never changes. These cases include the following:
•

The process must lock pages for a routine that will execute at
an elevated interrupt priority level (IPL). Section 4.n.l
discusses interrupt priority levels.

•

The process is not using the VAX/VMS I/O system and must
pages for direct I/O operations.

lock

If you use the $LKWSET system service, be careful not to lock so many
pages that the remaining pages in the working set incur too many page
faults.
If excessive page faulting occurs, you may need to increase
the working set limit with the Adjust Working Set Limit ($ADJWSL)
service (see Section 2.2.1).
The Lock Pages in Working Set system service has the following general
formats:
MACRO Format
$LKWSET inadr, [retadr], [acmode]
High-Level Language Format
SYS$LKWSET(inadr, [retadr], [acmode])
The general format of the Unlock Pages from Working Set system service
is the same as the above, except that SULWSET or SYS$ULWSET is used
instead of $LKWSET or SYS$LKWSET.

2.2.3

Keeping Pages in Memory ($LCKPAG)

The Lock Pages in Memory ($LCKPAG) system service locks a virtual page
or range of virtual pages in physical memory.
If the specified
virtual pages are not already in memory, they are brought into the
working set and then locked in memory. Locked pages are not available
for page replacement until they are unlocked by the Unlock Pages from
Memory
($ULKPAG)
system service or until the program terminates
(locked pages are unlocked automatically at image exit).
You must
have the PSWAPM user privilege to lock pages in memory.
It is usually not necessary to lock pages in memory;
locking them in
the working set is often sufficient.
(Section 2.2.2 discusses cases
in which pages should be locked in memory.)
Use caution, however,
because locking any pages in memory reduces by that number the pages
that VAX/VMS memory management can allocate among other processes in
the system.

2-7

CONTROLLING THE PROGRAM EXECUTION ENVIRONMENT
Locked pages remain in memory even if their process is swapped out.
To prevent the process from being swapped out, use the Set Process
Swap Mode {$SETSWM) system service to disable swapping
(see Section
2.2.4).

The Lock Pages in Memory system
formats:

service

has

the

following

general

MACRO Format
$LCKPAG inadr, [retadr], [acmode]
High-Level Language Format
SYS$LCKPAG{inadr, [retadr], [acmode])
The general format of the Unlock Pages in Memory system service is the
same as the above, except that $ULKPAG or SYS$ULKPAG is used instead
of $LCKPAG or SYSSLCKPAG.

2.2.4

Keeping the Process in Memory ($SETSWM)

The Set Process Swap Mode ($SETSWN) system service enables you to
prevent your process from being swapped out of memory or to allow it
to be swapped out of memory. You must have the PSWAPM user privilege
to alter process swap mode.
An example of real-time use of setting process swap mode is a process
running an image that must respond quickly to some external event
(such as an interrupt), but has nothing to do until the event occurs.
After it is activated, the image can lock critical pages in its
working set (see Section 2.2.2), disable swapping for the process, and
hibernate.
(It is important to disable swapping, because being in a
hibernate state normally makes a process a good candidate for
outswapping.) When the event occurs, an AST service routine (see
Section 3.3) can awaken the process.
The Set Process Swap Mode system service
formats:

has

the

following

general

MACRO Format
$SETSWM [swpflg]
High-Level Language Format
SYS$SETSMW([swpflg])
The SWPFLG argument can be a value of
swapping) or 1 (to inhibit swapping).

2-8

(the

default,

allow

CHAPTER 3
COMMUNICATING AND SHARING BETWEEN PROCESSES

Real-time applications often consist of related programs running as
several processes. These processes may be detached processes, or they
may be a detached process with one or more subprocesses.
These
processes usually need to communicate with each other and to share
common code or data. Interprocess communication often consists of
event notification
(for example, that an I/O operation is complete),
although it can also involve transmission of messages or other data.
Processes within the application can synchronize their operations
through effective communication. Processes can also share code or
data to reduce the application's physical memory requirements.
Table 3-1 lists several VAX/VMS features that can be used to
communicate between user processes, synchronize their operations, or
share code and data.
Table 3-1
Features for Communication, Synchronization, and Sharing
Feature

Main Use

Common event flags

Notify process of
event
completion;
synchronize access to a resource

Mailboxes

Pass messages
processes

AST service routines

Execute desired routine in response to an
external event,
regardless of when the
event occurs

Hibernation and
suspension

Activate subprocesses and detached
cesses only when they are needed

Global sections

Share data or code

Shareable images

Share data or code

Each feature listed in Table 3-1 is
features.
For example, an AST
completion might write a message to
process or might set an event
waiting.

other

data

between

pro-

often used with one or more other
service routine executing at I/O
a mailbox to be read by another
flag for which another process is

3-1

COMMUNICATING AND SHARING BETWEEN PROCESSES
3.1

COMMON EVENT FLAGS

Common event flags provide a simple and convenient means for event
notificAtion.
Cooperating processes can set, clear, and wait for
flags in a common event flag cluster.
Common event flags can be used to synchronize access to a resource by
multiple processes. Appendix A discusses and illustrates the use of a
common event flag as a mutual exclusion (mutex) semaphore to lock a
resource.
Event flags are status-posting bits maintained by VAX/VMS for general
programming use.
Each process can manipulate up to 128 event flags,
numbered 0 through 127.
The event flags are qrouped into four
clusters of 32 flag bits each; however, whenever you set, clear, or
wait for an event flaq, you specify the flag number, not a cluster
number or name.
(The significance of the cluster name for common
event flag clusters is discussed later in this section.)
The first two clusters, flags O through 31 and 32 through n3, are
called local event flags because they are available only to a single
process. Two additional clusters, flags n4 through 95 and 9n through
127, are called common event flag clusters because they can be used by
cooperating processes. Table 3-2 summarizes local and common event
flag clusters.
Table 3-2
Summary of Event Flag Clusters
Event
Flag Numbers

Description

Restriction

0-23
32-63

Local event flag
clusters for
general use by
a process

Event flags 24
throuqh 31 are
reserved for
system use

64-95
96-127

Common event
flag clusters

Must be associated
before use

Common event flag clusters are either temporary
or
permanent
(depending on the PERM argument value in the Associate Common Event
Flag Cluster system service call).
Temporary common event flag clusters:
•

Do not require any special user privilege, but do use part
the calling process's timer queue entries (TQELM) quota.

•

Are deleted when all processes associated with the cluster
have disassociated from it.
A process can disassociate
explicitly using the Disassociate Common Event Flaq Cluster
($DACEFC) service, or it can disassociate implicitly at image
exit.

3-2

COMMUNICATING AND SHARING BETWEEN PROCESSES
Permanent common event flag clusters:
creating

process

have

the

PRMCEB

user

•

Require the
privilege.

•

Continue to exist until they are explicitly marked for
deletion with the Delete Common Event Flag Cluster ($DLCEFC)
service and no processes are associated with them.

This section will present general formats and focus on aspects
pertinent to real-time applications.
Chapter 5 discusses special
(multiport)
considerations for common event flag clusters in shared
memory.
The VAX/VMS System Services Reference Manual has a chapter
flag usage and detailed description of event flag services.

3.1.l

event

Creating and Associating with Clusters

To create or associate with a common event flag cluster, use the
Associate Common Event Flag Cluster ($ASCEFC) system service, which
has the following general formats:
MACRO Format
$ASCEFC efn, name,

[prot], [perm]

High-Level Language Format
SYS$ASCEFC(efn,name, (prot], [perm])
The first process specifying a given name creates the cluster and
associates
with it;
any other processes specifying this name
associate with the existing cluster. All processes associating with
the same common event flag cluster must specify the same name, but
they do not have to specify event flag numbers in the same 32-bit
grouping.
You can allow any other process in your group to associate
with the cluster (the default) or restrict association to processes
with your UIC
(by specifying a PROT argument value of 1). You can
make the cluster temporary (the default) or permanent (by specifying a
PERM argument value of 1).

3.1.2

Setting Event Flags

You can set event flags in a variety of ways.
The following system
services accept an optional EFN argument, which specifies an event
flag to be set when the operation is completed:
•

Queue I/O Request ($QIO and $QIOW forms,
macros)

Set Timer ($SETIMR)

•

Update Section File on Disk ($UPDSEC)

•

Get Job/Process Information ($GETJPI)

$INPUT

and

$OUTPUT

Note that each of the above system services clears the specified event
flag before it begins the requested operation.

3-3

COMMUNICATING AND SHARING BETWEEN PROCESSES
You can also set an event flag using the Set Event Flag
($SETEF)
system service.
To clear an event flag, use the Clear Event Flag
($CLREF) system service. Both the $SETEF and $CLREF system services
accept only one argument: EFN, a value indicating the flag to be set·
or cleared.

Waiting for Event Flags

3.1.3

If a process needs to be activated only in response to one
events, you can use one of the following system services to
process in a wait state until it must execute:

or
pl~ce

more
the

•

$WAITFR - The Wait for Single Event Flag system service places
the process in a wait state until a single specified event
flag has been set.

•

$WFLOR - The Wait for Logical OR of Event Flags system service
places the process in a wait state until any one of a
specified group of event flags has been set.

•

$WFLAND - The Wait for Logical AND of Event Flags system
service places the process in a wait state until all of a
specified group of event flags have been set.

During this wait state the process can still receive asynchronous
system trap
(AST)
interrupts, but after the AST service routine
completes, the process automatically reexecutes the "Wait for ••• "
service call.
After the flag or flags have been set and the process has responded to
the event(s), the process can reenter the wait state by looping back
to the appropriate system service call.

3.2

MAILBOXES

A mailbox is a record-oriented virtual I/O device that cooperating
processes can use to send messages, status information, return codes;
or other data to each other. A mailbox must be created using the
Create Mailbox and Assign Channel ($CREMBX) system service. Any other
process that needs to use the mailbox simply assiqns an I/O channel to
the mailbox using the $CREMBX system service or the Assign I/O Channel
($ASSIGN) system service. Actual data transfer (reading and writing)
involving the mailbox is accomplished by using I/O system services,
RMS, or high-level language I/O statements.
Mailboxes are suited to sending messages that cannot be conveyed by
the simpler and faster operations of setting and clearing event flags.
Mailboxes can hold multiple messages, which are read on a first-in
first-out
(FIFO) basis, whereas with an event flag you cannot
determine from a flag's current status how many times it has been set
or cleared.
Some overhead is involved, however, with the use of
mailboxes. Therefore, to pass and read messages faster you can use a
global section (see Section 3.5) to hold the messages and common event
flags to notify processes that messages are ready to be read.

3-4

COMMUNICATING AND SHARING BETWEEN PROCESSES
A special use of a mailbox is as a process termination mailbox, which
receives a process termination message for the creating process when a
subprocess or detached process is deleted.
Process termination
mailboxes are discussed in the VAX/VMS System Services Reference
Manual.
Mailboxes are either temporary or permanent.
two types.

Table 3-3 contrasts

the

Table 3-3
Temporary versus Permanent Mailboxes
Temporary

Permanent

TMPMBX user privilege
required to create

PRMMBX
user
privilege
required to create

Creating process's buffered
I/O byte count (BYTLM)
quota is reduced (see
Section 3.2.1)

No process quotas affected

Logical name entered in
group logical name table

Logical name entered in
system logical name tnble

Automatically deleted when
no more channels are
assigned to it

Must be explicitly marked
for
deletion
with the
Delete Mailbox
($DELMBX)
service

Chapter 5 discusses mailboxes in shared
(multiport) memory.
The
chapter on the mailbox driver in the VAX/VMS I/O Us~!._~E._~G_uid~ contains
information on the use of mailboxes and a programming example.

3.2.1

Creating a Mailbox

The Create Mailbox and Assign Channel system service creates a mailbox
or,
if the specified mailbox already exists, assigns a channel to it.
This service has the following general formats:
MACRO Format
$CREMBX [prmflg], ch an, [maxmsg], [bufquo], [promsk],
[acmode], [ lognam l
High-Level Language Format
SYS$CREMBX( [prmflg] ,chan, [maxmsg], [bufquo], [promskl,
[acmode] , [ lognam])
The PRMFLG argument determines whether the mailbox is temporary
(the
default) or permanent (value of 1). If the mailbox is temporary, the
process's buffered I/O byte count (BYTLM) quota is reduced by the sum
of the following until the mailbox is deleted:
•

The number of bytes of system dynamic memory that can be
to buffer messages sent to the mailbox

•

The size of the mailbox unit control block
3-5

used

COMMUNICATING AND SHARING BETWEEN PROCESSES
The PROMSK argument allows you to restrict access to the mailbox by
setting specific bits in a protection mask. This mask contains four
4-bit fields:
15

ERLD

JGR~UP IOW~E~~TEM I

The bits are read from right to left in each field and indicate, when
they are set, that read, write, execute, and delete acce~s (in that
order) are denied to the particular category of user. Only read and
write access, however, are meaningful for mailbox protection. The
default setting of 0 (all bits cleared) indicates that all user~ have
read and write access to the mailbox.
The ACMODE argument allows a process executing at a more privileged
access mode to associate a less privileged access mode with the
channel assigned to the mailbox.
(Kernel mode is the highest;
user
mode is the lowest.) The access modes and their corresponding values
are listed below. The symbolic names for the values are defined by
the $PSLDEF macro.
Access Mode

Value

Symbolic Name

Kernel

PSL$C KERNEL

Executive

PSL$C EXEC

Supervisor

PSL$C SUPER

User

PSL$C USER

Any ACMODE value you specify is maximized with your current access
mode;
that is, the channel is associated with the less privileged of
the specified mode and your current mode.
The LOGNAM argument allows you to specify the logical name associated
with the mailbox.
Processes using a mailbox must specify the same
logical name to identify that mailbox. When the mailbox is created,
the logical name is entered in the group logical name table if the
mailbox is temporary and in the system logical name table if the
mailbox is permanent.

3.2.2

Other Mailbox Services

To use an existing mailbox, your process must assign it an I/O channel
using the Create Mailbox system service or the Assign I/O Channel
system service.
(A high-level language program, however, need only
issue an OPEN statement specifying the logical name of the mailbox.)
The Assign I/O Channel system service has the following general
formats:
MACRO Format

$ASSIGN devnam,chan, [acmode), [mbxnam]
High-Level Language Format

SYS $ASSIGN ( devnam, ch an, [a cmode] , [mbxnam))
3-6

COMMUNICATING AND SHARING BETWEEN PROCESSES
The DEVNAM argument must specify the mailbox logical name. The ACMODE
argument has the same meaning as in the Create Mailbox service. The
VAX{yMe__~-~IJl_ _§_e.__r._yl_c:_~§___B.ef ~renc_~_ Manual
describes the Assign I/O
Channel system service in detail.
To delete a permanent mailbox, you must mark it for deletion using the
Delete Mailbox ($DELMBX)
system service.
Actual deletion occurs,
however, when all processes have deassigned the
I/O
channels
connecting them to the mailbox or closed the file in a high-level
language program. To deassign the I/O channel, use the Deassign I/O
Channel ($DASSGN) system service.

3.2.3

Example Using a Mailbox

Figure 3-1 is a simple illustration of cooperating processes
mailbox.

using

PROGRAM MASTERPROC
INTEGER*4 SYS$CREMBX,SYS$CREPRC,STATUS,CHAN

c-- Create a mailbox and call it

BOX'

STATUS= SYS$CREMBX(,CHAN,,,,, 'MAILBOX')
IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

C-- Create a subprocess running program 'SUBPROC' and assign its input to be
C-- the mailbox and its output to be our terminal

STATUS= SYS$CREPRC(,'SUBPROC' ,'MAILBOX' ,'TTDh:' ,,,,,%VAL(2) ,,,)
IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))

C-- Send the subprocess a message

(in this case the number 12345)

OPEN(UNIT=l,NAME='MAILBOX',STATUS='NEW')
WRITE(l,*) 12345
END
PROGRAM SUBPROC

c-- Read the message from the mailbox and,

0
10

ACCEPT *,MESSAGE
TYPE 10,MESSAGE
FORMAT(' The message was:
END

Figure 3-1

in this case,

just display it

',IS)

Using a Mailbox to Communicate

Notes on Figure 3-1:

0
8

One process creates a mailbox.

The creating process writes a message to the mailbox.

The subprocess reads the message.

The process creates a subprocess.

3-7

COMMUNICATING AND SHARING BETWEEN PROCESSES
3.3

ASYNCHRONOUS SYSTEM TRAP SERVICE ROUTINES

An asynchronous system trap (AST) is a software-simulated interrupt
used for event notification within a process. An AST service routine
is a user-written routine that receives control when an AST is
"delivered" after being queued to the process. The AST is delivered
to the process (that is, interrupts the process execution flow)
as
soon as no higher-priority process is executable, unless specific
conditions temporarily prevent it from being delivered
(see Section
3.3.2).
When the AST service routine completes, the current image
continues executing from the point at which it was interrupted.
ASTs
are thus a mechanism to allow asynchronous operations.

System Services with AST Service Routine Arguments

3.3.1

Several system services allow you to specify an AST service routine to
be executed when the requested operation is completed. The call to
the service initiates the request, and an AST is queued to the process
when the request is completed. These services are as follows:
•

Queue I/O Request ($QIO)

•

Update Section File on Disk ($UPDSEC)

•

Get Job/Process Information ($GETJPI)

The Set Timer (SSETIMR) system service allows you to specify
(1)
an
absolute or delta time for an AST to be queued to the process, and (2)
the address of an AST service routine.
The Set Power Recovery AST
($SETPRA)
system service specifies the
address of an AST service routine to receive control after a power
recovery is detected.
The Declare AST ($DCLAST) system service allows a process to queue An
AST for itself at the same or a less privileged access mode and to
specify an AST service routine. This service is particularly useful
for testing an AST service routine and for initiating actions that
must be performed in an AST service routine.
The VAX/VMS System Services Reference Manual contains a chapter on AST
services, including. a aTscussTon on-wr1Trng-an AST service routine.

3.3.2

Access Modes and AST Delivery

ASTs are queued for a process by access mode.
An AST for a more
privileged access mode always takes precedence over one for a less
privileged access mode;
that is, an AST will interrupt any AST
service routine executing at a less privileged mode. Normally, AST
service routines that you specify execute at user access mode;
however, the process can receive ASTs from more privileged access
modes (for example, a kernel-mode AST at I/O completion).
Figure 3-2 shows a program interrupted by a user-mode AST, and
user-mode AST service routine interrupted by a kernel-mode AST.

3-8

the

COMMUNICATING AND SHARING BETWEEN PROCESSES

Program

j
'~: '-~

User-mode
AST

AST service
routine

-----i
Kerr;:~;ode AS~:~~::~:~~:tine
',,
!~~-=-------!

......

.......... ..........

'-...' '-

Legend:

Execution
flow

Return

...._ -

Return

Transfer of
control
--~

Figure 3-2

Access Modes and AST Delivery

An AST cannot be delivered to a process, however,
following conditions are true:

3.4

while

any

the

•

An AST service routine is currently executing at the same or a
more privileged access mode.

•

The current image is executing at a more privileged
mode than the mode for which the AST is declared.

•

You have explicitly disabled AST delivery using
Enable ($SETAST) system service.

•

The process is suspended (see Section 3.4).

the

access
Set

AST

HIBERNATION AND SUSPENSION

Hibernation and suspension are two synchronization mechanisms that
allow a process to control when it or another process becomes active.
Hibernation and suspension both temporarily halt the execution of a
process;
however, there are differences in how the mechanisms
operate. Table 3-4 contrasts hibernation and suspension.

3-9

COMMUNICATING AND SHARING BETWEEN PROCESSES
Table 3-4
Hibernation versus Suspension

------ · · - - - - - - · - - - - - Hibernation

Suspension

Process can cause only
itself to hibernate

Process
itself
process,
privilege

Interruptible; ASTs can
be delivered to the process

Not interruptible; ASTs
can be queued but not
delivered

Reversed by $WAKE system
service

Reversed
by
system service

Process can wake itself or
be awakened by another process

Process
cannot
cause
itself
to
resume;
another
process
must
cause resumption

Process can schedule wakeup at
absolute time or fixed time
interval ($SCHDWK service)

Process cannot
resumption

Hibernate/wake complete
quickly and require
little system overhead

$SUSPEND service
uses
system
dynamic memory;
resumption takes longer

The next two subsections provide
common uses of hibernate/wake:

coding

examples

•

Activating a process as needed

•

Activating a process at fixed intervals

can
suspend
or
another
depending
on

$RESUME

schedule

illustrating

two

Note that in both examples the process to be awakened is identified by
process identification number rather than by process name. Either
method is acceptable;
however, when a process is identified by
process identification number, the system service executes slightly
faster, because it does not have to search the process name table.

3.4.l

Example 1: Wakeups as Needed

PROCESSl creates PROCESS2 as a subprocess or detached process, but
wants the created process to run only when certain events occur or
certain conditions are true. Therefore, PROCESSl sets bit 5 in the
STSFLG argument to the Create Process system service call, causing
PROCESS2 to hibernate immediately after it is created.
PROCESS2 is
activated only when PROCESSl so requests, and PROCESS2 returns to
hibernation immediately after it
does
whatever
the
specific
application requires
(for example, writinq information to a mailbox
used by both processes).

3-10

COMMUNICATING AND SHARING BETWEEN PROCESSES
PROCESS 1

Wakes PROCESS2 whenever necessary

PROCESS2 ID:
PROCESS2-NAME:

.BLKL
.ASCID

$CREPRC S

l
;RECEIVE ID OF CREATED PROCESS
/PROCESS2/ ;NAME OF CREATED PROCESS

PIDADR=PROCESS2_ID,;CREATE PROCESS2
PCRNAM=PROCESS2 NAME,;SPECIFY NAME
STSFLG=#ABlOOOO~;PROCESS2 STARTS IN HIBERNATION
; (OTHER ARGUMENTS, AS NEEDED)

BSBW

ERROR

$WAKE S

P IDADR=PROCESS 2 ID
; WAKE PROCP.SS 2
ERROR
;BRANCH TO ERROR-CHECKING ROUTINE

BSB~

;BRANCH TO ERROR-CHECKING ROUTINE

$WAKE S PIDADR=PROCESS2 ID ;WAKE PROCESS2
BSBW
ERROR
;BRANCH TO ERROR-CHECKING ROUTINE

PROCESS2

Awakens, performs functions, then goes back to sleep
.ENTRY

START,O

;IMAGE ENTRY POINT & MASK
; (PERFORM FUNCTIONS)

RET

3.4.2

;BACK TO HIBERNATION

Example 2: Wakeups at Fixed Intervals

PROCESSl, a process with a priority in the timesharinq range, creates
PROCESS2 as a subprocess or detached process with a real-time base
priority.
PROCESS2 will run only at a fixed interval,
in this case
every hour, although its priority helps to ensure that when it does
run it will run without interruption.
PROCESS2 hibernates immediately after it is created.
PROCESSl used
the Schedule Wakeup ($SCHDWK) system service to schedule a wakeup for
PROCESS2 in one hour
(DAYTIM argument)
and every hour thereafter
(REPTIM argument). Wh~n PROCESS2 is activated, it performs its tasks
and returns to a state of hibernation.

3-11

COMMUNICATING AND SHARING BETWEEN PROCESSES
PROCESS!

Process with timesharing priority

PROCESS2 ID:
.BLKL
1
;RECEIVE ID OF CREATED PROCESS
PROCESS2-NAME:
.ASCID /PROCESS2/ ;NAME OF CREATED PROCESS
AlHOUR: :ASCID /0 01:00:00.00/ ;ONE HOUR (DELTA TIME) IN ASCII
BlHOUR: .BLKQ 1
;QUADWORD TO HOLD BINARY TIME VALUE

$CREPRC S

PIDADR=PROCESS2 ID, ••• ;CREATE PROCESS2
,PCRNAM:PROCESS2 NAME,BASPRI=#l7, ••• ;REAL-TIME PRIORITY
BSBW
ERROR
;BRANCH TO ERROR-CHECKING ROUTINE
$BINTIM S TIMBUF=AlHOUR,;CONVERT TIME TO BINARY
TIMADR=BlHOUR
BSBW
ERROR
;BRANCH TO ERROR-CHECKING ROUTINE
$SCHDWK S PIDADR=PROCESS2 ID,- ;SCHEDULE WAKEUP FOR PROCESS2
DAYTIM=BlHOUR,-IN ONE HOUR,
REPTIM=BlHOUR
AND EVERY HOUR THEREAFTER
BSBW
ERROR
;BRANCH TO ERROR-CHECKING ROUTINE
; (CONTINUE PROGRAM EXECUTION)

PROCESS2

SLEEP:

High priority real-time process

.ENTRY START,O
$HIBER S
ERROR
BSBW

;IMAGE ENTRY POINT & MASK
;SLEEP TILL NEX~ SCHEDULED ~~KEUP
;BRANCH TO ERROR-CHECKING ROUTINE
; (PERFORM HIGH-PRIORITY TASKS)

BRW

SLEEP

;BACK TO SLEEP (FOR ONE HOUR)

A specific application of this example might involve a routine that
needs to run periodically to gather and process status information.
The routine might run for only a very short time, for example, a few
seconds every hour.
To prevent the routine from beinq interrupted,
you can assign its process a real-time base priority and use any of
the other methods discussed in Chapter 2.

3.5

GLOBAL SECTIONS

A global section is an area of memory containing data or code that can
be shared by cooperating processes.
One process "creates" the
section;
subsequent processes establish their right to use the
section by "mapping" to it. The data or code in the section can be
from a disk file (disk file section) or in physical memory or I/O
space
(page frame section).
This section discusses disk file
sections. Physical page frame sections are treated in Chapter 4 in
the discussion of connecting to an interrupt vector.

3-12

COMMUNICATING AND SHARING BETWEEN PROCESSES
In many real-time applications, such as data acquisition or industrial
process-control, response time is so critical that control variables
and data readings must remain in memory. Frequently, many different
processes must use this data simultaneously. Global sections provide
a convenient mechanism for fast access to the data and for the rapid
passing of data from one process to another.
Global sections can be temporary or permanent. Temporary sections are
deleted when no processes are mapped to them, but permanent sections
must first be explicitly marked for deletion with the Delete Global
Section
($DGBLSC} system service.
Most global sections that you
create from within your programs should be temporary, so that the
system resources associated with the section can be freed as soon as
they are no longer needed. Temporary global sections in real-time
applications usually contain data rather than code. Permanent global
sections, on the other hand~
usually contain routines common to
several programs.
In fact, most of the permanent global sections in
the system are shareable images installed by the system manager as
known images.
(Shareable images are discussed in Section 3.n. The
INSTALL utility is explained in the VAX/VMS_ Syste~~_.91}_9_9er_'s Guide.}
VAX-11 Record Management Services (VAX-11 RMS}, with its file-sharing
capabilities, provides an alternative to global sections in some cases
as a mechanism for sharing disk file data.
Each method has its
advantages;
however, global sections provide the faster access that
many real-time applications require. Table 3-5 shows the trade-offs
involved in choosing between a global section and VAX-11 RMS for
sharing disk file data.
Table 3-5
Global Sections versus VAX-11 RMS
Global Sections

VAX-11 RMS
----------------~---------!

Faster access to data

Access to data slowed
file-system overhead

More programming effort
required; user must define
and keep track of service
arguments and other data

Programming simplified by
VAX-11 RMS or high-level
language
macros;
most
internal
operations
and
data structures transparent
to the user

Greater burden on the
user to protect data
and synchronize access

Automatic file protection
and
synchronization
of
access, based on parameters
supplied by user

Especially suited for
small files

Especially suited for large
files

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

Chapter 5 discusses qlobal sections in shared (multiport) memory.

3-13

COMMUNICATING AND SHARING BETWEEN PROCESSES
3.5.1

Creating and Mapping a Global Section

The Create and Map Section ($CRMPSC) system service creates a section
or maps to an existing section. The VAX/VMS _§_y§__t~~--S~rvJces Reference
Man_ua.} has a detailed description of this service and a lengthy
discussion of sections in general. The present manual gives only the
general format for calling the service and discusses a few arguments
especially significant to real-time users.
The Create and Map Section system service has
formats:

the

following

general

MACRO Format
$CRMPSC

[inadr]; [retadr], [acmode], [flags], [qsdnaml, [ident]
, [relpag], [chan], [pagcnt], [vbnJ, [prot], [pfc]

High-Level Language Format
SYS$CRMPSC ( [inadr], [retadr], [acmode], [flags], [gsdnam), [ident]
, [relpag], [chan], [pagcnt], [vbn], [prot], [pfc])
The FLAGS argument specifies a mask defining the section type and
characteristics.
This mask is the logical OR of the flag bits you
want to set.
(The $SECDEF macro defines the symbolic names for the
flag bits in the mask.) To specify a global section, you must set the
SEC$M GBL flag bit. You can set additional flag bits as needed.
The
flag -bit meanings and the default values they override are listed
below.
Flag

Meaning

Default Attribute

SEC$M GBL

Global section

Private section

SEC$M CRF

Pages are copy-on-reference

Pages are shared

SEC$M DZRO

Pages are demand-zero pages

Pages are not zeroed
when copied

SEC$M EXPREG

Map into first available
space

Map into range specified by INADR argument

SEC$M WRT

Read/write section

Read-only section

SEC$M PERM

Permanent

Temporary

SEC$M PFNMAP

Physical page frame section

Disk file section

SEC$M SYSGBL

System global section

Group global section

The PROT argument specifies a numeric value
representing
the
protection mask to be applied to the section. To deny read or write
access to the section to one or more types of user, you must specify
the appropriate protection mask. If you do not specify this arqument,
all users have read and write access to the section.

1-14

COMMUNICATING AND SHARING BETWEEN PROCESSES
The protection mask has four 4-bit fields:

15
WORLD

GROUPENE~~~ST~

Bits are read from right to left in each field and indicate, when they
are set, that read, write, execute, and delete access (in that order)
are denied for that particular category of user.
However,
the
following considerations apply to any protection mask you specify:

•

section
Only read and write access are meaningful for
protection. Denying execute or delete access has no effect.

•

For group global sections the "World" field has no effect,
because only members of the creator's group are permitted to
map to the section. The "World" field does apply, however, to
system global sections.

For example, to allow the owner of a group global section to read and
write to the section but allow other members of the group only to read
the section (that is, to deny them write access), specify a protection
mask of 0200 (hexadecimal).

Other Section-Related System Services

3.5.2

The following system services are often used with global sections:

3.6

Section

($MGBLSC).

Maps

existing

global

•

Map Global
section.

•

Update Section File on Disk ($UPDSEC).
Writes the modified
pages of a section back to the disk file. This system service
is especially useful for periodically updating a data base
that is being modified by multiple processes.

•

Delete Virtual Address Space
($DEL'l'VA).
"Unmaps" a global
section by deleting the process's virtual addresses into which
the section was mapped.

•

Delete Global Section ($DGBLSC). Marks a global section for
deletion. Actual deletion occurs when no processes are mapped
to the section.

SHAREABLE IMAGES

Shareable images can be used to share frequently used code or data
among multiple processes.
A shareable image might contain routines
that are common to several programs.
If a shareable image is
installed in the system as a permanent global section (as is normally
the case), other programs can share its contents by linking with it.
The benefits of using shareable images include reductions in disk
storage space, physical memory use, and system paqing activity.
The
VAX-11 Linker Reference Manual explains the benefits and uses of
shareable images in detail.
-

3-15

COMMUNICATING AND SHARING BETWEEN PROCESSES
In the airline reservation example in Chapter 7, the reservation
base is a shareable image.
To use a shareable image effectively, you must create
image and then permit other programs to use it.

the

data

shareable

To create a shareable image, you must perform the following steps:
1.

Code the program containing the routine or data to be shared.
Design this program to meet the needs of all other programs
that will be using it (that is, all programs that will be
linked to the shareable image).
Follow the programming
conventions discussed in the chapter on shareable images in
the VAX-11 Linker Reference
..
- - - Manual.
-----------~--,··--···

'", ,~·~-·

Assemble or compile the program containina the shareable code
or data. For example:
$ MACRO SHCODE
This command generates the object module SHCODE.OBJ in your
default directory
(assume that this is DBl: [SMITH] for this
and the remaining steps).

Link the object module to produce a shareable image,
the /SHAREABLE command qualifier. For example:

using

$ LINK/SHAREABLE SHCODE
This command generates the shareable image SHCODE.EXE in your
default directory.
To permit other programs to use the shareable image, you must
the following steps:
1.

perform

Create a linker options file.
Identify the shareable image
to be used with the /SHAREABLE file qualifier. For example,
create a file named A.OPT containing the following line:
DBl: [SMITH]SHCODE/SHAREABLE

Link each program that will use the shareable
image,
identifying the linker options file with the /OPTIONS file
qualifier. For example:
$LINK PROGRAMl,A/OPTIONS
This command generates an executable image named
that is linked with the shareable image SHCODE.

PROGRAMl

To permit multiple processes to use the same copy of the shareable
image, install it as a known image, using the INSTALL utility.
(The
VAX/VMS System Manager's Guide explains the INSTALL utility.)
It is
recommencre<r -"th-atyou ____copy the shareable image file to the directory
identified by the logical name SYS$SHARE (which by default is [SYSLIB]
on the system disk), and then run INSTALL:
$ RUN SYS$SYSTEM:INSTALL
INSTALL>SYS$SHARE:SHCODE/OPEN/SHARED
The example above designates the shareable image as a permanent global
section, that is, a permanently open section potentially available to
all users of the system.

1-10

COMMUNICATING AND SHARING BETWEEN PROCESSES

Note that the VAX/VMS image activator assumes that shareable images
linked with the executable image being run are located in SYS$SHARE.
To have the image activator look for a shareable image in a different
location, define the shareable image file name as a logical name with
the file specification as the equivalence name before running the
executable image. For example:
$ DEFINE SHCODE DBl: [SMITH]SHCODE

3-17

CHAPTER 4
PERFORMING I/O OPERATIONS

A real-time VAX/VMS process can use the VAX/VMS I/O system to perform
I/O
operations, or it can bypass most of the I/O system by
manipulating device registers and responding to device interrupts
directly.
Before you can optimize I/O operations for a real-time
application, however, you must understand the components that form the
VAX/VMS I/O system and how they interact.

4.1

OVERVIEW OF THE VAX/VMS I/O SYSTEM

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

The Queue I/O Request system service

•

Device drivers

•

Ancillary control processes (ACPs)

•

The I/O posting routine

The following
components.

4.1.1

subsections

describe

the

main

functions

these

Queue I/O Request System Service

Every I/O request issued by a process under VAX/VMS results directly
or indirectly in the invocation of the Queue I/O Request system
service. For example, both a FORTRAN READ statement and a VAX-11 RMS
$GET request from a VAX-11 MACRO program cause the Queue I/O Request
system service to be called.
You can call the Queue I/O Request system service specifying one of
three types of function code: physical, logical, or virtual. The
service validates the device-independent portions of the I/O request.
The device driver or ancillary control process (ACP) performs any
necessary validation of the device-dependent portions of the I/O
request.
The VAX/VMS I/O User's Guide lists the valid function codes for each
device driver or ACP and provides guidelines for choosing among
function codes when alternatives are available.

4-1

PERFORMING I/O OPERATIONS
Ancillary Control Processes

4.1.2

An ancillary control process (ACP) is a VAX/VMS process that performs
I/O-related functions associated with file structures and protocol,
rather than functions related to the actual transfer of data. VAX/VMS
supplies at least five ACPs:
•

Two or more ACPs for Files-11 structured disk devices

•

One ACP for ANSI magnetic tapes

•

NETACP for network functions

•

REMACP for remote terminal I/O functions

The use of ACPs is normally transparent to your programs. VAX-11 RMS
issues the necessary Queue I/O Request system services for virtual
functions on your behalf. You can, however, issue Queue I/O Request
system service calls directly for Files-11 disk and magnetic tape ACPs
to request such functions as the following:
•

File creation

•

File access

•

Reading and writing of virtual blocks

•

File deletion

The VAX/":{MS
processes.

__ User 's

~l_Q

Guide

describes

the

use

ACPs

user

When a user process or VAX-11 RMS issues a Queue I/O Request system
service for an ACP function,
the Queue I/O Request system service
passes the request to the appropriate ACP.
The ACP processes the
request
(if necessary), converts the function from virtual to logical
(if necessary), and queues the request to the appropriate device
driver.
The driver performs the transfer, as described in Section
4.1.3.

Device Drivers

4.1.3

Device drivers are responsible for taking the information that the
Queue I/O Request system service provides about an I/O request and
performing the I/O operation. To accomplish these tasks, a driver
contains the following main routines:
•

Device activation routine

•

Interrupt service routine

•

I/0 completion routine

Drivers also contain other routines to handle request validation and
such contingencies as power failure and device timeout, as described
in the VAX[~~~_q_u._!_9_~ __t:<? Writ i n_g___ a____pe'{!_<::_~~rAv~!:.

4-2

PERFORMING I/O OPERATIONS
The device activation routine obtains the device controller resources
needed to perform the transfer
(for example, the controller data
channel), sets up device registers in I/O space, and initiates the
transfer.
Once the transfer is initiated, the device activation
routine issues a wait request that temporarily suspends the device
driver.
When the transfer is complete, the device requests an interrupt and
the system activates the driver's interrupt service routine to handle
the interrupt.
(Section 4.6 discusses interrupt handling.)
In
addition to handling the interrupt, the interrupt service routine may
program the device for another transfer or may activate the I/0
completion routine in the driver to perform device-dependent I/0
completion. The driver's I/O completion routine,
in turn, passes
control to the VAX/VMS I/O posting routine.

4.1.4

I/O Posting Routine

Once the device driver has finished the device-dependent portions of
it calls the I/O posting routine.
I/O posting
the I/O request,
consists of completing the device-independent portions of the I/0
request, setting a designated event flag (flag 0 by default), and
queuing a kernel mode AST for the process that initiated the I/0
request.
The next time the system schedules this process for execution, the
kernel mode AST routine executes.
This routine completes the I/O
request by performing the following functions:
•

If requested, writes the status of
user-specified I/O status block.

the

I/O

request

into

•

If requested, queues an AST at the access mode of the Queue
I/O request for the process to execute a user-specified
routine.

•

For read requests that were buffered in system space, copies
the data from system space into the user's buffer. Device
drivers determine whether the data is read directly into the
user buffer
(direct I/O) or buffered first in system space
(buffered I/O).

The driver's I/O posting routine has a lower priority than the
driver's start I/O routine. Therefore, if a new I/O request is queued
for the device before the existing I/O request is completed, the new
I/O is started. This method of operation keeps the device as busy as
possible.

4.2

USER INTERFACE TO THE I/O SYSTEM

The design of the VAX/VMS I/O system allows user-written
interface with the system at a number of levels:

programs

•

VAX-11 Common Run-Time Procedure Library routines

•

VAX-11 Record Management Services (VAX-11 RMS)

•

Queue I/O Request system service for a device or ACP function

•

Connecting to a device interrupt vector

4-3

PERFORMING I/O OPERATIONS
In addition, users can write device drivers to support devices not
supported by VAX/VMS and incorporate those devices into the system.
Programs written in VAX-11 MACRO can interface with the I/O system by
using VAX-11 RMS, by using the Queue I/O Request system service, or by
mapping to I/O space and connecting to a device interrupt vector.
Programs written in a high-level language can interface with the I/O
system using the same methods as a VAX-11 MACRO program, or they can
issue the I/O statements specific to that language. In the latter
case, the program interfaces with the I/O system by means of the
VAX-11 Common Run-Time Procedure Library.
The following steps occur when a high-level lnngunqe program, in
case VAX-11 FORTRAN, issues a read request under VAX/VMS:

this

•

When the program executes, the read statement results in a
call to the Run-Time Library read procedure to initiate the
read operation. To initiate the read, the procedure issues a
VAX-11 RMS $GET request.

•

VAX-11 RMS gains control and, in turn, issues the
Queue I/O Request system service.

•

The Queue I/O Request system service processes the request (as
described in Section 4.1.l) and queues it to the driver or
ACP.

•

Once the driver activates the device and completes
operation, it calls the VAX/VMS I/O posting routine.

•

The
VAX/VMS
I/O
posting
routine
then
performs
device-independent I/O completion, returns status to the user
program, and, if requested, queues an AST or sets an event
flag.

appropriate

the

I/O

A user program can interface with the I/O system at one of several
levels, depending on its requirements.
At each level, the user
program makes trade offs between ease of use and execution speed.
As
a general rule, the closer to the VAX/VMS executive that a user
program interfaces, the less overhead is involved in the
I/O
operation.
This manual focuses on the following lower levels of
interface: the Queue I/O Request system service, the Create and Map
Section system service, and the connect-to-interrupt capability.

4.2.l

VAX-11 RMS Features of Interest to Real-Time Users

VAX-11 Record Management Services has several features that may permit
certain applications to take advantage of VAX-11 RMS and still meet
their throughput and response requirements.
Listed
below
are
descriptions
of these features,
with the VAX-11 RMS mechanism
associated with each feature. Complete descriptions of the features
and mechanisms are given in the VAX-11 Record Management Services
Reference Manual.

4-4

PERFORMING I/O OPERATIONS
Mechanism

Feature

$FAB ALQ=quantity

Preallocation of enough blocks to hold the
entire
file.
Avoids
time-consuming
file
extensions and ACP window turns;
prevents
discontiguous file extensions.

$FAB FAC=BIO

Block I/O (for $PUT operations).
because no RMS buffer is used.

$FAB FOP=CTG

Contiguous files.
Faster access, especially for
random access and/or files with many segments.

$RAB MBF=buff ers

Multibuffering.

$RAB ROP=RAH
$RAB ROP=WBH

Read-ahead and write-behind. Improve throughput
(done by default by certain high-level language
compilers).

$RAB MBC=blocks

Multiblock I/O. Reduces number of disk accesses
for record operations.

4.3

Faster

I/O

Improves throughput.

USING THE QUEUE I/O REQUEST SYSTEM SERVICE

The Queue I/O Request ($QIO) system service gives programmers in any
supported language a low-level, flexible interface with the VAX/VMS
I/O system. You must first assign an I/O channel to the device using
the Assign I/O Channel
($ASSIGN) system service. Your call to the
Queue I/O Request system service must specify this channel and a
function code identifying the operation to be performed. The optional
arguments to the Queue I/O Request service allow you to do the
following:
•

Perform asynchronous ($QIO form) or synchronous
I/O

($QIOW

•

Set an event flag at I/O completion (EFN arqument)

•

Receive the final completion status (IOSB argument)

form)

an AST service routine
(ASTADR argument)
to be
• Specify
executed when the I/O completes and pass a parameter (ASTPRM
argument) to that routine
•

Specify function-specific or device-specific
P2, etc.)

parameters

(Pl,

There are two forms of this service: Queue I/O Request
($QIO)
and
Queue I/O Request and Wait for Event Flag ($QIOW). The $QIO form
returns control to the program immediately after queuing the I/O
request and without waiting for the I/O to be completed;
this form
allows your program to perform asynchronous I/O. The SQIOW form waits
until the I/O is completed before returning control to your program.
(The $INPUT and $OUTPUT macros are special forms of $QIOW.)

4-5

PERFORMING I/O OPERATIONS
The Queue
formats:

I/O

Request

system

service

has

the

following

general

MACRO Format
$QIO[W]

[efn] ,chan,func, [iosb], [astadr], [astprm],
[pl] I [p2] I [p3] I [p4] I [p5] I (p~l

High-Level Language Format
SYS$QIO[W] ( [efn] ,chan,func, [iosb], [astadr], [astprm),
[plJ, [p2J, [p3J, [p4J, [pSJ, [pnJ)
The VAX/VMS System Services Reference Manual has additional general
informatic)"i1·---on this sysEem service and some examples of its use. The
VAX/VMS I/O User's Guide has specific information and examples of this
system- ser-vTc-e--Ior-ea-ch-of the device drivers it discusses.

4.4

INTERRUPT-GENERATED I/O

A process with suitable privileges can connect to a device interrupt
vector and/or map the processor's I/O space into process virtual
address space. Connecting to a device interrupt vector allows your
process to respond to interrupts from the device with minimal
overhead. Mapping processor I/O space allows your process to access
device registers from the main program or from an AST service routine.
A process normally uses these features for devices that do not have
VAX/VMS drivers. These devices must not be direct memory access (DMA}
devices, and they must be attached to the UNIBUS.
Examples of such
devices are the ADll-K the DRll-B, and the KWll-P.
You can use the Queue I/O Request
($QIO)
system service with an
appropriate function code to connect to a device interrupt vector and
to specify a user-supplied routine, called an interrupt service
routine
(!SR), that VAX/VMS executes when the designated device
interrupts. Connecting to a device interrupt vector allows you to do
the following:
•

Respond to an interrupt within a very short time

•

Preempt other system processing to handle a
for example, a clock interrupt

•

Buffer data from a device in real time and return the data
the process at a later time

•

Set an event flag or queue
receiving the interrupt

AST

real-time

your

process

event,
to

after

The effect of user-written interrupt service routines is to allow you
to perform some of the functions normally done by a device driver, but
without requiring that you write a full device driver and without
requiring that the routine be loaded into the VAX/VMS operating system
(device drivers are part of VAX/VMS).

4-n

PERFORMING I/O OPERATIONS
If you must access device registers from user mode {that is, from the
main program or a user-mode AST service routine), you must use the
Create and Map Section {$CRMPSC) system service to map I/O space,
specifying page
frame
number
(PFN) mapping.
The service creates a
global or private section that maps the specified I/O pages into your
process's virtual address space.
The process can then gain access to
I/O space using virtual addresses.
You do not need to map I/O space to access device registers
from any
of
the following routines specified in the $QIO call connecting to an
interrupt vector:
device initialization routine, start I/O
routine,
interrupt service routine,
and cancel I/O routine.
These routines
execute in system space and thus can access UNIBUS I/O space, which is
mapped as part of system space.
The sections that follow explain how to map the VAX-11 processor's I/O
space and how to connect to a device interrupt vector.

4.5

MAPPING I/O SPACE

On a VAX-11/780 processor, I/O space
is assigned physical address
locations of
20000000
(hexadecimal) and higher.
I/O space contains
device registers that a driver or user process can read and write to
control
a
device.
Each device controller has an associated
control/status register in I/O space.
Device registers
for
each
device are
located at an offset
from the device's control/status
register {CSR).
The $I0780DEF macro defines
the
layout of VAX-11/780 I/O space:

following

symbols

describing

Symbol

Meaning

Hexadecimal
value

I0780$AL IOBASE
I0780$AL-UBOSP

Start of I/O space
Start of address space for
first UNIBUS

20000000
20100000

the

These symbols are contained in SYS$LIBRARY:LIB.MLB.
The number of
registers and their
locations vary for
different
devices.
The PDP-11 Peripherals Handbook provides the necessary
information for devices supplied by DIGITAL.
The VAX-11/780 Hardware
Handbook contains information about the layout of I/O space.
On a VAX-11 processor, the address of a physical memory
the format illustrated in Figure 4-1.

t_ _ !
30

page frame number

Figure 4-1

location

has

I
I

918
I
I

byte

Physical Address

The page frame number (bits 9 through 29) specifies the number of a
physical page
in memory.
Bit
29
is clear to indicate a physical
memory address and set to indicate an address in I/O space.
Bits 0
through 8 specify the byte address within the page.

4-7

PERFORMING I/O OPERATIONS

For a process to gain access to I/O space or to any page of physical
memory, it must map that page into its virtual address space. When
your VAX/VMS process maps a page by specifying its page frame number,
it completely bypasses VAX/VMS memory management and creates its own
window to the page.
As a result, the protection functions that
VAX/VMS normally performs are not performed for mapping by page frame
number:
•

No checks are performed to ensure that no other
processes are mapped to the page and modifying it.

VAX/VMS

•

No reference count is maintained.
A process can delete a
global section mapped by page frame numbers when other
processes are still using it;
this is not the case when
VAX/VMS performs the mapping.

Modifying pages mapped by page frame numbers can have unpredictable
results and can adversely affect system operation, especially if the
operating system is also using these pages.
Because
of
the
unprotected nature of mapping by page frame numbers, you must have the
PFNMAP user privilege to use this capability.

4.5.1

Page Frame Number (PFN) Mapping

When used for mapping by page frame number, the Create and Map Section
system service designates the specified page(s) as a global or private
section and maps the section into the requesting process's virtual
address space.
The pages can be located anywhere in the VAX-11
processor's local memory, or in MA780 memory (if a multiport memory
unit is connected to the system), or in I/O space.
The format and conventions for mapping by page frame number (that is,
mapping a physical page frame section) are similar to those for
mapping a disk file section.
The Create and Map Section system
service has the following general formats:
MACRO Format

$CRMPSC

[inadr] , [retadr] , [acmode) , [flags] , [gsdnamJ , [ident]
, [relpag] , [chan] , [pagcnt] , [vbn] , [prot] , [pfc]

High-Level Language Format

SYS $ CRM PS C ( [ i n ad r ] , [ r e tad r J , [a c mode J , [ fl a g s ] , [ g s d n am ] , [ i den t J
, [relpag] , [chan] , [pagcnt] , [vbn] , [prot] , [pfc])
The RELPAG, CHAN, and PFC arguments are not applicable in mapping by
page frame number. The INADR, RETADR, ACMODE, GSDNAM, !DENT, and PROT
arguments have the same functions regardless of whether you specify
page frame number mapping;
these arguments are described in the
VAXlYM~--~_y st em~Ev i c e~__f3_~f i: re n c e -~~£l~a 1 •
The following arguments are affected by PFN mapping:
flags
Mask defining the section type and characteristics. This mask is
the logical OR of the flag bits you want to set. The $SECDEF
macro defines symbolic names for the flag bits in the mask.

4-8

PERFORMING I/O OPERATIONS

The SEC$M PFNMAP flag bit must be set to indicate mapping by page
frame numner. The SEC$M PFNMAP flag setting identifies the memory
for the section as startTng at the page frame number specified in
the VBN argument and extending for the number of pages specified
in the PAGCNT argument.
If appropriate, the following flags can also be set:
Flag

Meaning

Default

SEC$ GBL
SEC$M WRT
SEC$M-PERM
SEC$M-SYSGBL
SEC$M-EXPREG

Global section
Read/write section
Permanent section
System global section
Expand the process's
virtual address space
as needed to contain
the section.

Private section
Read-only section
Temporary section
Group global section
Map into range
specified by
INADR argument

Neither the SEC$M CRF
(copy-on-reference) nor the SECSM DZRO
(demand-zero) bit can be set when mapping by page frame number.
The VAX/VMS 8-_~~-~m s.er_yL~.~-?.--~~ef e__renc~-- Manual provides
information about the use of the flag settings.

add it iona 1

pagcnt
Number of pages in the section;
not be zero.

the value of this

argument

must

vbn
Page frame number of the first page to be mapped
(as opposed to
this argument's normal usage identifying the starting virtual
block number within a disk file). When you are mapping more than
one page with a single Create and Map Section system service
request, the pages are physically contiguous starting with the
specified page.
Notes

An error in mapping UNIBUS I/O space or a reference to a
nonexistent UNIBUS address causes a UNIBUS adaptor error.
However, this error does not cause a system failure.
Rather,
an entry is made in the system error log file and the user
program continues executing (probably with erroneous results).
The process is not notified of the UNIBUS adapter error.

If a power failure occurs on the UNIBUS, the system continues
to run. However, if a user process accesses UNIBUS I/O space
from user mode during a UNIBUS power failure,
the process
receives a machine check exception. To handle this condition,
the process must have a condition handler to deal with machine
check exceptions.
The VAX/VMS System Services Reference
Man u a 1 di s cusses con di t ion hand fe_r_s-Tn___ (J"eTaTf-: _H________________ ·-

During recovery from a UNIBUS adaptor power failure,
the
processor spends a considerable amount of time (perhaps 10 to
60 milliseconds) at interrupt priority level (IPL)
31.
This
action
blocks user processes from executing during the
recovery.

4-9

PERFORMING I/O OPERATIONS
Programming Conventions for Addressing Device .Registers

4. 5. 2

Once you have mapped to I/O space, you can read data from a device data
buffer
register
or
enable interrupts by setting a bit in a
control/status register, because the device
registers
are
now
addressable as part of your process's virtual memory. The UNIBUS
adapter performs the actual mapping of VAX-11 virtual addresses to
18-bit UNIBUS addresses that correspond to device registers.
Because UNIBUS devices are one word (lo bits) long, all instructions
referring to these registers must be word-context instructions (for
example, BISW, MOVW, and ADDW3), unless the register is
byte
addressable.
Instructions referring to byte-addressable registers
should be byte-context instructions, such as BISB and MOVB. Unaligned
references and references using a length attribute other than the
length of the register may produce unpredictable results;
for
example, a byte reference to a word-addressable register does not
necessarily respond by supplying or modifying the byte ad~ressed.
A
longword reference to a UNIBUS location causes a machine check.
Instructions that use a UNIBUS device register as a source operand
must not be ihterruptible instructions. In some cases when a device
register is being copied, interrupting and restarting an instruction
may cause a character to be lost. To guarantee a noninterruptible
sequence, use only the instructions listed in Appendix C of the
VAX-11/780 Hardware Handbook, and do not use autoincrement deferred
addressTng ·;n·0ae or_a_n_yOfthe displacement deferred addressing modes.
You should always store the address of a device control register in a
general register and then gain access to the device indirectly through
the general register.
The example below defines symbolic word offsets for each device
register and gains access to them using displacement mode addressing
from R4.
Device register offsets
CSR offset
Buff er address off set

0
2

MOVL

CSR_VA,R4

Get CSR address

TSTW

LP_CSR(R4)

; Is printer online?

The following restrictions
device registers:

also

apply

instructions

addressing

•

Operand types of floating, double, field, queue, or quadword
are not allowed, nor can the position, size, length, or base
of an operand be from I/O space.
For example, a field
instruction cannot be used to test a bit in a device register.

•

You cannot have more than one modify or write destination, and
this modify or write destination must be the last operand.

•

Instructions referring to I/O space must not cause
an
exception
after
the
first I/O space reference.
This
restriction includes deferred references to I/O space.

4-10

PERFORMING I/O OPERATIONS

4.6

CONNECTING TO AN INTERRUPT VECTOR

On a VAX-11 processor, peripheral devices have interrupt vectors
associated with them.
When a device interrupt occurs, the action
taken by the processor depends on the interrupt priority level
(IPL)
associated with the device.
Connecting to an interrupt vector differs from the standard method of
programming a peripheral device. Programming a peripheral device is
normally a 3-step loop:
1.

The device driver starts the device
from the device.

and

enables

The device generates an interrupt.

The device driver fields the interrupt, collects
data, and clears the interrupt condition.

interrupts

status

and

Under the VAX/VMS operating system, a user program normally requests
I/O by means of a Queue I/O Request ($QIO) system service call. A
device driver, executing as part of the operating system, controls and
responds to the device.
The driver returns status and data to the
requesting user process.
However, real-time application programmers can connect to an interrupt
vector to control and respond to a device without writing a full VMS
device driver, and without issuing $QIO calls for each device
interaction. Instead, you issue a connect-to-interrupt $QIO call that
specifies code to be executed to control the device, and a data area
that the program and the device control code can share.
You
subsequently control and respond to the device without additional SQIO
calls.
The timings involved in different system activities
connecting to an interrupt vector are as follows:

4.6.1

associated

with

•

The time between when the device generates an interrupt and
when the process's interrupt service routine receives control
depends upon the IPL of the processor at the time of the
interrupt. If the processor is executing at an IPL below that
of the device (as is the usual case), the interrupt service
routine gains control within a few microseconds. However, if
the processor is executing at an IPL above that of the device,
the interrupt service routine does not gain control until the
executing code lowers the IPL below the device IPL.
(Section
4.6.1 discusses IPLs.)

•

The time from the user interrupt service routine's exit to the
execution of the AST routine specified in the $QIO call
depends on the priority of the process and whether a context
switch is required.

Interrupt Priority Levels

VAX-11 processors define 32 hardware interrupt priority levels. These
interrupt priority levels establish the order in which peripheral
devices, error condition reporting, and various components of VAX/VMS
gain access to the processor;
that is, interrupt priority levels are
a synchronization mechanism.
(Interrupt priority is not related to

4-11

PERFORMING I/O OPERATIONS
process priority, which is
VAX-11 processors assign the
follows:

•
•

discussed
interrupt

User mode programs run at IPL O;

in Section l.n.) VAX/VMS and
priority levels
(IPLs) as
this is the lowest IPL •

VAX/VMS routines and
device
driver
processes
request
interrupts at IPLs 1 throuqh 15.
(Device drivers execute as
fork processes under VAX/VMS, as described in the VAX/V~~
~l:1_!_9_~-- to Writin_g a Devi.Ce Driv_~r.)

•

Peripheral devices generate interrupts at IPLs ln through 19.
UNIBUS peripherals generate interrupts of IPLs 20 through 23
(corresponding to UNIBUS BR levels 4 through 7).

•

Processor error conditions and the
interrupts at IPLs 20 through 31.

system

clock

generate

Because of the way in which priority levels are assigned, device
interrupts almost always receive immediate service from the processor
and VAX/VMS.
A VAX-11 processor always executes the code associated with the
highest IPL for which an interrupt has been requested. For example,
if the processor is executing a driver process and a device requests
an interrupt, the processor stops executing the driver, saves the
driver's context for subsequent reactivation, and activates the
interrupt service routine for the interrupting device. When that
interrupt service routine terminates, VAX/VMS activates the code
associated with the next lower IPL for which an interrupt has been
requested. The routine activated can be either of the following:
execution

but

was

•

A routine that had already started
interrupted by a higher level interrupt

•

A routine for which an interrupt has been pending while the
processor executed at a higher IPL but which had not been
executed previously

Performing the Connect-To-Interrupt

4.6.2

Connecting to a device interrupt vector allows your program to receive
notification
of an interrupt from a designated device by any
combination of the following means:
•

By execution of a user-supplied interrupt service routine

•

By the setting of an event flag

•

By execution of an AST routine that
process context

qain

control

In addition, you can specify a cancel routine that is to be executed
when the process disconnects from the interrupt vector or is deleted.
Before your program can run, the system manager
following at system generation time:
e

must

have

done

the

Specify the REALTIME SPTS parameter to the SYSGEN utility,
reserving system paqe table entries for use by real-time
processes. These system page table entries are use~ to map
process-specified buffers in system space (see the Pl argument

4-12

PERFORMING I/O OPERATIONS
description in Section 4.6.5).
The REALTIME SPTS parameter
value must be greater than or equal to the number of pages in
buffers specified by processes connected to interrupt vectors.
•

Configure the real-time device by issuing a CONNECT command to
the SYSGEN utility.
This command names the device;
its
vector, register, and adapter addresses;
and a skeletal
driver (CONINTERR) for the device.

The CONNECT command to the SYSGEN utility is explained in the
System Manager's Gu~de.

VAX/V~J?:

At run time the process calls the $ASSIGN system service to associate
a channel with the device.
The process can also map the page in
UNIBUS I/O space containing the device registers
(see Section 4.5).
To connect to the device interrupt vector, the process issues a $QIO
call specifying the IO$ CONINTREAD or IO$ CONINTWRITE function code
and as many of the following as are appropriate:
•

An interrupt service routine to be executed
generates an interrupt

when

the

device

•

A buffer containing code to be executed in system context
and/or data
(This buffer must be contiguous in the process's
address space.)

•

An AST service routine to execute and/or an event flag to be
set after the interrupt service routine (if any) completes (If
an AST service routine is specified, an AST parameter may also
be specified.)

•

A device initialization routine

•

A start I/O routine

•

A cancel I/O routine

A nonprivileged process (that is, lacking the CMKRNL privileqe) can
also connect to an interrupt vector, but it can only specify an AST
service routine to be executed or an event flag to be set
(or both)
when an interrupt is generated.
Section 4.n.5 explains the SQIO
format for connecting to an interrupt vector.

The Connect-To-Interrupt Driver

4.6.3

The VAX/VMS connect-to-interrupt driver (CONINTERR) provides a driver
interface to the system on behalf of the process. CONINTERR connects
the process to the device by executing the following steps:
1.

Validates the $QIO system service parameters, such as the
process's access to the specified buffer, and the number of
the optional event flag.

Locks the physical pages of the buffer into physical memory,
and maps the pages using system page table entries allocated
by the REALTIME_SPTS parameter to the SYSGEN utility.

Constructs argument lists and calling interfaces to the
process-specified routines by storing values in the device's
unit control block (UCB).

4-13

PERFORMING I/O OPERATIONS
4.

Allocates the specified number of AST control blocks to the
process, and inserts each block in a queue in the device's
UCB.

Transfers control to VAX/VMS to queue the connect
interrupt I/O packet to CONINTERR start I/O routine.

When the CONINTERR start I/O routine gains control, it passes control,
by
means of a user-specified JSB or CALLS interface, to the
process-specified start-device
routine.
This
routine
usually
initializes the device and may also start activity on the device.
When the device generates an interrupt, the interrupt service routine
in CONINTERR gains control.
This routine transfers control to the
process-supplied interrupt service routine.

The Interrupt and AST Service Routines

4.6.4

The interrupt service routine that you specify, like those supplied by
VAX/VMS, has the following characteristics:
•

It is mapped in system space.

•

It executes on the interrupt stack.

•

It executes at the
interrupt.

IPL

the

device

that

requested

the

Because of these characteristics, the interrupt service routine
executes as part of the VAX/VMS operating system rather than in the
context of your user process. As part of the operating system, the
interrupt service routine has access to system data bases not
available to user processes. However, because an interrupt service
routine has these capabilities and executes at a raised IPL, you must
code it carefully to avoid disrupting the system.
Section 4.n.9
discusses conventions for process-specified interrupt service routine.
The interrupt service routine that you specify usually performs one or
more of the following steps:
1.

Copies data from a device register

Writes to a device register to clear the interrupt condition

Restarts the device, or returns an offset, a byte
actual data as an AST parameter

Returns
an
interrupt
status
to
connect-to-interrupt driver (CONINTERR)

the

count,

VAX/VMS

Depending on the interrupt status, the CONINTERR interrupt service
routine queues a fork process to run 0t a lower IPL. Then the
interrupt service routine exits from the interrupt with an REI
instruction. When the CONINTERR fork process gains control, it queues
an AST or posts an event flag to the process (or both).
The AST service routine that you specify gains control in process
context.
This routine usually performs one or more of the followinq
steps:
1.

Reads or writes device registers if the
space (see Section 4.5).

4-14

process

mapped

I/O

PERFORMING I/O OPERATIONS
2.

Interprets data.
Use
caution,
however,
because
any
processing done by the AST service routine can be interrupted
by a device interrupt, which might store more data or modify
the buffer's contents.

Calls the Cancel I/O on Channel ($CANCEL) system
disconnect the process from the interrupt.

4.6.5

service

Queue I/O Request System Service for Connect-To-Interrupt

The format of the Queue I/O Request ($QIO) system service to connect
to an interrupt vector is given below. The explanation is limited to
connecting to an interrupt vector. For a detailed description of the
$QIO system service, see the VAX/VMS Syst~~ Service_~. ~~ference_~_~nu~l •
MACRO Format
$QIO [efn] , [chan] ,func , [iosb] , [astadr] , [astprm]
,[pl] ,[p2] ,[p3] ,[p4] ,[p5] ,[p6]
High-Level Language Format
SYS$QIO( [efn]

, [chan] ,func , [iosb] , [astadr] , [astprm]
,[pll ,[p2] ,[p3] ,[p4] ,[p5] ,[phl)

efn
iosb
astadr
astprm
These arguments apply to the $QIO system service completion, not
to device interrupt actions.
For an explanation of these
arguments, see the $QIO service description in the VAX/VMS System
Services Reference Manual.
f unc
Function code of IO$ CONINTREAD
or
IO$ CONINTWRITE.
The
IO$ CONINTWRITE function code allows locations in the buffer
pointed to by the Pl argument to be modified; the IOS CONINTREAD
function code makes the buffer contents read-only.
pl
Address of a descriptor for the buffer containing code and/or
data.
The first longword records the number of bytes in the
buffer;
the second longword records the address of the buffer.
(Note: The buffer size must not exceed 64K bytes.)
p2
Address of an entry point list.
The list consists of four
longwords that contain offsets into the buffer (specified in the
Pl argument) of entry points of process-specified routines.
These longwords and their contents are as follows:
CIN$L INIDEV
CIN$L-START
CIN$L-ISR
CIN$L-CANCEL

Offset
Offset
Offset
Offset

to
to
to
to

device initialization routine
start device routine
interrupt service routine
cancel I/O routine

Note: Symbols starting with CIN$ are defined by the $CINDEF
macro. The definitions are in the library SYSSLIBRARY:LIB.MLB.
4-15

PERFORMING I/O OPERATIONS
p3
Longword containing flags and an optional event flag number
specification.
The low-order word contains the logical OR of
flags describing options to the connect-to-interrupt facility.
The flags and their meanings are as follows:
CIN$M EFN
CIN$M-USECAL
CIN$M REPEAT
CIN$M INIDEV
CIN$M START
CIN$M ISR
CIN$M CANCEL

Set event flag on interrupt
Use CALL interface
to
process-specified
routines (default is JSB interface)
Leave process connected to the interrupt
vector until the connection is canceled
Process-specified
device
initialization
routine is in the buffer specified in the Pl
argument
Process-specified start I/O routine is in
buff er
Process-specified interrupt service routine
is in buffer
Process-specified cancel I/O routine is in
buff er

The high-order word specifies the number of the event flag to be
set when an interrupt occurs. This number is expressed as an
offset to CIN$V EFNUM.
For example, to specify that your interrupt service routine is in
the buffer and to set event flag 4, code P3 as follows:
P3 = CIN$M ISR!CIN$M EFN!4@CIN$V EFNUM>
See the "Notes" later in this section for additional
on the flags.

information

p4
Address of the entry mask of an AST service routine to be
as the result of an interrupt.

called

AST parameter to be passed to the AST completion routine (used as
the AST parameter only if the process-supplied interrupt service
routine does not overwrite the value).
pn

Number of AST control blocks to preallocate
fast, recurrent interrupts from the device.

anticipation

Return Status

SS$ NORMAL
System service successfully completed.
SS$ ACCVIO
The caller does not have the appropriate access to the buffer
specified in the Pl arqument or to the entry point list specified
in the P2 argument.

4-16

PERFORMING I/O OPERATIONS
SS$ BADPARAM
The size of the buffer specified in the Pl argument exceeds 64K
bytes, or the number of preallocated AST control blocks specified
in the P6 argument exceeds 65767.
SS$ DISCONNECT
A connection is already outstanding for the device, or
condition described in note 2.b (see "Notes") has occurred.

SS$_EXQUOTA
The process has exceeded its direct I/O limit quota
limit quota.

its

AST

complete

the

SS$ ILLEFC
An illegal event flag number was specified.
SS$ INSFMEM
Insufficient system dynamic memory is available to
system service.
SS$ INSFSPTS
Insufficient system page table entries are available to double
map
the process buffer.
(The value of the REALTIME SPTS
parameter to the SYSGEN utility must be increased.)
SS$ NOPRIV
The process does not have the CMKRNL privilege.
This privilege
is only required if the user specifies a buffer to be used by the
process and the process-specified kernel mode routines.
SS$ UNASEFC
The process is not associated with
specified event flag.

the

cluster

containing

the

Privilege Restrictions
The connect-to-interrupt $QIO call does not require privileges if
no shared buffer is specified. If the request specifies a buffer
descriptor argument, the process must have the CMKRNL privilege.
Resources Required/Returned
A connect-to-interrupt request updates the process
as follows:

quota

values

•

Subtracts the number of preallocated AST control blocks in the
P6 argument from the number of outstanding ASTs remaining for
the process (ASTCNT)

•

Subtracts 1 (for the $QIO) from the direct I/O count (DIOCNT)

4-17

PERFORMING I/O OPERATIONS
Notes
1.

After the $QIO call is issued, the operation is not completed
until the process or the connect-to-interrupt driver cancels
I/O on the channel.

The connect-to-interrupt driver can cancel I/O on the channel
for a number of reasons, including the following:

The driver cannot set the specified event flag, perhaps
because the process disassociated from the common event
flag cluster after requesting that a flag in that
cluster be set.

The driver cannot reallocate AST control blocks quickly
enough. This condition can occur because not enough AST
control blocks (P6 argument) were specified, because not
enough pool space is available for the requested AST
control blocks, or because the process ASTCNT quota is
exhausted.

The driver cannot queue the AST to the process.

If no event flag setting was requested in the P3 argument and
if no AST service routine was specified in the P4 argument,
Po if ignored and no AST control blocks are preallocated. If
you requested an event flag be set and/or an AST service
routine but did not preallocate any AST control blocks
(that
is, Po is zero), one AST control block is automatically
preallocated, because the system needs one control block to
set any event flag or to deliver any ASTs.
If you request an event flag and/or an AST service routine
and
if
you
preallocate any AST control blocks, the
CIN$M REPEAT bit is set automatically in the
longword
speciried
in the P3 argument.
Thus, as long as you
preallocate any AST control blocks, your process
will
automatically remain connected to the interrupt vector to
receive repeated interrupts until the process is disconnected
from the interrupt vector.
If the CIN$M REPEAT flag is not set, the process
is
disconnected from the interrupt vector after the first
successful interrupt, and a status code of SS$ NORMAL is
returned.

Conventions for Process-Specified Routines

4.6.6

Any routines that the process specifies in the connect-to-interrupt
call are double-mappe0, once in process space and once in system
space. Each routine executes in kernel mode at an appropriate IPL:
•
e

•
•

Device initialization routine after power recovery - IPL 31
(IPL$ POWER)
Start-I/O routine - IPL h (IPL$ QUEUEAST)
Interrupt service routine - devTce IPL (assumed to be IPL 22)
Cancel routine - IPL 6 (IPL$ QUEUEAST)

The process must have the CMKRNL user privilege.

4-18

PERFORMING I/O OPERATIONS
Each routine must:
•
•
•
•
•
•
•
•
•

Be position independent
Follow the rules for accessing I/O space (see Section 4.5.3)
Access only data within the buffer or non-pageable locations
in system space
Perform any necessary synchronization of access to data in the
shared buff er
Save any registers it uses
(unless otherwise noted in the
remaining sections of this chapter)
Exit properly
Not incur exceptions
Not perform lengthy processing
Not dispatch to code outside the buffer specified in the Pl
argument to the Queue I/O Request call

Sections 4.6.8 through 4.6.11 discuss conventions for specific process
specified routines. Section 4.6.12 describes several program examples
of connecting to an interrupt vector.
The VAX/VMS Guide to Writing a Device Driver explains how to write a
device initialization routine, a start I/O routine, an interrupt
service routine, and a cancel I/O routine. That manual also discusses
the I/O data structures used by these routines.

4.6.7

Programming Language Constraints

Only VAX-11 MACRO or VAX-11 BLISS-32 should be used to
code
process-specified routines in system space (see Section 4.n.n) or any
references to I/O space.
There is no assurance that the code
generated by compilers for other languages will satisfy all the
constraints described in this section.
The following constraints apply to process-specified routines in
system space
(that is, in the buffer specified in the Pl argument to
the $QIO call that establishes the connection to the interrupt
vector):
•

The compiler must generate position independent code
routines.

for

•

The generated code and data
space.

virtual

•

No calls can be made to any procedure outside the buffer.
(This restriction includes calls to routines in the VAX-11
Common Run-Time Procedure Library.)

must

contiguous

the

For any references to I/O space, the generated code must follow the
rules for accessing I/O space (see Section 4.5.2). Device reqister
access from high-level languages usually requires that the variable
equivalent to the register be a ln-bit integer data type. You may
need to check the assembly-language code generated by compilers for
languages other than VAX-11 MACRO or VAX-11 BLISS-32 to determine
whether it follows all necessary conventions.

4-19

PERFORMING I/O OPERATIONS
4.6.8

Process-Specified Device Initialization Routine

During recovery
from
a
power
failure,
VAX/VMS
calls
the
connect-to-interrupt driver's device initialization routine. This
routine marks the device as online in the UCB$W STS field, stores the
UCB address in the IDB$L OWNER field, and then transfers control to
the
process-specified
device
initialization
routine.
The
process-specified routine executes in system context at IPL 31
(IPL$_ POWER) •
If the process specified a JSB interface, the
control with the following register settings:
RO
R4
RS
R6
R8

address
address
address
address
address

of
of
of
of
of

the
the
the
the
the

process

argument count
address of the
address of the
address of the
address of the
address of the

gains

unit control block (UCB)
device status register (CSR)
interrupt dispatch block (IDB)
device data block (DDB)
channel request block (CRB)

If the process specified a CALL interface, the process
control with an argument list pointed to by AP:
O(AP)
4(AP)
8(AP)
12(AP)
16(AP)
20(AP)

routine

gains

of s
device status register (CSR)
interrupt dispatch block (IDB)
device data block (DDB)
channel request block (CRB)
unit control block (UCB)

device
registers.
The process-specified routine may initialize
However,
it must not lower IPL, and it must preserve all registers
except RO through R3.
The routine exits with an RSB instruction (for a JSB interface) or a
RET instruction
(for a CALL interface). The stack must be as it was
when the routine was entered.

4.6.9

Process-Specified Start I/O Routine

The process-specified start I/O routine executes in system context at
IPL 6 (IPL$ QUEUEAST).
It is entered from the connect-to-interrupt
driver's star~ I/O routine. The input to the process-specified start
I/O routine is as follows:
R2
R3
RS
O(AP)
4 (AP)
8{AP)
12(AP)
16(AP)

address of the counted argument list
address of the I/O requ~st packet (IRP)
address of the unit control block (UCB)
argument count of 4
system-mapped address of the process buff er
address of the I/O request packet (IRP)
system-mapped address of the device's CSR
address of the unit control block (UCB)

The process-specified start I/O routine may set up device registers.
It can raise IPL but must not lower it below n, and must exit at IPL
6. It must preserve all registers except RO through R4.
The routine exits with an RSB instruction (for a JSB interface) or a
RET instruction
(for a CALL interface). The stack must be as it was
when the routine was entered.

4-20

PERFORMING I/O OPERATIONS
4.6.10

Process-Specified Interrupt Service Routine

A process-specified interrupt service routine is entered when an
interrupt from the device occurs. This routine executes in system
context at device IPL. The input to the process-specified interrupt
service routine is as follows:
R2
R4
R5
O(AP)
4(AP)
8(AP)
12(AP)
16(AP)
20(AP)

address of the counted argument list
address of the interrupt dispatch block (IDB)
address of the unit control block (UCB)
argument count of 5
system-mapped address of the process buff er
address of the AST parameter
system-mapped address of the device status register (CSR)
address of the interrupt dispatch block (IDB)
address of the unit control block (UCB)

This routine is responsible for clearing the interrupt condition
(by
writing to some device register, for example) if such an operation is
required for the device.
In addition, the routine may copy the
contents of device registers into the shared buffer or into the AST
parameter. The routine must also follow these conventions:
•

Maintain an IPL equal to or higher than device IPL (If the IPL
is raised, the current IPL should first be saved on the stack
for later use in restoring IPL.)

•

Save and restore all registers other than RO through
in the routine

•

Restore the stack to its oriqinal state before exiting

used

• Place one of the following status values in RO before exiting:
low bit clear

-- dismiss interrupt

(process is not notified of

interrupt)
low bit set

•

4.n.11

set event flag if CIN$M EFN bit is set in P3
argument, and queue AST if P4 specifies an
AST service routine

Exit with a RET instruction
instruction (JSB interface)

(CALL

interface)

RSB

Process-Specified Cancel I/O·Routine

When the user process issues a cancel I/O request for a device
connected to the process, the connect-to-interrupt driver's cancel I/O
routine first checks to determine whether the process can indeed
cancel I/O for this device. If it can, the process-specified cancel
I/O routine is given control. This routine executes in system context
at IPL 8 (IPL$_FORK).
If a JSB interface was specified for the process-supplied
routine, the following registers are inputs:
R2
R3

R4
R5

cancel

negated value of the channel index number
address of the current I/O request packet (IRP)
address of the process control block (PCB) for the
canceling the I/O
address of the unit control block (UCB)

4-21

I/O

process

PERFORMING I/O OPERATIONS
If a CALL interface was specified, the argument list is as follows:
O(AP)
4(AP)
8(AP)
12(AP)
16(AP)

argument list count of 4
negated value of the channel index number
address of the current I/O request packet (IRP)
address of the process control block (PCB) for the
canceling the I/O
address of the unit control block (UCB)

process

The process-specified cancel I/O routine must not lower IPL below ~
and must exit at IPL 6.
It may clear device registers.
It must
preserve all registers except RO and R3, and must place a completion
status in RO-Rl
(which VAX/VMS will place in the 1/0 status block
associated with the connect-to-interrupt $QIO call).
The process-specified cancel I/O routine should not rely on the
channel index number unless it checks the UCB$M BSY bit in UCB$W STS
to confirm that the process is still connected to the device. -The
routine may set the UCB$M CANCEL bit in UCB$W STS.
The routine exits with an RSB instruction (for a JSB interface) or a
RET instruction
(for a CALL interface). The stack must be as it was
when the routine was entered.

4.6.12

Real-Time Applications Examples

To understand how the connect-to-interrupt facility is useful for
programming real-time devices, consider devices used in three types of
real-time applications:
1.

Asynchronous event reporting without datn:
devices that
generate an interrupt as the result of an external event not
initiated by a programmed request.

Program-driven data collection:
devices that generate an
interrupt as the result of a programmed request, and make the
result of the request available as data in a device register
at the time of the interrupt.

Asynchronous event reporting with data: one device triggers
another device by generating an interrupt that causes a
programmed request to be sent to the other device, which in
turn generates an interrupt.

Examples of these three types of real time applications and models
programs to handle the devices follow.
NOTE
The configurations described in
the
examples
in
this
section are not
officially supported; DIGITAL does not
provide
device
driver,
UETP,
or
diagnostic support for certain devices
mentioned.
The examples are provided
merely as possible models for users who
wish to design real-time applications
using
unsupported
devices
or
configurations.

4-22

PERFORMING I/O OPERATIONS
Chapter 6 contains a program example illustrating data definitions and
coding used to connect to a device interrupt vector.

4.6.12.1 Example 1: KWll-W Watchdog Timer - This type of device
reports asynchronous external events:
it generates an interrupt as a
result of an external event not initiated by a programmed request.
The only data of interest to be passed to the user process is the
occurrence of the external event. Such devices include contact and/or
solid state interrupts, and clocks or. counters. The program may need
to initiate clock and counter devices by means of a programmed
request,
but any subsequent interrupts are the result of external
events only.
In this example, a dual-processor system uses two KWll-W watchdog
timers connected back-to-back to monitor CPU failures.
Each processor
must arm its timer at regular intervals to prevent the timer from
operating a relay that outputs an alarm signal. The alarm output of
each timer is connected to the receive input of the other watchdog.
If processor A fails and its watchdog times out, the alarm output
generates an interrupt on processor B via the second watchdog timer.
The watchdog control program on each processor simply addresses the
timer at regular intervals.
If the interval passes without the timer
being addressed, the timer operates an output relay that generates an
interrupt to the second CPU.
For this example, assume that the
interval is 5 seconds (Example 3 later in this section addresses the
problem of a much smaller time interval).
The watchdog control program on processor A executes as follows:
1.

Assigns a channel to the device

Calls $CRMPSC to map to the I/O page in order to address
device registers

Issues a connect-to-interrupt $QIO call to connect the
program to the watchdog timer for processor B; specifies the
addresses of an interrupt service routine and an AST routine

Writes a value to a device register to start the timer

Calls SSETIMR to request that an event flag be
specified interval (for example, 5 seconds)

Calls $WAITFR to wait for the event flag

When the event flag is set,
register to reset the timer

Loops to step 5

writes

value

set

the

after

device

The same control program runs on processor B except that it connects
to the watchdog timer for processor A. If either processor fails, the
watchdog timer generates an interrupt on the other processor.
The standby processor that receives the interrupt gains control in the
VAX/VMS
connect-to-interrupt
driver
(CONINTERR), which calls a
process-supplied interrupt service routine (defined in step 3 above)
that handles the interrupt as follows:
1.

Sets the KWll-W switch relay
interrupt condition

4-23

clear

the

timer

PERFORMING I/O OPERATIONS
2.

Sets a status flag that will cause an AST to be delivered
the control program that connected to the interrupt

Returns to CONINTERR

CONINTERR completes the interrupt handling as follows:
1.

Schedules a fork process at a lower IPL. This fork process,
when it gains control, will queue an AST to the user program.

Executes an REI instruction to return from the interrupt

The timer control program on the standby processor regains control in
an AST routine.
This routine responds to the other processor's
failure by switching over and assuminq control of
the
other
processor's tasks (or whatever is appropriate).

4.6.12.2 Example 2: ADll-K, AMll-K; A/D Converter with Multiplexer
Connected to the UNIBUS - This type of device provides program-driven
data collection:
it generates an interrupt as the result of a
programmed request to the device, and makes the result of the request
available as data in a device register. Typical devices include A/D
converters and digital I/O registers.
The data collection operation is usually repetitive
for
such
applications.
Therefore, the interrupt service routine must be
capable of buffering data from the device in order to ensure that no
data is lost due to the high speed data transfer rate. A typical
buffer size for this sampling technique might be 32 ln-bit words.
In this example, a user program controls an ADll-K/AMll-K combination
that accepts analog data from thermocouples. The ADll-K converts
analog data to digital data and returns the data in a device register.
Every 10 seconds, the program samples 16 to 32 out of n4 channels at
gain settings that may vary based on the thermocouple type and
previous samplings.
To collect data efficiently, the program buffers
data
in
a
process-specified interrupt service routine, and requests delivery of
an AST to the user process when all the requested channels have been
sampled.
To perform variable sampling, the program passes parameters
to the interrupt service routine.
The program establishes a protocol to communicate between the program
and the interrupt service routine. The protocol defines a data area
shared by the main program, the interrupt service routine, and the AST
routine.
The data area contains parameters from the program and data
from the ADll-K. The data area is a 98-word array used as follows:
1.

Elements 1-2 of the data area contain an index to the next
buffer location to be filled, and a count indicating the
nuMber of samplings still to be taken.
The main program
initializes these values before starting the device. The
interrupt service routine reads and modifies these values in
the process of copying data and determining when to stop
sampling.

Elements 3-66 of the data area are reserved for interrupt
service routine parameters. Each pair of elements contains
the number of a channel, and a qain value. The main program
loads these parameters before starting the device.

4-24

PERFORMING I/O OPERATIONS

Elements 67-98 of the data area receive the data that the
interrupt service routine reads from the ADll-K data buffer
register. The AST routine later reads data from this part of
the buffer.

The program sets up for the sampling as follows:
1.

Assigns a channel to the device

Calls $CRMPSC to map to the I/O page in order to address
device registers

Initializes the data area by writing a n7 (the index to the
next buffer location to be filled) into element 1, and the
number of samples to take into element 2 of the data area;
zeroes elements 3-98 of the data area

Writes channel numbers and gain
section of the data area

Issues a connect-to-interrupt SQIO call to connect the
process to the A/D converter; specifies the addresses of the
area to be double mapped, an offset to the ISR, and an AST
routine

Sets the start and interrupt enable bits in the ADll-K status
register to start the A/D converter

Calls $HIBER to place the process in a wait state

values

into

the

parameter

As soon as the ADll-K has converted the first sample, the device
generates an interrupt.
The VAX/VMS CONINTERR routine calls the
process-specified interrupt service routine.
This process-specified
routine executes as follows:
1.

Computes the next location to be written in
reading the first element in the data area

the

buffer

Reads 12 bits of data from the A/D buffer register
next location in the buff er

into

the

Updates the buffer offset and count elements at the beginning
of the data area

If all requested samples have been collecte<l, writes the
address of the data area into the AST parameter, sets a
status flag that will cause an AST to be delivered to the
control program, and returns to the CONINTERR routine

Otherwise, sets the start bit in a device register to restart
the device and returns to the CONINTERR routine with a status
flag requesting no AST delivery or event flag setting

Based on the interrupt status from the process-specified interrupt
service
routine, the CONINTERR routine completes the interrupt
processing by queuing a fork process that will queue an AST to the
user process.
When the process gains control in the AST service
routine, this routine processes the samples in the following steps:
1.

Clears the interrupt enable bit in the device status register

Examines the data collected in order to adjust
selection and/or gain values for the next sampling

4-25

channel

PERFORMING I/O OPERATIONS
3.

Copies the data to a file

Reinitializes the data area

Calls $SCHDWK to wake the process after a short interval (for
example, 10 seconds)

Returns

When the time interval elapses, the process regains control.
The
program can then restart the sampling process by again setting the
start and interrupt enable bits in the ADll-K status register.

4.6.12.3 Example 3: KWll-P Real Time Clock and ADll-K Converter
Connected to the UNIBUS - This type of device reports asynchronous
external events by collecting data:
one device triggers another
device by generating an interrupt that causes a programmed request to
be sent to the other device, which in turn generates an interrupt.
A
typical example is a clock-driven A/D operation for precise time
sampling as required in signal processing. This processing technique
is often used in laboratories. The amount of data collected in such a
timed sampling might typically be 200 to 1000 16-bit words.
In this example, the main program sets up the real-time clock to
generate interrupts periodically.
At regular intervals, the clock
interrupt triggers a programmed request for an A/D
conversion
operation.
The ADll-K collects a sample, and interrupts the CPU with
a "done" interrupt and 12 bits of data. The ADll-K interrupt service
routine buffers the data and, if the buffer is full, causes an AST to
be delivered to the process. The process, gaining control in an AST
routine, copies the buffered data to another buffer or to disk.
Programming these device functions is slightly more complicated than
the previous example. The main program must specify a large buffer to
be used in ring fashion to guarantee that data is not lost between
clock-driven samplings. In addition, the program must connect to two
device interrupts
one for the clock and one for the A/D converter.
The protocol used by the main program, the interrupt service routine,
and the AST routine is similar to the previous example. The data area
is larger: 4K words of buffer area follow the parameter area.
The
A/D converter interrupt service routine and the AST routine treat the
4K-word buffer as four buffer sections of lK words per section.
The
first element in each lK buffer section is a flaq indicating whether
the section is in use. The AST resets the flag value after copying
the contents of the buffer.
The interrupt service routine uses a
buffer section only if the section's flag value indicates that the
buffer has been emptied.
The main program starts the sampling with the following steps:
1.

Assiqns channels to the clock and to the A/D converter.

Calls $CRMPSC to map to the I/O page in order to address
device registers.

Initializes the data buffer by writing a ~7 (the index to the
next buffer location to be filled) into element 1, and the
number of samples to take into element 2 of the data area;
zeroes elements 3-409n of the data area;
flags each page of
the buffer as available.

4-2fi

the

PERFORMING I/O OPERATIONS
4.

Writes channel numbers and gain
segments of the data area.

values

into

the

parameter

Issues a connect-to-interrupt $QIO call to connect the
process to the clock, and specifies the address of an
interrupt service routine.

Issues a connect-to-interrupt $QIO call to connect the
process to the A/D converter; and specifies the addresses of
the area to be double mapped, an offset to the interrupt
service routine and an AST routine.

Sets the sampling interval by writing a 16-bit value into the
KWll-P count set buffer register.

Starts the clock by setting the run, mode,
rate selection,
and interrupt enable bits in the KWll-P control and status
register. Setting the mode bit causes repeated interrupts
generated at a rate specified in the time interval.

Calls $HISER to place the process in a wait state.

The clock interrupts when zero (underflow) occurs during a count-down
from the preset interval count. The VAX/VMS CONINTERR routine calls
the process-specified clock
interrupt
service
routine.
This
process-specified routine starts the A/D conversion as follows:
1.

Starts the A/D converter by setting the start
enable bits in the ADll-K status register

and

Sets interrupt status that prevents AST delivery
flag setting as a result of this interrupt

Returns to CONINTERR

interrupt
or

event

Starting the A/D converter results in an interrupt from the ADll-K,
and control passes, via CONINTERR, to the ADll-K interrupt service
routine. This routine executes as follows:
1.

If this sample is the first sample for a new buffer
(indicated by a flag in the data area), the routine moves to
the next buffer section (branches to error handling if the
buffer is still full), and sets up the first two elements of
the data area to indicate the buffer section to be written
next.
Then, it sets the flag at the start of the new buffer
section and sets a flag in the data area to indicate that
sampling is occurring.

The routine computes the next location to be written in
buffer by reading the first location in the data area.

The routine reads 12 bits of data from the
register into the next location in the buffer.

The routine updates the buffer offset and count values in the
data area.

If this sample fills the data sector, the routine writes the
offset of the filled sector from the start of the 4K-word
buffer into the AST parameter, sets a status flag that will
cause an AST to be delivered to the control proaram, and sets
a. flag indicating that a new data section is to be starteo.

The routine returns to CONINTERR.

4-27

A/D

the

buffer

PERFORMING I/O OPERATIONS

The AST routine copies and zeroes the next buffer section to indicate
that the section is again available to the interrupt service routine.
When the next clock interrupt occurs, the data can be written to the
next buffer section, even if the AST routine has not yet emptied the
previous buffer section.

4-28

CHAPTER 5
USING SHARED MEMORY

The MA780 is a multiport memory unit that can be attached to
VAX-11/780 processors.
Each VAX-11/780 processor can support up to
two MA780s. Each MA780 has four ports, thereby allowing up to four
VAX-11/780 processors to be attacheo to it. Figure 5-1 illustrates
two VAX-11/780 processors attached to an MA780.
LOCAL
MEMORY

VAX

11/780

SBI

MBA

USA

Figure 5-1

LOCAL
MEMORY

SBI

MA780
PORT

MA780
MULTIPORT
MEMORY

MA780
PORT

USA

MBA

Two VAX-ll/780s Attached to an MA780

Using one or more multiport memory units, an application can consist
of multiple processes running on different VAX-11/780 processors.
Regardless of the processor on which they are running, these processes
can communicate the completion of an event, send messages, ano share
common data and code by means of the shared memory.

5.1

PREPARING MULTIPORT MEMORY FOR USE

Before an application using multiport memory can execute under
VAX/VMS, the system manager must activate the VAX/VMS operating system
in processors connected to the multiport memory unit and initialize
that memory.
The VAX/VMS System Manager's Guide explains the system
management responsibilities ___associated withamultiport memory unit;
the present section summarizes the system management functions for the
benefit of the application programmer.
First, the system manager activates the VAX/VMS operating system in a
VAX-11/780 and initializes the multiport memory unit. These actions
cause the following to occur:
•

The uninitialized shared memory is connected
system running in the processor.

5-1

the

VAX/VMS

USING SHARED MEMORY
•

A name is defined that all processes running in all processors
can use to refer to the shared memory (see Section 5.3)

•

Limits are set for the following resources in
memory unit:

this

multiport

Common event flag clusters: the total number that can
be created, and the number that can be created by
processes runninq on this processor
Mailboxes:
the total number that can be created, and
the number that can be created by processes running on
this processor
Global sections:
the total number that can
created, and the number that can be created
processes runninq on this processor

be
by

Then the system manager activates the VAX/VMS operating system in
other processors connected to the multiport memory unit. The system
manager then connects the initialized shared memory to the VAX/VMS
system running in each of these processors and sets limits for the
number of common event flag clusters, global sections, and mailboxes
that processes on each processor can create in the multiport memory.
The system manager can also install global sections in shared memory
just as they are installed in local memory. The INSTALL utility can
be used to create shared memory global sections for known files. Once
the global sections are installed, a process runninq in any processor
connected to the multiport memory can map to the section, if the
process has the appropriate privilege. The process can qain access to
the global section either by using a logical name defined by the
system manager or by using the section name specified when the global
section was created. In the latter case, the section name must be
unique on this processor.

5.2

PRIVILEGES REQUIRED FOR SHARED MEMORY USE

To use facilities in memory shared by multiple processors, you must
have all of the user privileges required to use the equivalent
facility in local memory.
For example, to create a permanent global
section, you must have the PRMGBL privileqe, and to create a temporary
or permanent mailbox, you must have the TMPMBX or PRMMBX privilege,
respectively.
In addition to any other required privileges, you must have the SHMEM
privilege to create or delete a common event flag cluster, mailbox, or
global section in memory shared by multiple processors. However, you
do not need the SHMEM privilege to use an existing cluster, mailbox,
or global section in multiport memory.

5.3

NAMING FACILITIES IN SHARED MEMORY

To allow access to facilities in memory shared by multiple processors,
the system manager and application programmers define names that
application programs use to refer to individual shared memory units.
During system installation, the system manager defines the name that
processes on that particular processor use to refer to the shared
memory itself. Application programs define the names that they use to
refer to common event flag clusters, global sections, and mailboxes
located in the shared memory.
5-2

USING SHARED MEMORY
By convention, facilities in shared memory have a name string
following format:

the

[memory-name:]facility-name
memory-name
Name assigned by the system manager during system installation to
the shared memory containing the facility. VAX/VMS requires the
memory name when you specify a common event flag cluster or
mailbox.
The colon is recognized as a delimiter separating the
two parts of the name string.
facility-name
Logical name assigned to the event flag cluster, global section,
or mailbox.
The name must contain 15 or fewer characters, and
can consist only of alphabetic characters, numeric characters,
the dollar sign ($),and the unJerline (_).
Examples of facility names are:

5.4

SHRMEM:GS DATA

Identifies the global section GS DATA in
shared memory named SHRMEM

the

SHRMEM:MAILBX

Identifies the mailbox
shared memory

same

MAILBX

the

ASSIGNING LOGICAL NAMES AND LOGICAL NAME TRANSLATION

You can define a logical name for a shared memory facility with the
DEFINE or ASSIGN command or the Create Loqic~l Name ($CRELOG) system
service. Application programs can then refer to the facility using
the logical name;
for example, a process can invoke the Create
Mailbox and Assign Channel ($CREMBX)
system service specifying the
logical name for an existing mailbox to which a channel is to be
assigned.
When translating a logical name for a shared memory facility,
the
VAX/VMS operating system uses a slightly different approach from that
used for other logical names. The purpose of this approach is to
allow programmers to specify either the complete name (memory name and
facility name) or a logical name that the system will translate to the
complete name.
If you define logical names properly, a program that
uses a given facility in local memory can be run without chanqe to use
the facility in shared memory.
Whenever VAX/VMS encounters the name of a common event flag cluster,
mailbox, or global section, it performs the following special logical
name translation sequence:
1.

Inserts one of the following prefixes to the name (or to the
part of the name before the colon if a colon is present):
CEF$ for common event flag clusters
MBX$ for mailboxes
LIB$ for global sections

5-3

USING SHARED MEMORY
2.

Subjects the resultant string to logical name translation.
If translation does not succeed (that is, the original name
did not use a logical name), passes the original name string
to the system service. If translation does succeed, goes to
step 3.

Appends the part of the original string after the
any) to the translated name.

Repeats steps l to 3 (up to nine more times,
if necessary)
until logical name translation fails.
When translation
fails, passes the string to the system service.

For example, assume that you have
assignment:

made

the

following

colon

logical

(if

name

$DEFINE MBX$CHKPNT SHRMEM$l:CHKPNT
Assume also that your program refers to the mailbox name as CHKPNT in
a system service argument.
The following loqical name translation
takes place:
1.

MBX$ is prefixed to CHKPNT.

MBX$CHKPNT is translated to SHRMEM$l:CHKPNT.

No further translation is successful; therefore, the
SHRMEM$l:CHKPNT is passed to the system service.

string

The logical name definition in the preceding example allows a program
that used a mailbox named CHKPNT in local memory to run usinq the
mailbox in shared memory, without being recompiled or relinked.
Note that if a process creates one or more subprocesses and they use a
mailbox or common event flag cluster in shared memory, the creator
should place the logical name in the group logical name table
(for
example, specify the /GROUP qualifier with the DEFINE command). If
the name is defined in the process logical name table
(the default),
the subprocesses will not receive the correct equivalence name,
because each subprocess has its own process logical name table.
There are two exceptions to
discussed in this section:

the

logical

name

translation

method

•

If the facility name starts with an underline ( ), the VAX/VMS
system strips the underline and considers the resultant string
to be the actual name (that is, no further translation is
performed).

•

If the facility is a global section with a name in the format
name nnn, VAX/VMS first strips the underline and the digits
(nnnT, then translates the resultant name according to the
sequence discussed in this section, and finally reappends the
underline and digits. The system uses this method with known
images and shared files installed by the system manager.

5-4

USING SHARED MEMORY
5.5

HOW VAX/VMS FINDS FACILITIES IN SHARED MEMORY

After the VAX/VMS system performs the logical name translation
described in Section 5.4, the final equivalence name must be the name
of a facility in either the processor's local memory or in shared
memory.
If the equivalence name specifies the name of a shared memory
(that is, the name is in the format name:facility-name), VAX/VMS
searches for the facility in the appropriate data base of the
specified memory.
If the equivalence name specifies a common event flag cluster or
mailbox and does not specify a memory name, VAX/VMS searches through
the common event flag cluster data base or the mailbox data base until
it locates the specified cluster or mailbox. Absence of a memory name
as part of a common event flag cluster name or mailbox name indicates
that the facility is located in local memory.
If the equivalence name specifies a global section and does
specify a memory name, VAX/VMS looks for the section as follows:
1.

First, it searches the global section tables for sections
the processor's local memory.

Then,
it searches the global section tables for
each
initialized shared memory connected to the processor in the
order in which they were connected and recognized by the
processor.

The result of searching in this order is that global
processor's
local memory take precedence over
memories. Thus, absence of a memory name as part of
name is not used as an indication of where the
located.

5.6

not
in

sections in the
those in shared
a global section
global section is

USING COMMON EVENT FLAGS IN SHARED MEMORY

Under VAX/VMS, any process can associate with up to two common event
flag clusters
(event flag numbers n4 through 95 and 9n through 127).
These clusters can be located in shared memory or in local memory. To
create and associate with a common event flag cluster in shared memory
and manipulate flags in the cluster, you use the same steps as you
would to associate with a common event flag cluster in local memory:
1.

Issue the Associate Common Event Flag Cluster
($ASCEFC)
system service to create the cluster or to associate with an
existing cluster.

Issue any of the services that set, clear,
designated event flags, as appropriate.

and

wait

for

As with local memory clusters, the first process among cooperating
processes to issue the Associate Common Event Flag Cluster ($ASCEFC)
system service causes the cluster to be created.
Any other process
calling this service and specifying the same cluster associates with
that cluster. VAX/VMS implicitly qualifies cluster names with the
group number of the creator's UIC;
therefore, other cooperatinq
processes must belong to the same group.

5-5

USING SHARED MEMORY

All of the event flag system services, with the exception of Associate
Common Event Flag Cluster and Disassociate Common Event Flag Cluster,
function identically regardless of whether they are used with local or
shared memory clusters.
The only difference with the associate and
disassociate system services is that to specify a cluster in shared
memory, you must provide the memory name as well as the cluster name.
That is, after VAX/VMS performs logical name translation of the name
argument, the cluster name must have the following format:
memory-name:cluster-name
Section 5.3 describes the name format, and Section
logical name translation performed by the system.

5.4

explains

the

Section 3.1 discusses common event flags and related system services.
The VAX/VMS System Services Reference Manual describes all of the
event flag services in detail.

5.7

USING MAILBOXES IN SHARED MEMORY

The first process on each processor to refer to a shared memory
mailbox must use the Create Mailbox and Assign Channel ($CREMBX)
system service to create the mailbox and assign a channel to it.
Any
$CREMBX system service call referring to a shared memory mailbox must
specify a mailbox name that has or translates to the following format
(Section 5.4 explains the logical name translation procedure):
memory-name:mailbox-name
When the mailbox is created, the $CREMBX system service also creates
the mailbox-name portion of the name string as a logical name with an
equivalence name in the format MBn. For example, if the complete name
string is SHMEM:MAILBOX, the system service will create MAILBOX as a
logical name with an equivalence name of, for example, MBB005.
The Assign I/O Channel ($ASSIGN) and Deassign I/O Channel
($DASSGN)
system services require that you specify only the mailbox-name portion
of a shared memory mailbox name string.
Likewise, any high-level
language program statements that open, close, read from, or write to a
shared memory mailbox must specify only the mailbox-name portion.
Figure 5-2 shows two VAX-11 FORTRAN programs using a shared memory
mailbox.
The memory-name in this example is SHMEM. The programs are
running in processes on separate processors.

5-6

USING SHARED MEMORY
PROGRAM
ONE
INTEGER*4 SYS$CREMBX,STATUS,CHAN
STATUS= SYS$CREMBX(,CHAN,,,,, 1 SHMEM:MAILBOX')
IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
C-- Open the mailbox using the mailbox-name; write a message.
OPEN (UNIT=l,NAME='MAILBOX',STATUS='NEW'}
WRITE (l,*)
MESSAGE

END

PROGRAM
TWO
INTEGER*4 SYS$CREMBX,STATUS,CHAN
STATUS= SYS$CREMBX(,CHAN,,,,, 'SHMEM:MAILBOX')
IF (.NOT. STATUS) CALL LIB$STOP(%VAL(STATUS))
C-- Open the mailbox using the mailbox-name;
OPEN
READ

read the message.

(UNIT=l,NAME='MAILBOX',STATUS='OLD')
(l,*)
MESSAGE

END
Figure 5-2
A mailbox in shared memory
mailbox.

Using a Shared Memory Mailbox
cannot

Section 3.2 discusses mailboxes
includes a programming example.

5.8

be
and

used
related

process
system

termination

services,

and

USING GLOBAL SECTIONS IN SHARED MEMORY

Under VAX/VMS, processes can map global sections
located
in local
memory or in shared memory.
A global section in shared memory can be
mapped to an image file or a data file, just like a global section
in
local memory.
To create a
global
section
in shared memory, you
perform the same steps a? you would to create a
global
section
in
local memory:
1.

Using VAX-11 RMS, open the file to be mapped.

Issue the Create and Map Section

($CRMPSC)

system service.

The file to be mapped must reside on a disk
device attached
to
the
local processor.
Once the section is created, however, processes on
all processors attached to the shared memory can map the section.

5-7

USING SHARED MEMORY
To map an existing global section in shared memory, you issue a Map
Global Section
($MGBLSC) system service specifying the name of the
section. Once the section is mapped, processes gain access to shared
memory global sections in the same manner as they do to local memory
sections.
VAX/VMS thus makes use of the shared
memory
unit
transparent to the process.
VAX/VMS treats the pages of a global section in shared memory
differently from pages in local memory. When a process creates a
shared-memory global section, VAX/VMS brings all of the pages of the
mapped image or data file into memory. Any process mapped to that
global section can gain access to those pages without incurring a page
fault because the pages are already in physical memory.
Unlike
process pages in local memory, global section pages in shared memory
are not included in the working sets of the processes that map the
section.
Because no paging occurs, VAX/VMS never writes the contents of shared
memory global section pages back to their disk file.
For read/write
global sections in which you want to maintain an updated file while
the application executes, you must issue an Update Section File on
Disk ($UPDSEC) system service. The process issuing the update request
must execute on the same processor as the process that created the
global section. You can update the disk file periodically during
execution of the application as a checkpoint precaution. The disk
file is automatically updated when the section is deleted.
Each process that has mapped a global section in shared
unmap the section in either of the following ways:

memory

can

•

Issue a Delete Virtual Address Space ($DELTVA) system service
to delete the process's virtual address space that maps the
section.

•

Terminate the current image, thereby causing VAX/VMS to
the process from the section automatically.

unmap

Deleting a global section in shared memory requires an explicit
deletion request, because all global sections in shared memory must be
permanent sections. The deletion request can be either a Delete
Global Section ($DGBLSC) system service issued by the application or a
deletion request issued by the system manager.
In either case,
VAX/VMS does not perform the actual deletion until all processes that
have mapped the section unmap it.
The VAX/VMS System Services Reference Manual provides information on
the use o( tfi~ VAX/VMS system services used with global sections, that
is, memory management system services. Section 5.8.l of the present
manual provides information specifically related to creatinq and
mapping a global section in shared memory.
The $CRMPSC, $MGBLSC,
$DGBLSC, and $UPDSEC system services are the only memory management
system services for which the shared memory
has
any
direct
implications.

5.8.1

Create and Map Section System Service

The Create and Map Section System Service has the following qeneral
formats when issued to create and/or map a global section in multiport
memory.

5-8

USING SHARED MEMORY
MACRO Format
$CRMPSC

[inadr],
, [ident],

[retadr],
[relpag,],

[ a c mode ] ,
[ fl a g s ] ,
[chan],
[pagcnt),

gsdnam
[vbn),
[prot]

High-Level Language Format
SYS$CRMPSC
([inadr],
[retadr],
[acmode],
[flags], gsdnam
, [id en t] ,
[ re 1 pa g ] ,
[ch an] ,
[pa g c n t] ,
[vb n] ,
[pro t ] )
With the exception of the FLAGS, GSDNAM, and PFC arguments, the
arguments of this service are not affected by MA780 considerations.
flags
Mask defining the section type and characteristics.
defined, the following two must be set.

Flag

Meaning

SEC$M GBL
SEC$M-PERM

Global section
Permanent section

That is, sections in
sect ions.

shared

memory

must

Of the flags

permanent

global

If appropriate, the following flags also can be set.

Flag

Meaning

Default

SEC$M DZRO

Pages are demandzero pages

Pages are not zeroed
when copied

SECSM WR'r

Read/write section

Read-only

SEC$M SYSGBL

System global
section

Group global section

SEC$M EXPREG

Map section
into the
first free range
of virtual
addresses large
enough to hold
the section

Map section according
to the INADR argument

Neither SEC$M CRF
(copy-on-reference) nor SEC$M PFNMAP
(page
frame number -mapping) can be set when using the Create and Map
Section system service to create global sections in shared
memory.
If SEC$M CRF is set, VAX/VMS places the global section
in local memory.
gsdnam
Address of a character string descriptor pointing to the text
name string for the global section. This argument is required
for creating sections in shared memory.
The string can be either the name of a global section or the
logical name of a global section. VAX/VMS performs logical name
translation as described in Section 5.4.

5-9

USING SHARED MEMORY

VAX/VMS implicitly qualifies global section names with
an
identification.
For group global sections, the section name is
also implicitly qualified by the group number of the process
creating the global section.
pf c
Page fault cluster size for local memory sections. This argument
is ignored for global sections in shared memory, because VAX/VMS
reads the file into memory when it creates the section and does
not allow paging for sections in shared memory.

5-10

CHAPTER

PRIVILEGED SHAREABLE IMAGES

A privileged shareable image is a shareable image containing one or
more routines that nonprivileged users can call to perform privileged
functions. The creator of the privileged shareable image codes,
compiles or assembles, links, and installs the routine; other users
can then call this routine in their programs using the standard CALL
interface, provided they have linked their object module(s) with the
privileged shareable image. Privileged shareable images thus provide
a vehicle for users,
in effect, to write and use their own system
services.
Because privileged shareable images can be written for any purpose,
their
use is not limited to real-time applications.
However,
privileged shareable images can provide real-time users with a
suitable vehicle for special-purpose routines that nonprivileged
processes in applications can use.

6.1

CODING THE PRIVILEGED SHAREABLE IMAGE

The following requirements
shareable image:

must

met

coding

privileged

•

It must contain a special change-mode vector
kernel-mode and/or executive-mode dispatcher.

•

Its entry point must be followed by a CHMK or CHME instruction
with a negative operand.

•

Any kernel-mode or executive-mode dispatcher pointed to in the
change-mode vector must validate the CHMK or CHME operand, and
must be followed by one or more routines that perform the
desired function(s).

•

The privileged shareable image (or each routine in it) must
enable any necessary user privileges and disable them when
they are no longer needed.
The Set Privileqes
($SETPRV)
system service is used to enable and disable user privileges.

Each of the preceding considerations is
sections.

~-1

discussed

identifying

the

following

PRIVILEGED SHAREABLE IMAGES
Change-Mode Vector

6.1.1

One of the program sections in a privileged shareable image must start
with a change-mode vector. The purpose of this vector is to point (by
means of self-relative offsets) to the start of the kernel-mode or
executive-mode dispatch routine within the privileged shareable image.
The program section containing the change-mode vector must be assigned
the VEC attribute.
{See the VAX-11 MACRO Language Reference Manual or
the VAX-11 Linker Reference Manual for a discussion of program section
attributes.)
The change-mode vector must have the format shown in Figure 6-1.
The
offsets from the base of the vector to specific items are expressed by
symbols starting with PLV$L •
These symbols are defined by the
$PLVDEF macro and are contained in SYS$LIBRARY:LIB.MLB.
Vector Type Code
(PLV$C_TYP _CMOD)

PLV$L_TYPE

System Version Number
(SYS$K __VERSION)

PL V$L_ VERSION

Kernel Mode Dispatcher Offset

PLV$L_KERNEL

Exec Mode Entry Offset

PLV$L_EXEC

Reserved
Reserved

----

I-----·-

RMS Dispatcher Offset

PLV$L_RMS

Address Check

PLV$L_CHECK

Figure n-1

Change-Mode Vector Format

The significant offsets in the change-mode vector and
are as follows:

their

contents

•

PLV$L TYPE - Contains
the
type
code
identTfying this as a change-mode vector.

PLVSC_TYP_CMOD,

•

PLV$L VERSIUN - Contains the system version number
(expressed
by tlie value SYSSK VERSION). When the privileged shareable
image is linked, the Tinker inserts the value of SYSSK VERSION
into this location. Before the privileged shareable Image is
used at run time, the VAX/VMS image activator compares this
value with the current version number of SYS.EXE; and if the
two do not match, the privileged shareable image is not used
and an error status is returned.

•

PLV$L KERNEL - Contains a self-relative
pointer
to
the
user-iupplied kernel-mode dispatcher.
("Self-relative" means
relative to the start of the longword field.) A zero value
indicates there is no kernel-mode dispatch~r.

EXEC - Contains
a
self-relative
pointer
to
the
• PLV$L
user-iupplied
executive-mode
dispatcher.
A zero value
indicates there is no executive-mode dispatcher.

fi-2

PRIVILEGED SHAREABLE IMAGES
•

PLV$ RMS - Contains a self-relative pointer to the dispatcher
for -VAX-11 RMS services. A zero value indicates there is no
user-supplied VAX-11 RMS dispatcher.
Only one privileged
shareable image should specify the VAX-11 RMS vector, because
only the last value will be used. This field is intended for
use only by DIGITAL.

•

PLV$L CHECK - Contains a value to verify that a privileged
shareable image that is not position independent is located at
the proper virtual address.
If the image is
position
independent, this field should contain zero. If the image is
not position independent, this field should contain its own
address.

Entry Point to the Privileged Shareable Image

6.1.2

The entry point of a privileged shareable image must be an entry mask
followed by a CHMK (change mode to kernel) or CHME (change mode to
executive)
instruction, depending on whether you
want
control
transferred to a kernel-mode or executive-mode dispatcher (specified
in the vector). The operand of the CHMK or CHME instruction must be a
negative value,
because positive values are reserved for callinq
system services supplied by DIGITAL.

Kernel-Mode or Executive-Mode Dispatcher

6.1.3

The kernel-mode or executive-mode dispatch code that you write must:

6.1.4

•

Validate the
operands.

CHMK

CHME

operand,

handling

any

invalid

•

Transfer control to the appropriate coding segment if the
privileged shareable image contains functionally separate
coding segments. The CASE instruction in VAX-11 MACRO or a
computed
GO-TO-type
statement in a high-level language
provides a convenient mechanism for determining where to
transfer control.

•

Precede the coding segment(s) performing the function(s)
privileged shareable image was designed to perform.

the

Enabling and Disabling User Privileges

A privileged shareable image must enable any privileges that it needs
but that the nonprivileged user of the privileged shareable image
lacks. The privileged shareable image must also disable any such
privileges before the nonprivileged user receives control again.

6-3

PRIVILEGED SHAREABLE IMAGES
To enable or disable a set of privileges, use the Set Privileges
($SETPRV) system service.
The following example shows the operator
(OPER) and physical I/O (PHY_IO) privileges being enabled.
PRVMSK:

• LONG
.LONG

$SETPRV S

<l@PRV$V OPER>!<l@PRV$V PHY IO> ;OPERAND PHY IO
0
;QUADWORD MASK REQUIRED. NO BITS SET IN
;HIGH-ORDER LONGWORD FOR THESE PRIVILEGES.

ENBFLG=#l,PRVADR=PRVMSK

;l=enable, O=disable
;Identifies the privileges

Any code executing in executive or kernel mode is granted an
SETPRV privilege.
The VAX/VMS ~t~!!l f?_~ry_ic::_~§_Ji~terence Manual contains
of the Set Privileges ($SETPRV) system service.

6.2

implicit

explanation

is,

create)

•

Use the /SHAREABLE command qualifier to identify the image
be created as shareable.

•

Use the /PROTECT command qualifier or the PROTECT= option to
identify the entire image or specific clusters, respectively,
as protected aqainst user-mode or supervisor-mode write access
(see Section n.2.1 for further information).

•

Define the privileged shareable image's entry
universal symbol, using the UNIVERSAL= option.

LINKING THE PRIVILEGED SHAREABLE IMAGE

The following conventions apply when you
privileged shareable image:

link

(that

point

The listings in Section 6.5 include the LINK command and linker
options file used to create the sample privileged shareable image.

6.2.1

Specifying Protection for the Image or Clusters

The VAX-11 Linker allows you to protect all or part of a privileged
shareable image from write access by code executing in user or
supervisor mode. The /PROTECT command qualifier causes all image
sections to be so protected. The PROTECT= option in a linker options
file permits you to specify protection for individual clusters, thus
allowing privileged shareable images to contain parts into which the
nonprivileged user can write.
The linker option takes the form PROTECT=YES or PROTECT=NO and
precedes the specifications for clusters that are to be protected or
unprotected, respectively. The following example shows the linker
options file entries to designate clusters A, B, and D as protected,
and cluster C as unprotected.
PROTECT=YES
CLUSTER=A,,,MODULE1,MODULE2
CLUSTER=B,,,MODULE3,MODULE4,MODULE5
PROTECT=NO
CLUSTER=C,,,MODULEn,MODULE7
PROTECT= YES
CLUSTER=D,,,MODULE8,MODULE9

PRIVILEGED SHAREABLE IMAGES

The VAX-11 Link~r Reference Manual discusses linker options files
explains each available option.

6.3

and

INSTALLING THE PRIVILEGED SHAREABLE IMAGE

To make a privileged shareable image usable by nonprivileged programs,
you must install it as a protected permanent global section. The
following procedure is recommended:
1.

Move the privileged shareable image to a protected directory,
such as SYS$SHARE.

Run the INSTALL utility, specifying the /PROTECT, /OPEN, and
/SHARED
qualifiers.
You
can
also
specify
the
/HEADER RESIDENT qualifier. The following entry could be
used to install the privileged shareable image presented in
Section 6.5 (the image name is USS):
$ RUN SYS$SYSTEM:INSTALL

INSTALL>SYS$SHARE:USS/PROTECT/OPEN/SHARED/HEADER_RES
The INSTALL utility
Manager's Guide.

6.4

discussed

the

VAX/VMS

System

USING THE PRIVILEGED SHAREABLE IMAGE

To the nonprivileged user of a privileged shareable image there is
difference between using it and using an ordinary shareable image.
use a privileged shareable image, the user must:

6.5

no
To

•

Call the privileged shareable image.

•

Link the privileged shareable image into the executable image
being created. Note:
If the shareable image was installed as
writeable, you cannot link it into an executable image.
You
must link an uninstalled copy of the writeable shareable image
into the executable image.

PROGRAM LISTINGS

The rest of this chapter contains listings of modules in a privileged
shareable image and of a module that calls the privileged shareable
image.

6-5

USSDISP .LIS

USER SYS DISP
Tabl; of-contents
( 1)
(1)
( 1)

( 1)
( 1)
( 1)
( l)
( 1)

108
177
214
262
318
371
395
427

Example of user system service dispatc 10-MAR-1980 15:48:30

VAX-11 Macro V02.42

Page

Declarations and Equates
Transfer Vector and Service Definitions
Change Mode Dispatcher Vector Block
Kernel Mode Dispatcher
Executive Mode Dispatcher
Get Time of Day Register Value
Set Page Fault Cluster Factor
Null Service

::0

<
H

C"1
Cs:J

USER SYS DISP
Vl.0

.J'\

I
~

Example of user system service dispatc 10-MAR-1980 15:48:30
10-MAR-1980 15:48:21
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000

1
2
3
4
5

.TITLE
.IDENT

USER SYS DISP /Vl.O/ -

VAX-11 Macro V02.42
Page
1
_DBB2: [HUSTVEDT.USS]USSDISP.MAR;23(1)

Example of user system service dispatcher

7
8
9
10
11

12
13
14
15

ln
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

This software is furnished under a license for use only ~n a single
computer system and may be copied only with the inclusion of the
above copyright notice. This software, or any other copies thereof,
may not be provided or otherwise made available to any other person
except for use on such system and to one who agree to these license
terms.
Title to
and
ownership of the software shall at all times
remain in DEC.
The information in the software is subject to change without notice
and should not
be construed as a commitment by Digital Equipment
Corporation.
DEC assumes no
responsibility for the use or
reliability of its
software on equipment which is not supplied by DEC.
; Facility: Example of User Written System Services
;++
; Abstract:
;
This module contains an example dispatcher for user written
;
system services along with several sample services.
It is a
;
template intend to serve as the starting point for implementing
;
a privileged shareable image containing your own services.
When used as
;
a template, the definitions and code for the sampl~ services
:
should be removed.

G1
Cs:J

tj
ti)

::c

>
::0
Cs:J

Cl
C"1
Cs:J
H

>
G1
Cs:J
ti)

0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000

32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

Overview:
User written system services are contained in privileged shareable
images that are linked into user program images in exactly the
same fashion as any shareable image. The creation and installation
of a privileged, shareable image is slightly different from that
of an ordinary shareable image. These differences are:
1. A vector defining the entry points and providing other
control information to the image activator. This vector
is a the lowest address in an image section with the VEC
attribute.
2. The shareable image is linked with the /PROTECT option
that marks all of the image sections so that they will
protected and given EXE~ mode ownership by the image
activator.
3. The shareable imaqe MUST be installed /SHARE /PROTECT
with the INSTALL utility in order for the image activator
to connect the privileged shareable image to the change mode
dispatchers.
A privileaed shareable imaqe implementing user written system services is
comprised,of the followinq major components:

.,,::c

<
H
t""
trl

G'l
trl

t='

O"I

::c

>
::c
>

-....]

trl

USER SYS DISP
Vl.0

- Example of user system service dispatc 10-MAR-1980 15:48:30
10-MAR-1980 15:48:21
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000

VAX-11 Macro V02.42
Page
2
_DBB2: [HUSTVEDT.USS]USSDISP.MAR;23{1)

°'
t""
trl
H

3
58
59
60
61
62

1. A transfer vector containing all of the entry points and
collecting them at the lowest virtual address in the shareable
image. This formalism enables revision of the shareable
image without necessitating the relinking of images that
use it.

fi3

64
65
66
67

2. A Privileged Library Vector in a PSECT with the VEC attribute
that describes the entry points for dispatching EXEC and
KERNEL mode services along with validation information.

fi8

3. A dispatcher for kernel mode services. This code will
be called by the VMS change mode dispatcher when it
fails to recognize a kernel mode service request.

69
70
71
72
73
74
75
7fi

4. A dispatcher for executive mode services. This code will
be called by the VMS change mode dispatcher when it fails
to recognize an executive mode service request.
5. Service routines to perform the various services.

>
G'l
trl

0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000

C'I

79
80
81
82
83
84
85
86

The first four components are contained in this template and are
most easily implemented in MACRO, while the service routines can
be implemented in BLISS or MACRO. Other languages may be usable
but are not recommended -- particularly if they require runtime
support routines or are extravagant in their use of stack or are
unable to generate PIC code.
This example is position-independent (PIC) and it is good practice
to implement shareable images this way whenever possible.

87
88

89
90
91
92
93
94
95
ge:;
97
98
99
100
101
102
103
104
105
106

Link Command File Example:
$

Command file to link User System Service example.

$ LINK/PROTECT/NOSYSSHR/SHARE=USS/MAP=USS/FU,LL SYS$INPUT/OPTIONS
Options file for the link of User System Service example.

.,,::c
H

SYS$SYSTEM:SYS.STB/SELECTIVE

Create a separate cluster for the transfer vector.

t""
CZl
G')

CLUSTER=TRANSTER VECTOR,,,SYS$DISK: []USSDISP
!

CZl

GSMATCH=LEQUAL,1,1

::c
CZl

to
t""
CZl
H

USER SYS DISP
Vl.0

- Example of user system service dispatc 10-MAR-1980 15:48:30
Declarations and Equates
10-MAR-1980 15:48:21
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000

108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

.SBTTL

VAX-11 Macro V02.42
Page
3
_DBB2: [HUSTVEDT.USS]USSDISP.MAR;23(1)

Declarations and Equates

Include Files
.LIBRARY "SYS$LIBRARY:LIB.MLB"

Macro library for system structure
definitions

Macro Definitions
DEFINE SERV1CE - A macro to make the appropriate entries in several
different PSECTs required to define an EXEC or KERNEL
mode service. These include the transfer vector,
the case table for dispatching, and a table containing
the number of required arguments.
DEFINE SERVICE Name,Number_of_Arguments,Mode

>
G')
CZl
Ul

I
l.D

00000000

0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000

125
126
.MACRO DEFINE SERVICE,NAME,NARG=O,MODE=KERNEL
127
.PSECT $$$TRANSFER VECTOR,PAGE,NOWRT,EXE,PIC
128
.ALIGN QUAD
; Align entry points for speed and style
129
.TRANSFER
NAME
; Define name as universal symbol for entry
130
.MASK
NAME
; Use entry mask defined in main routine
131
.IF
IDN MODE,KERNEL
132
CHMK
#<KCODE BASE+KERNEL COUNTER> ; Chanqe to kernel mode and execute
RET
; Return
133
134
KERNEL_COUNTER=KERNEL_COUNTER+l ; Advance counter
135
136
.PSECT KERNEL NARG,BYTE,NOWRT,EXE,PIC
137
.BYTE
NARG ; Define number of required arguments
138
139
.PSECT USER KERNEL DISPl,BYTE,NOWRT,EXE,PIC
140
.WORD
2+NAME-KCASE BASE
; Make entry in kernel mode CASE table
141
142
.IFF
CHME
#<ECODE BASE+EXEC COUNTER> ; Change to executive mode and execute
143
RET
; Return
144
145
EXEC COUNTER=EXEC COUNTER+l
; Advance counter
14n
147
.PSECT EXEC NARG,BYTE,NOWRT,EXE,PIC
148
.BYTE
NARG; Define number of required arguments
149
150
.PSECT USER EXEC DISPl,BYTE,NOWRT,EXE,PIC
151
.WORD
2+NAME-ECASE_BASE
; Make entry in exec mode CASE table
152
.ENDC
153
.ENDM
DEFINE SERVICE
154
155
Equated Symbols
151)
157
Define process header offsets
158
SPHDDEF
159
$PLVDEF
Define PLV offsets and values
160
SPRDEF
Define processor register numbers
161
lfi2
Initialize counters for change mode dispatching codes
163
164 KERNEL COUNTER=O
; Kernel code counter

.,,::c

1-1

C'"1
tz:I

Cl
tz:I

t:l

::c

>
::c
tz:I
>
O::I
C'"1
tz:I

1-1

Cl
tz:I

USER SYS DISP
Vl.0-

- Example of user system service dispatc 10-MAR-1980 15:48:30
Declarations and Equates
10-MAR-1980 15:48:21
00000000

0000
0000
0000
0000
0000
00000000
0000
0000
00000000
0000
0000

USER SYS DISP
Vl .O-

lfi 5 EXEC COUNTER=O

VAX-li Macro V02.42
Page
4
_DBB2: [HUSTVEDT.USS]USSDISP.MAR;23(1)

; Exec code counter

Hin
Hi7

168

Own Storage

lfi9

170
.PSECT
171 KF.RNEL NARG:
172
173
.PSECT
174 EXEC NARG:
175

KERNEL NARG,BYTE,NOWRT,EXE,PIC
; Base of
;
number
EXEC NARG,RYTF.,NOWRT,EXE,PIC
: Base of
numher

- Example of user system service dispatc 10-MAR-1980 15:48:30
Transfer Vector and Service Definitions 10-MAR-1980 1S:48:21

byte table containing the
of required arguments.
byte table containing the
of required arguments.

VAX-11 Macro V02.42
Page
5
_DBB2: [HUSTVEDT.USS]USSDISP.MAR;23(1)

"'O

::c

1-f

O"I

I
1--'

FFFFFCOO
FFFFFCOO

0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0002
0002
0004
0004
0002
0002
0002
0002
0002
0002
0002
0002
0002
0002
0002

177
.SPTTL Trcnsfer Vector and Service Definitions
178 ;++
The use of transfer vectors to effect entry to the user written system services
179
enables some updatinq of the shareable image containing them without necessitating
180
a re-link of all proqrams that call them.
The PSECT containinng the transfer
181
vector will be positioned at the lowest virtual address in the shareable image
182
and so lonn as the transfer vector is not re-ordered, programs linked with
183
one version of the shareable image will continue to work with the next.
184
18 5
186
Thus as additional services are added to a privileged shareable image, their
definitions should be added to the end of the following list to ensure that
187
programs usinq previous versions of it will not need to be re-linked.
188
To completely avoid relinking existing programs the size of the privileged
189
shareable image must not change so some padding will be required to provide
190
191
the opportunity for future growth.
192
193
DEFINE SERVICE USER_GET_TODR,l,KERNEL ; Service to get value of time
194
of day register
;
DEFINE SERVICE USER_SET_PFC,2,KERNEL
195
; Service to set value of process
196
default pagefault cluster
;
197
DEFINE SERVICE USER_NULL,O,EXEC
: Null exec service
198
199
200
The base values used to generate the dispatching codes should be negative for
201
user services and must be chosen to avoid overlap with any other privileged
202
shareable images that will be used concurrently.
Their definition is
203
deferred to this point in the assembly to cause their use in the preceding
204
macro calls to be forward references that guarantee the size of the change
205
mode instructions to be four bytes. This satisfies an assumption that is
206
made by for services that have to wait and be retried. The PC for retrying
207
the change mode instruction that invokes the service is assumed to be 4 bytes
208
less than that saved in the change mode exception frame.
Of course, the

0002
0002
0002
0002

209
particular service routine determines whether this is possible.
210
Base CHMK code value for these services
211 KCODE BASE=-1024
Base CHME code value for these services
212 ECODE-BASE=-1024

1-f

t""

tZl
Cl
tZl

0
tJ)

:c
>
::c
tZl

°'t""
tZl

1-f
~

G')

tZl
tJ)

USER SYS DISP
Vl.0-

O'\

I
I-'
I-'

- Example of user system service dispatc 10-MAR-1980 15:48:30
Change Mode Dispatcher Vector Block
10-MAR-1980 15:48:21
0002
0002
0002
0002
0002
0002
0002
0002
0002
0002
0002
0002
0002
0002
0002
0002
0002
0002
0002
0002
000.2
0002
0002
0002
0002
0002
0002
0002
0002
0002
0002
0002
0002
0002
0002
0002
0002
00000000
0000
00000001
0000

214
215
2Hi
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253

00000000'
00000005'
00000001'
00000000
00000000
00000000
00000000

254
255
256
257
258
259
260

0004
0008

oooc
0010
0014
0018
OOlC

;++

.SBTTL

VAX-11 Macro V02.42
Page
6
_DBB2: [HUSTVEDT.USS]USSDISP.MAR;23(1)

Change Mode Dispatcher Vector Block

This vector is used by the image activator to connect the privileged shareable
image to the VMS change mode dispatcher.
The offsets in the vector are selfrelative to enable the construction of position independent images.
The system
version nuMber will be used by the image activator to verify that this shareable
image was linked with the symbol table for the current system.
Change Mode Vector Format

+------------------------------------------+
Vector Type Code
(PLV$C TYP CMOD)

+-------------------=---=------------------+

PLV$L TYPE

System Version Number
(SYSSK VERSION)

PLV$L_VERSION

.,,:::c

Kernel Mode Dispatcher Offset

PLV$L KERNEL

<
H

PLVSL_EXEC

+-------------------=----------------------+
+------------------------------------------+
Exec Mode Entry Offset

L'
tr.I

tr.I

+------------------------------------------+
Reserved

CJ)

::c

>
:::c

+------------------------------------------+
Reserved

tr.I

+------------------------------------------+
RMS Dispatcher Offset

+------------------------------------------+
Address Check

PLV$L_RMS
PLV$L_CHECK

+------------------------------------------+

°'
L'

tr.I
H

>
G)
tr.I
CJ)

.PSECT

USER_SERVICES,PAGE,VEC,PIC,NOWRT,EXE

.LONG

PLV$C TYP CMOD

.LONG
.LONG
.LONG
.LONG
.LONG
.LONG
.LONG

SYS$K VERSION
KERNEL DISPATCH-.
EXEC DISPATCH-.
0
0
0

Set type of vector to change mode
dispatcher
Identify system version
Offset to kernel mode dispatcher
Offset to executive mode dispatcher
Reserved.
Reserved.
No RMS dispatcher
Address check - PIC image

USER SYS DISP
Vl.0-

- Example of user system service dispatc 10-MAR-1980 15:48:30
Change Mode Dispatcher
10-MAR-1980 15:48:21

0000'8F

OOOO'BF

O"\

I
I-'

0400

F8
51
F3

51
OOOO'CF41
00000004 9F41
0400'CF40

fiC
Dl
50

FCOO SF

0020
0020
0020
0020
0020
0020
0020
0020
0020
0020
0020
0020
0020
0020
0020
0020
0020
0020
00000000
0000
3C 0000
04
0005
0006
3C 0006
04
0008
05
oooc
OOOD
OOOD
9E OOOD
19
0012
Bl
0014
lE
0017
0019
0019
0019
0019
0019
9A 0019
DE OOlF
0027
91
002D
lF 0033
AF 0035
0037
0037
0037
0038
0038
003B
003R
003B
003B
00000000
05 0000
0001

21i2
263
264
2'>5
2fif1
267
268
269
270
271
272
273
274
275
27Fi
277
278
279
280
281
282
28 3
284
285
28f'
287
288
289
290
291
292
293
294
295
2%
297
298
299
300
301
302
303
304
305
30"
307
308
309
310
311
312
313
314
315
311)

VAX-11 Macro V02.42
Page
7
_DBB2: [HUSTVEDT.USS]USSDISP.MAR;23(1)

.SRTTL Kernel Mode Dispatcher
;++
Input Parameters:
(SP)

- Return

- Chnnne mode argument value.

- Current PCB Address. <Therefore R4 must be specified in all
register save masks for kernel routines.)

- Argument pointer existing when the change
mode instruction was executed.

.PSECT
KACCVIO:
MOVZWL
RP.T
KINSFARG:
MOVZWL
RET
KNOTME: RSB

~ddress

if bad chanqe mode value

Address of minimal call frame to exit
the change mode dispatcher and return to
the original mode.
USER KERNEL DISPO,BYTE,NOWRT,EXE,PIC
; Kernel access violation
#SSS ACCVIO,RO
; Set access violation status code
and return
Kernel insufficient arguments.
#SSS INSFARG,RO
; Set status code and
return
RSB to forward request

KERNEL DISPATCH::
- MOVAB
WA-KCODE BASE(RO) ,Rl
BLSS
KNOTME CMPW
Rl,#KERNEL COUNTER
BGEQU
KNOTME
-

Entry to dispatcher
Normalize dispatch code value
Branch if code value too low
Check high limit
Branch if out of range

"tJ

::0

1-t

C1l

0
(/)

::0
C1l

°'rC1l
1-t

The oispatch code has now been verified as being handled by this dispatcher,
now the argument list will be prohed and the required number of arguments
verified.

>
C)
C1l
(/)

MOVZRL
MOVAL
T F!\!ORD
CMPB
BLSSU
CASEW

KCASE RASE:

WAKER!\!EL NARG[Rll,Rl
; Get required argument count
0#4[Rl],Rl
; Compute hyte count including arg count
Rl, (AP) ,KACCVIO
; Branch if arglist not readable
(AP) ,WA<KERNEL NARG-KCODE BASE>[RO] ; Check for required number
KINSFARG
;- of arguments
RO,; Case on change mode
argument value
#KCODE BASE,Base value
#<KERNEL COUNTER-1>
Limit value (number of entries)
Case table base address for DEFINE SERVICE

Case table entries are made in the PSECT USER KERNEL DISPl by
invocations of the DEFINE SERVICE macro.
The-three PSECTS,
USER_KERNEL_DISP0,1,2 wilI be abutted in lexical order at link-time.
.PSECT
RSB

USER KERNEL DISP2,RYTE,NOWRT,EXE,PIC
; Return to reject out of
; range value

USER SYS DISP'
Vl.0-

- Example of user system service dispatc 10-MAR-1980 15:48:30
Executive Mode Dispatcher
10-MAR-1980 15:48:21

50
50

0000'8F
0000'8F

I'\

....

0400

F8
51
F3

51
OOOO'CF41
00000004 9F41
0400'CF40

6C
Dl
50

FCOO 8F

0001
0001
0001
0001
0001
0001
0001
0001
0001
0001
0001
0001
0001
0001
0001
00000000
0000
3C 0000
04 0005
0006
3C 0006
04 0008
05 oooc
OOOD
OOOD
9E OOOD
19 0012
Bl 0014
lE 0017
0019
0019
0019
0019
0019
9A 0019
DE OOlF
0027
91 002D
lF 0033
AF 0035
0037
0037
0037
0038
0038
0038
0038
0038
003B
00000000
05 0000
0001

318
319
320
321
322
323
324
325
32fi
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
34fi
347
348
349
350
351
352
353
354
355
356
357
358
359
360
3fil
362
363
364
365
366
367
368
369

VAX-11 Macro V02.42
Page
8
_DBB2: [HUSTVEDT.USS]USSDISP.MAR;23(1)

.SBTTL Executive Mode Dispatcher
;++
Input Parameters:
(SP) - Return address if bad change mode value
RO

- Change mode argument value.

- Argument pointer existing when the change
mode instruction was executed.

- Address of minimal call frame to exit
the change mode dispatcher and return to
the original mode.

.PSECT
EACCVIO:
MOVZWL
RET
EINSFARG:
MOVZWL
RET
ENOTME: RSB
EXEC DISPATCH::
MOVAB
BLSS
CMPW
BGEQU

USER EXEC DISPO,BYTE,NOWRT,EXE,PIC
; Exec access violation
#SS$ ACCVIO,RO
; Set access violation status code
and return
Exec insufficient arguments.
#SS$ INSFARG,RO
; Set status code and
return
RSB to forward request
WA-ECODE BASE(RO) ,Rl
ENOTME Rl,#EXEC COUNTER
ENOTME -

Entry to dispatcher
Normalize dispatch code value
Branch if code value too low
Check high limit
Branch if out of range

The dispatch code has now been verified as being handled by this dispatcher,
now the argument list will be probed and the required number of arguments
verified.
MOVZBL
MOVAL
IFNORD
CMPB
BLSSU
CASEW

ECASE BASE:

WAEXEC NARG[Rl],Rl
; Get required argument count
@#4[Rl],Rl
; Compute byte count including arg count
Rl, (AP) ,EACCVIO
; Branch if arglist not readable
(AP),WA<EXEC NARG-ECODE BASE>[RO] ; Check for required number
EINSFARG
-; of arguments
RO, ; Case on change mode.
argument value
#ECODE BASE,Base value
#<EXEC-COUNTER-1>
Limit value (number of entries)
Case table base address for DEFINE SERVICE

Case table entries are made in the PSECT USER EXEC DISPl by
invocations of the DEFINE SERVICE macro. The-three PSECTS,
USER_EXEC_DISP0,1,2 will be abutted in lexical order at link-time.
.PSECT
RSB

USER EXEC DISP2,BYTE,NOWRT,EXE,PIC
; Return to reject out of
; range value

.,,
::0
1-4

1-4

tZl

G')

tZl

0
ti)

>
::0
tZl

°'r

tZl

1-t

>
G')
tZl

ti)

USER SYS DISP
Vl .O-

- Example of user system service dispatc 10-MAR-1980 15:48:30
Get Time of Day Register Value
10-MAR-1980 15:48:21

51
50

fil
18
00000000'8F
50

O"\

I
f-'

04 AC

0000'8F

USER SYS DISP
Vl.0-

OOlC
DO
DB
DO
04
3C
04

0001
0001
0001
0001
0001
0001
0001
0001
0001
0001
0001
0001
0001
0001
0001
0003
0007
OOOD
0010
0017
0018
0018
OOlD

VAX-11 Macro V02.42
Page
9
_DBB2: [HUSTVEDT.USS]USSDISP.MAR;23(1)

371
.SBTTL Get Time of Day Re9ister Value
372 ;++
373
Functional Description:
374
This routine reads the content of the hardware time of day
375
processor register and stores the resulting value at the
376
specified address.
377
378
Input Parameters:
379
04(AP) - Address to return time of day value
R4 - Address of current PCB
380
381
38 2
Output Parameters:
RO - Completion Status Code
383
384
.ENTRY USER GET TODR,AM<R2,R3,R4>
385
MOVL
4(AP),Rl; Get address to store time of day register
386
I FNO\A1RT #4,(Rl),10$
387
; Branch if not writable
MFPR
#PR$ TOOR, (Rl)
; Return current time of day register
388
#SSS-NORMAL,RO
; Set normal completion status
389
MOVL
and return
RET
390
391
MOVZWL #SS$_ACCVIO,RO
392 10$:
Indicate access viol~tion
393
RET

- Example of user system service dispatc 10-MAR-1980 15:48:30
Set Page Fault Cluster Factor
10-MAR-1980 15:48:21

VAX-11 Macro V02.42
Page
10
_DBB2:[HUSTVEDT.USS]USSDISP.MAR;23(1)

.i::.

00000000'9F
51
08 AC
QA
61
7F SF

34 A5
04 AC
04
7F 8F
50
34 A5
50
00000000'8F

0030
DO
DO
13

9A
91
lB
90
90
DO
04

OOlE
OOlE
OOlE
OOlE
OOlE
OOlE
OOlE
OOlE
OOlE
OOlE
OOlE
OOlE
OOlE
OOlE
OOlE
OOlE
0020
0027
002B
002D
0033
0037
003C
003E
0042
0046
004D

395
.SBTTL Set Page Fault Cluster Factor
396 ;++
397
Functional Description:
This routine sets the page fault cluster to the specified value
398
399
and returns the previous value.
400
401
Input Parameters:
402
04(AP) - New value for Page Fault Cluster factor
403
08(AP) - Address to return previous value
404
(0 means none)
405
R4 - PCB address of current process
406
407
Output Parameters:
408
RO - Completion Status code
409
410
.ENTRY USER SET PFC,AM<R4,R5>
@#CTLSGL-PHD,R5
411
MOVL
Get address of process header
8(AP) ,Rl412
MOVL
Get address to store previous value
10$
413
BEQL
Branch if none
414
IFNOWRT #4, (Rl) ,30$
Branch if not writable
415
MOVZBL PHD$B DFPFC(R5), (Rl)
Return current value
416 10$:
CMPB
4 (AP)-;-#127
Check for legal value
417
20$
BLEQU
Branch if legal
418
MOVB
#127 ,RO
Set to maximum value
419 20$:
MOVB
RO,PHD$B DFPFC(R5)
Set new value into PHD
420
MOVL
#SSS_NORMAL,RO
Set normal completion status
4 21
RET
and return

"'C

:xi

1-4

t'""
[':l

Cl
[':l

en
:c

>
:xi
[':l

°'t'""
[':l

1-4

>
Cl
[':l

USER SYS DISP
Vl .O-

0000'8F

3C
04

004E
004E
0053
0054

422
423 30$:
424
425

MOVZWL
RET

#SSS ACCVIO,RO
-

Indicate access violation

Example of user system service dispatc 10-MAR-1980 15:48:30
Null Service
10-MAR-1980 15:48:21

0000
0000 I BF·
3C
04

0054
0054
0054
0054
0054
0054
0054
0054
0054
0054
0054
0050
0058
005C
005C

427
428
429
430
431
432
433
434
435
43n
437
438
439
440
441

VAX-11 Macro V02.42
Page 11
_DBB2: [HUSTVEDT.USS]USSDISP.MAR;23(1)

.SBTTL Null Service
;++
Functional Description:

;
;
;
;
;

Input Parameters:
Output Parameters:

,
.ENTRY
MOVZWL
RET
.END

USER NULL, AM<>
#SSS=NORMAL,RO

Entry definition
Set normal completion status
and return

"tJ

::c
H

<
H
1:-1

CZl

G')

CZl

0
O"\

I
1--'
V1

(fl

::c

>
::c
CZl
>

°'
1:-1
CZl

>
G')
tZl

(fl

USER SYS DISP
symbol table

O"'I

I
t-'
O"'I

BIT •••
= 00000000
CTL$GL PHO
x
********
EACCVIO
00000000 R
ECASE BASE
0000003B R
ECODE-BASE
= FFFFFCOO
EINSFARG
00000006 R
ENOTME
OOOOOOOC R
EXEC COUNTER
= 00000001
EXEC-DISPATCH
00000000 RG
EXEC-NARG
00000000 R
GBL .7.
= 00000000
KACCVIO
00000000 R
KCASE BASE
0000003B R
KCODE-BASE
= FFFFFCOO
KERNEL COUNTER = 00000002
KERNEL-DISPATCH 00000000 RG
KERNE'L-NARG
00000000 R
KINSFARG
00000006 R
KNOTME
OOOOOOOC R
PHD$B ASTLVL
OOOOOOCB
PHD$B-CPUMOOE
0000005C
PHD$B-OFPFC
00000034
PHD$B-PAGFI L
OOOOOOlF
PHD$B-PGTBP FC
00000035
PHD$C-LENGTH
00000180
PHD$C-PHDPAGCTX= 00000008
PHD$K-LENGTH
00000180
PHD$L-BIOCNT
00000054
PHD$L-CPULIM
00000058
PHD$L-CPUTIM
00000038
PHD$L-DIOCNT
00000050
PHD$L-ESP
00000078
PHD$L-FREPOVA
00000028
PHD$L-FREP1VA
00000030
PHD$L-FREPTECNT 0000002C
PHD$L-IMGCNT
OOOOOOF4
PHD$L-KSP
00000074
PHD$L-POBR
OOOOOOC4
PHD$L-P0LRASTL
OOOOOOC8
PHD$L-PlBR
oooooocc
PHD$L-PlLR
00000000
PHD$L-PAGEFLTS
00000048
PHD$L-PAGFI L
OOOOOOlC
PHD$L-PC
OOOOOOBC
PHD$L-PCB
00000074
PHO$L-PFLREF
OOOOOOFC
PHD$L-PFLTRATE
OOOOOOF8
PHD$L-PGFLTIO
0000004C
PHD$L-PSL
ooooooco
PHD$L-PSTBASOFF 00000020
PHD$L-PTWSLELCK 00000060
PHD$L-PTWSLEVAL 000000fi4
PHD$L-RO
00000084
PHD$L-Rl
00000088
PHD$L-Rl0
OOOOOOAC
PHD$L-Rll
OOOOOOBO
OOOOOOB4
PHD$L=Rl2

- Example of user system service dispatc 10-MAR-1980 15:48:30
10-MAR-1980 15:48:21

oc
OB
OB
OB
OB
OB
04
09
09
09
03
09
09

PHD$L Rl3
OOOOOOB8
PHD$L-R2
0000008C
PHD$L-R3
00000090
PHD$L-R4
00000094
PHD$L-R5
00000098
PHD$L-Rfi
0000009C
PHD$L-R7
OOOOOOAO
PHD$L-R8
OOOOOOA4
PHD$L-R9
OOOOOOA8
PHD$L-REFERFLT
00000014
PHD$L-RESLSTH
OOOOOOFO
PHDSL-SPARE
0000013C
PHD$L-SSP
0000007C
PHD$L-TIMREF
00000100
PHD$L-USP
00000080
PHD$L-WSL
00000180
PHD$M-DALCSTX = 00000002
PHD$M-PFMFLG
= 00000001
PHD$M-WSPEAKCHK= 00000004
PHD$Q-AUTHPRIV
OOOOOOOC
PHO$Q-IMAGPRIV
OOOOOOE4
PHO$Q-PRIVMSK
00000000
PHD$S-ASTLVL
= 00000008
PHO$S-POLR
= 00000018
PHD$V-ASTLVL
= 00000018
PHOSV-OALCSTX = 00000001
PHD$V-POLR
= 00000000
PHD$V-PFMFLG
= 00000000
PHD$V-WSPEAKCHK= 00000002
PHO$W-ASTLM
00000040
PHO$W-BAK
00000044
PHD$W-CWSLX
OOOOOOOA
PHD$W-DFWSCNT
OOOOOOlA
PHD$W-EMPTPG
00000004
PHO$W-EXTDYNWS
00000072
PHO$W-FLAGS
00000030
PHO$W-PHVINOEX
00000042
PHO$W-PRCLM
0000003E
PHO$W-PST
00000020
PHD$W-PSTBASMAX 00000046
PHO$W-PSTFREE
00000026
PHO$W-PSTLAST
00000024
PHO$W-PTCNTACT
OOOOOOnC
PHD$W-PTCNTLCK
00000068
PHO$W-PTCNTMAX
OOOOOOnE
PHD$W-PTCNTVAL
0000006A
PHO$W-QUANT
0000003C
PHD$W-REQPGCNT
00000008
PHD$W-RESPGCNT
OOOOOODfi
PHD$W-WSAUTH
OOOOOOOA
PHO$W-WSDYN
OOOOOOOE
PHO$W-WSFLUID
00000070
PHO$W-WSLAST
00000012
PHD$W-WSLIST
00000008
PHO$W-WSLOCK
oooooooc
PHOSW-WSLX
00000046
PHO$W-WSNEXT
00000010

VAX-11 Macro V02.42

Page

- DBB2: [HUSTVEDT.USS]USSDISP.MAR;23(1)

PHD$W WSQUOTA
00000018
PLV$C-TYP CMOD = 00000001
PLV$C-TYP-MSG = 00000002
PLV$L-CHECK
OOOOOOlC
PLV$L-EXEC
oooooooc
PLV$L-KERNEL
00000008
PLV$L-MSGDSP
00000008
PLV$L-RMS
00000018
PLV$L-TYPE
00000000
PLV$L-VERSION
00000004
PR$S SID ECO
= 00000008
PR$S-SID-PL
= 00000004
PR$S-SID-SN
= oooooooc
PR$S-SID-TYPE = 00000008
PR$V-SID-ECO
= 00000010
PR$V-SID-PL
= oooooooc
PR$V-SID-SN
= 00000000
PR$V-SID-TYPE = 00000018
PR$ ACCR= 00000029
PR$-ACCS
= 00000028
PR$-ASTLVL
= 00000013
PR$-CADR
= 00000025
PR$-CAER
= 00000027
PR$-CM IE RR
= 00000017
PR$-CS RO
= 00000010
PR$-CSRS
= OOOOOOlC
PR$-CSTO
= OOOOOOlF
PR$-CSTS
= OOOOOOlE
PR$-ESP
= 00000001
PRS-ICCS
= 00000018
PR$-ICR
= OOOOOOlA
PRS-IPL
= 00000012
PRS-ISP
= 00000004
PR$-KSP
= 00000000
PR$-MAPEN
= 00000038
PRS-MCESR
= 00000026
PR$-NICR
= 00000019
PR$-POBR
= 00000008
PRS-POLR
= 00000009
PRS-PlBR
= OOOOOOOA
PR$-PlLR
= OOOOOOOB
PRS-PCBB
= 00000010
PRS-PME
= 00000030
PR$-RXCS
= 00000020
PR$-RXOB
= 00000021
PR$-SBIER
= 00000034
PRS-SBIFS
= 00000030
PR$-SBIMT
= 00000033
PRS-SBIQC
= 00000036
PRS-SBIS
= 00000031
PR$-SBISC
= 00000032
PRS-SBITA
= 00000035
PR$-SBR
= oooooooc
PR$-SCBB
= 00000011
PR$-SID
= 0000003E
PR$-SID TYP750 = 00000002
PRS-SID-TYP780 = 00000001

'ti

....::c
....<
r

CZ]
G')

CZ]

0
CJ)

::c

>
::c

CZ]

°'r
CZ]
H

G')

CZ]
CJ)

!)SER SYS DISP
symbol table
PR$ SID TYP7ZZ
PR$-SID-TYPMAX
PR$-SIRR
PR$-SISR
PR$-SLR
PR$-SSP
PR$-TBDR
PR$-TBIA
PR$-TBIS
PR$-TODR
PR$-TXCS
PR$-TXDB
PR$-UBRESET
PR$-USP
PR$-WCSA
PR$-WCSD
SS$-ACCVIO
SS$-INSFARG
SS$-NORMAL
SYS"S'K VERSION
USER GET TODR
USER-NULL
USER-SET PFC

- Example of user system service dispatc 10-MAR-1980 15:48:30
10-MAR-1980 15:48:21
00000003
00000003
00000014
00000015
OOOOOOOD
00000002
00000024
0000003~

0000003,\
OOOOOOlB
00000022
00000023
00000037
00000003
0000002C
0000002D

x
x
x
x

********
********
********
********
00000001 RG
00000054 RG
OOOOOOlE RG

"':::0

09
09

<
H

L1
Cz:I

08
QC

oc
oc

Cz:I

()\

I
I-'
-i

VAX-11 Macro V02.42
Page
13
_DBB2: [HUSTVEDT.USS]USSDISP.MAR;23{1)

PSECT name

---------ABS
BLANK
$ABS$
KERNEL NARG
EXEC NARG
$$$TRANSFER VECTOR
USER KERNEL-DISPl
USER-EXEC DISPl
USER-SERVICES
USER-KERNEL DISPO
USER-KERNEL-DISP2
USER-EXEC DISPO
USER-EXEC-DISP2

Phase
Initialization
Command processing
Pass 1
Symbol table sort
Pass 2
Symbol table output
Psect synopsis output

Allocation

---------{
00000000
00000000
00000184
00000002
00000001
00000017
00000004
00000002
00000020
00000038
00000001
0000003B
0000005C

Page faults

----------8
13
306
7
200
27
5

{
{
(
(
(

{
(
(
(
(
(
(

+----------------+
! Psect synopsis !
+----------------+
PSECT No. Attributes
--------- ----------

0.)
0.)
388.)
2.)
1.)
23.)
4.)
2.)
32.)
59.)
1.)
59.)
92.)

00
01
02
03
04
05
06
07
08
09
OA
OB

0.)
1.)
2.)
3.)
4.)
5.)
(
fi.)
(
7.)
(
8.)
(
9.)
( 10.)
( 11.)
( 12.)

{
(
{
(
(
(

NOP IC
NOP IC
NOP IC
PIC
PIC
PIC
PIC
PIC
PIC
PIC
PIC
PIC
PIC

+------------------------+
! Performance indicators !
+------------------------+
CPU Time
Elapsed Time
-----------------00:00:00.04
00:00:00.18
00:00:06.fi4
00:00:00.25
00:00:01.49
00:00:00.12
00:00:00.011

00:00:00.18
00:00:00.4fi
00 00 09.97
00 00 00.41
00 00 02.00
00 00 00.15
oo oo 00.011

USR
USR
USR
USR
USR
USR
USR
USR
USR
USR
USR
USR
USR

(/)

>
:::0
Cz:I

CON
CON
CON
CON
CON
CON
CON
CON
CON
CON
CON
CON
CON

ABS
REL
ABS
REL
REL
REL
REL
REL
REL
REL
REL
REL
REL

LCL
LCL
LCL
LCL
LCL
LCL
LCL
LCL
LCL
LCL
LCL
LCL
LCL

NOSHR NOEXE NORD
RD
NOSHR
EXE
RD
NOSHR
EXE
NOSHR
EXE
RD
NOSHR
EXE
RD
NOSHR
EXE
RD
N03HR
EXE
RD
NOSHR
EXE
RD
NOSHR
EXE
RD
EXE
RD
NOSHR
RD
NOSHR
EXE
NOSHR
RD
EXE
RD
NOSHR
EXE

NOWRT NOVEC
WRT NOVEC
WRT NOVEC
NOWRT NOVEC
NOWRT NOVEC
NOWRT NOVEC
NOWRT NOVEC
NOWRT NOVEC
NOWRT
VEC
NOWRT NOVEC
NOWRT NOVEC
NOWRT NOVEC
NOWRT NOVEC

BYTE
BYTE
BYTE
BYTE
BYTE
PAGE
BYTE
BYTE
PAGE
BYTE
BYTE
BYTE
BYTE

>
to
L1
Cz:I
H

>
Cl
Cz:I
(/)

USER SYS DISP
VAX-Tl Macro Run Statistics

- Example of user system service dispatc 10-MAR-1980 15:48:30
10-MAR-1980 15:48:21

Cross-reference output
Assembler run totals

567

00:00:00.00
00:00:08.78

VAX-11 Macro V02.42
Page 14
_DBB2: [HUSTVEDT.USS]USSDISP.MAR;23{1)

00:00:00.00
00:00:13.24

The working set limit was 293 pages.
27596 bytes {54 pages) of virtual memory were used to buffer the intermediate code.
There were 10 pages of symbol table space allocated to hold 194 non-local and 4 local symbols.
441 source lines were read in Pass 1, producing 41 object records in Pass 2.
17 pages of virtual memory were used to define 15 macros.

+--------------------------+
! Macro library statistics !
+--------------------------+
Macros defined

Macro library name
DRAS:[SYSLIB]LIB.MLB;l
-DRAS:(SYSLIB]STARLET.MLB;l
TOTALS {all libraries)

14
0

.,,:::c

427 GETS were required to define 14 macros.

<
H

There were no errors, warnings or information messages.

USSDISP/LIS

t""
tz:I
tz:I

O'\

I
I-'
00

Cll

::c

>
:::c

tz:I

°'
t""
tz:I

Cl
tz:I
CJ)

USSTEST.LIS
US ST EST
Table of contents
(1)

10-MAR-1980 15:12:23

VAX-11 Macro V02.42

10-MAR-1980 15:12:23
10-MAR-1980 15:02:5fi

VAX-11 Macro V02.42
Page
1
_DBB2:(HUSTVEDT.USS]USSTEST.MAR;5 (1)

Page

Sample invocation of user written system

US ST EST
Vl.0

°'I
!--'
l..O

00000000

0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000
0000

1
2
3
4
5

.TITLE
.!DENT

USSTEST
/Vl.O/

7
8
9
10
11

This software is furnished under a license for use only on a single
computer system and may be copied only with the inclusion of the
above copyright notice. This software, or any other copies thereof,
may not be provided or otherwise made available to any other person
except for use on such system and to one who agree to these license
terms. Title to and ownership of the software shall at all times
remain in DEC.

12
13
14
15
The information in the software is subject to change without notice
16
and should not be construed as a commitment by Digital Equipment
17
Corporation.
18
19
DEC assumes no responsibility for the use or reliability of its
20
software on equipment which is not supplied by DEC.
21
22
23
Facility: Example of User Written System Services
24 ;++
25
Abstract:
2fi
This module contains an example of a program that invokes a sample
27
user-written system service that is contained in a privileged
28
shareable image. The module USSDISP contains the sample service
29
and associated dispatching code being invoked by this simple test
30
program.
31
32
Link Command File:
33
34
$
35
$ !
Link Command file for USSTEST
36
s !
37
$ LINK USSTEST/MAP/FULL,SYS$INPUT/OPTIONS
38
39
Options file for USSTEST
40
USS.EXE/SHARE
41
42
43 BUF:
.LONG
Location to receive TOOR contents
0

.,,

"<
H
H

t"'
tZl

G')

tZl

0
CJ)

::c

.,,">
tZl

t"'
tZl
H

G')

tZl
CJ)

USSTEST

10-MAR-1980 15:12:23
Sample invocation of user written system 10-MAR-1980 15:02:56

Vl.O

F7 AF

0000
9F

OOOOOOOO'EF

0004
0004
0004
0004
0004
0004
0004
0004
0004
0004
0004
0004
0004
0004
0004
0006
0009
0009
0010
0010
0011
0011

45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

.SBTTL

;++

VAX-11 Macro V02.42
Page
2
_DBB2: [HUSTVEDT.USS]USSTEST.MAR;5 (1)

Sample invocation of user written system service

Functional Description:
This routine shows an invocation of the example user system service that
will read the contents of the time of day register.
As can be seen by this example, the privileged nature of the code used
to implement the reading of the TODR is not visible to the caller.
For coding convenience and better maintainability, the code can be
generated by macros patterned on the standard VMS system service macros.

.ENTRY
PUSHAB

BUF

CALLS

#1,USER_GET TOOR

USSTEST,~M<>

Entry mask and definition
Build argument list - set address for
return value
Invoke routine in privileged sh. image
to get value from Time-of-day register

"'O

::0
H

RET

.END

tzl

USSTEST

tzl

l:j

O"I

US ST EST
Symbol table

10-MAR-1980 15:12:23
10-MAR-1980 15:02:56

VAX-11 Macro V02.42
Page
_DBB2:[HUSTVEDT.USS]USSTEST.MAR;5

!'-.)

BUF
USER GET TODR
USSTEST -

00000000 R

********

00000004 RG

PSECT name

01
01
01

3
(1)

(/)

::c

>
::0

tzl

°'
r

+----------------+
! Psect synopsis !
+----------------+

Allocation

PSECT No.

tzl

Attributes

ABS
• BLANK •

Phase
Initialization
Command processing
Pass l
Symbol table sort
Pass 2
Symbol table output
Psect synopsis output
Cross-reference output
Assembler run totals

00000000
00000011

Page faults
9

14
33
0

35
0
2
0

O.)
17.)

00
01

0.)
1.)

NOPIC
NOP IC

+------------------------+
! Performance indicators !
+------------------------+

CPU Time

Elapsed Time

00:00:00.05
00:00:00.18
00:00:00.23
00:00:00.00
00:00:00.14
00:00:00.01
00:00:00.02
00:00:00.00
00:00:00.63

00:00:00.16
00:00:00.98
00:00:01.11
00:00:00.00
00:00:00.21
00:00:00.01
00 00:00.02
00 00:00.00
00 00:02.49

USR
USR

CON
CON

ABS
REL

LCL NOSHR NOEXE NORD
LCL NOSHR
EXE
RD

NOWRT NOVEC BYTE
WRT NOVEC BYTE

tzl
(/)

The working set limit was 200 pages.
673 bytes (2 pages) of virtual memory were used to buffer the intermediate code.
There were 10 pages of symbol table space allocated to hold 3 non-local and 0 local symbols.
66 source lines were read in Pass 1, producing 13 object records in Pass 2.
0 pages of virtual memory were used to define 0 macros.

+--------------------------+
! Macro library statistics !
+--------------------------+

Macro library name

Macros defined

_DRA5: [SYSLIB]STARLET.MLB;l

0 GETS were required to define 0 macros.
There were no errors, warnings or information messages.
USSTEST/LIS

"'C

:::c
H

<
H
t"1

Cz:I

°'rvI
I-'

USSLNK.COM

$
$
Command file to link User System Service example.
$
$ LINK/PROTECT/NOSYSSHR/SHARE=USS/MAP=USS/FULL SYS$INPUT/OPTIONS
Options file for the link of User System Service example.
SYS$SYSTEM:SYS.STB/SELECTIVE
Create a separate cluster for the transfer vector.
CLUSTER=TRANSTER VECTOR,,,SYS$DISK: [lUSSDISP
!

GSMATCH=LEQUAL,1,1

USSTSTLNK.COM
$

$ !

Link Command file for USSTEST

$ !

$ LINK USSTEST/MAP/FULL,SYS$INPUT/OPTIONS
Options file for USSTEST
USS.EXE/SHARE

C/)

:::c
>
:::c
Cz:I

°'
t"1
Cz:I

Cz:I
C/)

USS.MAP
USS

15:48

10-~AR-1980

Module Name

I dent

USER SYS DISP
SYS SYSVECTOR

Bytes

Creation Date

0882: [HllSTVEDT. USS] USSOISP .OB,J; 18
- DRA5:
fSYSEXE]SYS.STB;l

- ORAS: [SYSLIB]STARLET.OLR;l
-

_DBB2: [HUSTVEDT.USSJUSS.EXE;l9

Type Pages

TRANSTER VECTOR

00000200
00000400

0 READ ONLY

0 RF.AD ONLY

_DBB2:[HUSTVEDT.USSJUSS.EXE;l9

-------

VAX-11 Macro V02.42
LINK-32 V02.42
VAX-11 Macro V02.42

LINKER V02.42

G1ohal Sec. Name

Page

Match

Major id

Minor id

"'C
:::0

<
H
10-MAR-1980 15:48

Creator

Image Section Synopsis !

Base Addr Disk VBN PFC Protection and Paqinq

4
4

10-MAR-1980 15:48
5-MAR-19RO 20:17
5-MAR-1980 00: 11

lC-MAR-1980 15:4R
!

Cluster

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

-----

275
0

Vl.O
.STB;l
0221

Page

Object Module Synopsis !
File

LINKER V02.42

Page

tZ3
0

Program Section Synopsis

ti)

l:"1
tZl

Psect Name

Module Name

Base

End

Length

Align

Attr-ibutes

>
:::0

N
N

tZ3

BLANK

00000000 00000000 00000000
00000000 00000000 00000000

0.) BYTE 0 NOPIC,USR,CON,REL,LCL,NOSHR,
0.) BYTE 0

EXE,

RD,

00000200 00000210 00000017
00000200 00000210 00000017

23.) PAGE 9
23.) PAGE 9

PIC,USR,CON,REL,LCL,NOSHR,

EXE,

RD,NOWRT,NOVEC

00000200 00000200 00000000
00000200 00000200 00000000

O.) BYTE 0 NOPIC,USR,CON,REL,LCL,NOSHR,
0.) BYTE 0

EXE,

USER SYS DISP

l.) BYTE 0
l . ) BYTE 0

PIC,USR,CON,REL,LCL,NOSHR,

EXE,

RD,NOWRT,NOVEC

USER SYS DISP

00000217 00000217 00000001
00000217 00000217 00000001
00000218 00000219 00000002
00000218 00000219 00000002

2.) BYTE 0
2.) BYTE 0

PIC,USR,CON,REL,LCL,NOSHR,

EXE,

RD,NOWRT,NOVEC

USER SYS DISP

0000021A 00000254 00000038
0000021A 00000254 00000038

59.) BYTE 0
59.) BYTE 0

PIC,USR,CON,REL,LCL,NOSHR,

EXE,

RD,NOWRT,NOVEC

USER SYS DISP

00000255 00000250 00000002
00000255 00000256 00000002

2.) BYTE 0
2.) BYTE 0

PIC,USR,CON,REL,LCL,NOSHR,

EXE,

RD,NOWRT,NOVEC

USER SYS DISP

00000257 00000282 0000005C
00000257 000002B2 0000005C

92.) BYTE 0
92.) BYTE 0

PIC,USR,CON,REL,LCL,NOSHR,

EXE,

RD,NOWRT,NOVEC

USER SYS DISP
USER KERNEL DISPO
USER SYS DISP

00000283 000002ED 0000003B
000002B3 000002ED 0000003B

59.) BYTE 0
59.) BYTE 0

PIC,USR,CON,REL,LCL,NOSHR,

EXE,

RD,NOWRT,NOVEC

SYSVECTOR
$$$TRANSFER VECTOR
USER SYS DISP
BLANK
EXEC NARG
KERNEL NARG
USER EXEC DISPO
USER EXEC DISPl
USER EXEC DISP2

WRT,NOVEC

°'l:"1tZl
H

RD,

WRT,NOVEC

tZl
ti)

USER KERNEL DISPl
USER SYS DISP

000002EE 000002Fl 00000004
000002EE 000002Fl 00000004

(

4.)

USER KERNEL DISP2
USER SYS DISP

000002F2 000002F2 00000001
000002F2 000002F2 00000001

(
(

l.)
l.)

USER SERVICES

00000400 0000041F 00000020
00000400 0000041F 00000020

(

USER SYS DISP
_DBB2: [HUSTVED7.USS]USS.EXE;l9

Symbol

Value

CTL$GL PHD
EXEC DlSPATCH
KERNEL DISPATCH
SS$ ACCVIO
SS$-INSFARG
SS$-NORMAL
SYS°S'K VERSION
USER GET TODR
USER-NULL
USER-SET PFC

7FFEFE88
00000227-R
000002CO-R

(

4.) BYTE 0
BYTE 0

PIC,USR,CON,REL,LCL,NOSHR,

EXE,

RD,NOWRT,NOVEC

BYTE 0
BYTE 0

PIC,USR,CON,REL,LCL,NOSHR,

EXE,

RD,NOWRT,NOVEC

32.) PAGE 9
32.) PAGE 9

PIC,USR,CON,REL,LCL,NOSHR,

EXE,

RD,NOWRT,

VEC

Page

10-MAR-1980 15:48

+-----------------+
! Symbols By Name !
+-----------------+
Symbol

Value

Symbol

LINKER V02.42

Value

Symbol

-----

Value

-----

.,,

oooooooc

<
H

00000114
00000001
35503058
00000258-RU
000002AB-RU
00000275-RU

C""'
Cz:l
G)

Cz:l

0
(/)

O'\

I
N

_DBB2:[HUSTVEDT.USS]USS.EXE;l9

10-MAR-1980 15:48

+------------------+
! Symbols By Value !
+------------------+

Value

Symbols •••

-----,
00000001

oooooooc

00000114
00000227
00000258
00000275
000002AB
000002CO
35503058
7FFEFE88

SS$ NORMAL
SS$-ACCVIO
SS$-INSFARG
R-EXEC DISPATCH
R-USER-GET TODR
R-USER-SET-PFC
R-USER-NULL
R-KERNEL DISPATCH
SYS$K VERSION
CTL$GL PHD

Key for special characters above:

+------------------+
!

* - Undefined
U - Universal
R - Relocatable
WK - Weak

+------------------+

LINKER V02.42

Page

:I:

">
Cz:l

°'
C""'
Cz:l

Cz:l
(/)

_DBB2:[HUSTVEDT.USS]USS.EXE;l9

Virtual memory allocated:
Stack size:
Image header virtual block limits:
Image binary virtual block limits:
Image name and identification:
Number of files:
Number of modules:
Number of program sections:
Number of global symbols:
Number of image sections:
Image type:
Map format:
Estimated map length:

10-MAR-1980 15:48

+----------------+
! Image Synopsis !
+----------------+

C"I

Page

00000200 000005FF 00000400 (1024. bytes, 2. pages)
O. paqes
1. block)
1.
1.
2. blocks)
2.
3.
USS .STB;
3.

3.
18.
9.
4.
PIC, SHAREABLE. Global section match = "LESS/EQUAL", G.S. !dent, Major=l, Minor=l
FULL in file " DBB2: [HUSTVEDT.USS]USS.MAP;l9"
43. blocks
-

+---------------------+
! Link Run Statistics !
+---------------------+

Performance Indicators

N
.i:::.

LINKER V02 .42

Page Faults

Command processing:
Pass 1:
Allocation/Relocation:
Pass 2:
Map data after object module synopsis:
Symbol table output:
Total run values:

9
31
7

3
17
0
F,7

"'C

<
H

CPU Time

Elapsed Time

00:00:00.08
00:00:01.00
00:00:00.05
00:00:00.22
00:00:00.25
00:00:00.04
OO:OO:Ol.n4

00:00:00.12
00:00:01.79
00:00:00.19
00:00:00.72
00:00:00.70
00:00:00.33
00:00:03.85

Using a working set limited to 200 pages and 14 pages of data storage

(excluding image)

CZ]

G1
CZ]

0
ti)

,,>::c
CZ]

°'r
CZ]

Total number object records read (both passes):
272
of which 51 were in libraries and 2 were DEBUG data records containing 414 bytes
Number of modules extracted explicitly
with 1 extracted to resolve undefined symbols

= 0

0 library searches were for symbols not in the library searched
A total of 4 global symbol table records was written
/PROTECT/NOSYSSHR/SHARE=USS/MAP=USS/FULL SYS$INPUT/OPTIONS
Ready

>
G1
CZ]
ti)

CHAPTER 7

PROGRAM EXAMPLES

This chapter presents applications that use many of the features
discussed in this manual.
Each application is explained, and the
program listings are given.
The programs are in VAX-11 FORTRAN,
although some routines are in VAX-11 MACRO.
The following applications are included in this chapter:

7.1

•

An analog-to-digital (A/D) data acquisition
system

•

An airline reservations system

and

manipulation

DATA ACQUISITION AND MANIPULATION

This system, called LABIO, allows multiple users to receive and
manipulate analog-to-digital
(A/D)
data in real time.
In this
example, a 16-channel A/D converter, such as the ADll-K, is shared by
1 to 16 independent users. This example demonstrates the real-time
use of many VAX/VMS system services and features
(described in
Sections
7.1.2
and
7.1.3).
However,
because each real-time
application is unique,
this example does not show the only, or
necessarily the most efficient, use of these features.
It is meant
only as a guideline for possible implementations.

7.1.1

Application Overview

In the LABIO system the In-channel A/D converter is to be used
independently by up to 16 users;
that is, each user must be able to
specify collection parameters and collect data from one or more A/D
channels without conflicting with other users. This independence is
achieved by placing a single "privileged" process (LABIO_DATA_ACQ)
in
control of the ADll-K.
The LABIO DATA ACQ process collects data from the ADll-K and stores
the data in -buffers in a shared data array. The process runs at a
real-time priority and
uses
the
VAX/VMS
connect-to-interrupt
capability to process interrupts from a dedicated KWll-K real-time
-clock. On every clock overflow, data from the ADll-K is taken and
stored in the shared data array. The process uses control information
stored in the shared data array to determine how much data is to be
collected for each A/D channel. To protect users from other users
(and from themselves), the shared data array is read-only for the
users.

7-1

PROGRAM EXAMPLES

To store control information in the control block, each
user
communicates with a second "privileged" process, LABIO CONNECT. The
LABIO CONNECT process receives, validates, and acknowledges each user
request,
and modifies the data base accordingly.
Simultaneous
requests from different users are serialized through the use of
mailboxes.
The mailbox that receives user requests has the logical
name LABIO CONNECT. Users can issue four types of request:
•

CONNECT

ALLOCATE

•

DISCONNECT

•

DEALLOCATE

The first user request must be CONNECT. This request makes the user
known to the LABIO system. The user also passes the logical name of a
mailbox, which the LABIO CONNECT process will use to ackowledge the
user's requests.
After a CONNECT request is completed, the user can issue ALLOCATE and
DEALLOCATE requests.
The ALLOCATE request is used to gain ownership
of a specific A/D channel; once a channel is allocated by a user, no
other users can allocate it until the owner specifies it in a
DEALLOCATE request. Four parameters are associated with the ALLOCATE
request:
•

Channel number

•

Sample rate

•

Buffer size

•

Buffer count (number of buffers to be acquired)

A user can allocate any number of A/D channels. The ALLOCATE request
can also be used to change collection parameters for a channel a user
already owns.
When finished with a channel, a user issues a DEALLOCATE request for
the channel; and when finished altogether, a user issues a DISCONNECT
request. The DISCONNECT request removes a user from the LABIO system
and implicitly deallocates any channels still allocated to the user.
Once connected to the LABIO system and allocated channels, a user
communicates with the data acquisition process (LABIO DATA ACQ) using
event flags. Each channel has three flags associated ~ith Tt:
•

ACTIVITY flag

•

NOTIFY flag

•

STATUS flag

The ACTIVITY flag determines whether data collection is enabled
(flag
set by user) or disabled (flag cleared). The user process tells the
LABIO DATA ACQ process to check the ACTIVITY flag by setting the
NOTIFY flag; that is, when the NOTIFY flag is set, the LABIO DATA ACQ
process checks the state of the corresponding ACTIVITY Ilag -and
enables or disables the channel. When a data buffer is ready for user
processing, the LABIO DATA ACQ process sets the STATUS flag for the
channel.
When the user process detects that the STATUS flag is set,
it clears the flag and processes the data buffer.

7-2

PROGRAM EXAMPLES
There is one utility program associated with the LABIO system:
LABIO STATUS, which displays the status of each of the A/D channels on
a VT52-compatible video terminal.

7.1.2

LABIO System Details

The LABIO system uses a number of VAX/VMS features described
manual.
The
following
sections
describe the major
illustrated in this system.

in this
features

7.1.2.l Shared Data Base - The processes share data by using global
sections. The LABIO DATA ACQ process creates the global section using
the Create and Map Section ($CRMPSC) system service. A VAX-11 MACRO
routine
(GBL SECTION UFO)
is used to open the data file to be
associated with the global section. This global section is read/write
for
processes with the same UIC
(that is, LABIO DATA ACQ and
LABIO CONNECT), but read-only for other processes in the- group
(that
is, the processes running the user programs). The global section is
not accessible by any processes outside the group.
Other processes
map the global section using the Map Global Section ($MGBLSC) system
service, specifying the global section name LABIO_COMMON.
Because global sections are mapped by pages, it is important to ensure
that the data arrays are page aligned. To ensure this alignment, the
VAX-11 FORTRAN named-common and block-data features are used with the
VAX-11 Linker cluster option.
The shared data region contains three arrays:
•

AD BLOCK, containing ln
channel

•

CONNECT BLOCK, containing ln control blocks, one for each
process- that can be connected to the system (each process is
identified by its process identification)

•

DATA_BUFFER, the array into which the A/D data is stored

control

blocks,

one

7.1.2.2 Common Event Flag Clusters - Two common event
are used in the LABIO system:

•

LAB IO EF_NOTIFY, containing In NOTIFY flags

•

LABIO EF STATUSJ containing
flags - -

for

each

flag

A/D

clusters

ACTIVITY flags

and

STATUS

The LABIO DATA ACQ process waits for the logical OR of the ln NOTIFY
flags;
that is, the process is activated whenever any of the flags is
set. Each user process normally waits for the logical OR of the
STATUS flags for the channels it has allocated. Each user process
must set and clear the ACTIVITY flags as appropriate, and must set the
corresponding NOTIFY flag if it wants the LABIO DATA ACQ process to
check the ACTIVITY flag. The LABIO DATA ACQ process sets the STATUS
flag when a buffer is ready and stores-the buffer index in AD BLOCK.
The user process is then responsible for clearing the STATUS flag.

7-3

PROGRAM EXAMPLES
7.1.2.3 Mailboxes - The LABIO CONNECT process creates a mailbox with
the logical name LABIO CONNECT.
All user processes write their
requests to this mailbox.
Each user process must also create a
mailbox, and must specify the mailbox's logical name in the CONNECT
request.
If the LABIO CONNECT process accepts the CONNECT request, it
opens the user's mailbox and acknowledges the request by returning the
user request line preceded by a 2-character code:

•

Zero to indicate a positive acknowledgment

•

Nonzero to indicate a negative acknowledgment
(the
code corresponds to the field containing the error)

specific

7.1.2.4 Connecting
to
an
Interrupt
Vector - The
actual
analog-to-digital I/O is performed by an interrupt service routine
specified in the connect-to-interrupt $QIO call. The process connects
to the interrupt vector for the KWll-K real-time clock, which
generates an interrupt every millisecond.
On each interrupt,
the
interrupt service routine does the following for each active ADll-K
channel (all control information is stored in AD_BLOCK):

Decrements the timer for the current channel

If the timer overflows, takes an A/D reading and
result in DATA BUFFER

If the data buffer is full, switches to the next buffer

If the last buffer has been acquired, deactivates the channel

stores

the

If any buffer was filled, an AST is requested and bits 0 to 15 of the
AST parameter word are set to indicate those channels that had a
buffer filled. The AST service routine SET EF AST sets the STATUS
event flags corresponding to the channels that had buffers filled.

Typical LABIO User Program Logic

7.1.3

A typical program running in a user process in the LABIO system
contain the following logical steps:

would

Map the global section LABIO COMMON

Associate with the common event flag clusters LABIO EF NOTIFY
and LABIO EF STATUS

Open the mailbox LAB! o__ CONNECT

Create a mailbox to
LABIO_CONNECT process

Issue a CONNECT request and wait for an acknowledgment

Allocate channels
acknowledgments

Start data acquisition by setting
event flaqs

Wait for buffer(s) to be filled by waiting for
f laqs to be set

receive

using

ALLOCATE

7-4

from

acknowledgments

requests
the

and

ACTIVITY

the

wait

for

and

NOTIFY

STATUS

event

PROGRAM EXAMPLES
9.

Process the contents of the buffers

10.

Repeat steps 8 and 9 until finished

Program Listings

7.1.4

This section lists the files needed to create and use
the
laboratory
data acquisition application.
Three programs that make up the system
and three sample programs that use the system are presented first,
followed by modules used by all or some of the programs.
The
remaining files are used to activate the system and to compile and
link the program.
The files are presented in the following order:
1.

Three programs that make up the system.
The modules in each
program are as follows (LABIOCOM.FOR, listed later, is common
to all three programs) :
a.

LABIOACQ.FOR, GBLSECUFO.MAR, LABIOCIN.MAR

LABIOCON.FOR

LABIOSTAT.FOR

Three sample programs to use the system.
The modules in each
program are as follows (LABIOCOM.FOR, listed later, is common
to all three programs):
a.

LABIOPEAK.FOR, PEAK.FOR

LABIOSAMP.FOR

TESTLABIO.FOR

Modules used by all or some programs
a.

LABIOCOM.FOR

(common routines)

LABMBXDEF.FOR

(mailbox format)

LABCHNDEF.FOR

(common data structures)

LABIOSEC.FOR

(common data definitions)

Command procedures to activate the system
a.

CONNECT.COM

LABIOSTRT.COM

Files to compile and link the programs
a.

LABIOCOMP.COM

LABIOLINK.COM

LABIO.OPT

LABIOCIN.OPT

7-5

PROGRAM EXAMPLES

lFilel

LABIOACQ,FOR
Program LABIO.DATA.ACQ

This is the program that acQuires data for the LABlO system
It uses the connect•to•interrupt feature of VMS to acquire
via a user written 1/0 routine. The actual I/O routine is
written in MACRO, The mein program monitors tne event flags
and •~ables and disables data acavisition for eac~ channel,
It also notifies users via event flags w"en e buffer is ful I,
Define the LABIO data base
Include 'LABCHNDEF,FoR·
Local Variables
Logiea1*4

S~CTIO~.FLAGS,

SECTI0~ 4 PROT

System Services
Lo91ea1*" SYS$ASCEFC,SYS~MGBLSC,SYS~ASSIGN,SYS$Ql0
Logical*~

SYS!C~REF

External constants
External SEC,M.GBL,SEClM.wRT,SSS 4 CRtATEO,SS$.wASSET
External SET.tf .AST

Misc,

Create the Global Section for the data buffer
This data buffer will be REAJ/wRITE for the owner, READ only

for the

G~C

First see if t~e global s~ction already exists, if it
does Just map to it, ano set the restart +lag.
If not, Open the Data File. Tnis can not be opened
via FORTRAN since we need the V~S channel nu~ber,

SECTlONCl) = XLocC LABio.euFFf~.S)
!Start address of
SECTIONC2) : ~Loe( LABlo.~uFFtR.E) • 1 1En1 address
Page count for the section
SECTlON~SIZE : C SECT10N(2) • SECTIUN(ll )/512 + 1
FLAGS for Section are
SECTION~FLAGS

seetio~

GLOBAL1SHAREO,NON~ZE~OED,READ/~RITE,TE~P

: %Loe( 5tC$M.GBL ) + Y.Loc( SEC$M.wRT )

Trv Just maoPing to the global sect;on
SUCCESS: SYSSMGBLSCC
11( SUCCESS ) T~en
RtSTART : ,T~UE,

SECTION,,,~Va1CSECT10N~FLAGS),•LABIOCOMMON',,

lSueces,

t~;s

is a restart

Else

SUCCESS : GBL.SECTION.UFOC SECT!ON 4 SIZE, 'LA6IO.SEC.FILt',
StCTION~CHANNEL l
If C ,not. SUCCESS )
Call fATAL~E~RORCSJCCESS,'Opentng Glooal Sectio~ File')

7-6

PROGRAM EXAMPLES

PROTECTION is OWNER : READ/WRITE, GROUP : READ, SYSTEM/WORLD : none

= 'F E 0 r•x LProtection for section

S~CTION~PROT

Create and Map the Section

SUCCESS: SYS$CRMPSCC SECTION,,,%ValCSECTION.FLAGS),'LABIOCOMMON',
,,%Va1CSECTION.CHANN€l),%Va1CSECTION.SIZE),,
XVa1CSECTION 4 PROTJ,%ValCSECT!ON.SIZE))
If C ,not, SUCCESS )
Ca11 FATAL~ERROR(SUCCESS,'Creating Global Section')
RESTA~T = ,FALSE.
£We ere not restarting
End If
1
1

If this is not a restart, elear the data structures
If (

,~ot,

RESTART l Then

Do 32 I = 1,
Do 3IO J :

MAX.AD.C~ANNE~

AD.6LOCK(J,I) : ~
Do 31 K : lr BUFFER.COUNT
Oo 31 J : 1, MAX.BUF.SIZE
DATA.BUFFER(J,K,Il : J
Continue
Do 33 1 : 1, MAX.PIO

Do 33 J :

lClear Data buffers

1r 2

CONNtCT.bLOCKCI,J) : 0
El"ld IF

1Clear AO""'BLOCK

U:>

1Clear Process connect o1oek

Create event flag cluste~ EF~NOTIFV and associate with event flags
These are used to not1fy the Data Acauis1tion orocess.

~Q•95

SUCCESS : SYSSASCEFCC XVALCEF.NOTIFV.ll,EF 4 NOTIFV 4 CLSTR,,)
If C ,not. SUCCESS)
1
Call FATAL~tRRQR( SUCCESS, 'CREATI~G ~VENT FLAG CLUSTtR')
Create event flag cluster EF'.STATUS and associate witn event flags 96•127
These ere used to ~otify and report the status of the user buffers
SUCCESS : SYS$ASCEFCC %VALCEF 4 STATUS~l),EF~STATUS.CLSTR,,)
If C ,not, SUCCESS)
1
Call FATAL~ERRORC SUCCESS, 'CREATING EVtNT FLAG CLUSTER')
Make sure that

can•t be swepped

Call SYS$SETSWM(ZVa1Cl))
the Connect•to•InterruPt
First ass1gn a VMS channel for the device
Then cal1 the connect•to•interrupt setup routine,

Set·~P

succtss : SYS$ASS1GN( 'LAblO~AD',Cl~~CHANN~~,,

If ( ,not, SUCCESS )
1 Call FATAL~ERROR( SUCC~SS, 'assigl"li"g A/D aevice'

succ~ss

= AD.CIN~SETU~( C!N~CHANNtL,Stl.EF~AST )

If t ,not, SUCCESS )
1 Call FATAL.tRROK(

SUCC~SS,

7-7

'connectinq•to•;nterrupt')

PROGRAM EXAMPLES

End Of Initialization, Notify other processes by setting

Call SYS$5ETEFC

~Val(

EF+DATA~ACQ

EF.DATA.ACQ) )

Wait for an event flag in the EF.NOTIFY cluster
Then reed the EF.NOTIFY CLUSTER and EF.STATUS~CLUSTER

Call SYS$WFLORC %Va1CEF 4 NOTIFY.1) , %ValC'FFFF'X)

the flag(s) set in EF.NOTIFV
'l Looktheforcorresponding
activity flag is set, activate the channel,
l

1 otherwise deactivate it, Also check tne buffer status flag, if clear
1 clear the buffer index,
l
1 db

Do 20 I :

If( SYSSCLREFC %Va1CEF.NOTIFY~OFF + Ill ,eq, %LocCSS$~WASSET)l Then
lfC AD.BLOCK(1,I) ,ne, 0 ) Then
If( SYS$RtADEFC %Val(~F 4 ACTIVITY 4 0FF + IJ,EF 4 5TATE
,eq, XLoccsss.wASSET l l Then
A0 4 BLOCK(l,Il : ACTIVE
Else

AD 4 8LOCK(1,!) : INACTIVE
El"IO

If( SY5$RtADEF( %Val(f:F.STATuS.OFF + !),EF.STATE )
1

,ea,

%Loe(SS$~WASCLR))

End If'
End It

Continue
Go To 10

Eno
Subroutine

SET.Ef~ASTC

~vENT~fLAGS

This is a AST routine which is ;nvokea oy t~e
Iriterrupt serv1ce routine, Tnis routine sets
tne event flags indicated by tne ISR,
Iriclude 'LABCHNDEF,FOR'
Integer EVENT.FLAGS

The Event flags
Do
10

1~1

are

set in cluster

EF~STATUS~CLSTR

I::; lilt

lf( CEVE~T.FLAGS ,an~. blTC!)) ,ne, ~
1 Call SYSiSf:TEFC %Va1CEF.,,.,STAlUS..,OFF +I))
Coritinue
Return
Erio

lLEnd of FileJ

7-8

AD.B~OCK(7,l)

PROGRAM EXAMPLES
,TITLE GBLSECUFO
Global Section UFO (User File Open)
JTh1e routine opens a file to be used as a global section
;An RMS OPEN 1s performed with t~e file ootions CFQP) of
1U1er File Open (UFO), The calli~g routine specifies the
Jfilt na~e and number of blocksf this routine returns the
;channel number on wh1eh t~e f11e ~~•opened,
1tf the specified file does not exist, the file is created
J

JThe calling seQuence is

Whtl't
blkcnt :> Number of blocks in t~e file
file•name => filename descriotor block
ehan => channel opened
J

J
JEumpl ea
1
Integer*~ CrlANNEL
1

I
I

Call GBL.SECTION.uFoc10,'LABIO ... DATA,DAT',CHANNEL

,SBTT~

GBL.SEC.UFO

J RMS FAB for a SCRE.ATE

GBLFABs SFAB

FAC=PUT,•
FOP=<UFQ,CIF,C~T>

NUM~ARG

sNu~ber

of arguments

,ENTRY

MOVL.

BLSS

#SS$.a.INSFARG,R0
CAP), #NU"1..,.ARG
Ex IT

JAssume bad arg count
JCl'lecl< erg coul'lt
7Too few

MOVL

~(b.P),Rl

MOV8

(~1) 1 G8LFAB+FA8$8 4 FNS

JGet file name address string descriptor
JStor~ string length 11'1 FAB
:And file name

Ct-iP~

"10VL

4(R1),G8L~A~+FAB$L~FNA

MOVL

04(AP),GdLFA8+FABSL.a.ALQ :Number of blocks to alloeate

!>CREATE. FAd:GbLFAB

;Open data file, Create it if
does not e•ist
G~LFAB+FA~,L.STV,~12(AP):Store channel number
; i f ;t

MOVL
EX IT:

RU
• t.NO

7-9

PROGRAM EXAMPLES
Kw ... HIST : 1
.TITLE LABI0 4 CIN • LABIO Connect•to•Inter~u~t Module
.IDENT /\101/
:++
FACILITY I
LABIO demonstation system

ABSTRACTS
This module contains the I/O code for ~endling
an AOll•K. It is an examole of a connect•to interrupt
routine, This module contains code to oerform tMe following
The start I/O routine
The interruot service routine
The e~ncel I/O rout1rte

AUTHOR:
P. Programmer

:··

.s~TTL

DATA STRUCTURES

,PScCT

LABIU.SECTION

The following data structures are also oef1ned Dy a
FORTRAN INCLUDE file, These definitions must aqree.
; AD.a.BLOCK

AID Control dlocl<

MAX.a.AD ... CHANNEL : lb
JNumDer of A/D c~annels
AD ... BLOCK 4 SLOTS = lb
rnumoer of entries in one block
AD ... BLOCK.S!ZE = MAX~AD~CHANNEL•AD~~LOCK~SLUTS

:AD ... BLOC~ offsets (long woros)
AD 4 STATUS
=0
ACTIVE.._L: 2
lNACTIVf: .... L :

PIO

TICS ... SAMPlE
BUFFER.SIZE

BUFFER.COUNT
8Uf FER ... ACQ
VALID ... BUF .._IND

= l.l
=8
= 12
= 1b
= 20

: 2/J

VALI0 4 BUF ...,COUNT : ~f.!.
: 32
CUR 4 BUF.IND
CUR.,..BUF 4 COUNT
TI cs ... REMA IN I NG

"Sb

:STATUS (Unknown, inactive, or active )
ACTIVE
INACTIVE

PID of connected process
~ate ;n tics/sa~ole
user soecified ouffer s;ze
1 vser soec,fieo buffer count
Number of buffers acquired
l~d~x of current vel id data buffer
N~moer of data oo1~ts in lest buffer
Inoex to current acq. buffer
Number of ~eta ooi~ts in last ouffer
Tics remaininq to next sample
Offset to aco point
Offset to eno of e block

AD...,BLOCK.JNO

= 4v.)
= 4l.1
= b4

A0 4 BLOCK:

,8LKL

: DATA,..t3UFFER

Data buffers for LAHlO

CUR ... ACQ..,.OFF'

MAX.._BUF.._COUNT
MAX.BUF 4 SIZE

: 2
: 512

AD.._BLOCK.S IZE

J~um~er

JMaxi~um

7-10

buffers/channel
ouffer size (wOkOS)

PROGRAM EXAMPLES
BUFFER,._E.NO

= MAX~HUF.COUNT•MAX ... 8UF~SIZE•? J Size of o"e set of buffer•

DA TA ... BUF ..,.5 I ZE
DATA ... BUFFERa

MAX~AD..,CHANNEL•MAX..,BUF.._SIZE*~AX 4 BUF.COUNT

,BLK~

OATA.BUF.._SIZE

DATA ... BUFFER~OFF :

OATA..,.6UFFER•AD~BLOCK

: CONNECT,,.BLOCK

Process

MAX ... PID : 16

:Ma~

JOffset to data buffer from
Jbeginning of data structure

Co~~ect

COntro1 block

number of processes connected

CONNECT.SIZE : MAX.PID*2
CONNECT.BLOCK:

,BLKL

,SBTTL

CONNEC ·r ..,.SIZE

I/0 DEVICES

:This section def;nes tMe constants asocc1ated with the KW11•K
:and the AD11-~ AID converter

cloc~

JKW11•K Clock

;CSR bit assignments
:GO b;t
J r< a t e = b i t s 2 - LI
1Interrupt enable

KW11$M..,GO: •01

KW11$M ... RATE :
•02
KW11$M ... JNTENB : •0100
KW11$M ... REAOV :
·02~0
KW11$M ... REPINT = •0400
~w11.csR ... CONS

KW11 .... PRESET

JReady

tiit

irepeateo interwuPts

; KW11SM ... REPlNTlKW11$M.INTE~Bl<1*K~11$M~RATt>
~RP.oeated ;nterrupts,1nterruot enable
: Ra t e

= 1~00,

= 1 ~H'i z

:Preset => Interrupt rate of 1 KHz

KW11.A,..6UfFt~ : •02
KWlt .... A... COUNTEP : •024

;Offset to cloc~ A oreset buffer
JOffset to clock A counter

:AD11•K AID converter
AD11.a.OFFSET

AD11 ... dUF
AD11 ... GO

AD11.a.MUX ... INCR
ADl 1... CSR,..CONS

= - i~
=2
=
= •otHH-'
= AD11..,.GO

:Limit for stopoinq
AD11,,,. L0 0 p .... L I MIT

IS~

1
1

Go bit
: N1ux incr h.it
Jrdtial CSR value

loop

= A() l 1.... ,. . , ux... I Nc R* < ~'I A x... A D""" c H A IJt·..i t L- 1> 1 Al) 1 1 csR ... c 0 t--; s
,,a.

$UC6Df.F
$100EF

uefinition tor LIO drivers
Data st,.ucturs
l/O functio~ codes

.'f.CINDE.F

Connect•to•;nterr~pt

$ I080t F

C~B

$CRBDEF
$Vf.CDEF

,SB TTL

1
LABIO~CIN~START,

:++

Offset to the ADll fro~ t~r K~ll clock CSR,
AD11 cuffer offset fron ADll CSR

LABIO~CIN~START

- Starts tne

stuff

mo re
St~rt

K~11-K

: Functional descr1Pt1on:

7-11

l/C routine

PROGRAM EXAMPLES

This

starts the KW11•K
Rate = 1 Knz
RePeated f nterruot

rout~ne

Inputs:
0(R2)
4(R2)
8(R2)

count
Address of
Address of
Address
Address of

arg

•
•
12CR2) •
lb(R2) •

o"the process huf fer
tJ

the !RP (1/0 request D3Cket)

o., the device's CSR

the UCB (Unit control block)

Outputs:
none
The routine must preserve all registers eieept

:--

R~·R2

and R4,

,PSECT LA8IO ... CIN

LABIO.CIN 4 START::
MOVL

12(~2),R3

CLRW

(1-rn)

Get ad~ress of the KW11 CSR
Clear the Clock

MNEGw

#K~11 4 PRESET,•

Preset count ouffer

~~11.A.~UFFERCR~)

MOVW

~K~11.csA.CONS+K~11sM.GQ,(R~)

, Set the bits for

Repeated interrupt
Interrupt Enable
GU L

Load a success code into R0,

#SSi.NOR~AL,~~

~ovw

RS t;

J
LASIO~C!N~J~TE~RUPT,

,SB TTL

Return

Interrupt service routine

; ++
LA8IO.CIN.INTERRUPT
Functional description:

Inputs:
• arq count of 5
- Address of the orocess buffer

0(R2)
4(R2)
8CRt?)

• Aodress of t~e AST Parameter
12CR2) • Address of the Oevice•s CS~
lb(~2) • Aa~ress of t~e 108 (interruot ~ispatc~ block)
b:l(R2) - Addreas o" t"• UCci (Unit control olock)
Outputs:
Sets those hits in the AST parameter for those
cnannels who hed a buffe~ fi11eo

:-C!N...,BUF.ADD : 4
AST.a.PARM :

;Address of CIN buffer
;Offset to ~ST oer~eter aadress
:Ad<1ress of CSP

CIN.a.CSR,..ADD :

7-12

PROGRAM EXAMPLES
J

AD ... LOOP..,OATAa
1$1

TSTB

CR~)

BGEQ

MOVW

AD11 ... BUFCR4),CR1) [R~J

JTim~ h1stoQram donrt store actual det1
1store oata point in buffer,

J~ait

,IF NOF Kw.,HIST

for A/0 conversion

,ENDC

JAll done w1tk thia channel, setup for the ne•t
1
AD.d,.OOP ,..NEXT I

ADDL
ADDI..
ADDW
AOBLSS

1S I

uo ... eLOCK..,ENO, RS
#BUFFER .... ENO,Rl
#AD11 ... MUX.INCR,Ro
s•#MAX ... AD ...CHANNEl,R3,•
AD ... t..QOP

JNeMt c~annel block
JP\le)(t buffer
Jlner A/O MUX
JNext Cl'laruiel
J8!" if not done

routine • If any buffer overflowed, queue an AST
•AST ... PARM(R2),R~
Jlf any bit 11"'1 the AST peremeter
MOVL
BEQI.
1$
Jis set we ~ust aueue an •ST
#l,R0
J 1 means Queue the AST, 0 means don•t
MOVL
POPR
•·~<R5,Ro>
1 Restore RS,Ro

RSB

,SBTTL

1.ABIO..,CIN.CANCEL, Cancel IIO routine

J++
J

LABIO ... CIN ...CANCEL1 Cancels an 110 operation in orogress
Functional descr1Pt1ons
This routine turns off the

K~11•K

Input11
Addr of the UCB

Outputsa

The routine must preserve all registers except R0•Rl,
1··

LABIO...,CIN ... CNCLll
MOVL
MOVL
MOVL

ID6$L,..CSRCR0),~~

Cl..RW

(R0)

MOVW
RSB

~SS$.NORMAL 1 R0

,SBTTL

;++
; Label
;••

UCBSL ... CRBCRS),~0
CP~$L ... INTD+VEC$L.ID~CR0),R0

that

LABIO,..CI~.E~D,

mar~s

; Get Adoress of tne CRB
;Address of t~e IDB
Get eddr of l<W11
Turn of tl'le K~ll
And

return

End of Module

the end of the module

LABIO ... CIN,..END:
.SBTTL AD,..CIN,..SETUP

: Last location ;,, module
Set•uo routine for LABIO connect•to•interrupt

:+
; Tn;s routinP. issYes tne

~10

to connect to tne AD11/KW11 ;nterrupts,

7-13

PROGRAM EXAMPLES
LABIO..,CIN .. INT11
-

AD..,LOOP1

MOVL.
MOVL

#•M<RS,R6>
CIN..,CSR .. ADDCR2),R4
CIN.BUF 4 ADDCR2l,R5

MOVAL
MOVAL

OATA..,BUFFER .. OFFCRS),R1
A011..,0FFSETCR4lrR4

rServ1ce device iMterrupt, 11ve R5,R6
JAddreas of the KW11 CSR
JAddre11 of AD..,BLOCK, contro1 block
Jtor each AID C"1nnel
,oet1 Buffer•
JAddre11 of the AD11 CSR

MOVW
CLRL.
CLRL

#AD11..,CSR ..CONS,Rb
UST.PARMCR2)

JAD11 CSR b1t1, GO b1t on
rZero the AST parameter

CMPL.
BL.SS

CRS),S.#ACTIVE ..L
AD .. LOOP..,NEXT

SOBGTR

TICS..,REMAININGCRS),AD.LOOP .. NEXT
rDecr
t1m1r for tn1• channel
JBI" 1f ~o conver11on l"tQU11"td

MOVW

R&,(R4)

PUSHR

channel actf veT
JNo, try next cManntl

1I1 tn1•

t"•

1Start eonver11on, whf le that'• oofng o
JT1me histogram, 1tored fn d•t• bufftr
KW11..,A .. COUNTER•AD11..,0FFSETCR4),R0 1Get CUl"l"tnt clock content•
#KWt1 ..PRESET,R0
1Celc tfme from 1ntgerru~t
CRl) [R0]
JAdd o"e to that time bin

,IF OF KW.HIST

MOVZWL
AOOW
INCW
,ENDC
While the AID 11 convert1Mg, t~e tfc counter for this channel,
get the off1et to the date oo1nter, and update ft, Take •PPl"OPl"1ate
actfon ff we have buffer overflow,

TICS..,SAMPLECRS),•
1Re1et t1~er tor thf 1 channel
TICS..,REMAININGCR5)
MOVL
CUR.ACQ .. OFFCRS),R0
rGet index to next date point
, AdVll"ICt 1t
INCL
CUR.ACQ,..OFFCR5)
AOBLSS BUFFER..,SIZECR5),•
JU~d•t• current data count
CUR..,BUF,..COUNTCR5),•
,a~ if no buffer overflow
AO,,.,L.OOP,..OATA
JBufftl" overflo~ed, re1et date pof"ter, reset buffer pof nter
11ncrem1nt acquired buffer count, term1mete channel I/O ff done
MOVl.

MOVL
MOVL

MULL3

cuR .. BUF ... INO(RS),•
VALID ...BUF...,INOCRSl
CUR .. BUF.COUNTCRS),•
VALID,..BUF...,COUNTCRS)
CUR,..BUF 4 INO(R5),•

sValid deta buf available for

u••~

JNumber of pof nts f n buffer
JOf fset to next date oo1nt

#MAX..,BUF...,SIZE,•

CLRL
AOBLEQ

MOVL

CLRL
U:

INSV
AOBLSS

TSTL
BEQL

MOVL

CUR,..ACQ.._OFFCRS)
cuR ... BUF.COUNTCR5)
#MAX ... BUF 4 COUNT,•
CuR ... BuF ... INDCRS),1$
#1rCuR ... BUF ... INO(R5)
CUR .... ACQ .. OFFCRS)

JReset data count

JNext buffer index
J~raP•around,

#1rR3,~1,•AST 4 PARM(R2)

BUFFER ... COUNT(P.5),•
6UFFER .... ACQCRS),2l
BUFFER ... COUNT(RS)

2$
#IN ACT I \IE ..,.L, C.R 5)

2S:

7-14

~eset

ou1fer index

sAnd buffer offset
rSet bit in 4ST Para~eter word

1Incr buffer count
1Done with all ouffers?
Jlf original count was zero
1Don"t stop
iDeact;vate channel

PROGRAM EXAMPLES

It takas care of the internals associated with the eon~ect•to•interrupt
the VMS channe1 and the AST service routine address,
The connect•to•;nterrupt QIO condition coae is returMed,

QIO, Input parameters
,PSECT

AD ... C!N...,SETUP

AD .... CIN ...SETUP1:
,WORD
MOVL

AD ... CIN...,QIO:

$QI o,,,,s

8(APl,USER,..AST

;Get tMe user AST

CHAN:(l!t.1(AP) 1 •

7Channe1
sA11ow writing to the data b~ffer
:IIO status Block
J8uffer descriptor
:Entry list
JStatus bits,etc
rAST service routine
JPreal1ocate some AST control blocks
;Returl"I to cal 1er

FUNC:#l0$~CONI~T~RITE,•

IOSB:AD..,.CIN.._IOSB,•

Pt:AD,,,,CIN.BUF.DESC,•
P2:#AD.CIN ... ENTRY,•
P3=#AD ... CIN .... MAS~,.
P 4: #A LJ..,. CI r~ .... AST, •
P6=# 1 "1

RE.T

AD ... CIN...,BUF.,..DESC:
,LONG
,LONG

routi~e

aodr

JBuf fer descriptor for CIN

AD.._BL.OCK

of buffer and CIN
:Address of buffer

JNo

LABIO~CIN~END•AD.BLOCK

~Size

ha~dler

AD..,.CIN.E.NTRY:
,LONG
,LONG
,LONG
,LONG

1nit

LABIO~CIN.START·AD~BLOCK;Start

eode

coae

LA8IO.CIN.INT•AD.BLOCK

Jll"lterrupt service routine

LABIO~CIN~C~CL•AO.dLOCK

:IIO cancel routine

AD.._CIN.a.IOSB:
,LONG

IIO Status Blocl<

: Contro1 mask

AD,,.CIN..,.AST
This AST routine calls the user AST routine. Tne user routi~e
can not be called directly because the AST carameter its~lf
not its address is returned via tne connect•to•;nterrupt routine,
Th;s routil"le simply calls the user rout;~e with the ADDRESS of
the AST parameter,
AD..,.ClN..,.AST::

.wORD
PUSH A~
CALLS

:Get the AST cara~ete~
:Call tne USER rout1ne

4(AP)

tt.\,OU5E:..R...,A$T

aa~r

RET
USER,...AST:

:Ador of

, L.Ot>.JG

7-15

the

user AST routit"le

PROGRAM EXAMPLES
IFilel

LABIOCON,FOR
Program LABIO.CONNECT

Define Lab;o date structures
Include
'~ABCHNDEF,FOR'

Mailbox Definit;ons
Include 'LA8HbXDEF,FOR'

!Defines Mailbox Date Structures

System Service Definitions

Logice1-4 SYS$CREM8X,SYS$ASSIGN
Log;ca1*4 SUCCESS
External 55$.tNDOFFILE

Integ~r

CONNECT,OISCONNECT,ABORT,A~LOCATE,OEALLOCATE

Integer READ 4 MAILBOX,~RlTE.MAILBOx,LA8IO.LOG,ACKNO~LEDGE
Integer CHECK~PID,RETU~N.CODE
Commana Data Str~ctures
Parameter
MAX 4 COMHAND : S
Character*15 co~~AND,COMMAND.TAbLE(MAX.CO~MA~D)
Data COMMAND.TABLE
l'CONNfCl',
1
'DISCON~Ecr·,
1
'A80~T',
1
'ALLOCATE',
1
'DEALLOCATE'/

Map to the Glooal Data Section 'LABIO.COMMON'
And Define the Commom Event Flag Clusters
Reauest write access to the data base.
Cal 1

LABIO~INIT

C 1 )

See if ma;lbox LA8IO.C0NNtC1 exists Oy attempt;ng to assign it, ;f
;t does not e~ist, create ;t. This mail~ox is used to commun;eete with
other LABIO Processes, Restrict it to orocesses ~ithin this group,

SUCCE58 : SYSiASSIGN('LABIO.CONNECT',MBX.CrlANNEL,,)
If (,not, SUCC~SS l T~en
SUCCESS= SYSIC~E~BX(,MBx.CHANNtL,,,%Va1C'FD00'~),,'LAB!O~CQNNECT
If c.~ot, SUCCESS)
1
Call FATAL 4 f~ROR( SUCCtSS, 'Cresting mailbox')
End If
Tell other processes tnat we're reaay to qo,
Ca l l

SYS.:}) SE TE:. F ( 'Z v a 1 C EF

£ Get a command

fro~

.c 0 ~ i EC T )
•,j

e reauesting processes

7-16

PROGRAM EXAMPLES

Ca11 READ 4 MAILBOX
Ca1l CONNECT.CHECK

!Get a message
ICheek the database to clear
1eny deleted processes.

lf I/O status is EOf then process has term;nated, ABORT it,

If (

MBX~IO~STATUS

,eQ, %Loccsss.ENDOFFILE) ) Go To 23

Decode characters as a comm.and

If c MBX.MESSAGE.L ,eQ. 0. ) Go To 10
Decode (MBX.MESSAGE.L,100,MBX.MESSAGE,ERR:10) COMMAND
Search Command Table for

Com~and

Do 11 COMMAND.INDEX :
If ( COMMAND ,eo,

1,MAX.COM~AND

COMMAND~TA~LE(COMMA~D~INDE~l

) Go To 12

Continue
Go lo 13

1I11ega1 command

D1speteh to correct rout;ne

I If we get here,
13

it~s

an unknown command

Cal 1 LABIO..,.LOG(•l)

l CONNECT command

1
21

RETUHN ... CODE : CON~~CT (MBX.PID)
Call ACKNO~LEOGE( RtTURK.COUE )

IAcknowleage the reouest

Cal, LAaIO""'L.0(; ( Rf;,TIJRN.._COOE. )

1~og

the aek!'lowleogement

Disconnect if was bad connect
I f cRE:.T uR N .. c 0 l) E • !'I e •
Go To U1

DISCONNtCT
22

)

c a l 1 () l s c 0 N N t:. c T ( .. l )

Com~ano

RETuR i~ .. c oc· E =

o I s c c ~n Ec r
1

( t.I\ ~ x., P 10 )

Call LA8IO.,..LOG C RElUkN.CODE )
Go To iv1

ABORT commana

RE:.TUkN.,..CODE:
Go To 4fl1

Ad()iiT

(•--H).X,..Pli;)

7-17

lLog the acknowledgement

PROGRAM EXAMPLES

ALLOCATE command
RETURN.CODE
Go To 40

Al.L.OCATE CMBX 4 P ID)

DEALLOCATE command

RETURN..,.CODE ;: DEALLOCATE
Go To 40

Return status 1n first

(MBX.a.PID)

cnaract~r

Position

Call ACKNOWLEDGE( RETURN~CODE
Call LABIO.LOGC RETU~N 4 CODE )

LAcknowledge the reQuest
1Log the acknowledgement

Go To 10

Forrnets

100

Format CA)
Erid

Subroutine CONNECT.CHECK
This routine checks to make sure all processes
connected Cin CONNECT.BLOCK) actually exist.
If a process has been de1eted, this routine
removes it from the database by calling ABORT
Include 'LA8CHNDEF.FOR'
Logical•4 SYSSGETJPI

Do 10 1 : 1 1 MAX.PIO
PIO: CONNECT.~LOCKCI,ll
If C PID ,ne, 0 ) Then
I'fC ,not.

SYS$GETJPl(::(ValC2),P!D,,~,,,)

Ef"ld It

Contil"lue
Return
End

Logical•U Function REA0 4 MAILBOX

This routine ~eads the LABIO.CON~EtT mailbox
Returns when a messaqe is reedy
External I0$~RcADVBLK
Include 'LABMBXDEF.FOR'
Logica1*4 SYSSQIO~,SuCCESS

7-18

) Call ABORT( P!I))

PROGRAM EXAMPLES
Read for a message f rQm another process
MBX.READ=%~0CCIOS.READVBLK)

MBX~MESSAGEC1)

: ' '

REA0 4 MAILBOX : SVS$QI0W(,XVa1(MBX.CHANNEL),%ValCMBX.READ),
1
MBX.ro.sTATUS,,,MBX.MESSAGE,
1
%Va1(MAX 4 MESSAGE),,,,)
Return

End
Log1ce1•4 Function WRITE 4 MAILBOXCMBX.CHAN,MESSAGE,MESSAGE 4 ~ENGTH)
This routine writes a message to a mai1box
Input are tne MBX channel, the message, and message length
External l0$.WR!TEVBLK,I0$M 4 NQW
Logical SYSiQIO

Write response buffer of MBX
MBX.wRITE =XLocCIO$.WRITEVBLK)+XLocC!O$M.NQW)
WRITE.MAILBOX:
1
qq

SYS$QlO(,XVa1CMBX 4 CHAN) 1 %Ve1CM6X~WRITE),,,,
~ESSAGE,XValCMESSAGt 4 LENGTH),,,,)

Return
End
Logieel*4 Function

OPEN.MAJLBOX(MAILBOX~CHAN,MAILBOX.NAME)

This routine opens mailbox 1nd1ceteQ bv MA!LBOX 4 NAME. It returns
tne VMS cha~nel number assigned to it, The mailbo~ name een be
padded on the right with blanks,
Character•(*) MAILBOX.NAME
Integer
MAIL~ox.CHAN
Logical*Q SYSSASSIGN,SUCCESS

Determine 1enqth of maf lbo~ name string
MAILBOX.NAME~L=Index(M~1LBOX 4 NAME,' 'l•l
If C~AILBOX~NAME~L ,lt. ~ ) MAlLBOX.NAM~ 4 L:Len(MAIL~OX~NAMEl

Assign a channel to mailbox
Return status to C$ller

Return
End
Svbrouti~e

ACKNOWLEDGE

(~CK.CODE)

Tnis routine ac~nowlegdes a reQuest of process, by retur~ the
command string the process sent us. The string 1s oreceded

7-19

PROGRAM EXAMPLES

en acknowledge code (ACK.CODE), The acknowledgement 1s sent
vie the mailbox the the sending processes had created,
If that process hes not connected to us, we do nothing,

Include 'LA8CHNDEF,FoR•
Log1ca1*4 WRITE.MAILBOX
Include ·LABMBXOEF,FOR'
Integer CONNECT.INDEX,CHECK.PIO,AC~~CODE
If process is not in CONN~CT.BLOCK, do not respond,
CONNECT.INDEX : CHECK.PIDCMBX.PIO)

If CCONNECT.INOEX ,ne, 0 ) Then
Encode( MBX.RESPONSE.L,1~0,MBX.RESPONSE) ACK 4 CODE
MAI~SOX : CONNECT.BLOCKCCONNECT.INDEX12l
C$ll ~RITE.MAILBOX( ~AILBOX, MBX~RESPONSE,
1

M6X.MESSAGE.L

MBX.~ESPONSE.L

End If
Return

100

Format C I2 )
End

Subroutine LABIO.LOGC CODE J
This routine logs a measage that has been proeessed, The message
1s written to the log file, along with the time, process IO, IO status
word and the message length, This routine coens the log file
if it hasn't been opened.

Charaeter•24 TIME
Logical LOG.OPEN
Integer CODE
Data LOG.OPtN/,false./

Call

1Get the date

SVSS~SCTIMC,TI~E,,)

a~d

time

Open Log file if this is the first time thru

If C ,not, LOG.OPEN ) Then
Open CUnit = 1, Na~e='LABIO.LOG', lype:'Unknown', Access = 'Apoenc
LOG.OPEN : ,True,
~riteCl,100) TIME,' Labio Log Opened'
End If
10

Write(1,200)
1

TIME,MBX.?ID,M8X.IO~STATUS,~BX4MESSAGE.L1
CODE 1 (M8X~MESSAG~CilrI:1,MoX.,MESSAGE 4 L)

Return
100

Format( 2A )

7-20

PROGRAM EXAMPLES
200

Formate A,Z10,z10,110113,128A1 >

End
Integer

F~nction

CONNECTCREQ.PID)

Include 'LABCHNDEF,FOR•
Include 'LABMBXDEF,FOR'
Character*o3 MAILBOX.NAME
Integer•4 REQ.PIO,CHECK.PID
Logiea1*4 OPEN.M~ILBOX

CONNECT

Find an empty CONNECT.BLOCK slot

Do 10 I : 11 MAX 4 PID
If C CONNECT ... BLOCKCid)
Continue

1 eQ,

O )

Go To 20

We should never get here, s;~ce the last slot of
the CONNECT.BLOCK is a spare for sending message
disa1lowing a connect&
Go To qq
Ope~

user specified MAILBOA

Decode (MBX.McSSAGE~L,100,M8X.MESSAGE) MAIL60X.NA~E
If( .not, OPEN.MAILBOX( MAIL80X~CHA~,MAIL80X~NAME)

Go To qq

Allocate the eon~eet block, if it is not a duplicate
PIO, store the PIO and mailbo~ channel in CONNECT~BLOCK
If it is a duolicate, store tne PIO as •1,
If C CHECK.PIDCREQ.P!Ol ,eo, v.i l Tnen
CONNECT ... BLOCK(l,1) : fH C~ ... PI D
CUNNECT : 0
Else

1Dupl1cate PID1 we will DiseonMeet
lAfter Ac~nowledging reouest

CONNECT 4 BLOCKCI,1) : •1

If C I ,ge. MAX.PIO ) CONNECT : 1 lNo room for process£
qq

Ret1Jrn

10~

FormatClSX,A)
f.nd

Integer Function

DlSCONNECTCHE~~PlD)

Tnis routine disconnects a process from tne LA8IO system,
If it is a valid process, all CManriels still allocated are

7-21

PROGRAM EXAMPLES

deallocated, the reouest is ae~nowledged, t~e channel assigned
to the mailbox is oeessigned, and the CONNECT.B~OCK ent~y is removed,
Include •LABCHNOEF,FOR'
Integer•4 REQ 4 PIO,CHECK.PID
DISCONNECT : 1
F1~d

index into connect block
CONNECT 4 INDEX : CHECK.PIDCREQ.PlO)
If CCONNECT.INOEX ,eq, ~ ) Go To qq 1Not connected

Deallocate all AID cnennels

Acknowledge DISCONNECT reouest
Call

ACKNO~LEDGE(0)

Close the mailbox, and zero

CONNECT.~LOCK

Call SYS$0ASSG~( XValCCONNECT~BLOC~CCO~NECT~INDEX,2l)
CONNECT.BLOCKCCONNECT.INDEX,1) : ~
.
CONNECT.BLOCKCCONNfCT.INDEX,2) : 0
DISCONNECT =~
qq

Return

l~teger

Function A80RTCRtQ 6 PlDl

Call DISCONNECT( REQ.PID)
Return
End

Integer Funct;on ALLOCATECREQ.PID>

This rout1nes allocates an A/D channel to a specific orocess.
The process request a channels by numoer (1•1o), specifing
the aeemple rate in tics/samole, tne buffer size in ~ords, ano
tne number of buffers to acquire C 0: tnfinity ), The user can
default the rate to 1 t1c/samole, Default the ouffer size to
t~e maximum, and the buffer count to 0, If the user reallocates
the channel, tne aefaults are the previous values allocated,
The channel must been INACTIVE if it is reallocated,
Inelude 'L4BCHNDEF,FOR'
lncluoe 'LA8M8XDEF,FOR'

I"teger•4 REQ~PIO
Integer*4

PA~M(Q)

1PlD of reQuesting proe•ss
l4 input parameters

Integer•2 CONNECT 4 I~DEX,CHECK.PID
Integer•4 RE~.•o.CHAN,RtQ.TICS,REQ .. 8uF.SilE,REQ.BUF.COUNT

7-22

PROGRAM EXAMPLES
~ogical

Get 1ndex into CONNECT.BLOCK tor REQ.PID
If iMde~ is not > 0 , ignore request
AL~OCATE

: 1

£Checking first field

CONNECT.INDEX : CHECK.PIDCREQ.PID)
If ~ CONNECT.INDEX .le. 0 ) Go To qq £ReQ, Proc not conneetedl
Decode message into four fields

1Reouested AID channel is first
1T1es/sample is 2nd
1Huffer s;ze is 3rd
.Nu~ber of cuffers is 4th

REQ.AD.CHAN : PARM(l)

REQ.TICS

: PARM(2)

REQ~6UF.SIZE: PARM(3)
REQ~BUF.COUNT:PARM(4)

ALLOCATt

p~rm

lCheck next Parameter (channel number)

1 Valid channel numbers are l•lb

Requested c~annel must not allocated, or
allocated to the requesting Process
AD.BLOCKC2,REQ~AO~CHAN) ,ne, 0 ,and,
AD.6LOCKC2 1 REQ.AD.CHAN) ,ne, REG.PIO

Go To 99

1 The channel must not be active
If CAD.BLOCKCl,REQ~AD.CrlAN) ,gt, INACTIVE

Go To 99

If (

A~LOCATE

: 3

1Cneck1ng ~ext parm (Tics/sample)

Tics/sample must be between 1 and 2·31•1

If( ,not,
1

CHtCK.PARMCREQ~TICS,AD~BLDCKC3,REQ~AD.CHAN),

11'7FFFFFFF'X,1) ) Go To qq

ALLOCATE : 4

lCMeck;ng

parmeter (Buffer size)

Buffer size between 1 ano MAX.tiUF.S!ZE
If(

.not,

CHEC~ 4 PARMCREG.~Uf.SIZE,AD~BLOCK(4,REQ~A0 4 CHAN),
1,MAX.BUF.SlZE,~Ax.auF~SIZE) ) Go To qq

ALLOCATE : 5

£ Check1n.g

ne~t

parameter (number of buffers)

Number of buffers to acquire must be between 1 and 2·31•1, or
zero to inoicate no 1;m;t
If C ,not,

CHECK~PARM(REQ~BUF~CGUNT,AD~6~0CK(5 1 REQ.AO~CHAN),11

'7FFFFFFF'x,~)

ALLOCATE : 0
Enter info into AO.BLOCK

7-23

) Go To qq

PROGRAM EXAMPLES

ILock tne date base
Clear associated event flag$
Ca11 SYS$CLREFCXValC EF 4 NOTIFY.OFF +REG.AD.CHAN) )
Call SYS$CLREFCXVe1( ~F.ACTIVITY.OFF + REQ 4 AD~CHAN) )
Call SYS$CLREF(XValC EF 4 STATUS 4 0FF + REQ 4 AO~CHAN) )
AD 4 BlOCKC2,REQ 4 AD.CHAN) : REQ 4 PIO
AD.BLOCK(l,REQ 4 AD.CHAN) : REQ 4 TICS
A0 4 6LOCKC4,REQ 4 AD~CHAN) : REQ 4 6UF.SIZE
AD 4 BLOCK(S,REQ.AO.CHAN) : REQ.SUF.COUNT
AD 4 BLOCKC6,REQ 4 AD~CHAN) : 0
AD 4 BLOCKC7,REQ 4 AD 4 CHA~) : 0
AD 4 BLDC~(8,REQ 4 AD~CHAN) r 0

A0 4 8LOCK(Q,REQ 4 A0 4 CHAN) : 1
AD 4 BLOCKC10,RtQ 4 AD.CHAN) : 0
AD.BLOCKCll1REQ.A0 4 CHAN) : 1
A0 4 BLOCKC121REQ.A0 4 CHAN) : 0
A0 4 BLOCK(t,REQ 4 AD.CHAN) : INACTIVE
Return

!Requesting PIO
llics/semple
1Reauested buffer size
1Number of buffers to acQui
1No buffers acQuired
£No oete buffer available
£Number elements in last bu
!Current buffer index
!Current buffer count
1Tics remaining
lOffset to next data Point
!Channel is inactive

Error returri
qq

Return

100

FormatClSX,41)

1Returl"! to caller

End
Integer Function DEALLOCATECREQ.PlDl
Tnis routine deallocates a cnannel prev;ously allocateo by
a process. The channel must be INACTIVE when deallocated,
Include 'LAHCHNOEF,FOR'
Incluoe 'LABMSXOEF,FOR'
Integer•4 RtG.PID
lPlD of reQuesting process
Integer*2 CONNECT.INOEX,CHECK 4 PID
Integer•4 REG.AD.CHAN

Get index into CONN~CT~BLCCK for REQ 4 PJO
If index 1s not > 0 , ignore reauest
OEALLOCATE :

CONNECT.IND~X : CHECK.PIDCPID)
If ( CONNECT~INOEX .le. 0 ) Go

lo 99

Of.ALLOCATE : 2

1 Valid c~annel

nu~bers

are 1•16

1 Does reauesting Drocess own the

chan~el?

DEALLOCATE : 21

7-24

PROGRAM EXAMPLES

l Is

t~e

channel inactive, clear the channel parameters
DEALLOCATE : 22

If C AD.BLOCKC1 1 REQ.AD.CHAN) ,ne.
Cell

!~ACTIVE

) Go to 99

AO~CANCELCREQ.AO.CHAN)

lEverything

DEALLOCATE : 0

Ret u l"r'I
ERROR

retur!'I

Retu,.n

entry point is used to deallocate a11 channels
allocated toe spec1fic process,

T~is

Entry DEALLOCATE.ALLCREQ.P!D)

DEALLOCATE : 1
1 Valid PIO?

CONNECT.INDEX : CHECK.PIDCPID)
If C CONNECT.INDEX ,ne, 0 ) T~en
Look for all AID c~anne1s allocated to Process
and eeneel all I/O unconditionally,
Do 10 A0 4 CHA~ : 1 , MAX~AD.CHANNEL

If C AD 4 BLOCKC21AD.CHAN) ,eq, REQ.PIO) Call
Continue
DtALLOCATE 4 A~L : 0
El"ld If

100

AD~CANCELCAO.CHAN)

Return
Fo,.matC15X,I15)
E!"ld

Clears the paramete,. table associated w;th A/O channel

ll"lclude ·LABCHNDEF,FOR·
!l"lteger CHANNE:.L

AD.CANCEL : 1

1 Assul'l'le erro,.

Legal ct-1anne1 numbers a,.e 1•1t.>

Zero the AD.BLOCK for

t~is

Do 10

J :

AO~BLOCK(J,

AO,,.,CANCEL :
E.Md IF

1 ,

c~a~nel

lC:lear everth1ng

CHANNEL
Hverythfng 01c

7-25

PROGRAM EXAMPLES

Clear a11oc1ated event flaQs
Call

SYStCLR~f(XValC

EF 6 NOTIFY.OFF +CHANNEL)

Call SYS$CLREFCXVa1C EF 4 ACTIVITY 4 0FF +CHANNEL

Call SYS$CLREFCXVel( EF 4 STATUS.OFF +CHANNEL)
qq

Retul"n

End
Logical Function CHECK.PARM(IVAL,OVAL,~IN,MAX,OEFAULT)

This routine validates and defaults an 1nPut parameter CIVAL)
If IVAL is not 0, it comPares it to MIN end MAX, returning TRUE or FALSE,
It IVAL 1 s 0, ar1d OVAL is riot zero, !VAL : OVAL
If IVAL is 0, and OVAL ;s zero, !VAL : DEFAULT

= ,false,

CHECK 4 PARM

lassume the worst

If CIVAL ,ne, 0 ) Then

If( !VAL ,lt, MIN ,or, JVAL .gt. MAX) Go To qq

Else

If (OVAL ,ne, 0 ) Then
!VAL : OVAL

E 1 se

!VAL : DE.FAULT
End If
End IF

Return

END
Integer Function CHECK 4 Pl0(Pl0)
Th1s l"OUtine checks to see if a PIO is in CONNECT 4 8LOCK
If it is, t~e INDEX into CO~~ECT~BLOCK is returned, If
it isn't, 0 is returned
Include •LA8CHNDEF.FOR'
Integer•4 PIO
Assume PIO is not in d8tabase
CHECK ... PID :

1 If PID is

fou~d,

Do 1'1 I :

return
1 ,

inoe~.

r-1AX .... Pl0

If( CONNECT~aLOCKCI1ll .ea. PIO ) CHfCK4PIO = I
Continue
Return

t 1"1 d

7-26

PROGRAM EXAMPLES
&File&

LABIOSTAT,FOH
Program LABIO.STATUS
1 This is a utility routine for the LABIO system, It displays
l the status of all lb channels of the AID, It assumes that
l the terminal 1s a VT52 or an equ;velent, e,g VT10~ in VT52 mode,
I The display 1s update once every l•q seconds, Default is
1 one second, There are S commands assoc1ateo with the program

''
''

''
''
''

C •display status of lb channels
P • display status by process PIO
H • d;sPlaY help frame (timeouts after 1 m;n,)
E • Exit to VMS DC~
Dig1tC1•9) Change cycle ti~e,
The key pad cen also be used to enter commands, T"e special function
Keys on the Vl52 or VT100 correspono to the first 4 commands (3 on VT52),

' Typing ANY key will cause a display refresn,
Include

'~ABCHNOEF,FOR'

Character•10 STATUSC4)
Character•8 XTlME
Cnaracter*q XDATE
Parameter COMMAND.MAX : 4
Charaeter*l COMMAND,COMMAND.TABLECCO~MAN0 4 MAX,2),ESCAPE,TERMINATOR
Character•b3 COMMAND~DEV
External sss.NOTRAN,SSi4NORMAL,SS5.PAR1ESCAPE
External !0$M.CVTLOW,1U,M 4 NOECHO,IOS~.TIMEO,IO$.READV8LK,l0$M•PURGE
Logical SUCCESS,SYSiQlOW,SYS!ASSIGN
Integer CHANNEL,OISPLAY.FLAG,ULD~OISPLAY,COMMAND~CHAN
Integer DEF~TIME.OUT,TlME~OUT
Byte
ERASE 4 SCREENC2),HOME(2),ERASE.LINEC2),VT~2 4 MODEC7l
Integer*2 !O~STATUS(UJ,CHAR.COUNT
Equivalence (~SCAPE,rl01E),(CrlAR~COUNT,IO.STATUSC2J)

VTS2 control ESCAPE Sequences
Data HOME,ERASE.SCREEN,tRASE 4 LlNE
1
1'33'0r'H','33'0,'J','33'0,'K'I
VT100 control ESCAP~ sequences
This ESC sea Places a VT100 in VT52 mode

Data STATUS/'Unknown ','!~active',' Active ' , ' ' I
Data COMMAND~TABLE/'C','P','E','H','P','Q','S','R'/
Data OISPLAY.FLA~,tRASE.FLAG 11,,TRUf,/
Data DEF.TI~t.OUT 111
Map to the

GLO~AL

DATA

sectio~

created by the IIO program

Cell LA6IO.INIT(0)

7-27

PROGRAM EXAMPLES

Place VT100's in VT52 mode
Type 500, VTS2.MOOE
Initialize Command inout channel
We will read the comma~d via a QIO~ w~th a 1 se~ timeout
Comma~ds are single character, to simplify ~atters we will
read witn no echo and convert lo~er to upper ease.
Call SYS$ASSIGN( 'TT',COMMANO.CHAN,,,)
QIO.REAO = r.Loc(I0$M.NOECH0) + %LocC10$M.CVTLOw) + %LocCl0$M.TJMED)
1 + %Loc(IOS.HEAD~8LK)
TT.PURGE = %LoeCI0$M.PuRGE)
Go To 25
1 Display Something

£ Get a command

fro~

the user, but onlY wait a short time (TIME.OUT)

1 so we can update the screen. The input buffer is purged if e command
1 was decode on the last read, CPreve~ts unnecessary erase loops)

OISPLAY 4 FLAG : OLD 4 01SPLAY £Default is last display
TI~E.OUT : DE~.TIME.OUT
1Defeult time out

TABLE.INDEX : 1

Call SYS$QIOWC,%ValCC0MHANO•CHAN),%Val(QIO.REAO+PURGElr
1

LAssume no escape seQuence

ro.sTATus,,,%RefCCOM~~~D),r.Va1(1),%Va1CTIME.OUT),,,,)

PURGE :

If escape seq., set command table poi~ter to seco~d table and
get Character following escape,
TERMINATOR = Cha~c IO~STAfU5(3) )
If( TERMINATOR ,ne. ESCAPE ) Go To 23
TABLE 4 INDEX : 2
Go To 22
1Get c~ar following escape
23
If ( CHAR.COUNT ,ne. 0) Then
l Char count not 0
1 Check tor enar l•q
If( COMMANC ,ge. '0' .and, COMMAND ,le. •q• ) Then
DEF~TIME.OUT : Ic~ar C COM~AND J
• lchar( '0' )
L Not 1•9 try a commend,
Else
ERASE.FLAG : ,true,
1 Screen erase
Do 24 I : 1,COM~AND.~AX
lfC CUMMANU ,ea. C0MMANO~TA8Lt(I,TABLE~lNOEX)) DISPLAY.FLA~: I
24
Continue
Eno If
PURGE = TT.PURGE
IPurge the ;~put buffer next t;me
End If
1 Get date

and

time,

then

dispatch to aisolav routine

Call
Call

Go to

CXDATt)
TIME CXTIME)

OAT~

CS~,b0,99,4~)

DISPLAY.FLAG

screen

an~

I Refresh

the

(~rase

Red;solay)

1
3~

DISPLAY.FLAG : OLD 4 DIS~LAY
E~ASE.FLAG : .true.

7-28

P~OGRAM

EXAMPLES

Go To 25

' 1pl1y
I Df

the HELP frame, 1et tne temporary t1me•out to 1 minute

&Disp1ay the help fr1me
1Give the user 1 minute to reed 1t
IWhe~ 1t times out, d1f1ult old

Type &00, HOME,ERASE.SCREEN
TIME.OUT a b0
DISPLAY.FLAG s OLD.DISPLAY
ERASE.~LAG • ,true,
Go To Z1

'I Ge"er1te the Statue Line for each AID

ch1~nel

If C ERASE.FLAG ) Type 300, HOME,ERASE.SCREEN
Type 100, HOMf,XTIME,XDATE
CHANNEL.COUNT • 0
Do 51 CHANNEL • 1 1 MAX.AD.CHANNEL
lf( AD.BLOCKCZ,CHANNEL> ,ne, 0) Then
1If el located, d11pl1y 1nfo
Type 200,CHANNEL, STATUSCAD.BLOCKC1,CHANNEL)+1),
1 CAD.BLOCKCJ,CHANNEL), J • 2,b )
CHANNEL 4 COUNT • CHANNEL+COUNT + 1
El••
1If not alloc1ted, ••Y 10
Type q00, CHANNEL·•<Unused>•,ERASE.LINE
End lf
Continue
PIO COUNT • 0
Do S2 PIO.INDEX s 1, MAX.PIO
PIO• CONNECT+BLOCKCPID.INDEX11)
If C PIO ,ne, 0 ) PIO.COUNT • PIO.COUNT + 1
Continue
Type 400,ERASE.LINE, PID.COUNT,CHANNEL.COUNT
OLD.DISP~AY • DISPLAY.FLAG
ERASE.FLAG • ,fel11,
Go to 20

'&
'

St1tu1 d11pl1y v11 proce11 CPID>

If C ERASE.FLAG ) Tyoe 300, HOME,ERASE.SCREEN
Type 100, HOME,XTIME,XDATE
Number of connected proce11e11
PIO.COUNT • 0
Number of allocated channels
CHANNEL.COUNT • 0
Do bl PIO.INDEX s 11 MAX.PIO
PIO• CONNECT.BLOCKCPID.INDEX,1)
If C PIO ,ne, 0 ) Tnen
PIO.COUNT = PIO.COUNT + 1
OLD~COUNT • CHANNEL.COUNT
Do o2 CHANNEL = 1, MAX.AD.CHANNEL
If( AD 4 BLOCK( 2,CHANNEL) ,eQ, PIO ) Then llf right PIO, d11play info
Type 2~0, CHANNEL, STATUSCA0 4 6LOCK(1,CHANNEL)+1),
(A0 4 BLOCKCJ,CHANNEL), J = 2,o )
CHANNEL 4 COUNT = CHANNEL.COUNT + 1
End IF
Continue
If COLD.COUNT ,eq, CHANNEL.COUNT ) Tv.pe 80~, '<None>',PIO,ERASE.LINE
End IF
Cont;nue
Type

~00,ERASE.LINE,PID.COUNT,CHANNEL.COuNT,ERASE.SCREEN

OLD 4 DISPLAV : DISPLAY.FLAG
ERASE.FLAG : ,false,
Go to 2~

7-29

PROGRAM EXAMPLES

Ex it

Cal 1 Exit

1 Format Statments
1
100

Lab IO Status as of
PID
Tics/Sample

FormatC1X,2Al,'
1' Channel
Status
1
Buffers '/)

',A,' ',A//
8uffer Size

200

FormatCIS,Sx,A8,Z10,4I12l

300

Format(' ',4A1)

400

Format(' '2A1/' Totals: '1!21' Processes connected
'1121'
1 allocated'/'
<Type an H for helo>'2A1~)

500

Format(' '7Al)

b00

Format(' '4Al/
1' Tne following comm.ands ere available:'//
1'
VT100
VT52
anv'/
1'

••••••

••••

C~annel

•••'I

700

1'
PFl
red
C
Channel Display'/
1'
PF2
blue
P
Process OisP1$Y'I
1'
PF3
grey
H
Help Cisplay'/
1'
?F4
n/a
t
tx1t'//
1' To change disoley t;me1 type a digit 0-q for the desireo t1me'//
Format CA)

q00

formatCIS15~,A8,2A1)

End

1LEnd of FileJ

lfi1e:

LABIOPEAK,FOR

Program ~ABIO~?EAK
This routine continuously samples channel ut search for peaks,
Tl'le sample rate is 1/TIC. It reports the PEt.K height end oosition
to logical chal"\nel "L.AtHO..,.l'EAK4DATA"

Parameter MBX~NA~E = 'LABIO.PtAK'
Character*130 RETJR~
Cnaracter*15 COM~ANO
Character*24 DATE 4 TI~E
Loqical*~

SUCCESS,SYS~CkE~Bx

Parameter AD 4 CHANNEL : 1

7-30

Channel Number

PROGRAM EXAMPLES
Parameter AO.RATE = 1
Parameter AD 4 bUF.SIZE : 512

Rate
Suffer S1ze

Parameter MAX.PEAKS : 10
Integer*4 ITABLEC10),INLAST1I~PTR10UTPUT(2,MAX.PEAKS),IDI~O,NPEAKS
Integer*2 INPUTCAD.BUF~SIZE*2)
o~~a

ITABLE/10•01

Data

INLAST,INPTR,IOI~O,NPEAKS/0,0,MAX.PEA~S,0/

Map To the Global Oata Base and the event f1egs
Call

LA8IO.INITC0)

Open Ma1lbox to LA8I0 4 CONNECT
Open C Unit : 1, Name

= 'LABIO.CONNECT' , Type : 'OLD' l

Create Mailbox for response from
SUCCESS:
If C.not.

LAB!O~CONNECT

SYSSCREM8X(,MSX.CHANN£L,,,%Va1('fD~0'~),,MBX.NAME)

S0CCfSS )

Call FATAL.ERROR( SUCCESS, 'CREATING MAILBOX')

Open via FORTRAN
Open C Unit : 2, Name = ~ax~NA~E, Type
Deassign

t~e

= 'OLD'

channel assigned when we created 1t

Call SYSiOASSGN(

~VelCMBX.CHA~N~L)

)

Open A Data File

Connect to

t~e

COMMAND

LABIO system

= 'CO~NECT'

Write(l,1~0)

COMMAND.~ijX4NAME

wait for Response from LABIO system
Read(2,200) RETUR~~CODE,RETURN
lf ( RETURN.CODE ,ne, 0 ) Go To 99

1Fa11ed to

co~~ectl

Allocate Channel AD 4 CHANNEL
Rate : AO~RATE
Buffer size : A0 4 BUF~SIZt
COMMAND : 'ALLOCATE'
~rite(l,400)

Read(2,200)

If(

CO~~AND,A0~CHANNtL,AO.RATE,4D~&UF~SlZE 1 0
RtTU~~.CODE,R~TUR~

RETUR~.COOE

.~e,

0 ) Go lo 99

1Failed to allocatel

Enable deta acqusition by setting event fla9 ACTIVITY ena NOTIFY
Cell
Call

SYS$SETEF(%Va1CEF~ACTIVITY~QFF+AO~CHANNEL))
SYSSSETEF(JVelCEF~NOTIFY.OFF+AO.cHA~NEL))

l Now, wait for buffer to oe fi11eo, event flag STATUS will be set

7-31

PROGRAM EXAMPLES

when data

ready

e~e

Call SYSSWAITfRC XVa1CEF 4 STATUS+OFF+AD.CHANNEL)

Buffer is filled, get the buffer ;ndex

INDEX :

AO~BLOCKC7,AD.CHANNEL)

Move data from data buffer to ceak

proeessi~g

buffe~

= 1, AD.auF.SIZE

Do 10 I

INPUTCI+INLAST) : DATA 4 8UFFER(I,INO~X,AD 4 CHANNEL)
INLAST : INLAST + AD 4 8UF~SIZE

1 Clear the STATUS event flag and notify the I/O Process
1

Call SYSSCLREFC

XValCEF~STATUS~OFF+AD 4 CHANNEL)

)

1COEBUG) only
1
Write (3,6~0) COATA.BUFFER(I,INDEX,AC.cH4NNEL),I:1,AD4BUF4SIZE)
1
I Call the peak orocessing routf~e
1

Call

PEAKCITABLE,I~PUT,INLAST,INPTR,OUTPUT,MAX 4 PEAKS,NPEAKS)

Report tne oeak ;nfo
1Rememte~

the peak switch

If ( NPEA~S .ne. 0 ) Then
1we have some peaks
If( NPEAKS .1t. 0 ) NPEAKS : MAX~PEAKS 1~E have the max
Do 20 I : 1, NPEAKS
TOTAL 4 PEAKS : TOT4L 4 PEAKS + 1 !One ~ore
Write(3,500J TOTAL.PEAKS,(OuTPUT(J,I), J = 1,2)

E"'d I1
NPEAKS

Move any

PEA~ 4 SWlTCH

If(

u~orocessed

.lt,

!Reset the pointer
) Go To 15 1More oeaks to find

data to the

~egi"'n;ng

of the input array

If C C!NPTR ,gt. 0) .a"d• CINPTR .lt. INLAST) ) Then
Do 30 I : 11 !NLAST·I~PTR
INPUTCI) : INPUT( INPTR+l )
1Move the data
IN~AST = l
llast element stored

Else

INLAST:
Er"d

1Last element processed

Ir-.PTR : 0

Go wa;t for more data
1 All

ro 5

done,

Call

the exit

Cal!

100

Format(' •,A,A)
formatCI2,A)
Format(' ',A,uJ)

2~0

400

EXIT(ll

routine
! Ex i t

7-32

PROGRAM EXAMPLES
500
b00

Form1tC3I10)
Formet(IS)

End
ICEnd of File]

&File PEAK,FOR
Subroutine PEAKCITABL~1INPUT,INLAST,INPTR,OUTPUT1lDIMO,NPEAKS)
IA tr1v1e1 Peek•p1ck1ng routine, The ca111Mg sequence 1• patterned
&•fter the LSPLIB routine PEAK,
Integer•~ ITABLEC10),0UTPUTC21IDIMQ),INLAST,INPTR,IDIM0,NPEAK
lnteoer•2 INPUTC1)
Perimeter NOISE ~ 5
1No1se value = 5 A/D units

&ln1t1e11ze some p1rameter1, if necesary
lfC NPEAKS ,lt, ~ ) NPEAKS = 0
lfC INPTR ,lt, 0) INPTR : 0
&F1rat time thru?
IfC INPTR ,lt, INLAST ,and, ITA6LEC1) ,eq, 0 ) Then
lNPTR s lNPTR + 1
ITABLEC1) a 1
&Assume we're ria1ng
ITABLEC2) : 1
&first point
ITABLE(3) a INPUTCIN?TR)
End If
IAny date to process?
If(INPTR ,1t, INLAST ) Then
Do 10 I • INPTR+1 1 lNLAST
IfC ITABLEC1) ,gt, 0) Then 1we're rising, look for a fell
lfC INPUTCl) ,lt, ITABLEC3)•NOISE ) Then &we found a pe1k
If( NPEAKS ,lt, lDlMO) Tnen lAMy room to store it?
NPEAKS m NPEAKS + 1
OUTPUTC11NPEAKS) : ITABLEC3)
OUTPUTC2,NPEAKS) : ITA8LEC2l
ITABLE(l) : •1
Else
lNo, tell user
INPTR : I • 1
NPEAKS : •lDIMO
Return
End If
End If
~lse

lfC INPUTCIJ ,gt.
10

End If
ITABLE(3) :
ITABLEC2l :
End If

we found e valley
: 1

1~e're falling, see if
ITA8L~C5)+NOISE )
ITA8L~(l)

JNPUTCil
JTABLEC2)

INPTR : •1
Return

1Nor~a1

7-33

e~it

ell data processed,

PROGRAM EXAMPLES

1Ff lei

LABIOSAMP,FOR

This program samples channel #2 once every 10 aeconds,
It aeQuires 10 ooints at 1/tic, averages them and then
RePort• tne date, t1me, and average value o~ logcia1 device
LABI0 4 SAMPLE.DATA
Include 'LABCHNDEF,FOR'
Parameter ~BX.NA~E = 'LA8IO~SAMPLE'
Charaeter•130.RETURN
Cnaracter•lS COM~AND
Character•24 DATE.TIME
Logiea1•4 SUCCESS,SYS$CREM6X
lnteger•4 DELTA~TIMEC2),NEXT~TIMEC2l
lnteger•4 AVER~GE

Channel

Parameter AU 4 CHANNEL : 2
Parameter AD 4 RATE = 1
Param~ter AD 4 bUF~SIZE : 1~
Parameter SAMPLE 4 RATE : '0 ~sH:10'
Parameter ~AX 4 SAMPLE : 10 0~~
Map To the Global Oata Base
Cell

and

Maximum

samples

the event flags

LABIO.INITCJ)

Open Mailbox to LAdIO.CONNECT
Open C Unit : 11 Name :

Create

'LAB!O~CONN~CT'

, Type : 'OLD' )

for response from LA2l0 4 CONNECT

~a11bo¥

SUCCESS=
If C.not,

SYS$CREMBX(,MBX.C~A~NEL,,,xval('FD00'x),,~sx~NAMf)
SUCCESS) Call FATAL.~RRORC SUCCESS, 'CREATING MAILBOX')

Open vie FORTRAN
Open (
Oeassig~

U~it

: 2, Name : MBX.NAME, Type : 'Old'

the channel

assigne~

Call SYS$DASSGN(

when we createo ;t

%~al(M8X~CHA~~EL)

)

Open A Data File
Open( Unit : 31 Name : 'LAB.SAMPLE.DATA', Type :

Connect to the LABIO system
COMMAND

= 'CONNECT'

~rite(l,100)

Wait for

~esponse

COMMAND,MBX~NAME

from

LA~IO

system

7-34

'N~w'

)

PROGRAM EXAMPLES

ReadC21200l

RETURN~CODE,RETURN

If C RETURN.CODE ,ne. 0 ) Go To qq

1failed to connect&

Allocate Channel AO.CHANNEL

Rate
8uffe~

= AD.RATE
s1ze :

AD.BUF.SIZ~

Collect 1 buffer at a time
COMMAND = •ALLOC~TE•
Write(l,400) COMMANO,AO.CHANNEL,AD~RATE,AD.BUF~SIZE11
If( RETURN~CODE ,ne, 0) Go To qq
1F•11ed to allocate&

Every SAMPLE.RATE secs, we

collect one buffer of data

~111

ASCII delta time to binary
Ce11 SVS$BINTJM( SAMPLE.RATE, DELTA.TIMt

Co~vert

Schedule wake•ups every delt time interval
But first cancel any previous wake•ups
Call SYS$CANWAK(,)
Cel1 SYSSSCHD~Kc,,DELTA.TIME,D~LTA~TIME)
1 Wait for scheduleo time interval
10
Call SVS$HIBER()
Enable data aequsition by setting event flag ACTIVITY and NOTIFY
Cell

SYSSSETEFC%Va1CEF~ACTIVlTY.OFF+AD~CHANNEL))

Call SVSSSETEFC%ValCEF~NOTIFV~OFF+AO~CHA~NELl)
Call SYSSASCTIMC,DATE•T!ME,,)
Now, wait for buffer to be fil1ed, event flag STATUS will be set
when data are reedy
Cell SYS$~AITFR( %Ve1CEF~STATUS.OFF+AD~C~AN~EL)
Buffer 1s f1lled, get the buffer
IN.DE~

1~oex

= AD.e~OCK(7,Av.CHANNEL)

Clear the STATUS event fle9 and

Call SYSiCLREFC

~otify t~e I/O process
ZVal(tF.STATUS~OFF+AD~CH-NNELJ
%Va1CEF.NGTlFY~OFF+AO.CnA~NEL)

Cal1 SYSlSETEFC
Average the points
AVERAGE : 0
Do 20 I : 1, AD.BUF~SllE

AVERAGE: AVERAGE+ DATA~~0FFERCI,INDEX 1 AU~CHANNEL)
AVERAGE : AV£RAGE/AD.BUF.SIZE
~rite

out average with the aco, datelt;me
Write(3,U00)

DATE~T!Mt,AVERAG~

If we•re a11 done, close files and ex;t
If( AD~BLOCK(b1AO~CHANN~~) ,lt, MAX~S4MPLE ) Go To 10
1 All done, Ca11 tMe exit routine
qq

Call EX1T(1)

100

formate• ',A,A)

7-35

PROGRAM EXAMPLES

200
400

FormatCI2,A)
Format(' ',A,41)
End

l[End of File]

&file:

TESTLABIO,FOR

1 Tests the LABIO system by el locating upto lo cManners
1 Enter the number of channels, rate, end buffer size

Include 'LABCHNDEF,FOR'
Parameter

MBX~NAME

: 'TEST 4 LAbl02'

Character*130 RETURN

Character•lS

CO~~AND

DATE.TIME
Logice1*4 SUCCESS,SYSlCREMBX
C~eraeter*24

Integer•4

TEST~CrlAN,TEST.RATE,TEST.BUF4SIZE

Mao To the Global Deta Base and the event flags

Call LABI0 4 !NJTC0)
Open Mailbox to LABI0 4 CONNECT

Open C Unit : 1, Name :
Create Mailbox

for

SUCCESS:
If (,not,
Ope~

'LA8IO.CO~NECT'

, Type = 'OLD' )

resoonse from LABIO.CONNECT

SYS,CRE~8X(,~8X.CHANNEL,,,tVel('FD00'xJ,,MBX 4 NAMEJ

SUCCE.SS )

Cal 1 FATAL._E.RRORC SUCCE.SS,

"CREATING MAIL.BOX';

via FORTRAN

Deassign the channel assigne1

we created it

w~en

Cal 1 SYS$DASSGN( %Ve1 ( "18X._CH4NNfL)

Connect to the LABIO svstem
COM~AND :
'CONNECT'
Write(l,100) COM~A~O,~dX~NA~E

Wait for Resoonse

f~om

LA6IO svstP,m

Read(2,2~0) R~TURN~CODE,RtTUR~
!f ( RETURN~CUOE
0 ) Go

,ne,

To qq

1 Get parameters from ooerator

LAST 4 TEST.CHAN:TEST 4 CHAN

7-36

1Fai1ed to conr1ectl

PROGRAM EXAMPLES

Type 000,' Enter number of channels, rateC1n tics), and buffer size•
Accept 700, TEST.CHAN,TEST 4 RATE,TEST 4 BUf.SIZE
If C TEST.CHAN ,eQ, 0 ) CAll EwitC1l
Deallocate Channels from last time

Do 20 AD 4 CHANNEL=11LAST.TEST.CHAN
Call
Ca11

SYS$CLREfC%Va1CEF~ACTIVlTY.OFF+AD.CHANNEL))
SYS$SETEFC%Va1CEF~NOTIFV.OFF+AD.CHANNEL))

1Stop Acq,

COMMAND : 'DEALLOCATE'
Wr1te(1,400)

COMMANO,AD.CHANN~L

RETURN.CODE,RETURN
If ( RETURN 4 CODE ,ne, 0 )
1 Type 500, 'Oeellocation failure',RETURN.CODE,RtTURN
Continue

Read(2,20~)

20
1

I Allocate Channe1s

Do 30 AD 4 CHANNEL;1,TEST.CHAN

COMMAND : 'ALLOCATE'
Wr1te(1,~00) COMMANO,AD.CHANNEL,TEST.R6TE,TEST.BUF.sizE,0
ReadC2,200) RETURN.COOE,RETURN
lf C RETURN.CODE ,ne, 0 )
1 Type 500, ' Allocation failure',RETURN.CODE 1 RETURN
Enable data ecaus1tion by setting event flag ACTIVITY and NOTIFY
Ca11

SYS$SETEFC%VelCEF 4 ACTIVITY~OFF+AD~CHANNEL))

Cell SYS$SETEF(%Val(EF~NOTIFY 4 0FF+AO.CHANNEL))
Go To 10

1 Co~nect Failure
1
qq

Type 500, 'Connect failure',RETURN.CODE,RETURN
Go To 10

100

200
4~0

500
600
700

Format(' ',A,A)
FormatCI2,A)
Formate• •,A,~I)
Formet(A/' •,12,A)
Format(Al
Format(3I10)

End

1F11e:

LA8IOCOM,FOR
Logical Funct1on LA81U.IN!f (

PRIVIL~GE

)

This routine is used to attach a LASlO user program to the
LABIO system, It associated the two event flag clusters end
meps to the LABIO global data section,

INPUT:

PRIVILEGE• Privileged

7-37

LA~IO

users can set this

PROGRAM EXAMPLES
to 1 to allow write access to the data base,
All others must set this to 0,

OUTPUT I

None• CurreMtly will always return with success code,
lf an error occurs, FATALERR is ce11ed to display
th.e error messaqes and STOP THE PROCESS!

Include 'LABCHNDEF,FOR'
Logica1*4 SYS$ASCEFC,SYS$MG8LSC,SUCCESS,SYS$WAITFR
External SEC$M 4 wRT
Create event flag cluster EF.NOTIFY and essoci~te with. event flags b4•qs
These are used to MOtify the Data AcouisitioM ~rocess,

SUCCESS : SVS$ASCEFCC ZVALCEF~NOTIFY~l)1EF~NOTIFY.CLSTR,,)
If C ,not, SUCCESS)
1
Call FATAL.ERRQRC succtss, ·ckEATING EVENT FLAG CLUSTER')
Create event flag cluster EF.STATUS and associate wftM event flags 9b•12'
These are used to Motify and report the status of the user buffers
SUCCESS : SYS$ASCEFCC %VALC~F .... STATUS~l)1EF.STATUS..._CLSTR,,)
If C ,not, SUCCtSS)
1
Call FATAL 4 ER~ORC SUCCESS, 'CREATING EVENT FLAG CLUSTER')
Map to the GLOBAL DA.TA section created bv the I/O o~oqram
wait for event fla9 EF 4 CONNcCT Cno~·or1vileqed) or
Ef 4 DATA.ACQ Cor;vileged) before attemoting maoPi~g,

SECTION(l)
SECTIO~C2)

= XLoeCLABl0~8uFFER4S)

: XLocCLABIO.BUFf ER 6 ~)

SECTION 4 FLAGS :

•

H~efault

flags

If( PRIVILEGE ,ne, 0 ) Then
SECTION~FLAGS:XLoc(SEC$M~~RT)

Cal 1 SYS$WA!TFRC %Val ( t.F .... OATA..._ACC ) )

Else
Cal 1 SYS$w.AITFRC %Val (
E.nd If

t.F,...CO~hECT

) )

SUCCESS: SYS$MGBLSCC SECTION,,,IVelCSECTI0~ 4 FLAGS),'LABlOCOMMQN•,,
lfC •"ot, SUCCESS) Call FATAL~ERRO~CSUCCESS,'mapoin9 data section'
LABIO.INIT : SUCCESS

Retur"'
EP'ld

FATAL"'"ERROR

FATAL ERROR

HANDL~R

This routine is used to reoort a fatal error and exit

INPUT:

ERROR.CODE • SYSTtM EPROR coot TO REPORT
ERROR~MESSAGE • ERROR MESSAGE TO HE PRINTED

OUTPUT: NOr..IE

7-38

t~e

image

PROGRAM EXAMPLES

>>>> THIS ROUTINE DOES NOT RETURN <<<<<

FUNCTIONS TYPEs the message
'Process name•FATAL ERROR • error.message•

Then Prints system message corresponding to

ERROR.CODE

Finally, oits 1mege by calling Ll8$STOP

Subroutine FATAL.ERRORCerror.code,error.message)
Integer•4 ERROR*COOE
Character ERROR~MESSAGE*(*)
Logica1•4 SUCCESS,SYS!CREMBX,SYS!GETJPI
Integer*2 JP12(8),PROCESS..,NAME.L
Integer•4 JP14C4)
Charaeter•15 PROCESS.NAME
Equivalence CJPI2,JPI4)
Parameter JP1$.PRCNAM:'31C'X
Get the Process name
JPI2C1)

= JP15U..,PRCNAM
=
JPI4C2) = %Loe(PROCESS.NAME)
JPI4C3) = %Loc(PROCESS~NAME.Ll
JPI4(4) = QI

Jl'I2C2)

1Number of elements in name
lWant process name
1Adoress of orocess ~ame
1Address of process name le~gth
1 lermi P'lete 1; st

Call SV5$GETJPI(,,,JPI4,,,)

Pr1nt the process name and error message

Print the error message correspono;ng to tRROR.CODE and exit

Cal 1 Ll~$STOP( XVal CERRO~,,_CODE)
10~

Format(' 'A,' - FATAL

ER~OR

',A)

Stop

END
llEnd of FileJ

IFile1
LABMBXDcF,FOR
1Define mailbox olock for

~AB.IO

Parameter MAX.MESSAGE = 128
1Max1mum message length
Parameter MBX~RESPUNSE.L = 2
&Response Length
Parameter MBx.AcK.L : ~AX~MESSAGt+MBX~R~SPONS~~L

7-39

PROGRAM EXAMPLES

Integer•4 Max.Pro
Byte MBX.RESPONSECM8X 4 RESPONSE 4 L)
Byte M8X 4 MESSAGE(MAX,..MESSAGE)
Co~mon

/MKX 4 BLOCK/

M8X 4 lO.STATUS, MBX...,MESSAGE.L 1
MBX.PIO, MBx.RESPONSE, MBX ... MESSAGE

M6X 4 CHANNE~,

......................
.......................
................. .... .
1 MBX.CHANNEL
' Word 1•2
> MBX.BLOCK <
~

····--·-·---------------------------1 MBX ... MESSAGE,..L
1 MBX.,.IO.STATUS
-----------·--·--·-····-··-------·--·
-------------------·-····-···-------MBX...,RESPONSE.
-----------------------------------··
MBX.MESSAGE
I
•••••••••••••••••••••••••••••••••••••
1
1LEnd of File]

1File:
1

LABCHNOEF,rOR

lAD...,CHANNEL STATUS BL9CK defined tne parameters associated
1with eaeh AID c~anne1
1
lfor each A/D channel:
l 1)
Status of tne cnanne1 CACTIVE or INACTivE)
1 2)
PIO of t~e connected orocess al located tne channel
Ties/sample (time between sample in tics)
1 3)
1 4)
Buffer size in woras
1 5)
Buffer cou"t C0 if no limit)
Buffers acqu; red
1 b)
1 7)
Index to tne last full buffer containing val;d aata
0 =>No buffer availaole
Number of data points in the last full buffer
1 8)

The following elements are use~ by the oata ac~uisition interrupt service
routine, In general, t~ey will not te used bY an application process,
9)
10)
11)

12)

Index to the cur~ent data acautsition buffer
Number of data points in the current oata acQuis1tion buffer
Number of tics until tne next sam.ple
Offset to t~e next data ooint to oe acouired Cwrst buffer #l)
(NOTE: Offset ; Index • 1 )
Parameter
Pa,..ameter
Parameter

r.UX..._AO._CHANt~E.L

MAX.duF.SIZE
INACTIVE :

= 512

7-40

lMaximum number of channels
1Maximum buffer size
JStatus values +or AD 4 BLOCK

PROGRAM EXAMPLES
Pel"ametel"

ACTIVE s 2

Oet• buf fe1"1
Periemeter

BUFF ER..,.COUNT :

& Numbel" of buf fer1/eh1nne1

&T~1• module defines the common deta structures
&fori the priv11eoed LABIO processes,

&CONNECT BLOCK used to identify processes curreritly
&connected to the LABIO proceas,

'&Fol"
''

each proce11 CONNECT 4 6LOCK contains:
Proce11 ID CPID)
Internal VMS I/O channel of t~e connected processes me1lbox
Peremetel"
IMteger•4

MA~.PID = 1b
&Maximum number of pl"oce11e1
CONNECT.BLOCKCMAX 4 PID12)

DATA COMMON SECTION
Th11 w111 be mapped•• e global date section
ILABIO.SECTION/ AD.BLOCK, DATA.BUFFER, CONNECT.BLOCK
/LABl0 4 SECTION/ LABIO.BUFFER.E lLast element of DATA 1ecti~n
E~u1va1ence CAD.BLOC~ 1 LABIO.BUFFER.S)
1F1rst element of DATA 1ect1on
Integer•4 SECT10N(2l,SECTION.SIZE

Common
Common

Define Global Event Flag Cluster

~ames

and numbers

EF 4 NOTIFY.CLUSTER 1s used to notify the or1ve1eged LABIO process
tn•t cha~ge of status ~as oceured, 1,e. cnenne1 nea
become ACTIVE or INACTIVE, or a buffer nas been freed,
F11g1 0•15 of the cluster correspond to CHANNELS 1•1b
F11gs 16•31 are not used,
Parameter EF.._NOTIFY.CLSTR ; •LABIO.~F.NOTIFY'
First flag of notify
Parameter EF.._NOTIFY.,..1 : o4.
Ofhet to Notify
Parameter EF.._NOTIFV.OFF ; b3
Event F1eg EF.DATA.._ACQ is set when LABI0 4 UATA.ACQ nas completed in1t1a1ization
Parameter EF.._OATA~ACQ = EF.NOTIFY.1+17

7-41

PROGRAM EXAMPLES
Event Flag EF.CO~NECT is set when LABI0 4 CONNECT Mal completed in1t11li11tion
P1r1meter EF.CONNECT : EF 4 NOT1FY 4 1+18
i• u1ed to notf fy a applfcat1on1 proce~s
that •buffer f1 available, and used by en application
~roc111 to inieate the 1tatu1 (ACTIVE or INACTIVE) of
a ch•""'1•
E~.STATUS

Flega 0•15 of the cluster are the ACTIVITY f1191
if 11t Cby the aPP11catfon proee11l1 the correapond1no
ch1nn11Cl•lb) 11 active. If clear, the channel fs inactive.
When a change of atate 1• made the correapond1ng flag mu1t
1110 be 1et in Clu1ter EF.NOTIFY.CLUSTER.
F11g1 lb•31 are the buffer 1tatu1 flag1,

w~en

aet,

a buffer for the corre1pondfng channel C1•16) 11 1v1il1b1e,

The 1polie1t1on proc111 mu1 clear the fleg and set the correapond1ng
f11; 1n EF.NOTIFY.CLUSTER when ft 11 finished with the buffer,

Parameter EF.STATUS.CLSTR s •LABIO.EF.STATUS•
IF1rat event flag in Act1v1tv end Status
Parameter EF 4 ACTIVITV.1 • 9b
Parameter EF.STATus.1 • EF.ACTIVITv.1 + 16
IOffaet to Actfvitv aMd Status
Pe~amete~ EF.ACTIVITY OFF • 95
P•r•m•t•~ EF.STATus_o,F • EF.ACTIVITY.OFF + 16
I BIT 1rray, BITCI) • ha1 b1t I 11t C I • 1 to 32
I"teoer•4 BITC32)
Oat• BIT/ •1•x,•2•x,•4•x,•a•x,•10•x,•20•x,•40•x,'e0•x,
1

1
1
1
1
l

'ICEnd

'100•x,•200•x,•400•x,•a00•x,•1000•x,•~000•x,
•4000•x,•e000•x,•10~00•x,•20000•x,•40000•x,
•e0000•x,•100000•x,·2~0000•x,•400000•x,

•e00000•x,•1000000•x,•2000000•x,•4000000•x,
•e000000•x,•10000000•x,•20000000•x,•40000000•x,
•e0000000•x1

of Ffl•l

IFf 111 LABIOSEC.FOR
I Block D1t1 Routine to Pleet tMt LABIO.SECTION Common
& on• P•O• boundary, Thf1 ie nece111rv beceuae we w111
I rem1p ft, We could have u1ed • MACRO program to
I dec1ere the PSECT LABIO.SECTION to bt paged aligned,
I but the LINKer would then give ua • warning me11ao1,
Block Date LABIO.SECTION
Common /LABIO.SECTION/ AD.BLOCK

E"d

'llEnd of FfleJ

7-42

PROGRAM EXAMPLES
IFILE1CONNECT.COM
I This command fi1e loads the connect•to•interrupt
I then connects the KW11•K to to it.

~andler

CCONINT~RR)

and

S R SYSSSYSTEMaSYSGEN
L.OAD CONINTERR
CONNECT KWA0 /ADAPTER:3/CSR:X077~444/VEC:XQ404/DRIVER:CONINTERR
S E>d t

1F11el

LABIOSTRT,COM

&St•rt• up the LABIO SYSTEM
&Run1 the data ecQu1s1t1on ~rocess and connect process
&11 detached tasks, T"•n runs the status ~rogrem,

&Mike the 1og1ce1 name e1signment1
IA11fgn/Group L.ABIO,LOG LABIO.LOG
SA11f gn/Group LABIO,OAT LABIO~SEC.FILE
IA11i;n/Group KWA~I LABIO.AO SSet Noon

s
S&Run the date 1cqu111tion orogram
s

SRun/Uic•
/A1t,..L.1m1t•
/Output •
/Priority•
IP roce11,..nu\e•

/Prh11egea•
L.ABIOACQ

'FSUSERC)'•
20•
LABIOACQ,DAT•

IConnect•to•lnteru~t device 11
lDo~'t abort if we can't run 1

KW•11

program
llt 11 probably 11reedy running&
lRun •• a deetcned ~roc111
1we need • 11rge AST Quote
lSYSSOUTPUT
lHigh, Reel•Time priority
1Name of Proce11
1Same i:>riv11egea
1 I ruoe to ru"

17•

LAB I o.o• u ... ACQ•
SAME•

s
l&Run the connect program
s

S RUN/U1c•
/Output•
/Pr1or1tya
/Prh11•o••
/Proce11.,..n1rne•
LAB I OCON

&Log file
1G1obal Section F11e

"FSUSER() '•
L.ABIOCON,DAT•

1Run es • detached proce11
1SVSSOUTPIJT
IGive 1t • "1gh but not m1ontv i:>r1or1tv

15•

SAME•
LABIO.,,.CONNECT•

lNeme of the proceas

S&Run the atetua program
SRun L.ABIOSUT
SS.t On

LABIOCOMP,COM
Comm1nd procedure to eomc11e and assemble
the module• of tne LABIO system,

1~11•1

S Fortran L.ABIOACQ,LABIOCON,LABIOSTAT,LABIOCOM,LABIOSEC
S Macro/Lilt LABIOC1N+Syt$L1orary:LIB.MLB/L1brary
s Mecro/~11t GBLSECUFO

7-43

PROGRAM EXAMPLES

$£ Demo Programs
s Fortran LABIOSAMP,LABIOPEAK,PEAK,TESTLA8IO

&file: LABIOLINK,COM
1 Command procedyre to LINK tne LABIO system
$ Link/Map LABIOACQ,G~LSECUF01LA0IOCOM,LABIOCIN/Option
$ L;nk/Map LABIOCQN,LABIO/Opt;on
$ Link/Map LABIOSTAT,LABIO/Optio~
51 Demo Programs
S Link/Map LABIOPEAK,PtAK,LABIO/Opt
$ Link/Map LAbIOSAMP,LABIO/Opt
S Link/Map TESTLAtiIO,LABIO/OPt

&File: LABIO,OPT
&Linker OPTIO~ file for linking any process to be usea wit~
LABIOCOM
Cluster = LABID.CLUSTER,,,LABIOSEC

LABIOCIN,OPT
&Linker OPTION f;le for linking LABIO.DATA.ACQ
Cluster = Lab10.cluster,,,Labioc;n
lFileJ

7-44

~ABIO

PROGRAM EXAMPLES
7.2

AIRLINE RESERVATION SYSTEM

This example shows a series of programs to make and cancel airline
reservations.
This is not a "real-time" example in the same sense as
the data acquisition and manipulation example
in Section
7.1.
However,
the airline
reservation system does show a shareable image
data base, access to which is synchronized by the use of common event
flags.
It also shows the use of a shared memory common event flag
cluster.
The following commands define the logical names and install the global
section for the airline reservation system (FORTRAN program examples).
The shared memory is named SHM.

$ COPY DATABASE.EXE SYS$SHARE:DATABASE.EXE !PUT IT IN LIBRARY
$ DEFINE GBL$DATABASE SHM:DATABASE !LOGICAL NAME DEF. FOR SECTION
$ RUN SYS$SYSTEM:INSTALL
INSTALL> SYS$SHARE:DATABASE/OPEN/HEADER RESIDENT/SHARED
INSTALL> [CTRL/Z]
$ DEFINE/SYSTEM CEF$CEFN1 SHM:CEFNl !LOG. NAME DEF. FOR CLUSTER
$ RUN [desired program in the reservation system]

7-45

PROGRAM EXAMPLES
c
c
c
c
c
c
c
c
c
c
c
c

DATADESC.FOR
VMS AIRLINE RESEVATION SYSTEM
BEING A SIMPLE DEMONSTRATION OF THE USE OF A GLORAL
DATABASE AS A SHAREABLE IMAGE UNDER VAX/VMS.
DISCLAIMER:

NDESTS = 4
NDAYS = 3
NSEATS = 10
ITOTSEATS = NDESTS*NDAYS*NSEATS*2

PARAMETER
PARAMETER
PARAMETER
PARAMETER

THIS SOFTWARE IS FOR DEMONSTRATION PURPOSES
ONLY. NO AIRLINE IS EXPECTED TO HONOUR THESE
RESERVATIONS. FURTHER, IT IS INTENDED ONLY TO
DEMONSTRATE SOME OF THE TECHNIQUES AVAILARLE
WITH VAX/VMS AND VAX-11 FORTRAN.

CHARACTER DESTINS(NDESTS)*6,SEATS(NSEATS,2,NDESTS,NDAYS)*20
CHARACTER DAYS(NDAYS)*3

INTEGER HOWPAID(ITOTSEATS)

COMMON /FLIGHTDATA/SEATS,DAYS,DESTINS
COMMON /PAIDDATA/HOWPAID

BLOCK DATA DATABASE

INCLUDE 'DATADESC.FOR'

c
DATA DESTINS/'BOSTON', 'SYDNEY','LONDON', 'MADRID'/
DATA DAYS/' MON', 'TUE','WED'/
DATA SEATS/ITOTSEATS* I
I I

END

SUBROUTINE

LOCKFLIGHT(IDEST,IDAY)

c
INCLUDE

'DATADESC.FOR'

c
EXTERNAL SS$ WASSET
INTEGER PREVSTATE,EVFLAG
INTEGER SYS$SETEF,SYS$CLREF,SYS$ASCEFC

c
10

900
910

EVFLAG = 63 + NDAYS*(IDEST - l) + !DAY
IF ( .NOT. SYS$ASCEFC(%VAL(EVFLAG) ,%DESCR('FLIGHTLOCKS'),,)) GO TO 900
PREVSTATE = SYS$SETEF(%VAL(EVFLAG))
IF (PREVSTATE .EQ. %LOC(SS$ WASSET)) THEN
GO TO 10
ELSE
IF ( .NOT. PREVSTATE) GO TO 900
RETURN
END IF
ENTRY UNLOCKFLIGHT
IF (.NOT. SYS$CLREF(%VAL(EVFLAG))) GO TO 900
RETURN
TYPE 910
FORMAT(' **** EVENT FLAG SERVICE FAILURE ****')
END

7-46

PROGRAM EXAMPLES
PROGRAM DISPLAY

INCLUDE 'DATADESC.FOR'

CHARACTER DESTIN*6,DAY*3,HOMERASE*4,BLANKS*6,SMOKE*l
CHARACTER TIMEDELAY*l3,TOPOFSCREEN*6

INTEGER SYS$BINTIM,SYS$SETIMR,SYS$WAITFR,SYS$CLREF,DELAY(2)

c
BYTE CTLERASE(4),CTLTOS(4)

EQUIVALENCE (HOMERASE,CTLERASE(l)), (TOPOFSCREEN,CTLTOS(l))

DATA CTLERASE/'lB'X,'H' ,'lB'X,'J'/,BLANKS/'
DATA TIMEDELAY/'0 00:00:10.00'/
DATA CTLTOS/'lB'X,'Y' ,'22'X,'20'X/

1000
1010
1020
1030
1040

FORMAT(' Enter flight destination: ',$)
FORMAT(A)
FORMAT(' There are no flights to ',A)
FORMAT(' On what day? ',$)
FORMAT(' ',A, 'DESTIN DAY SEAT PASSENGER NAME
CREDIT
1 CARD NO. ( 0 IF CASH) I , I, I - - - - - - - - - - - - - - - - - - - - - - - - - - 1
,/)
FORMAT ( I + I , A , I I , A , I
I , A, I 2 , I
I , A , I 1 0 , I)
1050
FORMAT (I I ,A)
1060

---------------'

TYPE 1000
ACCEPT 1010, DESTIN
DO 20 !DEST = l,NDESTS
IF (DESTIN(l:2) .EQ. DESTINS(IDEST)(l:2)) GO TO 40
CONTINUE
TYPE 1020, DESTIN
GO TO 10

c
40

c
80

TYPE 1030
ACCEPT 1010, DAY
DO 60 !DAY = l,NDAYS
IF (DAY(l:2) .EQ. DAYS(IDAY) (1:2)) GO TO 80
CONTINUE
IF (DAY(l:3) .EQ. 'ALL') THEN
!DAY = -1
GO TO 80
END IF
GO TO 40
CONTINUE
IF (!DEST .EQ. -1) THEN
JD EST
1
KDEST
NDESTS
ELSE
JD EST
!DEST
KDE ST
!DEST
END IF
IF (!DAY .EQ. -1) THEN
JDAY
1
KDAY
NDAYS
ELSE
JDAY
IDAY
KDAY
IDAY
END IF

c
90

c
c

TYPE 1040, HOMERASE
LINES = 0
DO 500 !DEST = JDEST,KDEST
ILOOP = 0
DO 400 IDAY
JLOOP = 0

= JDAY,KDAY

DO 300 !SEAT = l,2*NSEATS
ILOOP = !LOOP + l
JLOOP = JLOOP + 1
IF (ISEAT .LE. NSEATS) THEN
SMOKE = 'N'
!SMOKE = 1
JSEA'f
I SEAT
ELSE
SMOKE = 'S'
!SMOKE = 2
JSEAT
!SEAT - NSEATS
END IF
LSEAT = !SEAT+ (IDEST-1)*2*NSEATS + (IDAY-l)*NDESTS

7-47

PROGRAM EXAMPLES
c
IF (LINES) 100,100,99
IF (!LOOP - 2) 100,120,140
DESTIN= DESTINS(IDEST)
GO TO 140
DESTIN = BLANKS
CONTINUE

99
100

120
140

IF (LINES) 160,160,150
IF (JLOOP - 2) 160, 180, 200
DAY = DAYS(IDAY)
GO TO 200
DAY = BLANKS
CONTINUE
I) THEN
IF (SEATS(JSEAT,ISMOKE,IDEST,IDAY) (1:4) .EQ. I
IF (!SEAT .NE. 1) THEN
GO TO 300
END IF
END IF
TYPE 1050, DESTIN,DAY,SMOKE.ISEAT,SEATS(JSEAT,ISMOKR,IDEST,IDAY),

150
160
180
200

1 HOWPAID(LSEAT)

300
400
500

LINES = LINES + 1
IF (LINES .GE. 19) THEN
TYPE lOnO, TOPOFSCREEN
LINES = 0
END IF
CONTINUE
CONTINUE
CONTINUE
END

PROGRAM RESERVATION

INCLUDE 'DATADESC.FOR'

c
CHARACTER DESTIN*6,DAY*3,SMOKE*3,PAYMENT*4

1000
1010
1020
1030
1040
1050
1060
1070
1080
1090
1100
1110
1120
1130

FORMAT (' Enter destination: ',$)
FORMAT(A)
FORMAT(' There are no fliqhts to ',A)
FORMAT(' On what day? ',$)
FORMAT(' Do you want a smoking area seat? ',$)
FORMAT(' The flight to ',A,' is full on ',A)
FORMAT(' No smoker seats left. Is non-smoking acceptible ?',$)
FORMAT(' Non-smoking is full. Is smoking area acceptible ?',$)
FORMAT(' Your seat is number ',I4,' on the ',A,' flight next ',A)
FORMAT(' Enter passenger name: ',$)
FORMAT(' Payment by cash or credit card? ',$)
FORMAT(' Enter credit card number: ',$)
FORMAT ( Il 0)
FORMAT(' *** INVALID CREDIT CARD NUMBER ***')

TYPE 1000
ACCEPT 1010, DESTIN
DO 20 !DEST = l,NDESTS
IF (DESTIN(l:2) .EQ. DESTINS(IDEST)(l:2)) THEN
GO TO 40
END IF
CONTINUE

TYPE 1020, DESTIN
GO TO 10

7-48

PROGRAM EXAMPLES
c
40

c
80

TYPE 1030
ACCEPT 1010, DAY
DO 60 !DAY = l,NDAYS
IF (DAY(l:2) .EQ. DAYS(IDAY) (1:2)) THEN
GO TO 80
END IF
CONTINUE
GO TO 40
TYPE 1040
ACCEPT 1010, SMOKE
IF (SMOKE(l:l) .EQ. 'Y') THEN
!SMOKE = 1
ELSE IF (SMOKE(l:l) .EQ. 'N') THEN
!SMOKE = 0
ELSE
GO TO 80
END IF
CALL LOCKFLIGHT(IDEST,IDAY)

100

110
120

c
150

170

c
200

220

240

260
900

DO 100 !SEAT = l,NSEATS
IF (SEATS(ISEAT,ISMOKE+l,IDEST,IDAY) (1:4)
GO TO 200
END IF
CONTINUE
JSMOKE = !SMOKE .XOR. 1
DO 110 !SEAT = l,NSEATS
IF (SEATS(ISEAT,JSMOKE+l,IDEST,IDAY) {1:4)
GO TO 150
END IF
CONTINUE
TYPE 1050, DESTINS(IDEST) ,DAYS(IDAY)
CALL UNLOCKFLIGHT
GO TO 900

.EQ.

') THEN

IF {!SMOKE .EQ. 1) THEN
TYPE 1060
GO TO 170
ELSE
TYPE 1070
END IF
ACCEPT 1010, SMOKE
IF {SMOKE(l:l) .EQ. 'N') THEN
GO TO 120
END IF
!SMOKE = JSMOKE
JSEAT = !SEAT + (NSEATS*ISMOKE)
KSEAT = JSEAT + (IDEST-1)*2*NSEATS + (IDAY-l)*NDESTS
TYPE 1080, JSEAT,DESTINS{IDEST) ,DAYS{IDAY)
TYPE 1090
ACCEPT 1010, SEATS(ISEAT,ISMOKE+l,IDEST,IDAY)
TYPE 1100
ACCEPT 1010, PAYMENT
IF ( PAYMENT(l:2) .EQ. 'CA') THEN
HOWPAID(KSEAT) = 0
ELSE IF (PAYMENT(l:2) .NE. 'CR') THEN
GO TO 220
ELSE
TYPE 1110
ACCEPT 1120, HOWPAID(KSEAT)
IF (HOWPAID(KSEAT) .NE. 0) GO TO 260
TYPE 1130
GO TO 240
END IF
CONTINUE
GO TO 120
CONTINUE
END

7-49

THEN

.EQ.

PROGRAM EXAMPLES
PROGRAM CANCEL

INCLUDE 'DATADESC.FOR'

CHARACTER DESTIN*6,DAY*3,NAME*20,BLANKS*20

DATA BLANKS/'

1000
1010
1020
1030
1040
1050

FORMAT(' Enter destination: ',$)
FORMAT(A)
FORMAT(' There are no flights to ',A)
FORMAT(' On what day? ',$)
FORMAT(' ',A' does not hold a seat to ',A,' on ',A,' flight')
FORMAT(' Seat number ',I4,' cancelled on the ',A,
l' flight next ',A)
1090
FORMAT (' Enter passenger name: ', $)

TYPE 1090
ACCEPT 1010, NAME
TYPE 1000
ACCEPT 1010, DESTIN
DO 20 IDEST = l,NDESTS
IF (DESTIN(l:2) .EQ. DESTINS(IDEST)(l:2)) THEN
GO TO 40
END IF
CONTINUE
TYPE 1020, DESTIN
GO TO 10

c
40

c
c
80
90

100

c
200

900

'I'Y PE 1 0 3 0
ACCEPT 1010, DAY
DO 60 IDAY = l,NDAYS
IF (DAY(l:2) .EQ. DAYS(IDAY) (1:2)) THEN
GO TO 80
END IF
CONTINUE
GO TO 40

ISMOKE = 0
DO 100 ISEAT = l,NSEATS
IF (SEATS(ISEAT,ISMOKE+l,IDF.ST,IDAY) (1:10)
CALL LOCKFLIGHT(IDEST,IDAY)
GO TO 200
END IF'
CONTINUE
IF (!SMOKE .EQ. 0) THEN
ISMOKE = 1
GO TO 90
ELSE
TYPE 1040, NAME, DESTIN, DAY
GO TO 900
END IF'

.EQ. NAME(l:lO)) THEN

JSEAT = !SEAT + (NSEATS*ISMOKF.)
KSEAT = JSEAT + (IDEST-1)*2*NSEATS + (IDAY-l)*NDESTS
TYPE 1050, JSEAT,DESTINS(IDEST) ,DAYS(IDAY)
SEATS(ISEAT,ISMOKE+l,IDEST,IDAY) (1:20) = 8LANKS(l:20)
HOWPAID(KSEAT) = 0
CALL UNLOCKFLIGHT
CONTINUE
END

7-50

PROGRAM EXAMPLES
PROGRAM MONITOR

c
INCLUDE 'DATADESC.FOR'

c
CHARACTER
CHARACTER

DESTIN*6,DAY*3,HOMERASE*4,BLANKS*~,SMOKE*l
TIMEDELAY*l3,TOPOFSCREEN*~

c
INTEGER SYS$BINTIM,SYS$SETIMR,SYSSWAJTFR,SYS$CLRP.F,nELAY(2)

c
BYTE CTLERASE(4) ,CTLTOS(~)

c
EQUIVALENCE

(HOMERASE ,CTLF:RASF. ( 1)), (TOPOFSCRP.P.N ,C'I'LTOS ( l))

c
DATA CTLERASE/'lB'X,'H','lR'X,'J'/,RLANKS/'
DATA TIMEDELAY/'O 00:00:10.00'/
DATA CTLTOS/'lB'X, 'Y', '22'X, '20'X, 'lR'X, 'J'/

c
1000
1010
1020
1030
1040

FORMAT(' Enter flight destinc1tion: ',$)
FORMAT(A)
FORMAT(' There are no flights to ',A)
FORMAT(' On what day? ',$)
FORMAT(' ',A,'DESTIN DAY SEAT PASSENGER NAME
CREDIT
1 CARD NO. (0 IF CASH) I,/, I ------ --- ---- -------------1
,/)
1050
FORMAT('+',A,' ',A,'
',A,I2,' ',A,IlO,/)
1060
FORMAT(' ',A)

---------------'

TYPE 1000
ACCEPT 1010, DESTIN
DO 20 IDEST = l,NDESTS
IF (DESTIN(l:2) .EQ. DESTINS(IDEST)(l:2)) THEN
GO TO 40
END IF
CONTINUE
IF

(DESTIN(l:3) .EQ.
ID EST
-1
GO TO 40
END IF
TYPE 1020, DESTIN
GO TO 10

c
40

c
80

c
90

'ALL') THEN

TYPE 1030
ACCEPT 1010, DAY
DO 60 IDAY = l,NDAYS
IF (DAY(l:2) .EQ. DAYS(IDAY) (1:2)) THEN
GO TO 80
END IF
CONTINUE
IF (DAY ( l: 3) • EQ. I ALL I) THEN
IDAY = -1
GO TO 80
END IF
GO TO 40
CONTINUE
IF (IDEST .EQ. -1) THEN
JDEST
KDEST
NDESTS
ELSE
JD EST
IDE ST
KDEST
ID EST
END IF
IF (IDAY .EQ • -1) THEN
JDAY
l
KDAY
NDAYS
ELSE
JDAY
IDAY
KDAY
IDAY
END IF
TYPE 1040, HOMERASE
LINES = 0
DO 500 IDEST = JDEST,KDEST
ILOOP = 0

7-51

PROGRAM EXAMPLES
c
DO 400 IDAY = JDAY,KDAY
JLOOP = 0

DO 300 ISEAT = l,2*NSEATS
ILOOP = ILOOP + l
JLOOP = JLOOP + l
IF (ISEAT .LE. NSEATS) THEN
SMOKE = 'N'
ISMOKE = l
JSEAT = ISEAT
ELSE
SMOKE = 'S'
ISMOKE = 2
JSEAT
ISEAT - NSEATS
END IF
LSEAT = ISEAT + (IDEST-1)*2*NSEATS + (IDAY-l)*NDESTS

IF (LINES) 100,100,99
IF (ILOOP - 2) 100,120,140
DESTIN = DESTINS(IDEST)
GO TO 140
DESTIN = BLANKS
CONTINUE

99
100

120
140

IF (LINES) HiO,H0,150
IF (JLOOP - 2) 160, 180, /.00
DAY = DAYS(IDAY)
GO TO 200
DAY = BLANKS
CONTINUE
I) THEN
IF (SEATS(JSEAT,ISMOKE,IDEST,IDAY) (1:4) .EQ. I
IF (ISEAT .NE. 1) THEN
GO TO 300
END IF
END IF
TYPE 1050, DESTIN,DAY,SMOKE,ISEAT,SEATS(JSEAT,ISMOKE,IDEST,IDAY),

150
160
180
200

l HOWPAID(LSEAT)

300
400
500

LINES = LINES + l
IF (LINES .GE. 19) THEN
IX= SYS$BINTIM(%DESCR(TIMEDELAY) ,DELAY)
IF (,NOT. IX) GO TO 900
IX= SYS$CLREF(%VAL(l))
IF (.NOT. IX) GO TO 900
IX= SYS$SETIMR(%VAL(l) ,DELAY,,)
IF (.NOT. IX) GO TO 900
IX= SYS$WAITFR(%VAL(l))
IF (,NOT. IX) GO TO 900
TYPE 10h0, TOPOFSCREEN
LINES = 0
END IF
CONTINUE
CONTINUE
CONTINUE
IX = SYS$BINTIM(%DESCR(TIMEDELAY) ,DELAY)
IF (.NOT. IX) GO TO 900
IX= SYS$CLREF(%VAL(l))
IF (.NOT. IX) GO TO 900
IX= SYS$SETIMR(%VAL(l),DELAY,,)
IF (.NOT. IX) GO TO 900
IX= SYS$WAITFR(%VAL(l))
IF (.NOT. IX) GO TO 900
TYPE lOnO, TOPOFSCREEN
GO TO 90

c
900

CALL LIB$SIGNAL(%VAL(IX))
END

7-52

PROGRAM EXAMPLES
$
$
$
$
$
$
$
$
$
$
$
$
$
$
$
$
$
$

BLDVMSAIR.COM
COMMAND FILE TO REBUILD FROM SOURCE
THE AIRLINE RESERVATION SYSTEM WHICH IS
A DEMO OF SHAREABLE IMAGES
FORTRAN/LIST/MACHINE CODE DATABASE
FORTRAN/LIST/MACHINE-CODE INTERLOCK
FORTRAN/LIST/MACHINE-CODE RESERVE
FORTRAN/LIST/MACHINE-CODE DISPLAY
FORTRAN/LIST/MACHINE-CODE CANCEL
FORTRAN/LIST/MACHINE-CODE MONITOR
LINK/SHAREABLE/MAP/FULL/CROSS DATABASE,INTERLOCK,DATABASE/OPTIONS
LINK/MAP/FULL/CROSS RESERVE,GETSHRIMG/OPTIONS
LINK/MAP/FULL/CROSS DISPLAY,GETSHRIMG/OPTIONS
LINK/MAP/FULL/CROSS MONITOR,GETSHRIMG/OPTIONS
LINK/MAP/FULL/CROSS CANCEL,GF.TSHRIMG/OPTIONS
PURGE *·*

DATABASE. OPT
LINK TIME OPTIONS DESCRIPTION FILE TO BUILD
THE SHARABLE IMAGE CONTAINING THE DATA BASE AND
THE INTERLOCK ROUTINE
UNIVERSAL=LOCKFLIGHT,UNLOCKfLIGHT

MAKE ROUTINE ENTRY POINTS
ACCESSIBLE TO USER PROGRAMS
SET GLOBAL SECTION MATCH CONTROL

GSMATCH=LEQUAL,0,0000

GETSHRIMG.OPT
LINK TIME OPTIONS FILE TO ACQUIRE THE SHARED
DATABASE AND INTERLOCKING ROUTINE.
DATABASE/SHARE=NOCOPY

MAPPED INTO ADDRESS SPACE

7-53

APPENDIX A
LOCKING A RESOURCE

A semaphore is a metering device that provides the capability of
controlling access to a set of resources. A semaphore that controls
access to a single resource is called a mutex (mutual exclusion) or,
more commonly, a lock.
You can perform two operations on a mutual exclusion semaphore (lock):

•

Lock - Test to see if the resource is free • If it is, then
take
(use) it and proceed with execution. If the resource is
not free, execution is stalled until the resource becomes
available.

•

Unlock - Give the resource back (make it available to others)
when it is no longer needed.
If any other processes are
stalled waiting for the resource, they are awakened.

Locking and unlocking must be interlocked operations, so that no race
conditions result. An example of a race condition is as follows:
in
the middle of the first process's test for a resource's availability,
the resource is returned by another process, but the return goes
unnoticed by the first process.
Two methods of creating a lock are (1) using a common event flag or
(2)
using a queue. In selecting either method, you must consider how
you want to service requests for the resource, how important is ease
of use, and how quickly the method must execute. Table A-1 contrasts
the two methods.
Table A-1
Two Methods of Creating a Lock
Queue

Event Flag
1.

Requests serviced according
to process priority

Requests serviced on a
first-in first-out (FIFO)
or a last-in first-out
(LIFO ) ba sis

Easy to use

More complicated to use
(requires a global section and special data
structures)

Uses time manipulating
the event flag

Executes at hardware
instruction speed when no
conflict occurs

A-1

LOCKING A RESOURCE
A.l

USING AN EVENT FLAG

Cooperating processes can control access to a resource by
common event flag as a lock. The procedure is as follows:

using

An initialization process is run to create a permanent common
event flag cluster and to set the initial state of all J2
flags to 1. This provides 32 individual locks.

Each cooperating process must associate with the common event
flag cluster.

Before any process uses the resource represented by a
it must execute the logic shown in
particular event flag,
Figure A-1.

Clear event flag

5$:

$CLREF_S

EFN=#G5

CMPL R01#SS$_WASSET
BEQL 10$

Yes

$WA ITFR .... S EFN=#G5
BRW
5$

Wait for event
flag

Proceed to
access
resource

10$:

;Proceed

$SETEF_S

Figure A-1

EFN=#G5

Event Flag Lock Logic

Because the initial state of the event flag is 1, only one process at
a time will be able to clear the event flag and find its previous
state to be a 1. All subsequent processes will find the previous
state to be O, and thus will wait until the owner process sets the
flag.
(This occurs when the owner process is finished with the
resource and returns it.)

A-2

LOCKING A RESOURCE

Setting the event flag causes all the waiting processes to awaken and
compete for CPU time according to their process priority (unless an
outstanding I/O
request
or
some
other
factor
prevents
a
higher-priority process from becoming computable). However, only one
waiting process will be able to clear the event flag and find its
previous state to be a 1.
(Note:
Clearing an event flag is an
interlocked operation implemented by VAX/VMS.)
Figure A-2 is a VAX-11 FORTRAN example using a common event flag as a
lock.
Note that in Figure A-2 it is not necessary to run an
initialization process (step 1 at the beginning of this section),
because the program logic prevents a race condition from occurring
during lock initialization.
INTEGER*4 SYS$ASCEFC,SYS$SETEF,SYS$CLREF,SYS$WAITFR,STATUS
EXTERNAL SS$_WASSET,SS$_WASCLR

c-- Associate with a common event flag cluster to be used as a mutual exclusion
c-- semaphore. If the cluster does not exist, it is created. The first two
C-- flags are used to avoid any race conditions during initialization.
STATUS= SYS$ASCEFC{%VAL{64} ,'MUTEX' ,,}
IF {.NOT. STATUS} CALL LIB$STOP{%VAL{STATUS}}
IF {SYS$SETEF{%VAL{64}} .EQ. %LOC{SS$ WASCLR}} THEN
CALL SYS$SETEF{%VAL{66}}
CALL SYS$SETEF{%VAL{65)}
ELSE
CALL SYS$WAITFR{%VAL{65}}
END IF

If creator
Init mutex
Set initialized
Initialized wait

C-- Perform any other program initialization
CONTINUE
C-- Obtain exclusive access to the mutex to make sure no other process
C-- will execute its critical section while we do.
If the mutex cannot be
c-- obtained, wait for it to be released.
50

STATUS= SYS$CLREF{%VAL{66}}
IF {STATUS .EQ. %LOC{SS$ WASSET}} GOTO 100
STATUS= SYS$WAITFR{%VAL(66}}
GOTO 50

c-- Execute the critical section of the program
100

CONTINUE

C-- Release the mutex and unblock any other processes that might have
C-- been waiting.
If more than one is waiting, the first one to obtain the
C-- the mutex will get it, and the others will fail and wait again.
CALL SYS$SETEF{%VAL{66})
GOTO 50
END

Figure A-2 Event Flag Lock Example

A-3

LOCKING A RESOURCE
A.1.1

Shared Memory Considerations

You can use an event flag in a shared memory common event flag cluster
to guarantee that only one process uses a resource at a time.
However, because of potential differences in the speeds and workloads
of the processors connected to the shared memory, there is no
assurance that the highest-priority waiting process will get the
resource each time it becomes available.

A.2

USING A QUEUE

Cooperating processes can use a queue to lock a resource and, after
unlocking, make the resource available on either a first-in first-out
(FIFO) or last-in first-out
(LIFO) basis.
(Queues and the queue
instructions are explained in the VAX-11 Architecture Handbook.) The
procedure is as follows.
1.

An initialization process must be run to create
global section and initialize a queue header.

permanent

To use the resource represented by the queue header, each
process must map the global section. Each process must also
create a 3-longword description with the following format in
the global section:
Forward link

Backward link
Process ID
"--------------------'
3.

Before any process uses the resource represented by the queue
header, it must execute the logic shown in Figure A-3.
(Figure A-3 shows a FIFO queuing policy. Figure A-4 later in
this appendix shows a LIFO policy.)

A-4

LOCKING A RESOURCE

Insert its description
into queue at tail

Yes

5$:

INSQUE

DESC1@HEADER+4

BEOL

10$

$HIBER_S

CMPL
BNEQ

DESC, HEADER
5$

REMQUE

@HEADER,RO

BEQL

20$

Yes

Access resource

10$:

Remove its description
from queue at head

Yes

MOVL
HEADER1Rl
$WAKE_S PIDADR=8(R1l

Wake first process
in queue

Proceed with
execution

Figure A-3

20$:

FIFO Queuing Policy

Because the initial state of the queue is empty, only one process will
be able to insert its entry in the queue and find it to be the first
entry. Each subsequent process will find more than one entry after
inserting itself, and thus will hibernate.

A-5

LOCKING A RESOURCE

When the owner process is finished using the resource, it simply
removes its description from the head of the queue. If the queue is
then empty, no process is waiting. If the queue is not empty, the
process whose ID is first in the queue is awakened, and that process
can now use the resource.
(Note:
The queue instructions are
interlocked operations implemented by the VAX-11 processor.)
Figure A-3 and its explanation described a FIFO queuing
Figure A-4 shows the logic for a LIFO queuing policy.

A.2.1

policy.

Shared Memory Considerations

The logic and coding in Section A.2 cannot be used
shared memory for the following reasons:
•

The Wake ($WAKE) system service cannot
process running on another processor.

•

The interlocked queue instructions
INSQTI, REMQHI, REMQTI).

must

with

used
be

used

queue

wake

(INSQHI,

To use a queue in shared memory, you must devise a more complicated
mechanism.
(Such a mechanism is beyond the scope of this manual.)

A-n

LOCKING A RESOURCE

Insert its description
into queue at tail

Yes

5$:

INSQUE

DESC,@HEADER+a

BEQL

10$

$HIBER_S

CMPL
BNEQ

DESC1HEADER
5$

REMQLJE

@HEADER+a,Ri

BEQL

20'1i

Yes

10$:
Access resource

Remove entry from
queue at tail

Yes

Insert that entry in
queue at head
Remove its own entry
from queue
Wake entry moved to
head of queue

Proceed with
execution

REMQLJE
@HEADER1RO
I NSQUE
(R 1) ,@HEADER
$WAKE_S PIDADR=81R1l

20$:

A-4 LIFO Queuing Policy

A-7

APPENDIX B
LPAll-K CONSIDERATIONS

Users should consider three factors
Laboratory
Peripheral
Accelerator
application:

in selecting and using the
(LPAll-K)
for
a real-time

•

The effect on performance
hardware configuration

resource

•

Throughout and response-time requirements of the application

•

The LPAll-K driver's use of
calls

parameters

availability

data

and

acquisition

The remainder of this appendix discusses each of these considerations.

B.l

RESOURCES, CONFIGURATION, AND PERFORMANCE

One factor that determines the performance of the LPAll-K is its
interaction with other devices and applications in the system. The
LPAll-K is designed as a real-time device. Its function is to sample
data synchronously with a real-time clock. However, if for any reason
the LPAll-K cannot maintain this synchronous transfer of data, a
nonretriable error is generated. This method of operation contrasts
with that of a disk, which can perform a retry because the original
data is still available (in memory for a write or on disk for a read).
In a real-time application, however, after the event of interest has
passed it may no longer be of interest.
Therefore, the resources needed to carry out an application in real
time must be guaranteed to be available. Some of the resources that
must be available to use the LPAll-K in real time are UNIBUS adaptor
map registers to map the buffers, UNIBUS adaptor data path, UNIBUS
direct memory access (DMA)
transfer bandwidth, processor interrupt
response time, memory in the working set for data buffers, and CPU
execution time for the application program.
If the application
buffers the data for storage on disk, the following resources must
also be available:
the disk controller and drive, -and sufficient
bandwidth and adaptors for the MASSBUS or UNIBUS (depending on where
the disk is interfaced).
The VAX/VMS system gives the application program control over many
system resources, to guarantee their availability when these resources
are needed. Processes can lock critical pages, thus ensuring the
availability of that memory. Processes can adjust their priority to
guarantee access to CPU execution time and
to
mass
storage
controllers.

B-1

LPAll-K CONSIDERATIONS
In other areas, however, control over resources is difficult, often
because
the resources are being used concurrently and involve
interrupt handling and contention for bandwidth on I/O buses.
In
fact,
several studies have concluded that the major impact on LPAll-K
performance is UNIBUS I/O bandwirlth contention.
The LPAll-K detects two classes or errors
performance:

associated

with

real-time

•

Buffer overrun/underrun -- deals with the ability of the
application program to supply new memory buffers fast enough
(for example, to process data at least as fast as it is coming
in)

•

Data overrun/underrun -- deals with the ability of the device
to arbitrate for UNIBUS cycles and to transfer data to and
from main memory

Buffer overrun/underrun errors often reflect inadequate application
control over resources;
data overrun/underrun errors are usually
caused by I/O contention.
The first class of errors, buffer overrun/underrun, is a function of
the application.
The application must run at a priority high enough
to guarantee it sufficient CPU time. It must also have a working set
large enough to hold in physical memory the data buffers and the code
that performs computation on the data, to prevent excessive paging (or
perhaps to prevent any paging at all). However, if these control
measures have been taken and the buffers are large enough, and if
buffer overrun/underrun errors still occur repeatedly, then the data
rate is too fast for the work that needs to be done.
In this case,
the solution might be to buffer the data to intermediate mass storage
for future processing.
The second class of errors, data overrun/underrun, is a function of
UNIBUS and memory I/O contention. As other OMA devices on the UNIBUS
become concurrently active, the effective throughput rate of the
LPAll-K can be significantly reduced. If LPAll-K throughput falls
below the application's requirements, an additional UNIBUS adaptor may
be needed.

B.2

THROUGHPUT AND RESPONSE-TIME REQUIREMENTS

The LPAll-K and its support under VAX/VMS are tailored primarily for
throughput-intensive applications. This device can recognize a simple
event, such as a single digital signal, and start data acquisition
when the event occurs.
However,
if the application must respond
quickly to events represented by the contents of the data being
acquired, the LPAll-K might not be suitable for two reasons:
•

The LPAll-K samples analog or digital data and stores it in
large data buffers in main memory, generating an interrupt
only when a buffer is full. Thus,
if the application must
detect a particular data value and respond quickly, it might
have to wait for an entire buffer to be filled before it could
start searching for the value.

•

VAX/VMS is designed
to
manage
LPAll-K
data
buffers
transparently
for
application
programs.
This
buffer
management involves some software overhead.
Thus,
if data
buffers were made very small
(the smallest beinq one data
point per buffer) in an effort to access data points sooner,
the software overhead would grow considerably.
B-2

LPAll-K CONSIDERATIONS
B.3

PARAMETERS FOR DATA ACQUISITION CALLS

The LPAll-K uses parameters in some data acquisition procedures.
For
example, assume that an application must acquire a stream of analog
data from several points at a specific rate per point, store the
digitized data in memory, and stop when enough data has been taken.
To accomplish these goals, you must specify the following parameters:
analog-to-digital conversion, the analog data channels to sample, the
sample rate, the place in memory to store the data, and the amount of
data to be taken. At the start of each data acquisition session, the
application provides these values as parameters to the LPAll-K driver.
Data acquisition calls using parameters have the advantages of
isolating the application from the actual hardware and simplifying the
programming:
the application programmer does not need to write
interrupt
service
routines in assembly language or microcode.
However, this approach might not be adequate for certain complicated
applications requiring a sophisticated sampling algorithm or complex
interactions between multiple data acquisition streams.
If the
application
requires
capabilities not provided by the LPAll-K
parameters, other devices should be investigated.

B-3

APPENDIX C
VAX-11 BLISS-32 PROGRAM EXAMPLE

This appendix
shows
a
VAX-11
BLISS-32
program
using
the
connect-to-interrupt capability.
The functions performed by the
program are described in the "Abstract" near the beginning of the
listing and in comments throughout the program. This program is only
a simple illustration of connecting to an interrupt vector and does
not reflect a typical real-time situation {for example, the line
printer is not a real-time device).
MODULE lpmultast(%TITLE'line printer driver' MAIN=lp_main, IDENT='X02')=
COPYRIGHT (c) 1980 BY
DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS.
THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE
INCLUSION OF THE ABOVE COPYRIGHT NOTICE.
THIS SOFTWARE OR ANY OTHER
COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY
OTHER PERSON.
NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY
TRANSFERRED.
THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT
CORPORATION.
DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL.

++
FACILITY:
A sample program that illustrates the use of the connect to
interrupt facility.
ABSTRACT:
This program assigns a channel to a line printer device, and
then connects to the device via the connect to interrupt
facility. The program then requests the name of a file from
the user, and outputs that file on the line printer.
%SBTTL
BEGIN

'External and local symbol definitions'

LIBRARY 'SYS$LIBRARY:LIB';

! Get important definitions

PSECT

C-1

ITS

VAX-11 BLISS-32 PROGRAM EXAMPLE
!+
! Define some PSECTs which we will need to refer to later
!-

OWN=
OWN=
LINKAGE
intrupt=
cancel=

sharedata(ALIGN(9),WRITE),
data;
JSB(REGISTER=2, REGISTER=4, REGISTER=5):
NOPRESERVE(O,l,2,3,4) NOTUSED(o,7,8,9,10,11),
JSB(REGISTER=2, REGISTER=3, REGISTER=4, REGISTER=5):
NOTUSED(o,7,8,9,10,11);

FORWARD ROUTINE
lp interrupt:
intrupt PSECT(sharedata),
lp-cancel: NOVALUE cancel PSECT(sharedata),
lp-main,
lp-isr ast,
lp:=ioclone_ast;

Interrupt server
Cancel I/O

Static Definitions
LITERAL
true
false =

1,
O,

io _page count
io_space_base

Pages needed in UNIBUS I/O space

%x'20100000',

Physical address of UBA 0 space
for VAX-11/780. Other processors
need different magic number .••

unibus lp_addr= %0'777514',

18-bit addr of LPll CSR

Calculate the page-frame number to map to get the physical address
that the unibus is mapped on.
io_page __Pfn = (io_space_base + unibus lp_addr)/512,
lp_csr_offset

%0'514',

filename_length

100,

record bufsiz
prompt:=length

Offset to printer CSRs.

256,

28;

OWN
lpchan:

WORD,

! Line printer channel number.

filename buffer:
file descr:
fdlen:

VECTOR[filename length,BYTE],
VECTOR[2] INITIAL( filename length, filename_buffer),
WORD,
-

record buffer:

VECTOR[record_bufsiz,BYTE),

file fab:

$fab(

! Input file fab

C-2

VAX-11 BLISS-32 PROGRAM EXAMPLE
Functional description:
This routine services an interrupt from the line printer
device. If the interrupt was expected, the routine disables
output interrupts. The disable is an optimization to prevent one
interrupt per character. With output interrupts disabled, the
line printer buffers characters until the device needs to output
the characters. Then the main program enables output interrupts
only for the period of time necessary for the device to empty
the buffer.
Then the interrupt service routine loads a success status into
RO and returns.
If the interrupt was not expected, the routine just loads
an error status into RO to prevent delivery of an AST to the
owning process and returns.
Inputs:
R2
R4
RS

- address of a counted argument list
- address of the IDB
- address of the UCB

The counted argument list is as follows:
0 (R2)
4 (R2)
8 (R2)
12 (R2)
16(R2)

count of arguments (4)
the system-mapped address of the user buffer
the system-mapped address of the device's CSR
the IDB address
the UCB address

Outputs:
The routine must preserve all registers except RO-R4.
BEGIN
MAP
arglist:
REF VECTOR[,LONG],
ucb:
REF BLOCK[,BYTE],
idb:
REF BLOCK[,BYTE];
BIND
arglist [l]:
bufadr
REF BLOCK FIELD(buf);

System adr of buffer

BUI LTIN
TESTBITCC;
IF TESTBITCC( bufadr[buf$l_flags]
THEN
RETURN O;

No interrupt expected, no AST wanted

(.idb[idb$l_csr])<0,16>

Disable the output interrupt

ss$ normal
END;
%SBTTL 'LP_CANCEL, Cancel I/O on Line Printer'
ROUTINE lp_cancel( chan_idx, irp, pcb, ucb ): NOVALUE cancel PSECT(sharedata)=
!++

Functional description:
This routine disables output interrupts from the line printer.

C-3

VAX-11 BLISS-32 PROGRAM EXAMPLE
fac=get,
fna=filename_buffer,
org=seq,
rfm=var,
dnm='TEST.LIS'),
file rab:

$rab(
fab=file_fab,
rac=seq,
ubf=record buffer,
usz=record=bufsiz),

io_page limits:

VECTOR [ 2)
INITIAL(200,
200);

Addresses of process-mapped
UNIBUS I/O paqe. 200 tells $CRMPSC
to map pages in PO space

BIND
onesecond delta=
UPLIT(-10*1000*1000,-1);

Delta time format for one
second.

!+
! Define offsets into the buffer that will be shared by the user
! process and the process routines that execute in kernel mode.
!-

FIELD
buf=
SET
bu f $1 flags=
buf$v int=

[0,0,32,0),
[O, 0, 1,0),

buf$w charcount=[4,0,16,0),
buf$1-startdata=[8,0,32,0J
TES, -

Flags longword.
Interrupt expected
Number of chars in buffer
Start of data in buffer.

lp=
SET
lp csr=
lp-dbr=

[0,0,16,1),
[2,0,8,0J

Offset to line printer CSR
Offset to line printer data

TES;

%SBTTL

'Double Mapped Page Buffers'

OWN
output_buffer:
PSECT
OWN=
PLIT=

BLOCK[512,BYTE) FIELD(buf) PSECT(sharedata);

sharedata,
sharedata;

The routines to be executed in kernel mode must follow directly
after this allocation of bytes to hold output data.
%SBTTL

'LP_INTERRUPT, Interrupt service routine'

ROUTINE lp_interrupt( arglist, idb, ucb ): intrupt PSECT(sharedata}=

!++

C-4

VAX-11 BLISS-32 PROGRAM EXAMPLE

Inputs:
R2
R3
R4
RS

- negated value of the channel index number
- address of the current !RP {I/O request packet)
- address of the PCB {process control block) for the
process canceling I/O
- address of the UCB {unit control block)

Outputs:
none
BEGIN
MAP
irp:
pcb:
ucb:

REF BLOCK[,BYTE],
REF BLOCK[,BYTE],
REF BLOCK[,BYTE];

BIND
crb=
LOCAL
csr:

.ucb[ucb$l_crb]:

BLOCK[,BYTE];

REF BLOCK[,BYTE] FIELD{lp);

UNIBUS addr.

csr = •• {crb[crb$l_intd] + BLOCK(O, vec$l_idb;O,BYTEJ);
csr [lp csr] = 0
END; %SBTTL 'LP_MAIN, the main routine'

! Addr of CSR

! Disable output interrupts.

ROUTINE lp main: PSECT{$CODE$)=
•++
LP_MAIN, the routine that controls the others
Functional description:
1. Assign a channel to the line printer.
2. Map the process to the I/O page.

3. Issue a connect to interrupt QIO to get the line printer.
4. Prompt the user for a file name.
5. Open and connect to the file.
6. Write the contents of the file to the line printer.
Inputs:
none
Outputs:
RO

- status code
SS$ NORMAL
RMS-code
SS$ DEVOFFLINE

- success
- error in opening or reading
the file
- error is writing to printer

BEGIN
PSECT

C-5

VAX-11 BLISS-32 PROGRAM EXAMPLE
OWN=

$OWN$;

OWN
buffer desc: VECTOR[2] INITIAL(
512+512,
output_buffer),

Descriptor of buffer shared
by process and kernel mode
process routines.

entry_list: VECTOR[4] INITIAL(

List of offsets to kernel
mode routines: init device;
start device;
interrupt servicing;
cancel I/O.

O,
lp interrupt-output buffer,
lp=cancel-output_buifer);

LOCAL
csr:
REF BLOCK[,BYTEl FIELD(lp) VOLATILE,
status;
EXTERNAL ROUTINE
lib$get_input;
Assign a channel to the line printer.
status

$assign (
devnam=$DESCRIPTOR('LPAO'),
chan=lpchan);

Assign channel to line
printer

IF NOT .status THEN RETURN .status;
Map the UNIBUS I/O page to the process so that the line printer's
device registers are accessible.
status

$crmpsc(
Map I/O page to process.
inadr=io page limits,
retadr=io page limits,
flags=secSm wrt OR sec$m pfnmap OR sec$rn_expreg,
pagcnt=io paqe count,
vbn=io_page_pfn );

IF NOT .status THEN RETURN .status;
Issue a connect to interrupt QIO to the line printer device. This
connection will allow the program to control and handle interrupts
from the device.
status

$gio(
Connect the process to the
chan=.lpchan,
line printer device.
func=io$ conintread,
Specify a read only buffer.
astadr=lp iodone ast,
Specify an AST routine.
pl=buffer-desc, Specify a shared buffer.
p2=entry list,
Specify routine entry points.
p3=cin$m=isr OR cin$m cancel,
Specify ISR, cancel routines.
Specify an interrupt AST.
p4=lp isr ast,
p6=sJT
Specify an AST count.

IF NOT .status THEN RETURN .status;

C-fi

VAX-11 BLISS-32 PROGRAM EXAMPLE
Ask user what file to print.
status

lib$get_input( file descr,
$descriptor('Name of file to be printed: '),
file_descr[O]);

IF NOT .status THEN RETURN .status;

Open and connect file.
file_fab[fab$b_fns] = .file_descr[O];

Length of spec.

status= $open(fab=file_fab);

Open file.

IF NOT .status THEN RETURN .status;
status= $connect( rab = file_rab );

Connect file.

IF NOT .status THEN RETURN .status;
Get a record at a time until end of file. Surround record's contents
with a linefeed and a carriage return.
WHILE status
BEGIN
LOCAL
inp,
outp;

$get(rab=file_rab) DO

outp =output buffer[buf$1 startdata];
CH$WCHAR_A( %CHAR(%X'A'), outp);

Target for first character
Start with a line-feed

inp = record_buffer;
Load length of this output buffer in the buffer header. Then copy
the contents of the input buffer to the output buffer. Translate all
lower case alphabetics to upper case characters.
output_buffer[buf$w_charcount] = .file_rab[rab$w_rsz] + 2;
DECR i FROM .file rab[rab$w rsz]-1 TO 0 DO
BEGIN
LOCAL
char;
char= CH$RCHAR A( inp );
SELECTONE .char-OF
SET
[ %C 'a ' TO %C' z ' ] :
TES;

char

CH$WCHAR_A( .char, outp )

C-7

.char - %X'20';

Upcase

VAX-11 BLISS-32 PROGRAM EXAMPLE
END;
CH$WCHAR_A( %CHAR(%X'OD'), outp );

I Put CR at end.

Send characters one at a time to the line printer. Before sending a
character, see if the line printer is still in ready state. If not,
set a timer to go off in one second, and go to sleep. When an AST
occurs -- either because of a line printer interrupt, or because
the timer runs out, the AST routine will wake the process up again.
If the line printer is still in ready state, just send the next
character.
outp =output buffer[buf$1 startdata];
csr = .io_page_limits + lp:csr_offset;

! Addr of output string
! Addr of LP's CSR

DECR i FROM .output buffer[buf$w charcount)-1 TO 0 DO
WHILE 1 DO
BEGIN
BIND
devbits= csr[lp_csr]: VOLATILE SIGNED WORD;
CASE SIGN(.devbits) FROM -1 TO 1 OF
SET
[-1):
RETURN ssS_devoffline;
BEGIN
csr[lp dbr]
EXITLOOP
END;

[ l]:

[O]:

Paper problem, maybe
Output a character

CH$RCHAR_A( outp );
Back for next char

Line printer is not ready. See whether it's in
trouble, or just busy. If it's in trouble, stop
program with error status. Otherwise, just wait
until it comes ready again.
!-

BEGIN
output buffer[bufSv int] =true;
csr[lp-csr] = .csr[Ip csr] OR %X'40';
status-= $setimr(
daytim=onesecond delta,
astadr=lp_isr_ast);

Interrupt expected
Enable LP interrupts
Set a one second timer.

IF NOT .status THEN RETURN .status;
Go to sleep.
Cancel timer request

Shiber;
$cantim ()
END
TES
END
END;

End $GET loop

IF .status NEQ ss$_endoffile
THEN
RETURN .status;

C-8

APPENDIX D

REAL-TIME OPTIMIZATION CHECKLIST

This appendix lists suggestions that usually improve real-time program
performance.
There is no guarantee, however, that any suggestion is
appropriate for all applications. You must consider the needs of each
application and the overall system activity when you evaluate any
suggestion.
1.

Avoid costly operations
operations include:

time-critical

File opens or extensions

Mailbox creation

Common event flag cluster creation

Device allocation

Error reporting

Avoid window turns on critical files.
a.

Use contiguous files

Specify a large window size

Inhibit system paging.
SYSGEN utility to:

Specify

code.

Costly

Suggestions:

parameter

values

the

Disable system code paging (SYSPAGING

Disable paging of pageable dynamic pool (POOL_PAGING

Specify a large system working set (SYSMWCNT)

= 0)

However, before adjusting any of the parameter values,
read
the explanation of the parameter and any cautions in the
VAX/VMS System Manag_~~--~ Q~<_!~.
4.

Use the Queue I/O Request ($QIO) system service directly
I/O.
a.

Setting an event flag is the fastest means of
I/O completion

Using an AST is more time-consuming

D-1

for

signalling

REAL-TIME OPTIMIZATION CHECKLIST

Global sections provide the
interprocess communication.

Waiting for an event flaq and usinq hibernate/wake
the fastest methods of interprocess signalling.

D-2

lowest-overhead

means

provide

INDEX

A
Accessing device registers, 4-10
ACP (ancillary control process),
4-2
Adjust Working Set Limit
($ADJWSL) system service, 2-6
Airline reservation system
(example), 7-45 to 7-53
Allocation, device, 1-4
Ancillary control process (ACP),
4-2
Associate Common Event Flag Cluster ($ASCEFC) system service,
3-3
Asynchronous system trap (AST),
3-8
conditions preventing delivery,
3-9
effect of access mode on delivery, 3-8, 3-9
service routine, 3-8, 3-9

Connect-to-interrupt
capability, (Cont.)
examples, 4-22 to 4-28, 7-6 to
7-44, C-1 to C-11
interrupt service routine,
4-14, 4-15, 4-16, 4-18,
4-19, 4-21
IPL, significance of, 4-11,
4-12
language constraints, 4-19
overview, 4-11
performing, 4-12, 4-13, 4-15
to 4-18
$QIO format, 4-15 to 4-18
start I/O routine, 4-20
timings, 4-11
Create Mailbox and Assign Channel
($CREMBX) system service,
3-5, 3-6
Create Process ($CREPRC) system
service, 2-3, 2-4

B
Balance set, 2-5
lock working set in, 2-8
Base priority (process), 1-9, 1-11
BLISS-32 example, C-1 to C-8

c
Change-mode vector, 6-2, 6-3
Common event flags, 3-2 to 3-4
associating with a cluster, 3-3
creating a cluster, 3-3
mutex use, A-2 to A-4
shared memory, 5-5, 5-~
permanent clusters, 3-3
setting, 3-3, 3-4
temporary clusters, 3-2
waiting for, 3-4
Condition handling, 1-4
CONINTERR, 4-13, 4-14
Connect-to-interrupt capability,
AST service routine, 4-14 to
4-16
benefits, 4-6, 4-7
cancel I/O routine, 4-21, 4-22
conventions for user routines,
4-18 to 4-22
device initialization routine,
4-20
disconnecting, 4-15, 4-18, 4-21,
4-22
driver, 4-13, 4-14

Data acquisition example,
explanation, 7-1 to 7-5
listings, 7-5 to 7-44
Deductible quotas, 1-7, 1-8
Detached process, 2-1 to 2-5
contrasted with subprocess,
2-2, 2-3
creating, 2-3 to 2-5
real-time programming uses, 2-3
Device allocation, 1-4
Device drivers, 4-2, 4-3
connect-to-interrupt, 4-13, 4-14
Device registers, 4-10
DMCll, 1-6
Drivers, 4-2, 4-3
connect-to-interrupt, 4-13,
4-14

E
Event flags, common (see "Common
event flags")
Examples,
accessing device register, 4-10
airline reservation system,
7-45 to 7-53
BLISS-32, C-1 to C-8
connect-to-interrupt, 4-22 to
4-28, 7-6 to 7-44, C-1 to
C-11
create process, 2-5, 3-7
event flaq, A-3

Index-1

INDEX

Examples, (Cont.)
hibernate/wake, 3-11, 3-12
LABIO system, 7-n to 7-44
lock (resource), A-3, A-5, A-7
mailbox, 3-7, 5-7
multiple features, 7-n to 7-44,
7-45 to 7-53
mutex, A-3, A-5, A-7
privileged shareable image,
6-5 to 6-24
queue (for mutex), A-5, A-7
RUN (process), 2-5
scheduled wakeups, 3-11, 3-12

G
Global sections, 3-12 to 3-15
advantages in using, 3-13, D-2
contrasted with VAX-11 RMS,
3-13
creating, 3-12, 3-14, 3-15
deleting, 3-15
mapping, 3-12, 3-14, 3-15
permanent, 3-13
shared memory, 5-7 to 5-10
temporary, 3-13
updating, 3-15

H
Hibernation, 3-9 to 3-12
contrasted with suspension, 3-10
examples, 3-10 to 3-12

Lock Pages in Memory ($LCKPAG)
system service, 2-7, 2-8
Lock Pages in Working Set ($LKWSET)
system service, 2-6, 2-7
Logical name translation (shared
memory facilities), 5-3,
5-4
LPAll-K (Laboratory Peripheral
Accelerator), 1-5, B-1 to B-3

M
MA780 (See "Shared (multiport)
memory")
Mailboxes, 3-4 to 3-7
creating, 3-5
examples, 3-7, 5-7
permanent, 3-5
process termination, 3-5
shared memory, 5-6, 5-7
temporary, 3-5
Memory,
lock pages in, 2-7, 2-8
lock process working set in,
2-8
Memory management, 2-5 to 2-8
overview, 2-5
system services, 2~5 to 2-8
Multiport memory (see "Shared
(multiport) memory")
Mutex, A-1 to A-7
shared memory considerations,
A-4, A-n
using a queue, A-4 to A-7
using an event flag, A-2 to A-4

I/O posting routine, 4-3
I/O space, 4-7, 4-8
accessing, 4-8 to 4-10
Interrupt priority level (IPL),
4-11, 4-12
Interrupt service routine (userspecified), 4-14, 4-15, 4-18,
4-21

Name string format (shared memory
facilities), 5-3
Networks, 1-5
Nondeductible quotas, 1-7, 1-8

0
Optimization checklist, D-1, D-2

L
LABIO system (example),
explanation, 7-1 to 7-5
listings, 7-5 to 7-44
Laboratory Peripheral Accelerator
(LPAll-K), 1-5, B-1 to B-3
Lock (resource), A-1 to A-7
shared memory considerations,
A-4, A-fi
using a queue, A-4 to A-7
using an event flag, A-2 to A-4

p
Page frame number (PFN) mapping,
4-8 to 4-10
Permanent event flag clusters, 3-3
Permanent global sections, 3-13
Permanent mailboxes, 3-5
PFN mapping, 4-8 to 4-10
Physical memory control, 2-5 to
2-8

Index-2

INDEX

Pooled quotas, 1-7, 1-8
Priority, 1-9 to 1-11
adjusting base priority, 1-11
base, 1-9, 1-11
privileges required to adjust,
1-11
significance, 1-10
timesharing vs. real-time, 1-9
Privileged shareable image,
change-mode vector, n-2, n-3
coding, 6-1 to 6-4
dispatcher, 6-3
example, 6-5 to 6-24
installing, 6-5
linking, 6-4, 6-5
purpose, n-1
using, 6-5
Privileges, 1-6, 1-7
masks, 1-7
partial listing, 1-6
setting, 6-3, 6-4
Process creation, 2~1 to 2-5
Process ID (programming suggestion), 3-10
Process priority (See "Priority")
Process quotas (See "Quotas")
Process swap mode, 2-8
Program examples (see "Examples")
Programming suggestions, 3-10,
D-1 I D-2
Protection (privileged shareable
image), 6-4, 6-5

Q
Queue I/O Request ($QIO) system
service, 4-1, 4-5, 4-6
connect-to-interrupt format,
4-15 to 4-18
Quotas, 1-7 to 1-9
deductible, 1-7
nondeductible, 1-7
pooled, 1-7
resource wait mode, effect on,
1-9
s u mm a r y , 1 - 8

R
Real-time application needs, 1-1
to 1-4
responsiveness, 1-1, 1-2
throughput, 1-1, 1-2
VAX/VMS features, 1-2 to 1-4
REALTIME SPTS parameter, 4-12,
4-13Registers (device), 4-10
Reservation system (example) ,
7-45 to 7-53

Resource wait mode, 1-9
Response time (real-time need),
1-1, 1-2
RMS (see VAX-11 RMS)
RUN -(process) command, 2-4, 2-5
example, 2-5

s
Scheduled wakeups, 3-10 to 3-12
Sections, global (see "Global
sections")
Semaphore (mutex), A-1 to A-7
shared memory considerations,
A-4, A-6
using a queue, A-4 to A-7
using an event flag, A-2 to A-4
Set Priority ($SETPRI) system
service, 1-11
Set Privileges ($SETPRV) system
service, 6-3, 6-4
Set Process Swap Mode ($SETSWM)
system service, 2-8
Setting event flags, 3-3, 3-4
Shareable images, 3-15 to 3-17
privileged, 6-1 to 6-16
Shared (multiport) memory, 5-1
to 5-10
common event flag clusters,
5-5, 5-6
global sections, 5-5, 5-7 to
5-9
logical name translation, 5-3,
5-4
mailboxes, 5-5 to 5-7
mutex considerations, A-4, A-6
name, 5-2, 5-3
preparing for use, 5-1, 5-2
privileges required to use,
5-2
search for facilities in, 5-5
Subprocess, 2-1 to 2-5
contrasted with detached process, 2-2, 2-3
creating, 2-3 to 2-5
real-time programming uses,
2-3
Suspension, 3-9, 3-10
contrasted with hibernation,
3-10
Swap mode (process), 2-8
SYSGEN utility,
parameter selection, 1-5, D-1
REALTIME SPTS parameter, 4-12,
4-13System services (see individual
service names),
user-written (see "Privileged
shareable image")

Index-3

INDEX

T
Temporary event flag clusters,
3-2
Temporary global sections, 3-13
Temporary mailboxes, 3-5
Throughput, 1-1, 1-2

VAX-11 BLISS-32 example, C-1 to
C-8
VAX-11 RMS,
contrasted with global section
use, 3-13
features of real-time interest,
4-4, 4-5
opening section file, 5-7

u
UNIBUS,
access errors, 4-9
power failure, 4-9
User Authorization File (UAF),
1-5
User privileges (See "Privileges")
User-written system services (see
"Privileged shareable image")

w
Waiting for event flags, 3-4
Waking a process, 3-10 to 3-12
Working set, 2-5
adjusting the limit, 2-6
locking pages in, 2-6, 2-7

Index-4

VAX/VMS
Real-Time
User's Guide
AA-H784A-TE
READER'S COMMENTS

NOTE:

This form is for document comments only.
DIGITAL will
use comments submitted on this form at the company's
discretion.
If you require a written reply .and are
eligible to receive one under Software Performance
Report (SPR) service, submit your comments on an SPR
form.

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

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

,,
Did you find errors in this manual?
page number.

If so, specify the error and the

::>
)

l>
)

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

.....

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

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

Name ___________________ ·-·--·-- Date ____.
Organization _ _ _ _ _ _ _~~·

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

City________________ State _______.___ Zip Code _ _ _ _ _ __
or
Countrv

Do Not Tear - Fold Here and Tape -

No Postag1
Necessary
if Mai led in 1
United Stat
1

[

uslNE-SS-REPLY~MA1L

,,,,

ST CLASS PERMIT N0.33 MAYNARD MASS.
- ---....................... _. _,, __
- -.....
,,_ _
-

_________

POSTAGE WILL BE PAID BY ADDRESSEE

BSSG PUBLICATIONS TW/A 14
DIGITAL EQUIPMENT CORPORATION
1925 ANDOVER STREET
TEWKSBURY, MASSACHUSETTS

Do Not Tear - Fold Here

01876