Digital PDFs

EK-1VAXD-TM-003

August 1983

488 pages

Original

85MB

view download

OCR Version

24MB

view download

Document:	VAX Diagnostic Design Guide
Order Number:	EK-1VAXD-TM
Revision:	003
Pages:	488
Original Filename:

OCR Text

EK-1VAXD-TM-003

- VAX Diagnostic

Design Guide

Prepared bv Educational services
Digital EQuipment Corporction

\‘
1

First Edition August 1979

Second Edition, March 1981
Third Edition, November 1983

The reproduction of this material, in part or whole, is strictly prohibited.
For copy information, contact the Educational Services Department,

Digital Equipment Corporation, Bedford, Massachusetts 01730.

Printed in U.S.A.

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 not be used or copied except in accordance with the terms of
such license.

Digital Equipment Corporation assumes no responsibility for the use
or reliability of its software on equipment that is not supplied by Digital.

The manuscript for this book was created using DIGITAL Standard
Runoff. Book production was done by Educational
Development and Publishing in Nashua, NH.

Services

The following are trademarks of Digital Equipment Corporation:

DATATRIEVE
DEC
DECmate
DECnet
DECset
DECsystem-10

DECSYSTEM-20

Rainbow

DECtape

flfl@flflflfl

DECUS
DECwriter
DIBOL
MASSBUS
PDP
.-

RSTS
RSX

UNIBUS
VAX

P/OS

VMS
VT

Professional

Work Processor

CONTENTS

¢«

o«

GOALS

FUNCTION

PARALLEL
AND

TESTS,

TESTING

AND

AND
.

EXERCISERS

TESTING.

MICROPROGRAMS

TOP-DOWN

The

VAX

METHODS

THE

VAX

PERFORMING

VAX

STRATEGY

o«

+«

Devices.

Cluster

Testing

the

Testing

Peripheral

Level

GuidelinesS.

©+v

Level

Guidelines

¢
¢

v
¢

o
o

o
o«

o
o

o
o
o
o

Guidelines

CPU

PROGRAMS.
.

STRATEGY.

DIAGNOSTIC

[]

THE

DIAGNOSTIC

I/0

[-]

APPLYING

ENVIRONMENTS FOR VAX DIAGNOSTIC
Diagnostic Supervisor .
.
.
.
.

INTRODUCTION

[}

'VAX DIAGNOSTIC PROGRAMS
INTRODUCTION.

¢
¢

S
l

USERS.
.

e
i

MACROPROGRAMS

W W

Level
Level

Level

Guidelines

GuldelineS.

o
¢

GuidelinesS.

¢«

Overview

the

Overview

Memory

Layout

Introduction

Diagnostic

.
.

o
o«

o
o

.
.

Program
.

¢«

o
o

P-Table

DescCriptors

.«

Macros.

¢«

the

Supervisor

.«

Format.

Introduction

VDS
to

Introduction

l.—-l

o«
o

Diagnostic

wwN

VAX

P-Table

[]

.
.

P-Tables.
.

.«

o
o
o
o
o
o
Descriptors

o
.

&
.

111

o
P-Table

w N+
>

Test

I
LWWWWWwWwwww
o
|
H—=ooooWUu
NN

o
e
o

+¢

THE STRUCTURE
OF A VAX SUPERVISOR'DIAGNOSTIC PROGRAM

P-TABLES.

Tests

wWw
e

Logic

Ul >

D W N

Guideline
Function

LevelLevel

[]

GUIDELINES FOR WRITING VAX DIAGNOSTIC PROGRAMS

[]

|J
[]
[]
[]
[]
[}

®
[]
®
[]
[]
[]
®

¢«

el
®

el el

NN
N

RUN-TIME

[]

AND

SO OO
UTUTUTD
WD N

NN NNODNODNNMNDNDNDNDDNDNDDNDNDDND
N

SERIAL

BOTTOM~-UP

wbwwww

TESTS,

[]

INTRODUCTION.

PROGRAMS

ENVIRONMENTS

LOGIC

[]

TESTING

CHAPTER

PROGRAM

DEFINITIONS

REQUIREMENTS

[]

RUN-TIME

DIAGNOSTIC

CHAPTER

Wwbwob

=
X

USER

~JOU

INTRODUCTION.
USES

MHXxOUJdIONOTND
NN

WHAT IS A DIAGNOSTIC PROGRAM?

CHAPTER

W W

=W
N

)

) _

U1
N

Table.

Program

Sections

[]

Ul
W N+~

[]
[]
[

w N

®
[

Ul
W N

=W
N -

3-22

¢«

Table.

¢«

3-23

3-22

3-23

CODE

3-24

Code

3-24

Services Used by the Inltlallzatlon Code.
.
Logical Units .
.
.
e
s
o
8
e
8
®
e
o
o
e
Program Passes and the Initialization Code.

.
»
.

3-24

Inltlallzatlon.Code

the

CODE.

o«

SUMMARY

ROUTINE

TESTS,

SUBTESTS,
«

Initialization

AND

3-25
3-25

EXxampleS.

3-26

3-27

3-28

SECTIONS

.«

3-29

Subtests.

¢«

o
o

SECEIONS.

3-31

ERRORS.

¢«

Error Message Formats

3-32

Control Flags

Preparation

EXrors.

EXYOrS

"Hard

Errors

Device-Fatal
v

«
o

o
o

o«
o

=
o

I1/0

with

&+«

the

3-34
3-35

3-35

o«

3-35

Errors

.«

3=-35
3-36

¢«

3-36

Boundaries.

3-37

«
o

¢
o

«
o

o«
o

o
o

=
o

3-38
3-39

¢«

3-490

3-43

Test.

¢«

3-43

Errors
.
o

Loop

.
o

System-Fatal
o+«

3-32

Assoc1ated

SOft

User-Specified

Defining

of LOOPS.
¢
+
o
¢
o

LoOOPIiNg.

Unit

Under

1in

User

Standalone Mode.

o«

.«

¢«

3-50

«
«

«
o

«
o«

o
o

=
o

3-52

User

3-41

I/O

the

Mode.

I/0

I1/0 with
N+

Characteristics
Nesting LOOPS «

3-22

o«
o

INPUT/OUTPUT.
ol ol

3-19
3-22

Program.

STRUCTURES

CONDITIONAL
AND UNCONDITIONAL BRANCHING .

NORE VO RN NS I O

3-13

VDS

Terminal.

Displaying Message Strings.
Prompting the User. « « ¢ ¢

.
«

«
«

«
o«

Displaying

HELP

Memory Management

Memory

Management

Memory

Allocation

SYNCHRONOUS

3-51

o«

3-54

User Mode.

.«

3-54
3-54

Standalone

Mode.

3-55

o
o

. .

o«

AND ASYNCHRONOUS

3-48

ALLOCATION.

TexXt.

AND

MANAGEMENT

MEMORY

'®

3-12

Tests.

LOOPING

[

~with Error Reporting.
EXror TYPES v v o o o

REPORTING

.
«

Format

wWwww

.
«

CLEANUP

Diagnostic

DATA

Header

Mnemonics LISt
PASSES

INITIALIZATION

AND SUBPASSES.

Device
- PROGRAM

the

GLOBAL

Program

Device-Dependent Fields.
from a Diagnostic Program

from Within
PROGRAM

Dispatch

P-Table Descriptors
P-Table Descriptors.
.

Diagnostic

[]
[]
[]
[]
[]
[
[]
[)
[

Attaching

[}

)
)
o
o
o
&
¢
|J
@

OCWOWWOWooowowowJIouTtutTuTuUTUTUTbd
WWLWWWwWwWwbdh DD

[4
[}
]
®
e

0
o
e
e

®
o
o
e

.,.....

Creating Names for
Referencing P-Tables
DIAGNOSTIC

FHRHHRRFRHRFRHERFRHRRHRRRFRRFRFOWOOOWOO

WWWWWWWWwWwWwWwwWwWwwwWwwwwwwwwww

Location
Creating

EVENTS

3-55
-

3-56

Event

Flags

Asynchronous

AST
AST

Delivery.
Routines.

Timing.

Timing
and

.
.

Standalone

Mode

Traps

(ASTS).

Available

Mode

Facilities

Only

Facilities

Timing

3.14,4.2

System

o«

User

Standalone

3.14.6

FILE MANAGEMENT
Introduction.

3.15
3.15.1

.
.

3-59

3-61

Available

3-65

.
.

3-66
3-66

3-68

XAB
. .
. .
RMS Control

.
.

3-68
3-69

VDS

3.15.3

3.15.4

The FAB, RAB, and
Accessing the VDS

3.15.5

Reading

. 3-70

3.15.6

Record

Processing

3.15.7

Block

Processing.

.
.

3-70
3-73

3.15.8

Mixing

3=73

the

‘Macro

Arguments

"Return

Status
USED

SERVICE

DEFINITION

o
o

w N

THIS

CHAPTER
.

MACROS.

DIAGNOSTIC
.

PROGRAM

.
PROCESS

Consultation Phase.
Planning Phase.
.
.
Design

Implementation

Design

Verification
STRUCTURE

Module

Modules.

Templates.

Header
Module

Phase.

Design

- Test
-

Specification

Phase.

Functional

PROGRAM

MACROS

DEVELOPMENT

CALLS

MACROS

VDS

OVEeLVIeW

MACRO

PROGRAM DOCUMENTATION

Phase

Phase
.

o
&
&
&
&
6
e

NS OoOYur ke Wi+

PROGRAM

MACROS

SYMBOL

'SYSTEM

CREATING

Codes

CONTROL

o
o
o
o

Processing

Macro

PROGRAM

STRUCTURE

Record

ot UTUTLTUTUT
U1 LTUT U1 U1
|
cooo~JuUuumuTwwTMNvddNDHEHFHFHH

4
o

SYSTEM

Fields

SERVICE

=V o
Y

INTRODUCTION.

CODING

PROGRAM

and

Structures.

MACROS

INTRODUCTION

Processing

Y
s

Block

CONVENTIONS

CHAPTER
5

U
UL LTy Ul g a

VDS

Files

NSOy Ok

Overview.

3-58
3-58

3.15.2

CHAPTER

RMS

.
.

3-58

.
.

Mode

Condition Handling.
Handling Control-Cs

3.14.5

3-56

Documentation

WN
®
.

5-8

5-12

Module

Cover

Page

5-12

Prefaces

and

Subtest

Source

Code

Files.

.
.

5-12
5-14

Comments.

5-16

Files

.
.

5-19
5-19

.«

Preface.
.

)

Description

w N

)

T
|

Creating
Contents

¢«

o«

Help Files .
.
of Help Files.

CONSIDERATIONS

(CRD)

5=20

.
.
.
.

5=23
5-24

.
«

5=25
5=25
5=25

.
«

Long Silences .
.
«
«
Hardware Preparation.

«
.

o
.

.
.

5=27
5-28
5-29

5=30

«
.

o«
.

.
.
.

¢«
.

.
.

5=31
5=-31

PROGRAM

.«

5=33

5=-34

Message

Formats

Intervention

Quick Mode.
.
«
Naming Symbols.
LINKING

Verification

Manual

«
.

DIAGNOSTIC

DEBUGGING

DIAGNOSTIC

.«

PROGRAM
«

5-34

Quality Requirements. .
Documentation Quality
Functional Quality.
.

.
.
.

5=-34
5-35
5=35

5=35

Assurance

5-490

QUALITY

ASSURANCE

Operational

.
.

DIAGNOSTICS

CONVENTIONS.

Error

Help

ENVIRONMENT

Volume

«5-9

Subroutine

bW N

CODING

.«

Names.

Code

.«

Module

Test
YU

DD
DD
o

[]

LYV AR VS B VS B US I VS I UV I O I

CUSTOMER-RUNNABLE

NSNS0

Source

N Oy U

PFROONSN
R
R

RUN-TIME

SESIESESESE
S

File.

Help

[]

N6 NN
R
N
°

R
.

RGN NGNS NEG RGN RGN RN
GRGEGESEG RGNS NGRS RGN

Introduction.
Documentation

Automated

.«

Quality

APPENDIX

TEMPLATE FOR THE VDS DIAGNOSTIC PROGRAM

APPENDIX

TEMPLATE FOR VDS DIAGNOSTIC PROGRAM TEST MODULES

APPENDIX

TEMPLATE

APPENDIX

SAMPLE

FOR

HELP

DIAGNOSTIC

PROGRAM

HEADER

DOCUMENTATION

MODULE

FILE

FIGURES
- Hardware

Environments

for

VAX

VDS OVerview.

.«

Layout

ProgramsS.

VDS

Memory

Sample Hardware

Configuration

P-Tables.

Layout.

.«

=«

P-Table

Diagnostic

and

Associlated

Legal

and

Examples
Proper

and

Nesting

$SQIO

Illegal
of

Loop

Usage

Improper

Loops

Function

Subtests

BoundarieS

Branching

Code

and

3-38

Loops.

3-39

Within

Modifier

I/0 Status Block Format
Typical $QIO Diagnostic

3-30

3-490

Fields.

3-45

&«
.

o
.

«
.

.
.

3-46
3-48

Routine.

.
«
«
¢«
+« &«
&«
Buffer Format

Argument

List

Passed

3-59

Argument

List

Passed

Condition

Handler

3-63

Array.

o«

3-63

Array

&«&«

&«

«
o

3-64

DescCriPtOr.

o«

J4=7

Format

Signal

Format

Mechanism

Quadword

String

Argument

List

SDS

BGNDATA

Format

AST

for

SDS _ENDDATA

¢«

o«

4-490

o«

4=-59

Format

.+«

o«

.4-114

Status Format .
.
.
.
e
SDS_CVTREG Value Mnemonics Table Usage.

o«
o

o
o

J4-135

Mode)

.4-177

.4-179

Sample

Parse

"Valtab"

Tree .

Table

Adapter

Device

Characteristics

Format

Terminal

Buffer

(Standalone

Characteristics.

<4-152

Program

Hardware

I/O

TABLES
Levels

and

Run-Time

Environments

Methods

and

Program

Device-Independent

Comparison

and

TYPES.

Read

VAX-11

Environment.

Hardcore

and

RMS

Write

and

VDS

.2-5

Requirements.

.2-6

o«

«2-9

Functions.

3-35

3-67

RMS

O ~JOU
b W+

wwwbw wwww

EXAMPLES
P-Table

Descriptor

P-Table

Skeletons

P-Table

Descriptor

for

RK611

RH78¢

for

Disk

Controller.

MASSBUS

RH780

3-16

3-17

Adapter.

3-18

«
«

3=-290

Adapter

MASSBUS

Referencing

P-Tables

MACRO-32.

Referencing

P-Tables

BLISS-32.

&«

@«

3=21

o«

3-33

3-34

RMS.

«v

o«

3=72

Sample

Error

MeSsSage€.

Sample

Error

MesSSage.

.«

Record

Processing with

vil'

1
CHAPTER
'WHAT IS A DIAGNOSTIC PROGRAM?

1.1

INTRODUCTION

This

chapter

design.

presents

discusses

the

testing

goals

the

various

methods

those

any

the

and

diagnostic

used

characteristics

regardless

introduction

uses

that

program

test

are

they

This

all

DIAGNOSTIC

diagnostic

discover
There are
l.

program

During

This
A

any

execution

or
v

specifically

During

when

or incorrect

the

possibility

program

set

was

of
of

malfunctioning
programs

hardware

system

will

hardware.

malfunctlon

executed

and,

failed.

manufacturlng.

hardware
Dbefore

modules

device
1t

are

put

the

device

put

together
in

put

programs,

events

built,

shipped

it
a

shipped

together

processors

together

itself

create

a customer.

until

the

device

entire

systems are

times,

tested
systems

individual
parts (previously

peripherals)

arrive

testing

whole

plant and

Other

thoroughly
This

First,
1logic
modules
separately.
Then, the

Sometimes

the manufacturing

and

tested.

must

customer.

generally is performed "bottom-up."
making
wup
the
device
are tested

being

systems

unexpected

results.

indicates

tested

in
|

designed

applications
or

produces

diagnostic

After

programs,

execute

program

to determine 1f there
so, which part of the

PROGRAMS

system

computation

diagnostic

and
identify
hardware
failures
in a computer system.
three main cases
in which diagnostic programs are used.

the

program

programs,

should
meet,
and
chapter discusses

designed

USES

diagnostic

design

are

test.

1.2

hardware.

common

hardware

users

the

customer

and

before
are

not

tested
site.

WHAT
IS

During

the

functionality of

the

and

design

DIAGNOSTIC

diagnostic

new

PROGRAM?

product.

product

program

for

accurately

the product

defined,

is correctly

it
executed
written, then when the diagnostic program is
hardware malfunctions)
no
has
product
the
(if
should
If
correctly.
functioning
indicate that the product is
been
have
errors
that
indicates
program
diagnostic
the
product
faulty
a
of
be the result
detected, they could
design

l.3

DIAGNOSTIC

Because

that needs

PROGRAM

diagnostic

corrected.

USERS

programs

are

put

wvarious

uses,

the

users

When a diagnostic

of these programs are also varied.

(operators)

customer
a
at
system
is used to identify problems in a
program
site,
the program may be run by a customer service representative
~or by the customer.
Diagnostic programs used
to
verify
devices
or
systems
might
be

proper
run
by

functioning
technicians

of
at

new
the

manufacturing site.
They
might be
1loaded
and
run
wusing
an
automated
method
requiring
no operator.
Also, customer service
representatives must verify proper
the

systems

arrive

A diagnostic
be

run

by a

customer

program used

hardware

functioning

of new systems when

site.

for design verification

design

would

engineer.

probably

Because of the variety
of
should
developer
program

wusers
for
diagnostic
programs,
the
who the users of his or her
aware
be
specific
a
for
intended
Some programs may be
program will be.
needs,
its
to
tailored
be
can
program
the
and
audience,
for a
intended
be
will
Other programs
background, and experience.
of
all
to
useful
be
to
and must be written
users
of
range
wide
them.

l.4

USER

REQUIREMENTS

All diagnostic program
meet.
must
programs
than

All

one

user,

some

are

users have specific requirements
that
the
are common to more
While some requirements
not.

users have in common the need

for

good

fault

detection,

find as many failures as possible).
to
ability
(the
"coverage"
being
device
the
on
exists
error
an
if
Every user expects that
tested,

then some diagnostic program will detect that error.

Customers, or
diagnostic

"end

programs.

users,"

have

main

three
|

requirements

for

WHAT

Ease

The

IS A

DIAGNOSTIC

use.

functions

diagnostic

relate
to
1internal
have the training to

place

1in

the

CSR

programs

are

technical

and

system hardware.
An end user may not
understand what operations are taking

diagnostic

interface must be
setting
switches
such

PROGRAM?

program.

Therefore,

the

human

simple.
For example, installing cables,
on logic boards, requesting information

addresses

device

priority

1levels

are

all

inappropriate.
Preservation

Since

media

device

diagnostic
destruction
by

only

Some

may

provide

contain

data

needed

the

user,

media

specific

designated

sectors

for

that

diagnostic

are

used

use.

only

for

purposes.

Nonexclusion

users.

large

system

timeshared

while

many

customer

users.

diagnostic

programs

site

the
are

will

users

usually

cannot

running,

use

the

significant

system

data.

programs
must
provide
safegquards
against
of this data.
This is generally
accomplished

writing

disks

diagnostic

user

loss

programs

and

not

the

<customer

can

occur.

should

operate

under

the

preempt

other

system

Customer service representatives'
program

Therefore,

user's

diagnostic

operating

system

users.

have

the

following

diagnostic

requirements.

Quick
The

fault detection.

faster

site,

customer

fixes

customer.
faults as

the

service

problem,

representative

and

Diagnostic programs
quickly as possible.

Identification

bad

leaves,

should

field-replacable

arrives

the

happier

able

the

find

units.

The diagnostic program should be able to tell the customer
service
Section

representative
which
should be replaced.

1.6)

FRU

(see

definition

1in

WHAT IS

Good

program

DIAGNOSTIC

PROGRAM?

documentation.

To identify a failure,
it
1is
often
necessary for
the
customer
service
representative
to
understand
what
functions
a diagnostic program is performing.
— Therefore,

the

Manufacturing
manufacturing
In

the

descriptions of

with detailed

documented

well

should

©program

functional

each

test.

—

requirements
depend
on
which
phase
process a diagnostic program is used in.

module

test

phase,

quick

error

detection

the

wvalued,

particularly
in
high volume settings.
Good error identification
is sometimes NOT necessary, because modules
are
sent to
module
repair
stations
that wuse their own special-purpose hardware and

software to identify module failures.
In
other cases,
module
and good error identification IS
wused
not
are
stations
repair
important.

During

device

testing,

manufacturing

technicians

requirements as customer service representatives.
will
process
manufacturing
the
so
is needed
Identification

of an

easily

replaced

have

the

same

part of

the

Quick detection
be slowed.
not

constituent

the
and
hardware system is necessary so the part can be replaced
shipped while the bad part is repaired, instead of holding
device
up shipment
of
the
device.
because
determining
the
bad
understanding of the diagnostic
The main

good

requirement of design

fault detection.

Since

Good
documentation 1s necessary
part sometimes requires a thorough
program's functionality.

engineers

that

the

the engineer
is using

program

give

the diagnostic

program to check out his or her design, any section of

the

logic

that
the
program
does not test could contain a design flaw that
may not be caught until
after
the hardware is 1in
production,
necessitating

engineering

change

order

(ECO).

It is important to note that user
requirements
often
product
to
product.
A
particular
user's specific

vary
from
needs often

depend on the type of product for which the diagnostic program
1s
being
designed,
or
the
program's
use.
For
example, program
requirements specified by manufacturing personnel will
depend
on
the

manufacturing

site's

testing

stategy for

the product.

This

strategy is often not the same from one product to the next.
The
with the
communication
close
maintain
must
developer
program
program's eventual users in order to tailor
the
program
to
the
requirements of

those

users.

WHAT

1.5

RUN-TIME

The variety

variety
must

DIAGNOSTIC

PROGRAM?

ENVIRONMENTS

uses

and users

"run-time

able

control-level

diagnostic

environments"

execute.

software,

any,

programs

"run-time

under

creates

which diagnostic
environment"TM

which

the

programs
1is

diagnostic

the

program

must

run.
Some
diliagnostic
programs
cannot
function
1in
all
run—-time
environments.
The environments a program is designed to

run

are

determined

In the "user mode"
system

the

purpose

the

system

users on the system at the time a
the
diagnostic
program
1is just

(The

program

operating

exceeding

its

medium

must

program

can

should

system

~the
to

with

any

the

write

serve.

timesharing

tested.

prohibit

Often,

There

operating

could

be many

diagnostic program is
run,
another user of the system.

affect

diagnostic

replaced
use

not

will

bounds.)

exclusively

program

run-time environment, a

executing

diagnostic

the

other

the

device

program,

tested

and

"scratch"
test

user

diagnostic

the

system.

program from
1is

assigned

device's

medium

patterns.

the

Some

and
The

storage

diagnostic

storage

devices

provide an area for the exclusive use of diagnostic programs, such
as the "maintenance cylinders" on some disk media.
In such cases,
the diagostic program uses this reserved area and other
users
of
the device are unaffected.
|
The

opposite

"standalone

the

mode"

wuser

mode

environment.

run-time

environment

standalone

mode,

the

1is

the

diagnostic

program has exclusive use of the computer
system.
There
1is
no
high-level
operating
system
to
allow other users to run at the
same time or to
place
execution
boundaries
on
the
diagnostic

program.
execution
Sometimes

program

Thus
modes
1n

the
and

diagnostic
©program
can
use
reserved
registers

standalone

provides

diagnostic
program.
execution constraints
The

advantage

execution

resolution

computer's
customer
these

The

standalone

boundaries

error
and

system

used

description

user

any

type

however,

mode

over

under

network

networks

programs,

increasing

contended

with.

user

sometimes

money.

are

system

monitor

other

and controls

identification.

programs

computer

in privileged
memory
space.
type

must

This
on

new

and
test

The
be

used

for

modes

connected

system

that

are

wused

the

number

that

down,

does

the

not

run-time

has
to

the

1lack

1level

and

exist

the
the
when

site.

that

the

system

via

There
run

that

costing

implied
another

the
place
|

manufacturing

diagnosis.
1load

control

not

qgreater

brought

systems
at

not

will

disadvantage

standalone
1s

mode

offers

execution

However, this type of monitor
on the diagnostic program.

operating

time

mode

services

run
and

are,

diagnostic

environments

WHAT

DIAGNOSTIC

PROGRAM?

Networks are commonly used at manufacturing
sites,
where
it
1is
necessary to test a large number of systems at once.
Typically, a
host processor will maintain up-to-date copies of
all
diagnostic

programs.

The

system

to be

tested will

and the host will transmit the
system.
The
©programs
will
processor, but the
host
will
programs

and

note

Networks

can

also

any

errors

used

this case,

"call"

customer's

diagnostic
customer

that

programs

the host,

occur.

diagnose

systems

centrally located host

service

be connected

appropriate programs
to
the
test
be
executed
in
the test system's
monitor
the
performance
of
the

system.

executed

‘The

representatives

the

with

system

host

use

<can

system

the

customer

can

then

tested

results

sites.

phone
and

lines

monitor

provide

the

tests.

This
can
greatly
decrease
the
amount of time customer service
personnel must spend at the customer's site.
Since they will
not
go
to
the customer site until after the tests are executed, they
will have a good idea of what the problem is before they arrive.

The

DEFINITIONS

following

are

System

some

under

commonly

test

(SUT)

diagnostic

program

1is

Unit under

test

SUT) .

The

host

the

hardware

system

which

(part

- The device
by

the

particular

SUT,

such as

one

tested

diagnostic

device
of

the

type

the

program,

remote

and

entire

nodes

that

must

system.

Hardcore - The

operate

Programs

hardcore

- The

defined

can be one drive of a
subsystem

terms.

executed.

(UUT)

UUT

used

portion of

properly
that

test

for

load

include

any

easily

(for

example,

devices

A program's
of

Field-replacable unit
be

hardware

typically

execute.
have

of the processor, main memory,

device.

portion

can

SUT's

peripheral

consisting

program

the

the diagnostic program

and
logic

the

hardcore

should

and a
never

UUT.

(FRU)

- Any portion of the UUT

quickly
board).

replaced

at a customer's

that
site

1.6

WHAT

l.7

TESTING

DIAGNOSTIC

PROGRAM?

GOALS

All diagnostic programs have the same testing goals,
what

they

test

are.

The

first

"testing

the

program

the

unit

what

goal

Clearly

The

can

and

tests.

under

support

define

scope"

their

test.

testing

portion

should

never

For

drives.

should

limited

those

areas

meant

(The

fewer

stray

program.

easier

will

The

hardcore

possible.

functioning

order

get

likely

and

other

which

the

from

that

the

writing

have

option

having

memory

program is running.
Having
hardcore for the diagnostic
to

test

next goal

the

disk

of a

The

must

any

part

pass

this

are

errors

diagnostic

program

scope.

the

small

some

through

hardcore,

the

made

without

outside

the scope
example,
a

For

program

management

requires

for

off

disk

might

while

memory management on will increase
program, and the program will
not

there

should

system,

should

smaller

diagnostic

the

diagnostic

the

device

the

memory

the

the
be

management

Detect any and all failures that could
“testing

the

test

logic.

The

that

unless

logic

program

signals

the

are

peripheral

UUT.

designer

able

program

tested

which

controller

failure.)

any

logic

drives,

a diagnosis
of
the
UUT
can
errors within the the system but
could invalidate the
diagnosis.

users

the boundaries

disk

there

diagnostic

almost

logic

the

generated

program

the

main

hardcore.

hardware

beyond

that

finding
test,

Testing

signals

identify

Correctly

required

diagnostic

faults

Signals

the

consider

detect

required

and

extend

example,

controller
cannot
be

not
avoided.

scope

that

several

regardless of

environments

to
the

execution

occur

within

the

malfunction,

the

|
wunit

wunder

test

could

diagnostic program should be able to detect that malfunction.
The
diagnostic program does NOT need to
be
concerned
with
problems
outside
the
scope
of
the
wunit
it
1is
intended to test.
For
example,
to

detect

diagnostic
CPU

inadvertently).

test

problems

disk

driver

(although

should
it

not

might

be expected
detect

them

WHAT

This goal

DIAGNOSTIC

simple

is clear-cut and

PROGRAM?

1if

occurs

malfunction

anywhere within the unit under test, the diagnostic program should
test
Thus a diagnostic program designed to
detect and report it.
should
drives
attached
their
and
rs
controlle
drive
tape
set of
a
be able to detect any failure occurring in either the
A system exerciser
drives.
associated
their
or

controllers
(designed to

the overall functionality of a computer system, including
validate

all peripheral devices) should be able to
and
memory,
CPU,
the
detect errors on any device attached to the system.

Once a failure has been detected, the diagnostic progam must
|

Attempt to identify which part of

under

test

has occurred.

The

the

unit

the malfunction.

caused

It is not enough to recognize that an

error

diagnostic program should also be able to indicate which part (or
|
parts) need(s) to be repaired or replaced.
it
for
one,
the 1last
as
This third goal is not as <clear-cut
to
g
attemptin
When
."
resolution
of
"degree
of
concept
the
involves
program designer must
the diagnostic
identify a failing part,
is that should be
system
the
within
part
smallest
the
decide ~what
devices,
hardware
of
up
made
is
system
computer
Each
considered.

which contain one or several logic boards, which in turn are made
of resolution is a
A diagnostic program's degree
up of IC chips.
smallest possible
the
identify
to
ability
its
of
relative measure
failing constituent part.

For example, consider a tape

subsystem

consisting of several tape drives connected to one controller. A
1logic Dboard
diagnostic program that could identify the failing
have a higher degree of
tape drive would
failing
the
within
drive.
failing
the
identified
only
that
one
than
n
resolutio
to the
refer
to
used
often
phrase
another
is
isolation"
("Fault
error

degree of

‘

resolution.)

A particular program's proper degree of resolution depends on

its

it would be impractical for a
For example,
function.
intended
system exerciser (described in Section 1.8) to attempt to identify
More likely, it would
failures to the degree of the failing chip.
1if the
ioning and,
malfunct
was
device
al
peripher
determine which
r,
controlle
one
to
attached
drives
several
of
consisted
l
periphera

On the other hand, a diagnostic program

which drive was in error.

designed to test a specific ©peripheral device probably should
attempt to identify the failing logic board within that device.

A diagnostic program's degree of resolution can also be affected
It is not always practical to
by the program's user requirements.

resolution,

because

run-time, and may require a more highly skilled operator.

In some

the

achieve

increasing

cases

highest

resolution

may

possible

<can

degree

also cause increased program size and

important to keep these variables within

bounds than to attain a high degree of resolution.
1-8

WHAT

DIAGNOSTIC

Unfortunately, achieving a high
sometimes
more
an
1ideal than
programs

used

customer

PROGRAM?

degree
of
error
resolution
is
an
attainable goal.
Diagnostic

service

representatives

should

be
able to identify the smallest malfunctioning
program to identify an error as existing on
one
two
to

requirements
execute

Second,

the

logic

resides

through

proper

the

proper

logic
by

when

Both

design

new

sometimes

not

1identify

a particular

determine

able

device.

diagnostic

along

with

achieve

for

the

locate
the failure
of

detected,

quickly

program
and

whose

transitions

small

can

easily

are

Thus

cannot

taking
have

ALL

Thls

goal

both

1.8

LOGIC
all

technician

will

have

electrical

signals

responsibility
technician with

of
the
aids to

These
invoked

aids
if

mainly

an error

provide

repetitive

the

hardware

logic

these

desired

transitions

final design goal for
all faults automatically

can

state

programs).

quickly

The

and

state

that

make

the

sure

diagnostic
programs
(at the present time,

goal

relevant

are

discussed

next.

FUNCTION

TESTS,

easily

that
this

detected

all

possible

observing

transitions.

which

programs

dlagnostic

tests,"

signals

place properly.

dlagnostlc

general,

all

program

To provide enough useful program'loops that
logic

"logic

subsets

diagnostic

errors

Not

one

1solate

includes

can

observe

The
the

designer

to guarantee

resolution

examining

accurately.

that

©purpose

techinician
they

and

1loops

communication

diagnostic

cases

FRU

met

resolution.

degree
of

these

component

FRU.

program

development,

error

used

which

only

wvisibility

high

1In

logic

single

can

the
is

determine

the

on logic boards with an oscilloscope.
diagnostic
program then is to provide
consist

failure

failing

hardware

and

product

situation.

the

reside

requirements

possible

all

must

these

designer

program

First,

failed

program

partitioning

the

accurately

met.

that

hardware

essential

1is

on.

hardware

needed

diagnostic

between
are

must

function

ideally

FRU.
But for the
particular
FRU,

logic

have

programs

"function

tests,"

tests

than

functlon

tests,

AND
the

can

and

EXERCISERS
same
be

functional

divided

into

"exercisers."

goals.
three

groups:

WHAT

A logic

DIAGNOSTIC

during

wused

test is usually

PROGRAM?

the
tests
A logic test
device.
(verifies that a specific section of

the

repair

faililing

device's combinational logic
the
within
1logic
hardware

A logic test should provide the
device is functioning correctly).
tests.
of
greatest degree of error resolution of the three types
to run in a standalone environment.
Logic tests are designed
A function

test verifies

the

functionality

device.

For

a function test for a disk drive would be used to verify
example,
and
reading
such as
that the "functions" provided by the disk,

writing

are operating properly.

data,

blocks

Function tests

the
detect
to
or
devices
may be used in the repair of failing
error
of
have as great a degree
not
may
tests
These
failure.
run
Function tests can be designed to
resolution as logic tests.
in

either

standalone

For many products,

developed.

failure and

The

the

both a

function

logic

user mode

logic

test

environment.

test

1is

repair

test to

and

used

the

function

test

are

part.

For

some

to detect the hardware

failing

Some products
1is used for repair.
test
function
the
products,
short,
In
1l.11).
have logic tests in microprograms (see Section
product.
to
product
from
vary
developed
programs
of
types
the
Program users will

particular

specify the

types of programs they desire

for

product.

purpose
Its
A third type of diagnostic program is an exerciser.
over a
sustalined
be
can
y
functionalit
is to verify that a system's

Exercisers are more likely to be designed for use
period of time.
an
Typically,
single device.
on a
than
systems
entire
on
testing
exerciser will simultaneously perform repeated functional

to detect (1)
every device composing the system, in an attempt

failures that

devices,
1.9

(2)

SERIAL AND

result

from

this

simultaneous

failures that only occur

rarely.

wuse

numerous

PARALLEL TESTING

Many diagnostic programs are designed
to
test
all
specific type of device existing on a given system.

units
of
a
There are two

be
can
units
multiple
of
testing
this
which
by
methods
Serial
testing."
"parallel
and
testing"TM
"serial
accomplished,
testing involves testing each unit of the device individually, one
Parallel testing is the testing of all units at once.
a time.
at
where
test,
Serial testing is more likely to be found in a logic
to a
activity
system
of
1is desirable to keep the overall level
it

Parallel testing, on the other hand, may be included
minimum.
function tests to achieve higher levels of system activity.

WHAT

1.1

Two

BOTTOM-UP

testing

are

AND

DIAGNOSTIC

TOP-DOWN

techniques

dJenerally

the

wused

are
1in

TESTING

used

test

combination

hardware

produce

systems.
thorough

They
test

SUT.

"Bottom-up

testing"
the UUT

considering
layer
layers
layers

from
the

involves
to

testing

made

device
or
of layers.

set

system

by
lowest

The

is the simplest and most
elementary.
Successively
higher
depend on proper functioning of the layers underneath.
All
taken

together

lowest

make

highest.

the

Once

entire

layer

UUT.

Layers

tested

are

tested

considered

hardcore

for the next layer.
This testing technique is
"guilty
wuntil
proven
innocent"
assumption.
That

section

of hardware is
("innocent" of causing

not
assumed
errors) until

Bottom-up

important

must

testing

tested

logic

must

pass

have

itself

looike
or

PROGRAM?

being

order

examined,

been

bottom-up

all

before

tested

another

the

that

properly.

technique
approach

the

electrical

logic

being

section

depends
on

Function

the
logic
section of

that

Each

hardware

entire

system

"Top-down

testing"TM

consists

then

the

gradually

failing

provides

signals

tested

tests

also

should

1logic

the previous

part

can

is
sections

make

use

"innocent

until

everything

operating

properly

this

approach

thorough,

can

the

take

systematic,

However,

long

using

looking

the

UUT

its

component

into

this

time.

UUT

parts

identified.

with

testing.

first

subdividing

assumption
problem

1logic

reaching

layer

validate

until

in logic tests, where
that whenever a certain

previously.

whole,

such

be
functioning
properly
integrity is verified.
|

testing.

step-by-step

method

operating

bottom-up

The

through

upon

layers

to
its

based
is, a

proven

This technique uses
an
(The program assumes
errors are detected.)
The

guilty."

unless

1is

that
a
fault might exist in a
portion
of
the
hardware
outside
the
testing
scope
of
the
diagnostic program.
In this case the diagnostic program might not
detect or might incorrectly diagnose the error, or
might
not
be
able to execute at all.

practice,

containing
techniques.
manner.

diagnosis

faults
Often,

Programs

of
a
hardware
system
suspected
of
uses
a
combination of top-down and bottom-up
bottom-up programs will be run in
a
top-down

written

order such that those
executed first, followed by
executed

programs

point

use

the bottom-up

technique

are

run

that test the largest
subsystems
are
those that test devices tht previously
as

gquestionable.

WHAT IS A DIAGNOSTIC PROGRAM?
1.11

MACROPROGRAMS AND MICROPROGRAMS

“Many computer processors built today have two
make
"Macro-instructions"
instructions.
These instructions are the
machine language.
so
and
operators,
boolean
and
arithmetic

types of
the
up
"moves,"
on, that

programming
processor's
"branches,"
are used to

use
that
Programs
manipulate data in specific memory locations.
assembly
an
of
use
the
through
directly
these instructions, either

language compiled
high-level
a
language or indirectly by using
ms." By far
"macroprogra
called
are
language,
an assembly
to
down
most programs written are macroprograms.
o

of
set
Beneath the macro-instructions is a
processor's
the
implement
to
=
used
Micro-instructions define the macro-level

the

machine

"micro-instructionsTM
language.
machine
plus

instructions,

the

language as existing "in the

registers

defined

counter).

Micro-instructions do not execute in the system's main

processor"

(such

general

purpose

registers

program

Instead, they are loaded into and executed in a "writable
memory.
also often exist in
(Micro-instructions
(WCS) .
store"
control
than
rapidly
more
execute
ions
micro-instruct
Since
ROMs.)
or
applications
for
useful
sometimes
is
it
macro-instructions,
systems programmers
"microprograms."

to use the

micro-instruction

set

create

of
use
make
sometimes
programs
diagnostic
Developers of
will
processor
the
test
to
designed
Programs
microprogramming.
Some
a WCS.
most likely use micro-instructions, executing them in
These
sors.
microproces
own
their
possess
devices
peripheral
have
routines
devices usually also have ROMs in which diagnostic
a
writes
programmer
diagnostic
the
case
this
In
stored.
been
residing
s
microprogram
the
activates
that
procgram
tic
macrodiagnos
in

the

ROM.

Parts of Chapter 2

However,

most of

discusses

this manual

-diagnostic

microprograms

further.

concerns diagnostic macroprograms.

CHAPTER 2

VAX DIAGNOSTIC PROGRAMS

2.1 INTRODUCTION
The

discussion

programs.

systems.

This

programs

that

Chapter

did

chapter

are

not

consisted

deal

introduces

unique

with

an overview

specific

types

characteristics

diagnostic
of

VAX.

computer

diagnostic

2.2 RUN-TIME ENVIRONMENTS FOR VAX DIAGNOSTIC PROGRAMS
VAX

diagnostic

run—-time
and

programs

environments.

network

execution

environments.

system.

For

VAX/VMS,

programs

are

programs

are

VAX

can

The

all

mode

used

include
user

diagnostic

almost

user

expected

These

diagnostic

executed

mode

the

supported

program

operate

mode,

must

customer

without

mode,

supports

operating

DIGITAL

under

developed.

These

bringing

several

that

VAX/VMS
by

sites

1in

standalone

environment

programs

devices

extensively

user

that

down

diagnostic

VMS

and

thus

locking

other

Many

programs are designed to execute in standalone
Manufacturing
sites
commonly
use
standalone
programs,
1if user mode programs were used it would be
necessary
to

users

out

the

system

under

test.

VAX diagnostic

mode.
because

boot
VMS
just
to run
programs often provide
programs,

programs

they

customer

have

almost

always

Networking
cuting

diagnostic

service

customer

been

the

better

personnel

sites.”

identified

involves

error

the

Repair

sometimes

and

removed

use

environments
have

been

programs.

Since
than

detection

must

failing

from

standalone

developed

use

device

the

standalone
user
mode
standalone

parts

system

diagnostic

for

(after

under

test)

programs.

and

diagnostic

exe-

programs on VAX computer systems.
One example
is the Automated Product Test (APT) run-time environment, commonly
used
at
manufacturing
sites.
Under this environment, a system
under

test

connected
to

"mother"

all
diagnostic
programs
wused.
For
"script" is built.
A script is a file

~nostic
~must

programs

passed

to
to

be
the

run,

this
script and sends
a time, to the
system

"down-line

loading.")

under

test,

which
Pleted

the
run.

along

with

diagnostic

Once

program

and

any

and

Programs

standalone

started,

until

executing

mode.

all

The

has

monitnred

the

has

run-time

copies

been
by

parameters

mother

diagnostic
(This 1is

will
note
any errors detected.
execution
the
, next one listed in

1line

that

programs,
referred

sent

mother

When

one

program

the

script

test

can

reads

one
to

the

under

that

system

at
as

system

- system,

has

comdown

sent

progr
in the
ams
script

system

each system
to be tested, a
containing a list of
diag-

program.

the appropriate
under
test.

started

system

have

only

been

run

Another example of
Diagnosis),
which

DIAGNOSTIC

diagnostic
provides
a

PROGRAMS

network
method

is
APT/RD
(for
Remote
of loading and monitoring

diagnostic programs for diagnosing a system at
APT/RD,

With

established

temporary communications link

between

system

belonging

system

located

the

DIGITAL

customer

tested

and

running

and

site.

(via phone lines)
a

1is

centrally

APT/RD

the

can
system
central
Once the 1link is established, the
software.
attempt to
to
programs
of diagnostic
script
a
through
step
diagnose the customer's system.
Unlike the APT
system
used
at

the APT/RD system usually does not
though,
sites,
manufacturing
the
Instead,
programs.
diagnostic
of
loading
down-line
perform
customer's
the
of
medium
storage
some
on
exist
programs must
system.
They are loaded "locally" from that
medium,
on
command
from
the central
system.
(Programs can be loaded down-line if
necessary, for example when the
diagnostic
1load
medium
of
the
system

under

2.2.1

The VAX Diagnbstic Supervisor

The

test

is malfunctioning.)

the

detailed

chapter

and

uses

wvarious

users

The above section describes the
diagnostic program may encounter.
If a
run-time environments supported for VAX diagnostic programs.
diagnostic

program

designer

had

include proper

interfaces

for

developed,
she
or
all users and environments in each program he
reason the "VAX
this
For
burdensome.
become
would
task
the
macroprograms
Diagnostic Supervisor" was developed for diagnostic
designed to run on VAX systems.
The VAX Diagnostic Supervisor, or
provide
and
execute,
1load,
VDS, is a control program that will
The

VDS

is divided

interface

"human
the

services

run—time

between

interface."

diagnostic

into

programs.

two major sections.

the VDS and

The other

program

and

One

the program user

is an
is

section

and

interface between

referred

is called

the

and

the

VDS

the

"program

interface."

The human interface consists of a command
that
receives
and
processes
commands

interpreter
(CLI)
on a terminal by a
Commands supported by the CLI include those for loading and
user.
running diagnostic programs, selecting which device units to test,
displaying execution summaries, and controlling program looping.
The

program

interface consists of a

set of

line
typed

service

routines

for

service calls from the diagnostic program to the VDS, along with
a

mechanism

for

routines

dispatching

the

VDS.

calls

from

These

the

service

program

routines

the

proper

provide

the

diagnostic program with convenient methods for
performing
device
I/0, formatting error messages, controlling program loops, storing
and retrieving system-specific device
parameters,
prompting
the
user
for
additional
run-time
parameters,
and
providing
file
management facilities.

VAX

The

specific

purposes

Provide

DIAGNOSTIC

the

VDS

common

programs.

PROGRAMS

are

human

With

the

programs

interface

1large

for

all

diagnostic

VAX

diagnostic

number

in existence, it is important that users
not
be
required
to spend time learning how to use each one.
The
VDS provides the user with a standard set of
commands
‘and
functions
that
can
be
performed
for
all
diagnostic

programs.

Insulate
the
environment.

diagnostic

The

be needed between
environment,
be
APT/RD,

Insulate

operations

be
4.

that

wused.

the

are

Thus
with

unique

the
diagnostic

the

knowing

the

type

processor-specific
I/0
of

program

type

run—-time

that may
and the
run-time
(user mode), APT,

the diagnostic program
that
environment
VMS

standalone.

concerned

Make

from
the
communication

the diagnostic
program
from
differences.
The VDS performs

hardware
being

program
performs any

VDS

VAX

initialization

VAX
processor
does not need to

processor.

programmer's

job
easier.
Providing
facilities
formatting
error
messages,
controlling
program
looping, initiating I/0 activity, manipulating files,
and
other
services
not
only
guarantees
consistency
among
diagnostic programs from the user's
standpoint
but
also

for

greatly
produce
Later

1s
in
The

chapters

reduces

new

the
program.

this

manual

VDS

used

for

VAX

section.

discuss

1introduced at this point in
the VAX diagnostic strategy,

written

2.3

development

INTRODUCTION
order

ensure

most,

but

systems,

TO
a

THE

all,

will

necessary

detail.

manual because
discussed next.

VAX DIAGNOSTIC

careful,

VDS

the

not

the

effort

diagnostic

shown

The

plays

VDS

role

macroprograms

the

following

STRATEGY

comprehensive, step-by-step approach
a strategy for diagnosis of VAX systems
Strategy, generally referred
to
simply
as
the
"VAX diagnostic strategy," has been to create
a hierarchy
of diagnostic programs based on hardcore
requirements.
Programs
higher
1in
the hierarchy require greater hardcore (they
require a
larger portion of the whole system to be
operating).

to
has

diagnosing
problems,
been developed.
This

PROGRAMS

Programs higher in the hierarchy are

likely

©provide

//n:mw\\

VAX DIAGNOSTIC

versatile human interface and are less likely to require exclusive

use of the system under test. On the other hand, programs lower
thus
in the hierarchy can test a device more thoroughly and when
Dbest,
1is
it
Hence
provide a more accurate diagnosis.

diagnosing a customer's system, to begin by using diagnostic
down the
programs of as higha level as possible and then drop
that can detect
hierarchy
the

fault.

necessary

until a program is found

The diagnostic strategy has been implemented by
types, or "levels," of diagnostic programs.
1.

Making use of the fact that the VAX hardware can be
divided into various building blocks that, when connected
These building blocks
together, create a whole system.
consist

2.
3.

defined by:

creating various
These levels were

console

A system

A CPU "cluster" consisting of processor,

Peripheral

I/0 channels

memory,

and

devices

Remembering that some fault diagnosis can take place while

a system's operating system is running.

Using the VAX diagnostic supervisor when appropriate.

By using these considerations, a set of five

program

levels

has

The diagnostic programs belonging to each level
been defined.
ms
possess characteristics that differentiate them from progra
related
are
stics
cteri
chara
These
belonging to the other levels.
to the program's run-time environment, hardware environment (see

below), and method of performing I/0 operations (see below) .

Table 2-1 introduces each program level by listing its level

and the run—-time environment associated with it.

name

VAX DIAGNOSTIC

Table

2-1

Program

Levels

PROGRAMS

and

Run-Time

Environments

Level

Run-Time

l’

'Runs under VMS bperating system.

Runs

Environment

under

VDS

(Before 1982 only.

are

written

for

standalone

mode only.

No new programs

this level.)

Runs under VDS

user

in both

user

modes.

and

Runs under VDS in standalone mode

only.

Runs

"Runs

program's

"hardware

configuration
this with the
hardware

that

environment

CPU

cluster,

controller

case

would

the

different

diagnostic
building
l.

CPU

cluster

hardware

listed

hardware

above.

These

load

environment.

can

Consists

main

only

Consists of
memory,

Consists

and

all

attached

the

whole

system.

illustrates

the

hardware

configuration.

defined

environments

and

this

environments

the

the
|

system

console

console,

channels.

system

console,

peripherals.

environments

VAX

are

the

I/0

for

relate

device.

environment.

and
this

the buses.)

environments

processor,

cluster,

words,

2-1

and

The

environment.

System

hardware

functioning
©properly
1in
order for the
execute.
For
example,
the
‘hardware
program to test a disk controller would be the

console

CPU

hardware

not confuse
amount
of

connecting the controller to the
cluster,
itself,
while
the hardcore requirements in

CPU cluster

not

the minimum

Console

VAX

console,

the program will execute.
(Do
hardcore, which is the minimum

and

the

VDS,

programs.

blocks

the

Figure

buses

the

Three

must

program

without

or system
memory.

environment"

on which
program's

diagnostic

standalone

in WCS
VAX main

in
A

for

the

In other

typical

VAX

VAX DIAGNOSTIC

PROGRAMS

SYSTEM ENVIRONMENT

CPU CLUSTER ENVIRONMENT
CONSOLE ENVIRONMENT
0L
AN
TRRN
RO
MR
AR - oo— (U

7~
3

yRR
l|ll||l|lll|l|HIIIIII\IIIII"II

sees

[]

CONSOLE STORAGE DEVICE

TK-10615

Figure 2-1 Hardware Environments for VAX Diagnostic Programs

The hardcore requirements and the hardware environments of the
levels vary, with both increasing as the hierarchical 1level
increases. Thus level 1 programs have the greatest hardcore

requirements

and

1largest

hardware

programs have the least and smallest.

environments,

while level 5

The hardware environment and hardcore requirements of each program
level are listed

Hardware Environments and Hardcore Requirements

Hardware Environment

System

Enough of system for VMS

to execute, plus UUT

Hardcore Requirements

Level

Enough of system for

VMS

execute

Enough of system for
VMS to execute

Same as 2R in user mode.
Same as 3 in standalone mode.

"CPU cluster, UUT, load device

CPU cluster, load device

CPU cluster

Console, subset of

Console, CPU cluster

CPU

cluster

Subset of console
‘:/

Table 2-2

in Table 2-2.

VAX

2.4

METHODS

DIAGNOSTIC

PERFORMING

I/O

Perhaps

the most

significant

levels

method

the

of
determined

I1/0 methods

are
diagnostic

for

VAX

put

restrictions

Before

each

operations

that

are

Logical

)

blocks

‘/

the

its

v'(

storage

any
that

various

program

The

environments
environments

performing

various

existing

generally

I/O

define

operations
three
types

the

run-time

environments.

medium,

such

sectors

block
structuring
or
file
may have been created for
the
:

For

1logical

device

used by
of
1I/0

may

I/O

operations,

referenced

can
the

disk,

structuring
device
by

disk-type

addressing

"logical"

on the device (blocks defined by software, such
512-byte
blocks
defined
by
VMS).
Blocks

referenced

of
necessary

provided

I/O

Storage

the

operations.

I/0 - In physical I/0 operations, references
to the actual physically addressable units of

ignoring
algorithms
software.
¢

among

I/0

operations.

methods

1is

Physical
be
made

device

I/0

the

difference

performing

by the run-time
programs, since run-time

discussing

level,

PROGRAMS

relative

medium,

and

block.

File

are

numbered

structuring

Virtual
I1/0
software-defined

the

beginning

from

@ to
algorithms

With
blocks

beginning

n,
are

the

where

as
are

storage

the

last

ignored.

virtual

I/0
operations,
referenced
relative to the

are

of a file.
They are numbered from 1 to n, where
the
1last block in the file being referenced.
This
of I/0 takes
full
advantage
of
software-defined
blocking and file structuring on the storage medium.

n
1is
method

detailed

VAX/VMS

I/0

development
In

level

requests

service

level

the

call,

transfers

the

programs

sometimes

wilthout

I/0

types

guide

program

operating

using

the

That

I/O

VMS

Level

Guide.

programs,
to

routines.

discussion

User's

are

accomplished
using

Management

expected
to

logical,
I/0
operations,
allowing
corrupting existing data on any storage

affecting

the

concurrently.

operation

any

found

read

1in

the

before

the

initiated.

syste
by
m

Record

are

can

should

other

the

1issuing

$QIO0

system

Services

(RMS)

perform

virtual,

them

media

and

processes

execute

thus

not

executing

VAX DIAGNOSTIC

PROGRAMS

by issuing the
For level 2R programs, I/0 transfers are performed ostic
supervisor
diagn
VAX
the
case
$QIO0 service call, but in this
to VMS,
t
reques
I/0
the
passes
turn
in
fields the call. The VDS
ams
progr
2R
Level
rmed.
perfo
where the I/0 operation is actually
for
and
ms,
syste
e
entir
or
are used for exercisers of devices
force
not
to
able
desir
is
it
when
functional testing of devices
other

users off

the

system.

1level

Physical I/0 transfers are generally used in

programs,

s to all areas of the
since this type of transfer allowsum acces
of the device's
usage
maxim
device medium and thus provides
Use of physical
.
stime
acces
e
logic. It provides minimum devic
placed in the
be
to
have
will
I/0 implies that a "scratch” medium
s the device
unles
data,
user
valid
UUT in order to not corrupt
use by
possesses special "maintenance cylinders" reserved for
res that the user of the
diagnostic programs. It also requi
the
"user privileges"” (see
program be granted special s VMS
1is
1I/0
cal
physi
While
.
)
Guide
VAX/VMS Command Language User'
more
be
may
I/0
al
virtu
most often wused, logical or even
appropriate

in some cases.

the S$QIO service
Level 2 programs also perform I/0 transfers using
mode, the VDS
user
In
«call.
call, with the VDS fielding the
, itself
VDS
the
de
mo
ne
dalo
stan
passes the request on to VMS. In clear that one diagnostic
program
services the request. It is not different run-time environmen
ts,
should be written to run in two
of the sometimes
since the program is at best a compromisenme
(for example,
nts
iro
of the two env
conflicting characteristics users
ty to have
abili
vs.
mode
in user
ability to run with other
difficulty
the
Also,
.
mode)
unlimited system access in standalone

tionality within the VDS is
in maintaining this duplicity of 5> func
IC PROGRAMS ARE NO
DIAG
considerable. Therefore, LEVEL level 2 NOST
programs will be accepted
LONGER

No new
BEING DEVELOPED.

for release.

operations directly.
Level 3 diagnostic programs perform their I/0 ters
field its
That 1is, they address the device's regis ting and
nel,"
"chan
a
interrupts. The VDS provides services for crea
ostic
diagn
the
insulates
or addressing path, to the device. Thisssor
the
ing
enabl
type,
program from the specific VAX proce
with
rned
conce
be
to
programmer to create code that does not need .
Since at this
I/0 characteristics of particular processors
for block

ns
there are no software provisio
program level
possible 1is
type
I/O0
only
the
ing,
ctur
stru
formatting or file
in level 3,
en
Logic tests (see Chapter 1) are writtaccess
physical.
to the
ly comprehensive
since this level allows relativeprovi
and
user
on
ding the VDS's comm
device under test while also
programming interfaces.

”

VAX

Level

programs

thus

not

test

those

are

not

perform

portions

considered

DIAGNOSTIC

used

I/O

PROGRAMS

test

peripheral

operations.

the

CPU

part

They

cluster

the

VAX

hardcore.
Level

they

are

programs

generally

processor.

However,

some

diagnostic microprograms
physical I/0O operations.
Table

2-3

levels.

summarize
the
s

The

generally

table

assigned

Table

Level

also
to

2-3

not

perform

microprograms

level

test

I/O

methods

each

Methods

service.

Generally

logical,

and

allowed),

operations,

test

are

Supervisor's

since

portions

the
those

(specifically
devices)

may

in the
various
types of diagnostic

Program

using

physical

I/O

and

used

that

used

the

Virtual

virtual

perform

program
programs

level.

VMS

QIO

Diagnostic

peripheral

I/0 Method

devices

only

environment

programs

that

indicates

1I/0

used

I/0

should

logical

Types

System

Programs

exercisers.

(but

Exercisers

are

tion

tests

QIO

eral

devices.

wusing

VMS

using

VMS/VDS

and

func-

periph-

service.
2

Physical,
QIO

service.

Physical,
defined

wusing program1I/0

Function

tests

functions.

logic

tests

eral

devices.

Function

tests

ane,

physical USihg ~
functions.

devices.

None.

program-defined

tests

peripheral

and
CPU

and

periph-

logic

cluster.

Microprograms.

VAX

APPLYING THE VAX DIAGNOSTIC

2.5

PROGRAMS

DIAGNOSTIC

STRATEGY

the VAX diagnostic strategy to a specific product usually

Applying

developing

implies

programs

diagnostic

set

to test the

product.

2.5.1

Testing The CPU Cluster

several

program

Level

levels, as

existing

follows.

tests

Console

Processor

Memory

Level

programs,

set of

is tested by a

The VAX CPU cluster

tests

VAX instruction set test (hardcore for VDS)
Cache and translation buffer tests (VAX-11/750 only)

@
e

Level

level

(if no

Memory tests

Channel

adapter

Cluster

exerciser

5 test possible)

tests

VAX

This set of programs implements the

providing

set

blocks

building

diagnostic

strategy

which a system may be

tested, starting with the level 5 basic processor tests and ending

with

the level 3 "cluster exerciser," which is a program meant to

exercise

all

components of

cluster.

the

Level 5 programs may not exist for all VAX processors, since

are microprograms.
programs should

("front

end"),

executed

making

use

1in

console

separate
these

features.

on all

types

when

the

programs can be

new

processor

used

1is

processor

writable control store (WCS).

Low-cost VAX processors may not provide
Most of

they

Ideally (but not necessarily), microdiagnostic

developed

VAX

processors,

is not necessary to

new cluster.
produce a whole new set of programs for testing the
must be added to the
module
processor-specific
A new
However,
cluster

exerciser.

VAX

2.5.2

Testing

Thorough

there

Peripheral

testing

three

level

logic

level

function

level

group

also

without
level

bringing

the

conditions
method

the

via

the

which

customer's

level

the

The
of

making

level
the

technicians

level

function

device's

the

test

to repair

device

Level

level

will

provide

This

self-testing

aren't

capable

test

tests

program

function

typical
at

will

can

sequence
a

customer

error
This

1logic

boards,

contain
logic

used

usually

complete

test
to

very

required

detection

This

high

even

because

all

determine

correctly.

provides

consist

will

tested

the

use

for

site,

field

user

(VMS)

test

the

self-tests

function

the

found,
go

programs,

service)
B

level

test

stopping

run.

step

2R program

system
is

subset

much

the

environment.
copies
|

the

device's

The

tests

when dealing
with

follows.

suspects
|
|

2R program
is run to see if

approximate
o
|

these
as

test

without

operating

the

devices
perform

comprehensive

The level

via
'

bad

will

detected

~error

and

tested

detail of
is failing.

operating

are

typically

test.

The customer (or
in the device.

functionality

system

and

tests
1t
contains
are
exact
or
existing in the level 3 program.
A

programs
may

system

Some
that

capabilities,

unnecessary.

program

device

function

failures.
The

test

3 function

possesses

generally

logic

not
a

definitive

coverage.

functions.

accurately whether

device

greatest
of logic

and
will
provide
very high test coverage.
ROM-resident
microprograms
("self-tests")

testing,

strategy

used

type

accurate
and detailed

operating

logic test will provide the
indicating
which
section

will

device

diagnostic

very

program.

The level 3
resolution,

program

implements

down

development

test

for producing

fault

providing

the

each
|

test

function

facility

identifications

requires

test

programs

device

diagnostic programs.
For
(but not necessarily) exist

This

PROGRAMS

Devices

peripheral

typically

providing
by

different

will

DIAGNOSTIC

the

operating

fault
.

existing

error

can

system.

the

cannot

brought

identify

down

and

the

fault,

level
3

the

function

VAX

The

fault

operating

The

system

failing FRU

GUIDELINES

This

sections
writing

Level

the

then

is brought

FRU.

The

FOR WRITING

contains

the

failing FRU

brought

back

level
wused

FRU

VAX

general

VAX diagnostic

PROGRAMS

and

level
3 logic test, the
a module test station is

when

2.6.1

identified

The

logic

2.6

DIAGNOSTIC

back

up.

1is

DIGITAL,

replaced.

where

function test, or
to
identify
the

the

perhaps
failing

repaired.

DIAGNOSTIC

guidelines

PROGRAMS

that

should

followed

programs.

Guidelines

Level 1 diagnostic programs are usually used as exercisers of
the
entire
hardware
system.
Level 1 is used when 1t 1s necessary to
numerous
cause various concurrent activities to take place, using
types

provided

devices
by

the

and

other

hardware

and

software

<resources

system.

Since no standard human interface exists for level 1 programs,
it
is
important
for
the
program developer to design a convenilent,
"user-friendly" interface using such
techniques
as
English-like

‘commands, menus, and detailed "help" messages.
Error

reporting

designer.
error

2.6.2

will

However,

also

the

responsibility

much use can be made of

the

program

the system software's

reporting facilities.

Level

Guidelines

Level 2R programs run under the
VDS
is
wuser
mode.
They
test
device functionality and must test as many of a device's functions
as can be performed under the constraints of the operating system.
I1/0 is performed by
issuing
QIO
requests -to
the
VDS.
These
requests
are passed directly to VMS, which performs the indicated
operations and returns an error status.
Actual
I/O0
activity
1is
controlled
by VMS device drivers.
Full use should be made of the

returned error information,
which
may
include
device
register
contents.
All
information made available should be displayed to
the user via the VDS error reporting facilities.

The level 2R program should be written after the level 3
function
test
has
been
developed, since the level 2R program should be a
subset of the level 3 program.
Take the level 3
program,
change
the
I/0
method
from
the
channel
services of the level 3 (see
"below) to QIO
calls,
and
remove
any
functions
that
the
VMS
operating

system will

not

allow

2-12

performed.

VAX

DIAGNOSTIC

TM~

PROGRAMS

2.6.3

Level

WRITE

ANY

Level

NOT

2.6.4
Level

Guidelines
NEW

Function

programs

software

run

services

(discussed

the

diagnostic
details of

DIAGNOSTIC

Tests

the

program.

under

1limit

diagnostic
paths

LEVEL

Guidelines

the

VDS.

1in

the

under

system

hardware

test

i1s

order

dumps

tests

should

performing.

operating

system

rights

of the
channel
creating data

use

VDS

for

eliminate

the need
for
processor-specific

with

interrupts
are
fielded
by
the
programs have unlimited access to

detailed

contain

function

capable

also

resources,

that

access

program should
following chapters)

programs
to concern themselves
bus adapter mapping.

created

Level

the

I/0 operations are initiated and
diagnostic program.
Since these
be

There

functionality

However,

device

PROGRAMS.

error

messages

pertinent

test

every

1Illegal

can

and

should

the

device

registers.

function

orders

and

the

combinations

should

tried.

Not only should the data
transfer
functions
be
performed,
electromechanical
functions
should also be tested to assure

they

operate

should

within

the

specified

parameters

operater-related

write-protect

and

functions,

switch.

time
such

intervals,

setting

the

All timing operations
must
be
performed
services provided by the VDS, since the VDS

by
wusing
takes into

type

corrects

VAX

differences

2.6.5

Level

Because

processor

between

logic

good
Every

Guidelines

tests

are

designed

one

small

depends

logic

activity

effort

i1deal

the

than

boards,
activity

the

possible

time.

and

1is

particular

should
be made

section

used

the
timing
account the
for

timing

types.

Test

fragmentation

overall

being

processor

Logic

malfunctioning

but
that

help

1logic,

given

point

concentrate
The

hardware
attainable goal.

technicians

important

extent

design,

that

causing
in

and

1little

execution

electrical
which

repair

they provide

activity

this

time.

often

possible

VAX

DIAGNOSTIC

PROGRAMS

1is
that which
The first section of logic to be tested should be
Thus a general
on by other logic.
depended
be
to
likely
most
as
sequence of steps this type of program might contain would be
follows.

interface between the device's controller and the
address
including
attached,
is
it
which
to
controller
referencing
in
logic and logic used

Test the
bus
I/0
decoding

registers.

the

Test the controller's commands and

logic

associated

using the device's "maintenance mode"

command,

each

with

applicable.

Test the data transfer

maintenance mode.

using

functions

the

device,

again

In each step, invalid and borderline conditions should be checked.
For example, purposely formatting data improperly, issuing 1illegal
registers
function codes, and making illegal references to device
are

techniques

that

can

used.

timing
the
All timing operations must Dbe- performed by using
services provided by the VDS, since the VDS takes into account the
timing
type of VAX processor being used and corrects for
between

differences

2.6.6

processor

types.

Level 4 Guidelines

system
the
Level 4 programs are only used to test those parts of
not
are
that
and
the VDS environment's hardcore,
to
Dbelong
that
are
programs
4
1level
For example,
tested by level 5 programs.

needed
and

cache

test

some

the VAX instruction set, the tLanslatlon buffer,
not

(but

all) VAX processors.

If a new level 4 program needs

rules

should

adhered

to.

Use straight-line code
user
the
for
easier

developed,

the

following

it
This makes
(no subroutines).
through the program when
step
to

necessarye.

Use a minimum'instruction set,vat least at the
of

beginning

the program.

Write the program in p051t10n 1ndependent code, so that it
executed in any sectlon of memory 1in
and
loaded
be
may
case

there

a bad

area

of memory.

VAX

Create

section

conditions,
5.

not

such

use

required
6.

When

Use

the

DIAGNOSTIC

any

code

machine

terminal

perform

error

general

placed

Store

the

location,

Provide
to

use

2.6.7

very

type.

program

listing.

design
a

program

can

the

all

HALT

the

logic

tested.

instruction.

subtest

numbers

the

can

user

failure

and

what

must

find

out

was

the

user

some
them.

Since
must

exactly

happening

clearly

obtain

documentation.

provided,

microprograms.

set

are

Diagnostic

able

what
to

type

cause

indicated

the

Program

loops

tested

level

should

for

should

always

precise

the

each
be

and

there

processor

followed

1in

clear

description

program

component(s)

are

should

requiring

failing

enough

code

ECOs

program

should

fault

components

when

those

that

microcode

different,

when

designed

as short as possible, in order
to
activity
to
as small an area of the
Ideally, these loops should
enable
a
a

which

programs

rules

isolate

the

and

change

except

should

contain

referring

the

type

testing.

electrical
possible.

reports

should

level

microprograms

locate

Since

processor

microprograms.

bottom-up

EBrror

VAX

general

perform

and
@,

each

technician

execute

test

information

diagnostic

can

unless

previously

are

Following

routines

has

separate

isolate
logic as

I/O

been

interrupt

traps.

5 Guidelines

programs

developing

This

other

I/O

address

occurred

error.

hardware
must

precise

unexpected
or

GPRs.

displays

the

handle
checks

purpose
registers
(GPRs)
to
pass
the
user.
For
example,
on
a
data
the expected and actual bit patterns can

current

error

Level

the

such

terminal

the

detected,

information
to
comparison error,
be

PROGRAMS

their

for

component.

the

technician

listing.

what

may

The

logic

failing.

"E-numbers,"

listing

was

since

being
Avoid

these

issued.
be

able

external

test

every

stimulus.

component

CHAPTER 3
THE STRUCTURE OF A VAX SUPERVISOR
DIAGNOSTIC PROGRAM
3.1

INTRODUCTION

This

chapter

designed
discusses

describes

run

all

the composition
of
a
diagnostic
program
under
the VAX Diagnostic Supervisor (VDS).
It

the

functions

that
must
be
performed
by
the
such
as
device initialization and testing,
input/output functions.
It also provides
an

diagnostic

program,
reporting, and

error

introduction
where

within

the

macros

diagnostic

detailed

program

the

Chapter

various

indicating

macros

should

used.

3.1.1
The

Overview

VDS

The

divided

VAX Diagnostic
1into

three

Supervisor

major

segments,

performing

line

a
separate
function.
These
interpreter, the dispatcher, and the

Command

Line

The

command

the

line

interpreter

diagnostic

program

user

that

units

The
command
described in

segments

system

each

are

segment

the

service

command

routines.

Interpreter

portions

device

provides

©program.

select

which

program

programs

run,

the

human

allows

and

the

interface

diagnostic

execute,

which

the

test.

1line

1interpreter

the VAX

Diagnostic

implements
Superv1sor

the
User's

which

system S

commands
Guide.

Dispatcher
The

dispatcher

program.

interpreter
dispatcher
diagnostic
code,

1is

the

given

recognizes
will
call
program

tests,

which are
times.

controls

(such

<cleanup

discussed

operation

control

a
as

the

diagnostic

command

line

START
or
RUN
command.
the
wvarious
segments
of

The

the

code,

this

whenever

©program's
and

summary

chapter)

the

1initialization
routine,

the

all of
appropriate

THE

System

PROGRAM

OF A VAX SUPERVISOR DIAGNOSTIC

STRUCTURE

Service

Routines

" The system service routines provide run-time

services

the diagnostic program to facilitate many of the functions

a diagnostic program must perform, such as I/0 operations,

"error reporting, and event synchronization.
Figure

3 -1

illustrates the VDS segments and their relationship

a diagnostic

program.

USER'

~ COMMAND

LINE

" DISPATCHER

’

INTERPRETER

gznggés

DIAGNOSTIC
PROGRAM

]

UNIT UNDER TEST
TK-10516

Figure 3-1

3.1.2

VDS

Overview

A VDS Diagnostic Program

Overview Of

Every diagnostic program must possess several major

segments,

unit

follows:

Initialization Code

This is code that is executed before
tested.

a data

device

the operations necessary for creating
It performs

link

to the

device

tests.

unit.

Tests

These are

the actual

They report any errors

detected and provide the ability to create loops.
Cleanup

Code

This code performs any operations that might be needed

leave

the UUT in a state such that it is available to the

system

user.

THE

STRUCTURE

VAX

SUPERVISOR

There

are

various

for

the

tables

purpose

diagnostic program's
Additionally,
segments,

such

diagnostic

Error

Interrupt

service

Condition

handling

summary

that

the

low-level

routines
are
and

Program

‘Get

can

possess

program

should

called

testing

these

for

other

the

VDS

program

devices.

flows

dlagnostlc

Serial

viewed

©program

the

contains

flow
As

Passes executed

for

will

and the

Testlng:

REPEAT

Call

initialization

Call

selected

Call

summary

Unit_number
unit_number

Passes

UNTIL passes

cleanup

executed

executed
code.

code.

tests.

code.

unit

number

max unit

passes

both
seen

accomplished

number

number.

executed

EQL passes requested.

set

needed.

REPEAT

UNTIL

optional

dispatching

simply

when

are

program

START command.

Unit

the

routines

Get passes_requested.

Call

diagnostic

to control

routines

illustrations

between

RUN or

the

VDS

routines

parallel

Flow

program

read,

interaction

the

operatlon.

diagnostic

The

testing

residing
enabling

routine

reporting

mechanism.

Following

chapter

PROGRAM

Tables

program

Notice

DIAGNOSTIC

VDS.

serial
as

this

through

Get
Get

Flow

for

A VAX SUPERVISOR DIAGNOSTIC

Parallel

Testing:

RUN or START command.
passes requested.

Passes

REPEAT

executed
Unit

number

REPEAT

Call
Unit

initialization code.
number = unit number

Passes executed = passes_executed +
UNTIL passes executed EQL passes requested.

UNTIL unit number = max_ unitnumber.
Call selected tests.
Call

Call

3.1.3

PROGRAM

cleanup

Memory

summary

code.

Layout

Figure 3-2 shows the layout within memory of the various pieces of
All
software existing when a VDS diagnostic program is executing.
addresses
In standalone mode, the virtual
addresses are virtual.
also the physical addresses, so the illustration represents a
are
user
In
memory.
1in
layout
true picture of the actual program
and thus the virtual
operation
in
is
memory management
mode,

addresses shown have no relation to the actual program

layout

memory.

As can be seen in the figure, the base address of a diagnostic
(When a diagnostic program is linked, a
(hex).
is 200
program

The
must be explicitly specified.)
(hex)
base address of 200
loadable image of a diagnostic program may not extend beyond
the
for
the maximum size
Thus
(hex).
virtual address F9FF
loadable image of a diagnostic program is 63487

(decimal)

bytes.

communicate
to
VDS
the
Addresses from FA@Q@ to FFFF are used by
10000
address
The VDS loadable image starts at virtual
with APT.

(hex). At run time, the VDS occupies a
The
(hex).
memory starting at 10000
depends on such parameters as the type of

contiguous portion of
total size of this area
processor being used,

memory size, and the number of attached devices.

space to
allocate buffer
to
Two areas of memory are used
exist
may
The first area is any space that
diagnostic programs.
between the top of the diagnostic program's loadable image and
(and generally larger) area
The second
(hex) .
address FAQQ
address used by the VDS.
highest
the
above
addresses
of
consists
program is
a diagnostic
to
space
this buffer
Allocation of
d Section 3.13.3,
discussein

Memory Allocation.

TM~

Program

STRUCTURE

THE

STRUCTURE

VAX

SUPERVISOR

DIAGNOSTIC

PROGRAM

VIRTUAL ADDRESS (HEX)

UNUSED

200

DIAGNOSTIC PROGRAM

BUFFER SPACE

FOFF

FAQO

AREA USED FOR APT

COMMUNICATION
10000

VDS

S—

———

——

—

CE—

——

—

om———

BUFFER SPACE

TK-10517

Figure

3.1.4
All

Introduction

linkages

defined
main

between

set

3-2

VDS

The

Macros

Memory

the

diagnostic

macros.

These

groups.
@

This

Structure

group

delimited
Using

consists

the

tests,

and

the

those

cleanup

required

VDS

are

into

four

and

used

define

the

and

code.

exist

data

macros

call

Most

every

affect

structures

making

every test
$DS ENDTEST

enables

must
be
macros.

the

VDS

the

initialization

code,

the

macros

group

diagnostic

this

program.

Program Control Macros
These

macros

path

and

used

macros

structure

1locate

are

used

provide

branch-on-error.

;

the

divided

example,
BGNTEST
and

$DS

program

dispatcher

;

and

can

Macros

various
sections,
tables,
the diagnostic program.
For

program

macros
|

Program

are

Layout

define

the

For

such

example,

upper

bound

the
program's
execution
facilities
as
1looping
and

the

$DS

CKLOOP macro

a program

loop.

can

THE

STRUCTURE

VAX SUPERVISOR DIAGNOSTIC

PROGRAM

System Service Macros
This group
service

used

macro

program delay of a

call

service

$DS WAITMS,

specified

routines.

which can be

used

example

cause

number of milliseconds.

Symbol Definition Macros
This is a set of macros that define global symbols used by
VDS, and the diagnostic program.
the
macros,
other
the
the
For example, the $DS HDRDEF macro defines symbols for
header (see
program's
diagnostic
the
within
locations
Section

3.3.1).

This chapter will not give detailed descriptions

macros,

the

it will indicate when and where each macro (except the symbol
but
discussed
are
The macros
definition macros) should be employed.
detail

order

the

test

P-Tables

device,
a diagnostic

characteristics are

program must

system-specific,

have

some

Since

characteristics.

device's

impossible

access

device
define

it 1is
Instead,
program.
diagnostic
the
in
permanently
them
system-specific
these
which
by
means
a
provide
to
necessary
The VDS provides
specified at run time.
be
characteristics can
the "hardware parameter tables," or simply
"p-tables,"
for
this
purpose.

A p-table

device

is a

that

the device.

user

types

new

p-table

Supervisor

data

structure containing

is needed

in order

P-tables are constructed

the

ATTACH command

1is

created.

User's Guide).

Each

the

information

for a diagnostic program
by the VDS when

(refer

time

the

about

the

to access

program

VAX Diagnostic

the ATTACH command

1s used,

the p-tables,
Once the VDS has created

obtain
to
tables
the
reference
can
program
diagnostic
the
of
burden
the
Thus
UUT.
a
testing
for
necessary
information
diagnostic
determining device characteristics is removed from the
program

itself.

3-6

Introduction To

P-TABLES

3.2.1

Chapter

3.2

THE

STRUCTURE

VAX

SUPERVISOR

DIAGNOSTIC

PROGRAM

When the user attaches
a device, one of the parameters he
or she
must
specify
1is the
device's
"link." The 1link is the piece of
hardware to which the device is connected.
The
1ink
must
have
been
previously specified with another ATTACH command
p-table already exists.
A set of ATTACH commands will

tree

structure

device

1links.

The

root

so that its
result in a

this

tree

pseudo-device called HUB.
This pseudo-device was created
the
actual
hardware interconnect existing depends on the

processor

(for

processors

buses,

and

illustrates

example,

and

buses

the

are

device

units

the

manner

SBI

are

the

VAX-11/780).

HUB,

linked

system.

linked

which

controllers

p-tables

describe

11/780 | gg, | UNIBUS
CPU

ADAPTER

RKO06

DRIVE
O
RK611

CONTROLLER

RKO6

DRIVE 1

TYPE:

Dw780

LINK:

HUB

NAME:

DWO

P-TABLE FOR
UNIBUS ADAPTER

DEVICE CHARACTERISTICS

TYPE:

RK611

LINK:

DWO

NAME:

DMA

P-TABLE FOR

DEVICE CHARAC- | DISK CONTROLLER
TERISTICS

TYPE:
LINK:

NAME:

RKO6

DMA

DMAO

DEVICE CHARAC-

P-TABLE FOR

TYPE:

RKO6

LINK:

DMA

NAME:

DMA1

DISK DRIVE O

P-TABLE FOR
DISK DRIVE 1

TERISTICS

TK-10518

Figure 3-3

Sample Hardware Configuration

and Associated
3-7

P-Tables

because
type of

general,

are

controllers.

linked

Figure

3-3

hardware

STRUCTURE

THE

OF A VAX SUPERVISOR DIAGNOSTIC

The p-table for a particular device will contain

provided

contain the

the

ATTACH command

following

standard

arguments.

information:

Device type- This is the product

such as RK@6 or

TM@3.

name

PROGRAM

the

Each
|

for

information

p-table will
the

device,
the

which
with
Device's generic name - This is the name
device will be referred to, such as DRB1l or DMAJ.

Address of p-table for device's 1ink

that
information
of
types
Device characteristics - The
included in a p-table to sufficiently describe a
be
must
1link.
its
and
device
device depend on both the type of

For example, devices linked to a UNIBUS require the UNIBUS
device's
the
plus
1level,
request
bus
CSR address and
interrupt vector

39 292

P—Table

address.

Format

P-tables have a standard

format.

Each p-table is divided

into

two

first section contains device-independent fields.The
sections.
Each
fields.
these
<contain
devices
all
for
p-tables
All
device-independent field in the p-table has a mnemonic assigned to
fields
these
it which can be used by the diagnostic program when
p-table contains
the
of
section
second
The
referenced.
are
type
device-dependent information. This section is unique to the
of

device being

Figure

3-4

Following

described.

shows

the

description

standard

layout of all

the

p-tables.

device-independent

p-table

fields.

HP$Q DEVICE - A VMS-type quadword
descriptor
of
the
device
name string (see HPST DEVICE below).
That is, the first word

of the field contains the length (number of characters) in the
device name string, the next word is unused, and the following
of
address
(the
longword contains the address of the string
HP$T

DEVICE).

1includes
This
HPSW SIZE - The size of the p-table in bytes.
the device-independent and the device- dependent p-table
both
fields.

THE

STRUCTURE

VAX

SUPERVISOR

DIAGNOSTIC

PROGRAM

0 (decimal)

HP$Q_DEVICE

HP$B_DRIVE

HP$B_FLAGS

HPS$W_SIZE

8
12

HP$T_DEVICE

‘6

HP$A_DEVICE

HP$A DVA

HP$A_ LINK

HP$W_VECTOR

HP$T_TYPE
44

HP$A_DEPENDENT

J 52

:::

®
[]

TK-10519

Figure

HPSB

Flags

initialized.

Flags

FLAGS

3-4

P-Table

used
are

the

defined

HPSM ALLOC -

(bit

request

VMS

allocate

device

before

HPSM

WASALL

can

(bit

- If
be

successfully

allocated.

(Bits

Unused.

2-7)

Layout

set,

VDS

when

device

follows.

indicates

(SALLOCATE

tested

user

Set

VDS

the

that

system

the VDS must
service)

the

mode.

device

has

been

THE STRUCTURE OF A VAX SUPERVISOR DIAGNOSTIC PROGRAM
the
1is
This
device.
the
of
HPSB DRIVE - The unit number
number appearlng at the end of the device's generic name, such

' TTAT'.

'7'

wvirtual

The

depends on the device

device,

and

address

type

type.

device,

UNIBUS

for

the

it would

For example,

configuration

lowest-addressed

being

pointed to

CSR

an SBI

for

on.

The address must be virtual, in Pl space (bit 30
is
because
when
memory
management is enabled

mode,

RHO'.

' ', as in '
All device names begin with

HPSA DEVICE - The

device

device's

the

representing

string

HPST DEVICE - An ASCII

generic name.

set).
This
in standalone

the VDS maps all phy51ca1 I/0 addresses through

virtual

space.

HP$ADVA - This

the

base

the

wvirtual

address

space

Devices linked to this device will
this device.
assigned to
When
have address assignments relative to this base address.
constructs a new p-table for a device linked to this
VDS
the
one, it copies this field into the linked device's HPSA DEVICE
When the device address for the new device is fetched
field.
from the user,
HPSA DEVICE.

it can be added

the base address already
|
|

1in
|

The address must be virtual, in Pl space (bit 30
management is enabled
memory
when
Dbecause
is

mode,
Pl

the VDS maps all physical

set).
This
in standalone
virtual
I/0 addresses through

space.

1its
An example of
The HPSADVA field is not always relevant.
Each UNIBUS is assigned
is the case of UNIBUS adapters.
use

The addresses of devices connected
to a certain base address.
a particular UNIBUS are added to the UNIBUS's base address
to
UNIBUS's
A
address.
to obtain the device's actual physical
stored in the HP$SA DVA field for a UNIBUS's
1is
address
base
its
UNIBUS,
the
to
1linked
When a controller is
p-table.
HPSA DEVICE
field
will be initialized to the value contained
in the UNIBUS's HP$A DVA field.
Subsequently, the
wuser
will
This address
for the controller's 18-bit address.
be prompted

can be stored

in the

1low-order

bits

HPSA DEVICE

result in a full physical address for the controller.
HPSA LINK - The address of

this one

field

1is

contains

1linked.

the

p-table

for

this device

the device to which

is 11nked

to HUB, the

HPSW VECTOR - If relevant, contains the vector address through
This address is an offset
will interrupt.
device
the
which
into

the

System

Contol

Block

3-10

(SCB).

THE

STRUCTURE

VAX

SUPERVISOR

DIAGNOSTIC

HPST TYPE - Contains a counted ASCII string
device type, such as DW780, RH780, or RKG6ll.

HPSA DEPENDENT - The first location
section

The

HPSW SIZE,

all

the

PROGRAM

representing

the

device-dependent

p-table.

HPSQ DEVICE,

HPSB DRIVE,

HPST DEVICE,

HPSA_LINK,

and
HPST TYPE fields are filled in automatically by the VDS.
The
other fields are loaded (if needed -- not all fields are
relevant
devices)

p-table

descriptors

The
fields
within
mnemonics, but they

3.2.3

P-Table

3.2.3.1

accordance

(see

the
device-dependent
are unique to the device

contained

section
also
(see below).

device

device-dependent

Following

dialogue

that

VDS

referring to a "p-table descriptor." This is
that
1indicate
the
size
and
format

specified

the

have

Descriptors

device-dependent
p-table
ATTACH command, the VDS will
the

directions

Introduction To P-Table Descriptors - The

p-table
by
instructions

the

below).

type

order

fields

sample

are

fields.
refer to

ATTACH

typed
DS>

user

ATTACH

type?

RK61l1

Device

1ink?

DW@

Device name? DMA
777440

VECTOR? 210
BR?
4

VDS

user
types
descriptor
how

a set of
of
the
an
of

construct

p-table.

dialogue.

the

Device

CSR?

determine

particular

command

the

When
a
the
p-table

builds

Portions

are underlined.

the

THE

STRUCTURE

VAX

SUPERVISOR

DIAGNOSTIC

PROGRAM

In the sample, the first three prompts fill in
device-independent
fields of the p-table.
These prompts are generated by the VDS and
will be displayed every time the ATTACH command is used.
The last
three
prompts
are device-specific.
These prompts are defined by
the p-table descriptor for the RK61ll1.
|
|

Instructions within
following

types

the

The

p-table's

The device type

A prompting
parameter

p-table descriptor

specify to

information.

VDS

the

size

message
be

for

stored

each
the

device-dependent

deVicé—dependent

interpreted

The
p-table
field
in
device-dependent prompts

hardware

p-table

The format in which user response to the

prompts

the

which
are to

the
responses
be stored

the

3.2.3.2
Location
of
P-Table
Descriptors - P-table
descriptors
generally reside in the VDS.
When a diagnostic program is written
to test a device for
which
the
VDS
does
not
possess
p-table
descriptors,
it
1is
the
reponsibility of the diagnostic program
developer to also create a
p-table
descriptor
for
the
device.
This

descriptor

Note:

group when

P-table

will

then

important

developing

descriptors

program.

When

Including

the

incorporated

to work
a

may

the

VDS.

in cooperation with

p-table

also

processing

into

the VDS support

descriptor.

included

an ATTACH command,

the

diagnostic

the VDS will

first

check the diagnostic program to see if a p-table descriptor exists
for the specified device type.
If none exists, the VDS will check
its own p-table descriptors to locate the appropriate one.
Thus,
a descriptor residing in a diagnostic program will have precedence
over a descriptor for the same device residing within the VDS.
descriptors

diagnostic

program

disadvantages.
They can only be used by the diagnostic

are

program

defined.

The devices they describe cannot be
diagnostic

program

which

has

been

loaded.

attached

unless

the

|
-

they

several

has

THE

STRUCTURE

These
APT.

SUPERVISOR

Diagnostics

execution

When

VAX

DIAGNOSTIC

autosizer

the

descriptors

development

(CRD)

programs

The

program

may

1itself,

will

reside

program

has

been

also

containing

in
for

only
the
a

Each

new

device

the
the

wuser

solidified.

prompting

Responses

to
the
example,
instead
@

Only

what

should

message

information

requested

particular
type
UNIBUS addresses
of

hexadecimal,

Once

include

device.

information

This

device's

that

information

address,

interrupt

dev1ces

for

which

begins,

the

p-table

p-table's

design

following
general
p-table descriptor.

should
the
in

the

Only in rare instances
diagnostic program that

provide

user

must

format

of
data
should
be

since

p-tables.

diagnostic program until
design
of
the
device

P-Table
Descriptors - The
be followed when creating a

indication

prohibitions

own

support

is certain, it can be included in the VDS.
should
it
be
necessary
to
release
a
contains its own p-table descriptors.

3.2.3.3
Creating
guidelines should

place

their

VDS.

descriptor
should be first placed in
the descriptor
design,
and
indeed
hardware

PROGRAM

diagnostic programs will
not
be
executable
under
Other
special
environments,
such
as
Customer-

Runnable

clear

that

relevant

being requested.
For
formatted
1in
octal

that is

their

needed

may

include

vector,

provide.

normal

for

format.

referencing

such

items

the

level,

and

on.
Do not include information that will only be used by
one diagnostic program;
remember that
a
p-table
for
a
particular
device will be used by all diagnostic programs
that

test

program

macros

There

are

two

"skeleton"

that

(see

Chapter

steps

for

device.

test

the

creating

This

skeleton

required

for

the

4).

p-table's

defined.

response
to
an
device-independent

Information

should

p-table.

needed

obtained

p-table

via

representation
the

the

particular

$DS

descriptor.

device-dependent

When

VDS

the

must

memory
a

ASKxXxX

First,

fields

builds

ATTACH
command,
skeletons
and
device-dependent fields

space

p-table

of
both
the
are copied into a

dynamic memory storage area, and the fields are filled in with the
proper
information.
The
MACRO-32
skeleton
for
the
device-dependent fields is defined by using the S$SDEFINI, S$SDEF, and
SDEFEND
macros,
which
are
defined
1in
the
VMS system library
LIB.MLB.

example

skeleton

follows:

THE

.MACRO

STRUCTURE

S$DS

RK611

DEF

SDEFINI

SUPERVISOR

DIAGNOSTIC

PROGRAM

S$SGBL

$GBL, HPSA DEPENDENT
HPS$SL RK611 CSR, .BLKL, 1
;18-bit CSR address

SDEF

HP$B

SDEF

RK611 BR,

.BLKB,

HPSK RK611 LEN

SDEFEND

RK611,

SGBL,

;UNIBUS

DEF

level

$DS_RK11l DEF

Note:

The

p-table.

The

VAX

RK611,

SDEF

.ENDM

the

final

BLISS-32

$DEF

statement

the

example

defines

the

1length

“

version

|
of

this

example

is:

BLISS-32:

$SDS_RK611 DEF=

SET

[HPSK LENGTH+0,d,32,0],
[HP$SK LENGTH+4,
0, 8, ]

HPSL RK611 CSR
HP$B”RK611
BR

TES;—

This skeleton represents
of an RK61l1l controller.

are

two

fields,

named

HPSL RK611

MACRO-32

skeleton

Section 3.2.3.4 for

Notice

p-table

that

the

field naming

descriptor

1is

added

available to diagnostic
calls
this
mnemonics.

macro it
(See the

Notice

the

that

the device-dependent fields for a p-table
Each field is assigned a mnemonic.
There

CSR

and

HPSB RK611 BR.

defined

the

programs.

After

VDS,

macro.

this

the

skeletion

simply

When

macro

field

program

using

The

second

the
for

are

~and

step

the

creating

instructions

that

p-table

the

VDS

descriptor

will

use

when

the

declaration

statement.
The BLISS-32
example in Section 3.2.4 indicates
the field declaration is used by a diagnostic program.

generating

the

1s made

diagnostic

can reference the p-table fields by
MACRO-32 example in Section 3.2.4.)

BLISS-32

(See

conventions.)

how

involves

filling

device-dependent fields.
Also, instructions must be developed
filling
1in
the following device-independent fields, 1f they

relevant

HPSW_VECTOR.

the

device:

HPSA DEVICE,

HPSA DvVA,

HPSB

FLAGS,

THE

STRUCTURE

These

instructions

macros

make

use

VAX

SUPERVISOR

DIAGNOSTIC

are produced by using a
set
a temporary storage location

PROGRAM

of
macros.
‘The
referred to as the

"value

register." Certain macros cause information to be read from
the ATTACH command line and placed into the value register.
Other
macros can manipulate the value
register's
contents,
and
still
others
can
transfer
those
contents into fields of the p-table.
The p-table descriptor macros are as follows:

SDS SINITIALIZE

- This

descriptor.
It
size, the maximum

~®

the

first macro
the

any

p-table

device

the

device

type, the p-table
number of units allowed, and the name of
driver
wused
for level 2 diagnostic programs

(see

Chapter

2).

S$DS SNAME - Specifies a format to which the device
generic

name

must

S$DS $DECIMAL,
$DS

is typed.
which the
be

',/'///-\.

and

the
to

S$DS
to

used

$DS
a

the

SDS

data

the

used

alphabetic

string

the

programmer

and

stored

- These

the

into

the
and

SCASE,

$DS

read

wvalue

are

$DS

$DS $LOGICAL command
$DS

SSTORE

field

field.
place

used

S$DECIMAL,
will

it,

SDS

place

within

value ‘register's

field

macros

from

contents

macro
number,

Information

received

add

in
to

decimal

macros,

$DS_$STRING,

value

obtain

message.

1line

was

ATTACH command

$DS SDECIMAL

type

of these

contents

data from

the

contents

SFETCH

will

right-justified,

$DS_$END

- The

alter

p-table
shows

the

SDS SFETCH

that

SDS_SADD will

value

used

use depends on the format
particular parameter
1is

prompting

3-1

user when

SDS_S$STRING,
is

$COMPLEMENT

each

$DS_S$HEX,

are used

of
Example

the

macros

example,

command

current

retreive

the

macro

For

user

placed

p-table.
-

SDS_ SHEX,

these

user

$DS_SADD,

$DS_SOCTAL,
value

the

SSTRING

typed

$STORE

the

For

manipulate

and

The exact macro to
input string of the

from the ATTACH
register.

parameters from

specifies

Each

interpreted.

should
is

unit's

conform.

$DS_$OCTAL,

SLOGICAL

hardware

1indicates

how

$DS
the

contents

$DS_SEND macro

SLITERAL
of

the

used

descriptor.
these

macros

are

used.

value

These

macros

indicate

the

end

THE

STRUCTURE

OF A VAX SUPERVISOR DIAGNOSTIC

$N5. $INITIALIZE
FUS L ENAME
FNGEDCTAL
NS F5TORE
P05 $5TORE

RK&11y RKATLIEK.LENy O
FTOEMOCONTROLLER, I'M
CSRs 724000Gs 777776

FN5 . $0CTAL

HF$L
. RK&1T LCERs
HEEA DEVICE, Oy
VECTORY 2y 776

Oy
18

FNS5 L ESTORE

MFEW.
. VECTORY

0»

SNG_ ELECTMAL

BRy

HF$RB.RK&61L_
BRy

505

S TORE

PROGRAM

M-

CBTIE
S END

Example

3-1

P-Table Descriptor

for

RK611

Disk

Controller

This example will produce
the
dialogue
illustrated in
Section
3.2.3.1.
Explanations
of
the
macro
arguments can be found in
Chapter

This

example

will:

Cause

the VDS

Store

the CSR address

Cause the VDS

31,

request

the

user

type

in HPSL RK611l CSR,

and in HP$A DEVICE, bits @ through 17.

request

the

user

CSR address.

bits

type

through

vector

address.

Store the vector address in HP$W VECTOR,

Cause

Store the BR level

Following

the

RH780

contains

the VDS to

request

# through 8.

type a BR level.

bits

@ through 7.

example -- the p-table descriptor

adapter

the MACRO-32 and

user

in HP$B RK611 BR,

is a more complex

(MASSBUS

the

bits

for

the

VAX-11/780).

BLISS-32 skeletons.

3-16

for

Example 3-2

THE

STRUCTURE

VAX

SUPERVISOR

DIAGNOSTIC

PROGRAM

MACRO-32
2

« MELRI

$OS RHZ7B80.DEF

s$GRL

POEFINT

RH7B80 s $GEBLyHFSA

PUOEF

HFE$E_ . RH780_.TRs s BLKE, 1

DEFENDENT

number
of

s0EF

HP$BE_RHZ780 _BRy . BLKEB. 1

level

#DEF

HF$RK_RH7820_LEN

asdarter
adarter

FOEFENT

RH7830»2LBL
DEF
|
5 _RH720_DEF

+ ENDM

BLIGL -3

SET
HFEEE
. HHZ780.TR
HFE$R.EH780_BR

RH7B0DEF
=

LHF$K _LENGTH+0:0:8201,

$NS

CHF$K .LENGTH+1+50+8,01]
.

TESs
Exampl e

Example

3-2

P-Table

for

RH780

MASSBUS

Adapter

3-3 presents the p-table descriptor for the

descript or

causes

l‘

VDS

The
(TR)

Skeletons

The

will

following
request

events

user

for

stored

the

RH784.

This

occur:
an

SBI

transfer

request

1level.

level

through

The

the

will

1is

also

HPSB

RH780

TR,

bits

level

through

stored

HPSA

DEVICE,

16.

bits

The TR level is also stored in HP$W VECTOR, bits 2 through
5‘
The

VDS

will

The

BR level

stored

The

also

level

request

the

user

for

HP$B

stored

level.

RH780 BR,

bits

HPSW VECTOR,

@ through

bits

through

The

value

The

"6"

(This

is placed
will

/q -

physical

create

address

loaded

with

the

HPSA DEVICE,
a

virtual

2@@@@@@@

(hex)
.)

value

bits
space

"6."

through

address

for

31.
the

THE STRUCTURE OF A VAX SUPERVISOR.DIAGNOSTIC PROGRAM
10.

of
The contents

loaded

HP$A DEVICE

the

into

wvalue

This value

is written

into

HPSA_DVA.

12,

The value register 1is 1oadéd with the value "1."

13.

The "1" is piaced in HP$SA DVA, bit 10.

14.

The "1" is placed in HP$W_VECTOR, bit.8.
$US. RH780.DEF

$INITIALIZE

ENAME

SIS _$DECTHMAL
$NS. . $S8TORE

FTO$EM_UNIT,

TRy1s15
HF$R.RH780_TR+0+8

FNG . $STORE

HF$A.
. TEVICE» 13,4

$STORE

HF$W_VECTOR2+
4

SRS
NS

$DECIMAL
$8TORE

BRs4,7
HF$R_RH780_BR.0,+8

$NE_$ETORE

CHF$W_VECTOR»
692

S8 sLITERAL
FNE$STORE

&
HF$A_DEVICE 28,4

$NS . $FETCH

HE$A

SSTORE

HF$A
. TIVA, 0 32

$1S . $STORE

HF$A_TIVA» 10,1

$LITERAL

NS _$STORE
G5 $END

Example

RH?SO!RH;BO$& LEN,8

3-3

DEVICE 0,32
|

HF$W.VECTOR
8+ 1
o
|

P-Table Descriptor

for

RH780 MASSBUS Adapter

Note that several fields of
a p—table created from this descriptor
require

several

constructed

steps.

For

1instance,

the HPSA DEVICE field

1is

by:

Setting the high order four bits to "6" (bit 30
indicates
Pl
space
and bit 29 indicates VAX-11/780 I/0 addresses).
The VDS
remember.
to
This is an important step
Note:

‘maps

turned on.

as virtual

addresses to I/O space when memory management 1is
Therefore device addresses must be constructed

addresses

Pl space.

which

will

In this case the contents of HPSA DEVICE are copied

into

Using

the TR level

to set bits 13 through 16,

select the address space for
HPSA DVA,

and bit

the

10 of HPSA DVA

TR level.
indicated
is set.

THE

STRUCTURE

(Note:

will

When

device

initialize

contents

for
HPSA

VAX

the

SUPERVISOR DIAGNOSTIC

attached

example

adapter's

illustrates

coordinated

this

RH780

field

that

field.

The

p-table

HPSA DEVICE
HPSA

the
device
must
be
DEVICE that were loaded

descriptor, to
possible
1ink

that

DVA

careful
in HPSA

not
DVA

to
of

important,

first obtain copies
of
devices.
The
design

with

p-table design

for

mnemonics.

These

p-table

descriptor

macros

Also,

the
references

The
for
the

diagnostic

link

RK611

by
on,

p-table

Fields - For
easy
p-table should be

then

use

the

used

and

the

$DS_S$FETCH.

mnemonics

when

( ),

the data type specifier (L for longword, W
as
1listed
in
Table
5-1), followed
by
followed

controller's

storing
i

devices.)

$DS $ADD,

p-table.

followed
and
so

underscore

the

RK611 CSR.

Note:

Many

p-table

was

the

device-dependent

the

current

then

address.

This

were

Previously,

For

example,

the

field

for

device-dependent

device
name,
as in 'RK611SL

fields

name.

1is

named

Dbefore

standard

was

this

for

field

dollar
sign,
data
type,
CSR'.
If the mnemonics for

particular

they will

field

developed
the

for
an

p-table

conform

this

not

match

old standard.

Referencing P-Tables from a Diagnostic Programr
program

$DS_GPHARD

macro.

argument

the

program

the

Program

can

above) .

macro,

base
then

address

The

the

$DS

GPHARD

provides

for

the

macro

macros

define

device-dependent

3-19

that

unit.

wusing

the

offsets

(see

mnemonic

further

p-table
them

diagnostic

The

the

3.5).
p-table

field
must

fields and,

fields).

for

referencing

device-independent

the

Section

the

using

discussed

(see

wunit number

p-table

field

before

which

pass

the

code

that

p-table

within

example

Notice

will

predefined

initialization

referenced,

SDS RK611
DEF

indicates

VDS

fields

and

program.

($DS_HPODEF

the

address

Example

3-4

access

program

and

access

MACRO-32

gains

The

description

field

descriptors

standard,

A diagnostic

base

the

has
CSR

implemented.

names to consist of the
underscore, field name,

3.2.4

p-table

<controller's

HPSL

standard

the

field naming conventions for p-tables follow the VMS
standard
data structure naming conditions.
The field name begins with
name of the data structure (HP), followed
by
a
dollar
sign

($),
word,

can

VDS

descriptor

when designing

can

$DS $STORE,

program

the

device

the
descriptors
for
all
of the new p-table must be

these

mnemonics

adapter,

overwrite
bits
in
the
adapter.
This

3.2.3.4
Creating Names
for
Device-dependent
reference,
all
device-dependent
fields
of
assigned

PROGRAM

mnemonics
be

this

called

case,

THE STRUCTURE OF A VAX SUPERVISOR DIAGNOSTIC PROGRAM

. Lefine device-inderendent r-table fields

$T1S_HFODEF

JNefime RK&11 device~dependent fields

$0OS _RK&611 . 1EF
]

LOG_UNIT?
FTARBLE

UDEV_NAM:

+ BLKL
« BLKL

1
1

: Flace to store log, unit no.
i Flace to store rointer

+ASCIC

N\RK&11N

Ascii name of desired device

Get

FPtable

for

nmnext

address

FTABLE

LOG_UNIT

INCL

$NS_GFHARD.S

CMFL

ENEQ

10%:

DNS$_NORMAL

- ROy

40%

DEV_NAMs RO
(RO)Yy HF$T_TYFE(RZ)
20%
A(ROYy HF$T_TYFE+4(R2)
30%

MOVAL
CMFL
RNEQ
CMFW
REQL.

‘
$N1S_AEORT ARG=TEST
HF$E_RK&411_BR(R2), R10
MOVUZEL

20% ¢
306¢

HF$A_DEVICE(RZ)s

units done

then branch to re-init,

K11

i Set us rointer to ture
3 Check length and first 3
characters of tuare.
’
# Check last 2 characters
i If it matchesy 0OK

3
+

If ot RK&611ls abort test
Set R10 to BR level
Set R11 to CSR zddress
//‘m\\\\\

MOVL

If 211

unit

log.

i Use R2 zs structure rointer

FTAEBLEy R2

MOUVL

DEVNUM=LOG_UNIT,
ADRLOC=FTARLE

40%
3

Example

(Note:

p-table

3-4

Referencing

P-Tables

MACRO-32

This code is meant only'tO‘show an example of~the

included

mnemonics.
in

real

The

function

diagnostic

use

performed does not need

program.)

be
-

Example 3-5 is a BLISS-32 example of referencing p-tables.
Notice
that before p-table mnemonics can be referenced, a pointer must be

$DS HPO DECL
the
using
'PTABLE')
declared (in this case called
declaration for the device type
field
the
including
and
macro
being

Notice

tested

(an

that the

this

RK61ll

'HPST'

prefix

case).

fields

expand

only to addresses.

data fetches from these fields, explicit field
do
be made (as in the example for HPST TYPE).

references must

THE

STRUCTURE

VAX

SUPERVISOR

DIAGNOSTIC

PROGRAM

BEGIN

LLOCAL

LOG_UNIT,
BR_LEVEL

!
!

Place
Flace

to
to

store
store

log. unit
BR level

rno.

STATUS»
I Status return from service calls
CSR ¢ REF VECTOR [C» LONG1,
I llevice register access
FTARLE ¢ REF $DS_HFO._.DECL ($DS_RK&611_DEF)}
| Address of Ftable

BIND

DEV_NAM

Get

the

UFLIT

address

RYTE

the $DS_GFHARD

(ZASCIC’RK&é6117)3

the

r-table

for

ca3ll

returns

successfullyy

the

mext

Ascii

lodicazl
do

name

unit

the

device

rnumber.

Frocessing.

LOG.UNIT

STATUS

$NS_GFHARD

LJLOG_UNIT

(UNIT=.,LOG_UNIT,

RETADR=FTARLE))
IF

.STATUS
THEN

EQL

$0S_GFHARD

Ftable

+(FTARLE
OR

Get

DS$_NORMAL

REGIN

CHF$T_TYFE])

+(FTARBLE

NEQ

CHF$T_TYFE]

.DEV_NAM
+

4)<0s

16>

VYalidate

NEQ

worked

ture

.(DEV_NAM

THEN

$NS_ABORT

(ARG

TEST):

BR_LEVEL

CSR

= .FTAEBLE CHF$B_RK&611_ER1;}
FTAELE C[HF$A_DEVICE];

Get

Abort

test

bus

request

Get

CSR

4)<0y
wrong

level

rointer

END

ELSE

BEGIN

$LUS_GFPHARD

returrmed

error.

ENTI
END
s

Referencing

3-5

Example

P-Tables

BLISS-32

16
device

THE STRUCTURE OF A VAX SUPERVISOR DIAGNOSTIC

PROGRAM

of
use
This code is meant only to show an example of the
(Note:
be
to
need
not
does
performed
function
The
p—-table mnemonics.
included

in a

diagnostic

real

program.)

Attaching From Within The Diagnostic Program

3.2.5

necessary

It may occasionally be

for

diagnostic

program

instead of depending on the program
explicitly attach a device
1is
For example, if the program
user to issue an ATTACH command.

a file (see Section 3.15, File Management), the

access

going

device on which the file resides must be attached before it can be
case, the diagnostic program can issue the
this
In
referenced.
This macro serves exactly the same function

$DS ATTACH macro.
the

ATTACH command.

DIAGNOSTIC PROGRAM GLOBAL DATA STRUCTURES

3.3

The data structures described here are used
about

3.3.1

the diagnostic

Diagnostic

program

the

VDS.

pass

information

Program Header

var ious
The diagnostic program header is a data block containing
program's
the
as
such
VDS,
the
by
needed
on
informati
types of

program

title and pointers to the various areas of the

VDS must call

during program

execution.

that

the

This macro
The header is allocated by using the $DS HEADER macro.
(lowest)
first
the
is
It
program.
the
of
beginning
the
will be at

When the program 1is
area of memory allocated to the program.
will be location 200
address
first
header's
loaded by the VDS, the
(hex)
.

Some header entries must be initialized at assembly time wusing
macro arguments. Other entries are filled in by the linker. The
diagnostic program should not alter or reference any header
entries during

3.3.2

Dispatch Table

The dispatch table is

program
The

execution.

program

control

the

means

which

the

VDS

dispatches

the various tests in the diagnostic program.

table consists of a

list of addresses of the

tests.

The
The dispatch table is defined by the $DS DISPATCH macro.
ic
diagnost
the
when
d
table's entries (test addresses) are generate

program

1is

linked.

’/,,--\\

THE

3.3.3
The

STRUCTURE
OF A VAX SUPERVISOR DIAGNOSTIC

Program

program

names

pointers

Sections

sections
the

to
a

section

determine

the

program

3.3.4
The

device

what

mnemonics

types

testing.

The

uses

this

table

VDS

with

RUN

section

defined

the

well

table

START

exists

defining

3.8.3),

and

when
the
user
command, in order to
where

with

the

which

located.

SDS_SECTION macro.

List

list

RUN

strings

Section

devices

When
a

character
(see

name

Mnemonics

contains

sections

specified

sections

Device

table

sections.

specifies

The

Table

program

the

PROGRAM

the

START

means

diagnostic

command

the

program

issued

VDS

determines

1is

capable

the

VDS

user,

the

compares the device types in the device mnemonics list against
the
types
of
the & SELECTed
devices
(see
the
VAX
Diagnostic Supervisor User's Guide)
to determine if there are any
SELECTed devices that the program can
test.
The
1ist
has
two

kinds

ASCII

entries.

strings

Entries

addresses

can

For device types'having p—table
VDS,

device

address

types

The

having

program,
the

the

device's

3.4

PROGRAM

Most

counted

within

list

It
the

complete

one

For

AND

defined

list

1is

<created

and

the

formatted

contain

several

tests

common
for
a system-under-test
of device being tested.

(see

have

diagnostic

the

Section

several

all

selected

tests

all

selected

units

all

selected

tests

one

selected

wunit

"pass."

execution

will

within

will

descriptor.

"subpass."

pass

entry

SUBPASSES

programs

execution

program

complete

1is
type

mnemonics

the
of an
RK06,

PASSES

diagnostic

3.8.1).
units of

each

defined

descriptors

device

p-table

device.’mnemonics

One

descriptors

p-table

$DS DEVTYP macro.

i1s

addresses

device
mnemonics
1list entry will be the address
string representing the
device
type
(for
example,

diagnostic

One

descriptors.

the

ASCIC

For

either

p-table

program

consist

employing
one

serial

testing

subpasses.

(see

Chapter

1),

THE STRUCTURE OF A VAX SUPERVISOR DIAGNOSTIC PROGRAM

(see Chapter
For a diagnostic program employing parallel testing
devices are
all
since
1), each pass will contain only one subpass,
tested

3.5

concurrently.

INITIALIZATION CODE

Prior to the execution of a group of tests on a particular device,
the diagnostic program generally must perform some initialization
functions. These functions 1include obtaining the address and
other needed characteristics of the next unit to be tested,

initializing ©program
and
the device,
creating a data path to
buffers and counters. These functions are placed in a portion of

the diagnostic program known as the "initialization code." This
code is delimited by the macros $DS_BGNINIT and $DS_ENDINIT. The
VDS will dispatch control to this code at the beginning of each
program subpass, before calling any of the

3.5.1

tests.

Format Of The Initialization Code

The format of the

diagnostic

initialization

code

depends

whether

the

will

Dbe

program performs serial testing or parallel testing of

‘the units (see Chapter 1l).

For serial testing, one unit

initialized each time the initialization code is executed. The
VDS will dispatch control to each selected test and then call the
that the next wunit may be
so
again
code
initialization
the
of
each execution
testing,
parallel
For
ed.
initializ
ed.
initialization code should cause all wunits to be initializ

When the VDS calls the tests, all units will be

tested

once.

the VDS itself does not operate any differently when
that
(Note
The
‘testing.
instead of serial
parallel testing is occurring
initialization code determines the type of testing to be performed
testing, or
by initializing only one device at a time for serial
all devices at once for parallel

3.5.2

testing.)

Services Used By The Initialization Code

1initialization
important in the
to the
p-table
a
of
address
the
pass
This macro will
code.
device
the
wuse
then
will
program
The
diagnostic program.
parameters stored in the p-table to determine how to reference the
The $DS GPHARD service is very

device.

(P-tables are discussed in Section 3.2).

initializing a unit
programs,
(standalone mode)
For level 3
get a unit's p-table
to
macro
GPHARD
$DS
the
g
executin
involves
to initialize
macro
NNEL
$DS_CHA
the
ng
executi
address, and then
may also be
macro
SETMAP
$DS
The
the appropriate bus adapter.
and
CHANNEL
$DS
the
(Both
code.
zation
initiali
used in the
tests.)
actual
the
within
used
be
also
may
macros
$DS_SETMAP

,/"“‘\\

THE

For

STRUCTURE

level

consist

p-table

(user

indicates

that

3.5.3

At
be

the

testable

with

the

obtain

SASSIGN

allocated

the

system

(see

will

unit's

service.

service)
is
the
device

Section

3.2.2).

the

Guide)

testable
Mnemonics

by
List

VDS

the

number

User's

the

$DS
will

loop
unit

and

comparing

than

return

Thus

with

the

the
diagnostic program
- see Section 3.3.4).

GPHARD macro

greater

status.

logical

1indicates

written

to handle
an
unspecified
of units will vary from system
the VDS determines the
number
of
units
using the list of SELECTed units (see the

1is

error

the

REPEAT-UNTIL

increments
value

must

value

units,

routine

initialization

the
S$SALLOCATE
system
p-table
descriptor
for

must

since

types
Device

this

contain

unit

GPHARD macro
to

issuing

the

Supervisor

device
in the
If

code

arguments

number."

run time,
tested by

Diagnostic

list
of
contained

$DS

PROGRAM

Units

units,

to system.
that
<can

VAX

VDS

DIAGNOSTIC

programs,

(using

the device

initialization

SUPERVISOR

the

followed

the

Logical

number

VAX

mode)

allocation

requested

The

executing

address,

- Device

from

the

"logical

actual

the

(as
One
unit

number

SDS_GPHARD

1initialization

service

<code

can

that executes the $DS GPHARD macro and
number until the macro's return status

error.

It is important to note that the "logical unit number"
the SDS GPHARD macro does not refer to the actual unit

argument to
number of a

hardware configuration.
For
example,
consider
a
program
that
tests disks.
Suppose this program is run on a system that has two
controllers,

each possessing one
drive.
Each
of
these
drives
be
unit
@ on its respective controller.
The logical unit
associated with the unit would depend on the order in which

could
number
the

drives

executed,

were

the

(specifically,

associated

field

with

3.5.4

Program

When

$SDS_GPHARD

numbered

must

signal

VDS

the

And

that

the

logical

DRIVE)

$DS

GPHARD

service

has

unit

number

can

examined

determine

error

status,

has

been

one

program

used

for

which

number.

The Initialization

wunit

VDS

Once

the

HPSB

returns

macro

service

for

logical unit

Passes

1logical

SDS_ENDPASS

attached.

p-table

tested,

this

pass

unit

has

been

Code

indicating
the
highest
the initialization code
has

purpose.

been

This

completed.

macro

will

The

call

that

will update the count of
passes
executed
and
1if
the number of passes requested by the user has
If so, the program's summary routine (see
Section
cleanup code (see Section 3.6) will be executed, and the

check
to
see
been executed.

3.7)

and

VDS

command

control
code,
new

which

program

line

interpreter

returned

will be
called.
Otherwise
program
the diagnostic program's initialization

can

reset

the

pass

can

begin..

logical

unit

number

zero

that

THE STRUCTURE OF A VAX SUPERVISOR DIAGNOSTIC PROGRAM
Two other macros useful in the initialization code are

$SDS_BPASS(

and $SDS BNPASS#. These macros are used to cause program branching
depending on whether or not the first program pass 1is being
executed. It is often necessary to perform special initialization
For example,
the first time the initialization code is executed.
the location containing the number of the next logical unit to be
tested must be initialized the first time through the code.
Another example of a function that should only be performed the
"volume
first time the initialization code 1is executed 1is
(see Section 5.6.2). These macros are discussed in
verification"
Section 3.11, Conditional and Unconditional Branching.
3.5.5

The

1Initialization Code Examples

are

following

initialization code.

examples

program

steps

e Testing:
for Serial
Initialization Cod
IF

PASS

THEN

BEGIN

Program initialization

ALLOCATE BUFFERS
LOGICAL UNIT NUMBER=0

END

ELSE

INCREMENT LOGICAL_UNIT;NUMBER

ALL

UNITS

DONE

THEN

BEGIN

! End of
CALL $DS

pass
ENDPASS

LOGICAL UNIT NUMBER=0
END

Per—-pass code

CALL $DS_GPHARD
ASSIGN CHANNEL
CLEAR BUFFERS
CLEAR COUNTERS

needed

in
|

THE

STRUCTURE

Initialization
IF

Code
PASS

VAX

for

SUPERVISOR

Parallel

DIAGNOSTIC

PROGRAM

Testing:

THEN

BEGIN

Program

ALLOCATE

initialization
BUFFERS

END

ELSE
BEGIN

! End of
CALL $DS
LOGICAL

pass

ENDPASS

END

UNIT

NUMBER=0

REPEAT

$SDS GPHARD
ASSTIGN CHANNEL
INCREMENT

UNTIL

ALL

CLEAR

BUFFERS

CLEAR

COUNTERS

3.6

CLEANUP CODE

When

all

means

testing

for

LOGICAL

has

that

cleanup

code

will

program

pass

The

last

The

diagnostic

macro

has

detected

The

issues

the

been

when

VDS's

1is

under

the
a

ABORT

must

the

program

—

Chapter

with

4).

aborted
no

user

because
present

for

program,

following

This

failure

command.

exception condition occurs and is handled
by
last
chance
condition
handler
(see
Section
Condition Handling).
The

known,

$DS_ABORT macro.

catastrophic

executed

provided

the
diagnostic
$DS_ENDCLEAN.

program.
the

there
1left

completed.

executes

wused

1is

code"

executed

program

should

user

completed,
device

state.
The "cleanup
This
code
resides
in
macros $DS BGNCLEAN and

circumstances.

been
the

static

this
purpose.
delimited by the

UNIT NUMBER

DONE

device

guaranteeing

initialized,

The

UNITS

a
and

$DS
no

ASKxxxx

default

the

VDS

3.14.5,

macro

was

response

(see

THE STRUCTURE OF A VAX SUPERVISOR DIAGNOSTIC PROGRAM
Cleanup code should perform the following functions.
Disable all device and adapter interrupts.
if

Deassign channels,

in user mode.

Deallocate memory buffers.
Cancel

3.7

timers.

SUMMARY ROUTINE

The "summary routine" is an optional portion of the diagnostic
If included, it is wused to display on the user's
program.
Summary
terminal a summary of the program's execution history.
m
perfor
that
ms
progra
in
ded
inclu
be
routines are most likely to
since
times,
on
executi
long
have
many repetitive functions and/or
The
these program are likely to compile 1large error counts. 1last
the
of
end
the
at
VDS
the
summary routine will be called by
program pass (unless the user has inhibited the display with the.
VAX Diagnostic Supervisor User's Guide)
the
see
IES flag;
the SUMMARY command

routine

will be executed when the user issues

(see the User's Guide).

When the SUMMARY command is issued, the VDS provides a generalized
summary message whether or not the diagnostic program includes a
name and the
summary routine. This message indicates the programdiscus
ses error
3.9
n
(Sectio
d
reporte
number of errors that were
reporting).

An example of the message is as follows:

Summary of EVRAD - LEVEL 2 DISK FUNCTIONAL TEST» Rev 1.13
i1 erodrzm detected error (1 Hard, 0 Softy O Sustem:s 0 Device).
O Supervisor detected errors.

program, the
If a summary routine is included in the diagnostic with
the above
yed
displa
1is
ne
‘routi
that
message generated by
|
~

message.

The

summary

routine

delimited

the

$DS_BGNSUMMARY

and

All messages displayed with the summary
$DS_ENDSUMMARY macros.
routine must be printed by using the $DS_PRINTS macro.

Typically, the routine will contain code to display such runtime
the total numbers of read transfers, write
as
statistics
been detected
transfers, read errors, and write errors that have releva
nt to the
ation
inform
other
Any
on each unit being tested.
te set
separa
A
yed.
displa
be
also
type of device being tested may
these
store
to
useful
is
It
of totals must be kept for each unit.
sets of

totals

1in

one

1large

data

area

within

delimited by the $DS BGNSTAT and $DS_ENDSTAT macros.

the

program,

the

Additionally,

THE

3.8

STRUCTURE

TESTS,

3.8.1
All

SUBTESTS,

VAX

SUPERVISOR DIAGNOSTIC

PROGRAM

AND SECTIONS

Tests

diagnostic

"tests."

programs

contain
one
or
consists of code that

test

UUT.

more
(usually
several)
examines a portion of the

If the diagnostic program is a logic test (see
Chapter
1),
test should be designed to check a subset of the
UUT's logic.
If the program is a function test (see Chapte
r 1), then each
test
will
check
a
subset
of
the total functionality of the device.
Specific design, content, and number
of
tests
are
the
program
designer's
decision
of
what
is
appropriate
for
a particular
device.

each

Each

test

must

be free-standing.

test

must

Thus,

not

any

group

combinations

several

Segment

depend

and

tests

may

the

tests

must

proper

require

made

into

test

delimited

Sometimes

may

execution

executable

any

common
a

segment

global

all

code,

routine

called

placed

the

in
a
boundaries

$DS

BGNTEST

other

test.

possible

routines should
be
diagnostic program, outside

P— \\\

is,

execution

sequences.

Global

BEach

That

this
by

common

each

test.

separate

of
and

any

area
of
the
particular test.

SDS_ENDTEST macros.

be desirable to execute the same test
repeatedly,
different set of input arguments each
time.
This may
be accomplished by grouping the various
sets
of
input
arguments
together and delimiting them with the
$DS BGNDATA and $DS ENDDATA

but

wusing

macros.

Code

When

within

this

the

test

done,

the

once

before

VDS

for

will

every

automatically

set

execute

arguments

going on to the next test.
From the user's point
this repeated execution of the code within
the test will
be one execution of the test.

3.8.2
Tests

the

specified

view,

appear

Subtests
should

small

subtest must be
The
S$DS_BGNSUB

subtest.

composed

section

delimited

macro

Subtests

are

one

code
by

that

"subtests."TM

performs

one

the

$DS BGNSUB and
automatically
assigns

numbered

from

for

subtest

function.

$DS

Each

ENDSUB

macros.

number
each test,

to each
where N

—i

is
the total number of subtests within the
test.
Subtests cannot
be nested.
It is not leto
ga
branc
l
h from one subtest to
another
using
GOTO-type
instructions.
Subtests
may be either executed
Sequentially

illustrates

legal

called

and

from

illegal

higher-level

program

flow

routine.

using

Figure

subtests.

3-5

1 38V .. acnH#sNog~ sas
.

dNsSanN3a sads dns aN3 sas
c#

gNsSAN3a Sds

THE STRUCTURE OF A VAX SUPERVISOR DIAGNOSTIC PROGRAM

3-30

THE

STRUCTURE

VAX

SUPERVISOR

DIAGNOSTIC

If several tests require the use of the
within
the
subtest
(NOT including the

macros)

can

area

the

each

diagnostic

subtest

Subtests
@

placed

useful

They

provide

small

command

the

option

VAX

Diagnostic

"section"

the

test.

cause

and

the

1looping

the

Sections

program

user

can

execute

can

use

the

program

user

subtest.

for

errors.

particular

User's

Then

loop-on-error

Looping,

diagnostic

including

separate

test.

looping

The

Supervisor

group

the

tests.

program

Certaln section of
assigned
to
that

the

user

specify

The

programmer

needing

performing

subtest,

Refer

VDS
Dbe
with

the

Guide.

the

program

wish

run

belong

should

Sections

are

macros,

and

set

any

are

the

consider

and

associated

defined

user

number,

are

the

test

section

The

which

create
of

string

sections

for
the
specifies that a
all

tests
frees the

numbers

manually.

groups

names,

and

programmer's

groups

section

for

using

the
section

name(s)

These

macros

indicate

with

which

sections.

the
|

and

of
but

user

might

test

set.

$DS SECDEF

arguments

VDS

tests

purposes
option,

tests

that

SDS_SECTION

the

This

sections.

includin
the
g

5DS_BGNTEST macro.

should
be

long

assign

number

defined

functions.

program's

wuser.

program is to be executed,
section are automatically run.

similar

particular

may

which
a

the

3.10,

and

Sections

convenience

of
to

Section

subroutine.

for

means

language

the

Dboundaries

boundaries

portion

executed

3.8.3

call

placed

the
code
$DS_ENDSUB

particular

reasons:

loop

any

following

Refer

discussion
of

the

1loop

facility.

can

code

same
subtest,
SDS_BGNSUB and

subroutine

the

for

define

global

outside

requiring

are

program,

PROGRAM

which

the

tests

THE STRUCTURE OF A VAX SUPERVISOR DIAGNOSTIC PROGRAM

The

contents

are generally specified by the program's user community.

However,

Every program has a default section called DEFAULT.

this

section depend on the particular program application and

no . test within the default section can require any sort of manual
intervention, such as altering switch positions, adding cables,
and

on.

The

default section MAY ask for keyboard responses

using the $DS ASKxxxx macros (see Section 3.12.2.2, Prompting the
User), but all $DS ASKxxxx macros included in the default section
MUST provide default responses. This will ensure that the default
section will execute to completion if the VDS control flag
OPERATOR is clear, indicating that no operator (user)

1is present.

manual
require
program
the diagnostic
If any tests 1in
section.
one
in
together
grouped
be
must
tests
these
intervention,
The manual section MUST
This section should be called MANUAL.
by using the SDS BOPER or
r
operato
test for the presence of an

$DS BNOPER macro (see Section 3.11, Conditional and Unconditional
If an operator 1is not present, each test in this
Branching) .
section must use the $DS_ABORT macro.

3.9

REPORTING ERRORS

The VDS provides extensive capabilities, via macro calls, for
reporting detected error conditions. All error conditions MUST be
Error macros have the
reported by using the VDS macro calls.
|
this section.
in
later
ed
indicat
as
format $DS_ERRxXxx,
3.9.1

Error Message Formats

The macrosS call VDS services that will cause error messages to

displayed on the user's terminal. Error messages are divided into
three sections, or "levels." This is so users can use VDS control
flags to select or inhibit the display of all or part of a

message, as discussed

in Section 3.9.2.

The first level is referred to as the "message header." Part of
this header 1is generated automatically by the VDS and identifies
The rest of the
the current test, subtest, unit, and error.
programmer as an
the
by
d
specifie
message
a
header consists of
argument to the $DS ERRxxxx macro.

This last part of the

is a short statement identifying the type of error.

The second level is provided by the programmer via the

message

$DS_PRINTB

1is used to provide a clear statement of what
particular register's contents
the error is.
as expected, this level would be
not
be
to
found
are tested and
used to display the expected and actual contents of the register.

macro.

This

level

For example, if a

3-32

THE

STRUCTURE

The third level, also
using
the $DS_PRINTX

including

such

vs.

send

dumping

The

out

and

referred
an

and

message

the

"error

the

reporting

will

(first

specifying

levels

routine

VDS

header

individual

Example

DIAGNOSTIC

the
be a

PRINTX macros

message

reporting

($DS_ERRxxxx),

Details

provided by
macro), can

$DS

third

error

the

SUPERVISOR

PROGRAM

programmer
(this
time
by
detailed error description,

variable data as device register dumps and
received
data
patterns.
This
1level is
large amounts of auxiliary information.

$DS_PRINTB

second

VAX

error

are

the

routine
been

for
|

to generate

When

passed

the
has

used

contained

routine."
1is

cause

level)

that

are

buffers
used

the

subroutine

address
error

macro

executed

after

displayed.

messages

are given in the
description
(SDS_ERRxxxx)
in Chapter 4.

macros

3-6

shows a typical error message.
In this
example,
the
first three lines comprise the message header.
The second half of
the third line was specified by the programmer;
the rest
of
the
header
(plus
the
1last line of the message) was generated by the
VDS.
The remaining portions of the message were
generated
by
an

error

reporting

macro

would

XXXXKKKkKk

ECKAX

Fass

1»

test

Hard

error

routine.

used

VAX

number

EXFECTEDN!

CONTINUE

ACTUAL
S
XXXXXXX%

flag

racket

hard

Example

butes
error

the

3-7 illustrates

S$DS_PRINTX
three-line

last

part

should

example,

CFU Cluster

4-MAR-1983

Attempting

only

reporting

the

$DS

routine.

Exerciser

- 4.0

PRINTB
-

********

09:04:30.04

initialize

TUS8

controller.

received.
i
bedirnning
number

3-6

macros

error

the

message

this
1is a
belongs
to

0000EAQO

XKXEKXKKK KX

should

displayed using

Sample

header

service.
Since
information,
it

this
error

received,

Example

and

error

KAO!

butes

00000092(X)
End

testing

Incorrect

Unrecognizable

the

11/750~specifi¢

subtest

while

within

Error

message

used.

which

The

be displayed
displays

Message

using

the

both

first

SDSPRINTB

1line

following
$DS PRINTB.
The

‘parameters

fairly
long
1list
the
¢third
message
$DS PRINTX.
-

of
level
|

$QIO

auxiliary
and hence

THE STRUCTURE OF A VAX SUPERVISOR DIAGNOSTIC PROGRAM

YkkkEk FUYERS - UAX PBue Irnterzotion Progsram - Sl KEXKEKK
Foos 1y subtest 1

osrror S5 F-HAY-83 1410535129.146

Susten fetzl error while testing TTGLY ERROR ONM IO COMPLETION

ERROR

ATTEMFTING

WRITE

OGOOGGIACTX)
00G00050CH)

GIQ.I0SE]

O204EZBECX)

GTOLASTATRS

proLel
FIO_F23
RIDF3S
N 0 S
JEI R S
RIN.F&L

104 WRITEFBELE FUNCTION
TSk ARDRESS

;

ADNRESES OF AGT

QOON1I0&EY (X))

JOO040100X)
GOo00Q05 (X))
QOOGOQS0O0 (X))
GOOQGOG00 (X))
DOO00000 0K
GOGAER QG LK

: 1
i P2
s F3
P4
: FEH
s Pa

of device fatsl
Example

3.9.2

EVENT FLAG #
QI CHAMMEL #

OD04ESI0 R

BRI ASTRFRMS

Fro

MBh

X))
2000GG0E

RIDFUNCT

HkELEE

BIOERFHZ
AIC_CHA&NT

7TTG1:

NOFRIV
WERE!
it >

IO COMPLETION STATUS WaG:
JTTH1 QIO RLOCK FARAMETERS

3-7

s ValUE OF asST FARAMETER
ARG
oarRG
ARG
ARG
ARG
ARG

VALUE
VALUE
VALUE
VALUE
VALUE
VALUE

esrror number 5 KEEEXE
Sample

Error Message

VDS Control Flags Associated With Error Reporting

Several VDS control flags are associated with error
1IE2, HALT, and LOOP.
IE2,
These flags are IE1l,
Guide for a complete
User's
sor
Supervi
VAX Diagnostic
of VDS control

reporting.
(See the
discussion

flags.)

If
The IE1, IE2, and IE3 flags control error mesSsage displays.
displayed. If
the user sets the IE3 flag, message level 3 is notnot
displayed.
are
3
and
2
levels
es
messag
the IE2 flag is set,
error
Setting

the

IE3 flag will inhibit displaying of the entire

message.

If the user has set the VDS control flag HALT to activate
halt-on-error, the VDS will stop execution of the diagnostic
If the VDS
program after the error message has been printed.
executing a
begin
will
VDS
the
set,
control flag LOOP has been
(see
d
execute
been
has
e
messag
program loop after the error
Section

3.10,

Looping).

THE

3.9.3

STRUCTURE
OF A

Error

VAX SUPERVISOR

conditions

are

divided

Classes

"preparation

are

macro

"device-fatal

Preparation
They

properly

"prepared"

refer

The

program

writing

may

3.9.3.2

Soft

Errors

from.

that

this

user,

but

the

could

skip

issued

- A

soft
it

that

finds

tests

the

unit

using

the

point

error

diagnostic

error

can
be
example

write-check

the

maximum

macro

can

3.9.3.3

has

not

error.

require

ERRPREP
the

macro.

diagnostic

potentially

can

may

the

away

even

operating
reported

flag

from

error

might

writing

data

soft

when

all

recovered

that

the

a
not
the
device.)
program,
the error

use

only

Hard

when

hard

operation

being

disk

reporting

issued

Errors

from.

might

reached,

error

(see

below)

recovered

user

be reported and the operation reexecuted.
However,
there
generally
a maximum number of retries that should be allowed.

declared.

The

the

should
If

that

medium.
(It may be the medium that is bad, and
When a soft error is detected by the diagnostic

important

error

drive

$DS

not

disk

within

that

has

example,

altogether.

which

would

program

or
not
they
completed.
An

one

hardware

user

preparation

repeated.

probably

errors,"”

that

the

their

error

not

For

declare

any

are

program

code.

is,

from

the

program

those

five

"hard

errors

require

can

The

errors,"

testing.

may
it

class.

errors."

which

only

detected

occurrence

run

type

errors
whether
operation can be

the

drive,

cleanup

"soft

for

declared

That

each

Preparation

UUT

user.

the

program

are

except

system

case

Pprogram

operation

then

UUT,

errors

macro

recovered

depending

for

"system-fatal

Errors

the

could

the

Preparation
This

classes,

five

errors,"

the

write-enabled

into

provided

and

diagnostic

write—-enabled
not

errors,"

faults.
particular

PROGRAM

Types

severity.

3.9.3.1

DIAGNOSTIC

- A

from

seek

hard

error.

soft

within

error

That
1is,
it
performed cannot

should

then

1is

A hard

an operation

error

tests

1is

SDS_ERRSOFT.

(see

Section

one

that

error so
completed.

error

should

This

3.8.1).

cannot

serious

Such

also

that

the

error

declared

detected
a
soft
error
and
the
operation
was
unsuccessfully several times.
If, for example, a routine
performing write operations on a disk detect
ed several write-check
retried

errors

(which

declared.

are

soft

errors),

then

hard

error

3-35

should

THE STRUCTURE OF A VAX SUPERVISOR DIAGNOSTIC PROGRAM

This
Hard errors are reported by using the §$DS_ERRHARD macro.
.
3.8.1)
n
Sectio
(see
tests
within
macro can only be issued from
3.9.3.4
detects

program
Device-Fatal Errors - Sometimes a diagnostic
ess to
pointl
is
it
that
UUT
a
on
so many hard errors

testing

Perhaps there is something so
continue testing the device.
that it cannot be tested at all.
device
the
seriously wrong with
In
test a nonexistent unit.
to
made
been
Or maybe an attempt has
e a device-fatal
any of these cases it is appropriate to declar
m intends to
progra
the
that
user
error, which indicates to the
Whenever a
on.
questi
in
UUT
the
attempting to test
stop
performing serial
device-fatal error is declared 1in a progratm test
(by issuing the
curren
the
leave
testing, the program should
be set to
could
flag
al
intern
an
,
$DS_EXIT macro). Additionally
test could
Each
ed.
declar
been
has
indicate that a fatal error
macro.
_EXIT
$DS
the
issue
ately
immedi
check this flag and, if set,
this
(for
unit
the
on
med
perfor
be
would
That way no more testing
allow
to
flag
the
reset
would
pass). The initialization code
the

next unit.

This
The macro for declaring device-fatal errors 1is $SDS ERRDEV. progra
m
stic
diagno
a
within
re
anywhe
from
macro may be issued
except the cleanup code.

3.9.3.5 System—-Fatal Errors - A system-fatal error 1is one SO
at all. In
serious that the diagnostic program cannot be executed
ed if
declar
be
should
error
l
—-fata
system
a
user mode, for example,
ary to
the user's process does not possess VMS privileges mnecess
as
(such
progra
stic
diagno
the
by
ed
perform functions requir

to the
PHYSIO for a program that uses physical I/0 -- refer -fatal
system
a
time
Any
.)
Manual
nce
VAX/VMS System Services Refere
orror is declared, the diagnostic program should subsequently
execute the $DS ABORT macro to abort program execution.

The macro for system-fatal errors 1is $DS ERRSYS.

issued

from

cleanup code.

3.1¢

anywhere

This

macro

may

within a diagnostic program except the

LOOPING

to repair
The VDS facility that 1is probably the most useful often
called
loops,
am
Progr
ng.
loopi
technicians 1is program
in tracing signals
"scope loops," because they aid the technician
sets the VDS
with an oscilloscope, are enabled when the technician
VAX Diagnostic Supervisor User's
control flag LOOP (see the
Once this flag has been set, a loop will begin executing
Guide).
any time an error macro ($DS_ERRxXxxX)

3-36

1is issued.

THE

STRUCTURE

3.10.1

Defining

Although
programmer

loop

these

define

will

have

will

After

after

The

upper

the

the
is

again

cycle

through

the

execute

program

even

loop

perpetually

are

the

loops.

and

upper

error

macro.

macro

<call,

initiated
of

the

bound.

Within

Whenever

an error

been

For

continues

VDS

causes

returns
the

call.

the

point

execution

until

the

program

control

until

the

bound.

program

reached,

started,

may

continues

whether

not

the

error

may

through
not

the

defined

typed

the

explicitly

values

the

will

user's

the

subtest

the

error

subsequent

For

default

lower bound
$DS_BGNTEST and $DS

containing subtests,
the
respectively, the SDS_BGNSUB

containing

condition.

the

error

macro

terminal.

programmer.

used.

tests

report

means that the loop
will
<continue
condition disappears.
1In fact, once
initiated, it
will
continue
to
execute

default

are,

execution

executed

This

control-C

then

bounds

error

not contain subtests,
loops in that test are
upper

VDS

repeated.

the

may

the

program,

issued.

loop.

diagnostic

lower

again

macro

has

not,

respectively.

diagnostic

cycle

until

boundaries

macros

the

reached.

bounf,

the

loop's

once

the

program

bound

passes

and-

responsibility

one

error

bound

the

Execution

The

the

upper

the

for

loops

1is

error

diagnostic

From

that

they

PROGRAM

program

bound

least

the

directly

macro,

does

control

érror

Loop

boundaries

lower

servicing

macro

the

VDS,

program

upper

DIAGNOSTIC

serviced with the LOOP flag set, the VDS begins executio
n
loop.
Loop execution proceeds in the following sequence.

branch

/A\

the

loop's

SUPERVISOR

the

Note

VAX

Loop Boundaries

bounds

macro

actual execution

automatically

Each

test

that

and upper bound
ENDTEST macros,
default

and

that

lower
$DS_ENDSUB

was

executed

THE STRUCTURE OF A VAX SUPERVISOR DIAGNOSTIC PROGRAM

The programmer can explicitly define loop boundaries by using the
$DS_CKLOOP macro. This macro is placed after an error macro, bhut
before the next $DS ENDSUB or $DS ENDTEST. If the the $DS_CKLOOP

macro

contained

within

a test that consists of subtests, it

must be placed within the bounds of a subtest. The macro takes as
an argument the name of a program label. This label must be
located before the error macro, but after the most recent
The result is a loop whose lower bound
$DS_BGNSUB or $DS_BGNTEST.

is the label and whose upper bound is the $DS CKLOOP macro itself.

Figure 3-6 illustrates the various 1loop boundaries.
$DS_BGNTEST

$DS_BGNTEST

$DS_BGNTEST )

$DS_ERRxxxx &LOOP

$DS_BGNSUB

$DS_ENDSUB

'$DS_BGNSUB |

$DS_BGNSUB

label:

$DS_ ERRxxxx
LOOP

$DS_ERRxxxx

LOOP

$DS_CKLOOP label

$DS_ENSUB

$DS_ENDSUB J

$DS_ENDTEST

$DS_ENDTEST
TK-10521

Figure

3.10.2

3-6

Examples

Loop Boundaries

Characteristics Of Loops

Each loop should generate a minimum amount
'Loops should be small.
of electrical activity on the UUT. The less activity that is
occurring, the easier it will be for the technician to trace
relevant signals.

There 1s no
Loops must be made up of code that is repeatable.
that loop
within
point 1in creating a program loop unless the code
the same
cause
must
The code
can be executed repeatedly.
. For
executed
1is
electrical activity to occur each time it

example, a loop that just sets a bit is useless, because the bit
will be set the first time through the loop, and subsequent passes
through the loop will cause no changes to take place. A loop that

sets and then clears the bit would be appropriate.

THE

STRUCTURE

order

necessary

first

make
to

VAX

loop's

alter

SUPERVISOR

code

the

DIAGNOSTIC

repeatable,

program

flow

pass

PROGRAM

may

within

occasionally

the

loop

after

be
the

through the loop.
The $DS_INLOOP macro can be used
to
determine
if a loop is being executed.
Branching within the loop
can be performed depending on the return status
from
this
macro.
This
macro is
wuseful
in
places
where
severe
errors
occur.
Ordinarily the programmer may want to abort the
program (using the

$DS ABORT

macro)

it may be desirable

the

loop

such

case.

branch around

continue.

Caution
should
be
practiced
containing
$DS_CKLOOP macros.

the

$DS_CKLOOP macro,

suppose a

loop

loop's upper
loop
tests

being

the

branching

important

loop

could

executed,

error

past

with

does not

loop

$DS ABORT macro

when

bound.
Suppose now that a
for a hard error condition

*DS_ERRHARD macro
of

However,

within
not

broken.

present,

subtests
branch past

For

example,

SDS _CKLOOP macro

section

and

allow

the

code within the
branches around a

then

exist.

the

branch

goes

the $DS_CKLOOP macro, the loop will be broken.
TIllustrations
proper and improper branching within loops are
shown in
Figure

PROPER BRANCHING
WITHIN A LOOP

IMPROPER BRANCHING
WITHIN A LOOP

label1:

[]

[}

[]

TSTL
BNEQ
®

ERRBITS
NO_ERROR

TSTL

ERRBITS

BNEQ

NO_ERROR

[]

NO_ERROR:

$DS_CKLOOP

$DS_CKLOOP LABEL1

LABEL1

.
NO_ERROR:

TK-10522

Figure 3-7
3.10.3

Proper and Improper Branching Within Loops

Nesting

Loops

Loops whose
be
nested.

boundaries

3-8,

Figure

Example

contained

are defined with the $DS
3-17 illustrates nesting of

Fiqure
1loop

within

loop

1is

loop

and

loop

contained

3-39

are

CKLOOP

macro

loops.

contained

within

loop

and

may
Example
1.

loop

THE STRUCTURE OF A VAX SUPERVISOR DIAGNOSTIC PROGRAM

EXAMPLE B

EXAMPLE A

)

LABEL1:

)

LABEL1:

LABEL2:

LABEL3:

LOOF 2

error macro 2
$DS_CKLOOP LABEL?2

LOOP 1

'LABELS3:

error macro 3

LOOP 2

error macro 3

LOOP 1

$DS_CKLOOP LABEL3

LOOP 3

$DS_CKLOOP LABEL3

~error macro 1

LOOP3

$DS_CKLOOP LABEL1

error macro 2

$DS_CKLOOP LABEL?2

)

error macro 1

)

$DS_ CKLOOP LABEL1

TK-10523

Figure

3-8

Nesting

Loops

When loops are nested, the VDS always executes the

containing the issued error macro.
Example B,

loop 2 would be executed.

smallest

1loop

If error macro 2 was issued in

The VDS will always execute the loop containing the most recently
In Example A, sSuppose error macro l was
issued error macro.
issued. This would cause loop 1 to begin executing. Suppose at a
later point in time that error macro 2 was executed for the first
Then
time (perhaps because of an intermittent hardware failure).
loop 2 would begin execution and loop 1 would be forgotten.

3,10, 4

User-Specified'Looping

There is a method by which the user can request a loop to Dbe
executed even though an error macro has not been issued. The
the
/SUBTEST qualifier on the RUN and START commands (see
a
specify
to
used
be
VAX Diagnostic Supervisor User's Guide) can
the
When
occur.
to
subtest on which the user wishes 1looping

is reached, looping begins on that subtest.
specified subtest

programmer should keep

this

feature

designed.

3-40

mind

subtests

The

are

THE

3.11

STRUCTURE

VAX

SUPERVISOR

DIAGNOSTIC

PROGRAM

CONDITIONAL AND UNCONDITIONAL BRANCHING

The

VDS

provides

branching

within

$DS_BERROR,

The

several

the

services

the

error"

1immediately

macros

will
cue

The

"branch

used

services.

System

the

and

function

BNERROR

services

one

makes

branch
if

operator

macros
They

the
These

was

inverse

That is,

these

argument

are

system

that

the

same

$DS BCOMPLETE
is

source

macros

call

macros over
the

others

"no

error."

the

other

code.

branch

for

This

the

flag.

run

time
<can

mode.

For

the

is
is

some

service

the

operator
the

OPERATOR

not

diagnostic
flag

(see

Guide).
They
make
it
certain
segments
of
code,
is

not

QUICK

you

present.

"branch

selected

the

QUICK

flag

diagnostic

flag

not

program.

(see

create

the
User's
"quick mode" in

optionally

the

user

program pass that does not
perform
when the user is more interested

used

careful,

used

Determination

and

the
allow

"branch

User's

anywhere

fast
is

set"

used

than
be

excluded

requirements.

flag

mode

Quick mode provides a
thorough
testing and
macros

and

anywhere

skip

user

macros

program.

QUICK

present"

setting

sets

included

there

QUICK
can

your

quick

and

incomplete"TM

that

sense

while

setting

whether

macros

fast

the

execute

"branch

Supervisor

be
The

branch.

macros

cue

The

set

wused

$DS_BNQUICK

They cue
Guide).

R@),

$DS BNCOMPLETE

$DS_BQUICK,

set"

the

can

Diagnostic

depending

should

can

services.

$DS_BNOPER

"branch

VAX
possible

(in

"readability"

the

macros

"branch

and

appropriate

program.

conditional

system

indication

successfully,"

The

error"

The

program

"completed

present”

no
call

following

Choosing

matter

$DS_BOPER,

that

$DS_BNERROR macros.

$DS

$DS BERROR.
Ssimply

status

status.

complete"
immediately

"branch

macros

and

equivalent

facilitate

$DS_BNCOMPLETE

Their

°DS_BERROR

that

which

$DS_BCOMPLETE,

and

after

return
on

address

also

program.

$DS BNERROR

"branch if

used

macros

diagnostic

skip

what

complete

around

segments

fault

segments

quick mode depends on

3-41

code

detection.
of

code

should

specific

program

THE STRUCTURE OF A VAX SUPERVISOR DIAGNOSTIC PROGRAM
$DS_BPASS@,

$DS_BNPASSO

h not pass g"
The "branch if pass 0" and "branc1f

macros

can

be used when it is necessary to cause program flow to change
depending on whether or not the current program DpasSs is thea
first

The

one.

macros call a system service that returns

status indication (in R@) of whether or not the

current

pass

is the first one, then an appropriate branch is generated.
program's
the
in
used
These macros are only to Dbe
initialization code.

$DS_ESCAPE

The $DS ESCAPE macro is used to exit from a test or subtest 1if
an error has been detected within that test or subtest. It is
code
used when it is pointless to execute the rest of the
For
d.
detecte
was
error
the
after
within the test or subtest
disk
a
on
tests
write
ing
execut
in
point
example, there is no
if it has been discovered that the disk 1is write-protected and
a

user

not

present.

If an error reporting macro ($DS_ERRxxxx) has been issued from

within the current subtest or test, then issuing an SDS ESCAPE
macro will cause program control to pass to the end of the
subtest

test.

$DS_EXIT

The $DS EXIT macro provides for unconditional branching to the
end of a test, a subtest, an interrupt service routine, or the
conjunction with
summary routine. This macro is often used infollowi
ng example:
the conditional branching macros, as in the
$DS_BGNTEST

- 108:

SDS_BOPER 10%
$SDS_EXIT TEST
:

'$DS

ENDTEST

THE

3.12

STRUCTURE

VAX

SUPERVISOR

DIAGNOSTIC

PROGRAM

INPUT/OUTPUT

3.12.1

I/0 With

The

I/0

User

3.12.1.1

Unit

Under

Mode

Test

user

mode

(level

2R programs),

all

input/output operations must be accomplished by using the VMS $QIO
s ervice.
The details of performing I/0 operations with the
SQIO0
se rvice are described in the VAX/VMS I/0 User's Guide, which

system

MUST

read

Initiati ng

I/0

e ach

steps,

before

activity

which

Assigning
A

development

device

user

requires
channel

cannot

the

assignments
service.

has

VMS

system

service.

unless

channel

"assigned"

1linking

service

the

device

This

cleanup
the

program's

service

the

device

"allocated"

necessary

using

program
tested
(no

the

should

initialization

user.

device

request

should

linking

the

A
the

$ASSIGN
be

issued

code.

using
using

the
the

requested

device,
S$DASSGN
1in

the

device.

while
if

three

code.

diagnostic

the

the diagnostic program has finished
<channel
should
be
deassigned
by

Allocating

;

involving

When

service.

begun.

process

the

diagnostic

accomplished

This

program

from

program's

been

path

are

level

device.

referenced

Channel

system

’/""""%‘\_1

the

program

system

its

;

mode

use

"channel" is
a
data
diagnostic program.

the

being

1in

UUT.

loaded

(nonscratch)

manner,

device

tested),

diagnostic

program

placed

will need exclusive
other users allowed

requires

the

device

allocation

then

the

program.
a

device must
Allocation is

scratch

medium

program

can

use

currently

medium

1iIn

not

that

use
of
the
to reference

necessary.

the

nondesructive

STRUCTURE

VAX SUPERVISOR

Device
allocation
1is
diagnostic
program.
issued by the VDS (via

DIAGNOSTIC

PROGRAM

not
performed
directly
by
the
Instead,
the allocation request is
when
the SALLOCATE system service)

the
(see
command
SELECT
VDS
the
types
user
the
VDS
The
Guide).
User's
Supervisor
VAX Diagnostic
the device by
allocate
not to
or
whether
determines
p-table (see
device's
the HPSM ALLOC bit in the
checking
is set (by
bit
this
If
Format).
©P-Table
3.2.1,
Section
the program developer who created the p-table
descriptor;
the
then
Descriptors),
P-Table
3.2.2,
Section
See
SALLOCATE service

requested.

allocated

because

has

else,

VDS

the

informs

the device

already been

the

allocated

cannot
to

someone

user.

An allocated
device
will
be
deallocated
(by the
VDS
a SDEALLOCATE service request) when the device 1is
issuing
DESELECTed

when

the

VDS

EXIT command

typed.

to
might have
program
diagnostic
An instance when the
deallocate a device is in the
and
allocate
specifically
VMS
to
referring
not
are
(We
case of error logging.
error
writes
program
2R
level
a
If
logging.)
error
system
allocate
logging data to a device, it MAY be necessary to
should
program
diagnostic
the
case
this
In
device.
the

use the S$ALLOCATE service of VMS within the initialization
cleanup code will have to use the SDEALLOCATE
The
code.
the
to
Refer
device.
the
deallocate
to
service
VAX/VMS

System

Queueing

I/0

Services

Reference

Manual.

requests.

Actual input/output operations are requested by using
the
$0I0
and
S$QIOW
system
services,
which
will place the
a
that
These services require
request in an I/0 queue.
set of parameters be passed to the service routine.
These
parameters specify the following types of information.

The channel number over which the data transfer is
take

place.

SASSIGN

is obtained

from

the

service.

The type of transaction desired.
This is indicated by
and is discussed below under "I/O
code"TM
a "function
Function

The channel number

Encoding.”

The method by which the program is to be notified that
Three methods are
the transaction has been completed.

available and are discussed below under "Synchronizing
I1/0

Completion.TM

THE

STRUCTURE

The

VAX

SUPERVISOR

address

information.

Diagnostic

I/0

DIAGNOSTIC

buffer

This buffer

PROGRAM

receive

is discussed under

diagnostic

"The S$QIO

Buffer.”

Function

Encoding

I/0 functions fall into three grdups, corresponding to

the

three

virtual).

I1/0

The

the

type

The

function

diagnostic

methods

(physical,

1logical,

type of function

to be used will

tested

device being

program

that

being

written

(refer

and

be performed by a

is
1indicated
by
passing
to
16-bit value having the format

the

and

depend
type

Chapter

2).

$QIO service

the
service routine a
illustrated
in
Figure

FUNCTION

MODIFIER

CODE
TK-10524

Figure

3-9

S$QI0 Function Code

and

Modifier

Fields

The "function code" is a six-bit field indicating
the
type
of I/0 operation to be performed. Some function
codes are device-independent, and others
are
devicedependent.
Table
3-1
contains
device-independent

function codes
three

Table

3-1

I/0

for

transfer

read

Device-Independent
Physical

I/O

I0$ READPBLK

I0S WRITEPBLK

and

write

functions

1in

the

modes.

Read

Logical

and Write

I/0

IOS READLBLK

1IOS WRITELBLK

Functions

Virtual

I/0

IOS_READVBLK
I0S

WRITEVBLK

Refer to the VAX/VMS I/0 User's Guide for
discussions
of the function codes available to individual devices.

3-45

THE STRUCTURE OF A VAX SUPERVISOR DIAGNOSTIC PROGRAM
The "function modifier" field is used
to
operation specified by the function code.

this

code,
be

field

can

and

the

$QI0 service will

performed

set

conjunction

IOS INHRETRY modifier

can

function

retries

1inhibit

with

alter

accordingly.

function

example,

with

when

the

For

used

modify
the
Bits within

the

IOS READVLBK

read

errors

are

encountered.

detailed
dicussion
of
I/0
function
with tables of all function codes and

Refer

the

encoding,
modifiers

along
that

are

VMS.

valid

for

VAX/VMS

each

I/0O

device

User's

supported

Synchronizing

I/0

Three

methods

exist

which

determine

that

I/0

can

The

the

desired

S$SQI0

Guide

for

Completion

method

for

event

service

the

diagnostic

request

has

determination

call.

The

three

been

program

completed.

indicated

methods

with

available

are

Waiting
It

possible

SQIO
(see

or
I/0

3.14.2)

has

can

specify,

$QIOW macros,

Section

when

Testing

status

I/0

address

the

that

argument

number

the

event

flag

set

system

service

The

diagnostic

completed.

(by using
specified flag
combination of

The

flag.

program

system
service)
wait
for
the
to be set.
(The SQIOW service is a
the $QI0 and SWAITFR services.)

block.
"I/O0O

status

block"

can

specified -as an argument to the $QIO macro.
When
this is done, the
S$QIO
service
will
cause
the
first
word
of
this
block
to
be loaded with a
status
code
when
the
I/0
operation
has
been
completed.
The
program can test the contents of
the block to
determine
the
status
of
the
1I/0
operation.
The
format
shown in Figure 3-140.

16
TRANSFER COUNT

I/0

0
STATUS

TK-10525

I/0 Status Block Format
3-46

block
|

DEVICE-DEPENDENT DATA

Figuré 3-1¢g

status

1is

‘THE STRUCTURE
OF A VAX SUPERVISOR

Refer

the

details

DIAGNOSTIC

VAX/VMS

about

the

AST

I/0

PROGRAM

User's

contents

Guide

the

for

1I/0 status

block.

Execution

routine.

It is possible to specify, as a $QIO argument, the
address
of an AST routine.
(ASTs -- asynchronous
system traps —-- are discussed in Section 3.14.3.)
If this is done, an
AST routine called)
been

completed.

completion

most
I1/0

The

$QIO

AST will be delivered (and
when
the
I/O0
operation
This

provides

efficient,

for

with

method

the

most

regards

the
has

determining

I/O

asynchronous
processor

(and

usage)

activity.

Diagnostic

Buffer

When a $QIO or SQIOW macro is issued, it
1is ©possible
to request the system service routine to load a buffer
with the contents of
the
device's
registers.
This
"diagnostic
buffer"
will be loaded if two conditions
are

met:

The

I/0

transfer

method

physical

(see

Chapter

2)
.

The

process

privilege
User's

request

programmer

possesses

(see

the

Command

the

VMS

Language

Guide).

the

system

service

load

buffer,

the

must:

Define

a buffer

area

within

‘program.
This
buffer
contain
the
<contents
registers.

" b.

"diagnostic"

VAX/VMS

must
of

be
all

the

1large
the

diagnostic

enough to
device's

Specify the address of this
buffer
as
the
"P6"
argument
to
the $QIO or SQIOW macro (see Chapter

When

the

contain

I/0

the

operation

final

has

completed,

contents

the

buffer

device

will

registers,

plus
additional
1information.
Generally
(but
not
always),
the
format of the buffer's contents will be
as

indicated

Figure

3-11.

STRUCTURE

OF A

VAX SUPERVISOR

DIAGNOSTIC

PROGRAM
TN

THE

OPERATION START TIME

IN 64-BIT FORMAT

OPERATION COMPLETION TIME
IN 64-BIT FORMAT

FINAL ERROR COUNTER CONTENTS

NUMBER OF DEVICE REGISTERS

DEVICE REGISTERS,

J.,

ONE PER LONGWORD

“TL' |

TK-10526

Figure

3-11

Typical

$QIO Diagnostic

Buffer

Format

Two
other
VMS
system
services
are
useful
to
diagnostic
programmers.
The
SGETCHN service will provide information about
the device attached
to
a
specific
channel.
This
information
consists
of
the "primary" and "secondary" device characteristics
as described in the VAX/VMS I/O User's Guide.
The SCANCEL
system
service
channel,

will
cancel
all
pending
I/0
requests
including those already in progress.

on a

specified

3.12.1.2
I/0 in Standalone Mode - In
standalone
mode
(level
3
©performed by direct reference of the device's
is
I/0
programs),
registers,
Thus routines to set up a device's control
registers.
service

its

contained

interrupts,

within

The diagnostic

channel

Because

<can

the

and

diagnostic

program must

be created

differences

set

check

for

error conditions must be

program.

the

transfer

inherent

bus

adapters

that

information across

the

bus

data

the buses.

adapters

the

various
VAX
processor
types,
the
VDS
provides facilities for
programmer
channel initialization that remove from the diagnostic
the
burden
of
dealing
with
processor-specific
details.
This
allows diagnostic programs to be automatically compatible with all
VAX processor

The

types.

$DS CHANNEL and

$DS_SETMAP services of

the

VDS

are

wused

The $DS CHANNEL service
data channels in standalone mode.
create
Depending
is used to initialize the MASSBUS and UNIBUS adapters.
service
the
macro,
on the parameters included with the $DS CHANNEL

will

Initialize
the adapter
the

adapter

Enable

disable

Provide

current

interrupts

adapter

status

//rn\\\

Clear

THE

STRUCTURE

Details are
in

Chapter

provided

VAX

SUPERVISOR

the

DIAGNOSTIC

description of

the

PROGRAM

$DS

CHANNEL

macro

The S$DS SETMAP service will set up the adapter's mapping reglsters
so
that
data
transfers will reference the desired areas of main
memory.
Details are provided in the description of the $DS SETMAP
macro

Chapter

The SDS_SHOCHAN'service provides automatic display on

the

user's

Interrupt
delimited

should
be
The address

terminal of a bus adapter's internal registers.
The configuration
register and the status register are always displayed.
If
error
conditions
exist,
additional
registers
will also be displayed.
This macro should be used whenever the $SDS CHANNEL system
service
detects an error condition.

service
by the

routines
1in
a
$DS BGNSERV and

of the interrupt service routine

diagnostic
program
$SDS_ENDSERV macros.

the

1is passed

$DS _CHANNEL

service.
The
VDS
has
an interrupt preprocessor that initially
receives control when an interrupt
occurs,
and
then dispatches

control

the

specified

interrupt

service

routine.

An interrupt service routine's function should be minimal, such as
disabling
further
1interrupts, making sure that the interrupt was
expected (arrived through the proper vector),
and
saving
device

status.

Error

service
should

reporting

routine,
report

Typical

with

one

unexpected

program

flow

should NOT be carried
exception;

interrupt

out

Clear
Set

when

using

interrupt

service

Code:

and

initialize

I/0

channel.

transfer.

Start watchdog timer.
Enable interrupts.
|
Clear

done

flag.

REPEAT

Test

UNTIL

done

flag.

flag

set

OR watchdog

timer

flnlshes.

set

THEN

cancel watchdog

ELSE

report

timeout

interrupt

routines

interrupts.

follows.
Main-Line

in an

service

tlmer,
error.

report

I/0

status

routine

1is

THE

STRUCTURE

Interrupt

Service

Disable
IF

set

ELSE

Set

VAX

SUPERVISOR

DIAGNOSTIC

PROGRAM

Routine:

interrupts.

unexpected

THEN

interrupt

error

save

done

(wrong

vector)

status

device

status.

flag.

Return.

the

information

$DS

Other

mode

interrupts

macros

useful

when

can

the

found

the

description

chapter.

performing

I/0

functions

standalone

are:

$DS

SETVEC

exception
ONLY

the
to

the

$DS

CLRVEC

had

been

with

the

Removes

address

the

VDS

Reinitializes

their

standard

$DS

SETVEC

$DS

PROBE

not

the

have

- Attempts

hardware

specified

address.
may

specified
a

interrupt

This

condition
the

macro

1loaded

the

(do

the

whatever

macro,

and

handler.

vectors

system

interrupt

been

not

and

may

This
be

contents

replaces

reset

control

(do

not

block

(SCB),

1if

several

exception vectors,

wvalues.

Useful

memory

macro

used.

access

(either

vector

$DS SETVEC

(VDS-defined)

macros

vectors

method by
which
SCB directly).

INITSCB

specified

from

contains all

address

I/0O

determine

device)

1is

whether

connected

it.

SDS SETIPL

(IPL)

specified

3.12.2

I/0 With

All

between

I/0

directly).

which

contents

which

SCB

placed

the
ONLY
clear the

$DS

Sets

wvector

method
by

reference

CHANNEL service

accomplished

Sets

The
a

the

processor's

User

VDS

priority

1level

terminal

must

Terminal

diagnostic

via

interrupt

value.

program

macros.

and

Macros

Displaying messages consisting
a combination of ASCII strings

Prompting the user for
storing the response

the

are

user's

provided

for:

of simple ASCII strings
and variable data

response,

and

then

receiving

and

THE

STRUCTURE

Displaying
mnemonic

VAX

the

SUPERVISOR

contents

each

DIAGNOSTIC

PROGRAM

and

assigning

bit

Determining the user's terminal

type and characteristics

3.12.2.1
Displaying Message Strings - Message strings
consisting
a combination of ASCII strings and data variables are displayed
by means of the "print"
macros.
This
set
of
macros
has
the
of

general

form

$DS

PRINTx.

macros,

known

SDS

SDS_PRINTS.

The

$DS_PRINTB

error

messages,
ERRxxxx).

messages

macros

(S$SDS

(see

the

keyed

the

$DS

and

for

summaries

The

macros

can

Using

also

WRITE

system

macro
a

service
by

macro

are

the

specifying

useful

are

service

such

messages

fact,

such

"format

statements

indicate

the

SFAO

will

The

method

same

the

service

format,

but

is
not

macros will both format and print the
possible (and occasionally desirable)

the

SFAO

service

and

then

display

macros.

for

this

names

assigned

with

macro

words

data,

printed.

This

displaying

macro,

the

information

vyou

string

bits

will read the register and
produce
which
bits
of
the
register
are
one

the address

using

VMS.

VDS.

data

address

with

are

PRINTF

user

strings,

Format

provided

The print
It is also

With

the

variables.

format

$DS

the

variable

and

displayed

contents

and

macros
the

message

the variables

print, a message.
desired message.

CVTREG.

the

strings

involves
1list

which

provided

SDS

display

ASCII

(B)

and

error

LOCKED.

0R0LOB0330300000

Another

ASCII

XOR:

the

one

simple

inhibit

The

error

Routines).

(B)

format

Summary

the

$DS_PRINTS

(B)

format

The

1011101010101010

provide

1010101010191010

the

using

3.7,

and

used

User's Guide)

EXPECTED:

used
also

used

reports.

with

used

RECEIVED:

statement”

SFAO

flags

Supervisor

four

PRINTF,

are only

SDS_PRINTX macros.

error

Section

used

are
SDS

conjunction

necessary

(see

combination

control

and

1is

there

PRINTX,

$DS PRINTX macros

used

VDS

PRINTB

are

DEVICE

They

are

The

is used when it
information
unrelated

used

and

SDS

VAX Diagnostic

macro

Specifically,

PRINTB,

specify

the

of mnemonics.

within

the

user

address

The

mnemonics
The

a
character
string
set.
This string can

macros.

macro

telling
then be
|

THE

STRUCTURE

A VAX SUPERVISOR

DIAGNOSTIC

Details on the print macros are in Chapter 4.

discussed

Reference

Manual.

Chapter

and

the

PROGRAM

The SFAO service is

VAX/VMS System Services
ke

to know the type and characteristics of the

is sometimes useful

user terminal.
For instance, you may want to format text displays
differently on a video terminal than on a hardcopy terminal.
The
type

and

characteristics.

3.12.2.2
which
common

may be used to determine the user terminal's

service

$SDS GETTERM

Prompting

it
1s
example

the User - There are occasionally instances

necessary
to solicit information from the user. A
is the case in which the program must, at a certain

point
in its execution, ask the user to perform an action such as
connecting a cable and to then type a response indicating that the
action
has
taken
place.
Also, there may be circumstances under
which it is necessary to obtain information about
the UUT
other
than
what
1s
contained
1in
the
p—-tables.
(It 1s important,
however, to TRY to place all device-specific
information
in
the
the
BEFORE
commands
ATTACH
in
specified
be
can
it
p-tables so that
diagnostic

program

started.)

All solicitation of user responses during the diagnostic program's
execution
must be made through the use of the $DS ASKxxxXX macros.

These macros allow the programmer to specify a prompting

message,

the
format in which the user's response is to be interpreted,
a storage area into which the response should be placed.
Specifically,

$DS ASKADR - Prompt

the
store

range

and

range

store

and

$DS _ASKVLD - Same as

‘to

specify

$DS ASKLGCL
response,

wuser
the

for

address

result.

within

$DS ASKDATA - Prompt the user for a numeric value within a

storage

position
and size)

$SDS ASKXxXxxX macros.

specified

five

store

the

result.

except allows programmer

1location of result as a

within a

Prompt

and store the

$DS _ASKSTR - Prompt

the

$DS_ASKDATA,

the

result.

are

there

and

large bit

the

wuser

user

for

structure.

result as one bit,
a

field (using

"yes"

"no"

set or cleared.

character

string

and

THE STRUCTURE OF A VAX SUPERVISOR DIAGNOSTIC PROGRAM
The
for

macros also allow the programmer to specify
the
response.
If there is no user present

state
of
the
VDS
control
VAX Diagnostic Supervisor User's

automaticall
be
y

will

used.

default

OPERATOR,
the

value

wvalue
by the

see

default

exists,

the

wvalue

the

will

program

aborted.

Sometimes diagnostic
options
other
than
command language.
used
to
prompt
parameters.

questions

The

flag
Guide),

a
default
(indicated

One

that

programs require the user to specify run-time
those
that
can
be
selected using the VDS

In
the

such cases, the $DS
wuser
to
indicate

method

can

accomplishing

answered

YOU

WISH

YOU

WANT

THE

RUN

with

this

"no,"

"yes"

OPTION

DEVICE

ASKxxxXx
macros
the
required

can
be
run-time

ask

such

set

X?
RUN

MODE

responses

to these question
could
be
converted
to
set
or
bits that the diagnostic program could test.
This method
if the total number of program options is small.

Cleared
is fine
However,

the

for

program

every

time

want

cases,

allow

program

user

the

program

use

the

him

the

her

a large

have

might

type

number

answer

executed

default

programmer

with

might

want

for

just

run-time

large

(assuming

values

string

these

she

questions).

prompt

options,

list

the

user

options,

questions

did

not

such

once

and

OPTIONS ARE OPTION
X, OPTION
Y, OPTION
Z
(DEFAULT

TYPE

Allowing

the

convenient
programmer

For
be

user

for the
to check

program

beneficial

example

might

OPTIOX)
N

OPTIONS:

type a list of the
user, even though it
the strings typed to

options

wanted
1is
more
is more difficult for the
see if they are valid.

having a very large set of run-time options it might
for the programmer to create a command language.
An
be

Commands:
OPTIONS

select

options

MODES

select

device

BEGIN

begin

program

RESUME

continue

after

modes

execution
control-C

THE STRUCTURE OF A VAX SUPERVISOR DIAGNOSTIC

The user would type the VDS RUN or
diagnostic
program's
execution.
code

perhaps

$DSASKxxXXx

within

macros

START
command
In the program's

particular

prompt

PROGRAM

the

test,

user

for

the

to
start
the
initialization

program

command

executes

strings.

The
(or
command
The BEGIN
program parses and executes each command.
something
similar)
simply
allows
the
VDS
to
continue normal
would
command
The RESUME
dispatching of the diagnostic program.
diagnostic
the
within
defined
is
handler
useful if a control-C
be
The number and
program (see Section 3.14.6, Handling Control-Cs).
types
of
commands defined would, of course, depend
the particular diagnostic program being designed.

completely on

The VDS provides two macros to facilitate
command
parsing.
$DSCLI macro is used to define the desired command language.
the
SDS PARSE macro compares an input stream (obtained from

via a $DS ASKxxxxX macro)
a

set of

action

against the command language defined with

$DS CLI macros and

routines or

The
The
|user

inform

will

the

either

user

dispatch

if an

illegal

the

command

proper

has been

typed.

3.12.2.3
Displaying HELP Text - Chapter 5 discusses the
creation
of
HELP
files,
which
are
supplemental
files
containing

informational text that the user can read.
It
may
sometimes
be
desirable for the diagnostic program to fetch and display sections
$DS_HELP
This can be accomplished by using the
of the HELP file.
macro.
Read
the
section
of
Chapter 5 on HELP files, and ~then
refer
to Chapter 4 for a description of the $DS HELP macro.

3.13

Note:

MEMORY MANAGEMENT AND ALLOCATION

For

~Architecture

discussion

VAX

memory

Handbook.

management,

see

the

VAX

The memory management hardware may not be directly
diagnostic programs running under the VDS.

referenced
|

In user mode (level 2R programs), memory
management
hardware
under
the
control of VMS and it is always turned on.
All of
VMS memory management system services are
available
for
use

1is
the
by

3.13.1

Memory Management

User

Mode

VAX/VMS System Services
the
- See
programs.
diagnostic
VMS
to
applying
restrictions
" Reference Manual for the uses and
Allocation of new memory space should
memory management services.
described
as
only be accomplished with the VDS $DS GETBUF macro,
in Section 3.13.3.

THE

3.13.2
In

STRUCTURE

Memory

standalone

hardware
Diagnostic

VAX

Management
mode

SUPERVISOR

(level

Standalone
3

may
be
turned
programs
can

DIAGNOSTIC

Mode

programs),

on
turn

or
on

PROGRAM

the

memory

management

off.
Normally,
it
memory management

1is

off.
the

with

$DS_MMON macro.
Once
on,
1t
can
be turned back off with the
$DS MMOFF macro.
All map register initialization is performed
by
the
VDS,
outside the control
of the diagnostic program.
Turning
on

memory management

virtual
so

that

virtual

address

there

and

will

space,

direct

physical

memory management

all

pages

of any page
In

standalone

on and
These

mode,

commands

contained

within

the

SET

Some

diagnostic

the

with

the

return

turned
the

before

doing

one

memory

the

VDS

may

$DS

not

from

sets

this

the

protection

change

the

Thus

can

the

SDS

user

macros

has

issued

shut

off

»
execute

this

1is

indicates

the

of
that

program must

appropriate

memory

case,

the

printing

turned

MMOFF

cannot

beginning

macro

then

SET MM OFF commands.

program

protection

S$SETPRT macro.

and

able

between

space.

macro.

enabled.

mapping

hardware

MMON

MMOFF

be issued

registers

the

program.

$DS

program's

the

correspondence

possible

diagnostic

the

diagnostic

SET MM ON and

the

$DS ABORT macro),

the

program.
operator

abort
error

itself
message

so.

Memory

Allocation

diagnostic

programs

other

the

$DS GETBUF macro.
use

management

on memory management

(with

the

loads

by using

the

has

should

memory

via

programs

must

Many

dignostic

$DS_MMOFF macro

3.13.3

VDS

enabled,

override

hardware

status

the

one

pages

user,

command,

memory management

management

write."

group of

off by the

increase

addresses

When

to"user

not

since

wuses.
this

need

Additional

Both

macro,

extra

memory

space

user
since

mode
this

assuring that there will be no memory
the VDS and the diagnostic program.

and

space

may

for

standalone

method

allocation

I/0O

acquired
1is

mode

the

buffers

only

conflicts

using

programs
way

between

THE

The VDS
used to

STRUCTURE

keeps track
request the

VAX

SUPERVISOR

of all
VDS to

diagnostic

program.
the
memory
space
group of contiguous

DIAGNOSTIC

PROGRAM

free memory.
The $DS GETBUF
macro
assign a certain number of pages to

is
the

The VDS will return the starting
address
of
it has assigned.
(Space will be assigned as a
physical pages in standalone mode,
and as
a

group of contiguous virtual pages in user mode.) When a diagnostic
program is executing on a system possessing 512K bytes of physical
memory
(the
smallest
memory
size
supported
by
the VDS), the
Program

guaranteed

access

least

96K

bytes

the

VDS's

free

memory

buffer

space.

Memory space is returned
the $DS RELBUF macro.

3.14

SYNCHRONOUS

3.14.1

AND ASYNCHRONOUS

pool

wusing

EVENTS

Introduction

Synchronous

events

are

those

that

occur

within

the

normal

execution
flow
of a program.
Waiting for a bit to become set or
creating a time delay are both
examples
of
synchronous
events.
Asynchronous events are
those
that
happen
outside
the normal

execution flow.
VAX exceptions
are
asynchronous,
because
they
cause
the normal flow of a program to be changed (program control
is
passed
to
the
condition
handler).
Refer
to
the
VAX Architecture

Handbook

exceptions.

Diagnostic
synchronous

are

time-critical

Event

flags

detailed

used

and

discussion

VAX

programs
often
and asynchronous

synchronous

3.14.2

~synchronous processing
handlers

for

need
to
handle
occurrences
events.
"Event flags" are useful

events.

AST routines

asynchronous

processing.

asynchronous

situations.

methods

and

available

of
for

condition

There

are

for

handling

both

Flags

are

flags

that

can

used

diagnostic

programs

flags

are

indicate
status
information.
Services are provided for setting,
clearing, and reading the flags.
Additional
services
allow
the
diagnostic
program to wait for a flag or group of flags to be set
before proceeding with program execution.
The services are called
macros.
are

divided

flag

event

flags,

numbered

into
two clusters,
macros require that the

from

63.

The

each contalining
32 flags.
cluster be indicated.

Some

event

There

{

via

THE

STRUCTURE

VAX

SUPERVISOR

DIAGNOSTIC

Event flag 0 is reserved for exclusive
available to diagnostic programs.
Flags

through

SET

EVENT

can

FLAGS

used

can

and

set

CLEAR

implement

use

cleared

the

EVENT

FLAGS

user

selection

PROGRAM

VDS

the

commands,

and

1is

user

which

not

wvia

the

means

they

optional

©program

features.
Flags

level
level

through

programs.

Flags

through

Users

cannot

user

The

Event

flags

since

they

are

VMS

can

these

flags

cannot

availilable,

used

however,

programs),

macros

only

event

associate

all

diagnostic

©programs.

are

flags,

common

event

call

referred

wused

shared.

for

details.

from

flags"
system

since

flags

with

event

internally

numbered

Manual

flags

service

are

maintained

routines

within

"local

event

single

through

they can be
service
$ASCEFC

See

the

event

flags

processes

VAX/VMS

VMS.

flags,"

process.

127,

are

shared

must

order

for

System

Service

Reference

hence

are

flags.

referred
to
as
"common event
cooperating processes.
The VMS
used

and

They

flag

through

set of

available

these

(level

event
@

used

programs.

modify

mode

VMS.

Another

are

diagnostic

standalone

VDS,
VDS.

The

and

following

programs

mode

the

(level

event

macros

reference

$SSETEF
-

Sets

3),

flag

macros

are

wused

event

specified

call

are

service

both

maintained
routines

1level

the

within

the

and

level

event

flags.

flags:

event

flags.

SCLREF - Clears speéified event flags.
SREADEF

Read

the

current

SWAITFR - Wait

for

SWFLAND

for

a group

- Wait

SWFLOR - Wait

for

status

specified
of

specified

event flag
event

flags

one of a group of event

SQIOW - Queue an I/0 request and wait for

flag

alent

$QIO

become

set

followed

(indicating

SWAITFR.

I/O

to become set.
to

become

flags

set.

become

specified

completion).

set.

event

Equiv-

THE

STRUCTURE

VAX

SUPERVISOR

DIAGNOSTIC

Additionally, the\SSETIMR (see Section 3.14.4,
(see

Section

3.12.1.1,

specify

references

3.14.3

Asynchronous

asynchronous

can

AST

event

trap

are

Timing)

macros

can

and

$SQIO

optionally

(ASTs)

(AST)

asynchronously,

dispatched

Mode)

flags.

to a device interrupt.
referred
to
as
an

routines

User

System Traps

system

entered

similar
AST
1is

1I/0

PROGRAM

a method

outside

by which

the

normal

A routine that is
AST
routine.
The

called

AST

routine

program

entered
process

flow,

via
an
by which

delivery.

3.14.3.1
AST Delivery - Three macros, available to both level
2R
and
level
3
diagnostic
programs, allow the use of ASTs.
These
macros are $SETIMR, $QIO, $SQIOW, and S$SDS CNTRLC.
Fach
of
these

macros
- In

the

when

will

case

the

accept as an argument

the

specified

SQIOW macros,

the

I/0

operation has

will

cause

types

S$SETIMR macro,

an AST

amount

AST

routine

time

will

completed.

the address

the

AST

has

the

of an AST routine.

routine

elapsed.

executed

will

For

when

the

$DS CNTRLC macro

entered

when

the

entered

$QIO and

requested

used,

program

user

control-C,

ASTs may be enabled or disabled with the SSETAST macro.

are

routines

will

disabled,
not

ASTs

will

not

delivered

and

thus

the

AST

ASTs

executed.

If a diagnostic program is waiting for an event flag (see
Section
3.14.2,
Event Flags) or hibernating (see Section 3.14.4, Timing),
ASTs will still be delivered to it.
After
the
AST
routine
has
been executed, the program will be returned to the state it was 1in
before the AST was delivered (unless, of course, the
AST
routine
itself

set

the

desired

flag

woke

the

program).

3.14.3.2
AST Routines - An AST routine is
instruction.
Thus
the
routine must have

entered
via
an entry mask

return by using a RET instruction.
It must
save
(by
them
in
the
entry mask) any registers it uses, other

a
CALLG
and must

specifying
than RO or

R1.

When an AST routine

1is

entered,

the AP points

argument

1list

in
the format illustrated by Figure 3-12.
The register values 1in
the argument list are those saved
when
the
main-line
code
Wwas
interrupted
on delivery of the AST.
The AST parameter 1s a value

specified by the "AST parameter" argument of the S$SETIMR, $QIO, or
SQIOW
macro
used
to request delivery of the AST.
This argument
can be used by the AST routine to determine who called 1it.

STRUCTURE

VAX

SUPERVISOR

DIAGNOSTIC

PROGRAM

THE

AST PARAMETER
RO

R1
PC

PSL

TK-10527

Figure

3.14.4

Facilities

List

Passed

AST

Routine

are
provided
for
<creating
timing
program.
These facilities allow you

©Specify a particular length

before
Cause

the

diagnostic
event

Cause

asynchronous

timing

time
|

expected

of time

facilities

differences

proceeding

length
The

Argument

Timing

diagnostic

3-12

among

program
to

stop

delays
|

vyou

wish

wait

executing

wuntil

event

occur

after

specified

passed

provided

the

VDS

take

the various VAX process

into

types.

account

speed

Therefore,

operations

MUST

operations,

current

guarantee

The

VDS

can

program

compatability

with

all

use

order

and

future

Some

macros

types.

timer
used

programs,

diagnostic programs containing time-dependent
the
VDS
timing facilities when coding these
processor

occurs

has

within

services

for

while

both

are

level

others

may

accessed

by macro calls.

mode)

(user

only

used

and

for

level

(standalone)

programs.

Mode - The

both

used

Standalone

Timing Facilities Available in User Mode and

3.14.4.1

1level

following

and

time—-dependent functions.

1is

1level

1list of macros that may be

control

programs

SGETTIM - Gets the current system time.

SSETIMR - Allows you to cause an event to take place

specified amount of

after

time has passed.

1into

SBINTIM - Converts an ASCII string that specifies a time

a numeric value meaningful to the SSETIMR macro.

SCANTIM - Cancels requests specified with the SSETIMR macro.

SWAKE - Cancels a S$HIBER request.

expected.

until
SHIBER - Causes processing to stop
n."
"hibernatio
as
to
Referred
occurs.

event

Referred to as "waking"

the

for

$DS_WAITUS

‘

program.

$DS_WAITMS

specified

Delays

number

$SDS_CANWAIT - Cancels time

$DS_WAITMS call

execution

program

sequential

of milliseconds.

from

remaining

A typical use of'these macros in standalone mode would be ‘to issue
a SSETIMR macro that will cause an AST routine (see Section

Then
3.14.3) to be executed when the specified time has expired.
g
processin
other
Some
enabled.
be
could
a device's interrupts
the
When
interrupt.
the
for
waiting
while
could take place
routine could issue a
interrupt service
the
interrupt occurs,
SCANTIM macro to cancel

occur

before

entered.

steps for

the

time

the $SETIMR.

period

If the

ends,

This routine could declare

the

timeout

Interrupt Service
Process interrupt.

Continue.

Return from interrupt.

Enable interrupts.
flag

Issue $DS CANTIM macro.

set

THEN

issue

ELSE

not

error.

Program

$DS

AST Routine:

Routine:

Issue S$SETIMR macro.
error

does

this function would be as follows.

Main Program:

interrupt

AST routine would be

ERRxxXX macro

contilinue.

3-60

Set error flag.

Return.
|

A VAX SUPERVISOR DIAGNOSTIC PROGRAM
THE STRUCTURE OF

THE

STRUCTURE

VAX

SUPERVISOR

DIAGNOSTIC

3.14.4.2
Timing Facilities Available in
The next macro may only be used by level

SDS

WAITUS

specified
A

typical

use

interrupts
an

and

unnecessary

for

would

1is
was

this
Main
Set

set

issue
wait

$DS

indicate

wait

for

$DS WAITxx

loops.)

time out

the

$DS

After

service

If not,
condition.

see

interrupt
interrupt

any time
CANWAIT

eliminating
the

SDS_WAITUS

flag.
If
the entire
Program

the
time
steps

Service

Routine:

Process
Set

interrupt-occurred

the

device's

cancel

time

follows.

I/0.

macro

for

The

that

(Usually,

interrupt
occurred.

interrupts.

not

CANWAIT

execution

service

frame.

Interrupt

device

flag

enabling

WAITUS

flag

remaining

would

the

$DS

service.

Only

Mode

execution

time

improves

indicating

program

certain

be code to test the
set,
the
1interrupt
up,

the

Standalone
programs.

Program:

Issue
AN

would

call

within

the

function

Test

would

time

sequential

microseconds.

service

simply

used

Enable

this

would

from

optional

occurred

and

~remaining

delay

routine

occurred

call
flag

Delays

followed

interrupt

service

number

PROGRAM

call.

interrupt.
interrupt-occurred

Issue

flag.

$DS_CANWAIT

Return

set

macro.
interrupt.

from

THEN

issue
ELSE

$DS ERRXXXX

macro

continue.

3.14.5

Condition

Handling

Note:

For

additional

refer

the

information

VAX Architecture

Handbook.

The

VDS

the

diagnostic

regarding
Handbook

and

condition
the

handling,

VAX/VMS

contains

Software

condition handling routines that will handle
all
exception
conditions.
It
1is
therefore
unnecessary under most
circumstances for the
diagnostic
program
to
provide
exception
handling
facilities.
However,
the VDS provides the ability for

program

field

3-61

exceptions

when

necessary.

The VDS searches for condition handlers in exactly the same manner

[
|J

HWN
-

If a primary handler exists, it is used.
If secondary handler exists, use 1it.
Search call frames for address of handler.

handler

found

Handle
(5S$

handler.

"last chance"

Use

order:

following

the

for

As detailed in VMS documentation, handlers are searched

VMS.

. ‘/mn\\

THE STRUCTURE OF A VAX SUPERVISOR DIAGNOSTIC PROGRAM

can

condition

the

return,

CONTINUE)

and

indicate

"success"

"resignal"
indicate a
Not handle the condition and
r
dispatche
handler
the
(5S$ RESIGNAL) return, which causes
to continue

to search for a handler.

The VDS has a secondary condition handler, but

services

only

BPT and T-bit exceptions associated the the VDS's breakpoint and
single-step facilities (see the VAX Diagnostic Supervisor User's

program's cleanup code to be executed).

In standalone mode, the VDS searches for a condition handler and
if none 1is found, a call to the last chance handler is forced.
This call to the last chance handler cannot be disabled by a

diagnostic

program.

Additionally, the address of the VDS last chance handler is placed
This means that in user
frame of the VDS.
on the highest <call
the
precedence over
take
mode, the VDS last chance handler will
e
standalon
in
as
that,
means
also
It
VMS 1last <chance handler.
handler.
VDS
the
disable
mode, a diagnostic program cannot

If a diagnostic program declares a handler

one

its

call

precedence over the VDS's last
take
that handler will
frames,
standalone mode, a
and
mode
user
In both
chance handler.

may

handler

condition

specified

address into the first address of

pointed
with

the

the FP).

instruction
MOVAB

the

<call

frame

the handler's
(the

address

In MACRO-32, this would be accomplished

(FP)
CONDHNDLR,

To declarea condition handler in BLISS-32,
Language

1loading

Guide.

3-62

refer

the

BLISS

The main condition handling facility of the VDS is a "last chance"
handler that 1is capable of dealing with all exception conditions
(and will abort execution of the diagnostic program by causing the

Guide) .

THE

STRUCTURE

user

When

VAX

diagnostic

the

using

condition

the

second

arguments

are

programs

also

service

given

argument

the

address

may

system

first

passed

DIAGNOSTIC

the

control,
the

manner

VMS.

address

PROGRAM

declare

Reference Manual.

handler

The

SUPERVISOR

$SETEXP

System Services

arguments.

and

mode,

handlers

VAX/VMS

is
a

"mechanism

indicated

condition

Refer

passed

the

two

"signal

array"

array."

These

Figure

3-13.

<+—AP

ADDRESS OF SIGNAL ARRAY
ADDRESS OF MECHANISM ARRAY

TK-10528

Figure

3-13

The signal
shown
in

longwords
Condition

/Q\\

the

Argument

List

array

indicates
Figure 3-14.

(excluding
names

VAX/VMS

are

the

the one

containing
by

System

macro.

then

the

argument

the

Services

Condition

the

$SSDEF

Reference

parameter

vector

offset.

up
of

CONDITION NAME

0 TO 2 EXCEPTION-SPECIFIC
PARAMETERS

EXCEPTION PC

EXCEPTION PSL
TK-10529

Figure

3-14

The mechanism array is

Format

illustrated

3-63

Signal

Array

Figure

3-15.

1is
of

the

array.
listed
SDS_DSDEF

LIB.MLB

Manual,
or the

name"

SCB

Its
format
total number

making
macro

"condition

the

Handler

type of condition.
the figure, N is the

defined

VDS

Passed

DSS

UNEXPINT,

THE STRUCTURE OF A VAX SUPERVISOR DIAGNOSTIC PROGRAM

HANDLER ESTABLISHER FRAME FP
FRAME DEPTH
RO
R1
TK-10530

Format of Mechanism Array

Figure 3-15

A condition handler can either field the condition or return with
a "resignal" status to indicate that another handler should be

If the handler fields the condition, it must place the
called.
If the handler
status code SS$ CONTINUE in R@ before returning.
code must be
status
RESIGNAL
does not field the condition, the SS$
RET MACRO-32
an
with
end
s
Condition handler
placed 1in R#.
macro to
SUNWIND
the
use
may
instruction. A condition handler
handle
cannot
it
if
flow)
the call frame (alter program
"unwind"
the
of
on
discussi
the
the condition. Unwinding is detailed in
SUNWIND macro

in Chapter

receive control when ANY exception
The condition handler will
The handler must determine the type of
occurs.
condition
exception (by examining the signal array) and decide whether or
It is quite common to
not to handle the particular condition.
write a condition handler that will only process one or two

types

of exception conditions, and resignal all others so that another
handler-(such as the VDS last chance handler) can process them.
As an alternate method

the

in standalone mode,

the programmer may

Useé

VDS macro SSETVEC to store the address of a condition handler

This allows the diagnostic
in the system control block (SCB).
program to field specific exception conditions, instead of all of

them. By using this method, the VDS handler dispatcher 1is
bypassed and control passes directly to the handler pointed to by
This handler MUST process the exception and
the exception vector.
cannot

"resignal."

the
If the diagnostic program contains a condition handler,
$SDS_PRINTSIG macro can by used to automatically format and print
contents of

the

signal

array.

the

THE

STRUCTURE

3.14.6

Handling

Normally
a

VDS

when

VAX

SUPERVISOR

DIAGNOSTIC

PROGRAM

Control-Cs

the

routine

user

types

which

control-C,

aborts

the

program

current

control

VDS

passes

function

(such

executing a diagnostic program or
building
a
p-table).
It
is
possible
to
specify
an
alternate
control-C handling mechanism
within the diagnostic program
by using the $DS CNTRLC macro.
The
diagnostic
program can use this macro to specify the address of a

routine
If

the

that

macro

used

program

perform
a.

control

any

executed

and

Pass

return

the

status

This

technique

for

the

Pass
VDS
a

nonzero

case,

was

should

not

the

zero

execute

control-C

code

(in

its

own

continue

own

VDS

will

pass

This

routine

may

R@),

which

control-C

where

perform

1is

status
will

the

(in

its

cases

program

before

typed.

then

code

useful

typed,

routine.

execute

VDS

performing

and

then

diagnostic

its own whenever
takes over.

control-C

specified

needed

VDS

control-C

the

processing

cause

when

will

handler.

desirable

some

processing of
before
the
VDS

typed,

RO), to indicate
that
control-C handler.
In
performing

the

control-C

and

(c)

was

the

the
such

function

typed.

Not return at'all.

possible

special

use

options

command

(b)

1language

has

been

would

the

defined

the

case

where

programmer

(see

Section 3.12.2.2, Prompting the User).
In this case it
might
be
desirable
for
the user to be brought back to the special command
line interpreter when a control-C is typed.
One
of
the
special

commands

(such
used.

would

might

the
If

the

option

(c)

The

$DS

CNTRLC

that

and

would

certain

reenabled.

disabled,
servicing

the
1is

SERVICING

MUST

TIME.

appreciate

command

also
of

CONTINUE

option
the

the

DISABLED

run-time

typed

command

would
the

user,

while

possible

disable

executed

servicing

code

function

can

ensure
without

disabled

executing,

and then

control-C

servicing

lost.
It will be serviced when the
is important to note that CONTROL-C
FOR

LONGER

environments

control-C

periods

Control-C
is

from

programmer

will

uninterruptable

not
It

(b)

current

fetched

This makes

code

control-C

NOT

typed,

would

allows

necessary.
a

not

VDS

altogether.

this

1longer
long

was

the

case

selected.

control-C is
reenabled.
Some

new

macro

while

tolerate

portions

interruption,

same function as
above), in which

command

servicing

temporarily

ONE

the

used

RESUME

aborted

control-C

have

RESUME

time

3-65

response
when

THAN

(APT

delay,

control-Cs

THREE

SECONDS

particular)

nor
are

not

cannot

users

serviced.

THE STRUCTURE OF A VAX SUPERVISOR DIAGNOSTIC PROGRAM
Because dispatching to the control-C handler is performed
by
the
VDS,
a
control-C
will
not be acknowledged while the diagnostic
program is executing.
Whenever the
diagnostic
program
calls
a

the service routine will check to see if a

system service routine,

control-C has been typed.
But suppose that
by
some
chance
the
large segment of code that does not call any
a
program contains
If a control-C
system service routines for a long period of time.

acknowledged

not

will

typed,

this

while

1is

code

1In order to prevent this problem, any large section of

executing.

(or small section that loops for a long period of time) that
code
the
issue
must occasionally
services
does not call any system
simply
that
service
a
call
will
This macro
$DS _BREAK macro.
Just
received,
been
has
none
if
and,
checks for a control-C
BE
MUST
SERVICE
SYSTEM
OTHER
SOME
OR
MACRO
$DS_BREAK
A
returns.
ISSUED AT

- 3.15

LEAST

FILE

3.15.1

EVERY THREE

SECONDS.

MANAGEMENT

Introduction

It may occasionally be necessary for a diagnostic program to

reference

facilities

are

available,

Record management

$DS LOAD system

into

subsidiary file.

buffer

area

1In

namely:

services

service

such a case,

make
two

The $DS_LOAD system service

e
The

separate,

(RMS)

useful

for

entire

file

of memory.

If more involved
manipulations
of
files
1is
desired, such
as
referencing specific records or blocks, then the record management
|
|
services should be used.
Level

services
services

(user mode)

programs may

use

VAX-ll

information

for

VAX-11

RMS

1is

available

Management Services Reference Manual.

Level 3

record

management

entire range of RMS
The
files.
manipulate
to
(RMS)
Detailed
program.
diagnostic
the
to
1is available

(standalone mode)

in the VAX-11 Record
-

programs are provided with a

subset

This functionality resides within
the VAX-11 RMS functionality.
is referred to in this manual
and
RMS
VAX-11
emulates
It
the VDS.
as VDS RMS.

For

those

functions supported by VDS RMS,

the program

Iis,
That
RMS.
interface is exactly the same as that of VAX-11
In
macros.
same
the
use
will
programs
3
level
and
2R
1level
both
1in
while
VMS,
by
fielded
are
calls
service
the
user mode
they are

handled

by the VDS.

‘\\\

standalone mode

3-66

THE

Table

STRUCTURE

3-2 lists

the

VAX-11

3-2

VAX

SUPERVISOR

Comparlson

RMS

read

and

write

RMS,

VAX-11
VDS

Provides

DIAGNOSTIC

limitations of VDS

RMS.

Table

RMS

PROGRAM

as compared

and

VDS

to VAX-11

RMS

Provides

read

Supports

sequential

files

Supports

sequential

and

access only.

access.

Supports

sequential

relative

files.

Supports
random,

f11e
¢
@

sequential,
and

randomby-RFA

access.

Terminals
Console

can

device

RAB,

control

by-RFA

accessed.

cannot

referenced.

e FAB,

and

file

Terminals

Console

(RT-11

XAB, and NAM
|

cannot

device

format

e Only FAB,

are

random-

access.

structures

only.

XAB are

be accessed.

can

referenced.

only.)

RAB,

and FHC fields of

defined.

Also,

many

the

option

bits

structures

are

not

defined

When

RMS

using

Management

using

RMS

Services

defined

1level

VDS

Reference

manual

Whether

the

diagnostic

are

defined

program
in

use
a

RMS

this

manual

may

the

control

VAX-11

reference

use

actually

level

is level

LIB.MLB

Note that these are
macro definitions.

RMS functions
program

VAX-11

manual

not

Record

guide.

When

as
the main
as detailed as

necessary

refer

also.

macros

BLISS-32.
VAX-11 RMS

the

program,

Manual

level 3
program,
reference guide.
However, since
the VAX-11l RMS reference manual,

that

RMS.

for

1level

MACRO-32

2R,

and

the

RMS

LIB.L32

for

VMS libraries and thus contain
the
Therefore, inclusion of unsuppor ted

program

executed.

3-67

will

not

detected

untll

the

PROGRAM

file,
In order for a diagnostic program to use RMS services on a
the file resides must have been previously
the device on which
(This is true for both level 2R and level 3 programs.)
attached.
1is the one from which the VDS was loaded, the VDS
device
the
If
If
the device.
issue a $DS ATTACH macro for
ly
will automatical
program
diagnostic
the
then
device
load
VDS
the
not
the device is

can issue an $DS ATTACH macro, or the program can
user

issue an ATTACH command.

depend

the

access

and

VDS RMS Overview

3.15.2

for

VDS RMS provides facilities

easily

gaining

files on a disk or magnetic tape device,
reading sequential
The records within a file
console device.
system's
the
including

be accessed sequentially, or they may be accessed randomly by

may
a

record's file address

discussed later).

(RFA,

service requests
VDS RMS consists of a set of routines that will
files, along with a group of control structures that
reading
for
are used to pass information about the file back and forth between

VDS RMS supports three
the VDS.
the diagnostic program and
an extended
(FAB),
the file access block
control structures:
attribute block (XAB), and the record access block (RAB). When a
1t usually must load fields
program requests a file service,
within these control structures. The control structures contain
read along
information such as the name and type of file to be
with codes indicating how the file is to be referenced.
3.15.3

The

RAB,

FAB,

And

XAB

The file access block (FAB) is a user control block that describes

particular

file.

An FAB is allocated by using the SFAB macro.

One FAB must be defined for each file that is to be referenced.

The record access
records.
file's

block
There

the
about
information
<contains
(RAB)
must be an RAB associated with each FAB.

An RAB is allocated by using

the SRAB macro.

An extended attribute block

(XAB)

that,

a file's FAB.

XAB"

optional

control

block

different

types

if used, contains file attributes beyond those contained in

XABs,

VDS

(FHC XAB).

While VAX-11 RMS supports several

RMS supports only the "file header characteristics
The FHC XAB is allocated with the S$SXABFHC macro.

3-68

v/m\\

THE STRUCTURE OF A VAX SUPERVISOR DIAGNOSTIC

THE

3.15.4
The

STRUCTURE

Accessing

The

VDS

RMS

Control

the

FAB,

RAB,

various

program
for each

fields

VAX

SUPERVISOR

assembly time by using
field.
The fields can

defined

for

the
4,

descriptions

VDS

RMS

control

general

each
the

structure

and

XAB

block

SRAB,

fields

can

are

and

are

PROGRAM

Structures

the predefined
also be loaded

control

$SFAB,

DIAGNOSTIC

named

S$XABFHC

defined

initialized

keywords that
at run
time.

and

described

macros
in

exist
The

Chapter

mnemonic

format

the

structureSdatatype
name
where

"structure"

FAB,

RAB,

specifier
(see Table 5-1);
are FAB$L_FNA and RAB$V_BIO.
To

access

offset
an
FAB

FAB

structure

has

the

been

BLOCK.

would

from

field

beginning
defined

done

with

MOVAB

FILE

MOVB

RO, FAB

BLISS-32,

run

the
the

FAB

"datatype"

the

time,

use

macro

the

such

BLOCK+FAB$L

same

the

FNA

fields

would

field

For
and

FAB

BLOCK+FAB$B _FNs

the

is a data
type
name.
Examples

field

structure.
$FAB

fields

instuctions

NAME,

XAB;

name

with

Accessing

and

has

name

example,

suppose

been

1labeled

MACRO-32

program

;Load

filename

addr.

;Load

filename

size.

referenced

with

the

statements

FAB_BLOCK

[FABSL

FNA]

FILE NAME;

FAB_BLOCK

[FABS$B

FNS]

. FILE

For

some

for
For

fields,

both

the

example,

the

bit

offsets

bit

the

offset
FAB.

mnemonics

and

field

could

be accomplished

the

have

offsets

NAME SIZE;
been

defined.

and

the

mask

FABSV

BIO

and

the

mask value

Referencing
with

the

this

#FABSM_BIO,FAB

BBC

#FAB$V_BIO,FAB_BLOCK+FAB$B_FAC

BLISS-32

FAB_ BLOCK

statements

[FABSB FAC]

IF .FAB _BLOCK

Mnemonics

FAC

BIO

are

these
are

run

time

;Set

BIO

;Branch

(unrelated)

size.
defined

offsets.

defined

BIO parameter

BISB

Similar

filename

FABSM

following

BLOCK+FABSB

filename addr.

values

bit

1Load
!Load

the

MACRO-32

instructions.
in

FAB's

BIO

FAC

clear.

would be
.FAB

[FABS$B FAC]

BLOCK

[FABSB _FAC]

<FAB$V BIO,1> THEN

...

for

FAC

FABSMBIO;

;

THE

STRUCTURE

A VAX SUPERVISOR

DIAGNOSTIC

PROGRAM

When a control block is declared (with the $FAB, S$SRAB, or
SXABFHC
macro),
relevant
fields
may
be
initialized at compile time by
using keyword representations of
the
fields.
An example
(in
MACRO-32)

FAC =

SFAB

FOP

RWO,
-

XAB

FHCXAB

Similarly,

fields can be loaded

SRAB

(BKT

SRAB STORE,

and

STORE

the

3.15.5

Two

STORE
the

this

the

$FAB STORE,

BLISS-32

example.

10,

.FILE

NAME

.FILE:NAME

macros
fields,

Reading

methods

time with

FAB = FAB BLOCK,
RAC = SEQ,
FNS

referencing

at run

SXABFHC STORE macros,

FNA

Using

1is

[ADDRESS],

[SIZE]);

a run-time

described

alternate

above.

directly
|

Files

are available

for

reading

files.

These

methods

are

"record
processing"
and "block processing." When a file is being
referenced, the
programmer
may
use
whichever
method
1s
more
appropriate
to
the
file
and operations being performed.
It is
also

possible

3.15.6

Record

comblne

the two

methods.

Processing

When using record processing, reading a
file
1involves
accessing
records
within
the
file.
The
number, size, and contents of a
file's records
are
immaterial
to
RMS
and
are
determined
by
access methods

record
(RAC)

access

field

following
e

1is

the

for

referencing

spec1fy1ng

the

RAC

the

records.

The

record access

f1e1d

one

the

chosen.
access

retrieved

order

specified by loading

When

sequential

Records

RAB.

values may be

SEQ

file.

are available

method

in the

the

through

sequential

access

which

they were

stored.

are

returned

Once all

records
have
Dbeen
retrieved,
any
further attempt
sequentially
access
records
1in
the
file will cause
end-of-file condition to be returned.

the
¢to
an
/ /'r'fi—» .

Two

utility created

whatever

THE

STRUCTURE

RFA

record's

VAX

SUPERVISOR

file

address

DIAGNOSTIC

PROGRAM

access

Whenever

a
record
1is
read
from
a
file,
an
1internal
representation of the record's location within the file is
returned in the RFA field of the RAB.
VDS
RMS
can
save
the

wvalue

that

(Note:

both
Before

file
an

the
to

disks

VDS

and

FAB.

the

record

the FAB
issued.

into

the

Once

the

record

can

read

file's

first

fetch

the

stream

FAB

break

stream

using

record

used

the

record

Example

to
3-8

has

the

field
a

can

read,

record

file

access

has

the

been

again

request.

supported

been

RAB.

established,

read,

and

the

opened

Then

The

stream

after

macro

processing

illustrates

record

for

the

SCONNECT

records

first

each

with

placing

stream"

S$GET

in
will

successive

record
issued.

the

file.

processing

file.

S$OPEN

address

macro

the

file

cause

SGET

processing
Then

the

association

if the RAB's RAC field is set to SEQ.
to RFA, then
each
S$GET will
retrieve
file address (RFA)
is stored in the RAB's

SDISCONNECT

terminate

use

"record

stream

established

and

random-by—-RFA

tapes.)

S$SGET macro.

RFA

record,

is set
record

field

the

using

random-by-RFA

the

field
whose

completed,

file

After

field.
To

RMS,

in
by

magnetic

established.

macro,

the RAC
record

record

record
of
s a

must

RAB

contained

retrieve

the

will

If
the
RFA

has

been

S$CLOSE

macro

This

routine

reads

sequentisal

file

a buffer.

into

MY.FAR!
MY.RAE:

|
0

+L.LONG

RUFFER

$FAR
$RAE

FNM = <INFILE!>
FAR=MY_FAR,-

Allocate

1000-bute

lescrirtor for buffer

1000

Length will

RUFF_DESC?
+LONG

A
Y WRT s NDEXE
DAT

Adddress

+BLKE

+FSECT

BUFFER!

Wmpr

h
-1

THE STRUCTURE OF A VAX SUPERVISOR DIAGNOSTIC PROGRAM

buffer

be set at

run time

buffer

File access blochk
Record access blockhk

FAE=MY_FAR

ELEC

ROSEXIT

$CONNECT RAE=MY_RAR
ROSEXIT
BLEC

‘B>

$0FEN

Oren

the

file.

Exit

onm

error,

CODE,NOWRTEXE
SIMFLE, "Ml

Connect

+FSECT
+ENTRY

UBF=EUFFERy
USZ=100

Exit

RET

ERRORS$

96>
‘|

ROs#RMS$..EOF
ERRORS
FAB=MY_FAR

oOn

record

[lone®
NoO

Return.

rointer

error.

the

file.

(Error handler.)
Example

3-8

Record

Processing

3-72

orerations.

error.

buffer

Get ahother record

“BP

CHPL.
BENEQ
$CLOSE

Advance

CHECK_DONE

BEranch

®w»r

BRE

Get 3 record

RAE=MY_RAR
RO» CHECK_DONE
MY . RAB+$W_RSZy~
_RUF
MY .RAE+RAE$L
y
GET_.RECORD

$GET
ELEC
AnnL

for

error.

GET..RECORD

with

RMS

THE

3.15.7

STRUCTURE

Block

indicate

VAX

makes

any

DIAGNOSTIC

record

directly

structure

PROGRAM

I/0

field

will

the

FAB

perform

block

performed

must

processing,

read

that

FAC

SOPEN macro.

possible

sort

that block

the

SUPERVISOR

Processing

Block processing
a file, ignoring
the file.

bit

set

the

blocks

might

exist

for

file,

the

BIO

before

issuing

file must

the

first

opened
with the SOPEN macro.
Then an RAB must be associated with
the file's FAB by using the SCONNECT macro.
Blocks
can
then
be
read
from
the
file using the $READ macro.
The first SREAD will
cause the first block of the file to
be
read.
Each
subsequent

SREAD will

When

file

macro

Mixing

the

Block

BRO bit

The

cannot

possible

pProcessing,
only
BIO

allow
bit

FAC

field

pProcessing

FAC

completed,

And

the

FAB!).

the

after

the

allow

some

Once

set,

later

block

time

bit

the

first

both

use

'l"’

pTN

Polnters

SGET

its

after

random-by-RFA

will

indicate

block

SREAD and

access.

For

the

block

been

processing

both

block

the

file.

issued.
and

record

processing

is accomplished by
setting
RAB (NOT the BIO bit in the
is

set,

pointer

the

has

disable

be-allowed.

and

$DISCONNECT

then

performed

$OPEN macro

both

this

FAB

may

processing modes requires some caution.
switching
from
block reads to record reads on
pointer

the

Processing

Mixing
record

file.

issue

Record

block processing.
This
in the ROP field of the

will

macro.

field

set

block

processing

initially

then

and
the

been

Processing

record

sequential

$CLOSE

the

and

bit

has

the

Processing

BRO

processing

followed

3.15.8
If

fetch

are

first

both

the

tape
tape.

record

example,

a disk,

when

RMS's

wundefined,

SREAD after

magnetic
of

For

further

SGET must

devices,

the
|

./lfiwk\.\u

e
i

CHAPTER 4
VDS MACROS

4.1

INTRODUCTION

This

chapter

describes

macro
used 1in
four sections.

in detail the format and function
of
each
VDS diagnostic programs.
The macros are grouped in
Within each
section,
macros
are
1listed
alpha-

betically

the

macro

name,

ignoring

the

$).
The

"program

sections,

structure

tables,

macros"

and

data

are

used

name's

structures

prefix

define

making

(SDS_ or

the

wvarious

diagnostic

the

program's

program.

The

"program

execution

control

path

macros"

and

are

provide

used
to
facilities

affect

such

<call

system

define

1looping

and

branch-on-error.

The

"system

‘provided

service

the

macros"

The

"symbol

definition

used

other

For

programs

before
In

the

any

BLISS-32

are

used

macros"
macros,

written

symbols

the

programs,

symbol

definition

issuing

symbol

are
the

MACRO-32,

definition

and

the

thus

macros.

and

these

defined

however,

macros

used
VDS,

For

global

symbols

diagnostic

program.

macros

the

symbols

may

the

macros
are

not

must

are

The

CODING SYSTEM
VDS

system

BLISS-32

service

macros

This

issued
within

without

first

programs,
in

this

the
guide

SERVICE MACRO CALLS

services

the
desired
service
Lo provide values for
declared.

referenced.

defined

referenced

documentation
on symbol definition macros provided
can be used simply as a list of available symbols.

4.2

services

VDS.

can

macro

are invoked by issuing a
macro
call
for
and, if required, including an argument list
the macro's parameters.
Before
any
system

called,

defines

the

the
$DS DSSDEF
macro
must
system service entry points.

VDS

Macro

Fields

names

The

consist

Macro

Name

three

fields.

These

fields

are:

A prefix.

This prefix may be 'SDS
' or '$'.
Macro names
having
the
'$DS_'
prefix are defined exclusively for use with the VAX
Diagnostic Supervisor.
Macro names having the
'S'
prefix
are
defined
for use
not
only
with
the VAX Diagnostic
Supervisor, but also for
any
program
running
under
the
VAX/VMS

operating

Diagnostic

system.

programmers

should

not

assume

that

macro

name's
prefix
implies
any
restriction
on
the run-time
environment in which the macro may be used.
For
instance,

used

NOT

assume

for

1level

restrictions

out

Because

the

alphabetized
for example,

the

programs.

that may exist

spelled

Any

for

description

different

'S$'

prefix may only be

run-time

environment

a particular macro

prefixes,

the

will

macro.

macro

names

have

Dbeen

in this chapter
by ignoring the prefix.
Thus,
S$BINTIM will be located after
$DS ABORT,
and

SDS_SETMAP will
A

that macros with

SREADEF.

name.

This

name

the

macro

identifies

the

system

service

being

1invoked

call.

A suffix.
For MACRO-32 programs
or

The

this suffix may be

' S8',

' G',

' DEF'.

suffix

indicates

that

used,

the macro

call

the

system

service

is to be called with a CALLS MACRO-32 instruction.

suffix

list
to
(Specifying
an

' L',

example

must

include

provide
values
for
required
argument lists is detailed below.)
of

the

' S'

form

the

macro

routine

If this

argument

parameters.
Following is

call:

$DS_ERRHARD S UNIT = LOG UNIT,

|
MSGADR = HARD12 MSG, PRLINK = HARD MSGRTN, Pl

= SAVED STATUS

4,.2.1

MACROS

VDS

MACROS

If the ' G' suffix is used, the system service routine will
In this case,
be called with a CALLG MACRO-32 instruction.
only one argument is specified with the macro
call;
that
1list of arguments to the
a
of
address
the
is
argument
system service.
Following is an example of the
' G'
form
of

the

macro

call:

$DS_ERRHARD
G HARD ARGLIST

The

' L'

suffix

will

not

call

the

system

service.

will

generate an argument list.
This argument list may later be
passed to the system service when
the
service
1is
<called
with
a
' G'
suffix, if the list's address 1is used as the
form

the macro

$DS _ERRHARD
L

UNIT = LOG UNIT,

PRLINK

Pl
' DEF'

suffix

MSGADR = HARD12 MSG, -

service's

' L'

call:

HARD ARGLIST:

The

is an example of the

Following

macro call's argument.

HARD

MSGRTN,

= SAVED STATUS

simply generates

parameters.

These

symbolic

names

can

for

the

used

fill in fields of an argument list that was defined with
a
' L' macro.
Names will consist of the service name, a "S$",
an ' ', and the parameter name.
The symbolic names
should
be used as offsets from the beginning of the argument 1list.
Following

example

the

' DEF'

form

the

macro

call:

$DS_ERRHARD
DEF

MOVAL
For

HARD13 MSG,

BLISS-32

programs,

HARDARGLIST+ERRHARD$
MSGADR
the

suffix

field

the

macro

«call

is
always
left
blank.
System services are always called
with a CALLS MACRO-32 instruction, and the macro call
must

include

BLISS-32

example

an
is

argument

decribed
in

invoking

1list.
the

system

(Specifying

service

$DS_ERRHARD
(UNIT

.LOG UNIT,

MSGADR = HARD12

section.)

MSG,

PRLINK = HARD MSGRTN,
Pl = .SAVED STATUS);

argument 1lists
Following

BLISS-32.

VDS

4.2.2

Macro

Most system

MACROS

Arguments
services

possess

set

input

parameters

for

values
must
be provided
when a service 1s invoked.
associated with input parameters via arguments
to
the
macro

For
of

call.

which

Values are
service's

MACRO-32 programs,
ways:

macro

arguments

may

specified

either

two

Arguments may be specified as a
1list
with
each
argument
except
the last followed by a comma.
The position of each
argument
is significant and thus arguments must
be
1listed
in
the
order
specified in the macro's description.
If a
particular argument is optional and is
to
be
omitted,
a
comma must be included to signify its omission.
An example
of

macro

call

using

positional

specification

arguments

is:

$DS _GETBUF_S

Arguments
symbolic

#3,,,

may be
names

specified
by
"keywords."
that
are assigned to input

Keywords
are
parameters.
A

keyword

is defined for every parameter of every macro,
and
that
keyword is the name used to identify the parameter 1in
the
description
of
the
macro's
MACRO-32
format.
For
example,
the $SDS GETBUF macro's MACRO-32 format is defined
|

as:

$DS_GETBUF x

pagcnt,

(brackets indicate optional
macro's

arguments

$DS_GETBUF_S
Notice

include

that

using

for

[phyadr],

arguments).

keywords

PAGCNT=#3,

when

commas

with

[retadr],

would

[region]

Specifying

appear

this

as:

REGION=#1

keywords,

unspecified

1is

not

necessary

¢to

arguments.

For BLISS-32 programs,
macro
arguments
may
also
be
specified
positionally
or
by
keyword,
but
the
choice
1is NOT up to the
programmer.
For some macros, arguments
must
be
specified
with
keywords.
For
others, arguments must be specified positionally.
If the
description
of
the
macro's
BLISS-32
format
specifies

(capital

letters followed by an equal
not

sign),

indicate

the keyword

keywords,

then

;

keywords

must be used.
If the description does
positional specification is required.

VDS

4.2.3

Return

Status

MACROS

Codes

All system services return an
status

code

should

diagnostic

program

All

codes

status

SS$_ - Most

status

RMSS_ -

Status
(RMS)

are

DSS_ - A
~Codes

status

~"RMSS$_",
error.

defined

codes

Severity

Value

codes

begin

MACRO-32

with

with
the

names

101-111

are

SSS$_NORMAL vs.
to

defined

DS$ NORMAL

indicate

prefix.

Such

DSDEF

begin

with

the

"SSS
"

severity

the

Name

STSSK_WARNING

STSSK

SUCCESS

STSSK

ERROR

STSSK

SEVERR

'STSSK INFO

fatal

erro

VMS with

the

macro.

Symbolic

- Most

that

Management

Reserved

names

For

macro.

this
$DS

follows:

Severe

prefix.

these

Informational

MACRO-32,

Error

100

Each

These

For

indicate

‘Success

g1l1

them.

macro.

bits

the

prefixes.

Record

prefix.

This

after

with

$SSDEF

Warning

010

Status

codes

R@.

service.

this

the

Meaning

2@l

Symbolic

SRMSDEF

three

are

(Binary)

the

symbolic

1low-order

with
by

associated

the

possible
”

defined

this

for

whose

three

with

from

associated

begin

are

codes

few status

are

the

codes

begin

defined

code

immediately

control

names

one

codes

status

examined

program

have

these

- Services

codes

symbolic

will

MACRO-32,

For

regains

have

of
these
names
prefixes are

error

always

the

S$STSDEF macro.

services

service

was

return

the

successfully

For

‘“"normal"
completed.

some services, the correct prefix on the "normal" return
code
"Sss$s
";
for
other
services,
"DS$
"
1is the proper prefix.
These two status codes are NOT interchangable.
Care must be taken

that a program's code
particular
service

description
For

all

status

will

set.

Thus

will

for

error

instruction.

indicate

codes

cleared.

uses

that

For

MACRO-32

has

the

being

which

code

indicate

all

other

programs

occurred

However,

proper

this

readablility
1is
improved
using symbolic names, as in

"normal"

invoked.

simply

'status

code
service's

Each

for

the
macro

correct.

error

status

method
if
the

condition,

codes,

bit

possible

using

the

NOT

bit

@ of

determine
BLBS

recommended.

status
codes
example:

are

@ of
RZ will

always

R®

that
BLBC

Program
tested

VDS

$SQI0O G

CMPLTM
BNEQ

I/0 request.

;Enqueue

QIO ARGLIST

|
R@, #SS$ NORMAL ;If success, then continue.
;:Else branch to the error handler.
QIO ERROR
;Continue

CONVENTIONS

USED IN THIS CHAPTER

conventions
certain
In the macro descriptions that follow,
These conventions are as follows:
been adhered to.

are
For macros that accept arguments, those arguments that
by enclosing the parameter
1indicated
been
have
optional
name

in brackets

([...]).

Iis,
That
Macro parameters are listed in positional order.
to be listed positionally, they must be
if arguments are
listed

in the order

For MACRO-32,

must

used

indicated

the macro format.

the parameter name indicates the keyword

arguments

are

specified

that

with

keywords.

letters.
then the
case
a
such

capital
1in
For BLISS-32, keywords are indicated
If a keyword is not supplied in the macro format,

macro will not accept keyword arguments.

arguments must be specified positionally.

indicate
will
parameter
macro
each
of
The description
be a
must
parameter
that
for
supplied
argument
the
whether
"value," an "address," or a "string."
e

required,
1is
wvalue
a
If
Values as arguments Thus
as a value.
interpreted
be
will
argument

the
if a

1literal
argument, that
literal is specified for the
If an
argument.
the
being
as
interpreted
be
will
address is specified, the CONTENTS of that address will
be

interpreted

as being

the

argument.

e Addresses as arguments - If an address'is required, the
be

the

interpreted

address.

argument occurs.

the
required,
is
string
Strings as arguments - If a
For
string.
literal
a
as
interpreted
be
will
argument
brackets
angle
1in
MACRO-32, strings must be enclosed
strings must be enclosed in
BLISS-32,
For
(€eoe) o
string
the
1if
and
('...'),
marks
single quotation
character it must be
(')
the
<contain
to
1is
itself
included

twice,

as in

4-6

'Debbie''s Program'.

)

N\-

will

translation

argument

have

4.3

MACROS

VDS

Some

services

require

MACROS

that

the

address

"quadword

‘descriptor"
or
"character
string
descriptor"
be passed.
For our purposes, these terms are interchangeable and
refer
to
a
quadword
that
describes
a
string
in
the manner
illustrated by Figure 4-1.

16 15

0
LENGTH OF STRING

ADDRESS OF STRING
TK-10531

Figure

String

$DS

Quadword

descriptors

directive

the

4-1

can

MACRO-32,
STRING macro.

String

the

Descriptor

generated

using

$%$ASCID directive

the

.ASCID

BLISS-32,

vDS

4.4

PROGRAM

MACROS

STRUCTURE

PROGRAM

STRUCTURE

MACROS

$DEF
The
It

SDEF macro is used to define a
1is
defined
1in the VMS system

can be

used

Section

define

p-table

field in a
data
library LIB.MLB.

desciptors,

structure.
This macro

discussed

1in

3.2.2.

MACRO-32 Format:
SDEF

sym,

BLISS-32
Not

alloc,

siz

Format:

supported

for

BLISS-32.

Sym

Symbolic name to be associated with the field.
alloc

Allocation

unit.

directives
for
directives are of

Use

one

the

MACRO-32

block

storage

this
parameter.
MACRO-32
block
storage
the form ".BLKx," such as .BLKW or .BLKQ.

siz

Size of
units
to

the

field.

This

indicates

the

number

allocation

assign.

Example:
$DEF

FIELDLI,

+RLKLy

$Field

nzmed

FIELD]

londword,

VDS

$DEFINI The

MACROS

PROGRAM

STRUCTURE

MACROS

$DEFEND

SDEFINI

and

structures.
by using the

The
S$DEF

system

1library

desciptors,

SDEFEND
fields
macro.

macros

LIB.MLB

and

discussed

are

used

define

data

within the data structure are defined
These macros are defined in
the
VMS

can

in Section

used

define

p-table

$DEFINI

3.2.2.

MACRO-32 Format:

,$DEFINIvstruc, gbl, dot
(data

structure

$DEFEND struc,
BLISS-32

field

definitions)

gbl

Format:

Not supported

for BLISS-32.

struc

Symbolic

name

that

was

assigned

the

structure

macro.

the
|

gbl
GLOBAL

symbolic

LOCAL.

name

Indicates

("struc")

will

whether

defined

the

data

globally

structure's

locally.

dot
Address
symbol

the

defined

first
by

field

the

value.

Subsequent

fields

memory

addresses.

The

512),

symbol

symbolic

must

within

first

(for

defined

SDEF

are

assigned

argument

example,

before

the

macro

be
the

structure.
The
assigned to this
next
sequential

numeric
(for example,
BLOCK ADDR).
If symbolic,
the

the

can

data
will
be

$SDEFINI

macro

call.

vDS

MACROS

PROGRAM

STRUCTURE

MACROS

structure

named

Example:

$DEFINI

TARLE1ls

GLORAL,

$NEF

FIELDl,

BLKLy

.EBLKEs

FNEF

FIELDYZ2y

$NEFEND

TABLE,

example,

this

been
FIELD]1

defined
starts

longwords.

OFFSET

GLORAL

to
at

global

data

contain

two

location

FIELD2

fields,

called

TABLEl1l+OFFSET

immediately

long.

follows

"TABLEl"

FIELDl

and

FIELDl

and

consists

and

has

FIELD2.
one

byte

VDS

MACROS

PROGRAM

STRUCTURE

MACROS

$DS_$ADD
The $DS SADD p-table
descriptor
macro
contents
of
the "value register"
(see
of

the

addition

field

1is

p-table

being

performed,

built.

and

the

1is
wused
to
add
the
Section 3.2.3.3)
into a

The

field

result

1is

placed

fetched,

the

back

the

into

field.

Macro-32

Format:

$DS _SADD

(offset,

pos,

size)

'Bliss-32 Format:
$DS_SADD

(OFFSET=offset,

POS=pos,

offset

into

p-table

value

SIZ=size);

offset
The

byte

contents

the

are

the

field

added.

which

the

pos

Bit

position
of

the

field,

byte
specified
by
boundary, this value

relative

"offset."
will be 0.

the

beginning

field

starts

the

byte

size
Number

than

bits

making

the

field.

The

size

cannot

larger

32.

Notes:

Bits

added

(or

The

Code generated by macro (shown in

contents of

carried)

beyond

the value

the

field

are

width

are

lost.

not changed.

Macro-32;

Bliss-32

Beginning

Word

structure

pos
size

;

Wme

.BYTE
.BYTE

offset

“X8A

.WORD

.BYTE

"equivalent):

Bit
Bit

data

ADD directive

position in
field size

word

offset

VDS

MACROS

PROGRAM

STRUCTURE

MACROS

Examples:

Macro-32

Examples:

$NS_$ADD

OFFSET=HF$A.DEVICEs

$OS_$ADD

STX40xy

Bliss-32

FOS=0,

SIZE=32

Examples:

$0S.¢ADD
|

(OFFSET=XFIELDEXFAND(HF$A_DEVICE,O)
FOS=XFIELDEXPAND(HF$A_DEVICE»1)»

$NS.$ANN

(OFFSET=%X‘40’y

SIZE=XFIELDEXFAND(HF$A_DEVICE2))
%

POS=0y

SI1Z=32)5

VDS

MACROS

PROGRAM

STRUCTURE

MACROS

$DS_$CASE
The

$SDS SCASE

current
and then

old

p-table

the

The

first

second
no

not

Macro-32

wvalue
of

$DS SCASE macro
value

each

pair

1is

matches

may be
the

the

There

pair

wused

used

contents

until
then

any number

value

test

the

with

found;

1into

pairs

3.2.3.3)
on
the

compared

match
is

then

the

specify pairs

are

1loaded

altered.

the

wvalue

case

1list.

value

will

Bliss-32

1is

Format:

$DS_SCASE
Bliss-32

The

current

value

macro

contents of the "value register"
(see Section
load a new value into the register, depending

contents.

values.

descriptor

<<case pair>,

[<case pair>,

...]>

[ (case pair),

...1):

Format:

SDS_SCASE

((case pair),

case pair

A pair of values, separated by a comma.
stored

Each

longword.

Notes:

Code

generated

by macro

(shown

Macro-32;

. LONG

matchl,

/",/—...\

. LONG

match-n,

valuel

~X8C

. BYTE

Beginning

.BYTE

Number

case

equivalent):

First

case

pair

;

Other

case

pairs

Last

(nth)

case

value-n;

CASE
pairs

pair

VDS

MACROS

192>y

PROGRAM

STRUCTURE

MACROS

Examples:

Macro-32

Example:

$NS_$CASE

<
L

$NS_$CASE

<<l sy <" XFFFFF2>2>9
<2+ <" XFFFEFFFF:>

Bliss-32 Example:
$DS_$CASE

(
(1+2)»

(223)s
(2v4))»
$NOS_$CASE

((12ZX'FFFFF
)y (2sXX'FFFEFFFF‘)) 3

4-14

VDS

MACROS

PROGRAM

STRUCTURE

MACROS

$DS_$COMPLEMENT
This
of

p-table

the

value

descriptor

macro

complements

the

current

contents

Macro-32 Format:

$DS_$COMPLEMENT
Bliss-32

Format:

$DS_$COMPLEMENT;

Notes:

Code generated

by macro

(shown

Macro-32;

equivalent) :

;

.BYTE "X89

;

Bliss-32

1is
|

Complement value register

VDS

MACROS

PROGRAM

STRUCTURE MACROS

$DS_$DECIMAL
This p-table descriptor macro reads a
value
from
the
ATTACH
command
1line.
If
no
more
parameters
are available on the

command line, or
it
will
prompt

if the next parameter is not a decimal
wvalue,
the operator with the prompt text value.
The

value that is read
Section
3.2.3.3)

is
for

$DS SCASE statement.

Macro-32

Format:

$DS_SDECIMAL
Bliss-32

stored
1in
the
"value
register"
(see
use by a $DS _SCOMPLEMENT, S$DS_SSTORE, or
-

<prompt>,

low,

high

Format:

$DS SDECIMAL
prompt

(PROMPT='prompt',

LOW=low,

HIGH=high);

Character

string

printed

This
prompt
will
be used
contain the required value.

that

the

prompt

ATTACH command

line

the

user.

does

not

low

The low limit for the value.
1If the value given is lower
than
this,
an
error message followed by the prompt message will be
displayed.
The default radix for this value is decimal.
high
The

high 1limit for the value.
If the
wvalue
given
1is
higher
than this, an error message followed by the prompt message will
be displayed.
The default radix for this value is decimal.

Notes:

Code generated by macro (shown

equivalent):

"X82
\prompt\
low
high

.BYTE
.ASCIC
. LONG
. LONG

Macro-32;

Bliss-32

Beginning of DECIMAL prompt
Prompt string
Low 1limit
High limit

1is

VDS MACROS - PROGRAM STRUCTURE MACROS

Examples:
Macro-32

Example:

$NS_$DECIMAL TRs 1» 15
$0S_$DECIMAL FROMFT=<NUMBER OF ARRAY CARDS>y

Bliss—-32 Example:

LOW=0y

HIGH=15

$NS_$DECIMAL (FROMPT='TR‘, LOW=1s HIGH=15);

¢NS_$DECIMAL

(FROMFT='NUMBER OF ARRAY CARDS’,

LOW=0,

HIGH=13)3}

VDS MACROS

PROGRAM STRUCTURE MACROS

$DS_SEND
The

$DS_S$END macro

Macro-32

used

terminate a

p-table descriptor.

Format:

$DS_SEND
Bliss-32

Format:

$DS_SEND;

Notes:

Code

generated

by macro

(shown

Macro-32;

equivalent):

.BYTE

"X81

;

End

p-table

descriptor

Bliss—-32

VDS

MACROS

PROGRAM

STRUCTURE

used

p-table

MACROS

$DS_S$FETCH
The

$DS SFETCH macro

extract

the

contents,

Section

contents

a field

right-justified,

3.2.3.3).

the

"value

descriptors.

within

possible

will

and

store

(see

p-table,

reference

device-dependent
field
that
was
filled
with
a
$DS_S$STORE
macro,
or device-independent field that

previous
was filled
by the VDS.
The macro can also be used to facilitate temporary
storage,
by
storing
a
wvalue
in the p-table while the wvalue
register is needed for something else, then restoring
the
old

value.

Macro-32

$DS

Format:

SFETCH offset,

Bliss-32

pos,

size

Format:

$DS_S$FETCH

(OFFSET=offset,

offset

POS=pos,

SIZE=size);

The byte offset into the p—-table of the field
contents

are

fetched.

position

the

field,

specified

from

which

the

pos

Bit

byte

boundary,

relative

"offset."

this

value

will

bits

making

the

beginning

field

field.

The

starts

the

byte

size
Number

than

size

cannot

1larger

32.

Notes:

Code

generated

by macro

(shown

Macro-32;

Bliss-32

equivalent):

. BYTE

“X87

;

Beginning

«WORD

offset

;

Word

.BYTE

pos

;

Bit

position

.BYTE

size

;

Bit

field

FETCH

directive

data structure

size

word

offset

VDS

MACROS

PROGRAM

STRUCTURE MACROS

Examples:

Macro-32

Example:

$NS_.$FETCH

OFFSET=HF$A_DIVA,

FO0S=0y

SIZE=32

$NS_$FETCH <"%40%, Oy 32
Bliss-32

Example:

$NS_$FETCH (0FFSET=ZFIELDEXPAND(HP$A-BUA70),

FOS=XFIELDEXFAND(HF$A_DVAy1)»
)}
SIZE=ZFIELDEXFPAND(HF$A_DVA»2)

$DS_$FETCH

(OFFSET=ZX7407,

FOS=0y

SIZ=32)%

VDS

MACROS

PROGRAM

STRUCTURE

MACROS

$DS_SHEX
The

from

$DS

SHEX p-table

the

ATTACH

available
a

hex

value.
(see

the

wvalue,

The

wuser

that

3.2.3.3)

$DS_S$CASE

Macro-32

command
the

value

Section

descriptor

command

macro

line.

used

parameter

1line,

will

prompted

read

for

use

is
by

the

left
a

read

with

the

value

parameters are
the

not

prompt

text

"value

$DS_SCOMPLEMENT,

statement.

Format:

$DS_ SHEX <prompt>, low, high
Bliss-32

Format:

$DS_SHEX (PROMPT='prompt', LOW=1ow, HIGH=high);
prompt

“

Character string that is to
This
prompt
will
be used

contain

the

required

printed

the

ATTACH

prompt

command

value.

to
line

the

user.

does

not

low
The

low

this,

limit

for

error

displayed.

For

hexadecimal.

the value.
If the
message followed by

MACRO-32,

For

the

BLISS-32,

default

the

value given is lower
than
the prompt message will be

radix

default

for

radix

this

wvalue

decimal.

high

The

high

than

be
1s

limit

this,

for

the value.

error

message

If the
wvalue
given
1is
higher
followed by the prompt message will

displayed.
©For MACRO-32, the default radix for
hexadecimal.
For BLISS-32, the default radix is

this

wvalue

decimal.

PROGRAM

STRUCTURE

MACROS

Notes:

Code generated by macro (shown in

Macro-32;

Bliss—-32

equivalent):

: Beginning of HEX prompt
Prompt string
Low limit
High limit

~X84
\prompt\
“X<low>
"“X<high>

. BYTE
.ASCIC
. LONG
.LONG

WMy

MACROS

VDS

Examples:

Macro-32 Example:

$0S_$HEX <WCS Last address>s0sFFFO
Bliss-32 Example:

$NS_$HEX (FROMPT=‘UCS Last address’y LOW=0y HIGH=ZX'FFFO’)3

MACROS

PROGRAM

STRUCTURE

MACROS

VDS

$DS_S$INITIALIZE
The

$DS_SINITIALIZE

macro

every

p-table

descriptor

descriptor.

macro

must

used

the

the
number
of
the device
reference
-

device type, the p-table's total size, the
maximum
units
allowed
by
the
hardware,
and
the name of
driver required for a level 2 diagnostic program
to
the device.

MACRO-32

Format:

$DS SINITIALIZE
BLISS-32

first

indicate

device,

length,

max,

driver

Format:

$DS_$INITIALIZE

(DEVICE=device,

LENGTH=length,

MAX=max,

DRIVER=driver)
;

device

//’—\\

Character

string

being

described

RH780,

and

representing

on.

the

The

the

string

that
the
user
must
command, as in "ATTACH

device

p-table,

specified

type as
RKo6l1l",

the

type

such

here

first

the

RK611l,

hardware

RK@6,

RM@3,

will

the

string

argument
|

the

ATTACH

length
The

length

The

(in

length

bytes)

device-dependent

value

1is

1includes

fields.

<created

specifications,

the

p-table

both

with

the

Generally,

that

1is

symbolic

SDEF macro during

illustrated

created.

device-independent

Section

name

and

the

for

this

memory allocation

3.2.2.3.

max

The

maximum

controlled

number
by

the

units

that

hardware

would
be 8 for an RK@7, since
RKO7 drives that can exist on

Some

devices,

assigned

unit

such

number.

can

design.

that
an

RK711l

controllers

For

these

exist.
For

the

This

number

example,

the

maximum

number

are

not

controller.

and

cases,

adapters,

"max"

should

VDS

If this value
not used, the

MACROS

PROGRAM

STRUCTURE

MACROS

is greater than 0, and if the $DS SNAME macro
is
device's generic name will be required to contain

a unit number.
If, on the other hand, the $DS SNAME
macro
used,
then
whether
or
not *a
wunit
number must be typed
controlled by the $DS SNAME statement.
The

default

value

for

"max"

1is

is
is

driver

The

name

the

QIO

driver

(if

any)

needed

1level

diagnostic
programs
in
order
to
reference the device.
The
value must be a string of two characters.
The
string
given,
'dn',
determines
the driver loaded as follows:
the string is
appended
' EXE'.

to the string 'EVQ' and
followed
by
the
Thus the driver's filename is 'EVQdn.EXE'.

file
|

type

Notes:

Code generated by macro

(shown

Macro-32;

Bliss-32

1is

equivalent):
TM

~X80

.WORD

WTMy

.BYTE

;

Length
Max Units

“A"Driver"

ASCIC

device

type

Length of p-table
Maximum unit number

WEe

\Device\

.BYTE
.BYTE

Driver

suffix

.ASCIC

End

initialization

statement

Examples:

Macro-32

Examples:

$OS_$INITIALIZE

DEVICE=DMC11, LENGTH=HF$K_DOMC11_LEN, -

DRIVER=<XM>
$DS_$INITIALIZE

DEVICE=DW780, LENGTH=HF$K_DW780_LENy -

RKé611y

HF$K_RK&611_LENs

r—

$NS_$INITIALIZE

MAX=3

VDS

Bliss-32

MACROS

PROGRAM

STRUCTURE

MACROS

Examples:

$DS_$INITIALIZE (DEVICE="DMC11’.
LENGTH=HF$K_DMC11_LEN>
¥
DRIVER="XM’)

$OS_$INITIALIZE (DEVICE='DW7807,
LENGTH=HF$K_DW780_LEN>
MAX=3)5

$0S_$INITIALIZE (DEVICE=‘RK611‘sy LENGTH=HF$K_RK&611_LEN);

MACROS

PROGRAM STRUCTURE MACROS
//a“n\u

VDS

$DS_SLITERAL
This p-table descriptor macro is used to load a

literal

wvalue

(see

This value can then be manipulated by
into the value register.
a $DS_SCOMPLEMENT, $DS_SSTORE, or S$DS_SCASE statement.
Macro-32

Format:

$DS_SLITERAL 1it
Bliss-32

Format:

$DS_S$LITERAL

Value

(LIT=1lit);

(longword)

Section

to be loaded into the

"value

3.2.3.3).

Notes:

Code generated by macro

(shown in

Macro-32;

equivalent):

. BYTE
.LONG

"X86
litl

Examples:

Macro-32 Examples:

‘$DS,$LITERAL LIT="XFF
$DS_$LITERAL 0776
Bliss-32

Examples:

$NS_$LITERAL

(LIT=XX'FF7)3

$NS_$LITERAL

(LIT=X0°7767)3%

; Beginning of LITERAL
; Literal value

Bliss-32
'

VDS

MACROS

PROGRAM

STRUCTURE

MACROS

$DS_$LOGICAL
This

p-table

response

one

may

with
was

the

descriptor

from

'YES'

or lower

the

macro is used
command line.

ATTACH

strings

upper

'NO'.

case.

response

was

to read a "yes"
or
"no"
The expected response is

They may

abbreviated,

The

value

"no,"

"yes."

with

will

the

and

loaded

response
|

Macro-32 Format:
*DS_SLOGICAL <prompt_>
Bliss-32 Format:

$DS_SLOGICAL

(PROMPT='prompt');

prompt

A character
displayed

string

the

representing

ATTACH

command

the

prompting

processing

message

routine
of

the

.be

VDS.

Notes:

Code

generated

by macro

(shown

equivalent):

Macro-32;

.BYTE

~“X8B

;

Beginning

.ASCIC

\prompt\

;

Prompt

Examples:

Macro-32

Examples:

$NS_$LOGICAL

<Load

WCS_.>

Bliss-32 Ekamples:
$0S_$LOGICAL (PROMPT='Load WCS’);}

string

Bliss-32

LOGICAL prompt

1is

VDS

MACROS

PROGRAM

STRUCTURE MACROS

$DS_$SNAME
The $DS_$NAME p-table descriptor macro

is used

device

name

used, the macro must immediately
If
desired.
1s
validation
present,
When this macro is
follow the $DS SINITIALIZE macro.
ATTACH
the
argument to
third
(the
name
generic
device
the
specified.
conventions
naming
the
to
command) must conform
(See

note

for

exceptions.)

All device names
can
be
described
by
the
general
formula
where 'gg' is a generic device prefix (not necessarily
'ggan';
which
representing
1letter
a
is
'a'
characters),
only two

or bus adapter the device is on, and 'n' represents
controller
Both
adapter.
the device's unit number on that controller or
must
'n' portions are optional, but every device
'a' and
the
the
by
fixed
For most devices, 'gg' is
have a 'gg' portion.
physical
type
of the device;
or, it may be determined by its
LINK device (the controller to
which
it
1is
attached).
The
$DS_$NAME
statement
allows
specification
and enforcement of
these

Macro-32

rules.

Format:

$DS_SNAME

flags,

Bliss—-32 Format:
$SDS_$SNAME

generic

(FLAGS=flags,

GENERIC=generic);

flags

Flag

bits that control

names
flag

for

bits

the

format of

the

device

name.

Symbolic

the flags are defined by the $DS PTDDEF macro.

are:

The

Bit 0 - PTDSM UNIT - The 'n' portion of the generic name is
required
for
this device.
Its maximum value is specified
by the "max" parameter of the $DS SINITIALIZE macro.

Bit 1 - PTD$M CONTROLLER - The

name

required

for

'a'

this

portion of

device.

the

generic

the

bit

match
must
PTDSM INHERIT CON is also set, the 'a' portion
is
device
this
which
to
controller
portion of the
the Ta'

attached.

VDS

Bit

name

MACROS

PROGRAM

Only

PTDSMNAME

required.

This

which

are

STAR,

GALAXY).

known

the

their

STRUCTURE

'gg'

most

DECnet

portion

common

for

names

(for

Bit

3 - PTDSM_INHERIT
PRE - The 'gg'
inherited
from
the
controller
to

‘attached.
name

'TXan'

This,

the

when

VT1PP

DZ1l1l

attached

Bits

to require

'TTA',

set

any

Additionally,
common

sets

two

the

generic

network

devices,

example,

device

name

which

the

YODA,

prefix

device

is
is

('TTa'),

allows
a VT100 to

attached

DMF32A

name

these

require

DZ1ll

('TXa').

- This

for

names

DEVICE

UNIT.

This

combines

when

DZ11

attached

'TTB'.

and

defined

that

must

not

the

bits PTD$M INHERIT PRE
the

normal

bits

PTD$M

commonly be

a bus,

combine

are:

the

This

combines

would

'TTAn'

expan51on

are

They

bits.

PTD$M

form

future

bits.

INHERIT CON.

PTDSM

the

attached

descriptor.

special
flag

when

reserved

therefore
require both
inherit them from their

used

rather

permutation

CONTROLLER

for devices
but

and

that are

than a controller,

'a' and 'n' portions
LINK device.

should

and

not

PTD$M_ENDDEVICE - This combines the bits
PTDSM CONTROLLER,
PTDSM_UNIT,
and
PTDSM INHERIT.
It would commonly be used
for dev1ces that have controllers, such as an RK@7 that
is

attached
name

The

'"TTBn'

connec ted dlrectly to

when

p-table

several

PTD$M

the

are

PTDSM_INHERIT
and

example,

'TTan'

Bit 4 - PTDSM INHERIT CON - The 'a'
controller
designator
portion of the device name is inherited from the controller
to which the device is attached.
This, for example, allows

for

form

MACROS

prefix

default

and

RK711l,

and

controller

should

inherit

the

controller's

letter.

PTDSM DEVICE.

generic

The 'gg'
portion
PTDSM_INHERIT PRE

device

linked

required
is
set,

HUB.

for
this

this

device.
If
the
flag
argument is used only if the
|

- PROGRAM STRUCTURE MACROS

VDS MACROS

Notes:'

1. The naming conventions specified with the $DS $NAME will be
ignored if the VDS is running under APT, or if the VDS is
executing a script file. This is to ensure compatability
with APT scripts and VDS
proper naming conventions.

Code generated by macro (shown in

equivalent):

.BYTE
.ASCIC

“X8D

flags
"generic"

Macro-32;

Bliss-32

of NAME statment
s+ Start

me
W

.BYTE

scripts that do not adhere to
|

Generic name format flags
Enforced generic name.

Examples:

Macro-32 Examples:
$NS_$NAME FLAGS=FTO$M_ENDODEVICEs GENERIC=DM

$DS_$NAME PTD$M_UNIT, DM

Bliss-32 Examples:
DS _$NAME (FLAGS=(PTD$M-ENDDEUICE); GENERICz'DM')i
$NS_$NAME (FLAGS=(PTD$M.UNIT)y» GENERIC='KA‘);

1is

VDS

MAC
-ROS
PROGRAM

STRUCTURE

MACROS

$DS_$OCTAL
The $DS_SOCTAL p-table
ATTACH
command
line.
the

command

value,

the

The value
Section

$DS

is
no

the

used
more

read

3.2.3.3)

for

use

will

stored
by

to read a
parameters

parameter

message

the

value
are

1is

displayed

"value

from

the

available

not

$DS_$COMPLEMENT,

statement.

on
octal

the

user.

(see

SDS_SSTORE,

Format:

$DS_ SOCTAL
Bliss-32

prompting

that

$SCASE

Macro-32

line,

macro

prompt,

low,

Format:

high
|

$DS_$OCTAL (PROMPT%prompt, LOW=1ow, HIGH=high);
prompt

Character strihg that is to bé printed as a prohpt to thé user.

This
|

|
/

prompt

contain

the

will

required

used

the

ATTACH

command

line

does

value.

not

low
The

low

this,

limit

for

the

value.

error

message

displayed.

For

MACRO-32,

octal.

BLISS-32,

For

the

followed

the

default

value

the

radix

given

prompt
is

lower

message

this

than

will

value

decimal.

high
The

high

limit

for the value.
1If the
value
given
is
higher
an error message followed by the prompt message will
be displayed.
For MACRO-32, the default radix of this value is
octal.
For BLISS-32, the default radix is decimal.

than

this,

4-31

VDS MACROS - PROGRAM STRUCTURE MACROS
Notes:

Code generatedlby macro (shown in

Macro-32;

Bliss-32

equivalent):

\prompt\
“"0<1low>
~O<high>

.ASCIC
. LONG
.LONG

; Beginning of OCTAL prompt

“X83

.BYTE

Prompt string
Low limit
High limit

Examples#
Macro-32 Exémples:
$NS_$0CTAL

CSR»760000+s777776

$0S.$0CTAL FPROMPT=<VECTOR_.>,

LOW=2, HIGH=776

Bliss—-32 Examplés:
$0S_$0CTAL (FROMPT=‘CSR’» LOW=XZ0’'760000’» HIGH=X0'777776")%
$DS_$0CTAL (PROMPT=‘VECTOR’,» LOW=%0‘2’, HIGH=Z0'7767)}

VDS

MACROS

PROGRAM

STRUCTURE

MACROS

$DS_$STORE
The

$DS_SSTORE p-table

contents
field of
store

values

SDS_SSTRING,

$SDS_SLITERAL,
statements.

while
not

read

can

value

value
the

the

$DS

(see

The

macro

S$SDECIMAL,

be
be

with

$DS

the

contents

can

$DS

used

stored

needed

for

$FETCH

the

$SOCTAL,

$DS

a
to

S$SHEX,

the

or $DS SCASE

facilitate
the

the

into

used

generated

p-table

something

statement.

value

1load

3.2.3.3)

$DS_S$COMPLEMENT,

also
can

wused

Section

SLOGICAL statements,

$DS_S$FETCH,

restored

change

$DS

It
A

the

later

macro

"value register"
p-table being built.

the

storage.

descriptor

the

temporary
temporarily

else,

This

then

macro

does

which

the

Macro-32 Format:
SDS_S$STORE
Bliss-32

offset,

pos,

size

Format:

$DS_$STORE

(OFFSET=0ffset,

POS=pos,

SIZE=size);

offset
The

byte

contents

offset

into

value

the

p-table

are

the
to

field

1into

placed.

pos

Bit

position

byte

the

specified

boundary,

field,

relativto
e

"offset."

this

value

will

bits

making

the

beginning

field

starts

the
byte

size
Number

than

field.

The

32.

size

cannot

larger

Notes:

+BYTE

FOS

+BYTE

size

~X88

offset

Macro-32;

Bedinning

Ewr

+BYTE

+WORD

(shown in

Word

Code generated by macro
equivalent)
:

Rit

rosition

Rit

field

data

structure

STORE
in

size

Bliss-32
directive

word

offset

1is

VDS MACROS - PROGRAM STRUCTURE MACROS

Macro-32

Examples:

0FFSET=HP$LNRK611,CSR, F0OS=0,» SIZE=32
|
ZoXA0Fy Os 32

$NS_$STORE
$DS_$STORE
Bliss—-32

Examples:

$0S_$STORE (OFFSET=%FIELDEXFAND(HFP$L_RK611_CSRs0)»
FOS=%FIELDEXFAND(HPSL _RK611_CSRr1)»
SIZE=ZFIELDEXPAND(HP$L-RK61I-CSR:E))3

$0S_$STORE (OFFSET=%X‘40‘, F0S=0y SIZ=32)3

VDS

MACROS

PROGRAM

STRUCTURE

MACROS

$DS_$STRING
The $DS SSTRING p-table descriptor macro
is
wused
to
read
a
string
from
an
ATTACH command line.
If the string exists on
the ATTACH command
1line,
it
will
be
wused;
otherwise
the
prompting

message

command line
the
number

order

given)

used,

for

tested

will

compared against a list
the
match
string (4,

returned

example,

'EIA'

Macro-32

the

value

determine

'20MA',

which

response

was

string

read

from

the

of
1,

valid
2, and

strings,
so on, in

and
the

This

DZ-11

the

statement

would

return

can

line card

"S$SDS_SSTRING
the

20MA.

('Line

response

was

<prompt
>,

<string,

[string,

...]
>

Format:

SSTRING

('prompt',

'string',

['string',

...]);

prompt

Character string to be used as a prompting message.
string

A character string
compared.
the input

with

which the

The number of the
will be returned.

first

input
string

string
that

exactly matches

Notes:

Code

generated
by

macro

(shown

Macro-32;

«BYTE

~X85

Beginning

.ASCIC

\prompt\

Prompt

.ASCIC

\stringl\

ASCIC

;

ASCIC strings

\stringn\
Y

;
;

ASCIC string n
List terminator

.ASCIC
.BYTE

Bliss=32

|
TMo

equivalent):

TMo

WMo

/'/

\\‘.

$DS

The

Format:

$DS SSTRING
Bliss-32

displayed.

is
of

type','EIA','20MA"')"
EIA,

STRING

string
string

prompt

1is

VDS

MACROS -

PROGRAM

STRUCTURE MACROS

Examples:

Macro-32 Examples:

$NSHSTRING <Module turers

<20MA:

<<EIAXy

$05$5TRING FROMPT=<Node turex, STRINGSzi?80y750,?30}
Bliss-32

Examples:

$NS.$STRING

('Module ture’s

$N5_$STRING

(/Node ture’s

‘EIA’y

‘7807,

“20MA7):

77307y

77307)%

VDS

MACROS

PROGRAM

STRUCTURE

MACROS

$DS_BGNCLEAN - $DS_ENDCLEAN
The

$DS BGNCLEAN and $DS _ENDCLEAN macros are
used
program's
clean-up
code.
These
macros

the

connections

which

execute

clean-up

MACRO-32

the

make

possible

delimit

create
1locate

the
and

for

the

VDS

names

placed

for

MACRO-32

. PSECT

the

argument

string

code.

Format:

$DS _BGNCLEAN

[<regmask>],

[<psect>]

»(clean—up code)
$DS_ENDCLEAN
BLISS-32 Format:
$DS_BGNCLEAN;
(clean-up

code);

$DS_ENDCLEAN;
r egmask
List

~entry

general

purpose

the

mask.

psect

Any argument

string

statement.

"CLEANUP, LONG"

that

none

will

is
1is

valid

specified,

used.

Notes:

In MACRO-32,

the

following code:

$DS BGNCLEAN

. SAVE

. PSECT

psect

CLEAN UP:

.WORD

“"M<regmask>

macro

will

generate

the

MACROS

In MACRO-32,

the

STRUCTURE

$DS ENDCLEAN

code:

following

PROGRAM

MACROS

macro will

generate

the

macro

will

generate

the

will

generate

the

CLEAN
UP X:

$DS BREAK

RET

. RESTORE

In BLISS-32,

the

$DS BGNCLEAN

code:

following

$SBTTL

PSECT CODE

UP'

'CLEAN

CLEANUP (WRITE);

GLOBAL ROUTINE

CLEAN UP:NOVALUE

BEGIN

In BLISS-32,
the
following code:

$DS ENDCLEAN

macro

END

Examples:

MACRO-32
NS

Example:

REGNOLEAN

“R2/R3E4yRTxy

<CLEANSECT» LONG:

[
4

FNG LENDCLEAN

BLISS-32 Example:
$05 BGNCLEANS
&

$05 ENUCLEANS

4-38

//m\\\

VDS

MACROS

PROGRAM

STRUCTURE

MACROS

$DS_BGNDATA - $DS_ENDDATA
The

$DS_BGNDATA and $DS _ENDDATA macros
1lists of input arguments to a

provide

executes

test

for

which

argument

are used
to
optionally
test.
Each time the VDS

lists

have

been

specified,

will

execute the code within the test once for each argument
list.
From the user's point of view, this
repeated
execution
of
the
code
within a test will appear to be one execution of
the

test.

The

SDS_BGNDATA

immediately
the

parameter

MACRO-32

$DS

and

before
lists

$DS
the

ENDDATA

$DS

macros

must

BGNTEST macro
of

the

located

test

which

belong.

Format:

BGNDATA

[align]

argument-list

$DS_ENDDATA

‘

‘/

[argument-list]

BLISS-32

This

Format:

macro

not

supported

for

BLISS-32.

align
Desired

alignment

Possible

values

from
at

the

power

1If

the

for

are

the

psect

containing

BYTE,

WORD,

LONG,

integer

address

that

QUAD,

the

argument

PAGE,

is specified, the
is a multiple of

psect will
two raised

1lists.
integer

start
to the

integer.

argument-list

list

occupy

shown

arguments

longword.
Figure

4-2.

used

the

Each parameter

test.

Each

list must be

argument

must

formatted

VDS MACROS - PROGRAM STRUCTURE MA@RQS

31
N

ARGUMENT 1
ARGUMENT 2
®

o=_

e
®

ARGUMENT N
TK-10532

Figure 4-2
The

Argument List Format for $DS BGNDATA - SDS_ENDDATA

$DSENDDATA will provide

by generatlng

longword

termination for

Notes:

the set

1lists

0@.

The VDS will call the test code with a CALLG
instruction.
the address of the next
called,
1is
test
the
time
instruction's
CALLG
the
as
used
be
argument list will
be
can
arguments
the
Thus
parameter.
list
argument
AP.
the
from
offsets
by
test
referenced within the
Each

Example:

NS .LBGNIOATA

s LONDG
«LONG
s LONG

4y
4y
4y

DATA_1» DATA.Z2y
Sy DATALSy
DATA.
DATA.1s DATA.3s

DATA.L3»
DATA.7»
DATA.7»

[DATA_4
DATA.LB
DATA.?

. ENDDATA
CEDS

4-40

VDS

MACROS

PROGRAM

STRUCTURE

MACROS

$DS_BGNINIT - $DS_ENDINIT
The

$DS_BGNINIT and

diagnostic
the

connections

~execute

MACRO-32

$DS

program's

the

that

ENDINIT macros

are

initialization code.
make

initialization

possible

used

delimit

These macros

the

create

for

the

placed

MACRO-32

.PSECT

the

argument

string

VDS

locate

and

code.

Format:

$DS_BGNINIT

[<regmask >],

[<psect >]

(initialization‘code)
$DS_ENDINIT
BLISS-32

Format:

SDS BGNINIT;
(initialization

code);

r egmask

'\<

$DS_ENDINIT;

List

entry

general

purpose

reglster

names

mask.

the

psect

Any

argument

statement.

string
If

that

none

"INITIALIZE,LONG"

will

is
is

wvalid

for

specified,

used.

Notes:

MACRO-32,

following

the

$DS

BGNINIT

code:

macro

will

generate

the

macro

will

generate

the

. SAVE
. PSECT

psect

INITIALIZE:

. WORD

MACRO-32,

following

the

S$DS ENDINIT

code:

"M<regmask>

VDS MACROS

X:
INITIALIZE
$DS

- PROGRAM STRUCTURE MACROS

BREAK

RET

. RESTORE

BLISS-32,

following

code:

SSBTTL

the

$DS BGNINIT

macro

Wwill

generate

the

generate

the

'INITIALIZE'

PSECT CODE = INITIALIZE (WRITE);
GLOBAL ROUTINE INITIALIZE : NOVALUE =
BEGIN

In BLISS-32,
following

code:

the

S$DS ENDINIT

macro

$DS_BREAK;
END

Examples:

MACRO-32 Example:

$015 BGNINTT <R2yR3IsRAyRExy SINITSECT»LONG:
¢
¢

£TS_ENDINTT
BLISS-32
BSOS

Example:

BEONINITS
¢
&

4
»

FUSENDINIT

4-42

will

VDS

MACROS

PROGRAM

STRUCTURE

MACROS

$DS_BGNMESSAGE - $DS_ENDMESSAGE
The $DS_BGNMESSAGE and $DS ENDMESSAGE macros should be used

delimit
the

each

error

MACRO-32

error reporting routine used
reporting macros ($DS_ERRxxxx)
.

conjunction

with

Format:

$DS_BGNMESSAGE [<regmask>]
(error

reporting

routine)

$DS_ENDMESSAGE
BLISS-32

Format:

$DS_ BGNMESSAGE

(ROUTINE_NAME=routine name) ;

(error reporting routine) ;
$DS_ENDMESSAGE;
regmask

List

general

purpose

associated

names

placed

entry mask.

the

routine name
Symbolic

name

routine.

with

the

error

reporting

Notes:

The
error
SDS_PRINTX

reporting
macros
to

routine
must
use
$DS PRINTB
and
print messages.
The most important
be
printed
first,
using
$DS PRINTB

information
should
macros.
The
most
detailed information, such
device registers, should be printed last, using
macros.

example

Refer

error

to Section
messages.

3.9.1,

Error

Further details on errorflreporting

the

description

the

error

macros

Message

routines are

as dumps of
$DS PRINTX
Formats,

for

1listed

($DS_ERRxxxx)
.

vDS MACROS - PROGRAM STRUCTURE MACROS

In MACRO-32, the $DS BGNMESSAGE macro
macro
$DS ENDMESSAGE
- The
mask.

generates an entry
RET
a
generates

instruction.

BLISS-32,

following

code:

THE

$DS BGNMESSAGE
.

macro

generates

the

(NUM, UNIT, MSGADR, PRLINK,
name) ne
GLOBAL ROUTINE 2NAME (routi
NOVALUE =
p1,

P2,

P3,

P4,

P5,

P6)

BEGIN

The $DS _ENDMESSAGE macro generates the following code:
RETURN
END

Examples:

macros (later in
Refer to the description of the $DS_ERRxxxx $SDS_B
and
GNMESSAGE
of
les
examp
for
chapter)
this
$DS_ENDMESSAGE.

VDS

MACROS

PROGRAM

STRUCTURE

MACROS

$DS_BGNMOD - $DS_ENDMOD
The

$DS_BGNMOD and

beginning
up

the

MACRO-32

and

end,

diagnostic

$DS_ENDMOD macros must be
respectively,

included

every

source

level

program.

module

the

making

Format:

$DS BGNMOD
(source

[env],

[tn],

[st]

module)

$DS_ENDMOD
BLISS-32

Format:

$DS_BGNMOD
(source

([ENV=evn],

[TEST=tn]);

module);

$DS_ENDMOD;
env

Used

indicate

this

wvalue
must
default).
NOTE:
of

program

In the
predefined

four

SEP_FUNCTIONAL,

and

the

should

not

SEP

Otherwise

program.

so,

the

value should be 8 (the
past, this parameter was assigned
one
values:
CEP_FUNCTIONAL,
CEP REPAIR,

REPAIR.

These symbols
are
meaningless
(SEP_FUNCTIONAL is equivalent to 2.)

used.

Value

in
is

representing

this

module,

the

number

this

module

assigned

contains

tests.

the

first

test

Default

value

Value

representing

subtest

this

Default

value

the

number

module,
1.

this

assigned
module

contains

the

first

subtests.
|

VDS MACROS - PROGRAM STRUCTURE MACROS

Notes:

In BLISS-32, the $DS BGNMOD and $DS_ENDMOD macros must be
contained within the bounds of " the MODULE and ELUDOM
keywords,

MODULE

follows.

modnam

BEGIN

$DS_BGNMOD

$DS_ENDMOD;
END

ELUDOM

() ;

VDS

MACROS

PROGRAM

STRUCTURE

MACROS

$DS_BGNREG - $DS_ENDREG
The

$DS_BGNREG and

storage

MACRO-32

area

$DS_ENDREG macros may be

which

device

used

contents

are

delimit

placed.

Format:

$SDS_BGNREG
(register

storage

area)

$DS_ENDREG

BLISS-32 Format:
$DS_BGNREG;
(register

storage

area);

$DS_ENDREG;

Notes:

MACRO-32,
the

$DS

BGNREG

"DEVREG:".

macro

generates

BLISS-32,

OWN

DEV REG

The

SDS_ENDREG

the

$DS

BGNREG

VECTOR

[@];

does

not

macro

generate

the

1label

generates

any

source

the

statement

code.

VDS

MACROS

STRUCTURE MACROS

PROGRAM

$DS_BGNSERV - $DS_ENDSERV
The $DS BGNSERV

and

$DS_ENDSERV

delimit interrupt service routines.

MACRO-32

macros

should be

used

Format:

$DS BGNSERV addr

service

(interrupt

routine)

$DS_ENDSERV
BLISS-32 Format:

These macros are not supported for BLISS-32.
addr

Symbolic name to

associated

with

the

interrupt

service

routine.

Notes:

The $DS BGNSERV macro will generate the following code:
ADDR:

.ALIGN

LONG,

PUSHR

# "M<RO,R1>

s+ ALIGN ON LONGWORD BOUNDARY
;

SAVE RO AND Rl

The $DS_ENDSERV macro will generate the following code:
POPR
REI

#"M<R@,R1>

; RESTORE R@ AND Rl
; RETURN FROM SERVICE

MACROS

PROGRAM

STRUCTURE

MACROS

VDS

$DS_BGNSTAT - $DS_ENDSTAT
The-$DS_BGNSTAT

and

$DS_ENDSTAT

macros

should

used

delimit the data storage area referenced by the summary routine
(see Section 3.7, Summary Routines).
This
data
area
should
contain
a
set of error counts for each unit under test.
Thus
there must be enough storage
space
allocated
to
handle
the
maximum number of device units the diagnostic program can test.

MACRO-32

Format:

$DS_BGNSTAT
(statistics

tables)

$DS_ENDSTAT

BLISS-32

Format:

$DS_BGNSTAT;
(statistics

tabiles);

$DS_ENDSTAT;

Notes:

In MACRO-32,

label

the $DS BGNSTAT

'STATISTIC:'.

The

code.

macro

simply

$DS ENDSTAT does

generates

the

not generate

any

In BLISS-32, the $DS BGNSTAT macro generates the
statement:

GLOBAL STATISTIC
The

VECTOR [@];

$DS_ENDSTAT macro

does

not

generate

any

code.

fdllowing

VDS

MACROS

PROGRAM

STRUCTURE

MACROS

$DS_BGNSUB - $DS_ENDSUB
The $DS BGNSUB and $DS _ENDSUB macros are
subtest existing in any particular test.
Tests,

MACRO-32

Subtests,

and

Sections,

for

used to
delimit
Refer to Section

discussion

each
3.8,

subtests.

Format:

$DS_BGNSUB
(subtest)

$DS_ENDSUB
BLISS-32

Format:

$DS_BGNSUB;
(subtest)
;

$DS_ENDSUB
;

Notes:

automatically

numbers

numbered

The

macro

from

for

number

subtests

within

The

$DS

BGNSUB macro

The

$DS

ENDSUB macro will

will
that

record

the

each

the

generates

subtest.

test,

where

Subtests

the

are

total

test.

call

VDS

routine that

numbers of the current test and subtest.
generate

call

VDS

routine

will verify that the current test and subtest numbers

are the
issued.

same as those stored when the $DS BGNSUB macro
If
the
numbers
do not match, the VDS will

execution

the

diagnostic

was
stop

program.

vDS

MACROS

PROGRAM

STRUCTURE

MACROS

$DS_BGNSUMMARY - $DS_ENDSUMMARY
The

$DS_BGNSUMMARY

delimit

the

Section

3.7.

summary

and

$DS ENDSUMMARY

routine.

MACRO-32 Format:

Summary

macros

routines

‘

are

used

discussed

to
in

$DS_BGNSUMMARY ([<regmask>], [<psect>]
(summary routine)
$DS_ENDSUMMARY

BLISS-32 Format:
$DS_BGNSUMMARY;
(summary

routine);

$DS_ENDSUMMARY;
|

r egmask
List

general

purpose

names

placed

the

MACRO-32

,PSECT

the

argument

string

entry mask.
psect

Any argument

string

that

statement.
If
none
is
'SUMMARY, LONG' will be used.

valid

for

specified,

Notes:

In MACRO-32, the
code:

$DS BGNSUMMARY

macro

will

generate

following

. SAVE
. PSECT

psect

SUMMARY:

WORD

“"M<regmask>

; ENTRY MASK

the

MACROS

PROGRAM

STRUCTURE

MACROS

In MACRO-32, the $DS ENDSUMMARY
following

code:

macro

will

generate

the

macro

will

generate

the

will

generate

“the

SUMMARY
X:

$DS BREAK
RET

. RESTORE

BLISS-32,

following
PSECT
GLOBAL

the

$DS BGNSUMMARY

code:
CODE

|
=

SUMMARY

ROUTINE

(WRITE);

SUMMARY

NOVALUE

BEGIN

BLISS-32,

following

the

code:

$DS_BREAK;
END

$SDS ENDSUMMARY

macro

VDS

vDS

MACROS

PROGRAM

STRUCTURE

MACROS

$DS_BGNTEST - $DS_ENDTEST
The

$DS_BGNTEST and

test
existing in a
Section 5.8, Tests,

$DS ENDTEST macros

are

used

diagnostic program.
Tests
Subtests, and Sections.

to
are

delimit

each

discussed

MACRO-32 Format:
$SDS BGNTEST [<section-name,section-name,...>],
[<regmask>],
[align]
(test

code)

$DS_ENDTEST
BLISS-32

$DS

Format:

BGNTEST

([SECTION <{section-name, sectlon name,...>J,

[TEXT='test-name']);
(test

code);

$DS_ENDTEST;
section—-name
Name

Sectlon

program

3.8,

section

Tests,

Subtests,

which
and

this

test

belongs.

Refer

the

Sections.

regmask
List
entry

general

purpose

names

placed

mask.

align
Desired

alignment

Possible

values

from @ to 9.
at
the
next

power

the

for

are

the

psect

containing

BYTE,

WORD,

LONG,

QUAD,

the

PAGE,

If an integer is specified, the
address
that is a multiple of

integer.

argument
or

psect will
two raised

1lists.
integer

start
to the

vDS

MACROS

PROGRAM

STRUCTURE

MACROS

text

Text

string identifying the
user terminal each

on
the
that the

character

user

specified

1is

has

set

the

test.
This test
time the test is

VDS

control

included within

twice,

in:

flag

the

will be
displayed
executed, provided

TRACE.

text string,

TEXT='Fred''s

test'

(In MACRO-32,

the identifying message is defined by

$DS _SUBTTL

the

(')

wusing

the

it must be

macro.)

Notes:

The

$DS BGNTEST macro

test.

The

test

will

assign

number

test

incremented

SDS_BGNTEST macro is called within a source
test number can be initialized when the $DS

called
2.

the

MACRO-32,

label

beginning

the

$DS

"xxx"

the

BGNTEST

each

the

time

the

module.
(The
BGNMOD macro is

source module.)

macro

causes

the

following

the $D8;ENDTEST macro generates the

following

generated:

TEST xxX::
where

number

JJWORD

1is

In MACRO-32,

the

“"M<

current

test

number.

code:

MOVL
TEST

nnn

#1,R@

;NORMAL

EXIT

X::

" $DS BREAK
RET

BLISS-32,

the

$DS BGNTEST macro

generates

entry point:

ENTRY

where
In

"xxx"

the

TEST_XXX,“M<
1s

BLISS-32,

the

following
|

current

test

number.

$DS_ENDTEST macro

generates

the

following

code:

$DS_BREAK;

SS$_NORMAL
END;

//«"7*"3"\\

VDS

MACROS

- PROGRAM

STRUCTURE

MACROS

$DS_CLI
The $DS CLI program structure macro is used to create
a
parse
tree.
The
tree
<can
then
be
used to parse command strings

containing commands defined
by
the
diagnostic
program
(see
Section
3.12.2.2,
Prompting
the
User).
Actual parsing of a
command
string
can
be performed
by
the
$DS PARSE
system

service.

That

constructed
A parse

time
nodes

tree

the
will

the

created

A character,

code"

will

traverse a parse tree previously

$DS CLI macro.
by using

macro
1is used, a -node
possess the following:

command

service

with

that

string

will

string

"action code"

set of

the

characters,

indicate

constitute

The address of a
turns

out

legal

that will be passed

node
to

jump to
the

created.

special

what must be next

if
there
1is
a
match between the
command
string.
Action
routines
discussion of the $DS_PARSE macro.

path

$DS CLI macros.

tree

wrong

command.

Each

Most

"traversal

to an "action

the

input

routine"

tree
are

node and the input
detailed
1in
the

the

current

one

mismatch

traversal
has

been

encountered)
.

Once the
can
be

tree has been created, the
SDS PARSE
used.
That service will start at the

system
root of

service
the tree

and traverse it, comparing an input
command
string
with
the
Each
"traversal codes" contained in each node.
or
characters
time there is a match, the
$DS PARSE
service
will
call
the
"action
routine,"
passing to
the
routine the "action code"
specified with the $DS CLI macro.
Then the next
node
1in
the
current
path will be checked.
If, on the other hand, there is
a mismatch, the system service will jump to the node
specified
as

being

the

one

a mismatch.

VDS

MACROS

PROGRAM

STRUCTURE

MACROS

MACRO-32 Format:
'$DS_CLI char,
BLISS 32

action,

miss,

[ascii]

Format:

Not implementéd'for BLISS-32.
char
l.

A character to be
input string, or

"traversal

compared

code,"

indicating

should

expected

codes

are

defined

the

discussed

in Note

the

character

which

types

input

string.

S$DS CLIDEF

the

characters

The

macro.

traversal

They

are

action

Code to be pasSed to the action routine.
called every time
the input string.

there

match

The action routine

between

the

current

node

and

mismatch

the

Address of node
current

jump to

there

1is

node.

ascii

ASCII string to be used as node content. if CLISKSTRING is used
-for "char"

(see

Note

1l).

See

examples

for

proper

format.

Notes:

The

"char"

parameter

may

the

$DS

PARSE

may

either
be a

traversal

system

code.

Its

service

what

single

ASCII

character

purpose

indicate

character,

characters,

types of characters should be expected next in

string.
macro.

The
The

the

input

traversal codes are defined by the
$DS CLIDEF
actions
that the $DS PARSE service will take

for each traversal

code are defined
as follows:

miss

vDS

MACROS

PROGRAM

STRUCTURE

CLISK ALNUM - Continue reading

alphabetic or

MACROS

input string as long

long

1long

encountered.

characters are

numeric

CLISK ALPHA - Continue

input string

reading

alphabetic characters are encountered.
CLISK NUM

- Continue

reading

input

string

Numeric characters
numeric characters are encountered.
setting
radix
default
current
must be valid for the
the
in
command
DEFAULT
SET
the
to
(refer
VAX Diagnostic

Supervisor

User's Guide.)

CLISK SYMBOL - Continue reading input string as long as
valid
symbol characters are encountered.
Valid symbol
characters are A - Z, 8 - 9, $, and .

CLISK FILE - Continue readinglinput string
as

valid

filename

characters are

characters are A-Z,
and

plus

encountered.

1long

(Filename

the wildcard characters *

%.)

CLISK SPACE - Continue reading input string as long
spaces
are
encountered.
If
no
spaces exist at
current point in the input string,
do not
<call
action routine;
branch to "miss" instead.

as
the
the

CLISK

character,

and

find next nonspace

input

COMMA - Find

see

"miss."

next nonspace

is a comma.

character,

then call

action

so,

input

routine.

Otherwise

branch

CLISK SLASH - Find next nonspace input
character,
and
see
1if
it
1is a slash (/).
If so, find next nonspace
Otherwise
routine.
input character, then call action
branch

"miss."

CLISK VALUE

- Find

next nonspace

input

character,

and

If so, find next nonspace
or an =.
it is a :
if
see
Otherwise
routine.
input character, then call action
branch

CLISK

EOL - Find

routine.

"miss."

next nonspace

1line

Otherwise

CLISK

DEC

valid

decimal

CLISK

HEX

numeric

- Continue

valid hexadecimal

character,
and

reading

string

branch

- Continue

input

terminator.
to

"miss."

input

characters are
reading

input

so,

call

see

action

1long

encountered.

string

1long

numeric characters are encountered.

vDS

MACROS

CLISKOCT

- Continue

valid octal

numeric

CLISK STRING
the

input

the

- PROGRAM

reading

"ascii"

the

parameter.

string

are

reading

matches

MACROS

input

characters

- Continue

string

STRUCTURE

input

string

character

The

1long

encountered.
as

strlng

comparison

long

specified

considered

to
be
a match even 1f only the first character of the
input string (starting at the current pointer position)

matches

the

CLISK
BR

character

Call

unconditionally

reading

CLISK BIF

address
reading
CLISK

the

action

the

input

- Call

string.

string

the

routine, then

address

specified

CALL

- Call

action

branch

"miss."

occurs.
routine,

specified by "miss" if bit
of the input string occurs.

branch
to
another
specified by "miss."

routine,

parse
Do not

then

branch

set.

unconditionally

tree.
Address
nest calls.

tree

CLISK RETURN - Call
action
routine,
then
return
to
original
parse
tree,
to
the
$DS CLI macro directly
following the macro
containing
the
CLISK CALL
code.
The
action
contents of

routine
R@ will

may

set

then

clear
saved

bit

for

of
use

r@.

The

the

CLISK BIFS macro.
CLISK BIFS

Used

action

routine,

set bit

macro.

after
then

during

(Contents

its value will
CLI$K_RETURN.)

return
branch

have

saved

subtree.

the action

processing

R@ will

been

from
i1f

had

CLISK RETURN

already

during

Call

routine
changed,

but

processing

CLISK EXIT
Call
the
action
routine,
then
stop
traversing
the
tree.
The
$DS_PARSE
system service
returns
control
to
the
<caller,
with
RO
set
to
SS$S NORMAL.
No
reading
of
the input string occurs.
This code

been

used

successfully

CLISK

ERROR

indicate

that

the

input

strlng

has

parsed.

Call

the

action

routine,

then

stop

traversing
the
returns
control

tree.
The S$SDS PARSE
system service
to
the
<caller,
with
R0
set
to

DSS

reading

ERROR.

This code

the
input
specified).

used

string

indicate
(an

the

1illegal

input

string

unsuccessful
command

occurs.

parse

string

was

Examples:

Here

command

simple

but

instructive

1language.

Suppose

example
wanted

of
to

N+
W

Figure

Add

sugar.

Add

salt.

Add

milk.

Beat
Bake

4-3

user-defined

<create

language to represent some of the steps involved
cake.
Consider just the following steps:

VDS MACROS - PROGRAM STRUCTURE MACROS

command

baking

ingredients.
cake.

illustrates

parse

tree

for

this

command

Leading spaces

TK-10533

Figure

4-3

Sample

Parse

Tree

language.

VDS

This

tree

would

MACROS

described

PROGRAM

with

STRUCTURE

SDS_CLI

macros

MACROS

follows:

NO ACTION=0

ADD=1
BAKE=2
BEAT=3

MILK=4
SALT=5
SUGAR=6

ILLCMD=7
" BADARG=8
:
TREE_ROOT:

$DS_CLI CLISK SPACE,

ADD NODE:

$DS_CLI

$DS_CLI
$DS_CLI
$DS_CLI
$DS _CLI

CLISK
CLI$K
CLI$K
CLISK
CLISK

NO_ACTION,

ADD NODE

STRING, ADD, B NODE, 'ADD'
SPACE, NO_ACTION, ILLCMDS
STRING, MILK, S_NODE, 'MILK®
EOL, NO ACTION, BADARGS
EXIT

B _NODE:

$DS CLI <"A'B'>, NO ACTION, ILLCMDS
$DS CLI CLISK STRING, BAKE, EAT NODE,
SDS CLI CLI$K EOL, NO ACTION, ILLCMDS$
$DS_CLI CLISK EXIT

EAT

;Leading

spaces

;ADD

;ADD<space>

; ADD<space>MILK
;ADD<space>MILK<cr>

; B

'AKE'

NODE:

$DS_CLI CLI$K STRING, BEAT, ILLCMDS, 'EAT’
$DS CLI CLI$K EOL, NO ACTION, ILLCMDS

;:BAKE
; BAKE<cr>

;BEAT
; BEAT<cr>

$DS_CLI CLISK EXIT
S _NODE:

SDS

CLI

<"A'S'>,

NO ACTION,

ILLCMDS$

$DS_CLI CLI$K STRING, SALT, UGAR_NODE,
$DS_CLI CLI$K EOL, NO ACTION, BADARGS
$DS_CLI CLISK EXIT
UGAR

NODE:

~ $DS_CLI CLI$K STRING, SUGAR, BADARG$,
$DS_CLI CLI$K EOL, NO ACTION, BADARGS
$DS_CLI CLISK EXIT

DONE
:

$DS_CLI

CLISK EXIT

ILLCMDS:
$DS_CLI

CLISK ERROR,

ILLCMD

BADARGS:

BADARG

$DS_CLI CLISK ERROR,

'ALT'

;ADD<space>S
; ADD<space>SALT

'UGAR'

;ADD<space>SUGAR

; ADD<space>SALT<cr>

;ADD<space>SUGAR<cr>-

VDS

MACROS

PROGRAM

STRUCTURE

MACROS

$DS_DEVTYP

The $DS DEVTYP macro is used to indicate
to the VDS which types
is capable of testing.
of devices the diagnostic program

MACRO-32

Format:

$DS_DEVTYP

BLISS-32

<[string],[stringl,...>,
<[address], [address],...>

Format:

$DS DEVTYP

([STRINGS=<string,[stringl,...>],

[ADDRESSES=<address, [address],...>]);

string

Character

string

representing

a device

type,

such as

'RK@6'

used to specify device types for
1is
parameter
This
'TM@3'.
in the VDS.
exist
which p-table descriptors
address

diagnostic
the
Address of a p-table descriptor defined within
the
within
defined
be
must
s
desciptor
P-table
programe.
diagnostic

program

if:

A p-table descriptor for the device does not exist

The
programmer
wishes
descriptor for a device.
in

Section

3.2. 2.

4-61

1in

the

to
override
the
VDS's
p—-table
P-table descriptors are discussed

VDS

MACROS

PROGRAM

STRUCTURE

Examples:
MACRO-32

Examples:

$NS_ _TNEVTYF

<RFO04y

FNH_DEVTYR

<>y <DESCE1ls

BLISS-32
NS

RFOSy

RFO&:
DESCRZ:>

Examples:

DEVTYF

POZLOEVTYR

(STRINGS=<RF04,

RFOSs

(ADDRESSES=<DESCR1s

4-62

RFO6:

DESCR2:

MACROS

VDS

MACROS

PROGRAM

STRUCTURE

MACROS

$FAB
The S$SFAB macro is used to allocate an
RMS
file
access
block
(FAB)
at
program
compilation
time
and, optionally, to load
values into the various fields within the FAB.
An
FAB
1is
a
data
structure that is required for performing file management
operations using RMS.
Refer to Section 3.15, File Management.

This description only discusses FAB
RMS.
For
the VAX/VMS

a
discussion
RMS Reference

fields

supported

of VMS RMS-supported
Manual.

fields,

VDS

refer

Besides allocating the FAB, the $FAB macro also defines symbols
for
each
FAB
field.
Symbols
are
of
the
form
"FABSdatatype fieldname,"
where
"datatype"
1is
a
data
type
specifier

MACRO-32

SFAB

listed

Table

5-1.

Format:

DNA=default-name—-address,
DNM=<default-name-filespec>,
-

DNS=default-string-size,FAC=fac—-param,
P——

FNA=filename—-address,
FNM=<filename-filespec>,
-

FNS=filename-string-size,FOP=RWO, -

FSZ=header-size,
XAB=xab-addr

BLISS-32

SFAB

Format:

(DNA=defaul t-name—-address,
DNM='defaul t-name-filespec',
DNS=default-string-size,
FAC=fac-param,

FNA=filename—-address,

FNM='filename—-filespec',
FNS=filename-string-size,
FOP=RWO,

FSZ=header—-size,

XAB=xab-addr)
;

vDS

Note:

the

All

RMS

MACROS

PROGRAM

parameters
are

run-time

STRUCTURE

optional.

services

MACROS

Refer

determine

descriptions

which

fields

are

required for which services.
Fields may be loaded at
run-time
with
the
S$FAB STORE
macro, or
by
directly referencing FAB
fields, as described in Section 3.15.4.
|
DNA

defaul t-name-address

Address of a character string representing defaults to be
for

the

filename,

incomplete.

following

The

the

default

actual

strlng

may

filename
contain

used

specification

all

some

the

DNA

is
the

fields:

Node

Device

directory

SQD - Sequential
.
tape)

4-66

device

block-oriented

(master

device

file

(magnetic

VDS

IFI

MACROS

PROGRAM

STRUCTURE

file

1identifier

Internal

associate

the

MRS

Maximum

ORG

File

FAB

with

record

internal

MACROS

field.

access

Used

block.

sigze.

organization.

Valid

values

for

this

field

files

having

are:
-

REL

IDX - Indexed file organization.'

OSEQ

Note:

Relative

Sequential

VDS

RMS

sequential
RAT

file.

a
a

discussion
diagnostic
-

file

organization.

supports

operations

attributes.

information

Refer

Record

records

organization.

RFM

only

Record

control

file

has

the

Indicates

been

VAX/VMS

RMS

of record attributes.
program will make use
format.

the

that

special

attached

to the records of
Reference Manual
for

It is unlikely
of this field.

Indicates

the

format

Possible

values

for

file.

that

this

the

field

are:

FIX

(FABSC FIX)

Fixed

VFC

(FABSC VFC)

Variable

control

record

length

format.

length

with

length

record

flxed

length

format.

VAR

(FABSC VAR)

Variable

UDF

(FABSC UDF)

Undefined

the

file

record

1is

the

record
console

format.

format.
medium-

(RT-11

format), the RFM code returned by the $OPEN service
be 4.
There is no symbolic repesentation
for
this value.

will

VDS MACROS - PROGRAM STRUCTURE MACROS

STS - Completion status code field. RMS services 1load
this field with a success or failure completion status
The
before returning to the caller of the service.
in
caller
completion status code is also passed to the
Rgo

STV - Status

additional

wvalue

status

field.

Sometimes

information

from

used

pass

a service to the

caller.

Table 4-1 1lists all of the FAB fields.

VDS

MACROS

Table
Field

PROGRAM

4-1

FAB

STRUCTURE

MACROS

Fields

and

Keyword

Field

Name

Size

Description

ALQ

Longword

Allocation

BID

Byte

Block

BKS

Byte

Bucket

Offset
quantity

FABSL

identifier
size

ALQ

FABSB

BID

FABSB

BKS
BLN

BLN

Byte

Block

BLS

length

Word

Block

FABSB

size

FABSW BLS

CTX

Longword

DEQ

Word

DEV

Longword

Device

DNA

Longword

Default

file

string
Byte

address

Default

file

FABSB

FAC

string

addr.

FABSL

FNA

string

size

FABSB FNS

DNS

Context

Default

file

extension

quantity

characteristics

specification

FAC

Byte

FNA

Longword

FNS

Byte

File

specification

FOP

Longword

FSZ

Byte

Fixed

IFI

Word

MRN

Internal

Longword

Name

MRS

Word

Maximum

NAM

ORG

Longword

Name

block

Byte

RAT

File

Byte

organization

Record

attributes

format

File-processing
control

file

block

RFM

Byte

RTV

Record

Byte

Retrieval

SDC

Longword

SHR

Spooling

Byte

File

STS

Longword

STV

Completion

Longword

Status

XAB

Longword

- Extend

size

characteristics

sharing

4-69

FOP
FSZ

FABSW

IFI

FABSL

MRN

code

NAM

FABSB

ORG

FABSB

RAT

FABSB

RFM

FABSB

RTV

FABSLTMSDC
FABSB

SHR

FABSL STS

values

attribute

FABSL
FABSB

FABSL

size

status

DNS

FABSW MRS

address

device

DNA

address

window

DEV

FABSB

identifier

record

FABSL

options

area

CTX
DEQ

FABSL

specification

string size
File access
File specification

FABSL
FABSW

FABSL STV

block

address

FABSL

XAB

MACROS

VDS

- PROGRAM STRUCTURE MACROS

Examples:

MACRO-32 Example:
$FAR

FAaBR_ _RBRLOCKS

INM=< ,EXE>y
FAC=RI0y -

FHA=FILE_NAME, FNS=FILE_NAME_SIZE

BLISS-32 Example:
(W

Fabk BLOCK

$FAR

(FAC=06GET»

)4
FNM=/EVXYZ.0DAT

VDS

MACROS

PROGRAM

STRUCTURE

MACROS

$SFAB_INIT

$FAB_STORE
The

SFAB

fields

STORE
at

programs.
Refer
to
FAB

run

and

SFAB

time.

INIT macros

The

The SFAB_INIT
the discussion

fields.

MACRO-32

SFAB

S$SFAB

can

STORE

macro

macro
is used
in
of the S$FAB macro

used
is

used

to
for

load

FAB

MACRO-32

BLISS-32
programs.
for a description of

Format:

STORE

DNA=defaul t-name-address, -

DNM=<default-name-filespec>, -

DNS=default-string-size,
FAC=fac-param,
FNA=filename—-address,
FNM=<filename-filespec>,
-

FNS=filename-string-size,
FOP=RWO,
-

FSZ=header-size,
XAB=xab-addr

BLISS-32

Format:

SFAB INIT

(DNA=default-name-address,

DNM='default-name-filespec',

DNS=default-string-size,
FAC=fac-param,
FNA=filename-address,

FNM='filename-filespec"',
FNS=filename-string-size,

FOP=RWO,

FSZ=header-size,
XAB=xab-addr)
;

Refer

input

parameters.

the

discussion

All

the

$FAB

parameters

macro

are

for

optional.

descriptions

VDS MACROS - PROGRAM STRUCTURE MACROS
Examples:

MACRO-32 Example:

$FAR.STORE
|

FNM=<FILE1.DATX>y -

AAB=XARBFHC _ADDR

BLISS-32 Example:

$FARB_INIT

(FNM='FILE1.DAT’
>
FOF=RWO)

4-72

VDS

MACROS

PROGRAM

STRUCTURE

MACROS

$DS_DISPATCH
The

$DS_DISPATCH

"dispatch
all

the

linker.)

table."

tests.

(These

The

uses

VDS

tests.

MACRO-32

macro
This

generates

table

contains

addresses

the

table

are

when

the
the

diagnostic

starting

placed

the

dispatching

program

addresses

table

the

control

the

Format:

$DS_DISPATCH
BLISS-32

Format:

$DS_DISPATCH;

Notes:

In BLISS-32 programs, the SDS_DISPATCH macro must be placed
before
the
$DS _HEADER
macro.
(Refer to the template in
Appendix
A.)

Examples:
MACRO-32

Example:

BLISS-32 Example:

VDS MACROS

PROGRAM

STRUCTURE MACROS

$DS_HEADER
The $DS HEADER macro generates the diagnostic

must

The header

(200 hexadecimal).

virtual 512

program

header.

situated so that its starting address 1is

(The diagnostic program may not

use address space below the header.)

MACRO-32 Format:

$SDS HEADER <pname>,

rev,

[update]l,

[nunit]

BLISS-32 Format:

SDS HEADER

(PNAME='pname',

REV=rev,

[UPDATE=update],

[NUNIT=nunit]);

pname

Character string representing the program's name.

is displayed on the wuser's terminal
(')
1In BLISS-32, if a
Note:
started.
it must be
included in the string,
PNAME='MARY''S

This

string

when the program is
to be
1s
<character
included twice, as in

PROGRAM',

The string should COntain the following information:
(EVKAC,

EVRAD,

and so on)

The program's name

The program's level

The

type

The

types of devices that the program can test

exerciser;

Refer

the

2R, or 3)

(2,

(logic

program

see Chapter

test,

function test,

examples below.

rev

Numeric value representing

the program revision level.

update

Numeric
default

wvalue
is

representing

the

©program

patch

level.

The

VDS

MACROS

PROGRAM

STRUCTURE

MACROS

nunit
Numeric
that

value

can be

representing

tested

the

maximum

program.

number

The

default

device
is

units

Notes:

Refer

the

location

macros

templates

the

appearing

depends

$DS
in

the

whether

Appendix

HEADER

program.

the

BLISS-32.

macro
The

program

determine

the

relation

arrangement

written

to
of

exact

other
macros

MACRO-32

Examples:
MACRO-32

Example:

$US.HEADER

FNAME

REV

NUNIT

<EVUXYZ

LEVEL

LOGIC

TEST

FOR

XXYY

DISK

CONTROLLER®,

TEST

FOR

YYZZ

TAFE

Example:

BLISS-32

$05 _HEADER

(FNAME

REV

)

NUMINT

‘EVZYX

=
1&);

LEVEL

FUNCTION

DRIV‘
E
s

vDS MACROS - PROGRAM STRUCTURE MACROS

SDS_PAGE

The $DS PAGE macro is used in conjunction

macro.

with

the

SDS _SBTTL

placed
If the $DS PAGE macro with a nonzero argument is action
s

immediately before the $DS_SBTTL macro, the following

will

1.
9.

take

place:

Printing of the $DS _SBTTL call in the assembly listing will
BTTL macro
be suppressed, but the expansion of the| $DS_S
|
|
will be printed.
The subtitle will appear at the top of a new page.

The result of these actions 1is that the .SBTTL statement
accompanying text generated by the $DS_SBTTL macro will appear
at the top of the next page in the assembly 1listing.
MACRO-32 Format:
$DS_SBTTL num

BLISS-32 Format:

Not supported
num

for BLISS-32.

ted by the
Flag indicating whether or not the subtitle genera
value is
this
If
$DS SBTTL macro should appear on a new page.
printing
and
page,
t
curren
@, the subtitle will appear on the
value
the
'If
.
of the $DS SBTTL macro call will be suppressed
will
le
subtit
The
is nonzero, a new page will be started.
the
of
ng
appear at the top of the new page, ~and printi
$DS_SBTTL macro call will be suppressed.

Example:

&S _Fant

ORTTL SREAT/WRITE TESTS:

VDS

MACROS

PROGRAM

STRUCTURE

allocate

MACROS

$RAB
The

SRAB

macro

used

RMS

record

access
block
optionally, to load
values into the various fields within
the RAB.
An
RAB
is
1
data
structure that is required for perfor
ming file management
operations using RMS.
Refer to Section 3.15, File Management.
(RAB)

This

description

RMS.

the

program

For

VAX/VMS

Besides

only

RMS

Reference

the

RAB

VMS

Manual.

and,

fields

supported

RMS-supported

fields,

VDS

refer

RAB,

the $RAB macro also defines symbols
field.
Symbols
are
of
the
form
fieldname,"
where
"datatype"
is
a
data
type
listed
in Table 5-1.
|

each
"RABSdatatype

specifier

time

discusses

discussion

allocating

for

MACRO-32

compilation

RAB

Format:

SRAB

BKT=bkt-code, FAB=fab-address,
-

RAC=rac-param,
RHB=header-buffer-address,
-

ROP=BIO, -

UBF=user-buffer-address,
USZ=user-buffer-size

BLI SS-32

Format:

SRAB

(BKT=bkt-code,
FAB=fab-address,

RAC=rac-param,
RHB=header—buffer-address,

ROP=BIO,

UBF=user-buffer—address,

USZ=user-buffer-size);
BKT

bkt-code

Bucket

the

code.

number

SREAD service.
4

for

internal
FAB

the

Used

only

the

first

"next

block

with

block

virtual

I/0.

block

specified,

SREAD,

Should

that

reading

will

loaded

read

begin

or
at
the block pointed
pointer" for subsequent S$READs.

fab-address

Address of

the FAB describing

the

file

to be accessed.

at
to

with

the

block
by

the

VDS MACROS - PROGRAM STRUCTURE MACROS
rac-—-param

RAC

Record access mode.

Indicates the type of access to be used 1in

retrieving records from the file.

Valid values are

This is the default.

- Sequential record access.
SEQ

RFA - Random access by record's file address (RFA).

"Refer to Section 5.15.6, Record Processing, and Note 2 below.
= header-buffer—-address

RHB

only for
Address of buffer to store record header buffer. Used
ol.
contr
th
-leng
fixed
with
ds
recor
ble
files consisting of varia
the
into
r
heade
d's
recor
the
The S$GET service will 1load

buffer.

specified

The size of this buffer must match the size

specified by the FSZ field of the FAB.

ROP

BIO

of
Block I/0. Only meaningful if BRO was set in the FOP gfield
BIO
the
settin
then
so,
If
the FAB before $OPEN was issued.
record processing option will enable record processing and
block processing to be mixed.

UBF

user-buffer—-address

SGET or block
Address of a buffer to receive record fetched'by
with USZ.
fetched by $READ.

USZ

Buffer size is specified

= user-buffer-size

Size (number of bytes) of buffer pointed to by UBF field.
Notes:

Read-Only RAB Fields

The following RAB fields are not loaded by

the

programmer

be read after the service has completed.

(Some

under VDS RMS.

They are filled in by RMS services, and may

fields are read/write in VMS RMS.)

e
e

BID - Block identifier field.

these

Identifies the block

of
|

the

RAB.

BLN - Block length field.
RAB.

Contains the length

VDS

ISI

with
e

MACROS

Internal

PROGRAM

stream

Contains

RFA

Record's

record

the

bytes,

status

code.field.

STS

- Completion
field

before

with

returning

completion

status

Status

additional

the
code

wvalue

After

successful

record

read

into

program

can

extract

memory.
/

Address

record,
RFA,

Then

the

setting

RFA

The

field

RFA

reference

the

RFA

RABSW

and

4-2

another

long.

RFA

extracted
to

There

field's

pass

the

the
The

field.

elsewhere

address

the

S$SGET.
are

two

ways

in
the

re-read

random-by-RFA

offset

field's size.

Thus

(by

into

the

RABSW_RFA(RO),

of the first
RABSWRFA4
is the
Thus

the

field

may

MOVAL

RABBLK,

MOVL

RABSL_RFAQ (RO),

MOVW

SAVE

RFA

RABSW_RFA4 (R@),

SAVE

RFA+4

the

RAB.

RAB

fields.

SAVE RFA

longword

offset

the

field may be

offset

field.

all

service

necessary

issues

#RABSS_RFA,

lists

The

calle r

address

the

store

mode

follows:

Table

the

RABBLK,

the

used

file

access

MOVAL

the

load

status

service.
to

from

the

1later

MOVC3

field.

read.

follows:

last

services

the

Sometimes

field

bytes

the

RABSLRFAQ
of

and

the

six-byte
word

passed

also
N

field:
is

completion

stored

returns

six

address

RMS

caller

1is

record

RAB$S:RFA is

copied

this

RAC),

read.

(RFA)

memory

record

failure

SGET operation,

program

sets

last

information

caller.
File

the

field.

status

RAB

the

success

R@.

Record's

File

Length,

address.

last

Note

STV

the

See

RSZ

Associates

read.

this

address

file

MACROS

identifier.

FAB.

RBF

STRUCTURE

the

last

copied

VDS MACROS - PROGRAM STRUCTURE MACROS

Table 4-2 RAB Fields
Field

and

Keyword

Field

Size

Description

BID
BKT

Byte
Longword

Block identifier
Bucket code

Name

RFA

Byte
Longword
Longword
Word
Longword
Byte
Byte
Byte
Longword
Byte
Byte
Longword
3 words

ROP
RSZ
STS
STV
STV
STV2
TMO
UBF
Usz

Longword
Word
Longword
Longword
Word
Word
Byte
Longword
Word

BLN
CTX
FAB
ISI
KBF
KRF
MBC

MBF
PBF
PSZ

RAC
RBF

Longword

RHB

Block length
Context
File access block address
Internal stream identifier
Key buffer address
Key of reference
Multiblock count
Multibuffer count
Prompt buffer address
Prompt buffer size
Record access mode
Record address
Record's file address

MACRO-32 Example:
BUFFERS +ELEE 50
BUF .SI1E =, - BUFFEH
FaRLBLOCKS
ok

FHM=<INFILE.DAT>

ELOGK S

+RAHK

RABSB BID
RABSL BKT

RABSB BLN
RABSL CTX
RABSL FAB
RABSW ISI
RABSL KBF
RABSB KRF
RABSB MBC

RABSB MBF
RABSL PBF
RABSB PSZ

RABSB RAC
RABSL RBF

RABSW RFA
RABSL RHB
Record header buffer
RABSL ROP
Record-processing options
- RABSW_RSZ
|
Record size
RABSL STS
Completion status code
RABSL STV
Status value
STV@
RABSW
Low-order word of status value
STV2
RABSW
High-order word of status value
TMO
RABSB
Timeout period
UBF
RABSL
User record area address
RABSW USZ
User record area size

Examples:

SFAR

Offset

FAR=FAR.BLOCKy
RatG=8EQy

UEF=BUFFER
U&sZ=BUF__8IZE

oyee

VDS

BLISS-32

MACROS

PROGRAM

STRUCTURE

Example:

LEITERAL
BUF_SIZE

503

EBELOCK

Rab

VECTOR

BUFFER
FaRLRILOCK

PFAR

(FNM="FILEL1.DAT
)

OWN
CRUF.SIZEy

EYTED»

$RAHR

(FAB=FaB_ BLOCK .
RAL=%E0Ry
UWRF=RIUFFER

—

al=RUF_SIZE)

MACROS

VDS

MACROS

PROGRAM

STRUCTURE MACROS

$RAB_INIT

$RAB_STORE
The

SRAB STORE and

RAB

fields.

SRAB_INIT macros can be

wused

load

RAB

The S$SRAB STORE macro is used for MACRO-32
at run time.
fields
programs.
BLISS-32
in
is used
The SRAB INIT macro
programs.
Refer
to the discussion of the $RAB macro for a description of

MACRO-32

Format:

$RAB_STORE

BKT=bkt-code, -

FAB=fab—-address,

RAC=rac-param,
-

RHB=header-buffer—-address,
ROP=BIO,
-

UBF=user-buffer—-address,
-

USZ=user-buffer-size

BLISS-32

Format:

SRAB_INIT

(BKT=bkt-code,
FAB=fab-address,

RAC=rac-param,
RHB=header-buffer—-address,
ROP=BIO,

UBF=user-buffer—-address,
USZ=user-buffer-size);

Refer
input

to the discussion of the $SRAB macro for
descriptions
parameters.
All parameters are optional.

VDS

MACROS

PROGRAM STRUCTURE

MACROS

Examples:

MACRO-32

Example:

|
IN_RUF!

.
.EBLKE

RUF_SIZE = 50
BUF_SIZE

$RAE._STORE

UEF=IN_EUF, UERZ=#RUF_SIZE

BLISS-32 Example:
LOCAL
|

|
INEUF

VECTOR

$RAR_INIT

[50y

EYTED;

(UBF=INRBUF, UBZ=RUF._SIZE)s

MACROS

VDS

PROGRAM

STRUCTURE MACROS

$DS_SBTTL
The $DS SBTTL macro should be used at
test and subtest.
It will perform the
e

It will generate
text
<containing
the
test
and subtest
numbers,
along with the contents of a programmer-specified
.SBTTL
a
This text will be included in
character string.
MACRO-32
statememt, and will also be displayed on the user
terminal when the test or subtest is entered
and
the
VDS
Control

Flag

TRACE

set.

If the macro is at the beginning
section
(.PSECT) is assigned to

included

the
beginning
of
each
following functions:

program
new
a
(A subtest will

in the PSECT of the test to which it belongs.)

The code 'of
specified

of a test,
the test.

the

test

programmer..

subtest

will

aligned

MACRO-32 Format:
N\\‘v

$DS SBTTL ascii, [align]
Not

supported

BLISS-32 Format:
for

BLISS-32.

ascii

Character string
representing
text
subtitle and to be displayed when VDS

to
be
used
TRACE flag is

as
program
set.

align

Desired

program

section

Possible values are

from @ to 9.
at
the
next
power

the

alignment

BYTE,

WORD,

for

LONG,

the

test

QUAD,

PAGE,

subtest.

If an integer is specified, the psect will
address
that is a multiple of two raised

integer.

4-84

integer

start
to the

VDS

MACROS
-

PROGRAM

STRUCTURE

MACROS

Notes:

The

$DS_SBTTL macro

$DS_PAGE

should

used

SWAF

DATA

conjunction

macro.

Example:

FNS.SBTTL
ALIGN

EYTEs

ARCTT

<JREANAWRITE

TEST:

with

the

VDS

MACROS
-

PROGRAM

STRUCTURE MACROS

$DS_SECDEF
The $DS_SECDEF macro
test
sections
(see

is used to declare
Section 3.8.3) of

all
the

of the names of the
diagnostic program.

This macro must appear in every
source
module
tests.
The
macro is used in conjunction with
macro.

that
contains
the $DS SECTION

MACRO-32 Format:

$DS SECDEF a, [b, ¢, d, e, £, g, h, i, j, k, 1, m, n, o, p]
BLISS-32

Format:

$DS SECDEF (a, [b, ¢, d, e, £, g, h, i, j, k, 1, m, n, o, pPl);
a,

ce ey

List

from

identical

the

test

section

names.

list

included with

the

tests

belonging

every listed

if the module in which the $DS SECDEF

does not

include

This

1ist

must

$DS SECTION macro,

macro

1is

even

being

placed

name

DEFAULT

section.

Notes:

The macro automatically includes the
at the beginning of the section name

section
list.

Examples:

MACRO-32

Example:

$NS_ SECHEF READNTEETES, WRITETESTS, SEEKTESTS
BLISS-32

Example:

$NS_SECLEF

(READTESTS,

WRITETESTS,

4-86

SEERTESTS)s

VDS

MACROS
-

PROGRAM

STRUCTURE

MACROS

$DS_SECTION
The

$DS _SECTION macro

the
test
program.
contains

conjunction

MACRO-32

with

BLISS-32

to declare

all

the

names

the

$DS SECDEF

macro.

[b,

¢,

£,

Format:

$DS_SECTION

used

Format:

$DS_SECTION a,

sections
(see
Section
3.8.3)
of
the
diagnostic
This macro must appear
in
the
source
module
that
the
$DS HEADER macro.
The $DS SECTION macro is used

(a'

[b'

g’

h’

1’

Pl);

a' b'oloo,O' p
List of from 1 to 16 test section names.
identical

the

list

included

with

the

This

1ist

$DS _SECDEF

must

Dbe

macro.

Notes:

The
at

macro
the

automatically

beginning

the

includes

the

section

name

section
1list.

Examples:

MACRO-32

Example:

%HQQSEbTIGN READTESTS, MRITETEETS? SEEKTESTS
BLISS-32

Example:

$HS;$E€TIGH (READTESTS

NHITETESTQy SEERTESTS) »

name
|

DEFAULT
~

VDS

MACROS

PROGRAM

STRUCTURE

MACROS

$DS_STRING
The $DS _STRING
macro
can
be
wused
to
generate
a
quadword
descriptor
(see section 4.3) for a given character string.
1In
MACRO-32 programs, .ASCIC and .ASCIZ formats for the string may
also
be
generated.
This enables the programmer to reference
the

same

string

any of

the

three

formats.

MACRO-32 Format:

$DS_STRING
BLISS-32

<text>,

[labell],

[label?]

Format:

$DS_STRING

(*text");

text

Character

string

for

which

quadword

descriptor

1is

constructed.
labell

Label

to
string.

placed at the .ASCIC
(This parameter may not

construction
of

construction

referenced

the

character
keyword.)

label?2

Label

string.

placed

(This

the

parameter

.ASCIZ

may not be

the

character

referenced

keyword.)

contructed

the

label

Notes:.

The

quadword

PC.
call,

descriptor

will

It
may
be
accessed
as illustrated in the

by placing
example.

current

the

macro

VDS

MACROS
-

PROGRAM

STRUCTURE

MACROS

Examples:

MACRO-32
MSG

Example:

LAREL S

FLHS

STRING

yCrezte

STHIS

BLISS-32

LakeELi,

MoG

LAaBELR

HMESSAGE
&y

descrirtor

for

!
A

i meluae

lasbel

for

ASCIC

Ilneclude

label

for

ASCIZ

Example:

BTN

,
MEGLLABEL

$US_S5TRING

string,

{(THIS

HMESSAGE.
s

VDS

MACROS

PROGRAM STRUCTURE

MACROS

$XABFHC
The

$XABFHC

will

allocate

Extended
Attribute
Block
structure used by RMS.
If

pointer

the

File

the FHC XAB is specified

operation
will
characteristics

Header

Characteristics

(FHC XAB), which is an optional data
the S$XABFHC macro is used, and if
a

load
the
FHC
obtained
from the

opened.

in the FAB, then the SOPEN

XAB
with
header of the

file
file

header
that was

Besides allocating the XAB, the S$XAB macro also defines symbols
for
each
XAB
field.
Symbols
are
of
the
form
XABSdatatype fieldname,
where
"datatype"
is
a
data
type
specifier

MACRO-32

listed

in Table

5-1.

Format:

SXABFHC
BLISS-32

Format:

SXABFHC;

Notes:

FHC

XAB

Fields

Following

Refer

VMS

are

the

FHC

VAX/VMS

RMS.

XAB

fields

ATR

- Record

attributes.

BLN

COD

- Type

EBK

FFB - First free byte

e¢

HSZ

Length

Virtual

Fixed

the

LRL

Longest

Same

fields

VDS

RMS.

filled

XAB

RAT field

FAB.

XAB.

(Only

FHC

block

number

length

field

1in

for

filled

RMS Reference Manual

type

allowed.)

end-of-file.

in end-of-file block.

control

header

size.

Same

FSZ

FAB.

record

length.

VDS

MACROS

PROGRAM

STRUCTURE MACROS

MRZ - Maximum record size.
RFO

- File

ORG and

organization

contiguous;

otherwise

Examples:

Example:

¢XARFHC

XaGBOBLODCK?
BLISS-32

Example:

$XABFHC?»

AAB_BLOCK

record

format.

Combines

RFM fields of FAB.

SBN - Starting block

MACRO-32

and

Same as MRS field
of FAB.

4-91

number

field

is #.

the

file

vDS

MACROS

PROGRAM

STRUCTURE

MACROS

$DS_ERRNUM

The

$DS _ERRNUM

MACRO-32

Format:

macro

used

label,

[num]

in - conjunction

$DS _ERRxxxx
L
macros.
It generates executable
dynamically load
the
"num"
argument
of
the
created by the $DS ERRxxxx
L macro.

$DS_ERRNUM
BLISS-32
Not

with

the

code that
argument

will
1list

Format:

supported

for

BLISS-32,

label

Address of the argument

1list

generated

macro.

the

SDS ERxxxx
L

num

Error

number.

value

specified,

the

value

will

used

as the "num" parameter in the argument 1list.
If a value 1is not
specified, the current
assembly-time
error
number
1is
|used.
Refer to the description of the $DS ERRxxxx system services for
an

explanation
time.

the

assignment

error

numbers

-assembly

Notes:‘

Using

the $DS

ERRxxxx

L macro

create

argument

1list,

dynamically
altering the error number with the $DS_ERRNUM
macro, then calling the error service with a
$DS_ERRxxxx
G
call
has
a
disadvantage.
It
is
difficult to relate a

program's

use

run-time,

because the error
macro
argument.
depending
on the
|

point
1in
the
program listing
not explicitly specified
as
a
or
may
not
be
a
problem,
users.

displayed

//flfl_

specific
number is
This
may

and

message,

error

specific

VDS

MACROS

—

PROGRAM

STRUCTURE

MACROS

Example:

ARGLLLISTS
UNIT

slleclare

LOG.UNIT,

MSGADR

HARD_
. MSG1 »

FRILINK

HARDIL.RTN1

hard

error

arg.

list

PNSERRHARD.L

CSR ~REG

)

$NS_ERRNUM

ARGLLIST

sFut

error

number

ST,

list

VDS

4.5

MACROS

PROGRAM

CONTROL MACROS

PROGRAM CONTROL MACROS

$DS_BCOMPLETE - $DS_BNCOMPLETE
The

$DS BCOMPLETE and

$DS_BNCOMPLETE program

control macros can

to test the return status of a system service (or any
used
be
the
1if
branch
returns a status code in R@) and
which
routine
service's operation was "complete" or "incomplete."

MACRO-32 Format:

$DS_BCOMPLETE adr
$DS_BNCOMPLETE

adr

BLISS-32 Format:
Not supported
language.

for

See

BLISS-32,

since

example below.

the

testing

RO is

implicit

the

adr

Address to which

to branch if

tested condition

1is satisfied.

Notes:

For all error status codes,
bit
these macros simply generate the
$DS_BCOMPLETE
$DS_BNCOMPLETE

@
1is
<clear.
following code:

BLBS R@,adr
-

BLBC

R#,adr

If an error status code is
detected,
the
contents
of
RO
should
be compared with all error codes that could possibly

be returned from the service
the

exact nature

the

(or other)

error.

Examples:

MACRO-32

Example:

NS LGETHUF
05 BNCOMPLETE
BLISS-32

Therefore,
|

2y RETALIDR»
BADR_RUF

FPHYSADDR

Example:

$LE_GETEUF

(FAGONT=2)}

THEN

4-94

...

routine to determine

VDS

MACROS

PROGRAM

CONTROL

MACROS

$DS_BNERROR
- ERROR
$DS_B
The

$DS_BERROR and

used

test

the

$DS_BNERROR program

return

status

control

macros

can

of a system service

routine which returns a status code
service's operation was in error or

in R@)
and
branch
was error-free.

(or

any

the

MACRO-32 Format:
$DS_BERROR

adr

$DS_BNERROR adr

BLISS-32 Format:
Not

supported

language.

for

See

BLISS-32,

since

example

below.

the

testing

is implicit

///A\‘\

Address to which to branch if tested condition is satisfied.
Notes:

For

all

these

error

macros

status

simply generate

$DS_BERROR $DS BNERROR

BLBS

status

compared

be returned from
the exact nature

bit

the

1is

clear.

following

‘Therefore,

code:

BLBC R@,adr

error

should

codes,

code
with

R@,adr

is
all

detected,
error

the service (or
of the error.

the

codes

other)

<contents

that

could

routine

possibly

determine

Examples:

MACRO-32
LS

Example:

GFHARD

$HG BENERROR
BLISS-32

NOY

LOG.LUNITs

ADDRI

10%

Example:

#DS.GFHARLD

(UNIT=,LO0G.UNITs

4-95

RETADR=ADDORL)

THEN

...

VDS

MACROS

PROGRAM

CONTROL

MACROS

$DS_BOPER - $DS_BNOPER
The $DS BOPER and $DS_BNOPER macros can be used to determine the
presence of
an operator (user) during program execution.
(The
VDS
the
of
<condition
the
presence of a user is indicated by

can be used to control
macros
These
flag OPERATOR.)
control
a
1if
whether certain portions of the program are executed only
$DS BOPER will cause a branch if the OPERATOR
1is present.
user
is
flag is set, and $DS BNOPER will cause a branch if the 'flag
clear.

MACRO-32 Format:
$DS BOPER

adr

$DS_BNOPER adr

BLISS-32

Not

Format:

implemented

corresponding
is

for

BLISS-32.

control

recommended.

Direct

reference

flag, as illustrated
|

the

in the example
TM

below,

VDS

Address to which to branch if the testéd condition is satisfied.
Examples:

MACRO-32

Example:

FUS CBNOFER
BLISS-32
L

100%

Example:

L OSAsV
. OFER

THEM

BEGIN

ENID

adr

VDS MACROS - PROGRAM CONTROL MACROS

$DS_BPASS0 - $DS_BNPASS0
The

$DS BPASS@

used

within

the

initialization

pass

code

through

determine

the

initialization

code

the

often

and

necessary

initialization
subsequent

"pass

pass

code

through

of
as

the

BNPASS@

perform

passes

initialization
~of

$DS

certain

executed

through

run-time
the

program

the

not

that

(It

takes

current

one.

1is

time

the

repeated
code,

helpful

place

can

the

first

initialization

variables.

execution

tests

should

macros

first

operations

that

the

control

before

such

+to

think

the

first

occurs.)

SDS BPASS@ will
initialization
branch
not

the

cause a branch if the current pass
through
the
code is the first one.
SDS BNPASS® will cause a
current pass through the
initialization
code
is

first

one.

initialization

MACRO-32

macros

may

only

used

the

Format:

$DS_BPASS@

adr

$DS_BNPASSO
BLISS-32
Not

These

code.

adr

Format:
implemented

corresponding

below,

for

VDS

BLISS-32.

control

Direct

flag,

recommended.

reference

illustrated

the

example

adr
Address

which

branch

BEGIN

...

the

tested

Examples:
MACRO-32

Examples:

EBNFASSO

FOS

BPASSO

Fassl

BLI 5S5-32

Example:

JDSA$V_FASS0

THEN

END

condition

satisfied.

VDS MACROS - PROGRAM CONTROL MACROS
$DS_BQUICK - $DS_BNQUICK
The $DS BQUICK and $DS_BNQUICK program control macros can be
used to determine if the VDS control flag QUICK has been set by

The $DS BQUICK will cause a branch 1if the
the program user.
1is set, and the $DS BNQUICK will cause a branch if
QUICK flag
the diagnostic
If the flag has been set,
the flag is clear.
code deemed
of
execute only the portions
should
program
appropriate to the "quick" mode of operation.

MACRO-32 Format:
$DS BQUICK adr

$DS_BNQUICK adr
BLISS-32 Format:

the
of
reference
Direct
BLISS-32.
for
implemented
Not
corresponding VDS control -flag, as illustrated in the example

below,

recommended.

adr

// ‘

Address to which to branch if the tested condition is satisfied.
Examples:

MACRO-32

Examples:

$fi8mBGUICH TAakl
SUS_RNOUICK 100%

BLISS-32 EXample:
08a$Y
. QUICK

THEN

EBEGIN

...

ENDy

ATEE—

VDS

MACROS

PROGRAM

CONTROL

MACROS

$DS_CKLOOP
The SDS_CKLOOP program
control
macro
is
used
to
explicitly
specify
the upper bound of a program loop.
It is used when the
implicit upper bound provided by
a
$DS ENDSUB
or
SDS_ENDTEST

macro

creates

loop

that

too

large

useful.

detailed

discussion
of
program
1looping,
1including
the
use
$DS_CKLOOP macro, is provided in Section 3.18, Looping.

MACRO-32

the

Format:

SDS_CKLOOP label
BLISS-32
Not

Format:

supported

for

BLISS-32.

See

note

label
Address

executed,

must

higher

1loop's

1lower

program

lower

than

flow

than

the

most

bound.

After

branches

location

recent

this

the

SDS

$DS BGNTEST
or

$DS _CKLOOP

address.

The

CKLOOP

address

macro,

$DS_BGNSUB

but

macro.

Notes:

S$DS_CKLOOP

contain
anywhere

are

wused

within

The

$DS

been

has

programs

that

matter)

with

judicious

can

not
written

define

use

test
macros

$DS_CKLOOP macros must
CKLOOP

the
$DS CKLOOP
test.
For tests

the

However,

macros

subtests,
within the

placed

the

implemented
BLISS-32

sufficiently

$DS_BGNSUB

that

may
contain

and

not

placed
subtests,

subtests.

for

(and

small

does

BLISS-32.

MACRO-32,

program

$DS ENDSUB

The $DS_INLOOP system service may be used inside
of
a
1loop to determine whether or not the loop
being executed.

for

loops

macros.
the
is

bounds
actually

VDS MACROS - PROGRAM CONTROL MACROS
Example:

_ EGNSUR
NS
&

LOGH OBGN:

$NS ERRHART

G
. UNIT,»
UNIT=LO

MSGADR=HRID1ly

FRLINK=HRIRTNI

BDECKLOOP

. BGN
LODF

/flm\

E0S_ENDEUR

4-100

VDS

MACROS

PROGRAM

CONTROL

MACROS

$DS_ESCAPE
The

$DS ESCAPE

test

program

subtest

control
a

macro

hardware

can

failure

within

used

has

exit

from

been

detected

will

branch

from

the test or subtest.
If the failure
is
reported
using
one
of
the
error
reporting
macros
($DS_ERRxxxx),
and
if
$DS_ESCAPE is executed before the next $DS ENDSUB or $DS ENDTEST

macro

encountered,

$DS_ENDSUB or

MACRO-32

then

program

$DS_ENDTEST

control

(whichever

the

specified).

Format:

$DS_ESCAPE arg

BLISS-32 Format:
Not

supported

Indicates

$DS_ENDSUB
SUB

for

whether

BLISS-32.

program

nearest

See

Note

control

$SDS_ENDTEST.

should

The

branch

argument

TEST.

nearest

may be

either.

Notes:

For

programs

obtained

statement,

written

BLISS-32,

follow1ng

shown

the

4-101

the

similar

$DS _ERRxxXx

example below.

functionalilty

macro

with

can

LEAVE

- PROGRAM CONTROL MACROS
VDS MACROS

Examples:

MACRO-32

Example:

BEGHNSUE
»
[y

$NS . ERRHARD

$05 _ESCAFE

UNIT=LOG_UNIT, MSGADR=HRIMSG3Z, FRLINK=HRIRTN3

SUR

PLOSENDSUR

BLISS-32

Example:

NS CBGNSURS

EEGIN

SUERE3S
&

)
05 FRRHARD.S (UNIT=,LO0G.UNIT, MSGADR=HRIMSGI, FRLINK=HRIORTHNI
LEAVE

SUBI

ENTIe

NS _EMNMIOSURSY

4-102

VDS

MACROS

PROGRAM

CONTROL

MACROS

$DS_EXIT
The

$DS_EXIT

program

control macro is
wused
to
branch
to
the
end of the currently executing
Exits can be made from any of the following:
l.

A subtest

interrupt

The

summary

MACRO-32

unconditibnally
program segment.

test

service

routine

Format:

$DS_EXIT arg
BLISS-32
Not

Format:

supported

for

BLISS-32.

See

note

arg

Indicates

program

SERV,

SUMMARY.

and

segment

type.

Valid

arguments

are

TEST,

SUB,

Notes:

For

programs

obtained

example

written

using

BLISS-32,

similar

the

statement,

below.

MACRO-32 Example:
SERV_RTN

FOS_EXIT

SERY

functionalilty

shown

Examples:

NS _BGNSERY

LEAVE

PSS ENNSERY

4-103

can

the

VDS

BLISS-32

MACROS

PROGRAM

CONTROL

MACROS

Example:
FNGE_BGNTEST
3

TELBLKL:

BEGIN

LEAVE

T2LELKLS

4
&

;

END

EMOTEST

SIS

4-104

VDS

4.6

SYSTEM

MACROS

SYSTEM

SERVICE

service

can

MACROS

SERVICE MACROS

$DS_ABORT
The

Abort

Program

either

the

whole

Test

be used to stop execution
program or just the current

diagnostic

test.
If the program is aborted, a system service
1is
called.
This service will execute the program's cleanup code and return

control

current

the

test

instruction)

MACRO-32

VDS

command

1line

aborted,

the

and

the

interpreter.
test

selected

test

exited

called.

only

(with

the
RET

Format:

$DS_ABORT arg
(No

suffix.)

BLISS-32

Format:

SDS_ABORT

(ARG=argqg)
;

arg

'PROGRAM'
program

'TEST'.

will

'PROGRAM'

‘specified,

then

the

aborted.
If 'TEST' is specified, the current
test will be exited (with an
RET
1instruction)
and
the
next
selected test will be called.

Return

Status:

status

generate
program

1is
a

returned,

service

control

because
$SDS

ABORT

return

the

diagnostic

Example:

$NS_ABORT

(FROGRAM)

$O5
. ABORT

{(TEST)

BLISS-32

(TEST)
(PROGRAM)
does

and

Examples:
MACRO-32

SDS_ABORT

call

Example:

05 LABORT

(ARG=FROGRAM)Y§

UL _ABORT

(ARG=TEST):

4-10@5

program.

does
not
not allow

VDS

MACROS

SYSTEM

SERVICE MACROS

$ASCTIM
The Convert Binary Time to ASCII String system service converts
from 64-bit time format into an
‘the contents of a quadword
function performed
This is the converse of the
ASCII string.
|

by the $BINTIM service.

MACRO-32 Format:

SASCTIMx [timlen], timbuf, [timadrl], [cvtflgl
BLISS-32 Format:

SASCTIM ([TIMLEN=timlen],

TIMBUF=timbuf,

[TIMADR=timadr],

[CVTFLG=cvtflg]);

timlen

Address of a word to receive length of output stfing.
timbuf

Address of a character

string

(see

descriptor

pointing to buffer to receive converted string.

Section

4.3)

timadr

Address of the 64-bit time value to be converted.

A value of 0

results in the «current system time being
default)
(the
A
converted. A positive value represents an absolute time.
the
from
negative: value represents a relative time (offset
current time).

cvtflg

A value of 1 causes only the hour,
Conversion indicator.
second, and hundredth of second fields to be returned,
minute,
time to Dbe
while a value of @ causes the full date and

returned.

4-106

VDS

Return

MACROS

SYSTEM

SERVICE

MACROS

Status:

SS$ NORMAL
Service

successfully

completed.

SS$_IVTIME
The

specified

relative

time

equal

greater

days.

than

10,000

Notes:

The

ASCII

format
2.

string

specified

receive

length

full

must

returned

the

notes

date

and

absolute

bytes.

and time, the buffer length
shorter buffer length will
truncated

the

buffer

service

the

time,

receive

must

This

may

"timbuf"

full

16 bytes.
the returned

only
the
absolute date is required,
is only necessary to provide a buffer

~ amount
of the

the

string

not the
that
can

returned string the caller wishes

BLISS-32

STR.LENGTH,

RUFFTRs

TIHE,

if,

hold

(TIMLEN=STR_LENGTH.

CUTFLG=113)3

TIMBUF=EUFFTR,
|

4-107

a
be

say,

It
the

to receive.

Example:

$ASCTIM

time.

Example:

$QSCTIM%5

day

Specifying

useful

and

buffer

relative

Examples:
MACRO-32

the

service.

cause

size.

will

$BINTIM

TIMADR=TIME,

VDS

MACROS

SYSTEM

SERVICE MACROS

$DS_ASKADR

$DS_ASKDATA
$DS_ASKLGCL
$DS_ASKSTR
$DS_ASKVLD
from
information
The "ask" system services are used to obtain
the
services,
these
With
time.
run
at
user
program
the
diagnostic

program

can

Prompt the user with a message specified by the programmer
Obtain keyboard

input

the

from

user

Interpret and validate the input string
Store the value specified by the input string

used

when

The Ask for Data ($SDS_ASKDATA) system service 1s used when

the

The Ask for Address (SDS_ASKADR) system service

1is

the information requested from the user is an address.

requested

information

than

from

the user is a numeric value other

address.

system service 1is
The Ask for Logical Response ($DS ASKLGCL)
user a questlon that can be answered with a
the
to ask
used
can specify
the caller
Optionally,
"yes" or "no" response.

addresses of routines that will automat1ca11y be branched to on
a

"yes"

"no"

response.

is
service
system
($DS ASKSTR)
The Ask for Character String
an alphabetic character string from the user.
obtain
to
used
Optionally, the caller can also provide a set of valid response

strings.

The

system service will compare the input string to

the valid responses and

was

indicate to the caller

which

response

provided.

The Ask for Data Field

($DS_ASKVLD)

system service is

used

obtain a numeric value from the user and insert the wvalue into
This service is
a data field indicated by a position and size.
1in large data structures (greater
fields
1loading
for
useful
than

32 bits).

4-108

VDS

MACRO-32

MACROS

SYSTEM

SERVICE

MACROS

Format:

SDS_ASKADR_x
[defalt],

msgadr,

[unused],

$DS_ASKDATA_x
[hilim],

datadr,

msgadr,

([defalt],

$DS ASKLGCL
x

[radix],

[exword]
datadr,

[unused],

msgadr,

[radix],

[exword]

datadr,

[lolim],

[hilim],

[mask],

[lolim],

[pos],

[yexfer],

[defalt]
SDS ASKSTR
x

msgadr,

bufadr,

$DS_ASKVLD_X msgadr,

datadr,

[radix],

[unused],

[exword]

[hilim],
BLISS-32

$DS

[defalt],

[maxlen],

Format:

ASKADR

(MSGADR=msgadr,

DATADR=datadr,
[RADIX=radix],
[LOLIM=10lim]},

[HILIM=hilim],
[DEFALT=defalt],
[EXWORD=exword]);

$DS_ASKDATA

(MSGADR=msgadr,
DATADR=datadr,

[RADIX=radix],
[MASK=mask],

[LOLIM=]lolim],
[HILIM=hilim],
[DEFALT=defalt],
[EXWORD=exword]);

SDS

ASKLGCL

(MSGADR=msgadr,

DATADR=datadr,
[POS=pos],
[YEXFER=yexfer],
[NOXFER=noxfer],
[DEFALT=defalt]);

$DS

ASKSTR

(MSGADR=msgadr,

BUFADR=bufadr,
[MAXLEN=max1len],

[VALTAB=valtab],
[DEFADR=defadr]);

4-109

[valtab],

[pos],

[noxfer],

[defadr]

[size],
|

[lolim],

VDS

MACROS

- SYSTEM

SERVICE MACROS

(MSGADR=msgadr,

$DS_ASKVLD

DATADR=datadr,

[RADIX=radix],

[POS=pos],
[SIZE=size],
[LOLIM=1lo0lim],
[HILIM=hilim],
[DEFALT=defalt]l,

)i
[EXWORD=exword]

msgadr

Address of counted ASCII string to be used

prompting

user

message.

datadr

d response value.
user
Address of longword to receive interprete
For $DS ASKDATA, value is placed in bit position 1indicated by
|

"mask."

For $DS_ASKVLD, value is placed in field indicated by "pos" and
"siz," where "pos" 1is bit offset from "datadr."

For $DS_ASKLGCL, value will be placed in one bit, indicated

"pos." The bit can be compared with PARSNO and PARSYES, defined
in $DS PARDEF.

bufadr

(No = 0, yes = 1) .

‘

($DS_ASKSTR only)

Address of buffer that will receive counted ASCII input string.
maxlen

($DS_ASKSTR only)

Size of the buffer specified in "bufadr." The_default value

72,

valtab

($DS_ASKSTR only)

GSee

Address of table containing list of string pointers.

4 for table format.

The

(uncounted) that represents a valid user response.

service

Note

Each table entry points to an ASCII string

system

will compare actual user input to the valid responses.

If a match is found, the number of the table entry pointing to
is not
the matched string will be returned in Rl. If a match
d
invali
an
that
user
found, the system service will inform the
prompt
the
e
response has been issued and will then reissu
message. See Note 5 for a description of the string comparison
algorithm.

“

4-110

vDS

this

MACROS

parameter

SYSTEM

(the

SERVICE

default),

MACROS

valldatlon

will

take

place.

defadr ($DS ASKSTR only)
Address

counted

response.

The

means

there

ASCII

string

default

wvalue

default

user

for

used
this

default

parameter

user

which

response.

radix
Radix

values

which

for

the

this

user

response

parameter

are

defined

interpreted.

the

and

consist of PARS BIN, PARSOCT, PAR$DEC,
default radix is dec1mal except in thecase
which

mask

the

default

($DS_ASKDATA

Mask

PARDEF,

PARS
$DS

hexadec1ma1

the

bit positions within

user response
(hexadecimal),

pos

and

Legal

$DS

HEX.
The
ASKADR for

only)

indicating

interpreted
is FFFFFFFF

macro

"datadr"

should be stored.
indicating 32 bits

in which

the

The default value
starting
at
bit
.

($DS_ASKVLD and S$DS ASKLGCL only)
Bit

offset

response
Default

size

from

1is
is

"datadr,"

1indicating

stored.

indicating

value

"datadr."

where

interpreted

See

Note

should

stored

for

legal

user

values.

starting

bit

($DS_ASKVLD only)

Number

bits

stored.

"datadr"

which

Range

through

32.

for

numeric

power,

except

user reponse.
in the case of

interpreted

user

response

lolim
Minimum
minus
for

acceptable
2

which

value

the

31lst

the

default

(unsigned)

Default
is
$DS _ASKADR,

hilim

Maximum
2

for

acceptable

the

which

value

31lst

power

the

default

for

numeric

minus
1,

except

(unsigned)

4-111

user
in

response.

the

FFFFFFFF

case

Default

$DS_ASKADR,

(hexadecimal).

VDS

MACROS

SYSTEM

SERVICE MACROS

defalt

to be used

The value

if the user does not

response

provide

The default value for "defalt"
(user just types return key).
"no"
is equivalent to a
for $DS_ASKLGCL,
(which,
is ©®
If no default is to be used, then NODEF must be set
response).
in the "exword" parameter.

For the $DS ASKLGCL macro, default values may be

the

PARSYES,

and

PARSNO

symbols

defined

specified

Dby

1is

by the SDS PARDEF

macro.

yexfer

($SDS_ASKLGCL only)

Address to branch to
meaning
noxfer

if user response is "yes." Default
take

branch will

place.

($SDS ASKLGCL only)

Address to branch to
meaning

Default

if user response is "no."
take

no branch will

place.

unused

Reserved

for

expansion.

exword

The "exception mask."

This is a longword containing

"exception

flags are used to modify the interpretations of
These
flags."
flags
Symbols for the exception
parameters.
other
the
of
some
on
descripti
the
to
Refer
macro.
PARDEF
$DS
the
by
are defined
of that macro for

e¢

NODEF - There is to

response.

default

The flags are:

wvalue

for

the

|user

In other words, the "defalt" parameter is to be

ignored.

"defalt" parameter
ATDEF - The argument specified for the
the default value.
g
containin
location
a
of
is the address

is
ATLO - The argument specified for the "lolim" parameter
value.
limit
low
the
g
containin
location
the address of a

Iis
ed the "hilim" parameter
ATHI - The argument specififor
value.
limit
high
the
ing
contain
location
a
of
the address

By default,

all flags are cleared.

the complete symbol names.

4-112

VDS

Return

MACROS

SYSTEM

SERVICE

MACROS

Status:

SSS NORMAL

Service successfully completed.
DS$_PROGERR

An incorrect number of arguments was supplied with

the macro.

DS$ TRUNCATE

For

fit

$DS _ASKSTR,

in order

truncated

For

was

the

$DS ASKDATA and

too

caller.

large

The value

specified

string

buffer

the

into

supplied

pointed

by the user

to by "bufadr."

into

the buffer.

$DS_ASKVLD,

the value

fit

into

was truncated

the

was

too

long

The string was

specified

by the

user

into

the

bit field specified by the
order

fit

field.

Notes:

the

VDS

control

flag

OPERATOR

default value has been specified
then

the

diagnostic

diagnostic
automated
cannot be

program

will

for

intended

1is

<clear,

aborted.

and

1if

the prompting message,

Thus

1if

executed

the

1in

run-time environment (such as APT), these
used unless default values are provided.

macros

It is also required that if these macros are
used 1in
the
DEFAULT program section (see Section 3.8.3), default values
must be provided.

the VDS control

default

wvalues

with

prompting

the

flag

for

PROMPT

user

set,

responses will

message.

the

ranges

be displayed
|

and
along

To
ensure that
prompting
messages
precede each prompting message with a

4.,

Figure 4-4 illustrates the format of the "valtab" table.

4-113

are
left-justified,
CR and LF.

vDS

MACROS

SYSTEM

SERVICE

8 7

31
Unused

MACROS

String Pointer 1

- ASCI| string1

String Pointer 2

# ASCII string2

®
°

flL'

‘

& ASCII stringN

String Pointer N

TK-10534

When

the

$DS

4-4

"Valtab"

ASKSTR

Table

system

Format

service

compares

the

user

response
string with the set of valid responses optionally
specified by "valtab," it will
go
through
the
table
of
valid
string
pointers and, for each valid string, it will
compare the
characters
of
the
user
response
with
the
characters
of
the
wvalid string until the end of the user
response is reached.
If all the
characters
of
the
|user
response
match
all
the
<characters
of the current valid
string, up to the end of
the
wuser
reponse,
a
match
is
declared.
This
means
the
user
can
abbreviate
input
strings.
user
<can

For example, if
type EXEC, EX,

two valid

strings are START and

ST,
then
whichever
"valtab."

When

the

macro,

a valid
or even

the
of

STOP.

service
routine
would
the
wvalid
strings
was

"pos"

1ts

string
just E.

parameter

legal

range

is
@

wused

through

1is
EXECUTE,
the
However, suppose

the

user

declare
defined

with

the

typed

match
first

on
1in

$DS ASKLGCL

When the "pos" paraméter is used with the $DS ASKVLD macro,
its

1legal

range

that can be stored
is
is

normally

1is

in a Jlongword.

specified
for "datadr,"
through 31.

4-114

then

through

the

However,

the

legal

largest

value

range for

"pos"
|

Figure

VDS

MACROS

SYSTEM

SERVICE

MACROS

Examples:

MACRO-32

Example:

FROMET S

LAaSCI0

RESFONGE D

LLONG

FOS L AREADR.LS

BLISS-32

SREVICE

ALDRESSLS

MEGALR

FROMFTy

GAaTADR

REZFONGEs

Rl DX
LOLIM

¥FrRAaRE 00T,
#7600G00s -

HILIM

¥777777,

NEFALT

$#754000

Example:

FROGMET

2IM

UELIT

(XABCIC

THE

DRIVE

WRITE-EMABLEDT
)

RESFONSE»
<
)

¢
&

ASKLGCL

)

(MSGADR=FROMFT:

4-115

DATADR=RESFONSE
s

vDS

MACROS

SYSTEM

SERVICE

MACROS

$ASSIGN
The

Assign

I/0

channel

peripheral

with

issue
Refer

I/0

Channel

that

system

service

can

used

the

device

user

mode.

VMS

used

caller

Level

provide

communicate

programs

must

the
SASSIGN
macro
before
the $QIO macro can be used.
to Section 3.12.1.1 for details of I/O operations in user

mode.

This

service

remote

for

node

can
on

also

used

network.

to create

Refer

details.

the

logical

1link

DEChet-VAX

with

User's

Guide

MACRO-32 Format:
$ASSIGN_;x devnam, chan, [acmode], [mbxnam]
BLISS-32

Format:

SASSIGN

(DEVNAM=devnam,

CHAN=chan,

[ACMODE=acmode],

[MBXNAM=mbxnam]
);
devnam

Address of

character

string

descriptor

pointing to the device name string.
The
physical device name or a logical name.
of the string is an underscore (_ ), then
name.

Otherwise

performed
If

the

channel
the

and

device
to

the

one

1level

the

equivalence

name

contains

device

NET@:

double
and

Section

4.3)

string may be either a
If the first character
the name is a physical

1logical

name,

(see

name

any,

colon

translation

1is

used.
assigns

access

function

channel

number

assigned.

performs

(::),

VMS

network.

chan

Address of a

longword

receive

the

acmode

Access
access
I/0

and

mode

operations

Kernel,

be
1is

with the
with

the

channel

privileged

access

for

associated
maximized

Executive,

for

4-116

can

the

channel.
access

only

modes.

performed

Legal

Supervisor,

The

mode

and

specified
the

wvalues
3

for

caller.

from

are
User.

equal

for

VDS

MACROS

SYSTEM

SERVICE

MACROS

mxXbnam
Address

character

string

(see

descriptor

section

4.3)

logical
name string
for the mailbox to be
pointing
to
the
if
assocliated with the
anvy.
The
mailbox
receives
device,
status
information
from
the
device driver.
An address of 0
implies

mailbox.

This

the

default

value.

Return Status:

SS$

NORMAL
Service

successfully

completed.

successfully

completed.

SS$ REMOTE
Service

with

the

target

remote

A logical

1link

established

node.

SS$_ABORT

A physical 1line went down during a network correct operation.
SS$ ACCVIO
A

device

mailbox

read
by the
the caller.

name

caller,

string
or

the

string

channel

descriptor

number

cannot

written

SS$ DEVACTIVE
A mailbox

name

associated

SS$

has

with

been

the

specified,

but

mailbox

already

device.

DEVALLOC

Warning.

The device is a1located to another process.

SS$ DEVNOTMBX
A logical

but
SS$

the

name

has

logical

been

name

specified

refers

for

the

device

associated

that

not

mailbox,

mailbox.

EXQUOTA
The

target

process

has

control

block.

the

assignment

insufficient

1is
buffer

4-117

a
quota

remote
to

node

allocate

and
a

the

network

VDS

SS$

MACROS

- SYSTEM

SERVICE

MACROS

INSFMEM

The target of the assignment is on a remote node and there
insufficient dynamic system memory to complete the request.

|is

SS$ IVDEVNAM

device

name was

specified,

the

device

string
contains
invalid
characters.
If
target on a remote node, this status code

Network
SS$

Control

Block

has

invalid

mailbox

the device name
indicates
that

format.

name

is a
the

IVLOGNAM

The device or mailbox name string has a length of @ or has more
than

characters.

SS$ NOIOCHAN

No I/0 channel is available for assignmefit.
SS$

NOLINKS

No logical network links are available.
SS$ NOPRIV

The

process does

not

have

the

©privilege

operations.

perform

network

SS$ NOSUCHDEV

Warning.

The

specified

device or mailbox

does not

exist.

SS$ NOSUCHNODE

The

specified

network

node

nonexistent

SSS REJECT

unavailable.

The network connect was rejected by the network software or
the
partner
at
the remote node;
before the connect confirm could be

4-118

or the target
issued.

image exited

VDS MACROS - SYSTEM SERVICE MACROS
Notes:

Refer

the

before

the

VAX/VMS

$ASSIGN

System

system

attempting

I/O

Services

service.

operations

Reference

Manual

That manual
user

for

should

mode.

Examples:

MACRO-32

Example:

TTNAME ¢

+ARCTH

STTadt s

STERMINAL DESCRIFTOR

TTCHAN?

f BLIL

s TERMINAL

$A5GTENLE

BLISS-32

DEUNAM=TTNANME»

Example:

TTNAME

UFLIT

HIND

(ZasCIl

VECTOR»

"TTAZ:I
)

TTOHAN

$ASSION

(DEMVHAN=, TTHNAME:,

CHAN=TTCHAN)

4-119

CHANNEL

MNUMRER

CHAN=TTCHAN

notes

read

VDS

MACROS

SYSTEM

SERVICE MACROS

$DS_ATTACH
The Attach Device system service can

wused

use

"attach"

the

$DS ATTACH

device
automatically
from
within the
diagnostic
program,
instead of requiring the
program
user
to
1issue
the
ATTACH
An
1is discussed in Section 3.2.
devices
Attaching
command.

example of when it might be desirable

macro is the case in which record management services
to

used

default

MACRO-32

load

reference a

device.

file on a

device other

than

(RMS)
the

are

VDS

Format:

$DS ATTACH
x

cmd,

[pmt]

BLISS-32 Format:

_$DS_ATTACH

(CMD=cmd,

[PMT=pmt]);

cmd

Address of a quadword descriptor
command
argument
string.
If
contain every necessary response

"pmt"

should

parameter
not

include

that points to a valid
ATTACH
the
argument
string does not
to
each
ATTACH
prompt,
the

must also be specified.
prompting

strings).

(The argument string

pmt

Address of
a quadword descriptor pointing to a buffer that will
receive

error

messages

and

prompting messages

string pointed to by "cmd" is incomplete
or
parameter is optional only if the programmer

the

command

in
error.
This
is absolutely sure

that the specified command string will always
be
correct
for
any
hardware configuration.
Using the contents
of this buffer
is

Return

SS$

discussed

Note

Status:

NORMAL
Service

successfully

completed.

DS$ BADTYPE

invalid device

type was specified

4-120

the argument string.

VDS MACROS

DS$

- SYSTEM

SERVICE MACROS

BADLINK
The

device

1link

specified

1in

the

argument

string

not

was

too

attached.

DS$

ILLUNIT
The device unit
large.

number

was required

and

not

given,

DS$_ DEVNAME
-

The

device

name

specified

the

argument

string

invalid.

SS$ BADPARAM
A

numeric

range.

argument

was

specified

invalid

radix

was

out

SS$ INSFARG

\\‘\\

The

argument

string

was

incomplete.

Notes:
l.

If an'argument in the argument string is invalid, or if the
argument
a.

One

string
of

incomplete,

error

status

"cmd"

valid
The

will

portion
Dbuffer

invalid

codes

altered

following
will

the

reflect

argument

string.

described

VDS-generated

error

missing

macro.

The

user's

~argument
string,
argument string's
$DS ATTACH
macro
not actually

will

occur:

returned.

and

the

length

will
user

to
the

contain

prompt

for

the

used

the

argument.

response

buffer
can
parameter)
could

then

be
of
be

$DS_ASKSTRING
added
to
the

after
the
1last
wvalid
argument.
The
size would then
be
readjusted
and
the
would be reissued.
(Note that a p-table

built

this
process can
complete argument

"pmt"

message

The contents of
the
"pmt"
prompting
string
("msgadr"

the

The length field of the quadword descriptor pointed
by

Cc.

the

until

all

be repeated
string.)

4-121

arguments

until

the

user

are

wvalid,

has supplied

so
a

VDS

MACROS

SYSTEM

SERVICE

MACROS

This service will not display any information on the user's
simply using
occurs,
error
an
if
Thus
terminal.
and prompt
message
error
$DS ASKSTRING macro to display the
idea what
no
have
will
wuser
the
since
insufficient,
is
the
be necessary for
It will
device is being attached!
(1)
g
indicatin
message
ory
program to display an explanat
was
device
which
(2)
and
that an attach was being attempted
|
being attached.
Examples:

MACRO-32

Example:

CMDLINE:

L ARCID

ARH7E80

&EI

RHO

FUSLATTACH.S

CMILINE

BLISS-32 Example:
DIMI

= UFLIT

(¥6SCI0H

"RH780

_’)-

—
and

3
H

—

A e

a1t

CHIDLITNE

COMD=, CMOLINED #

4-122

SEI

RHO

5705

vDS

MACROS

SYSTEM

SERVICE

MACROS

- $BINTIM
The Convert ASCII String
an
ASCII
string
system 64-bit time

to Binary Time system service converts

to
an
format

absolute or
suitable for

offset
input

time value in the
to
the
SSETIMR

service.

MACRO-32

Format:

SBINTIM
x timbuf,
BLISS-32

timadr

Format:

SBINTIM

(TIMBUF=timbuf,

TIMADR=timadr);

timbuf

Address of a

character

pointing
to
the
to be converted.
The

maximum

string

descriptor

(see

Section

4.3)

buffer containing the absolute or offset
See notes for input string format.

offset

time

that

may

specified

10,000

time

days.

timadr
Address

quadword

receive

the converted

time

64-bit

format.

Return

Status:

SS$ NORMAL
Service

successfully

completed.

SS$ IVTIME

Syntax

out

range.

the

input

string

4-123

invalid,

the

specified

time

VDS

MACROS

SYSTEM

absolute

time,

the

SERVICE

MACROS

string

must

Notes:

For

input

formatted

dd-mmm—yyyy hh:mm:ss.cc
For absolute time, any of the fields may b@‘-omitted, but
all punctuation must be included.
The system will fill in
for

the current values

Examples

unspecified

all

fields.

are:

5-DEC-1983 5:16:14.98 (16 minutes, 14.98 seconds» after
on

A.M.

14:00:00.008

::05

5-DEC-1983)
(2

P.M.

seconds

today)

past the

current

time)

For relative time (time offset from the current time),
input
dddd

string

format

the

hh:mm:ss.cc

For
all

relative time, any of the fields may
be
omitted,
but
punctuation must be included.
The system will default

all

unspecified

Examples

fields
to 0.

are:

12:46:14.56

days,

seconds

from

5:12

(5 minutes

::10

(10

hours,

minutes,

now)

seconds

and

from

4-124

seconds
now)

from

now)

14.56

VDS

(‘

MACROS

SYSTEM

SERVICE

MACROS

Examples:
MACRO-32

Example:

ONE_MIN:

EIN_TIM?

«ASCID

» QUAD

$ERINTIM_S

BLISS-32

00:101:00.,00/

ONE_MINs

FDESCRIFTOR

sQUADWORD

FOR

HOLD

MINUTE,.

EBINARY

TIME.

BIN_TIM

Example:

BIND

ONE_MIN

UFLIT

(XASCID

‘0

00:01:100.007)f

DESCRIFTOR
FOR

LLOCAL
BIN_TIM

VECTOR

L2715

QUADWORD

HOLD

BINARY

+
+
<
&

$RINTIM (TIMEUF=0NE_MIN, TIMADR=BIN-TfH)§

4-125

TIME.

MINUTE.

VDS MACROS

- SYSTEM SERVICE MACROS

$DS_BREAK
The Break system service causes a

take

©place.

any asynchronous

character
to

All

from the

temporary return to
the
VDS
The main purpose of this return is to see if

events

user

(including

terminal)

receipt

have occurred and

control-C

are waiting

processed.

diagnostic

programs must

return

the

VDS

1least

once

every
three
seconds.
Issuing
any
system
service macro or
program control macro, plus some program structure macros (such
as
$DS _ENDSUB and $DS_ENDTEST) is considered to be
a return to

1if
called
be
the VDS, so the $DS BREAK service only needs to
‘none
of
those
macros
has
been
issued
1in
a
particular
"three-second
1interval.
Be
particularly
careful
that
all
this
to
adhere
3.10)
Section
(see
loops
program
potential
constraint.

MACRO-32

Format:

$DS_BREAK
(No

suffix.)

BLISS-32

Format:

$DS BREAK;
Return

Status:

None.

Examples:
MACRO-32
LG

Example:

HRE&R

BLISS-32

Example:

FIie . BRE AR

4-126

VDS

MACROS

SYSTEM

SERVICE

MACROS

Channel

system

service

can

$CANCEL
" The

Cancel

I/0O

I/0
requests
services.
The

which

I/0

cancel

all

used

that were created with the $QIO and
caller specifies the number of the

requests
current

are

and

pending

canceled,

I/0

and

operations

the

cancel

$QIOW system
channel
for.

service

directed

will

the

channel.
Level

MACRO-32

programs

not

use

this

service.

Format:

SCANCEL
x
BLISS-32

may

chan

Format:

SCANCEL

(CHAN=chan)
;

chah

:/,

Number of the I/0 channel on which I/0 is to be canceled.
Return Status:

SS$ NORMAL
Service

SS$

EXQUOTA
The

SS$

successfully

(user

process

has

only)

exceeded

Insufficient

direct

I/0

quota.

memory

service.

space

available

perform

the

that
is,
the number

a
of

Cancel

IVCHAN
An

invalid

number

channel
@

number
a

available.
SS$

its

INSFMEM

I/0

SS$

mode

completed.

NOPRIV
The

(user

specified

was specified,
number larger than

channel
channels

|
mode

only)

channel

privileged

access

was

not

mode.

4-127

assigned,

was

assigned

from

vDS MACROS

- SYSTEM SERVICE MACROS

Notes:

See

the

VAX/VMS System Services Reference Manual

of
discussions
requirements, and

|
privilege

other

notes

service.

Examples:

MACRO-32

Example:

$CANCEL.S

BLISS-32

CHANNUM

Example:

$CANCEL

(CHAN=,CHANNUM)

4-128

for

restrictions,= resource

relating

the

SCANCEL

VDS

MACROS

SYSTEM

SERVICE

MACROS

$CANTIM
The

Cancel

Timer

Request

system

timer
requests
previously
Section 3.14.4, Timing.

service

made

with

can

the

$SETIMR macro.

used

cancel

See

MACRO-32 Format:

SCANTIM
x
BLISS-32

[reqidt],

[acmode]

Format:

SCANTIM

([REQIDT=reqidt],

[ACMODE=acmode]);

reqidt

The request identification number of the timer request(s)

canceled.
A
request
1d number
request when the $SETIMR macro is

associated

to be

with

each timer
used.
The
SCANTIM
service
having the specified id number.

will
only
cancel the requests
The default value is @, which means
that
should be canceled, regardless of their id
acmode

(user

Access

mode

Return

less

timer

the

requests

maximized with
requests issued

privileged

than

the

canceled.
In user mode,
the
the access mode of the caller.
from an access mode
equal
to

resultant

access

mode

are

Status:

SS$_NORMAL
Service

successfully

completed.

Examples:'
MACRO-32

Example:

$CANTINM.S
BLISS-32

yCancel

timer

ICancel

z21]1

recuest(s)

with

Example:

$CANTIM

()

requests

numbers.

only)

access
mode
1s
Only those timer

all

timer

4-129

reacuests.

canceled.

VDS

MACROS

SYSTEM

SERVICE MACROS

$DS_CANWAIT
The Cancel Wait system service is used to cancel a program wait
created by using the SDS_WAITMS or $DS_WAITUS
was
state that
See

macro.

3.14.4,

Section

Timing.

MACRO-32 Format:

x
$DS CANWAIT_
BLISS-32

Format:

$DS_CANWAILT;

Return

Status:

SSS_NORMAL
successfully

completed.

Notes:
1.

The $DS CANWAIT macro is only useful if it is
1included
1in
that was
routine
service
interrupt
or
routine
AST
an
being
entered while a $DS WAITMS or $DS WAITUS service was
executed.

See

Section

Service

3.14.4.

Examples:
MACRO-32

Example:

DS _CANWAIT.S

BLISS-32

Example:

$NE_CANWATT#

4-130

VDS MACROS - SYSTEM SERVICE MACROS
SDS_CHANNEL
The Channel Adapter system
service
of
the
VDS
1is
used
to
control
functions
that
are initiated by referencing internal
registers in the bus adapters.
This service takes into account
all
processor—-specific
differences
1in
the adapters and thus
insulates the diagnostic program from those differences.
The

Channel

Adapter

service

enables

the

program

to:

Initialize a MASSBUS adapter or a UNIBUS adapter

Initialize

Enable and disable interrupts from a MASSBUS adapter

Abort

data

Purge

Set or

clear

Request

UNIBUS

adapter

transfers

UNIBUS

data

UNIBUS

clear

a MASSBUS

adapter

path

defeat

adapter

parity

status

For descriptions of the design and operation of the various bus
adapters

for

VAX

processors,

refer

the

VAX Hardware

Handbook.

The

Channel

diagnostic

MACRO-32

Adapter

service

func,

[vecadr],

may

only

used

level

programs.

Format:

$DS CHANNEL
x
BLISS-32

system

unit,

[stsadr]

Format:

$DS_CHANNEL (UNIT=unit, FUNC=func,

[VECADR=vecadr],

[STSADR=stsadr]);
unit

Logical

function

to which

unit

number

specified

this device

the

device

"func"

unit

will

unit

is attached.

4-131

performed

tested.

the

The

adapter

VDS

MACROS

SYSTEM

SERVICE

MACROS

func
Function

code

$DS CHANNEL
function

indicating

service.

codes

are

function codes are

the

function

Must

defined

described

literal
the

in Note

routine

$DS

performed

value.

CHCDEF

macro.

the

MACRO-32,
The

vecadr

Address

interrupt
specified

interrupt

occurs.
by "unit"

attached.
This
function code, in

service

receive

control

The
1interrupt
may
come
from
or from the adapter to which the

parameter
which case

is
it

only
wused with
is required.

when

the device
device
1is

the

CHCS

ENINT
|

Used

only

stsadr

Address of a quadword to receive
with

the

gases

Return

CHCS$

adapter

ENINT

and

CHCS STATUS

required.

The

adapter

status.

function

status
is

codes,

which

discussed

Note

Status:

SDS NORMAL
Service

successfully

completed.

$DS_ERROR

The specifiéd 1ogica1 unit number is too large.
$DS IHWE
Initial

hardware

adapter

before

function

will

hardware

error.

error

specified

performed.

not

error

CHCS STATUS

the

- after

this

condition

was

function

was

Note:

status

detected

initiated.

determine

returned,

the
The

exact

1issue

function.

$DS_IVVECT
The

p-table

parameter

for

the

contains

device

wunit

invalid

indicated

vector

with

the

"unit"

address.

$DS_LOGIC
An

attempt

failed.

set

Indicates

clear

bit

hardware

4-132

within

failure.

adapter

has

VDS

MACROS

function

SYSTEM

SERVICE

MACROS

$DS_NOSUPPORT
The

specified

being

used.

This

not

supported

error

the

condition.

processor

See

Note

type

$DS_PROGERR
An invalid function code was specified.
A

required

argument

was

not

list

included

with

the

macro

call.

valid functlon
status codes.

codes

along

Notes:

Following

their

functions

CHCS INITA

the

which

the
return

and

Initialize

the

device

MASSBUS

wunit

UNIBUS

specified

with

adapter

"unit"

attached.
Return

status

codes:

DS$ NOSUPPORT
e

CHCS_INITB

unit

Initialize

specified

Return

DSS$S NORMAL,

status

the

"unit"

codes:

DS$

DS$_ERROR,

UNIBUS

which

DS$ LOGIC,

the

CHCS_ENINT
UNIBUS

NORMAL,

DS$

which

the

attached.

Refer

"unit"

Return

status

CHCS DSINT
-

UNIBUS

ERROR,

DS$

- Disable

Return

status

attached.

the

MASSBUS

device

unit

specified

Note

for

details.

DS$ERROR,

DS$

DS$ PROGERR

interrupts
which

attached.

IVVECT,

CHCS ABORT

the

LOGIC,

for

DSS$S_NORMAL,

LOGIC,

adapter

codes:

DS$

"unit"

DS$

interrupts

DS$_NORMAL,

Enable

adapter

device

attached.

DS$ NOSUPPORT

IHWE,

for

the

MASSBUS

device

unit

specified

codes:

DS$ _NORMAL,

DS$ ERROR,

DS$S IHWE,

DS$ LOGIC

Abort

which

the

data
dev1ce

4-133

transfers on

the

unit

specified

MASSBUS
"unit"

VDS MACROS
Return

- SYSTEM SERVICE MACROS

status

codes:

DSS NORMAL,

DS$ ERROR,

DS$ NOSUPPORT

CHCS PURGE - Purge a buffered data path
on
The
buffered
data
path
that
1is
purged
specified by
the
1last
DS$ SETMAP
macro

UNIBUS

will

specified

Return

the

"unit"

one

status

which

attached.

codes:

a
UNIBUS.
1is the one
call.
The
device unit
|

the
|

DS$ NORMAL,

DS$ ERROR,

DS$ NOSUPPORT

CHCS CLEAR - Clear

status bits.

Clears

the status registers of the adapter

error

bits

1in

to which the device

unit specified by "unit"
is
attached.
This
function
should be requested before interrupts are enabled.
"Return status codes:

DS$ NORMAL,

DS$ ERROR,

DSS$_LOGIC,

DS$_NOSUPPORT

CHCS STATUS - Fetch status for the adaptér to which the

device
wunit
specified
by
"unit" 1is
attached.
The
current status of the adapter will be returned
1in
the
quadword specified by "stsadr." See Note 1 for details.
Return

status codes:

CHCS SETDFT

the

1is

Return
DS$

- Sets

the

which

adapter

"unit"

DS$ NORMAL,
Defeat Data

the

DS$ ERROR
Path

device

status

codes:

DS$ NORMAL,

NOSUPPORT

the

"unit"

to which

the

device

status

Path

unit

Parity

specified

bit

codes:

DSS NORMAL,

DSS ERROR,

Status

instances:

The

DS$ ERROR,

Adapter status will
1.

attached.

DS$_NOSUPPORT
Adapter

for

adapter

Return

specified

attached.

CHC$ CLRDFT - Clears the Defeat Data
for

Parity bit

wunit

CHCS

STATUS

interrupt

has

returned

function

occurred.

4-134

the

requested.

caller

two

the

VDS

MACROS

latter

case,

address
should)

SYSTEM

the

SERVICE

interrupt

was specified with
examine the status

MACROS

service

occurred.
The

routine

(whose

the "vecadr" parameter) can
quadword to see 1f
errors

(and
have

returned

Figure

status

gquadword

w111

have

the

format

indicated

4-5.

16 15

STATUS-1
VECTOR

STATUS-2

TK-10535

Figuré 4-5

Adaptér»Status Format

Note:

Both

longwords

CHCS

STATUS

the

first

longword

are

filled

function
filled

1in

when

interrupt

requested,

the

occurs.

however,

second

only

the

1longword

|is

cleared.

"Status-1"

is a bitmap,

condition.

Each bit

it,

also

these

the

form

defined,

symbols

Status-1

Bit

bits

bits
Bit

Bit

the

10 is

representing

name

longword

mask

for

CHSSM xxxxxx.

the $DS

error

associated

with

each

bit

MACRO-32,

CHSDEF

macro.

follows:

System

error.

Set

either

set.

25,

- Channel

26,

- CHS$V DEVERR

bit

symbolic

form

defined

- CHSSV_CHNERR

bits

with

are
are

XXXXXX.

- CHSSV_SYSERR
9

bits
Bit

CHS$V

each
has

and
-

error.

are

Device

Set

1if

any

error.

Set

is set.

either

-,cHssv_PGMERR

- Program

set.

error.

Set

if bit

set.

Bits

longword

Condltlons

and

mask)

types

Can

CHSSM ERRANY

SYSERR

ex1st.

4-135

wused

CHNERR,

(defined

test

DEVERR,

only

any

error

PGMERR

VDS

MACROS

SYSTEM

SERVICE

MACROS

has

the

occurred

bus.

Bit

did

not

respond.

— CHSSV _CHNDPE

- Data

map

frame

page

path parity error.

MASSBUS

failure/Overtemp.

A power

error.

parity

- CHS$V CHNMPE - Map

Bit 7

referenced

The

Bit 5 - CHS$V_DEVTO — Device timeout.

device

error

Some type of

Bit 4 - CHS$V _DEVBUS - Bus error.

parity error or a UNIBUS map register

parity failure was detected.

- CHS$V CHPFOT - Power

Bit 8

failure or overtemperature condition was detected.

Set if any
Bit 9 - CHS$V SYSMEM - System memory error.
to data
relating
conditions
error
of
number
a
of
was detected.

transfers

Bit 19 - CHS$V SYSSBI

having

this

- SBI
bit

1is

error.
set

detected.

condition
Bit

SBI,

CHSSV _PGMHDE

For

processors
©GSBI error

- Hardware-detected

program

The mapping registers were not set up correctly
error.
by the software, or the software attempted to 1initiate
was already in
one
while
transfer
data
MASSBUS
a
|
o
progress.

Bits 12 through 15 - Unused.
Bit

lo6

Bit
The

- CHS$V_MBAEXC — MASSBUS exception.

- CHS$V _MBANED
Nonexistent
MASSBUS
referenced
MASSBUS
device
did
not
Equivalent to bit 5.
-

Bit

18 - CHSSV_MBADTB

DTBUSY

'Bit

set

completed.

(not an

CHSSV MBADTC

data

transfer

bit).

MASSBUS

1is

MASSBUS

attention.

MASSBUS

Set

1if

set.

Bit 21 - CHS$V _MBACPE - MASSBUS control
Set

if MASSBUS

Set if MASSBUS DT CMP 1is set.

Bit 20 - CHSSV_MBAATN
MASSBUS ATTN

Set

- MASSBUS DTBUSY.
error

device.
respond.

MCPE

. 4-136

set.

parity

error.

VDS

Bit

INIT

Bit

MACROS

SYSTEM

CHS$V BUSINIT
is

SERVICE

MACROS

UNIBUS

INIT

asserted.

CHSSV_BUSIC -

UNIBUS 1n1t1allzat10n

',Set if UBIC is set.

Bit 24 - CHS$V_BUSPDN - UNIBUS power down.
PDN

error.

Set

MASSBUS WCK

LWR

Bit 26 - CHSSV_WBAWCKUPR - MASSBUS
error.

Set

Bit

device.

the
that

MASSBUS

CHSSV_BUSNXM

The

Whenever

program
the
bus

the

user's

A bit
that

the

called
the

A bit

that

contain

does

not

indicates

terminal.
exact

interrupt

check

upper

memory

This
cause

service

issued

conditions,

will
of

set,
the

enable
the

routine,

from

respond

error

CHIS$VCHNINT which,

interruptwas

so
be

the

error

"status-2"

indicates

adapter.

called

CHISVDEVINT which, if set,
1indicates
interruptwas issued from a device.

the

For MACRO-32,

device

the

IPL

the

at
bit
position
deflned by CHISS IPL,
interrupt.

the

defined

macro.
Note
that
CHISVCHNINT
not mutually exclusive, that is,

interrupt

starting
a length

the fields of "status-2" are

the
$DS CHIDEF
CHISV DEVINT are

The

1lower

set.

nonexistent

A
five-bit
field,
CHISV_IPL and having

received

check

follow1ng

whichcontains

write
is

address

the

condition.
examined

ERR

set.

UNIBUS

"status-1"

determine

should
call
the $DS SHOWCHAN service
adapter's
internal registers
will

user

WCK

referenced

displayed

will

Set

write

ERR is

completed.

set.

Bit 25 - CHSSV_MBAWCKLWR - MASSBUS

Note:

Set

set.

same

and

adapter

interrupt

by
and
both

can

time.

"vector"

field
will
contain
the
vector
of
the
device
which
caused the interrupt.
The field is only
relevant for interrupts
from
devices
attached
to
a
UNIBUS.

4-137

VDS

MACROS

SYSTEM

SERVICE MACROS

Interrupts

The CHC$ ENINT

function

for

interrupts

-enables

is capable
adapter
the
(if
adapter
interrupts must
Device
interrupts).
program.
by the diagnostic
enabled
function also loads the appropriate

MUST be used,
function
this
Thus
itself cannot generate interrupts.

vector

even

the

of generating
explicitly
be
The CHCS ENINT
if

addresses.

the adapter

of
Device vector addresses are loaded with the address
an
When
VDS.
the
within
r
preprocesso
interrupt
an

interrupt occurs, program control

interrupt

is vectored

the

preprocessor.

IPL
processor's
The preprocessor will first raise the
by
incurred
errors
for
Next it will check
to 17 (hex).
quadword.
status
the
construct
the bus adapter and then
adapter,
It will then determine the type of interrupt:
device, or "passive release." If the interrupt was from

an adapter or device, the appropriate bit in "status-2"
interrupt
user's
the
is set and control is passed to
If
.
instruction
JMP
a
with
routine ("vecadr")
service
is
instruction
REI
an
a "passive release" has occurred,
service
interrupt
<calling the user's
without
executed
|

routine.

the
check
The user's interrupt service routine should
ensure
to
quadword
status
address passed in the
vector
expected
the
from
was
received
interrupt
that the

can be done by comparing the vector 1in
This
device.
HPSW VECTOR of
the status quadword with the vector in

the interrupting device's p-table.

It is not wise to request the CHCS$ INITA or

function while

interrupts are

Processor-Specific

For

some

CHCS_INITB

enabled.

Considerations

processors,

some

functions

are

not

relevant.

functions will not cause an
such
requesting
However,
but
The $DS NOSUPPORT status will be returned,
error.

the
For

program

example,

VAX-11/730

need
the

but,

not necessarily test for this code.

CHCS$ INITB

1is

not

relevant

in order to allow a diagnostic program

to be compatible with all processor types, the VDS will

function
reject the
not
$DS_NOSUPPORT status code.

4-138

it will just return the
o

vDS

MACROS

SYSTEM

SERVICE

MACROS

Examples:

Following

will

example

function

SEARCH
MACRO-32

initialize

MACRO-32

MASSBUS,
an

RP@6

enable
disk

and

BLISS-32

bus

interrupts,

code

drive.

Example:

CYLINDERsRFOC(R2)

$OS_CHANNEL_.S

#CHC$_ENINT,

CLRQ

CH_.STATUS

MOVL

¥FSEAR
GOy
CH!
(R2)

REC

RITL

[lesired

culinder.

Enable

interrusrts.

IFL

disk

SERVICE_RTNy

FCHSSV_MBRAATN

CH_.STATUSs

20%

address

access.,

CH_.STATUS

Clear

SEARCH
Wait

status

auadword,

furmction.

for

finish,

20%2

IRIVEy

MOVL

Lower

NEXT_ADDRsRFDOACR2)

MASSRUS

MOVL

Initialize

$NS_SETIFL_.S

¥FCHCH_INITA

ORIVE,

W@F

$DS_CHANNEL.S

Check

for

drive

errors.

>
o

-r

¥FERRsRFIDS(R2)

BLISS-32

Example:

$0E _CHANNEL

(UNIT
FUNC

=
=

Initialize

MASSEUS

DRIVE,
CHC$_INITA)?}

$NS_SETIFL

(0)s

+ (RF_.BASE

Lower

RFDA)

IFL

+NEXT_ADDR

« {RF_BASE

RFIOC)

disk

+CYLINDER?S

llesired

culinder.

Enable

interrurts.,

UNIT

+IORIVE,

FUNC

CHC$_ENIT,

VECADR

CHon

$NS_CHANNEL

STSADLR

CH_.STATUS

+ (RF_BASE

RFCS)

Clear
=

GOs

+CH_STATUS

THEN

L K I

ELSE

+.+.4

uadword.

function.

for

drive

errors

occurred

finish.

“CHS$V_MBAATNs
1>y

RFILOS)

<ERRs1i:

]

status

SEARCH
Wait

+(RF_BASE

sccess,

SERVICE_RTN,

1
IF

CH_STATUS

REFEAT

UNTIL

address

+
*
4
+

4-139

then

LR
I

else

...

that

then issue

VDS MACROS

- SYSTEM SERVICE MACROS

$CLOSE

The Close File service of RMS is used to close a file after all
of the file has been completed.

processing

will also perform a $DISCONNECT operation.

The SCLOSE service

MACRO-32 Format:

SCLOSE fab,

[err],

[suc]

BLISS-32 Format:

(FAB=fab,

SCLOSE

[SUC=suc]);

[ERR=err],

rab

Address of the RAB to be associated with the FAB describing the
file to which <connection is to be made. (The address of the

"FAB

the

RAB.)

from

the

return

from

Address of a routine to be executed on error return
service.

suc

(user mode only)

Address of a routine to be executed on successful
the

Return

service.

Status:

Note:

For further details on return status

theVVAX*ll RMS Reference Manual.

refer‘ to

values,

RMS$ NORMAL

Service

successfully completed.

RMS$ CCF

Cannot close file.

(Status value will

FAB.)

4-140

placed
|

STV

(user mode only)

err

VDS

MACROS

SYSTEM

SERVICE

MACROS

Notes:

Table
IN

4-3

Reference

Table

lists

STANDALONE

4-3

the

MODE.

FAB

fields

used

user

mode,

For

Manual.

FAB

Fields

Field Mnemonic

the

refer

SCLOSE
to

the

service

VAX-11

RMS

Used

$CLOSE

(Standalone

Mode)

Field Name

Input:

IFI

Internal

file

identifier.

XAB

Extended attribute block éddress.

IFI

Internal file identifier (zeroed).

Output:

STS

Coméletion status code (also returned‘in RO) .

STV

Status

value.

Examples:
MACRO-32

Example:

$CLOSE FAE_ADDR
BLISS-32 Example:
$CLOSE

(FAER=FAER_ADDR):

4-141

VDS

MACROS

SERVICE MACROS

SYSTEM

$CLREF
(Event

The $CLREF macro is used to clear event flags.

are discussed

MACRO-32

Format:

SCLREF
x
BLISS-32

flags

in Section 3.14.2).

efn

Format:

SCLREF

(EFN=efn);

efn

Number of the event flag

number

may

standalone mode,

Return

from

to be

<cleared.

user

wmode,

the

1 through 23 or from 32 through 127.

flags 1 through 64 may be used.

Status:

SS$ WASCLR

Service

successfully

previously

completed.

The

specified

flag

was

completed.

The

specified

flag

was

number was

specified.

4@.

SS$ WASSET

Service

successfully

previously

SS$ ILLEFC

illegal

event flag

SS$ UNASEFC

flag
event
common
In user mode, indicates that the specified
process
the
with
d
associate
been
not
has
3.14.2)
Section
(see
issuing

the

CLREF macro.

indicates
In standalone mode,
through 127 was specified.
standalone

mode.

4-142

from 64
that an event flag
These flags are not valid in

VDS

MACROS

SYSTEM

SERVICE

Examples:

MACRO-32
$CLREF
BLISS-32

$CLREF

Example:
#5

iClear

event

flzg

!Clear

event

flag

Example:

(EFN=5)3

4-143

MACROS

VDS

MACROS

SYSTEM

SERVICE

MACROS

'$DS_CLRVEC
The Clear Exception or Interrupt Vector system service is
to

load

interrupt vector with the address of

purpose

the standard VDS condition handler
The

macro's

used

exception or

for

the

restore

specified

wvector.

standard VDS vector

contents after the vector has been modified with the $DS_SETVEC
service.

Only level 3 diagnostic'programs may use the SDS_CLRVEC macro.
MACRO-32 Format:
$DS_CLRVEC_x

vector

BLISS-32 Format:

$SDS _CLRVEC

(VECTOR=vector);

vector

The vector address, relative to the base of the System Control
Block

Return

(SCB).

Status:

DS$ NORMAL
Service

successfully

completed.

DS$ IVVECT

Address

specified

for

"vector"

not

valid

vector

address.

Examples:

MACRO-32 Example:
$DS_CLRVEC.S

BLISS-32

¥F"X60

tRestore
i memory

VDS handler address for
write timeout vector

Example:

$DS_CLRVEC

(XX’607)3%

Restore
! memorw

4-144

VIS handler address for
write timeout vector

VDS

MACROS

SYSTEM

SERVICE

MACROS

$DS_CNTRLC
The
It

Declare
can

Declare

the

Handler

system

service

has

two

purposes.

to:

control-C

program

user

handler

types

that

will

receive

control

when

control-C

Enable and disable delivery of control-Cs

Refer

Section

control-C

Control-C

used

the

$DS

handler

MACRO-32

and

CNTRLC

will

Handling

disabling

service

1is

Control—Cs,
delivery

not

wused,

for

details

control-Cs.

the

VDS

control-C

invoked.;v

Format:

SDS_CNTRLC_x
BLISS-32

3.14.6,

handlers

[astadr],

[disabl]

Format:

$DS CNTRLC

([ASTADR=astadr],

[DISABL=disable]);

astadr

Address

causes

VDS

the

control-C

handler.

handler

Default

value

1is

which

declared.

disable
Value

used

enabled.

disabled.
is

Return

SS$

1If

enabled,

control-C

indicate

disable

the

value

and

handler

control-C

set

(the

control-Cs
has

been

delivery

default),

will

should

control-C

disabled

delivery

control-C

delivered

will be
delivery

whichever

selected.

Status:

WASSET
Service

successfully

previously disabled

completed.

(the

disable

Control-C

flag

was

delivery

previously

was

set).

SS$_WASCLR

/.\

Service
successfully
completed.
previously enabled (the disable flag

4-145

Control-C

was

delivery
previously clear).

was

VDS

MACROS
-

SYSTEM

SERVICE

MACROS

Examples:

MACRO-32

Examples:

$NS_CNTRLC..S

CNTRLCmHDLR

$NS._CNTRLE..S

$NS_CNTRLC.S

BLISS-32

NISARL=%1

+I want to haendle control-Cs.,
rlet

VDS handle

conmntrol-Cs.

sDisable control«Ca}

Examples:

$NS_.CNTRLC

(ASTADR=CNTRLC_HDLR):#!I

$DS.CNTRLC

()5

ILet VDS handle control-Cs.

$NS.CNTRLC

(DISARLE=1)3»

Iiliszble

4-146

want

to handle control-Cs.

control-Cs.

VDS MACROS - SYSTEM SERVICE MACROS

$CONNECT
The

Connect

RAB

opened
after

MACRO-32

the

has

FAB

service

after

the

SOPEN

been

file

service.

RMS

used

described

The

file

rab,

associate

the

cannot

FAB

has

read

an
been

until

connected.

[err],

[suc]

Format:

(RAB=rab,

rab

[ERR=err],

[SUC=suc]);

|
Address

file
FAB

to
is

the RAB to be associated with the FAB
which »connectlon is to be made.
(The
the

(user

mode

Address

RAB.)

descrlblng

the
address
of the

only)
a

routine

executed

error

service.

suc

Format:

SCONNECT

err

FAB

with
it

SCONNECT
BLISS-32

RAB

return

from

the

(user mode only)
Address

the

Return

routine

executed

successful

return

For

VAX- 11

further

RMS

details

Reference

return

status

values,

Manual

RMS$ NORMAL
Service

successfully

completed.

RMSS CCR
An

from

Status:

Note:

the

service.

RAB

already

associated

with

RMSS$ FAB

The FAB block is invalid.

4-147

the

specified

FAB.

refer

VDS

MACROS

SYSTEM SERVICE

MACROS

RMS$_IFI
The

FAB's

IFI

field

invalid.

RMSS$ RAB

The

RAB block

invalid.

RMSS RAC

Invalid

record

sequential

and

access

mode.

RFA access modes

are

standalone

allowed.

mode,

only
|

Notes:

Table 4-4 lists the RAB fields used by the SCONNECT service
IN STANDALONE MODE.

Reference

- Table 4-4

For

user mode,

the VAX-11l RMS

Manual.

RAB Fields Used by SCONNECT

Field Mnemonic

refer

(Standalone Mode)

Field Name

Input:

FAB

Address of FAB.

ROP

Record—procéssing options.

(Only BIO is allowed.)

Output:

STS

Completion

status code.

Examples:

.MACRO—32 Example:

$CDNNECT RAB_.ADDR
BLISS-32

Example:

$CONNECT

(RAR=RAR_ADIDR)

4-148

(Also

returned

in R@.)

VDS

MACROS

SYSTEM

SERVICE

MACROS

$DS_CVTREG
The

Convert

service

assoclates
mnemonic

the

be used

each

field

constructed,

For

fields

available:
A

greater

mnemonic

(in

output
-

MACRO-32

$DS

value

String

system

one

longword)
of

one

output

bit

radix)

field.

the

only

are

two

the

associating

field's
In this

mnemonic

When

used:

bit,

with

and

that

with

string

length

associated

mnemonic

each

algorithm

only

the

specified

field

the

options

field,

field's

placed

with

numeric

into

the

field,

VALUE
can have a mnemonic assigned to
case, only the mnemonic is placed
1into

output

can

dlsplayed

$DS PRINTx

services.

string.

the

user

terminal

wusing

one

Format:

CVTREG

[v31,

than

any

following

1into

the

(or

current

the

the
string

the

Character

string.

Instead

the
it.

can

case

value

the

placed

For

consisting

are

which

The

—

indicates

mnemonic
is
bit is set.
¢

Contents

to produce an ASCIC character string

and

string
@

can

msb,

data,

mneadr,

strbuf,

[v4l, [v5], [v6]

maxlen,

[vl],

[v2],

BLISS-32 Format:
$DS

CVTREG

(MSB=msb,

MAXLEN=maxlen,

DATA=data,

[V1=vl1],

[Ve=v6]);

MNEADR=mneadr,

[V2=v2],

[V3=v3],

STRBUF=strbuf,

[Vd=v4],

[V5=v5],

msb

Most significant bit.
fields

progresses

indicates
31.

the

first

Reading

from

bit

1left

that

of the
to

specified

right,

read.

1location's

this

Maximum

parameter

value

data
Contents

the

converted.

contents,

but

the

(Note

contents

4-149

that

this

themselves.)

not

the

address

VDS

MACROS

- SYSTEM

SERVICE

MACROS

mheadr

Address of a

string

of mnemonics and

A mnemonic may be
a
character except '=',
Fields

are

specified

field

string of
any
',', or '@'.
in

the

following

specifiers.

1length,

containing
|

any

manner:

For one-bit fields,
simply
include
the
mnemonic
and
- follow it by a comma, such as ...,MNEM1l,MNEM2,MNEM3,...
For

multiple-bit

fields,

two

formats

are

used:

If a mnemonic is to be associated
with the field,
the format is "mnemonic=size”"radix", where "size" is
1n
radix
the
the size of the field and "radix" is
which
the field contents is to be displayed.
Valid

"o
(hexadecimal),
"X"
"radix" are
for
values
An example is IPL=5"X.
(octal), and "D" (decimal).

field's
the
is to be associated with
format is "mnemonic=size@", where
the

If a mnemonic
then
VALUE,

"size" is
mnemonic

value's
The
the field.
of
size
the
wusing the "v1" through "vé6"
specified
is

parameters.

If a bit is not to be

include

The

the

comma

first mnemonic

bit

indicated

will be assigned

included in

any

the mnemonics

the

list will

list;

field,
for

simply

example,

associated

with

the "msb" parameter. Mnemonics

from left to

right until

list
has
been
exhausted,
or
until
reached, whichever happens first.

the

bit

mnemonics

has been

strbuf

Address of a buffer to receive the character string.
maxlen

Length of

the buffer pointed

by "strbuf."

The buffer may not

If the character string
Caution:
than 255 bytes.
greater
be
a
contain
not
overruns the specified length, the buffer will
valid

string.

4-150

VDS

through

Each

these,

MACROS

SYSTEM

SERVICE MACROS

used,

is the address ofa
counted
table
of
Each table will contain pointers to lists of
to be associated with
the
©possible values
for a particular field.
One of these tables will be referenced
each time a field specifier with the format "mnemonic=size@" is
encountered
1in
the
mnemonic string (pointed to by "mneadr").
The first time that format is used, the
table
pointed
to
by

value
mnemonics.
mnemonics that are

"vl"

the
Each

to
in

will

table
entry

be
the

referenced;

field

field's
so on.

defined

will

wvalue

table

associated

field's
the
and

pointed

the

"v2"

will

with

the

second

will
the

used

the

first

time

format
and

used,

on.

of
a mnemonic

value.

offset
table

the

referenced,

address

field's

The

into

entry

value

the

that is
contained

table.

will

the

fetched;

1if
value is 1, the table's second entry will be
used,
The mnemonic pointed to by the table entry must be

by an ASCIC

string.

The

the

output
string.
Figure
involved in this mechanism.
Return

mnhemonic

4-6

will

1illustrates

placed

the

into

1linkages

Status:

DS$ NORMAL

Service

successfully completed.

DS$_PROGERR
The

output

provided,
The

string

invalid

string

of
field

was

too

larger

than

mnemonics
descriptor.

1large

255

and

fit

1into

the

field
)

descriptors

contains
|

" The value specified for "msb" was greater than 31.
The

total

number

macro

arguments

4-151

buffer

characters.

was

greater

than 11.

VDS

MACROS

V1:

SYSTEM

SERVICE

MACROS

ADDRESS OF
TABLE_T1

V2:

ADDRESS OF

TABLE_T2

TABLE_T1:

N
T1_ADDR_1

T1_ADDR_1:

.ASCIC /T1_STRING_1/

T1_ADDR_2

T1_ADDR_2:

.ASCIC /T1_STRING_2/

T1_ADDR_N:

.ASCIC /T1_STRING_N/

T2_ADDR_1

T2_ADDR_1:

.ASCIC /T2_STRING_1/

T2_ADDR_2

T2_ADDR_2:

.ASCIC /T2_STRING_2/

fi:

:F
T1_ADDR_N

TABLE_T2:

T2_ADDR_N

T2_ADDR_N: .ASCIC /T3_STRING_N/
TK-10536

Figure

4-6

$DS CVTREG

Value

Mnemonics

Table

Usage

Notes:

On return
length of

from the
service,
the output string,

A good convention to
unlabeled.
Fields

Rl
will
contain
even if the string

follow is
that must

the
total
overflowed.

to
not
1leave
any
fields
be zero (MBZ), are not used,

or consist of "don't care" bits
should
be
1identified
as
such.
This will cause the fields to be read and displayed,
and the program user will know if, for example, an MBZ
bit
actually

4-152

vDS

MACROS

SYSTEM

SERVICE

MACROS

Examples:

The

following

BLISS-32,

examples

method

MACRO-32

Example:

PSL_NME !

+ASCIC

1illustrate,

displaying

the

both

processor's

MACRO-32

and

PSL.

/CMs TR MBZ=2"XsFFDs
1S5y CUR=2RyFPRV=2@yMEZ,/

SIFL=8"XyMBZ=8"XsDVsFUsIVsTsNsZsVyC/
MODE_LIST:

.LONG

ANDRESS

KERNEL

+ADDRESS

EXEC

+ANDRESS

SUFER

cANDRESS

USER

KERNEL?

CEXEC?

SUFER:
USER?

‘

+ BLKE

+ASCIC

/KERNEL/

cASCIC

/EXECUTIVE/

+ASCIC
s ASCIC

/SUFERVISOR/

JUSERY/

255

OUT . BUF 2

MOVFSL

$0S_CVUTREG

sFetch

MSE
DATA

¥Creste
=
=

§$31y
ROy -

FSL

contents.

strinsg.

yhead 311 32 bits,
yFPSL contents.

MNEADR

FSL_MNE,

rMnemonics

STRBUF
MAXLEN

=
=

OUT_RBUF,y
#2855, -

yJutrut buffer,
sMaximum lendgth.

MODE_LISTy

Va2

MODE_LIST

]
4+
]

4-153

sl1st

table.

sand

table

string.

(use

1st

one

again)d.,

VDS

BLISS-32

MACROS

SERVICE

SYSTEM

MACROS

Example:

RIND

FSLL_MNE
UFLIT

(AASCIC

‘CHy TP s MBZ=2"XyFFID+ ISyCUR=2@yFRV=2C@yMEBZy IFL= BoX s MEBZ=8"Xy

HU:FU!IU:TsHerU9C’)i
BINI

RKERNEL
EXEC
SUFER
USER

=
=
=
=

UPLIT
UFLIT
UPLIT
UPLIT

OWN

1 VECTOR

MODE _LIST
OWN

OUT_RUF

(ZASCIC
(ZASCIC
(%Za48CIC
(ZASCIC

L33

[25%y

VECTOR

‘KERNEL’ Yy
E
TEXECUTIV)y

R
)y
‘SUFPERVISO

)s
“USLER

INITIAL

(45

RERNELy

EXEC»

SUFER>y

§
USER)

BYTED:

RUILTIN

MOVFSL
§

LOCAL
§
FOL_STORE

MOVFSL

IFetch FSL contents.
ICreate string.
IRead =211 32 bits.

(FSL_.STORE)

$NS_CVTREG

X1y

[ATA
MNEADR
STREUF-

= +FSL_STOREY
= FSL._MNE»
= OUT.RUF:s

MAXLEN

255

Vi1
V2

=
=

MODNE_L.IST,
MODE_.LIST)»

L X J

(MSE

4-154

contents.
IMnemonice string.
Dutrut buffer.

IFSL

IMaxlength.,
1ist Ltanle.
12nd table (use

one

sdgsin)d.

vDS

MACROS

I/0

Channel

SYSTEM

SERVICE

MACROS

system

service

$DASSGN
The

Deassign

release

'SASSIGN
macro

See

Section

all

that

Level
2R
I/0

was

diagnostic

operations

3.12.1.1

for

details

VMS

previously
a

1is

assigned

programs

should

device

have

been

I/O

user

mode.

wused

with

the

use

this

completed.

Format:

SDASSGN
x
BLISS-32

chan

Format:

SDASSGN

Return

channel

service.
when

MACRO-32

I/0

(CHAN=chan)
;

Status:

SSS$ NORMAL
Service

successfully

completed.

SS$_IVCHAN
An

invalid

number

channel
@

number
a

was

number

specified;
larger

than

that
the

1is,

channel

number

channels

avalilable.

SS$ NOPRIV
The

specified

channel

privileged

access

not

assigned,

was

assigned

from

mode.

Notes:

See the VAX/VMS System Services‘Reference,Manual
the

SDASSGN

performing
I/0

macro.
operations

That
in

manual
user

Examples:
MACRO-32

Example:

$IASSGN..S

BLISS-32

CHAN_NUM

Example:

PIASSGN

(CHAN=,CHAN_NUM)
;

4-155

mode.

should

for

notes

read
|

before
|

MACROS

SYSTEM

SERVICE

MACROS

vDS

$DISCONNECT
The

Disconnect

connection

record

RAB

from

between

stream

FAB

and

service

RAB

and

deallocates

RMS

FAB.

all

I/0

used

This

break

the

terminates

the

buffers

and

data

structures.

MACRO-32

Format:

SDISCONNECT
BLISS-32

rab,

[err],

[suc]

Format:

SDISCONNECT

(RAB=rab,

[ERR=err],

[SUC=sucl]);

rab

Address

the
err

the

address

(user

mode

Address

RAB

disconnected.

its associated

(The

RAB

will

contain

FAB.)

only)
a

routine

executed

error

return

executed

successful

from

the

service.
suc

(user

mode

Address

the

Return

routine

service.

return

from

Status:

Note:

the

only)

For

VAX-11

further

RMS

details

Reference

return

status

values,

refer

Manual.

RMS$ NORMAL
Service

successfully

completed.

RMS$ IFI
FAB's

IFI

field

invalid.

The

4-156

VDS

MACROS

id.

The

SYSTEM

SERVICE

MACROS

RMSS$ ISI
Invalid

stream

specified

RAB

and

FAB

connected.

were

not

RMS$_FAB
The

FAB

block

invalid.

block

invalid.

RMSS RAB
The

RAB

Notes:

Table

4-5

service
VAX-11

Table

4-5

lists
IN

the

RMS Reference

RAB

STANDALONE

Fields

Used

Field Mnemonic

fields
MODE.

used
For

user

the
mode,

Manual.

$DISCONNECT

(Standalone

Field Name

- Internal stream identifier.

Output:

STS

~ Completion status code.
(Also

returned

Examples:

MACRO-32 Example:
$DISCONNECT

BLISS-32

RAEB_ADLDR

Example:

$DISCONNECT (RAEB=RAR._ANDR) 3

4-157

the
|

Input:

ISI

SDISCONNECT
refer

R#.)

Mode)

vDS

MACROS

- SYSTEM

SERVICE

MACROS

$DS_ENDPASS

VDS
the
The End-of-Pass system service is used to indicate to
be
must
service
This
program pass has been completed.
a
that
included in the initialization code of every program.
Refer to
Section 3.5, Initialization Code, for an explanation of how the
$DS ENDPASS macro

MACRO-32

used.

Format:

$DS_ENDPASS_x;
BLISS-32

Format:

$DS_ENDPASS;

Return

Status:

This

service

does

not

return

status

code.

Examples:
Example:

ROy
10%

DS$_ERROR
,

104¢

then

F-tzble
211

for

units

declare

elee

Get

$0US_GFHARD
(DEVNAM
RETADR

unit.

dones

end-of-rass

continue.

Example:

Get

$NS_ENDFASS.S

‘BLISS-32

CHMPL
BENEQL

FTAEBLE.ADDR

LOGLUNITs

$NS _GFHARDLS

MACRO-32

F-table

for

» LOGUNITy
FTARLE_ADDR)

EQL DS$_ERROR

THEN

$DS_ENDFASSHS

311

declare

4-158

units

dones

end-of-r3s88.

unit.

VDS

MACROS

SYSTEM

SERVICE

MACROS

$DS_ERRDEV

$DS_ERRHARD
$DS_ERRPREP

$DS_ERRSOFT
$DS_ERRSYS
The

five

the

error

program

relate

reporting

user

any

to failures
in

system

services

errors

encountered

the

device

The

SDS_ERRDEV macro

1is

The

SDS_ERRHARD macro

errors.

The

$DS_ERRPREP

preparation

being

macro

1is

used
by

the

report

program

report

device-fatal

report hard

used

errors.

report

errors.

The $DS_ERRSOFT‘macro

is used

The $DS_ERRSYS macro

to
that

tested.

wused

used

are

device

to report soft'errors.

wused

report

system—-fatal

errors.

The error'types are discussed in Section 3.9, Reporting Errors.
The error reporting system services will:
l.

Display

title,

the

"header

message"

pass,

message
specified
by
parameter (see below).
Cause

the

message

"prlink" parameter
Test

set,
is

the

set,

3.10,

VDS

program

and

the

routine

subtest
error

specified

(see below)

control

execution

<consisting

test,

flags

the
loop

Looping).

4-159

HALT

of the
numbers,

macro's

the

"msgadr"

macro's

to be called.
and

LOOP,.

program

will

established

error

program
and the

I£f

stopped.
(see

HALT

1is

LOOP

Section

VDS

MACRO-32

MACROS

SYSTEM

SERVICE

MACROS

Format:

$DS_ERRDEV
x [num], [unit], [msgadr], [prl1ink], [pll,...[p6]
$DS_ERRHARD
x [num], [unit], [msgadr], [prlink], [pl]l,...[pb]
SDS _ERRPREP
x [num], [unit], [msgadr], [prlink], [pl]l,...[pb]
$DS _ERRSOFT
x

$DS _ERRSYS
x

BLISS-32

[num],

[unit],

[msgadr],

[prlink],

(pll,...[p6]

[pl]l,...[p6]

Format:

$DS_ ERRDEV

([NUM=num],

[PRLINK=prlink],

[UNIT=unit],

[MSGADR=msgadr],

[Pl=pl},...,[P6=p0]);

$DS_ERRHARD

([NUM=num],

[UNIT=unit],

[MSGADR=msgadr],

$DS ERRPREP

([NUM=num],

[UNIT=unit],

[MSGADR=msgadr],

[PRLINK=prlink],

[Pl=pl],...,[P6=p6]);

[PRLINK=prlink],

$DS ERRSOFT

[Pl=pl],...,[P6=p6]);

([NUM=num],

[PRLINK=prlink],

$DS_ERRSYS

[UNIT=unit],

[MSGADR=msgadr],

[Pl=pl],...,[P6=p6]);

(INUM=num],

[PRLINK=prlink],

[UNIT=unit],

[MSGADR=msgadr],

([Pl=pll,...,[P6=p6]);

num

An identification number assigned to the error macro.
specified,
a
number
is
automatically
assigned to
macro at program assembly
time,
according
to
the

If
not
the error

following

algorithm.

The

error

test

and

number
each

set

the

beginning

subtest.

each

Each
time
one
of
the
error
reporting
macros
encountered
at assembly time, the macro is assigned
current error
number
and
then
the
error
number

is
the
is

incremented.

If a macro
parameter,
number

Thus

the

call possesses
an
that
argument
1is
not

argument
used and

for
the
the stored

"num"
error

incremented.

default value

for

"num"

always

taken,

each

error

reporting macro within a given subtest will have a unique error
macros
error
the
number assigned to it, and for each subtest
will

numbered

sequentially starting

4-160

with

VDS

the

MACROS

$DS_ERRxxxx

argument

must

SYSTEM

form

SERVICE

the

MACROS

macro

specified

using

number

the

unit

the

used,

$DS ERRNUM

the

"num"

macro.

unit

The

logical

unit

currently

being

tested.

msgadr
-

Address

message

counted

header.

ASCII

Should

error.

string,

contain

included

short

the

description

error
of

the

prlink
Address

error

reporting

routine.

Routine

must

delimited
by $DS BGNMESSAGE and $DS ENDMESSAGE macros
use $DS_PRINTB and $DS PRINTX macros for output.
Pl

through
- One

must

paSs

p6
six

optional

arguments

contained

Return

and

the

©parameters
error

that

reporting

"prlink."

may

routine

used
whose

address

Status:

None.

"Notes:
l.

Registers

pointed

Error

The

R1l1l are preserved so
"prlink" can expect to find

Reporting

Routines:

"prlink"

parameter

routine to the
first dlsplays
to

through

The
properties:

error

entry

used

link

called

Then

the

reporting

with

routine

CALLG

pointed

must

have

instruction,

the

routine
intact.

error

error macro.
The error reporting
the header message, including the

"msgadr."

called.

that

them

service

text

pointed

the

reportlng

system

"prlink"

must

have

BGNMESSAGE

and

mask.

It
must
be
delimited
$DS _ENDMESSAGE macros.

4-161

the

SDS

following

VDS

MACROS

SYSTEM

SERVICE

It must print the second and

third levels of

message (see Section 3.9, Reporting Errors)
$DS_PRINTB and $DS_PRINTX macros,

MACROS

error

the

by using the

respectively.

It can reference arguments passed via the pl through pb6
These parameters can be accessed using the
parameters.
symbols defined by the $DS_ERRDEF macro.

It must contain all of

macros

the

$DS PRINTB

and

$DS PRINTX

that are used to display the error message.

(If

$DS PRINTB and $DS PRINTX macros are used to display an
an error
in
contained
they must be
message,
error
reporting

routine.)

Examples:

Note:

These examples will produce error messages

format
the
to
Formats.

indicated

4-162

Section

5.6.1,

that

Error

adhere

Message
|

VDS MACROS - SYSTEM SERVICE MACROS
MACRO-32

Example:

READERRMSG

+ASCIC

/REAL

FMT _GOODERAL:

CASCIC

N1 /V/Nlevice

error

while
base

rerforming

block

transfer./

address!i
_ 1 _1S5LN\~

N Aodress

exrected

buffer!
31 _ 15\~

NI /faddress

received

opuffer!
1 _ 1S5\~

(words)
! 1 15 \~-

N /Transfer

size

N Words

error!
L HL R

ST AN

FHT_DUMFHIRS

+ASCIC

\NI/V/ADDRESS
)V _EXFECTEDS | _RECEIVED ! _XOR 1/ 1 /N

FMT _DUMFRUF
3

fASCTC

NISLE_TSL
IS
PSR EAN

BUFIUMF
3
$1S
. BGNM ESSAGE

<R2yR3yR49yRE
-

TGS FRIN TR.S

FMT_GOODRAD s ~

’

Frint

second

level

ERR$ . FS(AP) yERR$._F2(AF) sERR$_FL1(AF)»

error

msdg,.

INCL

XORL
3

R3IsyRA»REG

$OS_FRIN TX.5

FMT _DUMFRUF
» -~

R3s (R4

‘a@p

20%

REQL

WFr

(R3)y (R4)

Get

zsddr.,

received

bouffer

W@r

CMFUW

for

erraor

count

Get

=zador.

exrected

buffer

REFEAT

EXF_.BUF sR4

header

See

this

‘gp

REC .BUFsR3

MOVAL

Frint
Clear

word

1is

CVr

MOUVAL

’

THEN

FHT _DUMFHIDR

Count

XOR

CLRL

FRR$ _FI(AF)
yERR$ _F4CAF)
$ODS_FRIN TX..S

Frint

word

the

baed

line

data

3rd

msd.,

level

» (RI) P RO

CMFL

R2: %8

REQL

JO%

THEN

CHMFL

(R3)+s (K4) +

CMFL

R3»¥REC_RUF _SIZE

BRE

10¢%

eight

Increment

S5ee
UNTIL

bad

words

stogr.
tor

entire

MEGADR=REANERRMSGy

FRLINK=RUFDUMF
.
F1=REC_RUF,

F2=EXF_BUF,

FI3=#REC._RUF _STZE,

FA=ERR_COUNT,

FPO=DIEV_RASE
[3

$NS _ENDTEST

4-163

rointers,

bhuffer

buffer

BGNTEST

UNIT=LOG_UNIT>

disrlavedy
.

buffer

$N5 _ENDM ~55AGE

$11S_ERRH ARD..S

dgoo0a0.

error.
and

$OS

dums

fad

do0o0d

ouffer

reached.

done.,

VDS

BLISS-32

MACROS

SYSTEM

SERVICE

MACROS

Example:

LITERAL

REC.BUF_SIZE

2567

BIND
‘

READERRMSG

UFLIT

(XASCIC

‘READ

error

rerforming

block

transfer.’
)y

OWN

REC_.BUF

VECTOR

[REC.BUF_SIZE,WORDIJ»

EXF_BUF

{

VECTOR

C[REC-RUF_.SIZE,>WORDIs

LOGUNITERR_COUNT

DEV_BASE s

$IIS__BEGNMESSAGE

(ROUTINE
. NAME=RUFDUMF)

LLacal

ERRORS
CXORVALUES

BRIND
~

/1 /Tlevice

| /Address

(ZASCIC

I /Address

UFLIT

1 /Transfer

size

FMT . G0ODEBADL=

bhase

address!_
{1 _18L7)y

V/Words

error!
31 _1SL7 )y

FMT_GOODRAD2=
UFLIT

(ZASCIC

exrected

buffer!_11_1G5L"
)

received

buffer! _11_15L" )y

FMT..GOODRAD3=

UFLIT

(XZASCIC

FHT..GOODEAL4A=

(XASCIC

(woras)l_t1_1SL7
)y

CURFLIT

(XASCIC
-

UFLIT

(XASCIC

UFLIT
FMT_DUMFHIOR=

(XASCIC

“!SLI.YSLY_ISLY_ISLY/
7))y

FMT .GOODNRADG=

1 /1 /ADDRESS I _EXFECTED: ' _LRECEIVED: ! _XORI Y/ 1/ 7 )y

FMT .DUMFRUF
=

UFLIT

NNisrlaw

the

b
'

second

level

the

error

FRINTE

(FMT_.GOOIBADINLSF3)

$OS_FRINTR

(FMT.GOODRADZSF2)s

$OS_FRINTE

(FMT_GOOLERADZsF1)
3

$OS _FRINTE

(FMT_.GOOLRBRADN4,F3)5

$OSFRINTER

(FMT_GOODERAUSF4)

liselese the
Firet srint

third level of
the header and

$NS_FRINTX
EREORS

the error
clesr the

(FMT_ _DUMFHIOR) s

0Oy

4-164

messadge.

messade.,
error count.

Frint

header

for

Clear

error

count

buffer

dumr.

VDS

Now

comrare

the

mismatches,

INCR

MACROS

exrected
more

INDEX

FROM

SYSTEM

buffer

than

with

eight

SERVICE

the

errors

received

are

REC_RBUF_.SIZE

MACROS

can

+REC_BUF

L[C.INDEX]

NEQ®

Disrlay

all

stor,

REGIN
IF

buffer.

found,

.EXF_BUF

L[.INDEXI

THEN
REGIN

ERRORS

.ERRORS

XOR_VALUE

+REC.RUF

$OS_ FRINTX

[C.INDEX]

XOR

|
JEXF_EBUF

(FMT_ .DUMFRUF

REC.EBUF

LC.INDEX1,

JEXPLRUF

CLINDEXDy

JRECEUF

C+INDEXDy

e XOR _VABLUE)
S
END
G

.ERRORS

EQL

THEN

EXITLOOF;

END
s
$DS_ENDMESSAGE5
+
[4

$IS_EGNTEST (TEXT=’Read tests’);
¢

$NS_ERRHARD

(UNIT=.LOG_.UNIT.,

FRLINK=RUFLUMF,

MSGAIR=READTERRMSG
»

F1=REC_.RUF,

F2=EXF_RUF »

F3=REC_.ERUF_.S5IZE
>

F4=,ERR.COUNT.

Fo=.DEV_BASE)

$DS_ENDTESTS

4-165

L[.INDEX1:

vDS

MACROS

SYSTEM

SERVICE

MACROS

$FAO
$FAOL
The Formatted ASCII Output (SFAO)
system
means
by
which
complex
messages can be
character strings.
This macro can be used
¢

Insert

variable

character

string

service

provides

formatted
to:

data

1into

into

a
ASCII
‘

output

string.

Convert binary values into the ASCII representations
their
decimal,
hexadecimal,
or
octal equivalents
substitute the results into an output string

The system service constructs an output string by
formatted ASCII output (FAO) directives contained
string" and using those directives to operate on
of

value

The

of
and

referring
to
in a "control
the
contents

parameters.

SFAOL macro

performs

the

exact

same

function

the

of
an
address
parameter to be

SFAO
of
a
listed

macro,
but
allows
the
specification
parameter list instead of requiring each
explicitly in the macro call.

Format:

SFAO
x
SFAOL
x
BLISS-32

SFAO

MACRO-32

ctrstr, [outlen], outbuf, [pl], [p2],
ctrstr,
[outlen], outbuf, prmlst

...[pn]
~

Format:

(CTRSTR=ctrstr,

[OUTLEN=outlen],

[P2=p2],

...[Pn=pnl);

SFAOQOL

(CTRSTR=ctrstr,

OUTBUF=outbuf,

[OUTLEN=outlen],

[Pl=pl],

OUTBUF=outbuf,

PRMLST=prmlst)
;
ctrstr

Address of a

character

pointing

the

set

string

"control

Formatted

ASCII

directives are described

descriptor

string."

Output

(see

The control

Section

4.3)

string contains a

(FAO)

directives.

1length

These

in the notes of the $DS_PRINTx macros.

outlen

Address

constructed
by

word
the

receive

service

routine.

4-166

output

string

VDS

MACROS

SYSTEM

SERVICE

MACROS

outbutf
Address

pointing
string is
pl

through
@

character

pn
20

directive

that

value

that

use

the

prmlst

the

Parameters

control

The
f

are

parameters,

corresponding

(see

fully

Section

formatted

contained

FAO

converted,

inserted,

listed

string.

the

than

directive, a
the
address

1length,

order

they

are

4.3)

output

longwords.

parameter may
of
a
string

argument

referenced

parameters

S$FAOL macro.

must

count.
by

the

specified,

(SFAOL only)

Address

parameters.
already
to

descriptor

(SFAO only)

Depending

string

to
the
output
buffer.
placed in this buffer.

Return

1list

The

existing

extracted.

1longwords

1list
data

may

structure

containing

any

from

length.

which

the

directive

It may be an

certain

wvalues

are

Status:

SS$_NORMAL
Service

successfully

completed.

SS$ BUFFEROVF
Service

successfully

completed,

string

was

than

(see

greater

the

but

‘the

maximum

size

allowed

and

the

was

output

truncated

notes).

SS$ BADPARAM

invalid

FAO directive was

specified

the control

string.

Notes:

1If

the

formatted

user's

$DS PRINTx
Refer

output

terminal,
to

macro

the

string

is to
important

1is

cause

description

the
of

4-167

the

be
displayed
on
the
to
select the proper

message
$DS

PRINTxX

displayed.

macros.

vDS

MACROS

SYSTEM

SERVICE

MACROS

Examples:

This

example

will

VALUES
MACRO-32

create

20@¢

the

(DEC)

following

0@@@0@12C

string:

(HEX)

-400

(SIGNED)

Example:

FAODESC?

illescrirtor for outrut buffer
+LONG
+LONG

80
FAORUF

s Qutreut buffer lensgth
sAddress of buffer

FAORUF:

BLKE

»30~character

FAOLEN?

+BLKW

sWord

buffer

receive

lendgth

outrut

CNTRL.STRING:

+ASCID
/VALUES
+LONG 200

Val.1:
VAL 2:

+LONG

300

VAL 3

+LLONG

~400

$FAD.S

(DEC)

'XL

CTRSTR=CNTRL.STRING,

(HEX)

'SL

(SIGNEIDN/

OUTRUF=FAQDESCy DUTLEN=FAOLEN, -

Fi=VAalLl,

BLISS5-32

F2=VALZ,

F3=VAL3

Example:

VECTOR
VECTOR

[80s
[21

L L

VECTOR
VECTOR

FAODERUF)

WORDIy

INITIAL

(200D,

VECTOR
INITIAL

(200D

VECTOR

INITIAL

(~400)

(ZASCID

‘VALUES

RIND
UPLIT

(80s
[1,

$FA0

(DEC)

'XL

(HEX)

)5
(SIGNELD

(CTRSTR=CHTRL_S5TRING>
OQUTBUF=FAODESC,

OQUTLEN=FAOLEN>
F2=VAL2y

Pi=VAalLly

F3=VAL3);

Val
3

®»
g

ValL
2

INITIAL
FAOLEN
VALl

RBYTED>

FAODBUF
FADDESC

OUWN

4-168

VDS

MACROS

SYSTEM

SERVICE

MACROS

$GET
The

Get

file.

Record

The

with

the

may

file

SOPEN
read

service

must

and

from

file

These access
Management.

MACRO-32

SGET

used

previously

services,
sequentially

methods

are

read

record

opened

from

and

connected

respectively.

Records

discussed

the

random-hy-RFA

Section
’

3.15,

Format:

rab,

BLISS-32

$SGET

RMS

been

$CONNECT
the

method.
F'ile

have

[err],

[suc]

Format:

(RAB=rab,

[ERR=err],

[SUC=suc]) ;

r ab
Address

file

FAB

etr

to
in

the

RAB

which
the

associated

connection

RAB.)

with

the

made.

FAB

(The

describing

the

address

the

(user mode only)
Address

routine

executed

error

executed

successful

service.
suc

(user

mode

Address

the

Return

from

the

only)
a routine

service.

return

from

Status:

Note:

the

return

For

VAX-11

further

RMS

details

Reference

return

Manual.

RMS$ NORMAL
Service

successfully

completed.

4-169

status

values,

refer

VDS MACROS

- SYSTEM SERVICE MACROS

RMS$ EOF

Attempt was made to read beyond end of file.
~RMSS_FAB-

The FAB block 1is invalid.
RMSS IFI

The FAB's IFI field is invalid.
RMS$ ISI

The

RAB's

field

ISI

invalid.

RMSS$ RAB

The

RAB block

invalid.

RMS$ RER

Read error.
STV field

(The device driver's return status will be in

the

RAB.)

the

'RMS$_RFA

Invalid RFA was specified
RMS$

in random-by-RFA mode.

RTB

Record retrieved was too big for the buffer provided,

and was

truncated.

Notes:

IN
Table 4-6 lists the RAB fields used by the SGET service RMS

STANDALONE

Reference

MODE.

For

user mode, refer to the VAX-11

Manual.

4-170

Table
Field

4-6

VDS

MACROS

RAB

Fields

Used

Mnemonic

Input:

Field

SYSTEM

SERVICE

$GET

MACROS

(Standalone

Mode)

Name

ISI

Internal

RAC

Record access mode.

-RFA

Record's address. (Used only if RAC=RFA.)

ROP

Record-processing

UBF

User

record

area

address.

usz

User

record

area

size.

RBF

Record

RFA

Record's

stream

identifier.

options.

Output:

/')/-\

RSZ

Record

address.

file

address.

size.

STS

Completion status code.

STV

Status value.

Examples:
MACRO-32

$GET

BLISS-32
$GET

Example:

RABR_ADDR

Example:
(RAB=RAB_ADDR)s

4-171

(Also returned

in R#).

(See Return Status, above.)

VDS

MACROS

SYSTEM

SERVICE MACROS

wused

$DS_GETBUF
The

$DS GETBUF macro

obtain

buffer

space.

standalone
mode, the buffer space is allocated by the VDS from
VM5
the
calls
VDS
the
In user mode,
its free memory pool.
- SEXPREG
system
service
(see
the
VAX/VMS System Services
Reference

The

Manual

caller

service

for

details).

indicates

the

returns

the

1low

number

and

high

pages

allocated.

When

can

the

desired,

addresses

and

of the

the

space

program

returned

longer

needs

the

allocated

buffer

space,

the free memory pool with the $DS RELBUF

macro.

MACRO-32

Format:

$DS GETBUF
x pagcnt,
BLISS-32

[retadr],

[phyadr],

[region]

Format:

SDS GETBUF

(PAGCNT=pagcnt,
[RETADR=retadr],
[PHYADR=phyadr],
[REGION=regilon]);

pagcnt

Size

(number

pages)

desired

for

bhuffer.

retadr

Address
of
a
two-longword
array
addresses of the low and high buffer

to
receive
limits.

the

vir tual

phyadr

Address
of a two-longword array
of low and high buffer limits.
in

standalone

mode.

4-172

to receive
physical
addresses
This parameter is only relevant

VDS

MACROS

SYSTEM

SERVICE

caller

wishes

MACROS

region
Memory

region

allocated.

from

Values

buffer

allocated

from

space.

buffer

allocated

from

space.

buffer

allocated

from

system

standalone

buffer

space

are

management

Return

which

mode,

this

turned

on.

parameter

(Default.)

space.

only

relevant

memory

Status:

SS$ NORMAL
Buffer

space

SSS_ACCVIO
The

SS$

(user

"retadr"

EXQUOTA
The

allocated.

mode

only)

array

cannot

(user

process

mode

written

the

caller.

only)

exceeded

its

paging

was

less

than

set

1limit

file

quota.

SS$ ILLPAGCNT
Requested

page

count

SSS;INSFWSL (user modé only)
The

©process's

accommodate

working

the

increased

virtual

address

not

1large

-enough

space.

SS$ VASFULL

Insufficient virtual
buffer
RO

request.

(standalone

Illegal

value

(See
mode

was

address
note

space

available

4.)

only)

given

for

"region"

4-173

parameter.

fulfill

the

vDS

MACROS

SYSTEM

SERVICE

MACROS

No tes:

Pl space

is requested

<contain

will

the

first element and

"retadr"

the

will

lowest

available

there

are

requested,

allocated.

then

element.

its second

space will always
returned.

physical

©pages

fewer

number

starting

the

available

pages

the

"retadr"

the

than

addresses

array.

Example:

BLISS-32

#10,

BUFLIMITS

tAek

for

yAsk for

10 radges.

Example:

GETRUF

sadges

(FAGCNT=Gy

RETADR=RBUF _LIMITE,
REGION=1)3

4-174

srace.

number

available will be

Examples:

$NS._GETEUF_S

page.

The beginning and ending virtual

this area will be placed

MACRO-32

allocated

In standalone mode, buffer space is allocated
the

array

high address as its

If there is not a set of contiguous
the
then
size,
buffer
requested

pages.
as contiguous
the
to
equal
pages
status

space's

the low address as

1In standalone mode, buffer

SS$ VASFULL

in user mode,

allocated

VDS

MACROS

SYSTEM

SERVICE

MACROS

$GETCHN
The

Get

I/0

Channel

information
about
assigned.
Two sets

The

primary

The

secondary

most

cases,

the

Information

two

sets

secondary

characteristics

the

are

device

the

characteristics

instances

are

not

are

device

1is
are

with

are

1identical.

the primary

mailbox,

the

those

spooled

those

are

which

and

same:

those

characteristics

secondary

the

associated

characteristics
the

three

characteristics
secondary

returns

has been
desired.

characteristics
device characteristics

there

service

device

However,

system

a
device
to which an I/0 channel
of information can be returned, if

the
device

the

device,

the

mailbox.

the

intermediate

characteristics

are

1ink

those

primary
and
the

primary
device

the

and

spooled

device.
3.

the

device

secondary

the

diagnostic

primary

and

service

Note:

programs
the

VAX/VMS

not

the

plans

1logical

System

describe

running

available

VMS

that

remove
Services

level

all

SGETDVI

network,

newly

the

link.

standalone
will always be

service

support of
Reference

4-175

in
the

characteristics

recommended

use

because
of

program

secondary

This

characteristics

mode,
the
identical.

programs.
developed

1instead

SGETCHN
Manual.

from

1level

SGETCHN,

VMS.

Refer

VDS

MACRO-32

SYSTEM

SERVICE

MACROS

Format:

[prilenl],

SGETCHN chan,
BLISS-32

MACROS
-

[pribuf],

[scdlen],

[scdbuf]

Format:

SGETCHN
(CHAN=chan,
[PRILEN=prilen],
[SCDLEN=scdlen], [SCDBUF=scdbuf]);

[PRIBUF=pribuf],

chan

Number

the

I/0 channel

assigned

the

device.

prilen

Address of

word

receive

the

1length

the

primary

characteristics.
pribuf

Address of a

pointing
The

default

character
is

buffer
@,

string
that will

implying

descriptor
(see
Section
4.3)
receive primary characteristics.
buffer.

scdlen

Address of a word

receive

the

1length

the

secondary

characteristics.
scdbuf

4.3)
Section
(see
descriptor
string
Address of a character
ics.
characterist
pointing to buffer that will receive secondary
The

default

implying

4-176

buffer.

VDS

Return

MACROS
-

SYSTEM

SERVICE

MACROS

Device

information

Status:

SS$ BUFFEROVF
Service

the

successfully

buffer(s),
so

completed.

information

was

overflowed

truncated.

SS$ NORMAL

Service successfully completed.
SSS

ACVIO (user

mode

only)

A buffer descriptor
or

buffer

length

cannot be

cannot

read by the caller,

written

the

bhuffer

caller.

'55$_IVCHAN
-~

invalid

number

of
avallable.

SSS NOPRIV
The

channel

number

was

number

specified,

greater

than

that

the

1is,

channel

number

channels

(user

specified

mode

only)

channel

privileged

access

not

assigned

was

assigned

from

mode.

Notes:

In standalone mode, the device characteristics are
placed
into
the
specified
buffer
in
the format illustrated in
Figure 4-7.

16 15

DEVICE CHARACTERISTICS
BUFFER SIZE

TYPE

CLASS

DEVICE-DEPENDENT INFORMATION

UNIT NUMBER
TK-10537

Figure

4-7

Device

Characteristics

4-177

Buffer

(Standalone

Mode)

MACROS

VDS

SYSTEM

SERVICE

" Following the unit number is an ASCII
the device's generic

name.

MACROS

string

representing

dependent
"device
and
characteristics”
"device
The
mode.
user
for
are
they
as
same
information"TM fields are the
details.
for
Guide
User's
I/0
VAX/VMS
Refer to the

placed

1into

VAX/VMS System Services Reference Manual

for

the device characteristics

In user mode,

are

the spec1f1ed buffers in the format detailed in the VAX/VMS

I1/0

Guide.

User's

Refer

to the

privilege restrictions
service in user mode.

and other notes on the use of this
|

Example S
MACRO-3 2

Example:

CHAN NUM?: .WORD
RUFF ER:

BRUF :

JLONG

DIBSK_LENGTH

+LONG

BRUF

+BLKE

DIRB$K.LENGTH

$GETCHN.S
BLISS-3 2

M:
» BUFFER
CHANNU

Examplé:

RUFF ER

Db
-

CHANNUN
BRRUF

OWN

VECTOR

CWORI]»

VECTOR CDIB$K._.LENGTH. EBYTEI.
VECTOR L[2]
INITIAL (DIEB$K_LENGTHs BERUF)»

$GETCHN

FER) s
NNUM,
s FRIBUF=EUF
(CHAN=,CHA

4-178

VDS

MACROS

SYSTEM

SERVICE

MACROS

$DS_GETTERM
The

Get

the

type

MACRO-32

Terminal
and

service
the

can

user's

used

obtain

terminal.

Format:

$DS_GETTERM~X
BLISS-32

Characteristics

characteristics

termchar

Format:

$SDS_GETTERM

(TERMCHAR=termchar)
;

termchar

Address
See

Return

SS$

Note

quadword

for

format

receive

the

terminal

characteristics.

Status:

NORMAL
Service

successfully

completed.

Notes:

The

terminal

with

fields

characteristics
in

the

following

are

returned

quadword

format:

0
PAGE WIDTH

TYPE

CLASS

PAGE

TERMINAL

LENGTH

CHARACTERISTICS
TK-10538

Figure

4-8

Values

for

are

Format
the

defined

Note:

"type"

the

characteristics,

Terminal
field

S$TTDEF

standalone

characteristics"
mode,
all
supplied.

and

fields

only

the

mode,

TTSM

and

"terminal

macro

fields

only

Characteristics

all

are

SCOPE

"type"

supplied.

and

For
provided.

1is

terminal

"terminal

terminal
In
user

characteristics

4-179

characteristics"

VMS.

are

- SYSTEM

SERVICE MACROS
TN

VDS MACROS

Examples:

MACRO-32 Example:

TERM_.INFO?

+ BLKQ

]
1

$NS_GETTERM.S
BLISS-32

TERM_INFO

Example:

OWN

TERM_INFO

VECTOR

[2]7

$0S_GETTERM (TERM_CHAR=TERM_INFD);

4-1380

VDS

MACROS

SYSTEM

SERVICE

MACROS

$GETTIM
-

The

Get

64-bit

the

$ASCTIM

Time

system

format.

service

furnishes

The time
can

sgrvice.

the

current

converted

system

ASCII

time

by wusing

current

time

MACRO-32 Format:
SGETTIM
BLISS-32

timadr

Format:

SGETTIM

(TIMADR=timadr);

timadr.

Address of a quadword
64-bit fprmat.

Return

SS$

that

receive

the

Status:

NORMAL
Service

successfully

completed.

SS$ ACCVIO (usét mode bnly)The quadword to receive the
caller.

time

Examples:
MACRO-32

Example:

$GETTIM.S

TIME

BLISS-32 Example:"
$GETTIM

(TIMADR=TIME)$

4-181

cannot

wfitten

by the

VDS MACROS - SYSTEM SERVICE MACROS
$DS_GPHARD
provide
will
service
The Get Hardware Parameter Table system
the caller with the address of the p-table for the logical unit
the
The p-table's contents can then be accessed by
specified.
initialization code,

MACRO-32

used

discussed

diagnostic

in Section 3.5.

©program's

Format:

$DS _GPHARD
x
BLISS-32

macro

The

caller.

devnam,

adrloc

Format:

$DS GPHARD x

(UNIT=devnam,

RETADR=adrloc);

devnam

being
1is
p-table
The logical unit number of the device whose
Minimum value is @. Maximum value 1is determined by
requested.
testable
VDS, depending on the number of selected device units
(See

notes.)

- /mam\\

by caller.

adrloc

Address

Return

DS$

longword

receive

p-table

base

address.

Status:

NORMAL

Service

successfully completed.

DS$ ERROR
The argument list does not contain exactly two arguments.
The

specified

logical

unit

number

4-182

1is

too

large.

VDS

MACROS

SYSTEM

SERVICE

MACROS

incremented

Notes:

"devnam"

1ssuance

was

initialized

the

$DS

status simply means that

testable

device

GPHARD macro,

units

the
have

and

then

the

p-tables
been

should
be
reinitialized
to
a.
Initialization Code, for details.

for
See

CINCL

Example:

LOG_UNIT

$NS_GFHARD.S

-~
LOG_LUNIT,

BLISS-32

F_TABLE

Example:

LOG_UNIT =
$OS_GPHARD

,LOG_UNIT + 13
(UNIT=,LOG.UNIT,

RETADR=F_TABRLE);

4-183

after

ERROR

all

referenced.

Examples:
MACRO-32

DSS$S

each

return

selected,
"Devnam"

Section

3.5,

VDS

MACROS

SYSTEM SERVICE

MACROS

$DS_HELP

The Display Help Text service can

be 4used

display

text

Help files are described in Chapter
in a help file.
contained
VDS command
5., This service is functionally identical to the
|

HELP.

MACRO-32 Format:

SDS HELP x keylst
BLISS-32

Format:

- $DS_HELP

(KEYLST=keylst);

keylst

Address of a character string descriptor (see Section 4.3) that
This list is exactly
a list of help file keywords.
to
points
equivalent to the keywords that would be included as parameters

the VAX Diagnostic Supervisor
(see
command
HELP
the
to
for
help file EVXYZ.HLP,
the
reference
To
User's Guide).
diagnostic program EVXYZ, the first keyword in the list must be
'"'EVXYZ'.

Return

Status:

from
returned
The return status may be any status that may be
Refer
SCONNECT, SREAD, or SCLOSE services of RMS.
SOPEN,
the
to descriptions of

these

services.

Examples:

MACRO-32

Example:

KEYSTRING?

+ASCID

/EVXYZ MANUAL

$DNS_HELF_.S

BLISS-32

OFTIONS/

KEYSTRING

Example:

(ZASCID

*e »9

BRIND KEYSTRING = UPLIT

$NS_HELP

(KEYLST=KEYSTRING)

4-184

)}
'EVXYZ MANUAL OFTIONS’

VDS

MACROS

SYSTEM

SERVICE

MACROS

$HIBER
The Hibernate system service allows
a
diagnostic
make itself inactive.
A hibernating program can be
to process
event
to 1ts

until

MACRO-32

asynchronous

handler
state of

the

events.

After

has been executed,
hibernation.
This

program

awakened

with

the

program to
interrupted
diagnostic program's

the program will be returned
state will remain in
effect

the

SWAKE

system

service.

Format:

SHIBER
S
(Note:

BLISS-32

Only

the

form

the

macro

supported.)

Format:

SHIBER;

//\\

Return Status:
SSS

NORMAL
Service

successfully

completed.

Notes:

standalone

mode,

awakened

routine

1is

the

for

interrupt

only

way

event

service

for

handler

hibernating

(for

routine)

process

may

the

VAX/VMS

example,

call

the

program

AST

SWAKE

service.
2.

user

mode,

another

hibernating

process.

Reference

Manual

Refer
for

details.

Examples:

MACRO-32 Example:
$HIRER..S
BLISS-32

Example:

$HIRBER¥

4-185

awakened

System Services

MACROS

SYSTEM

SERVICE

MACROS
PN

VDS

$DS_INITSCB
The
the

Initialize System Control Block system
service
will
1oad
VDS default values into all vectors within the SCB.
It can
used to restore VDS exception and interrupt handling to
all

be
vectors

own

if
handlers

the
diagnostic program has previously defined
using the $DS SETVEC service.

This system service 1s only available

1level

1its

diagnostic

programs.

MACRO-32

Format:

$DS_INITSCB
x
BLISS-32

Format:

$DS_INITSCB

Return

();

Status:

SS$_NORMAL
Service

successfully

completed.

Examples:
MACRO-32

Example:

$NS_INITSCR.S¢
BLISS-32

Example:

//TN

$NS_INITSCE?

4-186

VDS

MACROS

SYSTEM

SERVICE

MACROS

$DS_INLOOP
The SDS_INLOOP program control macro can be used
i1f
a
program
1loop
discussed in Section

MACRO-32

1is
being
3.14.

executed.

Format:

x
$SDS_INLOOP_
BLISS-32

Format:

$DS_INLOOP;

Return

DS$

Status:

NORMAL
A

DS$

program

loop

1is

being

loop

not

executed.

ERROR
A

program

being

executed.

Examples:

MACRO-32

Example:

$OS_INLOOFR.S
BLISS-32

Example:

$DS_INLOOF

4-187

Program

determine
looping

MACROS

SYSTEM

SERVICE

MACROS
TN

VDS

$DS_LOAD
The

$DS_LOAD system

service

can be

used

for

reading

file

into

a
buffer
area.
This
service
may be employed when the full
range of processing options provided
by RMS
1s
not
needed.
(The $SDS LOAD service uses RMS to implement
its functionality.)

MACRO-32

Format:

$DS_LOAD_X file,

default,

1length,

address,

retlen,A

[vbn]
BLISS-32

retrec,

:
Format:

$DS _LOAD

(FILE=file,

ADDRESS=address,

DEFAULT=default,

RETLEN=retlen,

RETEC=retrec,

LENGTH=length,

[VBN=vbnl]l);

file

Address

character

loaded.

quadword

string

The

descriptor

that

filename

(see

represents

format

Section
the

name

4.3)
of

describing

the

file

is:

NODE::DEV: [DIRECTORY]FILENAME.EXT;VER.

any

fields

with

fields

the

filename

specified

are

the

missing,

"default"

they

will

filled

parameter.

default

‘Address

character
filename.

quadword

string

descriptor

that

(see

represents

Section

the

4.3)

default

describing

fields
<

for

length

Size,

bytes,

the

buffer

that

will

receive

the

file.

address

Address of the buffer that will receive the file.
retlen

Address of longword to receive the total length of the file.

4-188

the

VDS

MACROS.
-

SYSTEM

SERVICE

receive

RMS

MACROS

retrec

Address

longword

file.
The first word of the
(maximum record size)
field.
FAB

RFM

the

FAB

the

(record
FSZ

format)

(fixed

SFAB macro

field.

header

for

file

attributes

the

longword will contain the FAB
The third byte will
contain

size)

The

fourth byte

field.

descriptions

Refer

these

will

the

MRS
the

contain

discussion

fields.

‘vbn

Virtual block number.
block

reading

Return

The

begin

This is the number of the first. virtual
The

with

default

the

first

value

block

the

which

will

cause

file.

Status:

$DS

wlth

LOAD

the

services

for

read.

lists

service

SOPEN,
RMS.

can

return

SCONNECT,
Refer
to

return

the

any

of the

SREAD,

statuses

S$SDISCONNECT,

descriptions
of

these

associated

SCLOSE
services

statuses.

Vs-

~.N\

Examples:
MACRO-32

Example:

NAMEDESC ¢

BUFF

DEFIIESC ¢
RUF_SIZE
BUFFER:

sFilename

descristor

+LONG

sStore

+LLONG
+ RLKE

EBUFF
30

sfddress of filemname string
ibtore filename here.

strind

lendth

sllefzult filename string descrirtor

+ASCID
=

filename

/.EXEsO/

512

+BLKE

BUF _SIZE

FILE_LENGTH?
LONG
FILE_ATTR?

+LONG

$0S_LOAD.S

NAMEDESC,DEFDESC, #RBUF_SI1ZEs

BUFFERFILE_LENGTHsFILE_ATTR

4-189

nere,

VDS

BLISS-32

MACROS

SYSTEM

SERVICE MACROS

Example:

LITERAL
RUF_SIZE
OWN

BUFFER

S12¢%

VECTOR CBUF_SIZEs

EBRYTE]>

| Store filename here.
¢t VECTOR C30y RBRYTE1:»
BUFF
! Filename descrirtor
NAMEDESC: VECTOR [21
I Store filename strind length here.
INITIAL (O
FILE_LENGTH
FILE.ATTR

:
+

EUFF)y

VECTOR,
VECTOR?Y

Address of filename string

BEIND

DEFDESC

(ZASCID ‘.EXE307)3#! Default filename string descrirtor

$0S_LOAD (FILE=NAMEDESC, DEFAULT=DEFDESCsy LENGTH=BUF.SIZE»
ADDRESS=BUFFERy RETLEN=FILE_LENGTHs RETREC=FILE_ATTR)?

4-190

vDS

MACROS

SYSTEM

SERVICE

MACROS

$DS_MMON
$DS_MMOFF
The

Turn

Memory

Management

enabling

Off

and

mode.

Only

level

off.

off,

DS$

MMOFF x

these
1is

(DS$

the

memory

programs

and

Turn

are

management

Memory

provided

for

hardware

may

program

services

MMON)
services

1in

turn memory management
turns memory management on

discussed

do
1in

on
or

so.
Section

3.13,

Memory

Allocation.

Format:

DS$S MMON

();

DS$ MMOFF

SS$

1level

system

Format:

MMON x

Return

use

and

DSS

BLISS-32

management

Management

MACRO-32

diagnostic

MUST

Memory

MMOFF)

disabling

standalone

Management
(DS$

();

Status:

WASCLR
Service

successfully

previously

completed.

Memory

disabled.

management
|

was

SSS WASSET

Service

successfully

previously
DSS

WARNING

The

$DS

disabled
issued

completed.

Memory

enabled.

(used

with

_MMOFF macro

because

(see

the

VAX

MMOFF

was

management

was

only)

issued,

but

memory management

was

not

a SET MM ON user command had previously been
Diagnostic

4-191

Supervisor

User's

Guide).

VDS MACROS - SYSTEM SERVICE MACROS
Notes:

The

wuser

command

$DS_MMOFF
macro.
management if the

SET

has

precedence over the

Thus
a
program cannot shut off memory
user has turned it on.

Examples:

MACRO-32

Example:

$0S_MMON_S
BLISS-32

sTurn on memory manasemeht.

Example:

(This example illustrates
the case of

execute if memory management is enabled.
turn memory management off, it aborts.)

Turn off memorg manadement.

c=11

the

that

program
|

cannot

cannot
o

it ony
If the user has turned

routine to rerort the sroblems

$ DS _MMOFF

program

then sbort the srogram,

()3

DS$_WARNING

THEN

REGIN

REFORT _MM_ON ()3
$NS._ARAGRT ()9

ENIIs

4-192

VDS

MACROS

SYSTEM

SERVICE

MACROS

$OPEN
The

Open

Existing

avalilable
processing

for
the

File

parameters

within

what

attributes

access

MACRO-32

the

FAB

RMS

Opening a
within the
to

file is the
file.
This

determine

assign
to

used

the

which

make

file

first step in
service
uses

file

the

$FAB

open

and

file.

Format:

SOPEN
BLISS-32

service

processing.
information

fab,

[err],

[suc];

Format:

SOPEN

(FAB=fab,

Address

(user

mode

Address

[ERR=err],

[SUC=suc]);

fab

err

the

FAB.

The

FAB

execute

declared

routine

mode

only)

Address

routine

execute

service.

return

from

open

successful

return

from

open

Status:

Note:

the

error

(user

Return

macro.

only)

service.
suc

using

For

VAX-11

further

RMS

details

Reference

return

status

values,

refer

Manual.

RMSS$ NORMAL
Service

successfully

completed.

RMSS$ ACC
Error

RMS$

accessing

file.

DME

Dynamic

memory

exhausted.

avallable.

4-193

Insufficient

dynamic

memory

VDS

MACROS

SYSTEM

SERVICE MACROS

RMSS DEV

Bad

device

specification.

RMS$ FAB

Error

in FAB.

RMS$ FNF
File

not

found.

RMSS FNM
Bad

file name.

RMSS$ ORG
Invalid

file

organization.

organization must be

standalone

mode,

file

sequential.

RMSS RER
File

read

error.

Notes:

Table 4-7 lists the FAB fields used by the $OPEN service IN

STANDALONE

MODE.

For

VAX-11] RMS Reference Manual.

user

mode,

refer

the

4-194

Table
Field

4-7

Mnemonic

VDS

MACROS

FAB

Fields_Used

Field

SYSTEM

SERVICE

SOPEN

MACROS

(Standalone

Mode)

Name

Input:
DNA

Default file specification string adaress.

DNS

Default file specification string size.

FAC

File

access.

FNA

File

specification

string

address.

FNS

File

specification

string

size.

FOP

File

processing

FSZ

Fixed

control

IFI

Internal

RAT

Record

attributes

RFM

Record

format;

XAB

Extended

ALQ

Allocation

file

options.

area

size;

unit

indentifier

(unit

unit

attribute

record

(must

record

record
block

devices

0).

devices

only.

only),

only.

address.

Output:

quantity;

block

allocated

BLS

Block

size.

DEV

Device

FSZ

Fixed
with

contains

the

highest

numbered

file.

characteristics.

control
fixed

area

length"

size;

IFI

Internal

MRS

Max imum fecord size.

ORG

File

RAT

Record

attributes.

RFM

Record

format.

STS

Completion

file

applies

control

only

"variable

RY).

records

identifier.

organization‘

status

4-195

code

(also

returned

MACROS

SYSTEM

Examples:

MACRO-32

$OFEN
BLISS-32

$OFEN

SERVICE

MACROS

VDS

Example:

FAB_RBLOCK
Example:

(FAE=FAE_EBLOCK)

4-196

VDS«MACROS

SYSTEM

The Parse Command String

'system

SERVICE

MACROS

$DS_PARSE

diagnostic

program

for

which

(see

service

will

parse

command

tree,

looking

for

the

tree.

nodes

service

will

presented

MACRO-32

Section

command

dispatch

the

can

used

unique command language has
3.12.2.2,
Prompting
the
User).

defined

and

service

notes

string

matches

Every

searching

between

the

time

match

"action

routin."

been
This

predefined

command

string

found,

Details

the

are

below.

Format:

$DS_PARSE_x bufadr, tree, action
BLISS-32

Format:

SDS_PARBE

(BUFFER=bufadr,

TREE=tree,

ACTION=action);

bufadr
Address

the

of
a

command

quadword

descriptor

string.

(see

Section

4. 3)

pointing

should

tree

Address

the

defined

using

tree

the

valid

$DS

CLI

commands.

This

tree

macro.

action

Address of action

routine.

See

notes

for

routine

format.

Return Status:
SSS_NORMAL

Service successfully completed.

DS$ ERROR

While_traversing the command tree; ah error
CLISK

ERROR,

other

words,

see

$DS

an illegal

CLI

description)

command

4-197

string

was

node

was

(defined

encountered.

specified.

by
In

VDS

MACROS

SYSTEM

SERVICE MACROS

The command string to be parsed should be fetched from

The $DS PARSE system service will

user by issuing the $DS_ASKSTR macro.

CLISK EXIT

until

(see DSS$ CLI description),
the caller.

the
tree

parse

the
traverse

a CLISK _ERROR code 1is encountered

return to

at which point it will

As the tree is traversed, the action routine will be called
match between the contents of the
a
1is
there
time
each
match
If a
the input stream.
and
current node of the tree
is

the

found,

action routine

is called

and

then

the next

branch
a
Otherwise,
node in the current path is checked.
of the
parameter
"miss"
the
by
specified
node
the
to
$DS CLI

Action

macro

occurs.

Routines:

Parameters will

be passed

the action routine as follows:

RP - Will contain action code specified
parse

for current node

tree.

R7 — Will

contain current value of pointer

traversing

used by VDS when

tree.

R8 - Will point to next unparsed

character

the

input
|

string.

R9 - Will contain number of unparsed
in

input

characters

Generally,

remaining

string.

R1¢J and:-R11 - Will contain quadword value of
string

read

from

1last

numeric

input buffer.

the programmer will

specify a

unique action code

for

Sometimes a "null"
using the $DS CLI macro.
tree node,
each
for the action
necessary
action code is used, because it is not
completely
not
do
which
nodes
for
anything
do
to
routine
words,
other
In
qualifier.
or
identify a command, parameter,
the
when
only
action
an
perform
to
wusually necessary
is
it
|
e.
recognizabl
something
parser is sure it has found

4-198

When

the

RO.

VDS

MACROS

action

routine

The

action

instruction
to

dispatch

subroutines

what

command

examine
routine
An

When

the
to

action

1in

chapter)
ACTION

use

expression,

set

can

the

passed

MACR0O-32

CASE

some

other

means,

code.

These

bitmap

indicating
qualifier has been

command
has

called.

been

This

which

corresponding

description

would

parsed,

dispatcher

command

the

$DS

CLI

follows:

RTN::

CASEL

RO,

#0,

.WORD

ACT NO ACTION-18S

« WORD

ACT

ADD-10S$

.WORD

ACT

BAKE-10$S

.WORD
. WORD

ACT BEAT-18$
ACT MILK-10$

. WORD
.WORD
.WORD

ACTSUGAR-10$S
ACTILLCMD-10$S
ACTBADARG-10$

.WORD

ACTSALT-10$

NO ACTION:

RSB
ACT ADD:

BISB

#1@ADD,

CMD BLOCK

RSB

ACT BAKE:

BISB

#1@BAKE,

CMD

#1@BEAT,

CMD BLOCK

#1@MILK,

PARAM BLOCK

BLOCK

RSB

ACT BEAT:

BISB
RSB

ACT

each

string

code

for

determine

routine

10S:

ACT

action

thus

subroutine

command

routine

bitmap

the

bits
parameter, or

entire

MACROS

can
processing

call.

defined

this

CASE

just

command
the

can

wunique

often

dispatching

example

tree

SERVICE

called,

routine

BLISS-32

will

command,

parsed.

a
to

SYSTEM

MILK:
BISB

RSB

ACT SALT:
BISB

#1@SALT,

RSB

PARAM

BLOCK
|

4-199

sample

macro

parse

(earlier

VDS

MACROS

ACT SUGAR:
BISB

SYSTEM

SERVICE MACROS

#1@SUGAR,

PARAM BLOCK

RSB

ACT

ILLCMD:
BISB

#1@QILLCMD,

ERROR_BLOCK

#1@BADARG,

ERROR BLOCK

RSB

ACT BADARG:
BISB
RSB

Examples:

' MACRO-32 Example:
This

example
and

string,

fetches a command
then either calls

attempts

string,

a command

parse

dispatcher

handler.
$0S_ASKSTR.S

for

user

Fromet

inrut

string,.

BNEQ

MSGADR=FROMFT_MSG
BUF ADR=STRING.RUF
RO» S5S5$_NORMAL
ASK_ERRHNDLR

If error occurred
then g0 to error handler

MOVZEL
MOVAL

STRING_.BUFy CMD_BUFFER
STRING.BUF+1s CMD_RBUFFER+4

Fut string length and string
address in quaduword descrirtor

CMFL

Farse

$0S_FARSE.S BUFADR=CMD_RUFFER,
TREE=TREE_ROQT»
ACTION=ACTION_RTN

CMFL

the

unsuccessful

ROy SS5$_NORHAL
FARSE _ERRHNDLR

thern g0

CHMI_DISFATCHER

Good rarse

4-200

inrut

error

string.

rarse

handler

Frocess command.

the

error

VDS

MACROS

SYSTEM

SERVICE

MACROS

$DS_PRINTB

$DS_PRINTF
$DS_PRINTS

$DS_PRINTX
The

Format

means

character
macros

which

call

macros.
Insert

Message

system

services

provide

messages

can

formatted

into

and

displayed

these

services

are

These

macros

variable

string

ASCII

complex

strings

that

"print"
e

and

can

character

the

Convert binary values
decimal,

substitute

used

string

the

into

Once

results

and using

the

those
parameters.

system

automatically

The

messages
messages

macro

(see

directives

into

output

the

("print

Section

<creates

display

generated

string by referring
to
contained in a "control

operate

output

error

second

3.9,
this

the

string,

message")

message

level

Reporting

Errors).

macro

will

The

$DS

message")

messages

(see

messages

generated

Section

control

flag

User's

Guide).

IE3

$DS PRINTS

exclusively

("print

display

VAX

macro
display

Diagnostic

this

set

3.7, Summary Routine).
macro will be inhibited
the

third

3.9,

with

extended

the

error

message

Reporting
macro

(see

("print

4-201

VAX

summary

used
error

Display
the

of
VDS

Supervisor

message")

is
(see

generated
IES

the

either

Diagnostic

flag
Guide).

used
error

1level

messages

is
of

(see

inhibited

messages
control

User's

set

Errors).
be

summary

Display of
if the VDS

Supervisor

will

the

program

Display

inhibited

PRINTX macro

contents

terminal.

basic

the

with

the

user

of
and

string

the
VDS control
flags
IE2
or
IE3
Diagnostic Supervisor User's Guide).

The

the

output

equivalents

VAX

exclusively

The
as

representations

octal

service

displayed

$DS_PRINTB

exclusively

the ASCII

hexadecimal,

system services construct an output
formatted ASCII output (FAO) directives

value

terminal.

referred

data

The

string"

user

commonly

ASCII

their

used
Section

with

this

set

(see

VDS

The $DS PRINTF

macro

("print

display informational
errors.
because

which

MACROS

forced

message")

1is

used

messages that are not related to device

messages
"forced"
as
These messages are referred to
flags
the
of
state
the
of
s
regardles
printed
they are

inhibit

Supervisor

MACRO-32

SERVICE

SYSTEM

MACROS

message

User's Guide).

VAX Diagnostic

the

(see

displays

Format:

SDS PRINTB_X format, [pfl], [pl]r [p2]r [p3]r [p4]r [pS]r
[p7T, [p81, [p9], [pal, [pbl, [pcl, [pdl, [pel, [pf]l

[p6],

[pS]r

[p61,

$DS PRINTF x format, [p@], [pll, [p2], [p31, [p4], [p5],

(p6l,

$DS PRINTS x format, [p@]1, [pll, [(p2], [pP3], [p4]; [p51],

[p6],

$DS_PRINTX_X format,

(p7T,
[p7T,

(p71,

BLISS-32

[p81,

[p8),

[p91,

(P91,

[p9],

[pfl]l

[pal,

[pl]r

[pbl,

[Pz]r

[pcl,

[p3]r

[pdl,
[pdl,

[pdl,

[p4]r

[pel,

[pf]

[pfl]

Format:

[p5],
$DS PRINTB (format, [p@], [pll, [p2], [p3], [pP4],
[p7], [p81, [p9]1, [pal, [pbl, [pcl, [pdl, [pel, [pfl);

[p6],

[P5],

[p6],

$DS PRINTF (format, [p@], [pll, [p21, [p31, [p4l, [pP3],
[p7]; [p81, [p9], [pal, [pbl, [pcl, [pdl, [pel, [pPfl):

[p6],

SDS PRINTS (format, [p®l, [pll, [p2], [p3], [p4l,

[p61,

$DS_PRINTX (format, [p@l1,

[(p7]1,

[p8]1,

[P9],

[pP9],

[pal,

[pbl,

[pa],».[pb],

[p2], [p3]1,

[pcl,

[pdl,

[p4]l,

lpel,

[pel,

[pfl);

[pSI1,

[pfl):

[p7), [p81,

[pll,

4-202

VDS

MACROS

SYSTEM

SERVICE

MACROS

format
Address

<counted

ASCII

string.

This

the

string,"
which consists of the fixed text of the
plus
FAO
directives
for
formatting
wvariable
directives
are
1listed
below.
Variable
data
parameters
jo3%

through

p@d

directive
parameters,
contained
on
the corresponding FAO directive,

Parameters

Return

pf.

value that is to be converted, the
1is
to
be
inserted,
a
1length,

control

output string
data.
FAO
1s
passed 1in

Depending

be a
that

through

"“control

are

listed

the

order

in
a

longwords.
may

parameter

address
of
a
or
an argument

they

are

referenced

string
count.
by

the

string.

Status:

SS$ NORMAL
Service

successfully

completed.

SS$ BUFFEROVF
Service

successfully

completed,

string

was

than

(see

greater

the

but

the

maximum

size

allowed

and

the

was

output

truncated

notes).

SS$ BADPARAM

invalid

FAO directive

was

specified

the

control

string.

Notes:

VDS

stores

being

the

output

created.

characters.

string

This
the

output

characters,
the
string
message 1s displayed.
2.

necessary

16 parameters,
@

Use

several

format

PRINT macros

internal

can

string

1is

possible

4-203

buffer

truncated

message

buffer

contain

512

greater

than

512

and

truncated

the

containing

succession,

than

VDS

MACROS

SYSTEM

SERVICE

Use
The

the S$SFAO or SFAOL macros
to
format
the
message.
message
should
then
be printed using the proper
print macro (for example, PRINTX for a 1level 3
error
message) .

In MACRO-32,

the

S$FAO
S macro form uses

PUSHL instruction

for all parameters (pl through pn) specified with the macro
be
to
are assumed
arguments
In other words, all
call.
1is
address
an
if
Therefore,
addresses.
not
values,
1load
or
desired, precede the argument with a # character,
the

FAO

MACROS

address

into

Directives:

FAO directive

has

the

format

!DD

where

indicates
as

interpreted

that the

following

FAO directive.

(s) are
character
o

to be
-

directive
A
DD is a one- or two-character FAO directive.
that a parameter be included in the parameter
require
may
Dbe
must
directives
All
Note:
list of the macro call.
specified
Optionally,
@

repeat

uppercase

directive

may

letters.
include:

count

A repeat count is coded as !n(DD), where
n
is
a
decimal
number indicating that the directive should be repeated for

the

output

An output
"length"
resulting

parameters.

field

length

field length is
specified
as '!tlengthDD,
the
that
field 1length
the
indicates
from the specified directive should have.

where
output

A directive may contain both a repeat count and a field length,
as

!n(lengthDD).

4-204

VDS

Repeat

counts

MACROS

and

output

variables,
by using a #
If a # 1is specified for
included

1in

the

macro

SYSTEM

SERVICE

MACROS

field

1lengths

may

in
a
call

must

specified for an output fleld
contain the 1ength value.

contain

length

the

count

only one length

also

each output
length.

string

control

FAO

character
the

(ASCII

output

Each

may

directives.

character

(by

that

argument

variable,

variable

fetched

generated

any

The

only

length

"X21).

the
the

and

from
the

directive
control

string

can

may

restriction

must

and

value),

the

repeat

then

argument

count

any

the use

literal

must

used.

that

not

string

contain

directive
1is copied into the output
of the message
being
formatted
1is

string,

count.

will

code

string,

will

string

specified

parameter

list, and
have that

specified

numeric value.
next
argument

If an output field length 1s specified as

repeat

place of an absolute
repeat
count,
the

directly

the

required

part

string.
Thus if
a nonvolatile

placed

number

into

FAO

a portion
character

the

control

string.

invalid

FAO

string,

creation

error

status

tests

are

parameters

directive
of

have

control
'string,
fetch parameters

the
past

encountered
string

the

included

1if

the

1in

the

specified

than

system

service

the

end

1in

ceases

the
that

control
point

and

number

caller.

determine

been

1is

output

returned

made
have

the

correct
macro

are

call.

referenced

routine

parameter

will

fewer

continue

the
to

1list.

Table 4-8 lists the FAO directives.
4-9

summarizes

how

the

determined,

length

field

/"""\\

Table

string

4-205

each

length

has

field

been

the

output

spec1f1ed.

MACROS

VDS

Table 4-8
Directive

Character
1AC

SYSTEM

SERVICE

FAO Directives
Parameter
(s)

Function

String

MACROS

Substitution:

Inserts
string.

counted

ASCII

Inserts

ASCII

string.

Address of the string;
the first byte must
contain the length
1)
2)

Length of string
Address of string

1) Length of stting

Inserts an ASCII string;
Replaces all nonprintable
ASCII codes with periods (.).

Inserts

Address

ASCII

string.

Address

string

quadword

character string
descriptor pointing
to the string
Numeric

Conversion

(zero-filled):

10B

Converts a byte to octal.

Converts a word to octal.
Converts a longword to octal.

ASCII representation

1 XB
1 XW
1 XL

Converts a byte to hexadecimal.
Converts a word to hexadecimal.
Converts a longword to hex.

For byte or word conversion,
'FAO uses only the low-order
byte or word of the longword

1ZB
1ZW
1ZL

Converts
an unsigned decimal
Converts an unsigned decimal
Converts an unsigned decimal

! OW
10L

Value to be converted
to

parameter.

byte.
word.

longword.

Numeric

Conversion

(blank-filled):

1UB

an unsigned decimal byte.
Converts

1UL

Converts an unsigned decimal

!SB
I SW
!SL

Converts a signed decimal byte.
Converts a signed decimal word.
Converts a signed decimal

1UW

Converts an unsigned decimal word.

Value to be converted to

ASCII representation
-

longword.

4-206

For byte or word
conversion, FAO uses only
the low-order byte or word
of

the

longword

parameter

VDS

MACROS

Table

Directive
Output

4-8

SYSTEM

FAO

SERVICE

Directives

Parameter (s)

Formatting:

Inserts

new

Inserts

tab.

Inserts

form

Inserts

the

recently

18T

MACROS

(Cont)

Function

String

13%S

not

line

(cr/1f).

None

feed.

exclamation

letter

converted

point.

if most

numeric

value

Inserts

the

system

time.

Address
value

ASCII.

the

quadword
converted

1If

current

time
to

specified,

system

time

used.

1%D

Inserts

the

! n<

Defines

output

characters.

system

date

field

All

data

and

width

and

time.
of

None

direc-

tives within delimiters are leftjustified and blank-filled within
- the

In*c

field.

Repeats

in
Parameter

the

the specified character
output string n times.

Interpretation:

! -

Reuses

last

parameter

list.
1+

Note:

Skips

specified
must

variable

with

precede

parameter

repeat

count

the

and/or

directive,

parameters

other

parameters

required

None

list.

variable

indicating

4-207

the

output

the

field

count

directive.

length

and/or

length

MACROS

VDS

Table 4-9

- SYSTEM

SERVICE MACROS

FAO Field Lengths and Fill Characters

How FAO Determines Output Field

Lengths and Fill Characters:

Conversion or

Action When Explicit

2 (zero-filled)
4 (zero-filled)
8 (zero-filled)

ASCII result is rightJjustified and blank-

ASCII result is
truncated on the

(zero-filled)

Hex or octal output is

Substitution
Type
Hexadecmal

byte
word

longword

Default Length
of Output Field

Output Field Length is
Longer Then Default

filled to the specified

Output Field Length is
Shorter Than Default

left.

length.

Octal

byte

longword

word

(zero-filled)

zero-filled

the

default output field
length, then blankfilled to specified
length.

Signed

As many

char-

acters as
necessary

Unsigned

As many char-

zero-filled

acters

decimal

necessary

ASCII

string

substitution

result is rightand blank-

ASCII

justified
filled to

unsigned
decimal

the

specified

length.

Signed and unsigned
decimal output fields
are completely filled
with asterisks (*).

ASCII result is rightjustified and zero-

filled

the

specified

leng th.

Length

character
string

input

ASCII string is left~justified
filled to

and
the

length.

4-208

blankspecified

ASCII

string
on

truncated
right.v

1is
the

VDS

MACROS

SYSTEM

SERVICE

MACROS

MACRO-32 Example:
FMT_ERRCOUNT
+ASCIC

TI/V/BYTES

TRANSFERRED:!SL!_ERAD:ISLI/Z1/7

$OS_FRINTB..S

BLISS-32

FMT_ERRCOUNTs

4(AF)s

ERR._CNT

Example:

BIND
FMT.ERRCOUNT

=
(ZASCIC

‘!/V/BYTES

TRANSFERRED!!SLI_BADIISLI/1/7)5

UFLIT

(FMT_ERRCOUNT,

.TOTALs

//'-—\

$DS_FRINTE

4-209

.ERR_CNT);

VDS

MACROS

SYSTEM

SERVICE MACROS

$DS_PRINTSIG
The Print Signal Array system service will format and print the
are passed to
arrays
Signal
array.
signal
contents of a
to
Refer
occur.
conditions
exception
when
handlers
condition
Section

3.14.5,

Condition Handling.

MACRO-32 Format:
$DS_PRINTSIG
G argptr

Only the G

(Note:
BLISS-32

form

the macro

1is

supported.)

Format:

$DS_PRINTSIG

(ARGPTR=argptr);

argptr

Address

Return

the

signal array.

Status:

SS$ NORMAL
Service
SS$

successfully

completed.

RESIGNAL

The VDS does not support condition handling

for

the

detected

The
displayed.
not be
array will
signal
The
condition.
status:
return
this
in
result
always
following conditions will
SS$ FAIL,

SS$ PAGRDERR,

SS$ DEBUG,

and SSS$_ARTRES.

Examples:

<condition
a
These examples illustrate use of the macro within
address
array
signal
the
receive
handlers
Condition
handler.
stack.
argument
as the first argument on the
MACRO-32

Example:

$NS_FRINTSIG.G
BLISS-32

yDisrlay sidnzsl arrav

@4 (AaF)

Example:

NS _FRINTSIG

(ARGFTR =

. (.AF + 4))3

4-2190

IDisrlay signal array

VDS

MACROS

SYSTEM

SERVICE

Address

system

service

MACROS

$DS_PROBE
The

Probe

determine

address.

the

Device

1if

The

logical

device

service

unit

number

resides

passed

the

that address, and it will
whether or not the address

the

address

device

return
exists.

that

status

This service is only available to level
MACRO-32

the

may

used

physical

checked

expected

and

at
code
indicating
S

3 programs.

Format:

SDS_PROBE
x

address,

length,

unit

BLISS-32 Format:
SDS PROBE

(ADDRESS=address, LENGTH=1engtH, UNIT=Unit);

address
The

VDS

a particular

o
physical

address

length

whose

existence

‘

determined.

‘

Size of the location specified by "address." Valid values are 1

for

byte,

for

word,

and

for

longword.

unit
Logical

unit

specified

Return

number

the

address.

device
~

expected
*

the

Status:

$SS_NORMAL
Service

$DS_ERROR
An
The

successfully

invalid

value

specified

address

does

was

address

not

completed.

specified
does

not

respond.

4-211

for

"length".

exist,

the

device

existing

VDS MACROS- SYSTEM SERVICE MACROS
Examples:

MACRO-32

Example:

This example probes devices on a MASSBUS controller.
*

$DS_GFHARD.S

LOG_UNITs

FTARLE

FTABLE, R3

MOUVL

Get r-table azddress.

base

address.

i See if the drive unit exists.

$NS_FROEBE.S -

y
y
]

ADDRESS = (R10)CR111]
= #4
LENGTH
= LOG.UNIT
UNIT

$0NS_RERROR

$ Init. controller redister rointer

Ri1l

CLRL

Get r-table.

} Get MBA controller redister

R~HF$A_DEVICE(R3)R10

MOVL

ERR10

(Continue)
¢

(Rerort error - device not there.)

ERR103
BLISS-32

Example:

$0S_.GFHARD (UNIT=.LOG_.UNITy RETADR=FTABLE)S?
CONTROLLER_RASE = .PTARLE CHFP$A_DEVICE]>S
HEVICE_ADDR

WHILE

,CONTROLLER_.BASE>

.DEVICE_ADDR LSS LAST_DEVICE DO

BEGIN

IF NOT $DS_FROEBE

(ADDRESS=.DEVICE_ALIR
LENGTH=4,

UNIT=,LOG_UNIT)

THEN REGIN ...Rerort error - drive not there...
ELSE DEVICE_ADDR = .DEVICE_ADDR + NEXT_DEVICE
v

ENIDS

4-212

END

VDS

MACROS

SYSTEM

SERVICE

MACROS

$Qlo
$QIOW
The

Queue

I/O

Request

system

service

(3$QI0)

initiates

I/0

has

operation in user mode by queueing a request to an I/0 channel.
The channel must have been
previously
assigned
with
$ASSIGN
service.
Once the I/0 request has been queued, control returns
to
the
<caller.
Notification
that
the
1I/0
operation
has
completed can be accomplished by one of three methods:
l.

AST

routine

can

caused

execute

completed.
2.

The

diagnostic

set

when

The

diagnostic

block

TN .

These

methods

Section

The

Queue

I/0

program
in

I/0

Request

$QIO

and

can

when

$SQIOW

and

(SQIOW)
combines
the
for Single Event Flag)

The

can

specify

that

specify

that

event

flag

completed.

notification

3.12.1.1,

I/O0

program

has

filled

for

when

I/O
of

User

Wait

has
I/O

I/0

status

completion

are

discussed

Mode.

for

Event

operations of the
system services.

services

completed.

may

not

Flag

$QI0

system

and

service

SWAITFR

used

(Wait

level

programs.

MACRO-32

Format:

$QIO0 x efn,
[p3], [p4],

chan,
[p51,

SQIOW
x efn, chan,
[(p2],

[p3],

[p4]l,

func,
[p6]

[iosb],

func,
[p5],

[astadr],

[iosb],

[p6]

[astprm],

[astadr],

[pl],

[p2],

[astprm],.

[pl],

BLISS-32 Format:
SQIO

(EFN=efn,

CHAN=chan,

[ASTADR=astadr],

[ASTPRM=astprm],

[P4=p4],

[P6=p6]);

- SQIOW

[P5=p5],
(EFN=efn,

CHAN=chan,

[ASTADR=astadr],

[ASTPRM=astprm],

[P4=pd],

[P6=p6]);

[P5=p5],

4-213

FUNC=func,
[Pl=pl],

[IOSB=iosb],
[P2=p2],

[P3=p3],

FUNC=func,
[IOSB=iosb],
[Pl=pl],
[P2=p2],
[P3=p3],

S
- SYSTEM
VDS MACRO

SERVICE MACROS

efn

Number of

completion.

the

default is @.

event

Caution:

flag

that

set

request

If an event flag is not specified, the

Since event flag @ is used by the VDS, a nonzero

value for this parameter must ALWAYS be specified, for both the
$Q0I0 and the $QIOW macros, whether or not the diagnostic
program actually tests this flag as a means of determlnlng that
the

I/0 operation has completed.

chan

which
Number of the I/0 channel assigned to the device to
Obtained by using the $ASSIGN macro.
request is directed.

the

func

Function code and modifier bits that specify the

operation

An introduction to function codes is provided in
be performeéd.
I/0 in User Mode. Complete documentation of
3.12.1.1,
Section
function codes is located in the VAX/VMS I/0 User's Guide.
iosb

Address of a quadword I/O status block that is to receive final
1in
"Synchronlzlng ~I/0 Completion"
See
completion status.
Section

3.12.1.1,

I/0

User

Mode.

astadr

Address of the entry mask of an AST routine to be executed when
The AST routine will execute at the access
1I/0 completes.
the

mode from which the $QI0 macro was issued.
I/0 Completion"

in Section 3.12.1.1,

See

"Synchronizing

I/O in User Mode.

astprm

AST parameter to be passed to the

4-214

AST

routine.

See

Section

vDS

MACROS

SYSTEM

SERVICE

MACROS

Optional

the

device-

VAX/VMS

I/0

and

function-specific

User's

The first patameter may be

specified

depending

address

parameters.

whether

respectively.
If the keyword is not
the argument is considered to be

and

through

Return

are

Refer

Guide.

always

interpreted

"pl"

value

used, "pl" is
ADDRESS.

"plv,"

1is required,
the

default

VALUES.

Status:

SSS_NORMAL
Service

successfully

completed.

The

1I/0

request

packet

was

queued.

SSS$ ABORT
A

network

logical

1ink

was

broken.

SS$ ACCVIO

The I/0 status block cannot be written by the caller.
This status
code
may
also
be
returned
if
device-dependent function codes are incorrectly

parameters

for

specified.

SS$ DEVOFFLINE
The

specified

device

offline.

SS$ EXQUOTA
The

process

quota,

resource
system

has

exceeded

Dbuffered

walt

mode

service;

with
or

its

I/0

buffered

byte

the
the

Set

I/0

<count

process

has

'SS$_ILLEFC
illegal

event

flag

number

was

4-215

specified.

direct

I1/0

and has disabled
Mode
(SSETRWM)

exceeded

quo ta.

quota,

quota
Resource
Wait

its

AST

1limit

VDS MACROS - SYSTEM SERVICE MACROS
SS$

INSFMEM

Insufficient

service,
the

Set

system

and

the

dynamic

memory

available

process has disabled

Resource Wait

Mode

(SSETRWM)

complete

the

resource wait mode with

system

service.

SS$ IVCHAN

invalid

channel

number
of
available.

number

was

number

specified,

larger

that

than
v

the

1is,

number

channel

of channels

SS$ NOPRIV

The

specified

privileged

channel

access

does

not

exist

was

mode.

assigned

SS$ UNASEFC

The process is not associated
specified event flag.

with

the

cluster

containing

the

Notes:.

See

~
2.
~

the

VAX/VMS System

Services Reference Manual

discussions
requirements,

restrictions,
privilege
of
and other notes
relating
to
the

Two potential

problems exist

- $QIOW macros.

when

the

$QIOW

for

resource
SQIO
and

service

Iis

used:

the

I/0 device

never
be
diagnostic

If
the I/0
restriction

three

better

SWAITFR

violated

the

never

event

for

4-216

or
overloaded,
checked at least

(see

Section

diagnostic

programs

Additionally,

the

to limit the amount of time
for the event flag, in case

set.

flag

return

may
the

the
every

3.14.56,
|

services.

service should be used
the
program will wait
becomes

will

Control-Cs).

therefore

and

service

device
1is
slow
that
control-Cs he

seconds may

Handling

$QI0O

is malfunctioning,

set
and
program.

use

the

SSETIMR

in which
it never

VDS

MACROS

SYSTEM

SERVICE

MACROS

Examples:
MACRO-32

Example:

$QRI0..S

EFN=%1, CHAN=TTCHANL,

tEvent flasg
sChannel

FUNC=#I0%_WRITEERLK

tVirtuasl

Fl=RUFADD,-

F2=3BUFSIZE
BLISS-32

write

yBuffer

address

sBuffer

size

Example:

NOT

(STATUS=¢#QIOW (EFN=32, CHAN=.LOG_UNIT,
FUNC=I0$_SETMODE OR IO$M_ATTAST.

I0SE

='SETNODE~IOSBv

F1=ATNAST)

THEN

BEGIN

(Rerort

error.)

END;

4-217

function

VDS

MACROS

SYSTEM

SERVICE MACROS

$READ
The Read File service of RMS is used to read a specified number

The file
of bytes, starting at a block boundary, from a file.
and
SOPEN
the
must have been opened and connected, using
respectively.

SCONNECT services,

MACRO-32

Format:

SREAD
BLISS-32

rab,

[err],

[suc]

Format:

SREAD (RAB=rab, [ERR=err], [SUC=ch]);
r ab

Address of the RAB to be associated with the FAB describing the
(The address of the
to which connection is to be made.
file
FAB

err

(user

the

mode

RAB.)

only)

Address of a routine to be executed on error

from

the

return

from

return

service.

suc

(user

mode

only)

Address of a routine to be executed on successful
the service.

Return

Status:

Note:
the

For further details on return status

VAX-11 RMS Reference Manual.

RMS$ NORMAL

Service

successfully completed.

RMSS$ EOF

Attempt was made

read

beyond

4-218

end of

file.

values,

refer

vDS

MACROS

SYSTEM

SERVICE

MACROS

RMSS_FAB

The FAB block 1is invalid;

RMS$ IFI

| The FAB's IFI field is invalid.
RMS$_Isi
The

RAB's

ISI

field

invalid.

RMS$_ RAB

The RAB block is invalid.
RMS$_ RER
Read
STV

error.

(The

field

Table

4-10

the

device

driver's

return

status

RAB.)

will

the

Notes:

lists

STANDALONE

Reference

the

MODE.

RAB

fields

For

user

Manual.

4-219

used

mode,

the

refer

S$READ
the

service

VAX-11

RMS

VDS

Table 4-19

MACROS

SYSTEM

SERVICE MACROS

RAB Fields Used by SREAD

(Standalone Mode)

Field Name

Field Mnemonic
Input:

BKT

Must contain the virtual
Bucket number.
block number of the first block to be read.

ISI

Internal stream identifier.

UBF

User

will

block

usz

User

This

record area address.
be

stored.

record area

transfer,

1is where the

size.

Indicates length of the

in bytes.

Output:
RBF

Record

RFA

Record's file address.

RSZ

address.

the

number

Record

size.

1Indicates

transferred.

Contains the virtual block
transferred.

first block

STS

Completion status code.

STV

Status value.

(See

the actual

number

of bytes

| <

(Also contained in R#.)

Return

Status,

above.)

Examples:

MACROQ32 Example:
$READ RAE=RAE_RLOCK

$READ

Example:

¢
(RAE=RAR_RLOCK)

/mk\‘

BLISS-32

4-220

VDS

MACROS

SYSTEM

SERVICE

MACROS

$READEF
The SREADEF macro is used to obtain the current status
flags
within an event flag cluster.
Event flags are
in

Section

MACRO-32

all

Format:

SREADEF_X
BLISS-32

3.14.
2.

discussed

efn,

state

Format:

SREADEF

(EFN=efn,

STATE=state) ;

efn
Number

any

number

event

flag

through

within

the

cluster

specifies
specifies cluster

read.

cluster

and

flag

state

Address

within

the

Return

SS$

longword

receive

status

The

specified

The

specified

all

event

flags

Status:

WASCLR
Service
clear.

SS$ WASSET
Service

(user

mode

only)

successfully completed.
(user

mode

SS$_NORMAL
Service

SS$ ACCVIO

successfully

(standalone

completed.

address

mode

Iis

event

flag

was

completed.

only)

specified

the

flag

only)

the

"state"

caller.

written

mode

successfully

(user

event

only)

Set.

The

the

cluster.

4-221

parameter

could

not

Dbe

- SYSTEM SERVICE MACROS
VDS MACROS

SS$ ILLEFC

An illegal event flag number was specified.
5SS$ UNASEFC

In user mode, indicates that the specified common event flag
(see Section 3.14.2) has not been associated with the process
issuing

the

$CLREF macro.

In standalone mode, indicates
through 127 was specified.
standalone mode.

Examples:
MACRO-32

Example:

$READEF_S
BLISS-32

35 FLAGS

Example:

$READEF

(EFN=3y

STATE=FLAGS)

4-222

that an event flag from 64
These flags are not valid in
-

VDS

MACROS

SYSTEM

SERVICE

MACROS

$DS_RELBUF
The

5DS_RELBUF macro

was

previously

used

obtained

with

deallocate
the

$DS

buffer

GETBUF

macro.

space

that

The

pages

deallocated
will
be
the
pages
that
were
most
recently
allocated.
1In user mode, the VDS calls the VMS SCNTREG service
(see the VAX/VMX System Services Reference Manual).

MACRO-32

Format:

SDS_RELBUF
x
BLISS-32

pagcnt,

[retadr],

[region]

Format:

$DS_RELBUF

(PAGCNT=pagcnt,
[RETADR=retadr],
[REGION=region]);

pagcnt

Size (number of pages)

of buffer space to be_deallocated.

retadr

Address of a twd-longword array to receive virtual addresses of
low

and

high

1imit

region

from

address

space

deallocated.

region
Memory

deallocated.

caller

wishes

allocated

from PO space.

buffer

buffer allocated from Pl~space.i

buffer

standalone
1is

allocated
mode,

this

turned

on.

from

Status:

SS$ NORMAL

Buffer

system

parameter

space deallocated.

4-223

buffer

space

management

Return

which

Values are

1is

(Default.)

space.
only

relevant

memory

VDS MACROS

(user

SS$ ACCVIO

- SYSTEM SERVICE MACROS

mode only)

The "retadr" array cannot be written by the caller.
DS$ FRAGBUF

(standalone mode only)

The deallocated space was not contiguous. This condition could
only exist 1if the specified page count was greater the page
count specified with the most recently issued $DS_GETBUF macro,
since space 1is always allocated 1in contiguous chunks in
standalone

mode.

SS$ ILLPAGCNT

The specified page count was less than l.
SS$ PAGOWNVIO

In user mode, indicates that a page in the specified

owned by a more privileged access mode.

In standalone mode, indicates

deallocate
GETBUF

that

attempt

was

range

made

pages than had been previously allocated with

macros.

Examples:

MACRO-32

Example:

BUF _LIMITS?
+QUAD

$NS_RELEUF #10y BRUF_LIMITS
BLISS-32
OWN

tRelease 10 ra3des.

Example:

VECTOR

[233

BUF_LIMITS

$DS_RELRUF

(PAGCNT=10y,

4-224

RETADR=BUF_LIMITS)?

VDS MACROS

- SYSTEM SERVICE MACROS

SSETAST
The

the

Set AST Enable system service is used to enable
delivery
of ASTs to the diagnostic program.

MACRO-32

disable

Format:

SSETAST
x

BLISS-32

and

enbflg

Format:

SSETAST (ENBFLG=enbflg);
enbflg

AST enable

indicator.

value

Return

SS$

disables

A value
AST

enables

AST delivéry,

while

delivery.

Status:

WASCLR
Service

successfully

completed.

AST

delivery

was

previously

Service successfully compléted,

AST

delivery

was

previously

delivery
Services

in
user
Reference

disabled.

SS$

WASSET

enabled.

Notes:

For

notes

mode,

refer

enabling and
to
the

Manual.

disabling AST
VAX/VMS System
|

4-225

VDS

MACROS

SYSTEM

SERVICE

MACROS

Examples:

MACRO-32

Example:

$SETAST.S #1
BLISS-32

sEnable delivery of ASTs

Example:

$SETAST

(ENBFLG=0)3

IMisable

4-226

deliverwy

ASTs

VDS

MACROS

SYSTEM

SERVICE

MACROS

$SETEF
The

Set

(Event

MACRO-32

Event
flags

system

service

discussed

used

Section

set

event

flags.

the

number

3.14.2.)

Format:

$SETEF_x

BLISS-32

Flag
are

efn

Format:

SSETEF

(EFN=efn)
;

efn

Number

may be

from

through

from

mode,

flags

through

may be

‘,//”N\\ \ E

Return

the

event

flag

set.

user

through

mode,

127.

1In

standalone

used.

Status:

SSS_WASCLR
Service
successfully
previously 4.

completed.

The

specified

flag

was

completed.

The

specified

flag

was

event

flag

5SS _WASSET

Service

successfully

previously

SS$

ILLEFC
An

SS$

illegal

event

flag

number

was

specified.

the

specified

UNASEFC

user

mode,

indicates

that

(see
Section
3.14.2) has
issuing the S$SETEF macro.

In standalone mode,

through

127

standalone

was

not

1indicates

specified.

mode.

4-227

been

that

common

associated

These

with

event

flags

are

the

flag

process

from

not valid

1in

VDS

MACROS

SYSTEM

SERVICE

MACROS

Examples:

MACRO-32

Example:

$SETEF #4
BLISS-32

$SETEF

sSHYet event flafi}number 4,

Example:

(EFN=4);

1Set

event

flag

4-228

number

4.,

VDS

MACROS

SYSTEM

SERVICE

MACROS

$SETIMR
The

Set

Timer

system

service

amount

make

number

possible

The

<caller

when

each

will

set,

specified

and

allows

an
event flag be
after a specified

time

notified
time

the

optionally

has
of

AST

request

that

delivered,

elapsed.

concurrent

(via

interval

caller

that

event
has

timer

flag

and

requests.

AST

delivery)

completed.

MACRO-32 Format:
$SETIMR_x

BLISS-32

efn,

daytim,

[astadr],

[reqidt]

Format:

SSETIMR

(EFN=efn,

DAYTIM=daytim,

[ASTADR=astadr],

[REQIDT=reqidt]);

efn
Number

the

event

elapsed.

Note:

which

cause

will

flag

VDS

not

set

after

specified,

the

specified

defaults

event

time

has

flag

errors.

daytim
Address

value

expire.
time.
(See

quadword

1indicates

A negative
In

notes

containing

expiration

absolute

value

standalone

time

indicates

mode,

only

for

specifying

time.)

the

entry

time.

which

positive

from

the

is to
current

values

are

allowed.

<called

offset

negative

the

timer

astadr

Address

mask

the
specified
time
interval
defaults to @, indicating no AST

4-229

AST

routine

expires.

routine

not

when

specified,

called.

VDS

MACROS

SYSTEM

SERVICE

MACROS

reqidt

Identification number for the timer request.
.
A unique number may be specified for each

Default value
timer request,

1s
or

the same number can be assigned to
several
related
requests.
This
number
can be specified with the SCANTIM macro to cancel
all timer requests having the specified number.
Also,
1f
an
AST
routine is specified, the number will be passed
to the AST
routine
Return

SS$

the

AST

parameter.

Status:

NORMAL
Service

SSS

successfully

ACCVIO
The

(user

mode

expliration

completed.

only)

time

cannot

read

the

caller.

SS$_EXQUOTA
®

user

Timer

mode:

entry

quota

insufficient

system

standalone

The

interval

unavailable

AST

dynamic

1imit

memory

quota

exceeded,

complete

the

request.

mode:

<clock

this

system

already

wuse

service.

and

hence

SS$_ILLEFC

An illegal event flag number was specified.
INSFMEM

SS$$

Insufficient dynamic

memory

allocate

timer

queue

entry.

SS$ UNASEFC
®

user

mode:

Indicates

3.14.2)
the

CLREF

that

has

the

not

specified

been

common

associated

macro.

4-230

event

with

flag

the

(see

Section

process

issuilng

VDS

MACROS

standalone

DS$

NOTIMP

SYSTEM

SERVICE

MACROS

mode:

Indicates that an
specified.

evént

These

(standalone

flags

mode

flag
are

not

from

through

valid

standalone

127

only)

An absolute time value was specified for "daytim." Only
time
DS$

values

IPL2HI
The

are

allowed

(standalone

current

IPL

mode
too

was

mode.

standalone

offset

mode.

only)

high.

The

IPL

must

less

than

the

"daytim"

Notes:

create

first

valid

specify

argqument

the

time

for

an ASCII

string,

then

SBINTIM macro to convert the ASCII string into
format required by the "daytim" parameter.
2.

user

mode,

passed,
l0

the

timer

specified

expires

the

quadword

time

has

already

clock

cycle

(within

absolute

the

use

the

milliseconds).

Each

time

requests

the

interval

clock

scanned

time

intervals

has

been

SSETIMR
4.

parameter,

have

set

requests

expired.
to

are

In standalone

mode,

S$SSETIMR

1In

interrupt

being

service

while

interrupts,

determine

not

the

any

queue

the

standalone mode,
every

timer

specified

the

clock

milliseconds

when

processed.
attempt

requests

4-231

are

wuse

still

the

pending.

$DS

WAITUS

VDS

MACROS

SYSTEM

SERVICE

MACROS

Examples:
MACRO-32

Example:

AYTIME§
« QUALDI

+Store

64-bit

time

).
L 4

+ENTRY

AST.RTNy

"M<R2yR3sR4:
¢

AST

routine.
¢
]

#5»

DAYTIMEs

AST_RTN

*d>

$SETIMKR.S

(1 o

RET

BLISS-32

Example:

OWN
DAYTIME

VECTOR

$SETIMR

(EFN=8,

[213
DAYTIM=DAYTIME)}

4-232

here.

vDS

MACROS

SYSTEM

SERVICE

MACROS

$DS_SETIPL
The

Set

change
Only

Interrupt
the

level

Priority

processor's
3

diagnostic

processor's
interrupt
change the IPL without

MACRO-32

system
priorty

service
level

programs

are
allowed
priority level.
These
using this macro.

used

to
change
programs may

the
not

(IPL).

Format:

$DS_SETIPL_x

'BLISS-32

Level

interrupt

level

Format:

$DS_SETIPL

(LEVEL=level);

level

The lével to which the IPL is to be set.

Return

SS$

Status:

NORMAL

Service

successfully

completed.

Examples:

MACRO-32

Example:

$NS_SETIFL.S

BLISS-32

#31

tSet

IFL

(decimszl).

1S5et

IFL

(decimal),

Example:

$OS_SETIFL

(LEVEL=31);

4-233

VDS

MACROS

SYSTEM SERVICE

MACROS

$DS_SETMAP
The Set Adapter Mapping system service of the VDS will

set

registers of a bus adapter so that data will be
the mapping
The
transferred to or from the desired physical address space.
service may be used to set, clear, validate, or invalidate an

adapter's mapping

MACRO-32

Format:

$DS_SETMAP_x unit, func, phyadr,
BLISS-32

“

registers.

[mapbas],

[bytcnt],

[datpth]

Format:

$DS SETMAP

[MAPBAS=mapbas],

(UNIT=unit,

[BYTCNT=bytcnt],

PHYADR=phyadr,

FUNC=func,

[DATPTH=datpth]);

unit

Logical

unit number of the device to be tested.

func

Function

code

indicating

Function codes are listed

the

in Note

function
1.

per formed.

physical

addresses

phyadr

Address of a two-longword array containing

of beginning and ending of physical address space from which or
1s the
Commonly, this
to which data is to be transferred.
value
The
service.
UF
$DS_GETB
the
by
in
filled
array
"phyadr"
the
validate
to
used
1is
address
ending
the
specified as
"bytcnt"

parameter.

mapbas

This argument is used to optionally select

the

first

(lowest

1in mapping virtual
map register to be employed
addressed)
The service
program addresses to physical memory addresses.
will start with the map register specified and set up (or
clear) enough map registers to map the address range indicated
by

"phyadr".

4-234

VDS

For

MASSBUS

255

operation,

(decimal),

selects

the

UNIBUS

where

second,

MACROS

SYSTEM

the

argument

selects

and

operation,

the

set

argument

selects

on.

MACROS

must

the
The

automatlcally

495
(decimal),
where
selects the second, and

SERVICE

value

from

map

first
MBA

Virtual

point

the

must be a value
the

first

spec1f1ed

from

map

Address

The default value is .
For

descriptions

the

VAX

Hardware

Number

bytes

address

translation

bus

adapters,

refer

Handbook.

bytcnt

operation,

composing

MBA

byte

2's
complement
counter.
Maximum value

For

both

MASSBUS

data

the

and

UNIBUS

default

bytes)

1is

value

operation,

the

value

allowed

setting
up
map registers -- enough
the number of bytes specified.
The

transfer.

this

pages

default

For

MASSBUS

stored

the

65535

(decimal).

value

are

used

mapped to

used,

one

when

handle

page

(512

mapped.

datpth
Value

indicating

the

UNIBUS

direct

be specified to select
field
1is
ignored
1if
buffered

data

paths.

data

path.

The

path.

Values

from

DS$ NORMAL
successfully

through

1is

may

one of the buffered
data
paths.
This
the
UNIBUS
adapter
does
not support

Return Status:

Service

default
1

completed.

4-235

vDS

MACROS

SYSTEM

SERVICE

MACROS

DS$ ERROR
The

specified

logical

unit

number

too

large.

DS$ IHWE

Initial hardware error.
A hardware error was detected
1in
the
bus
adapter
before the specified function was performed.
The
function was not
performed.
Call . the
$DS _CHANNEL
service,
specifying
the
CHCS STATUS
function
to
determine the error
type.

$DS_PROGERR
An

invalid

The

byte

function

count

code

specified

was
is

specified.
too

large

the
specified map register.
starting map register number.

Lower

The byte count specified
indicated by "phyadr."

not

the

fit

mapped

byte

count

into

the

starting

lower

buffer

the

1limits

will

Notes:

Function

Codes

Following

these

codes

list

are defined

valid

function

the

codes.

For

MACRO-32,

$DS CHMDEF macro.

CHMS INVALIDATE - Clear the "valid" bits- for
all
registers
1in
the bus adapter to which the device
specified by "unit" 1s attached.

e¢

CHMS MFWDN

transfer

Set

according

registers

forward

MASSBUS,
counter.

CHMS MFWDNO Set wup
map
registers
for
a
transfer
according to "phyadr," "mapbas," and
parameters, and set the "valid" bit
in
each

forward

set

used.
~a

byte

not

offset

the

"valid"

invalidate
any
transfer

4-236

will

"mapbas,"

invalidate any registers.
TIf
address register and MBA byte

and

"phyadr,"

for

"bytcnt"

used.
Do
not
load MBA virtual

map

and

parameters,

map
unit

bit

registers.
performed

each

"bytcnt"
register
Indicate that

(UNIBUS

only).

VDS

MACROS

CHM$ MFWDV

SYSTEM

Invalidate

registers

for

"mapbas,"

and

"bytcnt"

bit

1in

each

virtual

forward

CHMS MFWDVO

MACROS

all

registers.

"mapbas,"
and

forward

"bytcnt"

MREVN

transfer

Set

according

parameters,

and

used.

not

set

MBA

byte

all

map registers.

MBA virtual

CHMS

MREVNO

transfer

Set

according

parameters,
and

used.

byte

not

offset

CHM$ MREVV

registers
"mapbas,"

for
and

bit

1in

registers for
"mapbas," and

‘bit

each

transfer

CHM$

counter

any

map

and

MBA

registers

"phyadr,"

the

"valid"

any

will

each

registers.

bit

MASSBUS,

counter.

performed

all

map

used.

performed

(UNIBUS

not

MBA

alter

virtual

map

MBA

Set up

map

that

to "phyadr,"
the
"valid"

byte

offset

only).

address

1oad

counter.

contents.

and

MBA

If
byte

transfer.

alter

virtual

reverse

1Indicate

that

only).

Set up
map
to "phyadr,"
the
"valid"

registers.

(UNIBUS

MASSBUS,

Invalidate

reverse
"bytcnt"

Indicate

a reverse transfer according
"bytcnt" parameters, and set

forward

MBA byte

MBA

load

used.

a
and

each

registers.

for

byte

"mapbas,"

and

Do not

for

"bytcnt"

CHMS NREVN
MASSBUS,

and

"mapbas,"
bit

load

for

reverse

for

all map registers.
a reverse transfer according
"bytcnt" parameters, and set

will

NFWDN

MASSBUS,

Invalidate

address

CHMS MREVVO

registers

transfer

each

virtual

set

map

offset

"valid"

set

"phyadr,"

"valid"

"phyadr,"

and

Set
to

the

invalidate

MBA

counter.

a byte

the

"valid"

1load

Indicate that
(UNIBUS
. only).

map

address

map

"phyadr,"

MASSBUS,

according

parameters,

the

and

transfer

set

invalidate

load

and

used.

bit in each register used.
transfer will be performed

CHMS

Set

transfer according

Invalidate

for

map

parameters,

address

reglsters

SERVICE

map

transfer.

4-237

address

contents.

and

MBA

If
byte

VDS

SYSTEM

MACROS -

SERVICE MACROS

Examples:

MACRO-32

Example:

BUF_SIZE

1024

1
BLKL
BLKQ 1

LOG_UNIT:
BUFFER!
]

$DSmSETMfiP4S‘LDB-UNIT, $CHM$ _MFWIVs BUFFERs»#BUF_SIZE
BLISS-32

Example:

LITERAL

OWN

BUF_SIZE =
|

LOG_UNIT
BUFFER

10243

§ VECTOR,»
t VECTOR C2133%
L4

$0S_SETMAF (UNIT=.LOG.UNIT, FUNC=CHM$_MFWIV,
PHYADR=BUFFERs

4-238

BYTCNT=RUF_.SIZE)?

VDS

<
\

MACROS

SYSTEM

SERVICE MACROS

$SETPRT
The Set Protection on Pages system service allows a program

change the protection code associated with one or more pages of

virtual

MACRO-32

memory.

Format:

SSETPRT

inadr,

[retadr],

[acmodel,

prot,

[prvprt]

BLISS-32 Format:

SSETPRT

PROT=prot,

(INADR=1inadr,

[RETADR=retadr];

[ACMODE=acmode]l,

[PRVPRT=prvprt]);

inadr

Address of a two-longword array
containing
the
starting
and
ending
virtual addresses of the pages for which the protection
code 1s to be changed.
Specifying
the
same
value
for
the
starting
and ending addresses will cause the protection of one
page to be changed.
Only the virtual page
number
portion
of
the

address

used;

the

low-order

nine

bits

are

1ignored.

retadr

Address of a two-longword array to
of
addresses
virtual
ending
protections

changed.

See

Note

receive
the
starting
and
their
had
that
pages
the

acmode

Access mode on behalf of which the request 1is being made.
specified

access mode

maximized

with

the

access

mode

caller.
The result must be equal to or
more
privileged
the access mode of the owner of the pages being changed.
- This

parameter

ignored

standalone

The

the

than

mode.

prot

New protection,

various
macro

page

which

in bits

through

LIB.MLB.

protection
defined

codes

4-239

are

Symbolic

names

for

the

described by the SPRTDEF

VDS MACROS - SYSTEM SERVICE MACROS

prvprt

Address

last page whose

the

one

page

Return

byte

was

receive

changed.

(
the

protection

previously

protection was changed.

assigned

Useful

1if only

the

caller,

Status:

SS$ NORMAL
Service

SS$

successfully

completed.

ACCVIO
mode:

User

—

The

input

address

array

cannot

read

or
the output address array or the byte
previous protection cannot be written by
An

attempt

was made

nonexistent
@

Standalone

The

<change

the

protection

the

reserved

mode:

specified

address

page.
7N

to receive the
the caller.

space

address

range was

(CQ000000

virtual

FFFFFFFF)
.

SS$ EXQUOTA (use mode only)
The process exceeded its paging file
page

SS$ IVPROTECT

The

read-only

(user

specified

greater

private

mode

15.

mode,

quota
a

while

read/write

<changing
page.

only)

protection

than

section

code

has

numeric

value

1is

SS$ LENVIO

user

the

standalone

end

page

program
or

the

control

mode,

the program,

specified

range
is beyond

the

end

beyond

the

region.

page

control,

the

4-240

specified

system

range

region.

VDS

SS$ NOPRIV
A

page

(user
in

mode

the

SS$ PAGOWNVIO

MACROS
-

mode

DSS_PROGERR

MACROS

page

(standalone

range

the

system

address space.

only)

Page owner violation.
protection on

SERVICE

only)

specified

(user

SYSTEM

An attempt
owned

mode

was

by a more

made

privileged

<change

the

access mode.

only)

The specified address range was improperly formatted.
Notes:

standalone mode,

meaningful
2.

error

setting

page

memory management

occurs

while

has

<changing

protection
been
page

is |

only

protections,

the

enabled.

return
array,
1f
specified,
will
contain the start and
ending address of the pages that were
changed before
the
error
occurred.
If no
pages
were changed, the return
address array will contain a -1.

Examples:

MACRO-32 Example:

ADDR _RANGE ?

+BLKQ

+
¢

$SETFRT INADR=ADDR_RANGEs

FROT=#PRT$C_UW

BLISS-32

Example:

OWN
ADDR_RANGE

|
VECTOR

[C215

$SETPRT

(INADR=ADDR_RANGE:

FROT=FRT$C_UW)3

4-241

VDS

MACROS

SYSTEM

SERVICE

MACROS

$DS_SETVEC
The

Set

load

Exception or

service

exception

MACRO-32

routine.

Only level
Vector
use of

Interrupt

system

service

used

interrupt vector with the address of a

diagnostic

contents may
this macro.

Vector

programs may use

not

changed

the $DS SETVEC

by any means

macro.

other than

the

Format:

$DS_SETVEC
x vector,

BLISS-32

srvadr,

[code]

Format:

$DS_SETVEC

(VECTOR=vector,

SRVADR=srvadr,

[CODE=codel);

vector

The

vector address,
Block (SCB).
Refer

relative

the

to the base of
VAX Architecture

the

SCB.

vector

addresses

See

Note

the System
Control
Handbook for a list

srvadr

The

address

when
an
specified

service

routine

which

exception
or
interrupt
is
vector.
The address must be

receive

control

delivered
through
the
on a longword boundary.

code

Used

indicate

the

stack

which

the

event

1is

serviced.

(The

service

default

the

0.)

event

the

kernel

stack

unless

already
running
on
the interrupt stack, in which case
service
on
the
interrupt
stack.
Behavior
of
the
processor
is
undefined
for a "kernel stack not valid"
exception with this code.
|

If 1, service the event on the interrupt stack.
event

is an

exception,

raise

the

IPL to

the

1F(1l06).

Can

to
|

4-242

VDS MACROS - SYSTEM SERVICE MACROS
The

value specified for this
parameter
<1l:8>
of the specified vector.

Return

1is

1loaded

1into

bits

does

not

start on

Status:

DS$ NORMAL
Service

successfully

completed.

DS$_IVADDR

Address specified for "srvadr" routine
longword

boundary.

DS$_IVVECT

Address specified for "vector"
is not a valid vector address.
DS$ ICBUSY

The caller'specified
interval

clock

was

the

interval

clock's

wvector,

and

the

that

the

already active.

Notes:

When

setting

device

interrupt

vectors,

remember

SCB
1is several pages long.
The page on which a particular
device interrupt vector resides is determined by
both
the
bus
adapter(s)
to
which
the
device is attached and the
processor being used.

For

instance,

UNIBUS
device's
device's p-table,
HPSW VECTOR

find

the

SCB

offset

for

the

p-table

associated

with

existing between the device and the processor,

and

type

particular

vector
address,
read HPSW VECTOR in the
then OR this value with the
contents
of

adapter

depend on the processor

EACH adapter

The

type.

number

S~/‘(‘-—\\

device's p-table contains the actual UNIBUS vector, and
adapters'
p-tables
contain
relative offsets into the
for the bases of the vector areas for the adapters.)

4-243

(The

the
SCB

VDS MACROS - SYSTEM SERVICE MACROS
It thus becomes obvious that referencing device vectors
1in
to become
program
diagnostic
a
<cause
will
SCB
the

processor-dependent.

Using

the $DS CHANNEL service for

operations eliminates the need to load SCB vectors and
keeps diagnostic programs processor— 1independent.
|

I/O

thus

Examples:

MACRO-32

Example:

$0S_SETVEC.S

BLISS-32

VECTADDRy

SERV_RTN

Example:

$NS_SETVEC (VECTOR=,VECTADDRy SRVADR=SERV_RTN: CODE=1)3}

4-244

VDS

MACROS

SYSTEM

SERVICE

MACROS

$DS_SHOCHAN
The

Show

Channel

Status

the

wuser's

terminal

system

the

service

registers.
This
service should
$DS _CHANNEL or $DS SETMAP services
The

display

mnemonic
current

This

will

name
value

service

MACRO-32

consist

the

of ' each bit
of

each

only

bit

contents

available

name

VDS

will

internal

display

bus

adapter

be
used
whenever
detect adapter faults.
of

field within

field.

the

each

the

level

diagnostic

and

the

programs.

Format:

$DS_SHOCHAN
x unit

BLISS-32

Format:

$DS_SHOCHAN

(UNIT=unit);

unit
Logical

unit

number

which

are

displayed.

Return

this

unit

device currently
attached will be

being tested.
the one whose

Adapter
registers

Status:

$DS_NORMAL
Service

successfully

completed.

$DS_ERROR
Logical

unit

number

too

large.

Notes:

may

error

macros,

useful

reporting

include

routine

$DS ERRxxxX)
.

the

$DS SHOWCHAN

(refer

4-245

the

macro
in
an
error reporting

VDS

MACROS -

SYSTEM

SERVICE

MACROS

Examples:

Example:

$NS_SHOCHAN.S

BLISS-32

LOG_UNIT

tDisrlav

adarter

status.

Example:

$DS_SHOCHAN

(UNIT=.LOG_UNIT)?¢

//’

MACRO-32

4-246

VDS

MACROS

SYSTEM

SERVICE

MACROS

$DS_SUMMARY
The

Print Summary system
program's summary routine
discussed in Section 3.7.
also be executed when the

requested

MACRO-32

number

service

will
cause
the
diagnostic
to be executed.
Summary routines are
Note that the summary
routine
will
$DS ENDPASS service is called, if the

of program passes have been executed.

Format:

$DS_SUMMARY
x

BLISS-32

Format:

$DS_SUMMARY
;

Return
No

Status:
status

returned.

Examples:

MACRO-32

Example:

$DS_SUMMARY
.S

BLISS-32

Example:

—

“

$DS_SUMMARY$

4-247

VDS MACROS - SYSTEM SERVICE MACROS

$UNWIND
The

‘to

Unwind
Call Stack

"unwind"

the

system service allows a

©procedure

call

condition handler

stack to a specified depth.

a specified
through
of stepping
"Unwinding" is the process
number
of
call frames
on the stack so that when the condition
instead
handler returns, the specified call frame will be used
one placed on the stack when the condition handler was
the
of
called.
In other words, the normal execution flow is
altered.
Optionally,
an address can be specified
the return PC argument of the call frame

For

further

condition

discussion

handling

1in

the

unwinding,

that will be placed in
that was stepped to.

refer

sections

Manual.

MACRO-32

Format:

SUNWIND
x [depadr],

BLISS-32

VAX/VMS System Services Reference

[newpc]

Format:

SUNWIND ([DEPADR=depadr],

[NEWPC=newpc]);

depadr

Address of

longword

indicating

the

depth

is
to
be unwound.
A depth of @ indicates
'was active when the condition occurred (the

which

the

stack

the call frame that
frame
that
would

1
returns),
handler
condition
the
when
wused
be
normally
indicates the caller of that frame, 2 indicates the
caller
of
If the depth is specified
caller of the frame, and so on.
the

a successful status code
as @ or less, no unwind occurs and

1is specified for this parameter, the
value
no
If
returned.
unwind is performed to the caller of the frame that established
the

condition

handler.

newpc

Address to
value
1is

be given control when the unwind is complete.
placed
in
the return PC argument of the call
that is
stepped
to.
If
no
wvalue
1is
specified
for
parameter, the return PC argument is not altered.

4-248

This
frame
this

VDS

Return

MACROS

SYSTEM

SERVICE

MACROS

Status:

SSS NORMAL
Service

successfully

SS$ ACCVIO
The

(user

call

mode

stack

is detected
address.

when

completed.

only)
not

the

accessible

call

stack ‘is

the caller.

scanned

This

modify

condition

the

return

SS$ INSFRAME

There

are

number

insufficient call

frames

unwind

condition

currently

the

specified

frames.

SS$ NOSIGNAL
No

signal

for

exception

active.

SSS_UNWINDING
An

unwind

already

progress.

Notes:

The actual
called.

unwind
The

does

service

not
simply

in the call frames
so
returns,
an
"unwind"
that

being

that

occur

when

modifies

when

procedure

the

service

return

addresses

the
condition
handler
called from each frame

unwound.

Examples:

this

call

example,

frame

the

<created

SUNWIND will

the

replaced by OUTADDR, and the
handler will cause that call

cause

CALLS

the

return

ROUTINEl

RET instruction on
the
frame to be referenced.

4-249

instruction

the

condition

VDS

MACRO-32

MACROS

SYSTEM

SERVICE MACROS

Example:

ROUTINEL

CALLS

ROUTINE2

RET

ROUTINE2:
.

(condition handler is called.)
+
4

RET

COND_HNDLR?
$1s

MOVL

S$UNWIND_S

DEFPTH

LEPTHy

OUTADDR

RET

L L J

OUTADDR?

4-250

VDS MACROS - SYSTEM SERVICE MACROS
BLISS-32 Example:

ROUTINE

ROUTINEL

BEGIN

CALLS

ROUTINE?2

END?»

ROUTINE
-

ROUTINEZ2

BEGIN

(condition handler is'called.)
]

END3

ROUTINE COND_HNDLR

BEGIN

= 13}
DEFTH
$UNWIND.S

DEFTHs

ERRORS

ENDs

ROUTINE

ERRORS
BEGIN

END$

- 4-251

VDS

MACROS

SYSTEM

SERVICE

MACROS

SWAITFR
The

}

SWAITFR macro calls a

specified

event

flag

system service

set before

that will wait until

returning.

Event

(
a

flags are

discussed in Section 3.14.2.
1If the specified flag 1is
already
set,
the
service
routine
returns immediately.
Otherwise,
control is not returned to the caller until the flag
has
been
set.

MACRO-32

Format:

x efn
SWAITFR

- BLISS-32 Format:
SWAITFR

(EFN=efn);

efn

Number

Return

the

event

flag

wait

for.

Status:

SS$ NORMAL
Service

successfully

completed.

SS$ ILLEFC

An
SS$

illegal

UNASEFC

event

(user

flag

mode

number

was

specified.

only)

In user mode, indicates that the specified
common
event
flag
(see
Section
3.14.2) has not been associated with the process
issuing the SSETEF macro.

In standalone mode,
1indicates
through
127
was
specified.
standalone

mode.

4-252

that
an
event
flag
from
These
flags
are
not valid

64
in

VDS MACROS
- SYSTEM SERVICE MACROS
Notes:

While

the

system

service

routine

is waiting for
the
event
interrupt the service.
Program
SWAITFR
system service
after
routine has completed.
-

flag
to be
control will

set, ASTs can
return to the

execution

the

AST

Examples:

MACRO-32

Example:

SWATITHFR..S

BLISS-32

Example:

$WAITFR

(EFN=S5)3;

4-253

VDS MACROS - SYSTEM SERVICE MACROS

$DS_WAITMS
The Millisecond Wait system service is used to create

delay

the service
When
of milliseconds.
number
specified
of a
until
caller
the
to
returned
not
is
control
called,
is
routine

an
(unless
-elapsed
has
time
of
amount
requested
the
a
containing
routine
a
causes
that
occurs
event
asynchronous
1).
Note
see
executed;
be
to
macro
CANWAIT
$DS
or
SCANTIM

MACRO-32

Format:

$DS_WAITMS
x

BLISS-32

time,

[tag]

Format:

$DS_WAITMS

(TIME=time,

[RETTIM=tag]l);

time

Length of delay

milliseconds.

1in

time

units.

Value must be greater

One

time

than 0.

unit

equals

194

tag

Address of longword to
before
canceled
was

delay
receive amount of unused time, if
all requested time was used up (see note

l1).

Return

Status:

SS$ NORMAL
Service

successfully completed.

DS$ PROGERR

invalid value was specified

4-254

for

the

"time"

parameter.

VDS

MACROS

SYSTEM

SERVICE

MACROS

delivery

quota

SS$ EXQUOTA
®

user

Timer

mode:

entry

quota

insufficient
e

dynamic

standalone

AST

memory

exceeded,

space.

mode:

The

interval
unavailable to

<clock

this

is
already
1in
system service.

use

and

Notes:

If
an
asychronous
interrupt)
occurs,

interrupt

SWAITMS

issues

return

from

address

the

service
the

event
(AST
delivery
or
and
the
routine
handling

SCANTIM

will,

event

S$DS CANWAIT macro,

regaining program

handler,

specified

store

"tag"

and

caller.

Examples:

MACRO-32

Example:

$DS_WAITNS_S $#100y TIME_LEFT
BLISS-32

Example:

(TIME=200y

RETTIM=TIME_LEFT)

$OS_WAITMS

4-255

hardware
the AST or

the

control

unused

return

the

after

delay

control

time
the

VDS MACROS - SYSTEM SERVICE MACROS

$DS_WAITUS
a delay
The Microsecond Wait system service is used to create
service
the
When
s.
of microsecond
number
of a specified

d the caller
routine is called, control is not returneto
the

requested

amount

has

time

elapsed

asynchronous event occurs which causes a routine
SCANTIM or $DS_CANWAIT macro to be executed;

until

(unless

containing

see Note 1).

This macro may only be used'by,level 3 diagnostic programs.

MACRO-32 Format:

x time, [tag]
$DS WAITUS

BLISS-32 Format:

$DS_WAITUS

(TIME=time,

[RETTIM=tagl]);

time

Length of delay

microseconds.

time

units.

One

time

Value must be greater than #.

unit

equals

tag

delay
Address of longword to receive amount of unused time, 1f
was canceled before all requested time was used up (see notes).
Return

Status:

SS$ NORMAL

Service

successfully completed.

4DS$ _PROGERR
An

invalid value was specified for

4-256

the "time"

parameter.

VDS

MACROS

SYSTEM

SERVICE

MACROS

delivery

quota

SS$_ EXQUOTA
In

user

Timer

mode:

entry

quota

insufficient

dynamic

standalone

The

- interval

AST

memory

mode:

clock

1is

this

system

service.

asychronous

event

(AST

unavalilable

exceeded,

space.

already

use

and

hence

Notes:

delivery

hardware

interrupt)
occurs,
and
the
routine
handling the AST or
interrupt issues a SCANTIM or $DS CANWAIT macro,
then
the
$DS WAITUS service will, on regaining program control after

return

from

the

event handler,

in the address specified
caller.
|
|

not attempt

requests

have

to
been

use

the

issued

store

"tag"

and

are

still

Example:

$OS5_UWAITUS.S

BLISS-32

#50»

TIME_LEFT

Example:

$DS_WAITUS (TIME=40s, RETTIM=TIME.LEFT);

4-257

unused

return

$DS WAITUS

Examples:

MACRO-32

the

delay

control

service
pending.

time

the

$SETIMR

vDS

MACROS

SYSTEM

SERVICE

MACROS

service
reactivites
a
a
result
of
execution

process
of the

$WAKE
The Wake system
hibernation
as

that
1is
1in
SHIBER system

service.

MACRO-32

Format:

BLISS-32

SWAKE

pidadr

Format:

([PIDADR=pidadr],

(user

mode

Address of
the

prcnam

process

[PRCNAM=prcnam]);

only)

longword
to

containing

the

process

indentification

be awakened.

(user mode only)

Address of
pointing
Refer

details

Return

[prcnam]

[pidadr],

x
SWAKE

character
the

process

the

string
name

VAX/VMS

the

descriptor

(see

Section

4.3)

Reference

Manual

for

string.

System

interpretation

Services

these

parameters.

Status:

SS$ NORMAL

Service successfully completed.
SS$

ACCVIO
The

name

caller,
caller.

(user

mode

string

the

only)
string

process

descriptor

1id

4-258

number

cannot

read

the

cannot be written by the

VDS

MACROS

SYSTEM

SERVICE

MACROS

SS$ IVLOGNAM
The

process

name

string

invalid.

SS$ NONEXPR
Warning.

process

The

was

specified

process

does

not

exist,

invalid

specified.

SS$ NOPRIV

The caller's process does not have the privilege
waking

the

specified

required for

process.

Notes:

standalone

place

mode,

the

only meaningful

event

handler

use

that

will

this

executed

while the diagnostic program is in hibernation.
This
awaken the program so that it may continue executing.

Examples:

MACRO-32

Example:

$WAKE_S

BLISS-32

()¢

$WARE

Example:

4-259

macro

will

MACROS

SYSTEM

SERVICE

MACROS
PN

VDS

$WFLAND
The SWFLAND macro calls a system service that will wait until a
specified
group of event flags is set before returning.
Event

flags
All of the event
flags are discussed in section 3.14.2.
flags
specified
the
If
cluster.
flag
event
must be in the same
are already
set,
the
service
routine
returns
immediately.
Otherwise,
specified
MACRO-32

control

flags

have

not

been

returned

to the

set.

caller

until

all

Format:

SWFLAND
x efn,

BLISS-32

mask

Format:

SWFLAND

(EFN=efn, MASK=mask);

efn

Number

any

event

flag

in the

cluster

being

used.

mask

32-bit mask in which bits set to 1 indicate

must be

Return

set before

the

service

system

event

flags

that

common

event

flag

returns.

Status:

SS$ NORMAL

Service

SS$

completed.

ILLEFC

An
SS$

successfully

illegal

event

flag

number

was

specified.

UNASEFC

In user mode, indicates that the specified
(see

Section

issuing

the

3.14.2)

has not been associated with

macro.

In standalone mode,
indicates
specified.
was
127
through
standalone

the process

mode.

4-260

that
an
event
flag
from
64
not valid in
are
flags
These

VDS

MACROS

SYSTEM

SERVICE

MACROS

Notes:

While

the

system

service

routine

flags
to
be set, ASTs can
control will return to the

executio
of the
n AST

routine

has

Examples:

MACRO-32

Example:

$WFLAND.S

#0,

FLAG_.MASK

$WFLAND_S #0, #000000FO0
BLISS-32

Example:

SWFLAND

(EFN=0y

MASK=.FLAG_.MASK)}

SWFLAND

(EFN=0y

MASK=ZX’000000F0’)}

4-261

waiting

for

the

event

interrupt the service. Program
SWFLAND
system
service
after

completed.

VDS

MACROS

SYSTEM

SERVICE MACROS

$WFLOR
wait until
The SWFLOR macro calls a system service that will
specified group of event flags is set before
any one of a
All
Event flags are discussed in Section 3.14.2.
returning.
If
the event flags must be in the same event flag cluster.
of
the service
any one of the specified flags 1is already set,
1is not
control
Otherwise,
immediately.
returns
routine
flags has
specified
the
returned to the caller until one of
been

set.

MACRO-32

Format:

x
SWFLOR

efn,

mask

BLISS-32 Format:

SWFLOR (éfn, mask);
N\

efn

in the cluster being used.

Number of any event flag

mask

32-bit mask in which bits set to 1 indicate

are to be tested by the system service.

Return

SS$

Status:

NORMAL

Service

successfully completed.

SS$ ILLEFC

An illegal event flag numbér was specified.

4-262

event

flags

that

VDS

MACROS

SYSTEM

SERVICE

MACROS

SS$ _UNASEFC
In

user mode, indicates that the specified
common
(see
Section
3.14.2) has not been associated with
issuing the macro.

standalone mode,

through

127

standalone

was

indicates

specified.

that

These

event

flags

event

the

flag

are

flag

process

not

mode.

from

valid

Notes:

While
to

system

service

set,
ASTs
return to the

will
AST

the

routine

has

routine

can

interrupt

WFLOR

system

completed.

Examples:

MACRO-32

Example:

$WFLOR_-S

%20,

FLAG_MASK

$WFLOR.S

#0,

$000000F0

BLISS-32

Example:

$WFLAND

(EFN=0y

MASK=FLAG_MASK)3;

$WFLAND

(EFN=0y

MASK=%ZX’000000F0’)}

4-263

waiting

for

event

the service.
Program
service after execution

flag

control

the

VDS MACROS - SYMBOL DEFINITION MACROS
4.7

SYMBOL

DEFINITION MACROS

$DS_BITDEF
The $DS BITDEF macro defines (for MACRO-32 programs) a bit mask
for
each
bit from @ through 31.
For BLISS-32 programs, these
symbols may be referenced without first issuing the
$DS BITDEF
macro.

Symbols

defined

are:

BITO
BIT1

=
=

00000001
00000002

(HEX)
(HEX)

BIT2

00000004

(HEX)

BIT31

80000000

(HEX)

4-264

VDS

MACROS

SYMBOL

DEFINITION

MACROS

$DS_CFDEF
‘The

$DS_CFDEF macro defines (for
MACRO-32
programs)
symbolic
for
the fields of a call frame.
For BLISS-32 programs,
these symbols may
be
referenced
without
first
issuing
the
$DS_CFDEF macro.
names

Symbols

defined

are:

CFSL ONCOND

— Address

CFSW_PSW
CFSW MASK

- Processor status
- Register mask

CFSL

CFSL AP
CFSL _FP
PC

CFSL REG

condition

handler

word

- Saved AP
- Saved FP
Saved

- Start of

saved

RO through R1l

Notes:

These symbols are used
in '"CFSW_PSW(FP)'.

4-265

offsets

from

the

current

FP,

VDS

MACROS

SYMBOL DEFINITION MACROS

- $DS_CHCDEF
The $DS CHCDEF
symbolicTM names

the
(for MACRO-32 programs)
macro defines
of the function codes associated with the

‘Symbols defined

are:

$DS _CHANNEL service. For BLISS-32 programs, these symbols
be referenced without first issuing the S$DS_CHCDEF macro.

may

CHCS INITA
CHCS INITB

CHC$ ENINT

CHCS DSINT

CHCS ABORT
CHCS PURGE

CHCS CLEAR
CHCS$ STATUS
CHCS

SETDFT

CHCS$ CLRDFT

4-266

VDS

MACROS

SYMBOL

DEFINITION

MACROS

$DS_CHMDEF
The SDS_CHMDEF macro defines (for MACRO-32
programs)
symbolic
names
for
the
function
codes associated with the $DS_SETMAP
service.
For
BLISS-32
programs,
these
symbols
may
be
referenced without first issuing the $DS_CHMDEF macro.
Symbols

defined

are:

CHMS$ INVALIDATE

CHM$ MFWDN

CHM$ MFWDNO
CHMS MFWDV
CHMS$_ MFWDVO
CHMS MREVN

CHMS$ MREVNO
CHM$

MREVV

CHM$

MREVVO

CHMS NFWDN
CHM$ NREVN

4-267

VDS MACROS - SYMBOL DEFINITION MACROS

$DS_CLIDEF
The $DS _CLIDEF macro defines
for

"traversal

the

$DS_QLI

macro.

Symbols

defined

(for MACRO-32

codes"

used

programs)

associated

symbolic

with

the

are:

CLISK ALNUM
CLISK ALPHA

CLISK NUM

CLISK SYMBOL

CLISK FILE
CLISK

SPACE

CLISK

SLASH

CLI$K

VALUE

CLI$K COMMA

CLISK EOL

CLISK DEC

CLISK HEX
CLISK

OCT

CLI$K STRING
CLISK BR
CLISK BIF

/’/@\\

names

CLISK CALL

CLI$K

RETURN

CLISK BIFS
CLISK EXIT

CLI$K ERROR

4-268

VDS

MACROS

SYMBOL

DEFINITION MACROS

$DS_DSDEF
‘The

SDS_DSDEF

names
with

for
the

prefix

are

BLISS-32

first

the

defined

programs)

codes

the

$SSDEF

symbols

may

macro.

beginning

macro
be

the 'SsS_!
LIB.MLB.
For

referenced

NORMAL
ILLCHAR

DS$”VASFUL
DS$

IHWE

DSS$

ILLPAGCNT

DSS$ KRNLSTK
DS$ CHME
ICERR

DS$ UNEXPINT
DSS$ BADLINK

DS$ DEVNAME

DS$

WARNING

DS$ OVERFLOW
DS$

PROGERR

DS$ IVVECT

DS$ INSFMEM
DS$ FHWE

DS$ FRABUF
DS$ POWER

DS$S NOTIMP

DS$

ICBUSY

DSS$ CHMK
DS$ NEEDUNIT
DS$S NOPCS

4-269

symbolic

that begin

with

are:

DSS$S NOTDON

DS$

MACRO-32

Status

$DS DSDEF

DS$ SEVERE
DSS$

these

(for

returned by system services

'DS$_'.

programs,

DSS$S

defines

defined

issuing

Symbols

macro

status codes

DS$

ERROR

DS$S

TRUNCATE

DS$ NULLSTR

DS$ IVADDR
DSS MMOFF

DS$

LOGIC

DS$

MCHK

DS$

IPL2HI

DS$

ILLUNIT

DS$ TRANSL

DS$ ARITH
DS$ BADTYPE

DS$_NOSUPPORT

without

VDS MACROS - SYMBOL DEFINITION MACROS
$DS_DSSDEF
2

MACRO-3
(for
defines
macro
$DS_DSSDEF
of entry
names
ic
the symbol
programs)
BLISS-32
system services.

The

programs

points for the

"For BLISS-32 programs, the macro must be defined globally in at
least one source module, as follows:
GLOBAL
Symbols

defined

S$DSSDEF;
are:

DS$ABORT
DSSASKLGCL
DS$ATTACH
DS $BREAK
DS$CKLOOP
DS$CVTREG
DSS$SERRDEV
DSSERRSOFT

DS$FREEDBGSYM

DS $GPHARD

DS$INLOOP
DS $MAPDBGB LOCK
DS$SMOVPHY
DS$PRINTB
DSSPRINTSIG
DSS$RELBUF

DS $SETMAP
DS $SHOCHAN
DSSWAITUS
SYS$SASSIGN
SYS$SCANTIM
SYSSCONNECT
SYS$SDASSGN

SYS$GET
SYSSLKWSET
SYS$QIO
SYS$SREADEF
SYS$SSETIMR
SYS $SETRWM
SYSSULWSET
SYS$SWFLAND

DS SASKDATA
DSSASKSTR

DS $SBGNSUB
DSSCANWAIT
DSSCLRVEC
DSSENDPASS
DSSERRHARD
DSSERRSYS
DS SGETBUF
DSSHELP
DSSLOAD

DS SMMOFF
DSSMOVVRT
DSSPRINTF
DSSPRINTX
DSSRELMEM
DSSSETPRIEXV
DS $SUMMARY
SYSSALLOC

SYSSBINTIM
SYSSCLOSE
SYSSDISCONNECT
SYSSFAQ
SYSSGETCHN
SYSSNUMTIM
SYSSQIOW
SYSSSETAST
SYSSSETPRI
SYS SSETSWM
SYSSUNWIND
SYSSWFLOR

4-270

DS SASKADR
DSSASKVLD
DS $BRANCH
DSSCHANNEL
DSSCNTRLC
DS SENDSUB
DSSERRPREP
DSSESCAPE
DSSGETMEM
DSSINITSCB
DSSLOADPCS

DS SMMON
DSSPARSE
DSSPRINTS
DSSPROBE
DSSSETIPL
DSSSETVEC
DSSWAITMS
SYSSASCTIM
SYSSCANCEL

SYSSCLREF

SYSSDALLOC
SYSSFAOL
SYSSGETTIM
SYSSOPEN
SYSSREAD
SYSSSETEF
SYSSSETPRT
SYSSULKPAG
SYSSWAITFR

VDS

MACROS

macro

defines

SYMBOL

DEFINITION

MACROS

$DS_ERRDEF
The

$DS

symbolic

ERRDEF

names

SDS_ERRxxxx
error
-

For

macros.

reporting

BLISS-32

reporting
macro

the

These

(for

symbols

will

Refer

programs,

routines

produces

these

symbols

because
parameter

error

descriptions
for

examples

reporting

Symbols

defined

programs)

associated

most

likely

the

with
be

the

used

routines.

the

are

expansion
1list

routine.

macros

MACRO-32

parameters

not

for

the

$DS_BGNMESSAGE

referencing

used

the

error

$DS

BGNMESSAGE

error

reporting

and

SDS_ERRxXXX

routines.

1in

$DS_ ERRXXXX
parameters

are:

ERRS NUM

ERRS

UNIT

ERRS MSGADR
ERR$ PRLINK
ERRS$ Pl

ERRS

ERRS$ P3

ERRS P5

ERR$ P6

Notes:

These symbols are used as
example, ERRS P3(AP).

for

4-271

offsets

into

the

argument

list,

—~

MACROS

SYMBOL DEFINITION MACROS
TN

VDS

$DS_HPODEF
$DS_HPO_DECL
the
-32 programs)
MACRO(for
defines
p—-table.
a
symbolic names of the device-independent fields of
$DSHPODEF

The

macro

The $DSHPO DECL is used for BLISS--32 programs.
($SDS_xxxx DEF);

where "xxxx" represents
are

fields
p-table
DEF) .
($DS_RH780
Symbols defined

which
for
name of the device
the
DECL
HPO
$DS
as
such
defined,
be
to

are:

HP$Q DEVICE

HPSW SIZE

HPSB

FLAGS

HP$B DRIVE
HPST DEVICE
HPSA DEVICE
HPSA DVA
HPSA

follows:

this macro is as

$DS _HPO DECL

The format

LINK

HPSW VECTOR
HPST TYPE

HP$A DEPENDENT

Device-dependent

Quadword descriptor of device name

Total length of p-table
Initialization flags
Unit

number

Start of device name string
Hardware address of device

Base of address space assigned to device

Address of p-table for device's 1link
Device's

(

vector

t counted string for device type
Starof
Start of device-dependent portion of p-—-table

fields

Notes:

These symbols should be used as offsets from the Dbase of
the p-table. For example, if the p- table base address was
placed in R2, then the vector field could be referenced as
'"HPSW VECTOR (R2)'.

Refer

P-Tables from a Diagnostic

Section

Program.

3.2.4, Referencing

4-272

VDS

MACROS

SYMBOL

DEFINITION

MACROS

$DS_PARDEF
The $DS%PARDEF macro defines (for MACRO-32
names

and

for

"exword"

BLISS-32

first

wvalues

can

©parameters

programs,

issuing

Symbols

that

the

defined

used

with

the

$DS

these

symbols

$DS PARDEF

macro.

are:

PARS$ BIN

PAR$

DEC

PARS_HEX
PARS OCT
PARS NO

PARS YES
PARSV_NODEF

PARSM

PARSV ATLO

PARSM ATLO

PARSV ATHI

PARSV_ATDEF

NODEF

PARSM ATHI

PARSM ATDEF

4-273

may

the

programs)

"radix,"

ASKxxxx

symbolic

"defalt,"

macros.
For
referenced without

- SYMBOL DEFINITION MACROS
VDS MACROS

$DS_PTDDEF

The $DS PTDDEF macro defines (for MACRO-32 programs)

names

for

the

flags

associated

with

symbolic

the $DS_SNAME p-table

descriptor macro. For BLISS-32 programs, these symbols may
referenced without first issuing the $DS PTDDEF macro.
Symbols defined

are:

PTDSV_UNIT
PTDSV CONTROLLER
PTDSV_NAME

PTD$M_UNIT
PTDSM CONTROLLER
PTDSM_NAME

PRE
PTD$V_INHERIT
PTD$V_INHERIT_CON

PTD$M INHERIT PRE
PTD$SM INHERIT CON
PTDSM_INHERIT
PTD$SM_DEVICE
PTDSV_ENDDEVICE

4-274

VDS

MACROS

SYMBOL

DEFINITION

MACROS

$DS_PSLDEF
The’$DS_PSLDEF macro

defines

(for

MACRO-32

programs)

names
for fields of the process status longword.
programs, these symbols may be referenced without
the

$SDS_ PSLDEF macro.

Symbdls'defined are:
PSLS$V_CBIT
PSL$V_VBIT
PSLSV_ZBIT

PSL$V NBIT
PSLSK

KERNAL

PSLSK

SUPER

PSL$M CBIT
PSL$M VBIT
PSLSM ZBIT

PSL$M NBIT

PSLSK EXEC

PSL$K USER

4-275

symbolic

For BLISS-32
first issuing

VDS

MACROS

- SYMBOL DEFINITION MACROS

$DS_SCBDEF
symbolic
The $DS SCBDEF macro defines (for MACRO- 32 programs)
For
block.
control
system
the
in
names Ffor the vector offsets
without
referenced
be
BLISS-32 programs, these symbols may
first issuing

defined

are:

SCBSL ZERO
SCBSL_MACHCK

SCBSL KNLSTK
SCB$L_POWER

'SCB$L_OPCDEC

SCBSL_OPCCUS

SCBSL ROPRAND
SCB$L_ RADRMOD
SCBSL ACCESS

SCBSL TRANSL
SCBSL TBIT

SCBSL BREAK
SCB$SL COMPAT
SCB$L ARITH
SCB$L_CHMK

SCB$L CHME

SCBSL CHMS

SCBSL_CHMU

SCBSL SFTLVL1
SCBSL SFTLVL2
SCB$SL SFTLVL3

SCBSL SFTLVL4
SCB$L SFTLVL5
SCB$SL SFTLVLG

SCBSL SFTLVL7
SCB$L SFTLVLS
SCB$SL SFTLVLO

SCBSL SFTLVL1@

SCBSL SFTLVLI11
SCBSL SFTLVL12

SCBSL SFTLVL13

SCB$L

SFTLVL14

SCBSL SFTLVL15
SCBSL TIMER

Symbols

the $DS_SCBDEF macro.

4-276

vDS

MACROS

-- SYMBOL

DEFINITION

MACROS

$DS_DEFDEL
The

$DS

_DEFDEL macro

program assembly

time.

cause

memory

space

used

conserve

Some of

allocated.

the

memory

symbol
the

space

during

definition macros

$DS

DEFDEL

macro

issued
AFTER
the
symbol
space allocated during the

definition
macros, then any memory
symbol
defintion
process
will
be

deallocated.

not

This

will

themselves.

4-277

affect

the

symbol

definitions

CHAPTER 5
CREATING A VDS DIAGNOSTIC PROGRAM

5.1
The

INTRODUCTION
previous

chapters

have

contruct
a
diagnostic
Diagnostic Supervisor.
to

create

a VDS

diagnostic

to
1its
completion.
conventions to which

5.2

PROGRAM

5.2.1

presented

the

building

blocks

program,

from

the program's

inception

It also
specifies
all
standards
diagnostic program must adhere.

DEVELOPMENT

and

PROCESS

Overview

Creating

diagnostic

program

involves

Several

distinct,

consecutive
phases.
Each phase is required, and the
be entered in same order that they are described here.

5.2.2

Consultation

phases

must

Phase

TM~ .

needed

program
that
will execute under the VAX
This chapter describes the steps required

The

consultation phase

gathering
product

and

for

phase
group

has

Goals

which

should

made a
this
(what

identify

staffing

and

The

the

begin

product

the

key

<consultation

programming

the

and

engineering

develop

the

informal
hardware

written.

product

This

management

new product.

project

phase

the

begins

(dates),

and

before

staffing

Typically,

the

estimate

and

funding

result

of this

include

management
and
senior
englneerlng group or product line

future

program's

manufacturing

group.

milestones

requirements.

been negotiated.
project plan.

will

from

product,

after

relating
to

phase are to formulate a testing
strateqgy
for
the
types of diagnostic programs should be developed),

commitments
have
phase is a cursory

service

information

diagnostic program

soon

funding

Participants

commitment

few

personnel

of program development consists of

exchanging

user

community

personnel),

and

technical
developing

(generally
the

field

diagnostic

CREATING

An
a

important note:
new product
to

VDS

DIAGNOSTIC

PROGRAM

If it is desirable for the
provide
aids
that
will

detection of a diagnostic program,
group
must
request
these
aids

hardware
enhance

design
of
the fault

then the diagnostic programming
as soon as possible in order to

ensure that they will be
incorporated
into
the
device's
final
to aid diagnosis should
for design changes
Negotiations
design.
thus commence during this phase of the project.

5.2.3

Phase

Planning

This phase begins after staffing and fuhding commitments have been

made.
This
and
all
following
phases are
diagnostic program's project leader and his or
The
goal
of
implementation

the
of

planning
phase
1is
to
develop
a
the project.
This project plan will

description of the diagnostic program
and
goals, schedules, development requirements,
and

maintenance

performed
her staff.

requirements.

the

plan
for
include a

will
specify
project
training requirements,

The result of this phase is a Diagnostic Engineering Project'
adhering

Software

5.2.4

the

format

Development

Functional

specified

Policies

and

Specification

Section

Procedures.

goal

this

phase

Plan

of the

Phase

After the project plan has been completed,
the functional operation of the diagnostic
The

7C3-1.A

clearly define

the
task
of
defining
program begins.
the

functions

that

the

diagnostic
©program will perform.
A functional specification must
answer the question, "What will the program do?".
(On
the
other
" hand, it should NOT approach the question of HOW the function will
be

implemented.)

Additionally, a functional

specification

statements about the program's intended
regarding the program's performance and

will

uses and
run-time

include

specific

users, plus
parameters.

goals

The result of the functional specification phase is
a
Diagnostic
Engineering
Functional
Specification
that adheres
to the format
specified by Section 7C3-2.A of the
Software Development Policies

and

Procedures.

CREATING

5.2.5

Design

The

program's
specification

VDS

DIAGNOSTIC

Phase
design

phase

has

may

be
entered
completed.

been

The

goal of the design phase
that
defines
the
methods
functionality defined in the

answers

the

question,

Some

the
to

methods

the

Detailed

Interface

HIPO

OStructured
Program

5.2.6

may

will

describe

used

specify

The

coding

the

algorithm

designs

are:

blocks

Language

adhering

be a

the

Development

(PDL1l)

Policies

Implementation

and

debugging

below.)

Diagnostic

format

PDLT.

(See

specified

and

Engineering
in

Design

Section

Procedures.

7C3-3.A

This

docu-

Phase

After
the
design
has been
completely
implemented.
Design. implementation
1is,

which

functionality

charts

this phase will

describes

Design

program's

flowcharts

Design

Software

also

the

test.

specification

the

that

functional

functional
description
states
certain section of the device's

specification

hierarchy

result of

ment

will

if
the
test
a

the

diagrams

Specification,

design

perform

WwWwN

The

then
used

when

is to develop a design
specification
that
will
be
used to implement the
functional specification.
This phase

"How

provided?".
For example,
that
the
program
will

logic,

PROGRAM

take

specified,
of course,

it
the

may
phase

be
in

place.

schedule on which coding and debugging of the
various
pieces
of
the
program is based depends greatly upon the avallability of
product hardware.
Programs that are written for new hardware
are
typically
in
the
©process
of
development concurrently with the
hardware itself.
Therefore it is important to create
a
schedule
for
program
development
that matches the hardware development's
schedule.
-

CREATING A VDS DIAGNOSTIC PROGRAM

Implementation of programs for new hardware must often be <carried
These stages are referred to as "prototype
out in two stages.
support” and "final product support.”

Prototype

involves

support

providing

the

group

engineering

responsible for the product with a preliminary version of the
program. This version will be used to help verify the integrity

The engineering group will generally
of the hardware design.
for use within a matter of days
ready
expect this version to be
after the hardware is "powered up" for the first time. Specific
requirements for prototype support depend on the particular
These requirements should be specified in the Project
product.
Plan and Functional

Specification.

Unfortunately, it may be necessary to

provide

prototype

support

before the planning and specification phases just described have
carefully
to
important
it 1is
Therefore,
been completed.
coordinate all phases of program development so that the needs of

~all users can be met on schedule.

For example, some

portions

the design specification or even the functional specification may
the prototype
have to be delayed until debugged code supporting
hardware has been provided.

Final product support involves development of the program that
will be used with the final, error-free version of the hardware

product.

This is the version of the program that will be released

for general wuse. User requirements for the final product may be
different from user requirements for prototype support. Knowledge
of

the

hardware's

that was gleaned by the programmer

operation

during development of prototype support will, of course, aid him
or her 1in creating a program that provides high degrees of fault
detection and

isolation.

Because hardware development and diagnostic program development
occur concurrently for new hardware products, it is necessary to

Hardware
carefully coordinate the two development processes.
desire
often
will
l
personne
uring
manufact
and
s
design engineer
d
schedule
the
before
program
ic
diagnost
the
of
working versions
to
ers
programm
ic
diagnost
for
common
thus
is
It
date.
completion
provide "prerelease" versions of the program before the final
program

provide the full
program.

A prereleased program may or may not
functionality that will exist 1in the final

has been completed.

CREATING

5.2.7
Once

Design
the

VDS

Verification

final

program

DIAGNOSTIC

Phase

has

been

operation must be assessed to
the functionality goals that
adheres
macros

all

applicable

properly).

following

completed,

overall

steps

its

functionality

standards

program

1indicated

1in

(such

quality

diagnostic

described
the
1n

every

program.

large

measure

all

same
the

the

required

Since

all

and
VDS

5.3.1
The

1into

will

aid

consistency

module"

Header

header

used

Quality

optional

components
programs

program

from

one

should

one

source

"test

to
the

maintainers

program

are

arrange
these
source code of
by

the

ensuring

next.

compohents should

modules.

There

modules."

should

be
a

Module

module

globally

series

and

initialization,
module

5.10,

diagnostic

components, it
1is
wuseful
same
order
and format in

This

program.

In all diagnostic program sources, program

divided
"header

VDS

performed

STRUCTURE

Chapter

made up of
components

using

of
it

—

PROGRAM

VDS

as
is

Section

Assurance.

5.3

and

ensure that the program meets all
were
originally
set
and
that

operating

Assuring

the

PROGRAM

contains

<cleanup,

the

arranged

all

and

summary

diagnostic

the

tables

program.

the

used

routines,

following

the

plus

Components

VDS,

any
of

the

order:

Module»cover page (copyright statement, title and

maintenance

history)

Functional

description

Declarations of

header

author,

of module

libraries and BLISS require

files

@ User-defined macro definitions
e

Symbol

Diagnostic header ($DS_HEADER)

Dispatch

definitions

Statistics table

Section

table

($DS_DISPATCH)

($DS_BGNSTAT,

names declaration

$DS ENDSTAT)

(SDS_SECTION)

the

routines

(optional)

Device mnemonics

PROGRAM

DIAGNOSTIC

VDS

CREATING A

list

($DS DEVTYP)

o‘ ASCII text:
-

and

bit names

—

Other

ASCII

Error

message

for

$DS_CVTREG calls

strings
strings

Initialization code

($DS_BGNINIT,

Cleanup code

Summary routine

($DS BGNSUMMARY,

Error

routines

($DS BGNCLEAN,

reporting

$DS_ENDINIT)

S$SDS ENDCLEAN)

$DS ENDSUMMARY)

($DS_BGNMESSAGE,

@ Other (optional) global subroutines,
service

Note:

they

should

routines,

condition

handlers,

incldding

and

program has many global

routines and

module.

placed

separate

$DS ENDMESSAGE)

data

on.

interrupt

structures,

CREATING

5.3.2
Each

Test
test

tests

Each

VDS

DIAGNOSTIC

module

will

contain

the

number

and

module

Module

should

cover

page

one
of

tests.

tests

per

module

formatted

(copyright

maintenance

history)

Functional

description

Declarations

User-defined

macro

Symbol

Section

For each test in module:

library

names

statement,

Test

name

$DS_BGNTEST

—

Test

For

require

files

definitions

(SDS SECDEF)

($DS_SBTTL)

header

each

(optional)

Subtest

header

$DS_BGNSUB

Subtest code
$DS_ENDSUB

$DS_ENDTEST

title

module

and

declaration

The
are

subtest

number

unrestricted.

follows:

definitions

PROGRAM

Modules

modules

test

test:

and

author,

CREATING A VDS

Module

5.3.3

DIAGNOSTIC

PROGRAM

Templates

files
template
formats,
To help the programmer follow the above
test
a
and
template
module
header
a
is
There
created.
have been
t
ndependen
program-i
the
contains
template
Each
template.
module
in
fills
simply
r
programme
The
component.
program
fields of each
are
These templates
the program-dependent fields of each module.
and
HEADER.B32
and
MACRO-32,
for
TEST.MAR
and
HEADER.MAR
named
The templates are reproduced in Appendixes
2 BLISS-32.
for
TEST.B3
A

and

PROGRAM

5.4

5.4.1

DOCUMENTATION

Introduction

A diagnostic program should be considered to be

made

two

Each of these parts 1is
parts -- the code and the documentation.
Documentation should NEVER be thought of as
of equal importance.
to be hurriedly added at the end of the
the code,
auxiliary to

project, if time permits.

The best documentation is that which is

developed before and during code development.
Diagnostic

purposes:

Users of diagnostic programs probably refer to and depend
than users of any other
on program documentation more
cation of hardware
identifi
because
1is
This
software.
of what
failures requires a very exact understanding
section of
particular
function is being performed by a
are likely
circuitry
hardware
the
of
areas
code and what
1is
It
that function.
to carry out
to be activated
to read the
user
program
the
necessary for
sometimes
being
are
signals
what
see
program's listing files to
activated

1is

within a

the

<case

test or

with

subtest.

any

software

product,

program

maintenance is usually performed by persons other than the
product's author.

otherwise

update

Those who

must

diagnostic

enhance,

program

correct,

depend

the

documentation for understanding of the program's function,
design,

and

implementation.

two

program documentation serves

CREATING

Documentation

These

for

VDS

DIAGNOSTIC

dlagnostlc

programs

are:

PROGRAM

consists of

Source

tests

code

documentation

descriptions

providing

every

test,

the

user can

access

summarize

the

subtest,

code

"Help"

files

command,

that

and

that

instructions

The

Documentation

documentation

program.

The

EVXYZ.DOC.= A

both
RUNOFF
template can

The

Cover

detailed

functional

routine,

with

and
|

the

line

VDS

program's

- HELP

operating

File

file

will

documentation

template

for

distributed

file

the

for

file

will

with

program

documentation

and
non-RUNOFF
formats.
be found in Appendix C.

documentation
o

parts.

A documentation
file
containing
hardware
requirements,
operatlng instructions, and functional descriptions of the
program's

5.4.2

three

contain

the

EVXYZ

file

dlagnostlc

will

reproduction
|

following

called

available

the

information:

page

The cover page contains identification information such as

the
with

program's
copyright

Table

Abstract

name,
release date, and maintainer,
and disclaimer statements.

contents

The abstract
summarizing

document.

1is
a
short
description
of
the
program,
information
found
in
1later sections of the

This section should
identify
hardware will be tested.
It should also
level (level 2R or level 3).

Hardware

This

special
the

which
types
of
state the program

requ1rements

section

program

along

lists

the

execute,

connectors

minimum

hardware

required

plus any

optional

hardware.

other

program.

5-9

special

hardware

for

the

Include

required

CREATING A

PROGRAM

DIAGNOSTIC

VDS

List
the
processor
types with
which
the
program is
s, as
such
NOT make generalized statement
Do
compatible.
"all
VAX
processors,"
since
the
program
may
not
be
on

executable

Software

processors.

future

requirements

List the software required, including
the
VAX
Diagnostic
Supervisor.
Any
auxiliary data files should be included
here.

Prerequisites

This

section

should

list

the

program's

hardcore

requirements, that is, the hardware that must be operating
correctly
properly in order for the diagnostic program to

diagnose
e¢

faults

Operating

the

hardware being

tested.

instructions

In most cases, the
VAX Diagnostic Supervisor User's Guide
should
be
the
only
reference
needed
for
operating
instructions.
-

Options

the

user-defined

program has

should

Event

Flags

special

command

provided

this

instructions

language),
section.

(such as

that

If any user-controllable event flags are used
they should be

program,
@

Program
-

functional

Program

This

Program

The
be

listed.

the

description

overview

programe.
should

using

information

general

The

functional

description

included.

testing

strategy

size

load time and
specified.

auxiliary data

run-time memory requirements
Include
memory
required

files.

should
by
any
|

CREATING

Program
The

run

VDS

execution

time

dynamics

Indicate

how

the

Fault

each

error

Specify

the

fault

resolution

Performance

the

Indicate

how

failure,
Program

program

during

and

device

space

needed.

the
the

(include
percentage)
is capable of.
if

error

and

reporting

failures

program

will

from

handle

unexpected
failures, power

hardware

like.

uses

this

program

was

customer

designed

for,

services,

such

engineering,

whomever.

descriptions

each

test,

include:

functional

The

description

step-by-step

"Debug

aids"

what

should

Very

important

the

test

the
program
at next if the

for

logic

updated,

user
test

about
fails.

tests.

history

the

program

described

here.

the

and

change

hints

the

The

description

program's

time

flow

be looked

Maintenance

Each

its

applications

customers,

For

1listed

resources

buffer

messages,

resulting

and

the

Test

1include

memory

mimimum

hardware

manufacturing,

both

coverage

the

during

exceptions

List

section

provided,

allocates

Include

Include sample
error
routines are used.

1is

detection

Describe

program

mode

program

time.

allocations.
-

QUICK
also.

Run-time

execution

PROGRAM

times

here.
If
a
execution time
=

DIAGNOSTIC

the

must

version

update

include

number.

the

must
date

be
of

CREATING A

5.4,3

VDS

DIAGNOSTIC

PROGRAM

Source Code Documentation

5.4.3.1
D1agnost1c Codes - Each dlagnostlc
program
released
by
DIGITAL
1is
assigned a "diagnostic code" that uniquely identifies
Codes for VAX diagnostic programs consist of five characters,
it.
by the Release
1is "E." The code is assigned
which
of
first
the
Engineering

group.

the
having
diagnostic program
the
5.4.3.2 Module Names - For
named
be
should
module
header
the
code "EVXYZ,
diagnostic
a
1is
EVXYZ@.MAR if it is a MACRO-32 program, or EVXYZ@.B32 if it
BLISS-32 program.
Test modules
should be named
.B32), EVXYZ2.MAR (or .B32), and so on.

EVXYZ1l.MAR

page.

cover
Module Cover Page - Each module must have a
5.4.3.3
The cover page will include:
|
|
l.

Module

and

program

names,

including

version

(or

numbers

(see

above)
.

Module

Author

statement

abstract

Maintenance history (see

below).

The format of the cover page is illustrated in the header module
template

example contained

in Appendix

5.4.3.3.1
Maintenance History - Each time the module is
updated,
The description must include
must be described here.
update
the
the date of the change and the module's version number.

5.4.3.4

Test and Subtest Prefaces - Each test

contain

the

possess

must

Test

preface.

following

Prefaces

for

and

tests and

each

subtest

subtests must

information:

description

This will contain a detailed description of WHAT is
tested

and

HOW the

test

5-12

implemented.

beilng
|

CREATING

List

assumptions

the

Test

PROGRAM

being

made

hardware

are

good,

about

the

state

the

1is executed.
For example, if
properly unless certain
parts

list

those

parts.

steps

list
this

the test
purpose.

steps.

A pseudolanguage
«
|

1is

errors

Errors

Provide
this
5.

DIAGNOSTIC

before
the
test
will not function

In this section
very useful for
4,

VDS

Assumptions

hardware
this test

detailed

description of

all

reported

test.

Debug

This section should
©provide
information
that
might
be
helpful
to someone attempting to determine the cause of a
hardware error.
For example, there might be
a
statement
of
the
form "If error number X is reported, then Y might
be

The

format

module

broken."

test

template

and

subtest

Appendix

prefaces

5-13

illustrated

the

test

CREATING

5.4.3.5
preface.

VDS

DIAGNOSTIC

Subroutine
Preface - Each
Subroutine
prefaces

PROGRAM

subroutine
must
possess
a
must
contain
the
following

information:
Functional

description

This must be a DETAILED déscription of WHAT function
routine

performs

and

does

and

HOW

the

called,

#4,ROUTINE

CALLG

function

the

performed.

Calling sequence
Indicate

how

the

routine

CALLS
or

BSBW

Entered

for

example:

ARGPTR,ROUTINE

ROUTINE

via

exception

vector

Inputs

List

here all input parameters that are explicitly
passed
to
the
routine.
Explicitly passed input parameters are
those pushed onto the stack before a
routine
1is
called.
(In BLISS-32, explicit input parameters are those that are
listed in parentheses after the routine name.)
Implicit

inputs

List here all input parameters
that
passed
on the stack.
This list will

referenced
routine

the

and

parameters

passed

Note:

Use

routine

not

but

not

passed

implicit

defined

locally

explicitly.

registers
inputs

They
adversely affect
transportability.

are
not
explicitly
include ANY variable

are

implicit

should

program

For

kept

1in

the

example,

inputs.
to

maintainability

minimum.

and

routine

Outputs

List

all

the

parameters

that

are:

Loaded

onto

the

locations

Loaded

into

passed

that

Explicitly

the

stack

routine.

those

output

caller.

are

passed

the

whose

explicitly

output

routine,
addresses

passed

parameters

back

are

or
were

explicitly

CREATING

VDS

DIAGNOSTIC

PROGRAM

Implicit outputs
List

all

the
that

caller.
Implicit output parameters are ANY variables
are modified by the routine but were
not
explicitly

output

parameters

that

are

implicitly

passed

to the routine.
For example, if
register is updated, that
variable

returned

variable stored
1is
an
implicit

should

program

maintainability

could
passes

be
returned
by
along completion

output.

Note:

Use

minimum.
and

implicit

They

routine

Completion

outputs

adversely

affect

kept

transportability.

codes

Indicate all completion codes that
this
routine.
If
the
routine
codes

received

must
code

also
be
1s passed.

from

subordinate

1listed.
(Placing

subroutines,

these

codes

Also indicate how the completion
the code in
R@#
1is
the
normal

method.)

Side

effects

List here any actions taken
affect
the
operation
of

initializing

global
Also,

or
®

data

this
routine
other
routines.

structures

altering

that
could
Examples are

the

state

flags.
if

the

routine

indeterminate

Registers
Identify

places

state,

the

indicate

hardware

that

some

unusual

here.

used
the

purpose

each

general

purpose

by
the
routine,
so
anyone reading the code
determine
the functions of the registers.

used

can

quickly

the

header

The format of a routine

module

template

preface

Appendix

1illustrated

CREATING A VDS

5.4.3.6
source

DIAGNOSTIC

PROGRAM

Source Code Comments - It is extremely important that
code
be
very
accurately commented.
Comments within

source code can take three
"group comments," or "line

forms;
they may be
comments."

5.4.3.6.1
Block Comments - Block
major functions within
a routine.

"block

comments,"”

comments are
used
to
1identify
They have the following format:

MACRO-32

<skip>
; ++

;

This

is a

;

and

extends

block comment.
fully

It begins at

across

the

the left-hand margin

page.

<skip>

BLISS-32

<skip>
|

1++

This

is a

and

extends

<skip>

block

comment.

fully

across

It begins at
the

the
the

page.

the

left-hand

margin

CREATING

VDS

DIAGNOSTIC

PROGRAM

5.4.3.6.2
Group Comments - Group comments are used within
blocks
of
code
delimited
by block comments.
The are useful when it is
desirable to make a comment
have the following format:

stand

out

the

page.

Group comments

This is a group comment.
the

code

being

commented,

and

is indented
extends

the same amount as

fully

across

the

page.

MACRO-32

BLISS-32

This

the

is a group comment.
code being commented,

Group comments should be
BLISS-32

(below)

programs

used

illustration of

follows:

® & o

used

group

extensively

comments

instead

BLISS-32

the

line

programs.

comments

by MACRO-32 programs.

Explain

use

It is indented the same amount as
and extends fully across the page.

what

THEN

the

use of group comments

IF-THEN-ELSE

statement

in BLISS-32

will

code

do.

® @& o o

ELSE

BEGIN

Explain

what

the

REPEAT-UNTIL

loop will

do.

REPEAT

UNTIL

...

;

END;

See

the example

comments

the

MACRO-32

next section for

code.

illustration

group
|

CREATING

5.4.3.6.3
the
end

VDS

Line Comments of,
and
on the

BLISS-=32

statement.

MACRO-32

programs,

followed

line

Line
same

These
and

DIAGNOSTIC

PROGRAM

comments
line as,

comments
EVERY

are those that appear
a MACRO-32 instruction

are

MACRO-32

most

are

blocks

describe

they

Group

unnecessary.

in
be

comment.

self-documenting
(if

comments

important
instruction
should

extremely

are

In BLISS-32
programs,
line
generally
comments
are
because
group
comments
are preferable.
Since lines

code

what

Line
comments
(and
group
following MACRO-32 example:

are

will

occur

should

within

each

placed

block.

illustrated

are

line
before

the

Clear

the

data

buffers.

WAGOOD_DATA[R6]
WTM BAD DATA[R6]

#16,

R6,

158

longword

good

longword

bad

pointer

and

branch

buffer

cleared

data

buffer

Increment
UNTIL

and

received

and

bad

not match,

store

entire

data,

one

the

expected

data

buffer,

longword

and

data
data

received

respectively,

buffer
buffer

back

time.

they

data
data

in
in

values

the
can

8 (AP),

MOVL

12 (AP),

CLRL

4 (AP),

MOVL

W|MO

MOVL

later.

good

printed

expected

pointer

Clear

WO
WMo

they do

TMMo

Compare

buffer

Clear

AOBLSS

REPEAT

W|MP

CLRLCLRL

Clear

CLRL
15S:

TMM

comments)

properly),

written

comments

not
used,
BLISS-32
o

Put
Put
Put

byte count
address of
address of

Clear
Clear

in R2.
received
expected
error count.

buffer

pointer.

R3.
R4.

CREATING

This

example
l.
2.

VDS

illustrates

Every

MACRO-32

useful

where

DIAGNOSTIC

several

concepts:

instruction

indicate

applicable.

example.

IF-THEN-ELSE,

on,

flagged

keywords

comment.

structured

the

Capitalize

has

Notice

can

PROGRAM

the

programming

REPEAT-UNTIL

WHILE-DO,

similarly,

and

CASE

constructs,

enhancing

indent

constructs

construct

and

readability.

comments

within

construct.

Comments provide
comment in

useful
information.
For
example,
the
the example says, "Clear buffer pointer.”

last
It

does

anyone

5.4.4

Help

5.4.4.1

NOT

say

reading

"Clear

the

R5,"

which

code.

would

useless

Files

Description

Help

Files

- A

"help

file"

text

file

that is referenced when the VDS HELP command is used.
Text within
the file is displayed to the user.
Arguments specified
with
the
HELP

command

are

display.
A

help

file

reference

must

EVXYZ,

the

this

file

purpose

program

determine

which

portions

the

text

program

The

used

user

help

unique

file

include:

for

file

typing

diagnostic

with

program's

will

provided

quick

'HELP

A program abstract

ATTACH

procedures

5-19

diagnostic
named

program.

EVXYZ.HLP.

For

user

can

EVXYZ'.

program's

reference

characteristics.

every

must

help

file

source

that

will

Information

provide

the

summarize

the

contained

a help

CREATING

A VDS

DIAGNOSTIC

PROGRAM

program

each

A list containing the name and function

(devices
Descriptions of devices not supported by the VDS
for
which
p-table
descriptors
reside in the diagnostic

section

program

instead

containing

the VDS)

the

number

and

use

ahy

user-

A 1list

A description of the program's "quick mode" operation

Descriptions of tests requiring manual

The format of the prbgram‘s-summary message, if one exists

5.4.4.2

selectable event flags

referenced by the program

Creating Help Files - Help files

intervention

consist

"keywords"

Keywords are used by the VDS to locate the
text.
associated
and
typed
user
a
1f
instance,
For
display.
to
text
proper
named
file
help
the
search
would
VDS
the
SECTIONS,
HELP EVXYZ
text
the
display
and then
EVXYZ.HLP for the keyword "sections,"
referred
keywords,
of
types
two
are
There
keyword.
that
following
to as "numbered keywords" and "qualifier keywords."

preceded
1is
5.4.4.2.1 Numbered keywords - Each numbered keyword
keyword's
the
indicates
number
This
5.
through
1
from
a number
by
"level." Level 1 is the highest level, and is used to indicate the
Keywords with larger numbers are considered
topics.
file's main
file
the
If
numbers.
smaller
with
those
of
to be subtopics
a level 1 keyword followed by several level 2 keywords,
contains
keywords
2
1level
the
followed by another level 1 keyword, then
of the
subtopics
are
keywords
1
level
second
between the first and
followed
was
keyword
1
level
second
the
If
keyword.
1
first level
2 keywords, they are subtopics of the
level
of
set
another
by
second

level

keyword.

There
The level number must be the first character of a new line.
and
number
level
the
between
tabs
or
spaces
more
or
one
be
must
the

keyword.

text
When the user types a HELP command, the VDS will display the
the
display
also
will
It
keyword.
specified
the
following
subtopics
level
next-lowest
the
of
text)
keywords (but not the
For example,
keyword.
specified
the
with
associated
following:
the
of
consisted
file
help
portion of a

suppose a

CREATING

VDS

DIAGNOSTIC

PROGRAM

SECTIONS
Program

EVXYZ

|
contains

the

following

sections.

Type

HELP EVXYZ SECTIONS section-name

- for details on a particuldr section.

DEFAULT

(Text
2

describing

DEFAULT

section.)

MANUAL

(Text
2

describing

MANUAL

section.)

READ TESTS
(Text

describing

WRITE
(Text

READ TESTS

section.)

TESTS

describing

WRITE

TESTS section.)

'HELP

EVXYZ

1 ATTACH

the

user

typed

SECTIONS',

the

following

displayed:

SECTIONS
Program

EVXYZ

contains

HELP EVXYZ
for

details

the

SECTIONS

following

sections.

section-name’

particular

section.

Additional information available:
DEFAULT

MANUAL

READ

TESTS

WRITE

TESTS

Type

would

CREATING A

DIAGNOSTIC

VDS

PROGRAM

VDS
the
HELP command,
a
with
specified
is
Any time a topic
the
1lists
and
topic
the
with
associated
text
the
displays
with
associated
number)
level
subtopics (keywords with next higher
topic.

the

All of the subtopics of a topic are listed directly underneath thé
topic in the help file.

Thus all the level 3 subtopics associated

with a level 2 keyword would directly follow that level 2 keyword.
Thus

in the above example,

SECTIONS DEFAULT'.

suppose

the

user

The VDS would display the

typed,

'HELP

EVXYZ

text associated with

3
level
any
1ist
the level 2 keyword "default," and then would
file
help
sample
(The
keywords that follow the text for "default."

above does not associate any level

3 keywords with "default.")

diagnostic
a
Qualifier keywords - It is unlikely that
5.4.4.2.2
since they
keywords,
qualifier
will require
file
help
program's
not
are
They
qualifiers.
are only used to indicate command line
"/"
the
with
begin
they
instead,
number;
1level
by a
preceded
with
associated
implicitly
is
number
level
However, a
character.
that number is one greater than the number
keyword;
qualifier
a
That
keyword.
specified in the most recently specified numbered
the
1in
illustrated
1s
This
'Qualifiers'.
be
should
keyword
following

example:

1 START

Execute

previously

loaded

image.

Format:

START
2

[qualifiers]

Qualifiers

/SECTION:section—-name
Select a program section
/TEST:first:1last

Select a

range of tests

to be

|
executed.

to be executed.

CREATING A VDS DIAGNOSTIC PROGRAM
The '/' character must be the first character of a new line.
The
keyword
must
immediately
follow the '/'.
Immediately following
the
Kkeyword
there
"/QUAL:string."

may

additional

string,

Note:
If one qualifier keyword directly follows another, with
no
text in between, then the second qualifier keyword will be treated

part

the

form

the

5.4.4.2.3
which
of the

with

1level

associated

beyond

not

should

the

"/NOqual."

exceed

the

useful

the

keywords

should

not

keywords

other

68.

The

length

text

the

must

assocliated

text:

ATTACH

DEVICE

Describe

1list

display

the

files
the

the

extend

with

level

easily

screen

line
Text

column

should

not

readable
if

(no

scrolling

create

Help

files

for

1level

set
the

procedures

ATTACH

proper

links

for

diagnostic
keywords

the

from

the

that
unit

keyword,

the

devices

diagnostic
similar to
from

are
under

processor.

keyword,

the

provide

text

device-type
for
For

and

program.

commands

include a level 2
diagnostic program.

either

the

keyword

for

Under

each

following:

For devices with p-table descriptors contained in
VDS,

beyond

following

attach

the

- Under this
device tested

level
2

help

1is,
to

every

contain

necessary

test

keyword

Contents

That

qualifiers

a new line.
Each
the left margin.

any

for

occur).

5.4.4.3

This

with

column

programs

first.

Text - Text must immediately follow

Text

extend

does

for

and

it
1is associated.
It must start on
text must be indented one space from

associated

65.

text

"/qual"

typing

should

device

with

"HELP

descriptors

provide
a
description

DEVICE

5-23

"Type

HELP

the

DEVICE

description.”

p-table

program,
the device

state,

contained

device
that

device-type."

the

description
is
obtained

CREATING A

the program and describe

HELP -

This

PROGRAM

text

their

should

function.

contain

of
abstract

the

when

the

with the HELP keyword is
associated
text
The
program.
displayed when a user types 'HELP EVXYZ' without including
In other words, this is the default keyword.
a keyword.
QUICK - Describe the operation of
is

flag

the

program

set.

program.
OSECTIONS - List and describe each section of the
MANUAL
a
If
section.
DEFAULT
the
include
to
sure
Be
be
must
that
actions
the
deta11
section exists, clearly
performed

DIAGNOSTIC

EVENT - List any user-selectable event flags referenced by

QUICK

VDS

the

user.

routine.

Other keywords
The above keywords must appear in every help file.
program
unique
on
information
provide
to
added
be
should
|
characteristics.

The keywords must be placed in
order.

help file

alphabetical

1in

A sample help file is provided

5.5

the

in Appendix D.

RUN-TIME ENVIRONMENT CONSIDERATIONS

as
Supervisor,
VAX Diagnostic
the
One of the main purposes of
2, is to insulate the diagnostic program from
in Chapter
stated
diagnostic
for
that exist
environments
runtime
the wvarious

programs.

Thus if all of the rules, guidelines, and conventions described

this manual are followed, any diagnostic program written should be
under
run-time environments
the
capable of executing in any of
which diagnostic programs are expected

run.

Possible run-time environments for VDS diagnostic programs include
User

to):

mode

Standalone

W
N =

are not limited

(but

mode

Automated Product Test (APT)
Remote Diagnosis (APT/RD)

CREATING

‘For
in

VDS

DIAGNOSTIC

PROGRAM

details on any of these environments beyond what
1is
provided
this manual, contact the 32-Bit Systems Diagnostic Engineering

Group,

‘5.6
For

who

can

provided

CUSTOMER-RUNNABLE
both

system

the

DIAGNOSTICS

standalone

has

been

documents.

mode

and

developed

(CRD)

the

wuser

mode

environments,

and

automatically
run
diagnostic
programs.
This
referred
to as Customer-Runnable Diagnostics (CRD).

the

following

modes

"Auto mode,"
which
that
executed.

user's

in which
cause
a

This

"Menu mode,"

mode

environment.

provided

the

devices.

only

mode

can type one
diagnostic

programs

which allows

specific

CRD

user

set

the user
set of

mode

environments.

will

user

the

command (TEST)
programs to be

completely

select

standalone

1is provided

test

the

(by menu)

the

mode

in both the

run-time

standalone

Diagnostic

programs

that

may

certain

constraints placed

have

may

1lnclude

limitations

are
to be

maximum

executed

under

them.

execution

the

CRD

These

time,

system

constraints

prohibition

the
wuse
of any manual intervention (see Section 5.7.5), or
run—-time conditions.
Constraints placed on programs running
the

CRD system

Requirements

CRD

system

5.7

obey

Error Message

stated

the
They
The

must

described

CRD.

Any

the

in Chapter

$SDS_ERRxxxx

rules

should

set

document

called

that

will

forth

that

VAX

Diagnostic

executed

under

the

document.

adhere

the

first

the

VDS.

the

with
the
services

consist

1invoking

three

levels.

formats.

message

second

programmer.

contructed
SDS_ERRxxxx

Error messages

standard

formats

error messages are displayed

services.

format

the

Formats

controlled
The

program

other
under

CODING CONVENTIONS

5.7.1

are

for

and

1level

third

These

(the

message

parts

error
and

reporting
delimited

$DS_ENDMESSAGE macros.

message

levels

the

are

error

routines
by
$DS

and

system
is
CRD provides

operation:

system.

testing

CRD auto
mode

by which DIGITAL customers can easily

header)

Iis

controlled

message

are

called
by
BGNMESSAGE

the
and

CREATING

VDS

DIAGNOSTIC

When error reporting routines
formatted as follows:

are

PROGRAM

constructed,

messages

should

| Invalid contents of a register:
A message

that

reports

invalid

should
indicate
the
(received) contents,
the

expected

and

the

XOR value

all

values

contents

expected
and an

received

should

contents,
the
actual
exclusive-OR
(XOR)
of

values.

Mnemonics

be displayed.

Indicate

bits

the

set

radix

displayed.

Example:

EXPECTED:

5068 (X)

RECEIVED:

000 (X)

XOR:

5068 (X)

Reporting

data

comparison

;TIE,SAE,RIE,MSE,MAINT,FUNC=READ

errors for

buffers

When data comparison errors are detécted in data
buffers,

the

error

message

should

include:

The
The

base address of the failing
address of the buffer

—

The

size

The
The

number
buffer

the

transfer

device

data transfer

of comparision errors
address and contents of

all

bad

data

Example:

Device

base

address

60010500
(X)

Expected

buffer

address

Received

buffer

address

Transfer
Words in

size
error

PE10 (X)

1010 (X)

:
:

256
4

words

Address:

Expected:

Receilved:

XOR:

PE104
gE110
E1COH
GEL1F 0O

1010
1010
1010
1010

1000
1000
1000
1000

CREATING

there

flrst
®¢

are

VDS

large

DIAGNOSTIC

number

eight.

PROGRAM

errors,

~only

display

the

dumps

When

dumping the contents of a set of registers, list
the
registers
in
order
of
address.
Display
the register
mnemonic, the register's contents
(and radix), and the bit

mnemonic

for

each

set

bit.

Example:
RPCS1

1442703 (0)

RPWC

777710 (0)

RPBA

3@1003 (0)

RPDA

10031 (0)

RPCS2

340233 (0)

;SC,TRE,DVA,RDY,FUNC=WRITECHECK
|

;

TRACK=2, SECTOR=1
;sWCE,OR,UNIT=3

(etc.)

5.7.2
All

Volume Verification

diagnostic

provide

inadvertently
Some

programs

mechanism

disks

that

write

ensure that

onto
a

magnetlc

customer's

media

data

destroyed.

base

must
is

not

provide

that a
portion
of
the
medium
(called
tracks")
is always reserved for diagnostic purposes.
diagnostic program writes only
on
the
maintenance
tracks,
the customer's data base will not be affected.
|
|

"maintenance
If a
then
If
if

a dev1ce belng tested does not prov1de
the diagnostic program does not 1limit

malntenance

itself

malntenance

tracks,
only using

or
the

tracks on a device that does provide
them,
then
the
entire
medium
must
Dbe
protected;
a
method
must
exist
for
verifying that the medium loaded 1n the device under test
may
be
written on.
Thus,

for

devices

diagnostic

programs

that

must

not

check

the

provide

volume

maintenance

tracks,

name

of
a storage medium
before executing any tests that will write
on
that
medium.
By
convention,
media
that
contain
no
stored
data
and hence are
avallable for the wr1t1ng of test patterns by diagnostic
programs
are

named

Volume

code.

"“SCRATCH.

verification

must

take

place

program s

1initialization

CREATING A VDS

DIAGNOSTIC

PROGRAM

The program must read the storage medium's home block to determine
(Refer to the FILES-11 On-Disk
volume name.,
medium's
the
Structure Specification for a description of the home block's
format.)

If the volume name is
testing

may

thus

begin.

"SCRATCH,"

the

the volume name is anything other

medium

may

used

program

the

than "SCRATCH,"

if it is

must ask the user (via the $DS ASKLOGICAL system service)
all

right to use the medium.

Tf the response is

"no"

and

(the

user

to be used), then the program should
the medium
does not wish
RESPONSE MUST BE PROVIDED FOR
DEFAULT
A
call.
ABORT
$SDS
a
issue
AND THE DEFAULT MUST BE "NO." This
$DS_ASKLOGICAL SERVICE,
THE
will ensure that if the OPERATOR flag is cleared and a nonscratch
medium has been mistakenly placed in the unit under test, then the
medium will

not be

used.

first
the
executed
The volume verification code should only be
$DS_BPASS# or
the
(use
code
1initialization
the
through
time
to
Otherwise, the user would have to respond
$DS BNPASS@ macro).
the

$DS ASKLOGICAL question

Note:

for

every program pass.

Previous editions of this guide have indicated

that,

when

asking the user if it is all right to use a nonscratch medium, the
user prompt passed to the $DS ASKLOGICAL service must begin with a
null will force the VDS to check the user
This
character.
null
is
terminal for a response to the question, even if the program
being
is
program
(If the
being run by a command file (script).
run by a command file, all responses are obtained from the command
file, unless the prompt string begins with a null.)

1limitations onto
forces
This is not a good practice, because it
It should be
the user regarding how the program may be executed.

the user's decision whether a question's response is to be fetched
from a script or from the terminal, not the programmer's decision.

Therefore, prompt strings should never be

character.
for

(Refer

Long

with

null

to the VAX Diagnostic Supervisor User's Guide

n command
a descriptioof

5.7.3

preceded

files.)

Silences

A "long silence" is a long period of time in which there is no
|user.
the
and
program
diagnostic
the
between
communication
bad.
are
they
sometimes
and
good
are
silences
long
Sometimes

CREATING
A VDS

DIAGNOSTIC

A long silence is good when a
long
period
of time (either

per

pass

long,

because

selected
terminal.

by
the
wuser)
Long silences

jams

when

one

the other

the

hand,

terminal,

user
long

long

and

eliminate

per

pass,

least

long

once

per

purpose.

user

that

provide

disabling

For

example,

OPERATOR

only

5.7.4

long

the

flag

"Hardware
in
some

AST

should

All

hardware

is the
state

execution,

section)

programs

and

time

and

preparation

the

with
a

been

hardcopy
of
paper

present at

this

case

status
program

user

the

during
is not

can
monitor
STATUS, then

SHOW

capability
long

message

may

both

simple,

the

user

AST

flag is

for

this

indication

properly.

desires

check

times

displayed

used

succinct

routine

should

execution
to

progressing

$SDS BOPER

them,

should
the

means

provided.

status

$DS BNOPER

the

macros)

and

set.

act of setting the device
before
testing
begins.

referred

If
an

written

for

occur

requests

that

cable,

hardware

this is not possible, hardware
absolute
minimum,
since
it

nuisance

should

program

considered

under test
Hardware

switches,
connecting
device, and the like.

should

has to take place.
should be
kept
to

testing

started.

when

the

routine
be

routine
wusing

has
a

Preparation

diagnostic

lengthens

have

cause

preparation
may include
setting
loading a special medium into the
Ideally,

user

progress.

programs

should

silences

preparation"
physical

preparation
preparation

passes

silences.

execution

message

Hardware

must

above-mentioned

(by

the

program's

long

message

program

the

occurs, the only way a
type a control-C, then

silences

minute.

for

number

user's
terminal is
and lessen the risk
-

program

The

the

the
paper

kept abreast of the program's
order
to be assured that the

providing

the

large

silence
is bad when a

silence
1is
to

Thus a diagnostic

eliminating

around.

would like to be
executions
in

"hung."

diagnostic program 1s running for
a
because the program's execution time

and
save

monitoring
the

program
progress
CONTINUE.

PROGRAM

before

hardware

"manual

even

the

program
the

program

preparation

intervention"

user.

(see

nuisance.

Iis

during

CREATING A VDS

DIAGNOSTIC

PROGRAM

If a program detects a preparation error

correctly),

5.7.5

set

not

(hardWare

the '$DS_ERRPREP.service should be used to report the

Manual

Intervention

The term "manual intervention" refers to user actions during
program execution. A program redquiring manual intervention 1s one
requiring the program user to perform a duty at some point during
the program's execution. This duty might be as involved as adding
the system under
of hardware to (or removing one from)
a piece
be a simpler action, such as typing a response
test, or it might
on

the

terminal.

Ideally, no diagnostic
because
intervention,

manual
require
complicates the

should ever
intervention

program
manual

operation of the program from the user's point of view.

1inclusion

intervention

manual

following rules must be followed:

avoided,

cannot be
|

the
|

If the manual intervention involves ANY actions OTHER THAN

to questions at the user terminal, the tests
responding
program
a
1in
placed
that require these actions must be
are
actions
such
of
Examples
section called "MANUAL."
or
<cable,
a
connecting
switch,
setting a write-enable

watching

display

patterns generated by a program that tests video
B

terminals.

Each test within the MANUAL section must use the $DS BOPER

if a user is present.
or $SDS BNOPER macro to determine
call

a user is not present, the test must

service.

the

$DS_ABORT
|

Communication with the user must be performed by using the
$DS ASKxXXX macros.

If SDS_ASKXXXX macros are.inC1uded in the MANUAL

it is not necessary to provide default responses.

section,

If $DS ASKxxxx macros are used anywhere OTHER THAN in
tests within the MANUAL section, default responses MUST be
if the
If default responses are included, and
provided.
clears the OPERATOR flag, then the default responses
user
will automatically be used and the user will not have to
(This is of course true for the DEFAULT
be present.
section, also.)

CREATING-A

5.7.6

Quick

VDS

times.

capability, with
employed
when
a

decision

quick

mode

users.

1little
user

whether

one

Specific

are

also

and

users.

program
execution
in
which
the
relatively fast execution time per
to provide
in
programs
having

should

shared

not

fault
quick

fast

the

program

programmer

particular

mutual

pass/fail

1isolation.
It
verification of

diagnostic

between

functions

decided

provide

or
no
wants
a

integrity.
The

PROGRAM

Mode

"Quick mode" is a mode of
objective is to provide a
It is a convenient
mode
execution

DIAGNOSTIC

will

and

the

program's

agreement

between

main
pass.
1long

testing
will
Dbe
hardware

provide

quick

the

program's
mode

programmer

quick

mode operation is provided, it is to be executed only
1if
wuser
selects
it by setting the VDS control flag QUICK.
The
Program will use the $DS BQUICK or $DS BNQUICK macro to
determine
the state of the QUICK fTag.
|

the

5.7.7
For

the

Naming
sake

Symbols
of

important

symbols.

These

The

consistency

obey

conventions

dollar

defined

certain

sign

symbols

'$'

from

are

symbols

'S'

defined

program,

creating

names

for

included

in all
publicly
and in all other system
by
DIGITAL.
To
differentiate
available only to the program in

the

VDS

defined)
from
public
symbols,
private
not include the '$' character.
Since ALL
in diagnostic programs
are
private,
the

should never be used.

Note:
There
descriptors

signs.
details
2.

when

follows:

character

located

level software
provided
private
symbols
(those

which they
are
symbols
should

program

conventions

is
are

exception

public,

See
Section
and examples.

To determine
the
maximum

their

3.2.3,

written.

for

this

names

rule;

since

p-table

should

include

dollar

P-Table

Descriptors,

for
|

the characters
1length
of
a

reference manual
being

one

the

5-31

allowed
symbol

language

in
a symbol name,
name,
refer
to

which

the

program

and
the

CREATING A VDS DIAGNOSTIC PROGRAM

Global variable names are of the form:
Gt variablename

wvariable

type

(see

where "t" is a letter indicating the wvariable

type

(see

where "t" is a letter indicating the
|

Table 5-1).

Global arrays are of the form:
A arrayname

Structure field names are of the form:
me
ure
t fieldna
struct

Entry points to global routines having

are of

the

nonstandard

~calls

form:

entryname_Rn

where registers RO through Rn are

not

preserved

routine and thus must be saved by the caller.

the

When naming bits and bit fields in hardware registers, use
the bit mnemonics specified in the hardware documentation.

Table 5-1 contains letters uséd-for data types.

5-32

CREATING A VDS DIAGNOSTIC PROGRAM

Table

5-1

Letters

NKXE<CHNIOUWOZECRUHIOWE
UOQE

Letter

Some

Data

Types

Usage

integer
Single character

Double

precision

Reserved

Single

floating

DIGITAL

precision

General

floating

wvalue

Integer value for counters
Reserved for integer extensions

Reserved

Constant
Longword

integer

Field

customers

escape

other

codes

(all byte forms)
DIGITAL
as an escape

other

codes

string

Reserved

Packed

string

Quadword

integer

Reserved

for

Field

records

position

Context

(generic)

dependent

symbol

RPDS

diagnostic

EVXYZ1l,
EVXYZ.

names

the

EVXYZ1l,

EVXYZ2,

and

RPDS

into

of global

array

word

controller

registers'

REG

containing

byte

count

PROGRAM

program

using

(BLISS)

are:

storage array for RPxx

Offset

DIAGNOSTIC

image,"

storage
field reference

nonstandard

- Address

LINK/SYSTEM=512

program

- Address of

LINKING A

"system

(assembler);

|
(generic)

examples

Before

string
|
addressable

Word integer
Context dependent
Unspecified

(structure)

size

Text (character)
Smallest unit of

Field

for

mask

Numeric

GW _BYTE COUNT

where

Indicate

Byte

REG

5.8

Type

Address

A RP REG
RP

Data

Used

released,

command
EVXYZ2,

on,

must

1linked

line:
...

are

the

source

modules

for

PROGRAM

DIAGNOSTIC

CREATING A -VDS

to
If the symbolic debugger for diagnostic programs (VDSDEBUG) is
be used during program development, another linking procedure must
Refer to the VAX Diagnostic Debugger User's GUide for a
be used.
description of

5.9

DEBUGGING A DIAGNOSTIC

that procedure.

PROGRAM

Two facilities are available for.aiding' in
-

programs.

diagnostic

debugging

The VDS command language provides several commands that are useful
Commands are available for examining and
debugging programs.
for
setting
program,
diagnostic
the
within
locations
altering
Refer to
and "single-stepping" through the program.
breakpoints,
the VAX Diagnostic Supervisor User's Guide for details.
VAX Diagnostic
the
by
More debugging capabilities are provided
separate program that can run
a
is
This
(VDSDEBUG).
Debugger
It
diagnostic program.
a
in conjunction with
under the VDS

queue
watchpoints,
breakpoints,
as
features
such
provides
names,
symbolic
their
by
locations
program
referencing
traversal,
contents of program locations as
and depositing
examining
plus
Refer
numeric data, character strings, or MACRO-32 instructions.
and
details
for
Guide
User's
Debugger
Diagnostic
VAX
the
to
operating

instructions.

QUALITY ASSURANCE

5.1
5.10.1

Quality Requirements

All diagnostic

programs

must

meet

certain

standards.

quality

Quality standards must be met in all of the following areas before

a program will be accepted as a usable product:

Documentation quality -

The diagnostic

programmer

must

detailed documentation that gives both
provide accurate,
need
users and maintainers all the information they will
Documentation must adhere to the
their jobs.
perform
to

guidelines spelled out earlier

in this chapter.

the
of
Functional quality - The program must provide all
functional
the
in
contained
capabilities
functional
S
|
|
specification.

Operational ¢quality =

The

program

must

operate

accordance with the rules set forth in this manual.

CREATING

A VDS

5.10.1.1
Documentation
documention that must be
l.

Documentation
the

2.
3.

format

DIAGNOSTIC

Quality - Following
provided with every

file

presented

The
in

Map file - For

program

produced

linker

Listing

file

EVXYZ,

the

assembler

BLISS-32

Within

Section

EVXYZ,

the

EVXYZ.LIS

must

Source

Help

file
format

- A

help file
presented in

5.10.1.3
a

table
be

the

Code

EVXYZ.MAP
For

the

program
MACRO-32

provided.

table

guidelines

For

must

spelled

Documentation,

must

provided.
It
must
5.4.4, Help Files.

Section

Functional Quality - The'progfam developer

that
all
functions
specification have been

file

adhere

cross-reference

listing,

must

out

must

the

5.10.1.2

map

produced

followed.

file

provided.

compiler

the

5.4.3,

cross-reference

file

programs,

included.

is
a
1list
of
the
diagnostic program:

documentation
Appendix

must

including

listing

MACRO-32

the

PROGRAM

described
1in
the
program's
properly inplemented.

must

match

ensure

functional

Operational Quality - To guarahtee'the execution quality

diagnostic

program,

the

following

steps

must

performed:

Load and normal start

’

The following stepé mustAbe performed IN THE ORDER SHOWN:
l.

Load

Issue the proper ATTACH and SELECT ¢ommands.

3.
-

Load

the VDS.

and

commands

start
or

the

The

program

should

one

program

pass.

the
RUN

program

with

the

LOAD

command.

execute

without

and

START

stop

after

errors
|

and

CREATING A VDS DIAGNOSTIC PROGRAM
2.

For EACH SECTION of the program,

the following

should

performed:
Trace

mode

that
Check
Issue the SET TRACE command, then START.
program
with
coincide
messages
trace
and
numbers
test
documentation for the section being executed.
passes

Multiple

Execute the section again, specifying a pass count
at

140.

least

For EACH TEST of the program, the following steps must

performed:

Reverse

order

testing

Execute each test,

highest-numbered
test

Allow each
Multiple

one at a time,

starting

with

the

pass

and ending with test number 1.

test

complete

one

pass.

loop-on-test

Execute each

test
least

1individually,

specifying

10.

count of

Multiple

loop-on-subtest

Execute

each

subtest

each

test

specifying a pass count of at least 14.
Control-C

response

For each test,

response

individually,

start the

the

test and

type

control-C.

control-C should occur within three

type
displayed,
1is
prompt
the VDS
When
seconds.
CONTINUE. The program must continue from where it was
and must successfully complete the pass.
interrupted
Event

flags

Check that all event flags are used only as

1indicated

by the program's documentation.
Power

off

The
test.
under
device
Shut off the power for the
program must display a message stating that the device
is

without

power.

5-36

CREATING

Write

VDS

DIAGNOSTIC

PROGRAM

Protection

Write-protect

the

device

under

test.

Tests

to
the
device should display messages
that device is write-protected.

that

write

indicating

the

Off line
Place

that

the

device

Minimum

hardware

Set

minimum

off-line.

hardware

Set

should

state

configuration
configuration

that

configuration

specified

functional specification.
this configuration.
hardware

program

off-line.

hardware

Maximum

The

All

tests

matches

must

the

1in

the

execute

configuration

hardware

configuration

that

matches

the

max imum
hardware
configuration specified
in
the
functional specification.
All tests must
execute
on
this
configuration, and all units of the device under
test

must

Module

Place

tested.

extender

each

board

logic

module

extender

board,

test

execute

will

one

of
at

the
a

device

time,

and

under

test

verify

that

each

successfully.

Transportability
Repeat

all

processor

the

type

this

section

every

VAX

steps

which

the

program

supposed

has

been

run.

Marginal

testing

the program

successfully
timing, and so

conditions.

Error
-

reporting

Make

sure

specified

under
marginal
on), then execute

and

that

executed

conditions
(voltage,
each test under these

loop-on-error
no

executed
when
the
ABORT will cause the

$DS _ERRxxXxXxX

<cleanup
cleanup

macros
are
ever
code
1is run (Typing
code to be run.)

CREATING
A

Set

the

VDS

LOOP

DIAGNOSTIC

and

HALT

PROGRAM

flags.

Cause

every

reporting
macro
($DS_ERRxxxx)
to
(This
can be
accomplished
either

hardware
failures
on the device under
temporarily patching the program.)

$DS

ERRxxxx

CLEAR

the

IEl,

Make sure that all error messages are printed,
and
that they
are of the proper format (see
Section 5.7.1, Error Message Formats).
sure

that

the

printed before

and

IE3

entire

the

EVERY

IE2,

test

For

Make

macro,

error

be
executed.
by
causing

following:

flags.

message

the DS> prompt

has

been

is displayed.

Clear the IE3 flag.
Type CONTINUE,

and

make

begins executing.-

sure that

loop

TheVSDS_ERRxxxx,macro' should be

third level
this time the
but
message should not be displayed.

When the DS> prompt

feexecuted,

error

the

'appears,f clear

IEZ2

flag.

Type CONTINUE.
The $DS_ERRxxxx macro

but

this

the

error message

10.

Clear

11.

Type

12,

time

the

IE1l

should

and

not be

reexecuted,

third

levels of

displayed.

flag.

CONTINUE.

The $DS ERRxxXX macro

but

should

second

this

time none of

should

reexecuted,

the error message

should

displayed.

13.

Set the IE1l flag and clear the HALT flag.

14.

Type

15.

Allow the loop to

CONTINUE.

execute

several more

times.

CREATING

The following
section.
o
No

VDS

step
-

DIAGNOSTIC

must

PROGRAM

performed
-

for

the

DEFAULT

the

DEFAULT

operator

Clear the OPERATOR

flag,

then

execute

section
for
one
successfully,
and

pass.
the user

The
must

program
not
be

type

any

characters

other

form

The'following
programs

manual

execute

terminal

perform

any

intervention.

additional

that

the

must
execute
required
to-

steps

must

standalone

performed

mode:

for

Memory Management on
Turn

memory management

several passes.
Each
unless the program is
memory

management

should

abort without

Invalid
Using

and

execute

each

test

for

test should execute successfully
not supposed to be executed with

turned

on,

which

errors.

case

the

program

incorrect

device

address

the

ATTACH command,

address.
indicating

The
that

specify

program
an invalid

should
display
address has been

a
message
specified.

APT compatability

To verify that the program will execute under the

APT

run-time

for

eight

The

following

execute
Make

step must

user

run

sure

the

performed

mode:

program

under

for

programs

that

all

|
units

after
the diagnostic
following VDS and VMS

NSNS o

environment,

APT

hours.

ATTACH device-name
SELECT device-name
RUN

program-name

Type

control-C

ABORT

Type

control-Y

SHOW

DEVICE

5-39

that
|

are

program has
commands:

properly

finished.

deallocated

1Issue the

CREATING A VDS DIAGNOSTIC PROGRAM

logging,

error

for

None of the devices that were tested, used

or made use of in any way by the diagnostic

program should be still allocated.

The following steps must be performed

execute

under

for

1in

the

indicated

Issue ATTACH and SELECT commands as indicated

program's "UUT Support Data File"

for CRD.

Clear all VDS flags, then set any flags

Run the program for one pass, specifying

the

UUT Support Data

indicated

File.

in the UUT Support Data File.

the

section

should
pass
one
complete
to
The time required
time specified in the UUT Support Data
the
match
File.

that

programs

CRD:

program

The

should

not

manual

request

intervention.

(as
preparation
incorrect device
Purposely perform
the UUT Support Data File), and run the
in
indicated

program.

describing

The program should display an error

the

message

incorrect preparation.

certain
File specifies
the UUT Support Data
If
should
which
test
under
device
configurations of the

not affect successful execution of the program, set up

The

run the program.
and
configurations
these
successfully.
execute
should
diagnostic program
5.10.2

Automated Quality Assurance

In order to aid the programmer in ascertaining the

quality

diagnostic program, the VDS provdes an automated quality assurance

feature, called "Auto-QA." This feature will automatically perform

some

(but not all)

of the quality assurance checks listed above.

Auto-QA is invoked by including the '/QA' qualifier with
or

START

command .

Operating

instructions

for

the . RUN

Auto-QA

described in the VAX Diagnostic Supervisor User's Guide.

are

performed

manually.

by
Following is a list of the quality assurance checks performed
program
DEFAULT
the
checks
only
Auto-QA
that
Note
Auto-0QA.
Quality assurance of other program sections must be
section.

CREATING

Normal

Start

This check
diagnostic
The

must

appropriate

This

make

error

also

visually

makes

checked

sure

1input

This

equivalent

error-free

pass,

printing

from

that
the

the

user.

the

DS>

CLEAR

SET

FLAG

DS>

RUN

diagnostic-program-name

DS>

CLEAR

This check
passes

and

not

happen,

The

number

can

This

FLAG

sequence

ten passes

The

terminate

the

TRACE

execute

(by

after

the

tenth

pass.

message

will

passes

executed

the

default)

program must make

error

changed
by

check

VDS

ALL

program.

Check

will

the

TRACE

Passes

diagnostic

out

DEFAULT
section
does
(The OPERATOR flag is

following

DS>

Multiple

the

user.

commands:
FLAG

and terminating with End-of-Pass.
execute
an
error-free
pass,
an
message will be printed.
The trace

not
request
cleared.)

check

PROGRAM

a normal load and execution
the TRACE flag set.

messages
does not

must

check

DIAGNOSTIC

Check

trace
program

messages

VDS

will perform
program with

program

normal
If the

ten

error-free

this

does

printed.

diagnostic

program

user.

equivalent

the

following

VDS command:

DS> START/PASS:10

Infinite Loop-On-Test Check
This

check

program's

will

execute

DEFAULT

diagnostic must
times.

error

message

execute

the
will

each

section

each

diagnostic
be

100

test
in
the
diagnostic
times (by default).
The

test
does

the
not

given

execute

the

user.

properly,

printed.

The number of times each test is executed can

number

changed
|

CREATING A VDS

DIAGNOSTIC

PROGRAM

This check is equivalent to the following VDS commands:
DS>

START/PASS:100/TEST:1:1

DS>

START/PASS:100/TEST:n:n

DS> START/PASS:100/TEST:2:2

where "n" is the highest

numbered

The tests are executed

section.

the

test

DEFAULT

in ascending order.

Loop-On-Subtest Check

Infinite

tests
This check will execute each subtest in each of the
the diagnostic program's DEFAULT section 100 times (by
in

The program must loop on each subtest the given

does
program
the
If
times.
of
number
printed.
be
will
message
error
an
properly,
by

the

This check

changed

times

each

subtest 1is

executed

execute

can

user.

equivalent

the

following

commands:

DS> START/PASS:1008/TEST:1:1/SUBTEST:1
DS> START/PASS:100/TEST:1:1/SUBTEST:
2

DS> START/PASS:1@0/TEST:1:1/SUBTEST:ml

DS> START/PASS:100/TEST:2:2/SUBTEST:1
2
DS> START/PASS:100/TEST:2:2/SUBTEST:

DS> START/PASS:100/TEST:2:2/SUBTEST:m2

DS> START/PASS:100/TEST:n:n/SUBTEST:1
2
DS> START/PASS:10@/TEST:n:n/SUBTEST:

DS> START/PASS:100/TEST:n:n/SUBTEST:mx

Supervisor

The number of

not

default).

CREATINGA VDS DIAGNOSTIC PROGRAM
where

"n"

section,

and

the

"mx"

highest-numbered

the

number

test

of subtests

the

test

DEFAULT

"x."

The tests and subtests are executed in ascending order.
5.

Run

Individual

Tests

Reverse

Order

Check

This check executes the tests in the diagnostic
DEFAULT section

reverse

order.

This

check

program's

ensures

a test does not depend on results from
a
previous
and
that
each
test
1is
a
standalone
entity.
diagnostic program does not
execute
properly,
an
message

will

This check

that

test,
If the
error

printed.

equivalent

DS>

START/TEST:n:n

DS>

START/TEST:n-1:n-1

DS>

START/TEST:1:1

the

following VDS command:

where "n" starts at
the
highest
numbered
test
DEFAULT section, and descends to the first test.
the tests are executed in descending order.

1in
That

the
1is,

APPENDIX

APPENDIX A
TEMPLATE FOR THE VDS

DIAGNOSTIC PROGRAM HEADER MODULE

HEADER MODULE TEMPLATE FOR MACRO-32 PROGRAMS

A.l1

This is a template to a1d in the development of the header module
It is not intended to be a tutorial
of a VAX diagnostic program.
for

writing

the program.

Areas that must be deleted

replaced

programmer

the

enclosed between matching sets of triple stars.

Areas

that

matching

sets

may

optionally

of double

deleted.

are

enclosed

between

stars.

Comments marked with one star are
should

modlfled

are

for

information

purposes
,

and

APPENDIX

.TITLE

***

. IDENT

/01/

PROGRAM

.LIST

MEB

.NLIST

- CND

. PSECT

HEADER,

WMy

. DEFAULT

DIGITAL

NAME

LONG,

DISPLACEMENT,

(C)

***

NOWRT

CHANGE

ALIGNMENT

WORD

CHANGE

THIS

1983
CORPORATION,

LONG

PAGE

FOR

DEBUG

|
MASSACHUSETTS

MAYNARD,

DEBUG

01754

ABOVE

MAY

EXCEPT

TERMS.
REMAIN

NOT

NOTICE.

PROVIDED

FOR

USE

TITLE
IN

FURNISHED
UNDER A LICENSE FOR
AND
MAY BE
COPIED ONLY WITH

ON
TO

SUCH
AND

THIS

SOFTWARE,

OTHERWISE
SYSTEM

MADE

AND

OWNERSHIP

WHO

ONLY ON A
INCLUSION

OTHER

AVAILABLE

ONE

THE

ANY

USE
THE
TO

AGREES

SOFTWARE

COPIES
ANY
TO

THEREOF,

OTHER
THESE

SHALL

DEC.

SINGLE
OF THE

PERSON
LICENSE

ALL

TIMES

THE

INFORMATION

THIS

AND

SHOULD

CONSTRUED

Mg
N

THIS SOFTWARE IS
COMPUTER
SYSTEM

EQUIPMENT

CORPORATION.,

SOFTWARE
AS

SUBJECT

COMMITMENT

CHANGE
BY

WITHOUT

DIGITAL

NOTICE

EQUIPMENT

VWO

DEC ASSUMES

NOT

SOFTWARE

RESPONSIBILITY
WHICH

FOR
NOT

THE USE OR

SUPPLIED

RELIABILITY OF

DEC.

FACILITY:

VAX

DIAGNOSTIC.

ABSTRACT:

***

Short

ENVIRONMENT:

VA X DIAGNOSTIC SUPERVISOR.

description

program.

**%*

WMo

ON EQUIPMENT

AUTHOR:

***

MODIFIED BY:

NAME

DATE

***

VERSION

@1.

ITS

APPENDIX

. PAGE

DECLARATIONS

.SBTTL

FILES:

INCLUDE

.LIBRARY

\SYSSLIBRARY:DIAG.MLB\

; VAX FAMILY DIAGNOSTIC LIBRARY.

libraries here.

(Libraries are searched in reverse to the order listed.)

MACROS:

x#** USER MACROS (OPTIONAL). ***
EQUATED

SYMBOLS:

;** Declare programmer-defined

SDS BGNMOD

$DS_DSSDEF

*%% ENVIRONMENT *%%

GLOBAL

;%% USER EQUATED SYMBOLS **%*

;SUPERVISOR SERVICE ENTRY VECTORS

APPENDIX

\
PROGRAM

HEADER

DATA

BLOCK.

-+
-+

FUNCTIONAL

DESCRIPTION:

THE

.SBTTL

ALLOW

PROGRAM

BEGINNING

HEADER

DATA

BLOCK

DIAGNOSTIC

CONTAINS

SUPERVISOR
SUPERVISOR LOOKS

VIRTUAL

ADDRESS

THE

PARAMETERS

TO CONTROL THE
FOR THE HEADER

WHICH

PROGRAM.
INFORMATION

200 (HEX).

VWO

THE

$DS_HEADER

DISPATCH

REV=gl,

UPDATE=@,

NUNIT=*%]*%

TABLE.

THE DISPATCH TABLE IS A COLLECTION OF ADDRESSES GENERATED AT THE
BEGINNING OF EACH TEST AND GROUPED TOGETHER INTO A CONTIGUOUS
LIST BY THE LINKER.
THIS IS DONE BY DEFINING A PSECT CALLED
DISPATCH.

.SBTTL

<***PROGNAME***>,

$DS_DISPATCH

APPENDIX

WM
Mg

DATA,LONG

FUNCTIONAL DESCRIPTION:

* k%

* kX

ALL DYNAMICALLY MODIFIED DATA SHOULD BE PLACED IN THIS SECTION, * %k
THIS IS THE ONLY PSECT WHICH WILL NORMALLY BE WRITE ENABLED.

STATISTICS

TABLE.

“e

PROGRAM GLOBAL DATA SECTION.

.PSECT
++

. PAGE

.SBTTL

$DS_BGNSTAT
$DS_ENDSTAT

;*** OTHER GLOBAL DATA

(OPTIONAL)., **%*

**%*

APPENDIX

. PAGE
TEXT

SECTION.

+
+

PROGRAM

FUNCTIONAL

.SBTTL

DESCRIPTION:

WMo

THIS SECTION CONTAINS ALL OF THE DATA STRUCTURES THAT ARE MADE UP OF
STRINGS.

PROGRAM

SECTION

NAMES.

%Wme

|Ne

CHARACTER

$DS_SECTION

<***

NAMES

DEVICES

*#*#>

*%**)

i+
;

SECTION

DEVICE

MNEMONICS

LIST.

;—

T DEVICE:

<*%*

NAMES

DEVICE

REGISTERS

AND

BIT

MNEMONICS

WTMy

$DS_DEVTYP

NAMES

USE WITH

THE

DEVICE

REGISTERS

$DS_CVTREG

MACRO

AND

THEIR

ROUTINE.,

***

BITS

(OPTIONAL)

FOR

**%

W
W

ASCII

FORMATTED ASCII

OUTPUT

STATEMENTS.

TMy
.

’

We
.

’

MESSAGES

THE

OPERATOR,

ETC.

(OPTIONAL),

**#%

WMe

; ***

STRINGS

USED

REPORT

ERRORS

’

***

ERROR

REPORT MESSAGES.

(OPTIONAL)

*%*%*

APPENDIX

. PAGE
<+
+

INITIALIZATION CODE.

FUNCTIONAL

DESCRIPTION.

THIS
* %k

ROUTINE WILL BE EXECUTED
AT THE BEGINNING OF

DESCRIPTION

YOUR

ROUTINE.

EACH PASS.

*%*%*

CALLING

SEQUENCE:

THE DIAGNOSTIC

SUPERVISOR CALLS THIS ROUTINE WITH A CALLG INSTRUCTION.

INPUT

PARAMETERS:

NONE

IMPLICIT

INPUTS:

*% NONE

OUTPUT

PARAMETERS:

NONE

*%*

IMPLICIT

OUTPUTS:

NONE

COMPLETION

CODES:

NONE

%* %

* %

SIDE

EFFECTS:

NONE

WME

WML

WMy

.SBTTL

$DS_BGNINIT
;***

DEVICE

INITIALIZATION CODE.

$DS_ENDINIT

**#*

APPENDIX

. PAGE

CODE.

+
+

CLEAN-UP

FUNCTIONAL

DESCRIPTION:

THIS ROUTINE IS EXECUTED AT THE COMPLETION OF THE LAST PROGRAM PASS.

kkk

DESCRIPTION

YOUR

ROUTINE,

THE DIAGNOSTIC SUPERVISOR CALLS THIS ROUTINE WITH A CALLG INSTRUCTION.
% %

PARAMETERS:

NONE

IMPLICIT

* %

INPUTS:

NONE

OUTPUT

PARAMETERS:

*% NONE **
IMPLICIT

OUTPUTS:

NONE

COMPLETION

CODES:

* %

SIDE

NONE

* %

EFFECTS:

NONE

NI N

e W W

W WE

WI WY NE

W NI Wy my

INPUT

$DS_BGNCLEAN

#*#*x*

CALLING SEQUENCE:

WMy Mo

Wy TM

.SBTTL

;*** DEVICE "SHUT-DOWN" CODE.
$DS_ENDCLEAN

*#*%

APPENDIX

. PAGE

REPORT CODE.

+
-+

SUMMARY

FUNCTIONAL DESCRIPTION:

THIS ROUTINE ISSUES A SUMMARY REPORT UPON REQUEST
OPERATOR
OR WHEN A $DS_SUMMARY
G CALL IS MADE.
* ok
DESCRIPTION OF YOUR ROUTINE. **%*

FROM

THE

CALLING

SEQUENCE:

THE DIAGNOSTIC SUPERVISOR CALLS THIS ROUTINE WITH A CALLG INSTRUCTION.
INPUT

PARAMETERS:

NONE

IMPLICIT

INPUTS:

*%*

NONE

OUTPUT

PARAMETERS:

NONE

IMPLICIT

OUTPUTS:

NONE

* %

COMPLETION

CODES:

NONE

SIDE

EFFECTS:

NONE

WNe

///"\‘

MNP

.SBTTL

$DS_BGNSUMMARY

; **%* SUMMARY REPORT CODE.
$DS_ENDSUMMARY

(OPTIONAL)

**%

.SBTTL

GLOBAL SUBROUTINES.

OPTIONAL GLOBAL SUBROUTINES,

FUNCTIONAL

NP WY
WE

INPUT

DESCRIPTION:

SEQUENCE:

NONE

#**

PARAMETERS:

NONE

IMPLICIT

NONE

INPUTS:

*%*

OUTPUT PARAMETERS:
*%

NONE

IMPLICIT
**

NONE

#**

OUTPUTS:
**

COMPLETION
**

NONE

CODES:

*%*

SIDE

EFFECTS:

W NI

We "M

NP Wy Wy

WMe Ve

Ve MW

N e

We WP

N NI

CALLING
*%

W Ve WMo WMo

ROUTINES,

+
+

SERVICE

"N e

INTERRUPT

NONE

REGISTERS
**

NONE

USED:
**

* % %

SDS ENDMOD
. END

CONDITION

SUCH AS ERROR REPORTING ROUTINES,
HANDLERS,

ETC.-

APPENDIX

A.2

HEADER MODULE

TEMPLATE

FOR

BLISS-32

PROGRAMS

This is a template to aid in the development of the header
module
of
a VAX diagnostic program.
It is not intended to be a tutorial
for

writing

the

program.

Areas that must be deleted
or
enclosed between matching sets

Areas that

,r//_\\ S

matching

sets

may

replaced
of triple

optionally

of double

stars.

by
the
stars.

modified

are

programmer

enclosed
|

are

between

APPENDIX

RTITLE

‘'*** .tjtle

MODULE

***

***!

module

IDENT
)

name

***

(

'01-00"

+
<+

BEGIN

.
DIGITAL
THIS

SOFTWARE

ONLY

1IN

OTHER

THE

THEREOF

PERSON.

WITH

ABOVE
MAY

(c)

1983 BY

CORPORATION,

FURNISHED

ACCORDANCE

INCLUSION
COPIES

UNDER

THE

MAYNARD,

LICENSE

TERMS

NOTICE.

NOT

PROVIDED

TITLE

AND

MASS.
MAY

SUCH
THIS

USED

SOFTWARE

OTHERWISE

OWNERSHIP

THE

AND

COPIED

LICENSE AND WITH THE
MADE

ANY

AVAILABLE

SOFTWARE

OTHER
TGO

ANY

HEREBY

WITHOUT

NOTICE

TRANSFERRED.,
THE
AND

INFORMATION
SHOULD

NOT

THIS
BE

CORPORATION.
DIGITAL

SUBJECT

CHANGE

COMMITMENT

DIGITAL

RESPONSIBILITY

EQUIPMENT

WHICH

FOR

NOT

THE

USE

SUPPLIED

RELIABILITY

DIGITAL.

***,

VERSION:

FACILITY:

VAX-11

ABSTRACT:

***

ENVIRONMENT:

VAX-11 DIAGNOSTIC SUPERVISOR

AUTHOR:

MODIFIED

***

BY:

EQUIPMENT

ASSUMES

SOFTWARE

CONSTRUED

your

DIAGNOSTIC

abstract

name

***,6

**x*

DATE:

***

date

V@l.0

1ITS

APPENDIX

$SBTTL

'Declarations’'

1++

TABLE

CONTENTS:

FORWARD

ROUTINE

***

youtine

names

***

EXTERNAL

DECLARATIONS:

EXTERNAL ROUTINE
***

routine

|
names

***

;

module...

1++

FILES:

INCLUDE

*** Declare user—defined libraries
LIBRARY 'SYSSLIBRARY:STARLET';
LIBRARY 'SYSSLIBRARY:DIAG';

and

"require"

!
!

files here **%*
VMS MACRO LIBRARY
VAX DIAGNOSTIC FAMILY

"MACRO DEFINITIONS:
MACRO
***

OPTIONAL

USER-WRITTEN

|
MACROS

***x

1++

DIAGNOSTIC

SUPERVISOR

MACROS:

$DS _BGNMOD (ENV = **%* environment **%*);
$DS DISPATCH;
GLOBAL $DS DSSDEF;

$DS_DSADEF;
++

PROGRAM

$DS _SECTION

SECTION

(***

NAMES:

section

names

*#*%);

1++

DEVICE

MNEMONICS

LIST:

$DS_DEVTYP
|

(STRINGS =

ADDRESSES

(*** device types **%*),

(***

addresses

PT-desc

*%*%*));

LIBRARY

APPENDIX

'Program

Header

Data

Block'

+
+

$SBTTL

FUNCTIONAL

DESCRIPTION:

The progra
allows the
The

Diagnostic

beginning

$SDS_HEADER
|

header data block contains the parameters which
Diagnostic Supervisor to control the program.

Supervisor

virtual

looks

address

for

(PNAME ='#*** program name ***!',
REV

UPDATE
NUNIT

=
=

24
*%* *

number

units

the

200 (HEX).

**%*).

header

information

APPENDIX

'Program

Global

Data

Section'

-+
+

¥SBTTL

FUNCTIONAL

* % *

DESCRIPTION:

ALL

DYNAMICALLY

MODIFIED

1++

DEVICE

CONTENTS

TABLE

$DS_BGNREG;
$DS”_ENDREG
;
1++

STATISTICS

TABLE.

$DS_BGNSTAT;
$DS_ENDSTAT;
++

GLOBAL

SYMBOLS:

LITERAL

***k

enter

literals

OWN

STORAGE:

***

1++

GLOBAL

***

enter

variables

**%*

b T )

EQUATED

DATA

SHOULD

PLACED

THIS

SECTION.

*%k%

APPENDIX

'Program

Text

Section'

+
+

FUNCTIONAL

DESCRIPTION:

gum

gam

3SBTTL

the character'strings.

+
<+

‘omm

Gm®

Qus

This section contains all

NAMES

GLOBAL

***

for

DEVICE

REGISTERS

AND

BIT

MEMONICS:

registers

BIND

gscil

use

names

with

the

device

$DS_CVTREG macro

and

rotine

their

bits

#**%*

1++

FORMATTED ASCII

OUTPUT

***

the

messages

STRINGS USED TO
***

enter

operator,

REPORT

statements

STATEMENTS:

ERRORS

***;

etc.

(optional)

#***

(optional)

APPENDIX

'Initialization

Code'

+
+

$SBTTL

FUNCTIONAL DESCRIPTION:
This routine will be
of the diagnostic.
FORMAL

PARAMETERS:
**%

IMPLICIT

NONE

INPUTS:

* % NONE‘**
IMPLICIT
*%

OUTPUTS:
NONE

COMPLETION
*%*
SIDE

CODES:

NONE

*%*

EFFECTS:

*%*

NONE

$DS_BGNINIT;
BEGIN

***

jnitialization

END;

$DS_ENDINIT;

code

**%

executed

the

beginning

each

pass

APPENDIX

+
-+

$SBTTL 'Clean-up Code'
FUNCTIONAL DESCRIPTION:
The
program

***

cleanp-up

IMPLICIT

INPUTS:

NONE

IMPLICIT

OUTPUTS:

NONE

COMPLETION

CODES:

NONE

*%*

EFFECTS:

*% NONE **

$DS_BGNCLEAN;
-

BEGIN

***

PARAMETERS:

x* NONE **

SIDE

cleanup

executed

code

END;

$DS_ENDCLEAN;

the

completion

Description

FORMAL

code

pass.

***

your

routine

goes

here.

***

the

last

APPENDIX

'Summary

Report

Code'

-+
-+

$SBTTL

FUNCTIONAL

* %k

DESCRIPTION:

This

routine

displays

SUMMARY

command

Descrlptlon

FORMAL

PARAMETERS:

**
IMPLICIT

NONE

INPUTS:

NONE

*%*

OUTPUTS:

NONE

COMPLETION

SIDE

CODES:

NONE

*%*

EFFECTS:

** NONE

$DS_BGNSUMMARY
;
BEGIN

***

summary

code

END;

$DS_ENDSUMMARY;

***

the

when

a
a

summary

report

$DS _SUMMARY

routine

call

goes

when
is

here,

the

operator

issued.

*#*%*

types

p———

APPENDIX

ng routines,
1 *** Optional global subroutines, such as error reporti
should
etc,
,
handlers
on
conditi
,
interrupt service routines
!
be placed here. ***

-+
+

$SBTTL 'Global Subroutines'
FUNCTIONAL DESCRIPTION:

FORMAL PARAMETERS:
*% NONE

IMPLICIT

INPUTS:

** NONE

IMPLICIT OUTPUTS:
*% NONE

COMPLETION CODES:
*% NONE

SIDE

EFFECTS:
*%* NONE

REGISTERS

USED:

Qow

$SBTTL 'Summary Report Code'
FUNCTIONAL DESCRIPTION:

FORMAL PARAMETERS:
** NONE

Gen Oom O® Qam Qum

Oum s Qe Pum Ome 0=

Qum Sum fum

Q=8 gam

IMPLICIT

INPUTS:

%% NONE

IMPLICIT OUTPUTS:
*% NONE

./—\\

APPENDIX

COMPLETION CODES:
*%
SIDE

REGISTERS
NONE

$DS_ENDMOD;
END

E LUDOM

#*%

EFFECTS:

NONE

*%*

USED:
#*%*

APPENDIX

APPENDIX B

TEMPLATE FOR VDS
DIAGNOSTIC PROGRAM TEST MODULES
B.1

TEST MODULE

ThlS

VAX

diagnostic.

the

template

to
It

FOR

aid in
is not

MACRO-32

the

PROGRAMS

development

intended

of
a

that

enclosed

Areas

must

between

that

may

matching

sets

Comments

that

should

deleted

matching

contain

replaced
of

optionally

double

deleted.

or
sets

triple

test

tutorial

program.

Areas

and

TEMPLATE

the

module
for

one

modified

star

are

programmer

are

stars.

are

enclosed

between

1nformat10na1

purposes

stars.

only

writing

for

APPENDIX

*%**

.TITLE

. IDENT

/01/

.NLIST

CND

.LIST

PROGRAM MODULE

MEB

NAME

;%%

*%*%*

YVERSION NUMBER #*#*%*
|

+
+

(C)

1989

DIGITAL EQUIPMENT CORPORATION,

THIS SOFTWARE

IS FURNISHED

COMPUTER

SYSTEM AND

REMAIN

DEC.

MAY BE

MAYNARD,

MASSACHUSETTS #1754

UNDER A LICENSE FOR USE ONLY ON A SINGLE

COPIED ONLY WITH

THE INCLUSION OF THE

OR ANY OTHER COPIES THEREOF,
THIS SOFTWARE,
ABOVE COPYRIGHT NOTICE.
MAY NOT BE PROVIDED OR
OTHERWISE MADE AVAILABLE TO ANY OTHER PERSON
EXCEPT FOR USE ON SUCH SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE
TERMS.
TITLE TO AND
OWNERSHIP OF THE
SOFTWARE
SHALL AT ALL TIMES
IN

CORPORATION

VAX DIAGNOSTIC.

ABSTRACT:

***

ENVIRONMENT:

VAX DIAGNOSTIC

Short description of

this module.

WE
M
WE
WM

*** NAME

MODIFIED

BY:

WMe

AUTHOR:

ITS

FACILITY:

++
<+
+

DEC ASSUMES
NO
RESPONSIBILITY
FOR
THE USE OR
RELIABILITY OF
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC.

Ve
WMe

THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE
AND SHOULD
NOT BE CONSTRUED
AS A COMMITMENT
BY DIGITAL
EQUIPMENT

N W

. DEFAULT DISPLACEMENT WORD }* CHANGE THIS TO LONG FOR DEBUG

SUPERVISOR.

DATE **%*

VERSION @1.

***

APPENDIX

. PAGE
e

.SBTTL
+.

DECLARATIONS

FILES:

; INCLUDE

. LIBRARY

\SYS$LIBRARY:DIAG.MLB\

List

;**

(Libraries

programmer—-defined
are

;

libraries

searched

VAX FAMILY DIAGNOSTIC LIBRARY
here.

reverse

order.)

MACROS:

;**

(OPTIONAL).,

***

|
EQUATED

SYMBOLS:

; **% PROGRAMMER-DEFINED MACROS

; *** SYMBOLS
;***

AND

USER

$DS

BGNMOD

LOCAL USE AND SUPERVISOR

EQUATED

SYMBOLS

<*** ENVIRONMENT

$DS_CHDEF

GLOBAL

$DS_DSSDEF

;

SUPERVISOR

SERVICE

PROGRAMMER-DEFINED
LOCAL AND GLOBAL STORAGE

|
SECTION

DEFINITIONS:

$DS_SECDEF

CHANNEL SERVICE SYMBOLS

INTERFACE

<*** SECTION NAMES

*#*%*>

**x*

**%*

*#**)>
K TEST=*** NUMBER

;

GLOBAL

(OPTIONAL).,

“Ne

FOR

FIRST TEST

ENTRY

(LEVEL 3)
VECTORS

IN MODULE***

APPENDIX

TEST NAME

*#*%*)

+
+

<***

TEST

DESCRIPTION:

THIS WILL CONTAIN A BRIEF DESCRIPTION OF WHAT IS BEING TESTED

. PAGE
$DS_SBTTL

AND

THE

TEST

IMPLEMENTED.

ASSUMPTIONS:

HOW

***

ASSUMPTIONS

WHAT

BEFORE
TEST

MADE
OF

THIS

THE

TEST

BEFORE

THE

HARDWARE
IS

TEST
MUST

EXECUTED,

IS
BE

RUN,

SUCH

FUCTIONING

PROPERLY

***

STEPS:

DETAILED
FIRST

SECOND

THIRD

DISCRIPTION

STEP,

THE

TEST

AND

TEST

FLOW

**%

INITIALIZATION

STEP

ERRORS:

NI
NI

@1:

DETAILED

ERROR

@2:

ERROR

@3:

DISCRIPTION

THE

ERRORS

DETECTABLE

AND

REPORTED

**%*
'

DEBUG:

MNP

***

ERROR

**%*

PARTS

SECTION WILL
IN DEBUGGING

CONTAIN INSTRUCTIONS
THE UNIT UNDER TEST.

HOW

USE

THIS

THIS
TEST

$DS_BGNTST

<***

SECTION

NAMES

***> ALIGN=BYTE
;* CHANGE

Wme

“e

; *

BLOCK COMMENTS
IS DOING

EXPLAIN

WHAT

SPECIFIC

BLOCK

CODE

PAGE

THIS

FOR

DEBUG

SUBTEST

wNe

APPENDIX

*%* BRIEF DESCRIPTION OF WHAT THE SUBTEST CHECKS #%%

'SUBTEST STEPS:

DESCRIPTION:

#%*

DETAILED

FLOW

TEST

SEQUENCE

*#*%

ERRORS

***

BRIEF

DESCRIPTION
CAN

DETECTED

EACH
BY

THIS

THE

ERRORS

TEST

***

THAT

DEBUG:

HELPFUL

WMe

***

BLOCK

COMMENT

WMo

$DS_BGNSUB

$DS_ENDSUB
$DS_ENDTEST
$DS

ENDMOD

. END

HINTS

FOR

TRACKING

HARDWARE

FAULTS

#**%*

APPENDI
X
TEST MODULE TEMPLATE FOR BLISS-32 PROGRAMS

B.2

This is a template to aid in the development of the header
module
to be a tutorial
It is not intended
of a VAX diagnostic program.
for

writing

the

program.

Areas that must be deleted
or
replaced
by
the
enclosed between matching sets of triple stars.

Areas

that

matching

sets

may
of

optionally

double

stars.

modified

are
»

programmer

encloséd

are
|

between

APPENDIX

$TITLE

'"***

title

MODULE

***

module

name

***

(

IDENT ='@gl-900"

)

-+
+

BE GIN

**%!'

SOFTWARE

ONLY

OTHER

THE

THEREOF
PERSON.

WITH

ABOVE
MAY

(c)

1983

CORPORATION,

FURNISHED

ACCORDANCE

INCLUSION
COPIES

EQUIPMENT

UNDER

THE

TERMS

MAYNARD,

LICENSE

NOTICE.

NOT

PROVIDED

TITLE

AND

MASS.
MAY

SUCH
THIS

USED

SOFTWARE

OTHERWISE

OWNERSHIP

LICENSE

THE

MADE

AND

COPIED

AND WITH
THE

ANY

AVAILABLE

SOFTWARE

OTHER
TO

ANY

HEREBY

WITHOUT

NOTICE

TRANSFERRED.
THE
AND

NOT

THIS
BE

SOFTWARE

CONSTRUED

SUBJECT

CHANGE

COMMITMENT

DIGITAL

EQUIPMENT

CORPORATION.

DIGITAL ASSUMES
SOFTWARE

RESPONSIBILITY

EQUIPMENT

VAX-11

ABSTRACT:

***

ENVIRONMENT:

VAX-11

MODIFIED

FOR

NOT

THE

USE

SUPPLIED

RELIABILITY

DIGITAL.

#***,

VERSION:

FACILITY:

AUTHOR:

WHICH

***
BY:

your

DIAGNOSTIC

gbstract

name

***

DIAGNOSTIC

***,

DATE:

SUPERVISOR

***

date

V@l.0

ITS

APPENDIX

INCLUDE

FILES:

*** List all programmer-defined
LIBRARY 'SYSSLIBRARY:DIAG';
b+

and

"require"

files

here.

***%

SUPERVISOR MACROS

$DS BGNMOD (ENV = ***
$DS DSADEF;
$DS_DSSDEF;
$DS_SECDEF

(***

environment ***,

section

names

1++

libraries

EXTERNAL

***

DECLARATIONS

ROUTINE

routine

name

EXTERNAL
k%%

names

% % %

;

***

**¥);

TEST = ***

starting

test number

***%*);

APPENDIX

$SBTTL

'***%

gsyubtitle

**%*?

TEST

DESCRIPTION:

This

and

how

will

the

contain

test

brief

description

implemented.

what

run,

such

being

tested

#*#*%*

ASSUMPTIONS:

Gaw

***

Assumptions

made

Gum

which

portions

the

O=w

foE

Quw

Qun

***

OSww

Sum

1++

properly before

the

hardware

test

must

test

executed.

description

the

functioning

***

TEST

STEPS:
***

Detailed

***

step,

few

First

***

Second

Pmw

Ouw OE

gum

Guw

this

before

***

Third

step

and

test

flow

*#*%*

***

ERRORS:

***

Detailed

description

the

Error

@1l:

***

description

**%*

Error
Error

02:

***
***

description

**%*

03:

description

**%*

errors

detectable

and

reported

DEBUG:

fum

This

section

will

test

debugging

the

contain

unit

instructions

under

test.

***%

fom

***

Fmm

Qgum

fuw

Ofus

fum Cam

fuw

step

test

Initialization

$DS_BGNTEST

(SECTION = ***
TEST

'***

test

section names
name

**%,

***'),;

1++

]

***

| J——

BEGIN

Block comment to
of code is doing

explain
***

what a

specific

block

how

use

this

***

APPENDIX

'***

gubtitle

***!

+
+

$SBTTL

SUBTEST

DESCRIPTION:

*** Brief descriptiéh‘of whét the subtest checks ***
SUBTEST

STEPS:

*** Detailed

ERRORS:

flow of test

sequence

***

*** Brief description of each of the possible errors detected ***

DEBUG:‘

*** Helpful

hints for

tracking hardware faults ***

+
+

***

Block comment to
of code is doing

Omm

faw Q==

$DS_BGNSUB;

BEGIN

***

gubtest

END;

$DS_ENDSUB;

END;

$DS_ENDTEST;

$DS_ENDMOD;
END

ELUDOM

code

***

explain what a
***

specific

block

APPENDIX

APPENDIX C
TEMPLATE FOR DIAGNOSTIC PROGRAM

DOCUMENTATION FILE

This

Everything

/‘

;

matching

template
to

double

for

changed,

angle

VAX

diagnostic

added,

brackets,

'<<'

and

documentation

deleted

'>>'.

1is

files.

enclosed

APPENDIX

IDENTIFICATION

Product code:

ZZ-<< maindec

Product

name:

program

Product

date:

submission

date

diagnostic

engineering

Maintainer:

code,

name

The information in this document
notice

and

should

not

Equipment Corporation.
responsibility for any
The

software

described

license

and

may

terms

such

license.

responsibility

software

equipment

including

version >>

>>
>>

group

subject

construed

change without

commitment

Digital Equipment Corporation
errors that may appear in this
in

this

used

document

or copied

assumed
that

for
is

the
not

1is

only

use

Digital

assumes
document.

furnished

under

accordance

with

supplied

reliability
by

Digital

the

of
its

affiliated

companies.

The

following

are

trademarks

Digital

DEC

DECsystem-10

DECSYSTEM-20

DECUS

MASSBUS

PDP

UNIBUS

VAX

VMS

any

additional

<< Digital 1logo

trademarks

Equipment

Corporation.

APPENDIX

REQUIREMENTS

¢«

REQUIREMENTS

¢«

[]

Flags

¢«

[]

®
e

FUNCTIONAL

¢«

Program

SizZe

o«

Program

Run

¢«

o
o«

WNHKH

Odond

DESCRIPTION

Overview

Run—-time Dynamics
Fault Detection
.

[ J

INSTRUCTIONS

Options

OYOYOY OO

o«

Times

¢«

Performance

Hardware

Program

Test

During

Applications

Descriptions

MAINTENANCE

HISTORY

Failures

¢«

o«

1t N

Program

PROGRAM

o
¢

OO
»n

Event

PREREQUISITES

OPERATING

SOFTWARE

HARDWARE

Contents

G OO

[]

)

AB STRACT

Table

APPENDIX

ABSTRACT

C.l

from 3 to

<< program abstract;

20 lines

HARDWARE REQUIREMENTS

C.2

<< minimum hardware configuration;

SOFTWARE

C.3

optional

hardware

REQUIREMENTS

<< software environment,

e.g.

VAX Diagnostic Supervisor

PREREQUISITES

C.4

<< hardware that should be verified before running this program
C.5

OPERATING

Refer

INSTRUCTIONS

the

"VAX-11

Diagnostic

System

(EK-DS780-UG-002)
for instructions on how to

Diagnostic Supervisor and

how

load

and

load

User's
and

execute

Guide"

start

the

programs

under
the Diagnostic Supervisor.
The operator must ATTACH and
SELECT the device << e. g., KA780 before starting this program.

C.5.1

Options

<< any operator'options, such as MANUAL section
C.5.2

Event Flags

<< The

following

event

<<event

flag

2.,

<Kevent

flag

etc.

flags are

used

by this program.

APPENDIX

C.6

PROGRAM FUNCTIONAL DESCRIPTION
C.6.1
<<

Program

purpose,

C.6.2
<<

names

quick

memory

C.6.5

error

all

associated

files

Times

default,

with

options

Dynamics

allocations,

side

effects,

sequence

resolution,

Program

field

error

During

traps,

message

formats,

Hardware

Failures

power

fault

for

"Debug

C.7
<<

coverage

(%)

Applications

service

(RD),

manufacturing

(APT) ,

customers,

Test

Descriptions

each

test/subtest,

"Test

description",

aids"

MAINTENANCE
date,

failure

engineering

testing

Detection

unsuspected

C.6.8

units

Performance

C.6.7
<<

Run

verify,

Fault

C.6.6
<<

sizes

Run-time

multilpe

and

transportability

Size

Program

C.6.4
<<

strategy,

Program

C.6.3
<<

Overview

version:

HISTORY
description

changes

"Test

steps",

and

APPENDIX

APPENDIX
D

SAMPLE HELP FILE

ATTACH
The

CPU

must

information

attached.

Type

VAX—ll/?S@.

"HELP

A VAX-11/750

DEVICE

CPU

KA780"

for

KA750,

etc.

Example:

ATTACH

KA780

SBI

KA@

HELP

This program
instruction

exercises
the
VAX
native
mode
floating
point
set;,
which
can
be
executed
in any mode, i.e.,
non-priviledged
instructions.
The
program
is
capable
of
running

under

standalone

designed
1l

DEVICE

KA730

,'/A\\\

Type

"HELP

Diagnostic

run

any member

user

Supervisor

task

under

VMS.

VAX

family

the

DEVICE

KA730@"

for

information.

DEVICE

KA750"

for

information.

DEVICE

KA780"

for

information.

either
It

the

also

computers.

KA750
Type

"HELP

KA780
Type

the

environment

"HELP

EVENT

The

following

event

flags

have

the

described

effects

timer

interrupting

this

program:

Bvent

Flag

instruction
Event

Flag

faulting

Disable

1is

Enable

also

Event Flag 4:
error

the

interval

execution.

the

interval

timer

interrupting

while

page

enabled.

Enable the continuation

(normally

during

the

subtest

after

aborted).

QUICK
The

QUICK

flag

disables

page

faulting

case

1is

executed

only

combination.
1

SECTIONS

DEFAULT

the

exection

interrupting,

once

for

the

that

instructions

each

instruction

addressing

with
test
mode

APPENDIX

The DEFAULT section

other
2

includes

all

the

tests maklng

Precision

CVTBF,

CVTWF,

ADDF2,

EMODF,

Floating
CVTLF,

ADDF3,
and

Point

CVTFB,

SUBF2,

Instructions:
CVTFW,

SUBF3,

POLYF.

CVTBD,

CVTDF,

MULD3,

CVTWD,

CMPD,

DIVD2,

FLOATING

ADDG3,

Floating

CVTLD,

TSTD,

Range

CVTGL,

SUBG2,

Point

MULF2,

MULF3,

the

MNEGF,
CMPF,

DIVF2,

CVTDB,

EMODD,

and

Double

Instructions:

CVTDW,

ADDD2, ADDD3,

DIVD3,

Instructions:

CVTGW,

CVTRFL,

Precision

Extended

MOVF,

CVTFL,

DFLOATING

Double

FLOATING

DIVF3,

sections.

Single

TSTF,

four

MOVD,

CVTDL,

SUBD2,

CVTFD,

SUBD3,

MULD2,

‘Floating

~Point

POLYD.

Precision

CVTRDL,

MNEGD,

MOVG,

MNEGG,

CVTBG,

CVTWG,

CVTLG,

CVTGB,

CVTRGL,

CVTFG,

CVTGF,

CMPG,

TSTG,

ADDG2,

SuBG3,

MULG2,

MULG3,

DIVG2,

DIVG3,

EMODG,

and

POLYG.

H FLOATING

Extended

Range

Quadruple

Instructions:
CVTHW, CVTHL,
CVvTHG,
CMPH,

MOVH,
CVTRHL,
TSTH,

MULH3,

DIVH3,

DIVH2,

Precision

Floating

MNEGH,
CVTBH,
CVTWH, CVTLH,
CVTFH, CVTDH,
CVTGH,
CVTHF,
ADDH2,
ADDH3,
SUBHZ2,
SUBH3,

EMODH,

and

Point

CVTHB,
CVTHD,
MULH2,

POLYH.

SUMMARY

The

summary report gives an

report

is generated

there

error

were

count
no

errors.

test
|

number.

INDEX

SALLOCATE,

SASCTIM,
SASSIGN,

3-25,

3-44

4-106
3-25,

3-43

3-60,

4-123

3-48,

4-127

3-64,

4-129

$DS BGNINIT,

SBINTIM,
SCANCEL,
SCANTIM,

3-43,

SDEALLOCATE,

SDEF,

3-13

4-155

3-14,

SDEFEND,

3-13

SDEFINI,

3-13,

SDISCONNECT,

SDECIMAL,

$DS_SEND,

3-15,

$DS_S$FETCH,

$DS_S$HEX,

4-18

3-15,

4-156

4-15

4-16

4-23

3-15,

4-27

SDS

3-32,

5-28

3-36,
|

BGNCLEAN,

3-29,

4-96,

3-4 2,

4-97,

3-41,

4-9 8,

5-31

3-41,

4-96,

5-30

3-26,

BQUICK,

3-41,

3-66,

4-37

4-39

3-42

4-120

CLI,

3 61,

4-130

4-131

4-267

3-38 to
3-54, 4-55

3- 39,

4-268
3-58, 4-14 4
3-58, 3-65 _

3-51,

$SDS DEFDEL,

4-277

DEVTYP,

3-23,

$DS_DISPATCH,

$DS

DSDEF,

SDS

ENDDATA,

4-14 9
4-61

3-22,

4~ 73

4-269

$DS DSSDEF, 4-1, 4-270
$DS_ENDCLEAN, 3-27, 4- 37
$SDS ENDINIT,

3-29,

3-24,

$DS_ENDMESSAGE,

Index-1

5-31

4-266

$DS_CVTREG,

SDS

3-32,

4-98 .

4-126

3-24,

3-49,

CHCDEF,

$DS_CLIDEF,
SDS_CLRVEC,
$DS _CNTRLC,

4-94

4-95

3-27,

3-41 .

$DS_CKLOOP,

$DS

4-108

3-41,

4-94

3-26,

3-32,

$DS_CHMDEF,

to 3-54, 5-30
ATTACH, 3-22, 3-68,

$DS BGNDATA,

$SDS

3-48

3-52

SDS_BERROR,

$SDS BNQUICK,

SDS

$DS_ASKSTR, 3-52, 4-108
$DS_ASKVLD, 3-52, 4-108
SDS ASKxxxx, 3-13, 3-27,

$SDS_BCOMPLETE,

3-37,

4-9 5

5-28

$DS_CHANNEL,

SDS_ASKDATA, 3-52, 4-108
$DS_ ASKLGCL, 3-52, 4-108
$DS_ASKLOGICAL, 5-28

SDS

3-41,

$SDS BNOPER, 3-32,
5-29 to 5-30

3-51

3-52,

3-41,

$DS CANWAIT, 3-60
SDS CFDEF, 4-265

$SDS_S$SSTORE, 3-15, 4-33
$DS_$STRING, 3-15, 4-35

$DS_ASKADR,

BNERROR,

$DS _BREAK,

SDS_$NAME, 3-15, 4-28
$DS_$OCTAL, 3-15, 4-31

4-1¢5,

4-51

3-3 1,

5-28

3-15,

$DS SLOGICAL,

3-39,

SDS

5-29

4-26

3-27,

3-28,

4-264

$SDS_BPASS@,

3-15,

$DS_ABORT,

BITDEF,

$DS_BOPER,

4-19

$DS_SLITERAL,

$DS_S$PRINTS,

$SDS

4-21

$SDS_SINITIALIZE,

3-37,

$DS_BNPASS#,

3-15,

4-4 8

3-29,

SDS BNCOMPLETE,

3-73,

3-15,

BGNSUMMARY,

4-53

4-8

4-9

$DS_$COMPLEMENT,

3-49,

$DS_BGNTEST,

$DS_SADD, 3-15, 4-11
SDS $CASE, 3-15, 4-13

S$DS

$SDS

|
3-71,

BGNSERV,

4-50

3-44

SDS

4-45
4-47

4-4 1

4-43

SDS BGNSTAT, 3-28, 4-4 9
$DS_BGNSUB, 3-29, 3-31 .

SCLOSE, 3-71, 3-73, 4-140
SCLREF, 3-57, 4-142
SCONNECT, 3-71, 3-73, 4-147
SDASSGN,

BGNMESSAGE,

$SDS BGNMOD,
$DS_BGNREG,

3-44,

4-116

3-24,

SDS

4-3 9

4-4 1

4-43

4-99

4-145

INDEX

SDS ENDMOD, 4-45
$DS_ENDPASS, 4-158
$DS_ENDREG,
SDS

ENDSERV,

$DS_ENDSUB,
to

SDS

4-48

3-28,

3-29,

3-31,
4-51

SDS_ERRDEV,

SFAB

3-36,

$DS_ERRPREP,
SDS ERRSOFT,

4-159,
4-159

5-30

3-36,

3-42,

4-159

3-33,

3-19,

3-24 to 3-25,

$DS_HEADER,

3-22,

4-74

SDS

HPO

DECL,

3-20,

$DS_HPODEF,

4-272

$DS_INITSCB,

3-50,

MMOFF,

SDS MMON,
SDS_PAGE,

3-55,

3-55,
4-76

4-186

4-191

$DS_PRINTB,

3-32,

3-51,

$DS_PRINTF,

3-51,

4-201

SDS

3-28,

4-201

PRINTS,

$DS_PRINTSIG,

3-64,

3-33, 3-51,
$DS _PROBE, 3-50, 4-211
$DS_PSLDEF, 4-275
SDS

PTDDEF,

4-274

SDS RELBUF, 3-56,
$DS SBTTL, 4-84

4-276

$DS_SECDEF,

3-31, 4-86
3-23, 3-31,

$DS_SECTION,

4-201

SQIOW,

3-44,

3-47,

4-213
buffer,

3-46

3-47
3-47,

3-57 to 3-58, 4-213
SRAB, 3-69, 4-77
SRAB_INIT, 4-82

3-60,

SWFLAND,

SWFLOR,

4-201

3-58,
3-55,
3-64

SSSDEF, 3-63
SUNWIND, 3-64,
SWAITFR, 3-46,
SWAKE,

3-60,
4-239

4-248
3-57,

4-229

4-252

4-258

3-57,

SXABFHC, 3-69,
$XABFHC STORE,

4-2690

4-262

4-90
3-70

ABORT command,
3-27
Action routines, 4-198,

4-223

$DS_SCBDEF,

3-57 to 3-58,
SQIO diagnostic

SSETIMR,
SSETPRT,
SSETVEC,

4-210

$DS_PRINTX,

4-166

SSETAST, 3-58, 4-225
SSETEF, 3-57, 4-227
SSETEXP, 3-63

4-191

$DS_PARDEF, 4-273
SDS PARSE, 3-54, 4-197

4-71

SRAB_STORE, 3-70, 4-82
SREAD, 3-73, 4-218
SREADEF, 3-57, 4-221

4-272

$DS_INLOOP, 3-39, 4-187
$DS LOAD, 3-66, 4-188
$SDS

3-70,

4-166

3-60, 4-185
SOPEN, 3-71, 3-73, 4-193
$QI0, 2-7 to 2-8, 3-43 to

4-101

4-184

4-256

SHIBER,

SDS GPHARD,

3-54,

4-245

SGET, 3-71, 3-73, 4-169
SGETCHN, 3-48, 4-175
SGETTIM, 3-60, 4-181

$DS_EXIT, 3-36, 3-42, 4-103
$DS_GETBUF, 3-54 to 3-56, 4-172
SDS GETTERM, 4-179

$DS HELP,

3-49,

4-71

STORE,

SFAOL,

3-51

3-42,

4-63

SFAO, 3-51,

4-159

3-36,

3-49,

3-61,

3-69,

SFAB_INIT,

$DS_ERRHARD, 3-36,
$DS_ERRNUM, 4-92

4-182

4-242

4-88

WAITUS,

SFAB,

4-159

3-35,
3-35,

SETVEC,

$DS_STRING,

$DS

$SDS_ESCAPE,

3-5@,

3-48

$DS_SUMMARY, 4-247
$SDS_WAITMS, 3-60, 4-254

4-50

$DS_ENDTEST, 3-29,
3-37 to 3-38, 4-53
$DS_ERRDEF, 4-271

$DS_ERRxxxx,

4-233

3-24,

$DS_SHOCHAN,

4-49

SDS_ENDSUMMARY,
3-28,

SDS_ERRSYS,

3-50,

4-234

3-49,

3-38,

SETIPL,

$DS SETMAP,

4-47

$DS_ENDSTAT,
3-37

$SDS

Adapters
bus, 3-24,
displaying
3-49

4-87

Index-2

4-200

|
3-48
internal
|

registers

of,

INDEX

interrupts from, 3-28
mapping registers, 3-49
MASSBUS,

status

3-48

of,

UNIBUS,

3-43 to
2-1,

AST

3-48

2-2,

3-48

See

|
3-13,

5-24

See

3-60

system

3-11

command,

3-6

3-15,

3-13,

3-52,

Design
Device

quality

resolution,

3-22,

3-69,

all

assurance

customer
1-3 to

users,

Breakpoint
- BRO,

facility,

users

3-62

uses

3-73

Buffers,

3-4,

Channels,

3-28,

3-44,

string

descriptors,

3-25,

3-27 to
3-36,

3-35
CLEAR

EVENT

Cluster

Command

3-62

exerciser,

2-10

3-61

command,

Control-C,

3-37,

control-C,

3-65

Control-C

3-27,

5-23

code,

logging,

3-32
VDS

Error
3-65

3-54,

5-9

5-12

3-32

formats,

3-33,

4-43
to

5-25,

flags

reporting

5-27

and,

routines,

4-44,

4-162,

device-fatal,
3-35 to

hard,

Index-3

5-24

5-12,

4-271

Errors

3-66

5-12,

3-44

messages,

control

3-33,
4-161

flags

handler,

5-8

reporting

message

3-65

control

failing hardware,

5-21,

source

Error
Error

3-64

Flags

VDS

error

3-3,

1-4

1-2

5-14 to 5-19
Documentation files,

3-53

handling,

3-56,

CONTINUE

3-65

3-28,
3-43,

3-5,

language

3-50,

see

3-2,

3-57

creating

Control

FLAGS,

Condition
-

3-1

of,

1-4

5-14
code,

1-3

engineers,

Documentation,

4-7
Clean-up

during design of new products,
1-1
in manufacturing, 1-1
Dispatch Table, 3-22

3-48

assigning, 3-43
deassigning, 3-43
Character

1-2

on product,

detecting
1-1

3-55

reps.,

1-4

manufacturing,
3-73

5-3
3-23

1-2

customers,

3-73

1-9

|
buffer
header, 3-22

service

depending

processing,

buffer
diagnostic

design
BI10,

1-8

specifications,
mnemonics list,

3-68

automated
Autosizer, 3-13

Block

program,

3-44

Diagnostic program
Diagnostic programs
user requirements

3-8,

Auto-QA

See

diagnostic

command,

Diagnostic
See $QI0

traps

ASTs

3-25,

DESELECT

routines, 3-47, 3-58,
3-47, 3-58
Asynchronous events, 3-56

5-34
Degree

3-58

AST

ATTACH

|
Diagnostics

CRD

Debugging

3-65,

ASTs,

Asynchronous

representatives,

3-25,

5-24

delivery,

5-25

service

Customer-Runnable

devices,
3-44
3-4,

ApT,

3-13,

1-9

3-10,

Allocating

APT/RD,

CRD,

Customer

3-36
3-36

3-34

3-3,

INDEX

soft;

3-35

system-fatal,

see

5-29

Errors

3-64
BPT,

HUB,

block

3-69,

3-73

Fault detection,
Fault isolation,
Field-replacable
access

5-4
1-8,
unit

5-4
(FRU),

1-6

Flags

Event

Formatted

ASCII

I/0,

2-7 to

2-8

status

block,

to
to

3-24
3-42

specifications,

5-2,

Guidelines for writing diag.
level 1 guidelines, 2-12
level 2 guidelines, 2-13
level 2R guidelines, 2-12
level 3 guidelines,

2-12

Level
Level

environments,
2-6

Tables

3-60 to 3-61,

2-6

2 programs, 2-8,
2R programs, 2-7

2-11 to 2-12,

2-7,
|

2-13
to 2-8,

3-24 to 3-25,

3-54, 3 57

3- 59

3-66 to 3- 67
Level 3 programs, 2-8,
2-19 to 2-14, 3-48, 3-55,

2-15

2-5

1 programs,

3-43,

level

Halt-on-error, 3-34
Hardcore, 1-6 to 1-7,

3-48,

3-50

progs. Level

2-14

4 guidelines,
2-14 to 2-15
level 5 guidelines,

3-19,

3-36,
3-54

4-138
IPL,

Parameter

3-46

Interrupt service routines,
3-3, 3-42, 3-49, 3-60 to 3-61

Output

5-35

3-5,

3-26,
3-43,

Interrupts,

Functional

Hardware

virtual

3-1 to 3-2,

FAO

I/0

Flags

1-9

2-5

1 programs,

in level 2 programs, 2
in level 2R programs, 2 8
in level 3 programs, 2
in level 4 programs, 2in level 5 programs, 2
logical I/0,; 2-7 to 2-8
physical 1/0, 2-7 to 2-8

see VDS control flags
Format statements,
3-51

Hardware

in level

Implicit inputs, 5-14
Implicit outputs, 5-15
Initialization code,

block

FAB

2-13

3-45

FAO directives,
4-166, 4-201,
4-204 to 4-205, 4-207 to 4-208

5-4,

encodlng,

3-69,

See

functlon

I/O methods

3-68

FAC,

FRU,

3-10

O O 00|

FAB,

see

3-7,

_I/O

XAB

See

5-30

3-62

T-bit, 3-62
EXIT command, 3-44
Extended attrlbute

File

preparation,

HELP command, 5-19
Help files, 3-54, 5-19
créating, 5-20, 5-22 to 5-24
description of, 5-19 to 5-20
keywords in, 5-20 to 5-24
text in, 5-23 to 5-24

device-fatal, 3-36
preparation, 3-35
- system-fatal, 3-36
Event flags, 3-46, 3-56, 3-58
Exception vectors, 3-50
Exceptions, 3-27, 3-56, 3-61,

see

P-tables

Hardware

3-36

3-57 to 3-59, 3-66 to 3-67
Level 4 programs, 2-9 to 2-10,
to

2-6

2-14

2-15

Level 5 programs, 2-6,
|
2-9 to 2-10, 2-15
program,
diagnositic
a
Linking

Index-4

INDEX

p-table

3-4
Linking

diagnostic

3-11

program,

5-33

Logical unit number, 3-25
Looping, 3-2, 3-5, 3-34,
3-36

and

the

3-38

$DS BREAK macro,
to

3-19
UNIBUS
Passes,

1-12

structure,

3-5

symbol

definition,

3-6

3-5

Mechanism array, 3-63
Memory allocation, 3-55
3-4

5-30

3-56

of by VDS,
3-8, 3-52

device-independent

azr ¥

3-8

getting a
3-24 to
HUB 1link,

unit's
3-25
3-7

logical

unit

»
phase,

specification

5-5

phase,

5-2

loops,

sections table, 3-23
plans, 5-1 to 5-2, 5-4

3-36

Quadword descriptors,
4-7
Quality assurance, 5-5
e

5-35

functional quality, 5-35
operational quality,
5-35 to 5-36, 5-38, 5-40

3—6

Quick

mode,

3-41,

5-31

o
RAB,

RAC,

fields

of,

3-68, 3-73
3-70 to 3-71

Random-by-RFA,

3-71,

Reading

Files,

3-70

access

block

Record
See

p-table,

and,

management

services
|

RMS

See

3-25

3-73

RAB

Record

number

5-4

Program

3-14

format of,

phases

automated, 5-40 to 5-43
quality requirements
documentation quality,

5-31
to

programs,

3-55

device-dependent fields of
3-8, 3-11, 3-13
creatlng names for, 3-19,

3-13

4-97

diagnostic

program
Project

service,

control-Cs and, 3-65
device's link, 3-7

3-8,

3-28,

5-2

3-6

SALLOCATE

3-42,

phase, 5-3
verification

planning

Micro-instructions, 1-12
Micro-programs, 1-12

3-44
construction
contents of,

functional

3-5

3-54

design
design

system service, 3-6
Manual intervention, 3-32,
Manufacturing, 2-1

layout,

3-25

development

5-3

control,

program

the

3-41

consultation phase, 5-1 to 5-2
design implementation phase,

program

management,

from
a diagnostic

3-23,

Program

1-12

Memory

5-24,

and, 3-10
specification, 4-243

Prgrilease

1-9

Memory

3-12,

adapters

vector

Macros

and

of,

3-15

3-36,

Macro-programs,

3-25
list,

3-13,

referencing

3-39

Macro-instructions,

allocation,

5-23

3-36

P-tables,

device mnemonics

location

loop boundaries, 3-37 to 3-38
defaults for, 3-37
nesting loops, 3-39 to 3-40
user-specified, 3-40
Loops,

and

3-19

device

creating,

3-66

of,

program,

Looping,

3-12,

and

- 3=-23

3-37

characteristics

descriptors,
to

Record

processing,

3-71

Record

processing,

3-70

RFA,

Index-5

3-71

3-73

INDEX

RMS,

3-66

ROP,

3-73

RUN

3-71,

3-73

command,

3-1,

3-23,

3-54
Run-time

enviroments

user

1-5

mode,

Run-time

networks,

3-44,

of,

1-5

user

1-5

mode,

command,

3-28

Summary

routine,

3-1,

3-=28,

1-5

environments
when
|

dollars

signs

naming,

5-31

3-1¢,

4-242
Scope

3-50,

programming,

Sections,

SEQ,

See

3-36

SET

EVENT

5-30,
3-23,

OFF,

ON,

5-39
3-25,

(SUT),

Testing
bottom-up,

1-11

parallel,

3-70

3-57

3-55

Source modules
header module,
modules,

CONTINUE,

SSS RESIGNAL,

5-5

5-5,

5-7

3-24,
3-55

3-57,

3-64,

Standalone
START

3-59

mode,

SUBTEST

Tests,

3-40

3-29
looping

3-2,

and

sections,

and

subtests,

1-12
to

1-9

3-5,

3-29

3-31
3-31

3-29
3-22

intervention

serial, 3-3, 3-23 to
subpasses and, 3-23
3-40 y

1llegal

3-29

uses

of,

3-32

3-24

types

of
exercisers, 1-10
function tests, 1-10,
3-29

logic
of,

in,

parallel, 3-3, 3-24
passes and, 3-23

3-29

tests,

3-29
Tests, looping

Timing,
Timing

in,

3-1

manual

3-640,

3-23,

3-24

and

2-10

devices,

3-29,
characteristics of,
Dispatch Table and,

5-24

characteristics
global, 3-31
legal

1-11

1-7

3-4,

qualifier,

Subtests,

2-12

scope,

3-61

3-1,

3-23

top-down,
Testing

3-54
Subpasses,

peripheral

global routines in, 3-29
input arguments, 3-29

3-66,

command,

testing

1-7

3-64

mode, 2-1,
3-48, 3-54,

3-62,

1-10
|
CPU cluster,

goals,

|
5-6

1-12

1-10

Testing

3-64

Standalone

1-6

serial,
testing
2-11

3-55

3-4

SSS

SCB

test

access,

Signal array, 3-63 to 3-64
Single-~step facility, 3-62
Size of a diagnostic program,
-

test

3-56

Block

under

3- 44

3-71

FLAGS,

SET

Completion,

events,

Control

System

record

SET

5-33

command,

3-70

System

3-31

Sequential

5-31

3-46

3-64,

DEFAULT, 3-32,
MANUAL,
5-30
SELECT

in,

public, 5-31
Synchronizing I/0O

4-243

loops,

3-51

5-31

Synchronous
sCB,

3-42,

3-3,

Symbols

private,

considerations
5-24

on,

SUMMARY

1-6

mode,

3-29
looping

3-40

3-25,

environments,

standalone

Runtime

numbering

user-specified

3-37

Index-6

1-10,

in,

3-37

facilities,

3-60

3-59

2-13,

INDEX

Unit

under

See

test

UUT

Unwinding,
User

3-64

mode,

2-1,
3-4,
3-36, 3-43,

3-28,

3-54
3-62
ouT,

to
to

1-6

3-57,
3-63,

3-9,

3-25,

3-59 to 3-60,
3-66, 5-24

1-7,

3-2,

3-6,

3-29,

3-35

3-36,

3-38,

3-43,

3-52

3-15,

3-17,

~Value

4-11,

4-13,

4-16,

4-26,

4-31,

4-33

4-19,

VAX

Diagnostic

Debugger,

VAX

diagnostic

strategy

program

levels,

2-4

4-21,

5-34
2-7

VDS

human interface, 2-2
program interface, 2-2
purposes
VDS

of,

Control

IE2,

4-201

IE3,

4-201

IES,

4-201

VDS

control

HALT,

IES,

2-3

Flags

flags,

3-51

3-34

3-28

LOOP,

3-34,

3-36

3-37

OPERATOR,

3-32,

3-41,

5-28

5-3¢,

5-39

QUICK,

Vectors,

VMS
XAB,

3-41,

3-53,

5-31

4-138,

4-243

privileges,

3-36,

3-47

3-68

Index-7

VAX DIAGNOSTIC DESIGN GUIDE

Reader's Comments

Your comments and suggestlons will help us in our contmuous effort to improve the quality and
usefulness of our publications.

Whatis your general reaction to this manual? In your;udgmentis it complete, accurate, well organized,

written, etc? Is it easy to use’?

well

What features are most useful?

What faults or errors have you found in the manual?

Does this manual satisfy the need you think it was intended to satisfy?
Does it satisfy your needs?

—

Why?

Please send me the current copy of the Documentation Products Directory, which contains mformatuon
on the remainder of DIGITAL's technical documentation.

Name

—

Title

‘Company

Department

Street
—

City

- Zip -

Additional copies of this document are available from:
Digital Equipment Corporation
Accessories and Supplies Group

P.O. Box CS2008
|
Nashua, New Hampshire 03061

Attention: Documentation Products
| Telephone: 1-800-258-1710

' order Ne_ EK-1VAXD-TM

ZKO

‘

State/Country

d [g{Bl

No Postage

Necessary
if Mailed in the

United States

BUSINESS REPLY MAIL
FIRST CLASS

PERMIT NO.33

MAYNARD, MA.

POSTAGE WILL BE PAID BY ADDRESSEE

32-Bit Systems Diagnostic Engineering, TWO/F17
Digital Equipment Corporation

1925 Andover Street

Tewksbury, MA 01876

-t

afs

EK-1VAXD-TM-003

VAX Diagnostic
-

IMPORTANT

To automatically receive updates of this manual, fill out the following information:

Internal:

Name

Group

Mail Stop_
DTN

External:

_
,'

____

Name

Title
Company

Street

—

City
- State/Country.
Zip

Design Guide

| || || |

No Postage
Necessary

if Mailed in the

United States

BUSINESS REPLY MAIL
FIRST CLASS

PERMIT NO.33

MAYNARD, MA.

POSTAGE WILL BE PAID BY ADDRESSEE

Digital Equipment Corporation
Educational Services/Quality Assurance

12 Crosby Drive, BU/E0O8
Bedford, MA 01730