Digital PDFs

AA-FK67A-TE

April 1989

528 pages

Original

20MB

view download

OCR Version

23MB

view download

Document:	VAX Diagnostic Design Guide
Order Number:	AA-FK67A-TE
Revision:	000
Pages:	528
Original Filename:

OCR Text

VAX

Diagnostic Design Guide

Order Number: AA-FK67A-TE

April 1989

This manual describes the design strategy for VAX diagnostic programs.
In particular, it details how to design, create, and execute diagnostic
programs that will be used with the VAX Diagnostic Supervisor.

Revision/Update Information

This revised document supersedes the

VAX Diagnostic Design Guide, Order
No. EK-1VAXD-TM-004.

Software Version

VAX/DS Version 11.6

digital equipment corporation, maynard, massachusetts

First Printing, April 1989

The information in this document is subject to change without notice and should not be construed as a

commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for
any errors that may appear in this document.

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

No responsibility is assumed for the use or reliability of software on equipment that is not supplied by Digital
Equipment Corporation or its affiliated companies.

Printed in U.S.A.
The READER’S COMMENTS form on the last page of this document requests the user’'s critical evaluation to

assist in preparing future documentation.
The following are trademarks of Digital Equipment Corporation:
DEC

ULTRIX

VMS

DECnet

UNIBUS

MASSBUS

VAX

XMI

RSX

VAXBI

SBi

VAXcluster

mflgnan

HOW TO ORDER ADDITIONAL DOCUMENTATION

DIRECT MAIL ORDERS

uUsA”

CANADA

INTERNATIONAL

Digital Equipment Corporation
P.O. Box CS2008
Nashua, New Hampshire 03061

Digital Equipment
of Canada Ltd.
100 Herzberg Road
Kanata, Ontario K2K 2A6
Attn: Direct Order Desk

Digital Equipment Corporation
PSG Business Manager
c/o Digital’s local subsidiary
or approved distributor

In Continental USA, Alaska, and Hawaii call 800-DIGITAL.
in Canada call 800-267-6215.
*

Any order from Puerto Rico must be placed with the local Digital subsidiary (809-754-7575).
Internal orders should be placed through the Software Distribution Center (SDC). Digital Equipment Corporation. Westminster, Massachusetts 01473,

This document was prepared using VAX DOCUMENT, Version 1.1.

Contents
xvii

PREFACE

WHAT IS A DIAGNOSTIC PROGRAM?

1-1

1.1

INTRODUCTION

1-1

1.2

USES OF DIAGNOSTIC PROGRAMS

1-1

1.3

DEFINITIONS

1-1

1.4

USERS AND THEIR NEEDS

1-2

1.5

RUN-TIME ENVIRONMENTS

1-3

1.6

TESTING GOALS

1.7

LOGIC TESTS, FUNCTION TESTS, AND EXERCISERS

1-7

1.8

SERIAL AND PARALLEL TESTING

1-7

1.9

BOTTOM-UP AND TOP-DOWN TESTING

1-7

1.10

MACROPROGRAMS AND MICROPROGRAMS

1-8

VAX DIAGNOSTIC PROGRAMS

2-1

2.1

INTRODUCTION

2-1

2.2

RUN-TIME ENVIRONMENTS FOR VAX DIAGNOSTIC PROGRAMS

2-1

CHAPTER 1

'CHAPTER 2

‘

1-5

Contents

THE VAX DIAGNOSTIC SUPERVISOR

2-2

2.4

INTRODUCTION TO THE VAX DIAGNOSTIC STRATEGY

2-3

2.5

METHODS OF PERFORMING 1/0

2-6

2.6

APPLYING THE VAX DIAGNOSTIC STRATEGY

2-8

2.6.1

Testing the CPU Ciuster

2-8

2.6.2

Testing Peripheral Devices

2-9

2.7

CHAPTER3

3.1

3.2

GUIDELINES FOR WRITING VAX DIAGNOSTIC PROGRAMS

2-10

2.7.1

Level 1 Guidelines

2-10

2.7.2

Level 2R Guidelines

2-10

2.7.3

Level 2 Guidelines

2-11

2.7.4

Level 3 Function Tests Guidelines

2-11

2.7.5

Level 3 Logic Test Guidelines

2-11

2.7.6

Level 4 Guidelines

2-12

2.7.7

Level 5 Guidelines

2-13

CORE COMPONENTS OF A VAX/DS DIAGNOSTIC
PROGRAM

3-1

INTRODUCTION

3-1

3.1.1

Overview of the VAX Diagnostic Supervisor

3-1

3.1.2

Overview of a VDS Diagnostic Program

3-2

3.1.3

Memory Layout

3-4

P-TABLES

3-5

3.2.1

Introduction to P-Tables

3-5

3.2.2

P-Table Format

3-7

3.2.3

P-Table Descriptors
3.2.3.1

3.2.3.2
3.2.3.3
3.234

Introduction to P-Table Descriptors ¢ 3-10
Creating P-Table Descriptors ¢ 3-11

3-10

Creating Names for Device-dependent Fields ¢ 3-14
Location of P-Table Descriptors ¢ 3-15

3.2.4

Referencing P-Tables from a Diagnostic Program

3.2.5

Attaching from Within the Diagnostic Program

____

3-15

3-18

Contents

3.3

DIAGNOSTIC PROGRAM GLOBAL DATA STRUCTURES
Diagnostic Program Header
3.3.1
Dispatch Table
3.3.2
Program Sections Table
3.3.3
Device Mnemonics List
3.3.4

3-18
3-18
3-19
3-19
3-19

3.4

PROGRAM PASSES AND SUBPASSES

3-19

3.5

INITIALIZATION CODE
Format of the Initialization Code
3.5.1
Services Used by the Initialization Code
3.5.2
Logical Units
3.5.3
Program Passes and the Initialization Code
3.5.4
Initialization Code Examples
3.5.5

3-20
3-20
3-20
3-21
3-21
3-22

3.6

CLEANUP CODE

3-23

3.7

SUMMARY ROUTINE

3-23

3.8

TESTS, SUBTESTS, AND SECTIONS
Tests
3.8.1
Subtests
3.8.2
Sections
3.8.3

3-24
3-24
3-25
3-26

3.9

REPORTING ERRORS
Error Message Formats
3.9.1
VDS Control Flags Associated with Error Reporting
3.9.2
Error Types
3.9.3

3-26
3-26
3-28
3-28

LOOPING
3.10.1 Defining Loop Boundaries
3.10.2 Characteristics of Loops
3.10.3 Nesting Loops
3.10.4 User-Specified Looping

3-30
3-30
3-32
3-33
3-34

3.9.3.1
3.9.3.2
3.9.3.3
3.9.3.4
3.9.3.5

3.10

Preparation Errors ¢ 3-28
Soft Errors ¢ 3-29
Hard Errors » 3-29
Device-Fatal Errors ¢ 3-29
System-Fatal Errors ® 3-30

Contents

3.11

CHAPTER 4

CONDITIONAL AND UNCONDITIONAL BRANCHING

3-34

ADDITIONAL COMPONENTS OF A VAX/DS DIAGNOSTIC
PROGRAM

4-1

4.1

INTRODUCTION

4-1

4.2

INPUT/OUTPUT

4-1

4.2.1

4.2.2

I/0 with the Unit Under Test
I/O in User Mode ¢ 4-1

4.2.1.2

I/0 in Standalone Mode ¢ 4-5

1/0 with the User Terminal

4.4

4-7

4.2.2.1

Message Display

4.2.2.2

Prompting the User » 4-8
Displaying HELP Text ¢ 4-10

4.2.2.3

4.3

4-1

4211

4-7

MEMORY MANAGEMENT AND ALLOCATION

4-10

4.3.1

Memory Management in User Mode

4-10

4.3.2

Memory Management in Standalone Mode

4-10

4.3.3

Memory Allocation

4-11

SYNCHRONOUS AND ASYNCHRONOUS EVENTS

4-12

4.4.1

Introduction

4-12

4.4.2

Event Flags

4-12

4.4.3

Asynchronous System Traps (ASTs)

4-13

4.4.4

4431

AST Delivery » 4-13

4.4.3.2

AST Routines * 4-14

Timing

4-14

4.4.4 1

Timing Facilities Available in User Mode and

4.4.4.2

Timing Facilities Available in Standalone

Standalone Mode ¢ 4-15
Mode Only e 4-16

4.5

4.4.5

Condition Handling

4-16

4.4.6

Handling Control-Cs

4-19

FILE MANAGEMENT

4-20

4.5.1

Introduction

4-20

4.5.2

VDS RMS Overview

4-21

4.5.3

The FAB, RAB, and XAB

4-22

4.5.4

Accessing the VDS RMS Control Structures

4-22

Contents

4.5.5
4.5.6
4.5.7
4.5.8
4.6

4-23
4-23
4-25
4-25

Reading Files
Record Processing
Block Processing
Mixing Block Processing and Record Processing

4-25
4-26
4-26
4-27
4-28
4-29
4-29
4-30
4-30

VDS IN A MULTIPROCESSOR ENVIRONMENT
General Concepts
4.6.1
Multiprocessing Macros
4.6.2
Executing in an Attached Processor
4.6.3
Using VDS System Services
4.6.4
Memory Management
4.6.5
Timing
4.6.6
Input/Output
4.6.7
Events
4.6.8
4.6.8.1

The SCB » 4-30

4.6.8.3

Interprocessor Interrupts ¢ 4-31

4.6.8.4
4.6.8.5
4.6.8.6

ASTs ¢ 4-31
Control-Cs ¢ 4-31
Breakpoints ¢ 4-31

4.6.8.2

4.6.9

4.6.10

Exceptions and Unexpected Interrupts ¢ 4-30

Communication Between the Primary and Attached

4-32
4-32

Processes
Restrictions

VDS MACROS AND SYSTEM SERVICES

5-1

5.1

INTRODUCTION

5-1

5.2

CODING SYSTEM SERVICE MACRO CALLS
Fields of the Macro Name
5.2.1
Macro Arguments
5.2.2
Use of RO and R1
5.2.3

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

CHAPTER 5

Return Status Codes

5-4

5.3

CONVENTIONS USED IN THIS CHAPTER

5-5

5.4

SYSTEM SERVICE DESCRIPTIONS

5.2.4

$DS_ABORT
$DS_S$ADD
$ASCTIM
$DS_ASKADR
$DS_ASKDATA
$DS_ASKLGCL

5-7
5-8

5-6

5-10
5-12
5-16
5-19
vii

$DS_ASKSTR

Contents

$DS_ASKVLD
$ASSIGN
$DS_ATTACH
$DS_BCOMPLETE
$DS_BERROR
$DS_BGNATTACHED
$DS_BGNCLEAN
$DS_BGNDATA

$DS_BGNINIT
$DS_BGNMESSAGE
$DS_BGNMOD
$DS_BGNREG
$DS_BGNSERV
$DS_BGNSTAT
$DS_BGNSUB
$DS_BGNSUMMARY

$DS_BGNTEST
$BINTIM

$DS_BITDEF

$DS_CHSDEF
$DS_CKLOOP
$DS_CLI

$DS_CLIDEF

$CLOSE
$CLREF

NNSNNSNOOO®

oTM

5-100

$CONNECT

5-103

$DS_CVTREG
$DS_$DECIMAL
$DEF

$DS_DEFDEL

$DS_CLRVEC
$DS_CNTRLC
$DS_$COMPLEMENT

$DASSIGN

vili

[
B

$DS_CHMDEF

$DS_CHANNEL
$DS_CHCDEF

$DS_CANWAIT
$DS_$CASE
$DS_CFDEF

$CANCEL
$CANTIM

$DS_BQUICK
$DS_BREAK

$DS_BOPER
$DS_BPASSO0

$DS_BNQUICK
$DS_BOOTATTACHED

$DS_BNPASSO

7 e PERTLY
|
|
Ceeereeeey TeeLYYy

$DS_BNERROR

$DS_BNOPER

DA DDOAOIONINT
WM
OO ~NOY, &N =0 0voom®

$DS_BNCOMPLETE

5-102

5-105
5-110

5-111
5-113
5-114

Contents

$DEFEND
$DEFINI
$DS_DEVTYP

5-115

$DISCONNECT

5-118

$DS_DISPATCH
$DS_DSDEF

5-120

$DS_DSSDEF
$DS_SEND

5-122

$DS_ENDATTACHED

5-124

_$DS_ENDCLEAN
$DS_ENDDATA

5-126

5-128

$DS_ENDINIT
$DS_ENDMESSAGE

5-130

$DS_ENDMOD

5-134

$DS_ENDPASS
$DS_ENDREG
$DS_ENDSERV

5-135

$DS_ENDSTAT
$DS_ENDSUB

5-138

$DS_ENDSUMMARY

5-140

$DS_ENDTEST
$DS_ERRDEF

5-141

$DS_ERRDEV

5-144

$DS_ERRHARD
$DS_ERRNUM
$DS_ERRPREP

5-149

$DS_ERRSOFT
$DS_ERRSYS

5-160

$DS_ESCAPE
$DS_EXIT

5-170

$FAB

5-174

$FAB_INIT

5-180

$FAB_STORE

5-181

$FAO
$FAOL

5-182

$DS_$FETCH

5-188

$GET

5-190

$DS_GETBUF
$GETCHN
$DS_GETTERM

5-192

$GETTIM

5-201

$DS_GPHARD
$DS_HALTATTACHED

5-202

$DS_HEADER
$DS_HELP

5-206

$DS_$HEX
$HIBER

5-209

$DS_HPEO_DECL

5-212

$DS_HPEODEF

5-213

$DS_HPO_DECL
$DS_HPODEF

5-214

$DS_$INITIALIZE
$DS_INITSCB

5-216

5-116
5-117

5-121
5-123

5-132

5-136
5-137

5-139

5-143

5-154

5-155

5-165
5-172

5-185

5-195

5-199

5-204

5-208
5-211

5-215

5-218

Contents

$DS_INLOOP

5-219

$DS_LOAD
$DS_SLITERAL

5-220
5-223

$DS_$LOGICAL

5-224

$DS_MEMSIZE
$DS_MMOFF

5-225

$DS_MMON
$DS_$NAME

5-226

5-228

5-230

$DS_$OCTAL

5-233

$OPEN

5-235

$DS_PAGE

5-237

$DS_PARDEF

5-238

$DS_PARSE

5-239

$DS_PRINTB

5-243

$DS_PRINTF

5-250

$DS_PRINTREV
$DS_PRINTS

5-259

5-253

$DS_PRINTSIG

5-262

$DS_PRINTX

5-263

$DS_PROBE

5-266

$DS_PSLDEF

5-268

$DS_PTDDEF

5-269

$Qio
$sQlow
$RAB

5-270
5-273
5-276

$RAB_INIT

5-280

$RAB_STORE

5-281

$READ

5-282

$READEF

5-284

$DS_RELBUF
$DS_SBTTL

5-286

$DS_SCBDEF

5-289

$DS_SECDEF

5-290

$DS_SECTION
$SETAST

5-292

5-288

5-291

$SETEF

5-293

$SETIMR

5-294

$DS_SETIPL

5-298

$DS_SETMAP
$SETPRT

5-299

5-303

$DS_SETVEC

5-306

$DS_SHOCHAN
$DS_SHOWIDLE

5-310

5-309

$DS_STARTATTACHED

5-312

$DS_$STORE

5-314

$DS_STRING
$DS_$STRING

5-318

$DS_SUMMARY
$UNWIND

5-316
5-320
5-321

$WAITFR

5-324

$DS_WAITMS

5-326

$DS_WAITUS

5-328

$WAKE

5-330

Contents

5-332

$WFLAND
SWFLOR
$XABFHC

CHAPTER 6
6.1

6.2

6.3

6.4

5-334

5-336

CREATING A VDS DIAGNOSTIC PROGRAM

6-1

INTRODUCTION

6-1

PROGRAM DEVELOPMENT PROCESS

6-1

6.2.1

Overview

6-1

6.2.2

Consultation Phase

6-1

6.2.3

Planning Phase

6-2

6.2.4

Functional Specification Phase

6-2

6.2.5

Design Phase

6-2

6.2.6

Design Implementation Phase

6-3

6.2.7

Design Verification Phase

6-4

PROGRAM STRUCTURE

6-4

6.3.1

Header Module

6-4

6.3.2

Test Modules

6-5

6.3.3

Module Templates

6-6

PROGRAM DOCUMENTATION

6-6

6.4.1

Introduction

6-6

6.4.2

Documentation File

6-7

6.4.3

Source Code Documentation

6-9

6.4.4

6.4.3.1

Diagnostic Codes * 6-9

6.4.3.2

Module Names ¢ 6-9

6.4.3.3
6.4.3.4
6.4.3.5

Module Cover Page ¢ 6-9
Test and Subtest Prefaces ¢ 6-9
Subroutine Preface ¢ 6-10

6.4.3.6

Source Code Comments ¢ 6-11

Help Files
6.4.4.1
6.4.4.2
6.4.4.2.1
6.4.4.2.2
6.4.42.3

6.4.4.3

6-13
Description of Help Files ® 6-13
Creating Help Files » 6-13
Numbered keywords ¢ 6-14
Qualifier keywords ¢ 6-15
Texte 6-15
Contents of Help Files ® 6-15

Contents

6.5

DIAGNOSTIC PROGRAM CONSIDERATIONS

6-16

6.5.1

Run-Time Environments

6-16

6.5.2

Error Message Formats

6-17

6.5.3

Volume Verification

6-18

6.5.4

Long Silences

6-19

6.5.5

Hardware Preparation

6-20

6.5.6

Manual Intervention

6-20

6.5.7

Quick Mode

6-21

6.5.8

Naming Symbols

6-21

6.6

LINKING A DIAGNOSTIC PROGRAM

6-23

6.7

DEBUGGING A DIAGNOSTIC PROGRAM

6-23

6.8

QUALITY ASSURANCE

6-24

6.8.1

6-24

Quality Requirements
6.8.1.1

6.8.2

APPENDIXA

Functional Quality ¢ 6-24

6.8.1.3

Operational Quality ¢ 6-25

Automated Quality Assurance

6-28

TEMPLATE FOR THE VDS DIAGNOSTIC PROGRAM

HEADER MODULE

A-1

A.1

HEADER MODULE TEMPLATE FOR MACRO-32 PROGRAMS

A-1

A.2

HEADER MODULE TEMPLATE FOR BLISS-32 PROGRANS

A-9

APPENDIXB

xii

Documentation Quality ¢ 6-24

6.8.1.2

TEMPLATE FOR VDS DIAGNOSTIC PROGRAM TEST

MODULES

B-1

B.1

TEST MODULE TEMPLATE FOR MACRO-32 PROGRAMS

B-1

B.2

TEST MODULE TEMPLATE FOR BLISS-32 PROGRAMS

B-6

Contents

APPENDIXC TEMPLATE FOR DIAGNOSTIC PROGRAM
DOCUMENTATION FILE

C-1

C.1

ABSTRACT

Cc-3

C.2

HARDWARE REQUIREMENTS

C-3

SOFTWARE REQUIREMENTS

Cc-3

C.4

PREREQUISITES

Cc-3

C.5

OPERATING INSTRUCTIONS
C.5.1
Options
C.5.2
Event Flags

C-3
C-3
C-3

C.6

PROGRAM FUNCTIONAL DESCRIPTION
C.6.1
Program Overview

C-3
C-3

C.6.2

Program Size

C-4

C.6.3
C.6.4

Program Run Times
Run-Time Dynamics

C-4
C-4

C.6.5

Fault Detection

C-4

C.6.6

Performance During Hardware Failures

C-4

C.6.7

Program Applications

C-4

C.6.8

Test Descriptions

C-4

C.7

MAINTENANCE HISTORY

C-4

APPENDIXD SAMPLE HELP FILE

D-1

INDEX

xiii

Contents

EXAMPLES
3-1

Program Flow

3-2

Device-Dependent Field Declaration for the KDB50 Controller

3-3

P-Table Descriptor for KDB50 Controller

3-13

3-4

Sample ATTACH Dialogue

3-14

3-5

Referencing a P-Table in a MACRO-32 Program

3-16

3-6

Referencing a P-Table in a BLISS-32 Program

3-7

Computing the Base Address of the Extended P-Table

3-3
___

3-11

3-17
__

3-18

3-8

Initialization Code for Serial Testing

3-22

3-9

Initialization Code for Parallel Testing

3-22

3-10

Sample Error Message Using $DS_PRINTB

3-11

Sample Error Message Using $DS_PRINTB and $DS_PRINTX

3-27

4-1

Record Processing with RMS

____

3-28
4-24

FIGURES

xiv

2-1

Hardware Environments for VAX Diagnostic Programs

3-1

2-5

VDS Overview

3-2

VDS Memory Layout

3-4

3-3

Sample Hardware Configuration and Associated P-Tables

3-6

3-4

P-Table Layout

3-8

3-5

Legal and illegal Usage of Subtests

3-25

3-6

Examples of Loop Boundaries

3-31

3-7

Proper and Improper Branching Within Loops

3-32

3-8

Nesting Loops

3-33

4-1

$Ql0 Function Code and Modifier Fields

4-3

4-2

I/0 Status Block Format

4-4

4-3

Typical $QIO Diagnostic Buffer Format

4-4

Argument List Passed to an AST Routine

4-14

4-5

Argument List Passed to a Condition Handler

4-17

4-6

Format of Signal Array

4-18

4-7

Format of Mechanism Array

4-18

4-8

State Diagram for an Attached Processor

4-27

5-1

Quadword String Descriptor

5-2

Valtab Table Format

5-14

5-3

Argument List Format for $DS_BGNDATA

5-41

5-4

Adapter Status Format

5-78

5-5

Sample Parse Tree

5-6

$DS_CVTREG Value Mnemonics Table Usage

5-107

5-7

Device Characteristics Buffer (Standalone Mode)

5-197

5-8

Format of Terminal Characteristics

5-199

4-5

5-5

5-93

Contents

TABLES
2-1

2-2
2-3
4-1

Program Levels and Run-Time Environments
Hardware Environments and Hardcore Requirements
I/0 Methods and Program Types
Device-Independent Read and Write Functions

5-3

Comparison of VAX-11 RMS and VDS RMS
State Transitions for an Attached Processor
Algorithm for Demonstrating Use of $DS_BREAK
FAB Fields Used by $CLOSE (Standalone Mode)
RAB Fields Used by $CONNECT (Standalone Mode)
RAB Fields Used by $DISCONNECT (Standalone Mode)

5-4

FAB Fields

5-178
5-191

5-6

RAB Fields Used by $GET (Standalone Mode)
FAB Fields Used by $OPEN (Standalone Mode)

5-7

FAO Directives

5-246

5-8

FAO Field Lengths and Fill Characters

5-248

5-9

Revision Number to Letter Conversion

5-256

5-10

RAB Fields

5-278

RAB Fields Used by $READ (Standalone Mode)
Letters Used to Indicate Data Types

5-283

4-2
4-3
4-4

5-1

5-2

5-5

5-11

6-1

4-33
5-97

5-104
5-119

5-236

6-22

Preface
Intended Audience
This manual is intended for all diagnostic programmers.

Structure of This Document
This manual contains six chapters:

Chapters 1 through 4 discuss the fundamentals of a VAX/DS diagnostic

program.

Chapter 5 provides detailed reference information on each VAX

Diagnostic Supervisor macro and system service.

Chapter 6 describes the necessary steps required to create a VAX/DS

diagnostic program.

Associated Documents
Diagnostic program users will find the VAX/DS Diagnostic Supervisor
User’s Guide helpful.

The following documents may also be useful:
e

VAX Diagnostic Software Handbook

VAX/VMS System Services Reference Manual

VAX/VMS I/O User’s Guide

VAX Architecture Reference Manual

Conventions Used in This Document
Convention

Meaning

BOLD

Introduces new terms.

italics

Used for emphasis and indicates the title of a manual.

KEYWORD

Keywords are capitalized.

[

Square brackets indicate that the enclosed element is
optional.

DS> LOAD EVXYZ.EXE

Command examples show the VAX/DS prompt DS >.

xvii

Whatls a Diagnostic Program?

1.1

Introduction
This chapter presents an introduction to diagnostic program design. It

discusses the uses and users of diagnostic programs, the testing goals any

diagnostic program design should meet, and the various methods used to
test hardware. It also discusses those characteristics which are common to
all diagnostic programs, regardless of the hardware they are designed to
execute in or test.

1.2

Uses of Diagnostic Programs
A diagnostic program is any program designed specifically to discover and
identify hardware failures in a computer system. Diagnostic programs are

typically used in the following situations:
*

During execution of applications or systems programs, the system

produces unexpected events or incorrect computation results. This
indicates a malfunction, possibly hardware.

During the manufacturing stage, every device and system must be
thoroughly tested before it is shipped to a customer.

During the product design stage, the functionality of a product must be
verified.

1.3

Definitions
The following are some commonly used terms:

System under test (SUT). The hardware system on which a diagnostic
program is executed.

Unit under test (UUT). The device tested (part of the SUT). The UUT is
defined by the diagnostic program and can be one drive of a particular
device type or an entire subsystem of the SUT, such as one of the
remote nodes of a host system.

Hardcore. The portion of the SUT’s hardware that must operate
properly for the diagnostic program to execute. Programs that
test peripheral devices typically have a hardcore consisting of the
processor, main memory, and a program load device. A program’s
hardcore should never include any portion of the UUT.

Field-replaceable unit (FRU). Any portion of the UUT that can be easily
and quickly replaced at a customer’s site (for example, a logic board).

1-1

What Is a Diagnostic Program?

1.4

Users and Their Needs
Diagnostic programs are used in a variety of environments, and therefore

the users (operators) of these programs are also varied. When a diagnostic
program is used to identify problems in a system at a customer site,
the program may be run by a customer service representative or by the
customer. Diagnostic programs used to verify devices and systems may be
run by a technician at the manufacturing site. Diagnostics may be loaded
and run using an automated method requiring no operator. New systems,
upon arrival at a customer site, must be verified by a customer service
representative. Design verification, via diagnostic programs, may be done

by an engineer.
Because of the diversity of users, it is important that the writers of

diagnostic programs are aware of the users. Some programs are intended
for a specific audience, allowing the program to be tailored. However,
most programs are intended for a wide range of users and must be written

so that they are useful to all of them.
All users of diagnostic programs have specific needs that diagnostic
programs must fulfill. One common goal for all users (customers, customer

service representatives, technicians, engineers, etc.) is coverage, the ability
to find as many failures as possible. Every user expects that if a fault exists

on the device being tested, a diagnostic program will detect that faulit.
The most important goals for customers are:
*

Ease of use. The functions of diagnostic programs relate to internal

system hardware, and therefore are very technical. Customers should
not be required to understand all the operations which take place in the
diagnostic program. Therefore, the human interface must be simple.
For example, installing cables, setting switches on logic boards, and

requesting information such as CSR addresses or device priority levels
are all to be avoided if possible.
®

Preservation of user data. Since device media may contain data needed

by the user, diagnostic programs must provide safeguards against
destruction of this data. This is generally accomplished by writing only
on media designated for diagnostic use. Some disks provide specific
sectors that are used only for diagnostic purposes.
®

Usage of system during diagnosis. A large system at a customer site

will usually be timeshared by many users. If the users cannot use the
system while diagnostic programs are running, significant loss to the
customer can occur. Therefore, diagnostic programs should operate

under the user’s operating system and not preempt other system users.
The most important goals for customer service representatives are:
®

Quick fault detection. The faster a customer service representative

arrives at a site, fixes the problem, and leaves, the happier the
customer will be.
*

Identification of bad field-replaceable units. The diagnostic program
should be able to report to the customer service representative which

FRU should be replaced.

What Is a Diagnostic Program?

Good program documentation. To identify a failure, it is often
necessary for the customer service representative to understand what
functions a diagnostic program is performing. Therefore, the program
should be well documented with detailed functional descriptions of
each test.

The goals of a manufacturing team depend on which phase of the
manufacturing process a diagnostic program is used:

In the module test phase. Quick error detection is valued, particularly
in high volume settings. Good error identification is sometimes

unnecessary because modules are sent to module repair stations
that use their own special-purpose hardware and software to identify
module failures. In other cases, module repair stations are not used
and good error identification is important.

In the device test phase. Manufacturing technicians have the same
requirements as customer service representatives. Quick error
detection is needed so the manufacturing process will not be slowed.
Error identification of an easily replaced constituent part of the
hardware system is necessary so the part can be replaced and the
device shipped while the bad part is repaired, instead of holding up
shipment of the device. Good documentation is necessary because

determining the bad part sometimes requires a thorough understanding
of the diagnostic program’s functionality.
The most important goal of design engineers is:

High coverage. Every section of the logic should be tested by the
diagnostic. Any section that is not tested may contain a design flaw
that may not be caught until after the hardware is in production,
necessitating an engineering change order (ECO).

It is important to note that user requirements often vary depending on the
product. For example, program requirements specified by manufacturing
personnel will depend on the manufacturing site’s testing strategy for the
product. This strategy is often not the same for different products. The
program developer must maintain close communication with the program’s
eventual users in order to meet the needs of those users.

1.5

Run-Time Environments
The variety of uses and users of diagnostic programs creates a variety of
“run-time environments’’ in which diagnostic programs must be able to
execute. A run-time environment is the control-level software on which the
diagnostic program must run. Some diagnostic programs cannot function
in all run-time environments. The environments in which a program is
designed to run are determined by the purpose the program is to serve.
In the ““user mode”’ run-time environment, a timesharing operating system
is executing on the system tested. There could be many users on the

system at the time a diagnostic program is run, and the diagnostic program
is just another user of the system. The diagnostic program should not

affect any other user on the system. (The operating system will prohibit
the diagnostic program from exceeding its bounds.) Often, the device
1-3

What Is a Diagnostic Program?

tested is assigned exclusively to the diagnostic program, and the device’'s
storage medium must be replaced with a “’scratch” medium the diagnostic
program can use to write test patterns. Some 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 diagnostic program uses
this reserved area and other users of the device are unaffected.
The opposite of the user mode run-time environment is the ‘“standalone
mode’’ environment. In standalone mode, the diagnostic program has

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

boundaries on the diagnostic program. Thus, the diagnostic program
can run in privileged execution modes and use reserved registers and
memory space. Sometimes in standalone mode a monitor or other type

of control program provides services to and controls execution of the
diagnostic program. However, this type of monitor will not place execution
constraints on the diagnostic program.

The advantage of standalone mode over user mode is that the lack of

execution boundaries sometimes offers a greater level of resolution in
error identification. The disadvantage is that the computer’s operating

system must be brought down, costing the customer time and money. This
disadvantage does not exist when these programs are used on new systems
at the manufacturing site.

This description of user and standalone modes implies that the computer
system under test is not connected to another system by means of any

type of network used for system diagnosis. However, there are networks
that are used to load and run diagnostic programs, increasing the number
of run-time environments with which to be contended. Networks are
commonly used at manufacturing sites, where it is necessary to test a large
number of systems at once. Typically, a host processor will maintain upto-date copies of all diagnostic programs. The system to be tested will be

connected to the host, and the host will transmit the appropriate programs
to the test system. The programs will be executed in the test system’s
processor, but the host will monitor the performance of the programs and
note any errors that occur.

Networks can also be used to diagnose systems at customer sites.
In this case, a centrally located host system can use phone lines to

“call” a customer’s system. The host can then monitor diagnostic

programs executed on the system tested and provide customer service

representatives with the results of the tests. This can greatly decrease the

amount of time customer service personnel must spend at the customer’s
site; because 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.

What Is a Diagnostic Program?

1.6

Testing Goals
All diagnostic programs have the same testing goals, regardless of what
they test, what their execution environments are, or who the main users
are. The goals are:

Clearly define the testing scope and required hardcore. The “testing
scope’’ is that portion of the hardware logic which the program tests.
It should never extend beyond the boundaries of the unit under test.
For example, consider a disk controller that can support several drives.
A diagnostic program to test the controller should not detect faults on
the drives, unless it cannot be avoided. Signals generated in the logic
should be limited to those areas meant to be tested by the diagnostic
program. (The fewer stray signals there are in the system, the easier it
will be to identify the failure.)
The hardcore required by the diagnostic program should be as small
as possible. Testing almost any peripheral device requires some
correctly functioning logic that signals must pass through in order
to get to and from the UUT. The smaller this hardcore, the more
likely that a diagnosis of the UUT can be made without finding other
errors within the the system but outside the scope of test, which could
invalidate the diagnosis. For example, a program designer writing a
diagnostic program for a disk might have the option of having memory
management on or off while the program is running. Having memory
management on will increase the hardcore for the diagnostic program,
and the program will not be able to test the disk if there are errors in
the memory management logic.

Detect any and all failures that could occur within the testing scope.
If any part of the unit under test could malfunction, the 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 unit it is intended to test. For example, a diagnostic to
test a disk driver should not be expected to detect CPU problems
(although it might detect them inadvertently). This goal is clear-cut and

simple — if a malfunction occurs anywhere within the unit under test, /

the diagnostic program should detect and report it. Thus, a diagnostic
program designed to test a set of tape drive controllers and their
attached drives should be able to detect any failure occurring in either
the controllers or their associated drives. A system exerciser (designed
to validate the overall functionality of a computer system, including
the CPU, memory, and all peripheral devices) should be able to detect
errors on any device attached to the system.
Identify which part of the unit under test caused the malfunction. It is
not enough to recognize that an error has occurred. The diagnostic

program should also be able to indicate which part needs to be
repaired or replaced.

This third goal is not as clear-cut as the last one, for it involves the

concept of ““degree of resolution.”” When attempting to identify a
failing part, the diagnostic program designer must decide what the
smallest part within the system is that should be considered. Each
computer system is made up of hardware devices, which contain one
1-5

What Is a Diagnostic Program?

or several logic boards, which in turn are made up of IC chips. A
diagnostic program’s degree of resolution is a relative measure of its

ability to identify the smallest possible failing constituent part. For
example, consider a tape subsystem consisting of several tape drives

connected to one controller. A diagnostic program that could identify
the failing logic board within the failing tape drive would have a higher
degree of resolution than one that only identified the failing drive.
(““Fault isolation”” is another phrase often used to refer to the degree of

error resolution.)

A particular program’s proper degree of resolution depends on its
intended function. For example, it would be impractical for a system

exerciser (described in Section 1.7) to attempt to identify failures to
the degree of the failing chip. More likely, it would determine which
peripheral device was malfunctioning and, if the peripheral consisted

of several drives attached to one controller, which drive was in error.
On the other hand, a diagnostic program 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

by the program’s user requirements. It is not always practical to
achieve the highest possible degree of resolution, because increasing
resolution can also cause increased program size and run-time, and

may require a more highly skilled operator. In some cases, it may be
more important to keep these variables within bounds than to attain a
high degree of resolution. Unfortunately, achieving a high degree of

error resolution is sometimes more an ideal than an attainable goal.
Diagnostic programs used by customer service representatives should

ideally be able to identify the smallest malfunctioning FRU. But for

the program to identify an error as existing on one particular FRU,
two requirements must be met. First, all the hardware logic used to

execute the function that failed must reside on a single FRU. Second,
the diagnostic program must be able to determine on which FRU the
logic resides. Both these requirements can only be met through proper

hardware design of the device. Close communication between the

hardware designer and the diagnostic program designer are essential
when a new product is in development; this guarantees proper logic
partitioning along with visibility of all signals needed by the program to

achieve high error resolution.
Provide enough useful program loops so that all possible errors can be

quickly and easily detected by observing logic state transitions. It is
sometimes not possible for a diagnostic program to accurately identify

a failure to the degree of resolution desired in a particular situation. In

these cases a technician will have to determine the failing component

by examining electrical signals on logic boards with an oscilloscope.
The responsibility of the diagnostic program then is to provide the
technician with aids to locate the failure quickly and accurately. These

aids mainly consist of program loops that can be invoked if an error is
detected, and whose purpose is to provide repetitive state transitions
on small subsets of the hardware logic so that the technician can easily

observe these transitions and make sure they are taking place properly.

What Is a Diagnostic Program?

1.7

Logic Tests, Function Tests, and Exercisers
Not all diagnostic programs have the same functional goals. In general,
diagnostic programs can be divided into three groups: logic tests, function
tests, and exercisers.

A logic test verifies the device’s combinational logic, i.e., confirms that a

section of hardware logic within the device is functioning correctly. This
type of test should provide the greatest degree of error resolution. Logic
tests are usually used during the repair of a failing device, and are designed
to run in a standalone environment.
A function test verifies the functionality of a device. For example, a

function test for a disk drive would be used to verify that the functions
provided by the disk, such as reading and writing blocks of data, are
operating properly. These tests may not have as great a degree of error
resolution as logic tests. Function tests may be used to detect failures and
during the repair of failing devices. Function tests can be designed to run
in either a standalone or user mode environment.

An exerciser is used to verify that a system’s functionality can be sustained

over a period of time. They are typically designed for use on an entire
system rather than on a single device. An exerciser will simultaneously
perform repeated functional testing of every device composing the system,
in an attempt to detect both failures which result from simultaneous use of
numerous devices and failures which only occur intermittently.
For many products, both a logic test and a function test are developed.
The function test is used to detect the hardware failure and the logic test

is used during repair of the failing part. Some products have logic tests in
microprograms (see Section 1.10). The diagnostic program requirements
for every product will vary; therefore, it is important to discuss these
requirements with the program users.

1.8

Serial and Parallel Testing
Many diagnostic programs are designed to test all existences of a specific
type of device on a given system. There are two methods by which this
testing of multiple units can be accomplished: serial testing and parallel
testing. Serial testing involves testing each unit of the device individually,
sequentially. Parallel testing is the testing of all units simultaneously.Serial
testing is more likely to be found in a logic test, where it is desirable to
keep the overall level of system activity to a minimum. Parallel testing is
usually used in function tests to achieve higher levels of system activity.

1.9

Bottom-Up and Top-Down Testing
Two testing techniques, bottom-up and top-down, are used to test hardware
systems. They are generally used in combination to produce a thorough
test of the UUT.

What Is a Diagnostic Program?

Bottom-up testing involves testing a device or system by considering the

UUT to be made up of a set of layers of component parts. The lowest
layer of component parts
is the simplest and most elementary. Higher
layers depend on the proper functioning of the component parts contained
within lower layers. The simplest layer (lowest layer) is tested first; as a

layer passes the testing, it is added to the hardcore for the next layer. This
testing technique is based on a ““guilty until proven innocent’”” assumption,

i.e., a section of hardware is not assumed to be functioning properly
(“innocent”” of causing errors) until its integrity is verified.
Bottom-up testing is an integral part of logic tests. The logic must be

tested in an order such that all of the logic, through which electrical signals
must pass before reaching the logic being tested, has previously been

tested. Each section of logic is viewed as another layer which depends

on the previous sections or layers operating properly. Function tests
also use bottom-up testing. For example, a diagnostic program for a disk
should verify data reads before verifying data writes, since the data which
was written can not be checked unless the data can be read correctly.

The bottom-up technique provides a thorough, systematic, step-by-step
approach to hardware testing. However, using this method to validate an
entire system can be very slow.
Top-down testing consists of initially viewing the UUT as a whole, then
gradually subdividing the UUT into its component parts until the failing
part can be identified. This technique uses an assumption of “innocent

until proven guilty.” The program assumes everything is operating
properly unless errors are detected. An important consideration with

this approach is 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.
In practice, diagnosis of a hardware system suspected of containing

faults combines top-down and bottom-up techniques. Often, bottomup programs will be run in a top-down manner; i.e., programs written to

use the bottom-up technique are run in an order such that those which
test the largest subsystems are executed first, followed by those which test

devices which previously executed programs point out as questionable.

1.10

Macroprograms and Microprograms
Many computer processors built today have two types of programming
instructions.

““Macro-instructions’” make up the processor’s machine

language. These instructions are the ‘“moves,”” “‘branches,” arithmetic and
boolean operators, and so on, that are used to manipulate data in specific
memory locations. Programs that use these instructions, either directly
through the use of an assembly language or indirectly by using a high-level
language compiled to an assembly language, are called ‘‘macroprograms.”’
Most programs written are macroprograms.

Beneath the macro-instructions is a set of ‘“micro-instructions’’ used to

implement the processor’s machine language. Micro-instructions define
the macro-level instructions, plus the registers defined by the machine
language as existing “in the processor” (such as general-purpose registers

What Is a Diagnostic Program?

or a program counter). Micro-instructions do not execute in the system’s
main memory. Instead, they are loaded into and executed in a writable
control store (WCS). (Micro-instructions also often exist in ROMs.) Since
micro-instructions execute more rapidly than macro-instructions, it is
sometimes useful for applications or systems programmers to use the
micro-instruction set to create ‘’microprograms.”’

Developers of diagnostic programs sometimes make use of microprogramming. Programs designed to test the processor will most likely
use micro-instructions, executing them in a WCS. Some peripheral devices
possess their own microprocessors. These devices usually also have
ROMs in which diagnostic routines have been stored. In this case the

diagnostic programmer writes a macrodiagnostic program that activates the

microprograms residing in the ROM.

Parts of Chapter 2 discuss diagnostic microprograms further. However,
most of this manual concerns diagnostic macroprograms.

VAX Diagnostic Programs

2.1

Introduction
The discussion in Chapter 1 consisted of an overview of diagnostic
programs. It did not address specific types of computer systems. This
chapter introduces characteristics of diagnostic programs that are unique to
VAX.

2.2

Run-Time Environments for VAX Diagnostic Programs
VAX diagnostic programs are expected to operate in several run-time
environments. These include user mode, standalone mode, and network
environments.

The user mode environment that supports execution of VAX diagnostic
programs is the VAX/VMS operating system. For almost all devices
supported by DIGITAL under VAX/VMS, a user mode diagnostic program

must be developed. These programs are used extensively at customer sites
so that diagnostic programs can be executed without bringing down VMS
and thus locking other users out of the system under test.
Many VAX diagnostic programs are designed to execute in standalone
mode. Manufacturing sites commonly use standalone programs in order to
eliminate the need to boot VMS just to run the diagnostic programs. Since
standalone programs often provide better error detection than user mode
programs, customer service personnel sometimes must use standalone
programs at customer sites. Repair of failing device parts (after they have
been identified and removed from the system under test) almost always
involves the use of standalone diagnostic programs.

Networking environments have been developed for loading and executing
diagnostic 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 is
connected to a ‘‘mother”” system that has copies of all diagnostic programs
used. For each system to be tested, a ““script’’ is built. A script is a file
containing a list of diagnostic programs to be run, along with any run-time
parameters that must be passed to the diagnostic program. The mother
system reads this script and sends the appropriate diagnostic programs,
one at a time, to the system under test. (This is referred to as ‘’down-line
loading.””) Once a program has been sent to the system under test, it is
started and monitored by the mother system, which will note any errors
detected. When one program has completed execution, the next one listed
in the script is sent down the line and started, until all programs in the
script have been run. Programs executing on the system under test can
only run in standalone mode.

VAX Diagnostic Programs

Another example of a diagnostic network is APT/RD (for Remote
Diagnosis), which provides a method of loading and monitoring diagnostic
programs for diagnosing a system at a customer site. With APT/RD, a
temporary communications link (via phone lines) is established between

the system to be tested and a centrally located system belonging to
DIGITAL and running the APT/RD software. Once the link is established,
the central system can step through a script of diagnostic programs to

attempt to diagnose the customer’s system. Unlike the APT system used
at manufacturing sites, though, the APT/RD system usually does not

perform down-line loading of diagnostic programs. Instead, the programs
must exist on some storage medium of the customer’s 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 load medium of the system under test is malfunctioning.)

2.3

The VAX Diagnostic Supervisor
The previous chapter detailed the various uses and users of a diagnostic
program.

The above section describes the run-time environments

supported for VAX diagnostic programs. If a diagnostic program designer

had to include proper interfaces for all users and environments in each
program he or she developed, the task would become burdensome. For

this reason the VAX Diagnostic Supervisor (VDS) was developed for

diagnostic macroprograms designed to run on VAX systems. The VAX
Diagnostic Supervisor is a control program that will load, execute, and
provide run-time services to diagnostic programs.

The VDS is divided into two major sections. One section is an interface
between the VDS and the program user and is called the ““human

interface.” The other is an interface between the VDS and the diagnostic
program and is referred to as the ‘’program interface.”

The human interface consists of a command line interpreter (CLI)
that receives and processes commands typed on a terminal by a user.

Commands supported by the CLI include those for loading and running
diagnostic programs, selecting which device units to test, displaying
execution summaries, and controlling program looping.
The program interface consists of a set of service routines for service calls

from the diagnostic program to the VDS, along with a mechanism for

dispatching calls from the program to the proper routines in the VDS.
These service routines provide the diagnostic program with convenient
methods for performing device I/O, 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 Diagnostic Programs

The specific purposes of the VDS are:

Provide a common human interface for all diagnostic programs.
With the large number of VAX diagnostic programs 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 diagnostic program from the run-time environment. The
VDS performs any communication that may be needed between the
diagnostic program and the run-time environment, whether it is VMS
(user mode), APT, APT/RD, or standalone.

Insulate the diagnostic program from processor-specific hardware
differences. The VDS performs /O initialization operations that are
unique to the type of VAX processor being used. Thus, the diagnostic
program does not need to be concerned with knowing the type of VAX
processor.

Make the programmer’s job easier. Providing facilities for formatting
error messages, controlling program looping, initiating I/O activity,
manipulating files, and other services not only guarantees consistency
among diagnostic programs from the user’s standpoint, but also greatly
reduces the development effort necessary to produce a new program.

The VDS is used by most, but not all, diagnostic macroprograms written
for VAX systems, as will be shown in the following section.

Later chapters of this manual discuss the VDS in detail. The VDS is
introduced at this point in the manual because it plays a role in the VAX
diagnostic strategy.

2.4

Introduction to the VAX Diagnostic Strategy
In order to ensure a careful, comprehensive, step-by-step approach to

diagnosing problems, a strategy for diagnosing VAX systems has been
developed. This strategy, generally referred to as the “VAX diagnostic
strategy,”” has been to create a hierarchy of diagnostic programs based

on hardcore requirements. Programs higher in the hierarchy require
greater hardcore (they require a larger portion of the whole system to

be operating). These programs provide a versatile human interface and
are less likely to require exclusive use of the system under test. These
diagnostics will detect the existence of faults and help identify the region
which contains the faulty module or FRU. Conversely, programs lower in

the hierarchy will test specific devices more intensely and therefore can
identify faults. When diagnosing a customer’s system, it is recommended
to begin by using diagnostic programs which require a large hardcore
(high level), then by using lower level diagnostics as the region at fault is

identified more specifically.

VAX Diagnostic Programs

The diagnostic strategy has been implemented by creating various types, or
“levels,” of diagnostic programs. These levels are based on the following:

The VAX hardware can be divided into various building blocks. These
building blocks create a whole system when connected together, and

consist of:
—

A system console

—

A CPU “cluster”’ consisting of processor, memory, and 1/O

channels
—
*

Peripheral devices

Fault diagnosis can occur while the system’s operating system is

running.
*

The VAX Diagnostic Supervisor can be used when appropriate.

By using these considerations, a set of five program levels has been

defined. The diagnostic programs belonging to each level possess
characteristics which differentiate them from programs belonging to

the other levels. These characteristics are related to the program’s runtime environment, hardware environment (see below), and method of
performing I/O operations (see below).
Table 2-1 introduces each program level by listing its level name and the
run-time environment associated with it.
Table 2-1
Level

Program Levels and Run-Time Environments
Run-Time Environment

Runs under an operating system.

Runs under VDS in user mode only.

Runs under VDS in both user and standalone modes.

(There are no new programs which use QIQOs for this level.)
3

Runs under VDS in standalone mode only.
Runs in standalone without VDS.

Runs in WCS or system console, not in VAX main memory.

A program’s hardware environment is the minimum hardware
configuration on which the program will execute. (Do not confuse this
with the program’s hardcore, which is the minimum amount of hardware

that must be functioning properly in order for the diagnostic program to
execute. For example, the hardware environment of a program to test a

disk controller would be the CPU cluster, buses connecting the controller

to the cluster, and the controller itself, while the hardcore requirements in
this case would be the CPU cluster and the buses.)
Three different hardware environments can be defined for VAX diagnostic
programs. The hardware environments relate to the building blocks listed

above. These environments are:
1

Console environment. Consists of only the system console and the

console load device.

2-4

VAX Diagnostic Programs

CPU cluster environment. Consists of the system console, the VAX
processor, main memory, and I/O channels.

System environment. Consists of the system console, the CPU cluster,
and all attached peripherals. In other words, this is the whole system.

Figure 2-1 illustrates the hardware environments for a typical VAX
hardware configuration.

Figure 2-1

Hardware Environments for VAX Diagnostic Programs

SYSTEM ENVIRONMENT

CPU CLUSTER ENVIRONMENT
CONSOLE ENVIRONMENT

- — |

cess

CONSOLE STORAGE DEVICE

ZK-477585

The hardcore requirements and the hardware environments of the levels
vary, with both increasing as the hierarchical level increases. Thus, level
1 programs have the greatest hardcore requirements and largest hardware
environments, while level 5 programs have the least and smallest.
The hardware environment and hardcore requirements of each program
level are listed in Table 2-2.

Table 2-2

Hardware Environments and Hardcore Requirements

Level

Hardware Environment

System

Hardcore Requirements

Enough of system for the operating
system to execute

Enough of system for VMS to

execute, plus UUT

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 CPU cluster

Console, CPU cluster

Subset of console

VAX Diagnostic Programs

2.5

Methods of Performing 1/0
Perhaps the most significant difference among the various program levels
is the method of performing I/O operations. The various I/O methods
are determined by the run-time environments existing for VAX diagnostic
programs, since run-time environments generally put restrictions on 1/0O

operations.

Before discussing the methods of performing I/O operations used by

each level, it is necessary to define three types of 1/0O operations that are
provided by the run-time environments, as follows:
¢

Physical 1/0O. In physical I/O operations, references can be made to
the actual physically addressable units of the device or its storage

medium, such as sectors on a disk, ignoring any block structuring or
file-structuring algorithms that may have been created for the device by

software.

Logical I/O. For logical I/O operations, a disk-type storage device
may be referenced by addressing ““logical”’ blocks on the device

(blocks defined by software, such as the 512-byte blocks defined by
VMS). Blocks are referenced relative to the beginning of the storage

medium, and are numbered from 0 to n, where n is the last block.
File-structuring algorithms are ignored.
*

Virtual I/O. With virtual I/O operations, software-defined blocks are
referenced relative to the beginning of a file. They are numbered from
1 to n, where n is the last block in the file being referenced. This
method of 1/O takes full advantage of software-defined blocking and

file-structuring on the storage medium.

A more detailed discussion of the I/O types can be found in the VAX/VMS
I/0 User’s Guide, which should be read before the development of a level 1
or 2R program is initiated.

In level 1 programs, 1/O transfers are accomplished by issuing requests to
the operating system, such as the $QIO system service call or by using the

Record Management Services (RMS) routines of VMS. Level 1 programs
are expected to perform virtual, or sometimes logical, I/O operations,

allowing them to execute without corrupting existing data on any storage
media and thus not affecting the operation of any other processes executing
concurrently.

For level 2R programs, I/O transfers are performed by issuing the $QIO

service call, but in this case the VAX diagnostic supervisor fields the'call.
The VDS in turn passes the I/O request to VMS, where the 1/O operation is

actually performed. Level 2R programs are used for exercisers of devices

or entire systems and for functional testing of devices when one does not
want to force other users off the system.

2-6

VAX Diagnostic Programs

Physical I/O transfers are generally used in level 2R programs, since this
type of transfer allows access to all areas of the device medium and thus
provides maximum usage of the device’s logic. Physical I/O transfers
provide minimum device access time. Use of physical 1/O implies that
a “‘scratch” medium will have to be placed in the UUT in order to not

corrupt valid user data, unless the device possesses special "“maintenance

cylinders” reserved for use by diagnostic programs. It also requires that
the user of the program be granted special VMS "‘user privileges” (see
the VAX/VMS Command Language User’s Guide). While physical 1/O is most
often used, logical or even virtual I/O may be more appropriate in some

cases. Level 2 programs may also perform 1/O transfers using the $QIO

service call, with the VDS fielding the call. In user mode, the VDS passes
the request on to VMS. In standalone mode, the VDS itself services the
request. It is not clear that one diagnostic program should be written
to run in two different run-time environments, since the program is at
best a compromise of the sometimes conflicting characteristics of the two

environments (for example, ability to run with other users in user mode
versus the ability to have unlimited system access in standalone mode).
Also, the difficulty in maintaining this duplicity of functionality within the
VDS is considerable. Therefore, LEVEL 2 DIAGNOSTIC PROGRAMS
WHICH USE QIOs ARE NO LONGER BEING DEVELOPED AND WILL
NOT BE ACCEPTED FOR RELEASE.

Level 3 diagnostic programs perform their I/O operations directly. That
is, they address the device’s registers and field its interrupts. The VDS
provides services for creating a “’channel,” or addressing path, to the
device. This insulates the diagnostic program from the specific VAX
processor type, enabling the programmer to create code that does not

need to be concerned with I/O characteristics of particular processors.
Since at this program level there are no software provisions for block
formatting or file structuring, the only I/O type possible is physical. Logic

tests (see Chapter 1) are written in level 3, since this level allows relatively
comprehensive access to the device under test while also providing the
VDS’s common user and programming interfaces. Level 4 programs

are not used to test peripheral I/O devices and thus do not perform 1/O
operations. They should only be used to test those portions of the CPU
cluster environment that are considered to be a part of the VAX Diagnostic
Supervisor’s hardcore.

Level 5 programs generally do not perform I/O operations, since they are
generally microprograms used to test portions of the processor. However,
some level 5 programs (specifically those diagnostic microprograms that
test peripheral devices) may perform physical I/O operations.
Table 2-3 summarizes the /O methods used in the various program levels
and also indicates the types of diagnostic programs generally assigned to
each level.

2-7

VAX Diagnostic Programs

Table 2-3

1/0 Methods and Program Types

Level

I/0 Method

Types of Programs

Virtual or logical, using operating

System exercisers

system /O services
2R

Generally physical (but virtual or

Exercisers and function tests of

logical are allowed), using VMS

peripheral devices

QIO service
2

Physical, using VMS/VDS QIO

Function tests of peripheral devices

service
3
4

Physical, using program-defined

Function tests and logic tests of

110 functions

peripheral devices

None

Function and logic tests of CPU

cluster
5

None, or physical using program-

Microprograms

defined functions

2.6

Applying the VAX Diagnostic Strategy
Applying the VAX diagnostic strategy to a specific product usually implies

developing a set of diagnostic programs to test the product.

2.6.1

Testing the CPU Cluster
The VAX CPU cluster is tested by a set of programs, existing at several
program levels, as follows:
e

Level 5

—

Console tests

—

Processor tests

—

Memory tests

Level 4
—

VAX instruction set test (hardcore for VDS)

—

Cache and translation buffer tests (VAX-11/750 only)

Level 3
—

Memory tests (if no level 5 test possible)

—

Channel adapter tests

—

Cluster exerciser

This set of programs implements the VAX diagnostic strategy by providing

a set of building blocks by 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 the cluster.

2-8

VAX Diagnostic Programs

Level 5 programs may not exist for all VAX processors, since they are
microprograms. Ideally (but not necessarily), microdiagnostic programs
should be executed in a separate console processor (front end), making

use of a writable control store (WCS). Low-cost VAX processors may not
provide these features.

Most of the programs can be used on all types of VAX processors.
Therefore, when a new processor is developed, it is not necessary to
produce a whole new set of programs for testing the new cluster. However,
a new processor-specific module must be added to the cluster exerciser.

2.6.2

Testing Peripheral Devices
Thorough testing of a peripheral device requires the development of three

different diagnostic programs. For each device type the following will
typically (but not necessarily) exist:

Alevel 3 logic test

A level 3 function test

A level 2R function test

This group of programs implements the diagnostic strategy by providing
a facility for producing very accurate and detailed identifications of fault

conditions via the level 3 programs and by also providing a method by
which the device may be tested without bringing down the customer’s
operating system via the level 2R program.
The level 3 logic test will provide the greatest detail of error resolution,

indicating which section of logic is failing. This program will be used by
technicians to repair bad logic boards, and will provide very high test
coverage. Some devices contain ROM-resident microprograms (“‘self-

tests’”) that perform logic testing, making a level 3 logic test unnecessary.
The level 3 function test will provide a comprehensive test of all of the

device’s functions. This program will be used to determine accurately
whether or not a device is operating correctly. This is the definitive

function test and provides very high test coverage. Level 3 function tests
are usually required even if the device possesses self-testing capabilities,

because self-tests generally are not capable of complete detection of
function failures. The level 2R program will typically consist of a subset of

the level 3 function test. It will test as much of the device’s functionality
as can be tested in the user (VMS) environment. The tests it contains are
exact or approximate copies of tests existing in the level 3 program.

A typical sequence of use for these programs, when dealing with a system
at a customer site, is as follows:

The customer (or field service) suspects a fault existing in the device.

The level 2R program is run to see if the error can be detected without
stopping the operating system. If the error is found, go to step 4.

2-9

VAX Diagnostic Programs

If the level 2R program cannot identify the fault, the operating system
is brought down and the level 3 function test is run.

The fault is identified and the failing FRU is replaced. The operating

system is then brought back up.
5

The failing FRU is brought back to DIGITAL, where the level 3 logic
test, the level 3 function test, or perhaps a module test station is used

to identify the failing logic on the FRU. The FRU is repaired.

2.7

Guidelines for Writing VAX Diagnostic Programs
This section contains general guidelines that should be followed when

writing VAX diagnostic programs.

2.7.1

Level1 Guidelines
Level 1 diagnostic programs are usually used as exercisers of the entire
hardware system. Level 1 is used when it is necessary to cause various

concurrent activities to take place, using numerous types of devices and
other hardware and software resources provided by the system.

Since no standard human interface exists for level 1 programs, it is
important for the program developer to design a convenient “‘user-

friendly”’ interface, using such techniques as English-like commands,
menus, and detailed ‘‘help”” messages.

Error reporting will also be the responsibility of the program designer.

However, much use can be made of the system software’s error reporting
facilities. -

2.7.2

Level 2R Guidelines
Level 2R programs run under the VDS in user mode. These programs test
device functionality and must test as many of a device’s functions as can
be performed under the constraints of the operating system.
I/O 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/O activity is controlled by VMS device

drivers. Full use should be made of the returned error information, which
may include device register contents. All available information 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/O 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 to be performed.

2-10

VAX Diagnostic Programs

2.7.3

Level 2 Guidelines
DO NOT WRITE ANY NEW LEVEL 2 DIAGNOSTIC PROGRAMS WHICH
USE QIOs.

2.7.4

Level 3 Function Tests Guidelines
Level 3 programs run under the VDS. There is no operating system
software to limit the functionality or access rights of the diagnostic program.
However, the program should use VDS channel services (discussed in the
following chapters) for creating data paths to the device under test, in

order to eliminate the need for diagnostic programs to be concerned with

processor-specific details of bus adapter mapping.

1/0 operations are initiated and interrupts are fielded by the diagnostic
program. Since these programs have unlimited access to system hardware
resources, detailed error messages can and should be created that contain
dumps of pertinent registers.

Level 3 function tests should test every function that the device is capable
of performing. Illegal orders and combinations should also be tried.
Not only should the data transfer functions be performed, but
electromechanical functions should also be tested to ensure that they
operate within specified parameters and time intervals, as should the
operator-related functions, such as setting the write-protect switch. All
timing operations must be performed by using the timing services provided
by the VDS, since the VDS takes into account the type of VAX processor
being used and corrects for timing differences between processor types.

2.7.5

Level 3 Logic Test Guidelines
Because logic tests are designed to help technicians repair malfunctioning
logic boards, it is important that they provide good fragmentation of activity
in the logic, causing as little overall activity as possible at a given point in
execution time. Every effort should be made to concentrate electrical
activity to one small section at a time. The extent to which this is possible
depends on the particular hardware design, and it is often more of an ideal
than an attainable goal.

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

Test the interface between the device’s controller and the 1/O bus to
which it is attached, including address decoding logic and logic used in
referencing controller registers.

Test the controller’s commands and the logic associated with each
command, using the device’s “‘maintenance mode”’ if applicable.

Test the data transfer functions of the device, again using maintenance

mode.

2-11

VAX Diagnostic Programs

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

can be used.

All timing operations must be performed by using the timing services
provided by the VDS, since the VDS takes into account the type of VAX

processor being used and corrects for timing differences between processor
types.

2.7.6

Level 4 Guidelines
Level 4 programs are used only to test those parts of the system that
belong to the VDS environment’s hardcore and that are not tested by level
5 programs. For example, level 4 programs are needed to test the VAX
instruction set, the translation buffer, and cache of some (but not all) VAX

processors.

If a new level 4 program needs to be developed, the following rules should

be adhered to:
*

Use straight-line code (no subroutines). This makes it easier for the
user to step through the program when necessary.

Use a minimum instruction set, at least at the beginning of the
program.

Write the program in position-independent code, so that it may be
loaded and executed in any section of memory in case there is a bad

area of memory.

Create a section of code to handle unexpected interrupt conditions,
such as machine checks or other traps.

Do not use any terminal I/O routines unless all the logic required to
perform the I/O has been previously tested.

When an error is detected, execute the HALT instruction.

Use the general purpose registers (GPRs) to pass information to the
user. For example, on a data comparison error, the expected and actual

bit patterns can be placed in the GPRs.
e

Store the current test and subtest numbers in some location, such as

address 0, so the user can obtain them.
*

Provide very precise program documentation.

Since no terminal
displays can be provided, the user must be able to use the PC of

a failure to find out exactly what type or error occurred and what
was happening to cause the error. This information must be clearly
indicated in the program listing.

2-12

VAX Diagnostic Programs

2.7.7

Level 5 Guidelines
Level 5 programs are microprograms. Since the microcode and hardware
design of each VAX processor type is different, there must be a separate
set of level 5 programs for each processor type. Following are general rules
that should be followed when developing diagnostic microprograms:
Diagnostic microprograms should always be designed to perform
bottom-up testing.

Program loops should be as short as possible, in order to isolate
electrical activity to as small an area of the logic as possible. Ideally,
these loops should enable a technician to isolate a fault to the failing
component.
'

Error reports should be precise enough for the technician to locate the
code in a program listing. The listing should contain a clear description
of what logic was being tested and which component may be failing.
Avoid referring to components by their ““E-numbers,” since these can
be changed when ECOs are issued.
A level 5 program should be able to test every component except those
requiring an external stimulus.

2-13

Core Components of a VAX/DS Diagnostic Program

3.1

Introduction

This chapter describes the structure of a diagnostic program designed to
run under the VAX Diagnostic Supervisor (VDS). This group of diagnostic
programs is referred to as the VAX/DS diagnostic programs.

3.1.1

Overview of the VAX Diagnostic Supervisor

The VDS is divided into three major segments, each segment performing
a separate function. These segments are the command line interpreter, the
dispatcher, and the VDS macros and system services.
Command Line Interpreter

The command line interpreter provides the human interface to the
diagnostic program. It allows the diagnostic program user to select
which programs to execute, which portions of that program to run, and
which of the system’s device units to test.

The command line interpreter implements the commands described in
the VAX/DS Diagnostic Supervisor User’s Guide.
Dispatcher

The dispatcher controls the operation of the diagnostic program. It
is given control whenever the command line interpreter recognizes

a START or RUN command. The dispatcher will call the various

elements of the diagnostic program (such as the program’s initialization
code, tests, cleanup code, and summary routine, all of which are
discussed in this chapter) at the appropriate times.

VDS Macros and System Services

All linkages between the diagnostic program and the VDS are specified

by a set of macros. Some of these macros facilitate program structure,

program control mechanisms and symbol definitions; others provide
system service routines to perform functons such as error reporting,
1/O operations, and event synchronization. The system services will be
discussed in Chapter 5.

The program structure macros are used to define the various sections,
tables, and data structures making up the diagnostic program. For
example, every source module making up the diagnostic program

must be delimited by the $DS_BGNMOD and $DS_ENDMOD
macros; every test must be delimited by the $DS_BGNTEST and
$DS_ENDTEST macros. Using the program structure macros enables
the VDS dispatcher to locate and call the initialization code, tests, and
cleanup code. Most of the program structure macros are required in
every diagnostic program.

3-1

Core Components of a VAX/DS Diagr;ostic Program

The program control macros are used to affect the program’s execution
path and provide such facilities as looping and branch-on-error. For
example, the $DS_CKLOOP macro can be used to define the upper
bound of a program loop.
The symbol definition macros define global symbols used by the

other macros, the VDS, and the diagnostic program. For example,
the $DS_HDRDEF macro defines symbols for the locations within the
diagnostic program’s header (See Section 3.3.1).

Figure 3-1 illustrates the VDS segments and their relationship to a

diagnostic program.
Figure 3-1

VDS Overview

USER

COMMAND

LINE

DISPATCHER

INTERPRETER

ggl?\-/?CMES

DIAGNOSTIC

PROGRAM

UNIT UNDER TEST
ZK-4776-85

3.1.2

Overview of a VDS Diagnostic Program
Every

diagnostic

program must

possess several major
elements:
]

Initialization Code

This is code that is executed before a device unit is tested. It performs
the operations necessary for creating a data link to the unit, and
prepares the unit for testing.

Tables
There are various tables residing in the diagnostic program for the

purpose of enabling the VDS to control the diagnostic program’s
operation.

Tests

These are the actual device tests. Tests will detect errors and represent

an entity on which to loop.

3-2

Core Components of a VAX/DS Diagnostic Program

Error Reporting Routines
This code will report detected error conditions and any other pertinent
information related to the error.

C(Cleanup Code
This code performs any operations that might be needed to leave the

UUT in a state such that it is available to the next system user.
Additionally, a diagnostic program can possess other optional elements:
¢

T/O routines

Interrupt service routines

Multiprocessing routines

Note that the diagnostic program contains no dispatching mechanism. The
program should be viewed simply as a set of low-level routines to be called
by the VDS when needed.

Ilustrations of program flow for both serial testing and parallel testing of
devices follow. The program flow is accomplished through interaction

between the diagnostic program and the VDS.
Example 3-1

Program Flow

Program Flow for Serial Testing:
Get

RUN

START

command.

Get passes_requested.
Passes_executed

REPEAT

Unit_number =

REPEAT

Call

initialization code.

Call

selected

Call

summary

tests.

code.

Unit_number = unit_number
UNTIL unit_number

= max_unit_number.

Passes_executed = passes_executed +

UNTIL passes_executed EQL passes_requested.

Call

cleanup code.

Program Flow for

Parallel

Get

RUN

command.

Get

passes_requested.

START

Passes_executed =

Testing:

REPEAT

Unit_number

REPEAT

Call

initialization code.

Unit_number = unit_number
UNTIL unit_number
Call

selected

Call

summary code.

Call

cleanup

tests.

Passes_executed

UNTIL passes_executed

= max_unit_number.

= passes_executed

EQL passes_requested.

code.

3-3

Core Components of a VAX/DS Diagnostic Program

3.1.3

Memory Layout
Figure 3-2 shows the layout within memory of the various pieces of

software existing when a VDS diagnostic program is executing. All
addresses are virtual. In standalone mode, the virtual addresses are the
same as the physical addresses, so the illustration represents a true picture
of the actual program layout in memory. In user mode, VMS’ memory
management is in operation and therefore the virtual addresses shown

have no relation to the physical addresses.
The base address of a diagnostic program is 200 (hex). (When a diagnostic
program is linked, a base address of 200 (hex) must be explicitly specified.)
The loadable image of a diagnostic program may not extend beyond virtual

address FOFF (hex). Thus, the maximum size for the loadable image of a
diagnostic program is 63487 (decimal) bytes.
Addresses from FAQO to FFFF are used by the VDS to communicate with

Automated Product Test (APT). The VDS loadable image starts at virtual
address 10000 (hex). At run-time, the VDS occupies a contiguous portion
of memory starting at 10000 (hex). The total size of this area depends on
such parameters as the type of processor being used, the size of memory,

and the number of attached devices.
Two areas of memory are used to allocate buffer space to diagnostic

programs. The first area is any space that may exist between the top of the
diagnostic program’s loadable image and address FAQQ (hex). The second
(and generally larger) area consists of addresses above the highest address
used by the VDS. Allocation of this buffer space to a diagnostic program is

discussed in Section 4.3.3, Memory Allocation.

Figure 3-2

VDS Memory Layout
VIRTUAL ADDRESS (HEX)

UNUSED

0
200

DIAGNOSTIC PROGRAM

BUFFER SPACE

FOFF

AREA USED FOR APT

FA00

COMMUNICATION

10000
VDS

—

BUFFER SPACE

ZK-4777-85

3-4

Core Components of a VAX/DS Diagnostic Program

3.2

P-Tables

3.2.1

Introduction to P-Tables

In order to test a device, a diagnostic program must have access to the
device’s characteristics. Since some device characteristics are system-

specific, it is impossible to define them permanently in the diagnostic

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

A p-table is a data structure that contains device information that is
necessary for a diagnostic program to access the device. P-tables are
constructed by the VDS:

for a specific device, when the program user types the ATTACH
command (refer to the VAX/DS Diagnostic Supervisor User’s Guide).
for devices that are part of the boot path (constructed at boot time).

for all supported devices when the autosizer is run.

Once the VDS has created the p-tables, the diagnostic program can

reference the tables to obtain information necessary for testing a UUT.
When the user attaches a device, one of the parameters which must be
specified is the device’s link. The link is the piece of hardware to which
the device is connected. The link must have been previously specified
with another ATTACH command so that its p-table already exists. A set of
ATTACH commands will result in a tree structure of device links. The root
of this tree is a pseudo-device called HUB. This pseudo-device was created
because the actual hardware interconnect depends on the type of processor
being used, for example, the XMI on the VAX 6200. In general, processors
and buses are linked to HUB, adapters are linked to buses, controllers are
linked to adapters, and device units are linked to controllers. Figure 3-3
illustrates the manner in which p-tables describe a hardware system.

Core Components of a VAX/DS Diagnostic Program

Figure 3-3

Sample Hardware Configuration and Associated P-Tables

VAX62XX

CPU

EXTENDED MEMORY INTERCONNECT (XMI)

DWMBA
ADAPTER

@
RASO
DRIVEO

KDBS0
CONTROLLER

RAS0

DRIVE1
TYPE:

DWMBA

LINK:

HUB

NAME: DWMBA0 | P-TABLEFOR

XMI-VAXBI ADAPTER

DEVICE CHARACTERISTICS

TYPE:

KDB50

LINK:

DWMBAO

NAME: DUA

DEVICE CHARAC-|
TERISTICS

TYPE:
LINK:

RA%0
DUA

NAME: DUAO

P-TABLE FOR
DISK DRIVE 0

P-TABLE FOR
DISK CONTROLLER

TYPE:
LINK:
NAME:

DEVICE CHARACTERISTICS

TYPE:

KAG62A

LINK:

HUB

NAME:

KAO

RA90
DUA
DUA1

P-TABLE FOR
DISK DRIVE 1

MR-2250-RA

The p-table for a particular device will contain the informa
tion provided by
the ATTACH command arguments. Each p-table will
contain the following
standard information:
Device type — This is the product name for the device,
or DWMBA.

such as KA62A

Device’s generic name — This is the name that the device
will be
referred to, such as KAQ or DWMBA2. When possible
, the device
name will conform to VMS naming conventions.

Address of p-table for device’s link

Core Components of a VAX/DS Diagnostic Program

Device characteristics — The information which must be included in a
p-table to sufficiently describe a device. This depends on the type of
device and its link. For example, a device linked to a UNIBUS requires
the UNIBUS CSR address and bus request level, plus the device’s
interrupt vector address.

3.2.2

P-Table Format
All p-tables have a standard format. Each p-table is divided into three

sections. The first section contains device-independent fields. All p-tables

for all devices contain these fields. Each device-independent field in the
p-table has a mnemonic assigned to it which can be used by the diagnostic
program when these fields are referenced. The second section of the
p-table contains device-dependent information. This section is unique to
the type of device being described. The third section contains an extension
to the device-independent fields. (In the following discussion, references
to the device-independent section of the p-table include this extension).
Figure 3-4 shows the standard layout of all p-tables.

3-7

Core Components of a VAX/DS Diagnostic Program

Figure 3-4

P-Table Layout

0 (decimal) Ptable

HP$Q_DEVICE
HP$B_DRIVE

)

| HP$B_FLAGS

HP$W_SIZE

8
12

HP$T_DEVICE

16
20

HP$A_DEVICE

HP$A_DVA

HP$A_LINK

32
HP$W_VECTOR

36
40

HP$T_TYPE

44
48

HP$A_DEPENDENT

HPEST _DEVICE

n + 4 Extended Ptable
n+8

n+12

n+16

n+20

HPESA_EPB

HPESW_EXT_DRIVE

n+ 24

HPESA_EPB (contd)

n+28
MR-2126-S|

Below are the descriptions of the device-independent p-table fields. The

fields prefaced with HP$ are defined by $DS_HPODEF and are offsets
from the base of the p-table. The fields prefaced with HPE$ are the fields
in the extension of the device-independent p-table. They are defined
by

$DS_HPEODEF and are offsets from the base of the extended p-table block

(EPB).

3-8

Core Components of a VAX/DS Diagnostic Program

HP$Q_DEVICE — A VMS-type quadword descriptor of the device name
string (see HP$T_DEVICE below). The first word of the field contains. the

length of the device name string, and the next word is unused. The second
longword contains the address of the device name string. If the device
name conforms to the short format, that is, ggan, the second longword
contains the address of HP$T_DEVICE. If the device name conforms to the
long format, that is, name$ggan or $alloclas$ggan, the second longword
contains the address of HPE$ST_DEVICE. The field HPEST_DEVICE is
used simply because names with the long format will not fit in the field
HP$T_DEVICE.

HP$W_SIZE — The size of the entire p-table in bytes. This includes both
the device-independent and the device-dependent p-table fields.
HP$B_FLAGS — Flags used by the VDS when the device is initialized.
Flags are defined as follows:

HP$M_ALLOC — (bit 0) — If set, indicates that the VDS must request
VMS to allocate (JALLOCATE system service) the device before it can
be tested in user mode.

HP$M_WASALL — (bit 1) — Set by VDS if a device has been

HP$M_NAME — (bit 2) — Set by VDS if the device name uses the long

successfully allocated.
format.

(Bits 3-7) — Unused.

HP$B_DRIVE — The unit number of the device. This is the number
appearing at the end of the device’s generic name, such as 7 in _TTA7.
If the unit number is greater than 255, it can be accessed in the extended
p-table field, HPESW_EXT_DRIVE.

HP$T_DEVICE — An ASCII string representing the device’s generic name.

The device name is stored here only if it conforms to the short format, that
is, ggan.

HP$A_DEVICE — The virtual address of the lowest-addressed device
register. The type of register being pointed to depends on the device type.
For example, it would be a CSR for a UNIBUS device and a configuration
register for an SBI device.

The virtual address must be assigned to P1 space (bit 30 set). This is
because the VDS maps all physical I/O addresses through virtual P1 space

when memory management is enabled (standalone mode).

HP$A_DVA — This is the base of the virtual address space assigned to
this device. Devices linked to this device will have address assignments
relative to this base address. When the VDS constructs a new p-table for
a device linked to this one, it copies this field into the linked device’s
HP$A_DEVICE field. When the device address for the new device is
fetched from the user, it can be added to the base address already in
HP$A_DEVICE.

The virtual address must be assigned to P1 space (bit 30 set). This is
because the VDS maps all physical I/O addresses through virtual P1 space
when memory management is enabled (standalone mode).
3-9

Core Components of a VAX/DS Diagnostic Program

The HP$A_DVA field is not always relevant. An example of its use
is the
case of UNIBUS adapters. Each UNIBUS is assigned to a certain base
address. The addresses of devices connected to a particular UNIBUS

are added to the UNIBUS's base address to obtain the device’s actual
physical address. A UNIBUS's base address is stored in the HP$A_DVA

field for a UNIBUS's p-table. When a controller is linked to the UNIBUS,
its HP$A_DEVICE field will be initialized to the value contained in the

UNIBUS’s HP$A_DVA field. Subsequently, the user will be prompted
for the controller’s 18-bit address. This address can be stored in the loworder 18 bits of HP$A_DEVICE to result in a full physical address for the

controller.

HP$A_LINK — The address of the p-table for the device to which this one

is linked. If this device is linked to HUB, the field contains 0.

HP$W_VECTOR — If relevant, contains the vector address through which
the device will interrupt. This address is an offset into the System Control
Block (SCB).
HP$T_TYPE — Contains a counted ASCII string representing the device
type, such as KA62A, KDB50, or RA90.

HP$A_DEPENDENT — The first location of the device-dependent section
of the p-table.

HPEST _DEVICE — An ASCII string representing a device name if it is in
the long format, that is, name$ggan or $alloclas$name.

HPE$SW_EXT_DRIVE — The unit number of the device which is the number

appearing at the end of a device’s name, such as 293 in TT293. This
field

will allow the attachment of drive numbers greater than 255.

HPESA_EPB — Address of the extended p-table block. This address is
always 4 bytes less than the end of the entire p-table. It can be used to

reference the extended part of the device-independent ptable. Refer
to

Example 3-7.

The HP$W_SIZE, HP$Q_DEVICE, HP$B_DRIVE, HP$T_DEVICE,
HP$A_LINK, HP$T_TYPE, HPE$W_EXT_DRIVE, and HPE$T DEVICE
fields are filled in automatically by the VDS (when relevant). The
other
fields are loaded (if needed — not all fields are relevant to all devices)
in

accordance to directions contained in the p-table descriptors (see

below).

The fields within the device-dependent section also have mnemoni
cs, but
they are unique to the device.

3.2.3

P-Table Descriptors
3.2.3.1

Introduction to P-Table Descriptors
The VDS builds a p-table by referring to a p-table descriptor. This is
a set
of instructions that indicates the size and format of the device-d
ependent
p-table fields. When the VDS builds a p-table, it refers to the
p-table
descriptor of the specified device type in order to determine how
to
construct the device-dependent fields.

3-10

Core Components of a VAX/DS Diagnostic Program

Instructions within the p-table descriptor specify the following types of
information to the VDS:
e

The device type

A prompting message for each device-dependent hardware parameter

to be stored in the p-table

The format in which user response to the device-dependent prompts is
to be interpreted

3.2.3.2

The p-table field in which the responses to the device-dependent
prompts are to be stored

Creating P-Table Descriptors

There are two steps when you create a p-table descriptor:

Define the representation of the memory space required for the
p-table’s device-dependent fields, that is, a field declaration including
name and size of each field. When the VDS builds a p-table, skeletons

of both the device-independent and device-dependent fields are copied

into a dynamic memory storage area, and the fields are filled in with
the proper information.

Example 3-2 presents the KDB50 controller p-table field declaration

in MACRO-32 and BLISS-32. This step must be completed before the
descriptor can be written.

Example 3-2

Device-Dependent Field Declaration for the KDB50
Controller

MACRO-32:

.MACRO
SDEFINI

SGBL
$DS_KDBSO_DEF
KDBSO,$GBL,HP$A_DEPENDENT

SDEF

HP$L_KDBSO_IP

SDEF

KDBSO$L_IP,.BLKL,1

$DEF

HP$B_KDB50_BR

SDEF

KDBSOSB_BR,.BLKB,l

$DEF

SDEF
$DEF

SDEF

HP$B_KDB50_NODE_ID

KDBSO$B_NODE_ID,.BLKB,1
HP$B_KDBS0_BURST

KDBSO$B_BURST,.BLKB,1

$DEF

HP$K_KDB50_LEN

SDEF
SDEFEND
. ENDM

KDBSO$K_LEN
KDB50, $SGBL, DEF
$DS_KDB50_DEF

BLISS-32:

$DS_KDB50_DEF=
SET

KDB50$L_IP=
HP$L_KDB50_IP=

KDBS50$B_BR=

[HP$K_LENGTH+0,0,32,0],
[HP$K_LENGTH+0,0,32,0],

[HP$K_LENGTH+4,0,8,0],

[HP$K_LENGTH+4,0,8,0],
HP$B_KDBS50_BR=
KDB50$B_NODE_ID=[ HP$K_LENGTH+5,0,8,0},
HP$B_KDB50_NODE_ID=[HP$K_LENGTH+5,0,8,0],
[HP$K_LENGTH+6,0,8,0],
KDB50$B_BURST=
HP$B_KDB50_BURST=[HP$K_LENGTH+6,0,8,0]
TES,

3-11

Core Components of a VAX/DS Diagnostic Program

The device-dependent fields, defined by the field declaration are:
*

HPS$L_KDB50_IP, longword storage for the address of the UNIBUS

CSR

HP$B_KDB50_BR, byte storage for bus request level

HP$B_KDB50_NODE_ID, byte storage for node id

HP$B_KDB50_BURST, byte storage for the burst data transfer rate

Use the p-table descriptor macros to define the instructions which
will supply the device-dependent information to the p-table. Also,
you must develop instructions for filling in the following device-

independent fields, if they are relevant to the device: HP$A_DEVICE,
HP$A_DVA, HP$B_FLAGS, and HP$W_VECTOR.

The p-table descriptor macros make use of a temporary storage location
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
others can transfer thosé contents into fields of the p-table.
The following general guidelines should be followed when you create

p-table descriptor:
*

Each user prompting message should provide a clear indication
of
what information the user must provide.

Responses should be requested in a format that is relevant to the
particular type of data being requested. For example, UNIBUS

addresses should be formatted in octal instead of hexadecimal,
since that is their normal format.

Only information which is necessary to reference a device should

be included. This information may include such items as the
device’s address, interrupt vector, and bus request level (BR). Do

not include information which will only be used by one diagnostic

program; remember that a p-table for a particular device
will be

used by all diagnostic programs which test that device. Informati
on
needed by a particular program or test should be obtained
via the

$DS_ASKxxxx macros (see Chapter 5).

The p-table descriptor macros are briefly described below. For more
information, see Chapter 5.

$DS_S$INITIALIZE — This is the first macro in any p-table
descriptor. It indicates the device type, the p-table size, the

maximum number of units allowed, and the name of the

device

driver used for level 2 diagnostic programs (see Chapter 2).

$DS_$NAME — Specifies a format to which the device unit’s

generic name must conform. When possible, this format
will

conform to VMS naming conventions.

$DS_$DECIMAL, $DS_$OCTAL, $DS_$HEX, $DS_$STRING,

$DS_$LOGICAL — Each of these macros is used to obtain
hardware parameters from the user when an ATTACH comman

d
is typed. The exact macro to use depends on the format in which

the input string of the particular parameter is to be interpreted.

3-12

For

Core Components of a VAX/DS Diagnostic Program

example, the $DS_$DECIMAL macro should be used if the user is
to type a decimal number, and the $DS_$STRING macro is used
if an alphabetic string is to be typed. For each of these macros,
the programmer specifies a user prompting message. Information
is read from the ATTACH command line and stored in the value
register.

$DS_$STORE, $DS_$ADD, $DS_$FETCH — These macros are
used to manipulate data that was received from a $DS_$DECIMAL,

$DS_$OCTAL, $DS_$HEX, $DS_$STRING, or $DS_$LOGICAL
command and placed in the value register. $DS_$STORE will

place the value register’s contents into a field within the p-table.

$DS_$ADD will add the value register’s contents to the current
contents of a field. $DS_$FETCH will retreive data from a field and
place it, right-justified, in the value register.

$DS_$COMPLEMENT, $DS_$CASE, $DS_$LITERAL — These
macros are used to alter the contents of the value register.

$DS_$END — The $DS_$END macro is used to indicate the end of
a p-table descriptor.

Example 3-3 shows the p-table descriptor for the KDB50 controller.
It will supply the p-table with the necessary device-dependent and

device-independent information.

$DS_$STORE

HP$A_DEVICE, 25,7

$DS_S$STORE

HPSA_DVA, 25,7

$DS_S$LITERAL

<~"X1>

$DS_$STORE

HP$A_DVA,22,1

we
wme
wE
W

<<0,~X30>>

$DS_$CASE

p-table.

name validation.
Get

from the device-independent

field,
{See

Save

base.

Save

base.

Start

format

space

for

device

base

address

HPSA_DEVICE

section

Scorpio,

3.2.2).

make

window

<BI

$DS_$STORE

HP$B_KDB50_NODE_ID,0,8

;

the BI

node id

and

$DS_$STORE

HPSA_DEVICE, 13,4

;

it in 4

fields

$DS_$STORE

HP$A _DVA, 18,4

;

node id,

;

Node Number

(HEX)>,0,F

;

60000000.

space.

$DS_S$HEX

Generate message

requesting

then

store

the p-table:

adapter device
adapter

address

$DS_SSTORE

HP$SW_VECTOR, 2,4

;

$DS_SLITERAL

space and the adapter vector.

<N X5>

;

KDB50

fixed

$DS_$STORE

HPSW_VECTOR, 6,3

;

Store

$DS_$STORE

KDB50$B_BR, 0, 8

the

bus

$DS_SFETCH

HPS$SA_DEVICE, 0,32

the

adapter

request

fields.

Store base address of UNIBUS

$DS_S$STORE

HPSL_KDB50_IP,0,32

;

CSR

<" XF2>

;

Offset

$DS_$STORE

HPSL_KDBS50_1IP,0,8

$DS_$LITERAL

{Store in low byte).

<~X0>

;

Clear

$DS_S$STORE

HP$B_KDB50_BURST, 0, 8

;

transfer

$DS_KDB50

vector

level

$DS_$LITERAL

$DS_SEND
. ENDM

HP$A_DEVICE, 25,7

length of
Supply

$DS_SFETCH

fields

Ptd$M_Controller,
DU

device-dependent

$DS_S$Name

Supply the device type,

the macro.

KDB50, HPSK_KDB50_LEN

Include

$DS_SINITIALIZE

Name

$DS_KDB50_DEF

$DS_KDB50

.MACRO

P-Table Descriptor for KDB50 Controller

Example 3-3

in the

Init/Poll

this
the

address

burst

rate.

data

field.
by

~XF2

Core Components of a VAX/DS Diagnostic Program

Note that some fields of a p-table created from this descriptor require
several steps. For instance, the HP$A_DEVICE field is constructed by:
*

Setting the high order four bits to 6 (bit 30 indicates P1 space and bit
29 indicates VAX /O addresses).

Note: This is an important step to remember. The VDS maps P1 addresses
to I/O space when memory management is enabled. Therefore, device
addresses must be constructed as virtual addresses in P1 space. This
field will have been initialized by the VDS with the HP$A_DVA field
of the link device. For 82XX/83XX systems, the link is HUB, and
therefore the HP$A_DEVICE field is 0 and must be initialized by the
p-table descriptor.

Using the node id to set bits 13 through 16, which will select the
address space for the indicated Bl node.

In this case the contents of HP$A_DEVICE are copied into HP$A_DVA,
and bit 10 of HP$A_DVA is set.

Example 3-4 is the dialogue generated by the VDS. The first 3 prompts are
generated every time the ATTACH command is used; the last prompt is
device-specific and is defined by the p-table descriptor for the KDB50.
Example 3-4
DS>

ATTACH

Device type?

KDBSO0

Device Link?

DWMBA2

Device Name?

DUC

3.2.3.3

Sample ATTACH Dialogue

Node Number

(HEX)?

Creating Names for Device-dependent Fields
For easy reference, all device-dependent fields of a p-table should be
assigned mnemonics. These mnemonics can then be used by the p-table
descriptor macros $DS_$STORE, $DS_$ADD, and $DS_$FETCH. Also, the
diagnostic program can use the mnemonics when it references a p-table.
The field naming conventions for p-tables follow the VMS standard for data
structure naming conditions. The field name begins with the name of the
data structure (HP), followed by a dollar sign ($), followed by the data type
specifier (L for longword, W for word, and so on, as listed in Table 6-1),
followed by an underscore (_), followed by the field name. For example,
the KDB50 BI adapter p-table has a device-dependent field for storing the
node id. This field is named HP$B_NODE_ID.
Note: Many p-table descriptors were developed before this standard was

implemented. The previous standard was for field names to consist of
the device name, dollar sign, data type, underscore, field name, as in
"KDB50$B_NODE_ID. If the mnemonics for the device-dependent fields
of a particular p-table do not match the current standard, they will conform
to this old standard.

3-14

Core Components of a VAX/DS Diagnostic Program

3.2.3.4

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 is the reponsibility of the diagnostic program developer to
also create a p-table descriptor for the device. This descriptor will then be
incorporated into the VDS.

Note: It is important to work in cooperation with the VDS development group
when creating a p-table descriptor.

P-table descriptors may also be included in the diagnostic program. When
processing an ATTACH command, 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.

Including p-table descriptors in a diagnostic program has several
disadvantages:

The descriptors can only be used by the diagnostic program in which
they are defined.

The devices they describe cannot be attached until the diagnostic
program has been loaded.

These diagnostic programs are not executable under APT.

The autosizer program only supports devices for which the descriptors
reside in the VDS.

When development of a program for a new device begins, the p-table
descriptor should first be placed in the diagnostic program until the
descriptor design, and the design of the device hardware itself, has been
finalized. Once the p-table’s design is certain, it can be included in the
VDS. Only in rare instances should it be necessary to release a diagnostic
program that contains its own p-table descriptors.

3.2.4

Referencing P-Tables from a Diagnostic Program
A diagnostic program gains access to a p-table by using the $DS_GPHARD
macro. The program indicates a unit number as an argument to the macro,
and the VDS will pass the base address of the p-table for that unit to the
diagnostic program. The program can then access fields within the p-table
by using the base address and the predefined field mnemonic offsets (see
above). The $DS_GPHARD macro is discussed further in the description
of initialization code (see Section 3.5).

3-15

Core Components of a VAX/DS Diagnostic Program

Example 3-5 provides an example of referencing a p-table in a MACRO-32
program.

Notice that before the p-table field mnemonics can be

referenced, the macros which define them must be called ($DS_HPODEF
for the device-independent fields and in this case, $DS_KDB50_DEF for
device-dependent fields).
Example 3-5

Referencing a P-Table in

a MACRO-32 Program

$DS_HPODEF

;

$DS_KDB50_DEF

Define device-independent p-table fields

;

Define KDB50

device-dependent fields

« BLKL

Storage

for

- BLKL

logical

unit

Storage

for

pointer

to p~table

.ASCIC

\KDB50\

Ascii

INCL

LOG_UNIT

LOG_UNIT:
PTABLE:

number

$DS_GPHARD_S

PTABLE,

MOVAL

DEV_NAM,
RO

4(RO),

BEQL

308

Set

up pointer

Check

208:

$DS_ABORT ARG=TEST

308:

MOVZBL

HP$B_NODE_ID(R2),

MOVL

HPSL_KDBS0_IP,R4

If
If

Move

UDA

unit

re-init.

structure

last

log.

done

length

Check

characters

HPST_TYPE+4(R2)

CMPW

HPST_TYPE(R2)

units

branch

208

Use

all

(RO),

BNEQ

then

CMPL

MOVL

DS$_NORMAL

403

for

device

in PTABLE

RO,

BNEQ

PTABLE

address

CMPL

Get

desired

ADRLOC=PTABLE

name of

10s%:

DEVNUM=LOG_UNIT,

DEV_NAM:

and
of

not

node

pointer

type

first

type.

characters

it matches,
KDB50,

OK
abort

address

test

into
into

R3
R4

40S:

Note: (This code is meant only to show an example of the use of p-table

mnemonics. The function performed does not need to be included in

a real diagnostic program.)

3-16

Core Components of a VAX/DS Diagnostic Program

Example 3-6 is a BLISS-32 example of referencing a p-table. Notice
that before p-table mnemonics can be referenced, a pointer must be
declared (in this case called PTABLE) using the $DS_HPO_DECL macro
including the field declaration for the device type being tested (in this case,
a KDB50).

Notice that the HP$T prefix fields expand only to addresses. To do data
fetches from these fields, explicit field references must be made (as in the
example for HP$T_TYPE).

Example 3-6

Referencing a P-Table in a BLISS-32 Program

BEGIN
LOCAL

REF VECTOR [,

CSR :

LONG],

TEMP_ADDR : LONG,
DEVICEUNIT : WORD,

! Status return from service calls
STATUS,
{ Address of PTABLE
PTABLE : REF $DS_HPO_DECL (SDS_KDBSO_DEF);

BIND

DEV_NAM = UPLIT BYTE (%ASCIC’KDBSO’);

{ Ascii name of device

1 Get the address of the p-table for the next logical unit number.
! If the $DS_GPHARD call returns successfully, do the processing.
!

LOG_UNIT = .LOG_UNIT + 1;

STATUS = $DS_GPHARD (UNIT=.LOG_UNIT,

! Get PTABLE

;
RETADR=PTABLE)

IF .STATUS EQL DS$_NORMAL
THEN

! $DS_GPHARD worked
BEGIN
t Validate type
IF .(PTABLE [HP$T_TYPE]) NEQ .DEV_NAM
OR .(PTABLE [HP$T_TYPE] + 4)<0, 16> NEQ .(DEV_NAM + 4)<0, 16>
THEN

$DS_ABORT (ARG = TEST);

t Abort test if wrong device

NODE_ID = .PTABLE [HPSB_KDB50_NODE_ID]; ! Get BI node id
UDA_CSR = .PTABLE [HPSL_KDB50_IP]; ! Get address of UDA CSR

END
ELSE

BEGIN

! $DS_GPHARD returned error.

END

END;

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

3-17

Core Components of a VAX/DS Diagnostic Program

To reference a field in the extended part of the device-independent
p-table section, declare a pointer to the extended p-table fields using

$DS_HPEODEF, and compute the base address of the extended p-table

(See description of HPE$A_EPB, Section 3.2.2. Example 3-7 is that portion
of MACRO-32 code used to compute the base address of the extended
p-table to access the drive number for an RA90 disk drive.
Example 3-7

Computing the Base Address of the Extended P-Table

$DS_GPHARD_S

DEVNUM=LOG_UNIT,

ADRLOC=PTABLE

103:

MOVL
ADDL3

PTABLE,

HP$W_SIZE(R2),R2,R3

’

;

Get

PTABLE

’

address

;

Use

Move

;

Compute

end

3.2.5

MOVL

-(R3),R4

HPESW_EXT_DRIVE(R4),R5

;

Address

EPB

;

Accessing

log.

unit

in PTABLE

i
[4

MOVW

for

structure

size of

pointer

p-table into
extended

stored

drive number

p-table

here

field

in EPB

Attaching from Within the Diagnostic Program
It may occasionally be necessary for a diagnostic program to explicitly
attach a device instead of depending on the program user to issue an
ATTACH command. An example of this is the autosizer.

3.3

Diagnostic Program Global Data Structures
The data structures described here are used to pass information about the

diagnostic program to the VDS.

3.3.1

Diagnostic Program Header
The diagnostic program header is a data block containing various types of

information needed by the VDS, such as the program’s title and pointers
to the various areas of the program that the VDS must call during program
execution.

The header is allocated by using the $DS_HEADER macro, and must be
located at the beginning of the program. It is the first (lowest) area of
memory allocated to the program. When the program is loaded by the
VDS, the header’s first address will be location 200 (hex).
Some header entries must be initialized at assembly time using macro

arguments.

Other entries are supplied by the linker. The diagnostic
program should not alter or reference any header entries during program

execution.

3-18

Core Components of a VAX/DS Diagnostic Program

3.3.2

Dispatch Table
The dispatch table is the means by which the VDS dispatches program
control to the various tests in the diagnostic program. The table consists of
a list of addresses of the tests.

The dispatch table is defined by the $DS_DISPATCH macro. The table’s
entries (test addresses) are generated when the diagnostic program is
linked.

3.3.3

Program Sections Table
The program sections table contains character strings defining the names of
the program sections (see Section 3.8.3), as well as pointers to the sections.
The VDS uses this table when the user specifies a section name with a
RUN or START command, in order to determine if the specified section
exists and where it is located.

The program sections table is defined with the $DS_SECTION macro.

3.3.4

Device Mnemonics List
The device mnemonics list is the means by which the VDS determines
what types of devices the diagnostic program is capable of testing. When
a RUN or START command is issued by the user, the VDS compares the
device types in the device mnemonics list against the types of the selected
devices (see the VAX/DS Diagnostic Supervisor User’s Guide) to determine if
there are any selected devices that the program can test. The list has two
kinds of entries. Entries can either be addresses of counted ASCII strings
or addresses of p-table descriptors.

For device types having p-table descriptors defined within the VDS,
the device mnemonics list entry will be the address of an ASCIC string
representing the device type (for example, KDB50 and RA90).
For device types having p-table descriptors defined within the diagnostic
program, the device mnemonics list entry will be the address of the
device’s p-table descriptor.

The device mnemonics list is created and formatted by the $DS_DEVTYP
macro.

3.4

Program Passes and Subpasses
Most diagnostic programs contain several tests (see Section 3.8). It is

common for a system-under-test to have several units of the type of device
being tested.

One complete execution of all selected tests on all selected units is one
program pass.

One complete execution of all selected tests on one selected unit is one
subpass.

3-19

Core Components of a VAX/DS Diagnostic Program

For a diagnostic program using serial testing (see Chapter 1), each pass will

consist of one or more subpasses. For a diagnostic program using parallel
testing (see Chapter 1), each pass will contain only one subpass since all

devices are tested concurrently.

3.5

Initialization Code
Prior to the execution of a group of tests on a particular device, the

diagnostic program must perform some initialization functions. These
functions include obtaining the address and other characteristics of the next
unit to be tested, creating a data path to the device, and initializing program
buffers and counters, which 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 tests.

3.5.1

Formatof the Initialization Code
The format of the initialization code depends on whether the diagnostic
program performs serial testing or parallel testing of the units. For serial

testing, one unit will be initialized each time the initialization code is
executed. The VDS will dispatch control to each selected test and then call

the initialization code again so that the next unit may be initialized. For
parallel testing, each execution of the initialization code should cause all

units to be initialized.
When the VDS calls the tests, all units will be tested at once. (Note that the
VDS itself does not operate differently when parallel testing occurs instead

of serial testing. The initialization code determines the type of testing to be
performed by initializing only one device at a time for serial testing, or all
devices simultaneously for parallel testing.)

3.5.2

Services Used by the Initialization Code
The $DS_GPHARD service is very important in the initialization code.
This macro will pass the address of a p-table to the diagnostic program.
The program will then use the device parameters stored in the p-table to

determine how to reference the device.
For level 3 (standalone mode) programs, initializing a unit involves

executing the $DS_GPHARD macro to get a unit’s p-table address, and
then executing the $DS_CHANNEL macro to initialize the appropriate bus
adapter. The $DS_SETMAP macro may also be used in the initialization
code. (Both the $DS_CHANNEL and $DS_SETMAP macros may also be
used within the actual tests.)
For level 2R (user mode) programs, unit initialization will consist of

executing the $DS_GPHARD macro to obtain the unit’'s p-table address,
followed by issuing the $ASSIGN system service. Device allocation (using

the SALLOCATE system service) is requested by the VDS if the p-table
descriptor for the device indicates that the device must be allocated (see
Section 3.2.2).

3-20

Core Components of a VAX/DS Diagnostic Program

3.5.3

Logical Units
The initialization code must be written to handle an unspecified number

of logical units since the number of units will vary from system to system.

At run-time, the VDS determines the number of units that can be tested
by using the list of selected units (see the VAX/DS Diagnostic Supervisor
User’s Guide) and comparing it with the list of device types which may be
tested by the diagnostic program (as contained in the Device Mnemonics
List). One of the arguments to the $DS_GPHARD macro is the logical
unit number (LUN). If this value is greater than the actual number of
units which may be tested, the VDS will return from the $DS_GPHARD
service routine with an error status. The initialization code can then
contain a REPEAT-UNTIL loop that executes the $DS_GPHARD macro
and increments the logical unit number until the macro’s return status

value indicates the error.

It is important to note that the LUN argument to the $DS_GPHARD macro
does not refer to the actual unit 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 could be unit 0 on its respective controller. The logical unit
number associated with the unit would depend on the order in which the
drives were attached. Once the $DS_GPHARD service has been executed,
the p-table for the logical unit number can be examined (specifically, field
HP$B_DRIVE) to determine which unit has been associated with the logical
unit number.

3.5.4

Program Passes and the Initialization Code
When $DS_GPHARD returns an error status, indicating that the highest
numbered logical unit has been tested, the initialization code must signal
the VDS that one program pass has been completed. The $DS_ENDPASS
macro is used for this purpose. This macro will call a VDS service that
will update the count of passes executed and check to see if the number of
requested passes has been executed. If so, the program’s summary routine
(see Section 3.7) and cleanup code (see Section 3.6) will be executed, and
the VDS command line interpreter will be called. Otherwise, program
control is returned to the diagnostic program’s initialization code, which
can reset the logical unit number to zero so that a new program pass can

begin.

Two other macros useful in the initialization code are $DS_BPASS0 and
$DS_BNPASS0. These macros are used to cause program branching
depending on whether or not the first program pass is being executed.
It is often necessary to perform special initialization the first time the
initialization code is executed. For example, 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 first time the initialization code is executed is volume
verification (see Section 6.5.3). These macros are discussed in Section 3.11,
Conditional and Unconditional Branching.

3-21

Core Components of a VAX/DS Diagnostic Program

3.5.5

Initialization Code Examples
Examples 3-8 and 3-9 illustrate the necessary program steps in initialization

code.

Example 3-8
IF

PASS

Initialization Code for Serial Testing

THEN

BEGIN

Program

ALLOCATE

initialization
BUFFERS

LOGICAL_UNIT

NUMBER=0

END

ELSE

INCREMENT
IF

ALL

LOGICAL_UNIT_NUMBER

UNITS

DONE

THEN
BEGIN

{

End

CALL

pass

$DS_ENDPASS

LOGICAL_UNIT_NUMBER=0
END
!

Per-pass

CALL

code

$DS_GPHARD

ASSIGN

CHANNEL

CLEAR

BUFFERS

CLEAR

COUNTERS

Example 3-9
IF

PASS

Initialization Code for Parallel Testing

THEN

BEGIN

Program

ALLOCATE

initialization
BUFFERS

END

ELSE

BEGIN
!

End

CALL

pass

$DS_ENDPASS

END

LOGICAL_UNIT_NUMBER=0

REPEAT

$DS_GPHARD
ASSIGN

CHANNEL

INCREMENT
UNTIL ALL UNITS

3-22

CLEAR

BUFFERS

CLEAR

COUNTERS

LOGICAL_UNIT_NUMBER

DONE

Core Components of a VAX/DS Diagnostic Program

3.6

Cleanup Code
When all testing of a device has been completed, there must be a means
for guaranteeing that the device is left in a known, initialized, static state.
The ““cleanup code’’ is provided for this purpose. This code resides in

the diagnostic program, delimited by the macros $DS_BGNCLEAN and
$DS_ENDCLEAN.
The cleanup code will be executed under the following circumstances:
e

The last program pass has been completed.

The diagnostic program has executed the $DS_ABORT macro. This
macro should be used when a catastrophic failure is detected by the
program.

The user has issued the VDS’s ABORT command.

An exception condition has occurred and was handled by the VDS last
chance condition handler (see Section 4.4.5, Condition Handling).

The program has been aborted because a $DS_ASKxxxx macro was
executed with no user present and no default response.

Cleanup code must perform the following functions.

3.7

Disable all device and adapter interrupts.

Deassign channels if in user mode.

Deallocate memory buffers.

Cancel timers.

HALT all secondary processors on a multiprocessor system.

Summary Routine
The summary routine is an optional portion of the diagnostic program.
It is used to display a summary of the program’s execution history on
the user’s terminal. Summary routines are most likely to be included
in programs that perform many repetitive functions and/or have long
execution times, since these program are likely to compile large error
counts. The summary routine will be called by the VDS at the end of the
last program pass (unless the user has disabled the display with the IES
flag; see the VAX/DS Diagnostic Supervisor User’s Guide). Additionally, the
routine will be executed when the user issues the SUMMARY command

(see the VAX/DS Diagnostic Supervisor User’s Guide).
When the SUMMARY command is issued, the VDS provides a generalized
summary message whether or not the diagnostic program includes a
summary routine. This message indicates the program name and the
number of errors that were reported (see Section 3.9, Reporting Errors).
An example of the message is as follows:
Summary of

EVRAD -

LEVEL

1 program detected

error

(1 Hard,

Supervisor

DISK FUNCTIONAL TEST,

Soft,

Rev

0 System,

1l.1:

Device).

detected errors.

3-23

Core Components of a VAX/DS Diagnostic Program

If a summary routine is included in the diagnostic program, the message
generated by that routine is displayed with the above message.

The summary routine is delimited by the $DS_BGNSUMMARY and

$DS_ENDSUMMARY macros. All messages displayed with the summary

routine must be printed by using the $DS_PRINTS macro.
Typically, the routine will contain code to display run-time statistics such

as the total numbers of read transfers, write transfers, read errors, and
write errors that have been detected on each unit being tested. Any
other information relevant to the type of device being tested may also be

displayed.

A separate set of totals must be kept for each unit. It is useful to store
these sets of totals in one large data area within the program, delimited by

the $DS_BGNSTAT and $DS_ENDSTAT macros.

3.8

Tests, Subtests, and Sections

3.8.1

Tests
All diagnostic programs contain one or more (usually several) tests. A test
consists of code that examines a portion of the UUT.

If the diagnostic program is a logic test, each test should be designed to

check a subset of the UUT’s logic. If the program is a function test, each
test will check a subset of the total functionality of the device. The program
designer will decide on the specific design, content, and number of tests,

based on what is appropriate for the particular device. Each test must be
free-standing. That is, proper execution of a test must not depend on the
previous execution of any other test. Thus, any group of tests must be

executable in all possible combinations and sequences.

If several tests require a common segment of code, this common seqment
may be made into a global routine called by each test. Global routines
should be placed in a separate area of the diagnostic program, outside the

boundaries of any particular test.

Each test is delimited by the $DS_BGNTEST and $DS_ENDTEST macros.
It may be desirable to execute the same test repeatedly, but using a
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 macros. When this

is done, the VDS will automatically execute the code within the test once
for every set of arguments specified, before going on to the next test. From
the user’s point of view, this repeated execution of the code within the test
will appear to be one execution of the test.

3-24

Core Components of a VAX/DS Diagnostic Program

3.8.2

Subtests
Tests should be composed of one or more of subtests. A subtest is a small

section of code that performs one function. Each subtest must be delimited

by the $DS_BGNSUB and $DS_ENDSUB macros. The $DS_BGNSUB
macro automatically assigns a number to each subtest. Subtests are
numbered from 1 to N for each test, where N is the total number of

subtests within the test. Subtests cannot be nested. It is not legal to branch
from one subtest to another using GOTO-type instructions. Subtests
may be either executed sequentially or called from a higher-level routine.
Figure 3-5 illustrates legal and illegal program flow using subtests.
Figure 3-5

Legal and lllegal Usage of Subtests

LEGAL

$DS_BGNTEST
$DS_BGNSUB

ILLEGAL

$DS_BGNTEST
$DS_BGNSUB

ILLEGAL

$DS_BGNTEST
$DS_BGNSUB
[ ]

$DS_BGNTEST

$DS_BGNSUB

[ ]

control

$DS_ENDSUB

routine

GOTO LABEL1

$D§_BGNSUB

$DS_ENDTEST

L ]

$DS_ENDSUB

$DS_BGNSUB

$DS_ENDSUB

$DS_ENDSUB
.

:
°

$DS_ENDSUB

$DS_BGNSUB
.

$DS_BGNSUB

sub

$DS_END SUB|

|$DS_ENDSUB

$DS_ENDSUB

:
LABEL1: o
:

$DS_ ENDSUB
$DS_ENDTEST

$DS_ENDSUB

$DS_ ENDSUB
$DS_ENDTEST
ZK-4779-85

If several tests require the use of the same subtest, the code within the

subtest (not including the $DS_BGNSUB and $DS_ENDSUB macros) can
be placed in a global subroutine placed in a separate area of the diagnostic
program, outside the bounds of any particular test. Then every subtest

requiring the code can call the subroutine.
Subtests are useful for the following reasons:
They define loop boundaries for the loop-on-error facility. Refer to
Section 3.10, Looping, for a discussion of loop boundaries and looping
on errors.

They provide a means by which the program user can execute a small
portion of a test. The user can use the VDS command language to

cause the diagnostic program to be executed up to and including a
particular subtest, with the option of looping on the subtest. Refer to

the VAX/DS Diagnostic Supervisor User’s Guide.

3-25

Core Components of a VAX/DS Diagnostic Program

3.8.3

Sections
A section is a group of tests. Sections are defined for the convenience of

the program user. If the user specifies that a certain section of the program
is to be executed, all the tests assigned to that section are automatically run.

The user does not need to specify a long string of test numbers manually.
The programmer should assign tests which perform similar functions to
a section. The number, names, and purposes of a particular program’s

sections are the programmer’s option, but the program should consider
which groups of tests a user might wish to run as a set and create a section
for that set. A test may belong to any number of sections.

Sections are defined by using the $DS_SECTION and $DS_SECDEF
macros, and by including the section name as arguments to the

$DS_BGNTEST macro. These macros indicate to the VDS which tests
should be associated with which sections. Every program has a default
section called DEFAULT. The contents of this section depend on the
particular program application and are generally specified by the program'’s

user community. However, no test within the default section can require
any sort of manual intervention, such as altering switch positions and
adding cables. The default section may ask for keyboard responses using
the $DS_ASKxxxx macros (see Section 4.2.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) is present.

If any tests in the diagnostic program require manual intervention, these

tests must be grouped together in one section. This section should be
called MANUAL. The manual section MUST test for the presence of
an operator by using the $DS_BOPER or $DS_BNOPER macro (see
Section 3.11, Conditional and Unconditional Branching). If an operator
is not present, each test in this section must call 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 reported by using

the VDS macro calls. Error macros have the format $DS_ERRxxxx, as
indicated later in this section.

3.9.1

Error Message Formats
The error macros call VDS services that will cause error messages to be

displayed on the user’s terminal. Error messages are divided into three
sections or levels, 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 is

generated automatically by the VDS and identifies the current test, subtest,
unit, and error. The rest of the header consists of a message specified by

the programmer as an argument to the $DS_ERRxxxx macro. This last part
of the message is a short statement identifying the type of error.

3-26

Core Components of a VAX/DS Diagnostic Program

The second level is provided by the programmer via the $DS_PRINTB
macro, and is used to provide a clear statement of what the error is. For
example, if a particular register’s contents are tested and found not to
be as expected, this level would be used to display the expected and
actual contents of the register. The third level, also provided by the
programmer (this time by using the $DS_PRINTX macro), can be a detailed
error description, including such variable data as device register dumps
and buffers of sent versus received data patterns. This level is used for
dumping out large amounts of auxiliary information.
The $DS_PRINTB and $DS_PRINTX macros that are used to generate the

second and third message levels are contained in a subroutine referred to
as an ‘‘error reporting routine.”” When the address of an error reporting
routine is passed to an error macro ($DS_ERRxxxx), the VDS will cause
the routine to be executed after the message header (first level) has been
displayed.

Details on specifying error messages are given in the description of the
individual error macros ($DS_ERRxxxx) in Chapter 5.
Example 3-10 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 last line
of the message) was generated by the VDS. The remaining portions of the
message were generated by an error reporting routine. In this example,
only the $DS_PRINTB macro would be used within the error reporting
routine.

Example 3-10

Sample Error Message Using $DS_PRINTB

*x*xx** BCKAX - VAX 11/750-specific CPU Cluster Exerciser - 4.0 **%kkk¥x
Pass

1, test 8, subtest 2, error 2, 4-MAR-1983 09:04:30.04
Hard error while testing KAO: Attempting to initialize TU58 controller.
Incorrect number of bytes

received.

EXPECTED:

CONTINUE

flag

Unrecognizable packet received.
ACTUAL:
**kkkkxx

00000092(X)
End

hard

bytes
error

beginning
number

0000BAOO

****xxkkix

Example 3-11 illustrates an error message in which both $DSPRINTB
and $DS_PRINTX macros should be used. The first line following the
3-line header should be displayed using $DS_PRINTB. The last part of the
message displays the parameters of a $QIO service. Since this is a fairly
long list of auxiliary information, it belongs to the third message level and
hence should be displayed using $DS_PRINTX.

3-27

Core Components of a VAX/DS Diagnostic Program

Example 3-11

Sample Error Message Using $DS_PRINTB and

$DS_PRINTX
**x**xx*

Pass

EVXBA

VAX

subtest

System fatal

error

while

testing

QIO COMPLETION
QIO

BLOCK

WRITE

Program

9-MAY-83

5.1

TTGl:

ERROR ON

STATUS WAS:

NOPRIV

PARAMETERS

WERE:
;

EVENT

QIO_CHAN:

00000050 ( X)

;

QIO

QIO_FUNC:

0000000B(X)

;

I0$_WRITEPBLK

QIO_IOSB:

0004E888(X)

;

IOSB

FLAG

00001069 (X)

;

ADDRESS

0004E800 ( X)

;

VALUE

QIO P1:

00004C10(X)

;

ARG VALUE

QIO _P2:

00000005 ( X)

00000000 ( X)

; P3 ARG VALUE

;

ARG VALUE

QIO_P4:

00000000 (X)

;

ARG

00000000 (X)

;

ARG VALUE

QIO P61

0004E940 (X)

;

ARG VALUE

error

number

FUNCTION

OF AST

QIO _P5:

fatal

ADDRESS

QIO_ASTADR:

device

COMPLETION

CHANNEL

QIO_ASTPRM:

End of

QIO

TTGl:

00000020 ( X)

**xx*%x

***x%xxx

14:55:29.16

QIO_EFN:

QIO_P3:

3.9.2

Interaction

error

ERROR ATTEMPTING

TTGl

Bus

PARAMETER

VALUE

**xxxx

VDS Control Flags Associated with Error Reporting
Several VDS control flags are associated with error reporting. These flags
are IE1, IE2, IE3, HALT, and LOQP. (See the VAX/DS Diagnostic Supervisor
User’s Guide for a complete discussion of VDS control flags.)

The IE1, IE2, and IE3 flags control error message displays. If the IE1 flag
is set, the entire error message will not be displayed. If the user sets the
IE2 flag, message levels 2 and 3 are not displayed; if the IE3 flag is set,
message level 3 is not displayed.

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

(see Section 3.10, Looping).

3.9.3

Error Types
Error conditions are divided into five classes, depending on their severity.
A macro is provided for each class. The five error classes are preparation
errors, soft errors, hard errors, device-fatal errors, and system-fatal errors.
3.9.3.1

Preparation Errors
Preparation errors are not hardware faults, but result when the program

user has not properly prepared the UUT for testing. For example, a
particular diagnostic program may require that a disk drive be write-

enabled by the user. If the program finds that the user has not writeenabled the drive, it can declare a preparation error. The program could
then run only those tests that do not require writing to the UUT, or it could
skip the unit altogether.
3-28

Core Components of a VAX/DS Diagnostic Program

Preparation errors are declared by using the $DS_ERRPREP macro. This
macro may be issued from any point within the diagnostic program except
the cleanup code.

3.9.3.2

Soft Errors

A soft error is one that you can recover from. That is, it is an error which
may go away if the operation that detected the error is repeated. In an
operating system, this type of error probably would not be reported to the
user, but in a diagnostic program it is important to flag all errors whether
or not they can be recovered so that the operation can be completed. An
example of a soft error might be the occurrence of a write-check error when
writing data to a medium. (It may be the medium that is bad, and not
the device.) When a soft error is detected by the diagnostic program, the
error should be reported and the operation reexecuted. However, there
is generally a maximum number of retries that should be allowed. If the
maximum is reached, a hard error (see below) should then be declared.
The macro to use when reporting a soft error is $DS_ERRSOFT. This macro
can only be issued from within tests (see Section 3.8.1).
3.9.3.3

Hard Errors
You cannot recover from a hard error. That is, it is an error so serious that
the operation being performed cannot be completed. Such an error might
be a disk seek error. A hard error should also be declared if an operation
detected a soft error and the operation was retried unsuccessfully several
times. If, for example, a routine performing write operations on a disk
detected several write-check errors (which are soft errors), a hard error
should be declared.

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

Device-Fatal Errors

Sometimes a diagnostic program detects so many hard errors on a
UUT that it is pointless to continue testing the device. Perhaps there is
something so seriously wrong with the device that it cannot be tested at
all. Or maybe an attempt has been made to test a nonexistent unit. In
any of these cases it is appropriate to declare a device-fatal error, which
indicates to the user that the program intends to stop attempting to test the
UUT in question. Whenever a device-fatal error is declared in a program
performing serial testing, the program should leave the current test (by
issuing the $DS_EXIT macro). Additionally, an internal flag could be set to
indicate that a fatal error has been declared. Each test could check this flag’
and, if set, immediately issue the $DS_EXIT macro. In this way, no more
testing would be performed on the unit (for this pass). The initialization
code would reset the flag to allow testing of the next unit.

The macro for declaring device-fatal errors is $DS_ERRDEV. This macro
may be issued from anywhere within a diagnostic program except the
cleanup code.

3-29

Core Components of a VAX/DS Diagnostic Program

3.9.3.5

System-Fatal Errors
A system-fatal error is one so serious that the diagnostic program cannot be
executed at all. In user mode, for example, a system-fatal error should be

declared if the user’s process does not possess VMS privileges necessary
to perform functions required by the diagnostic program (such as PHYSIO

for a program that uses physical I/O; refer to the VAX/VMS System Services
Reference Manual.) Any time a system-fatal error is declared, the diagnostic
program should subsequently execute the $DS_ABORT macro to abort
program execution.

The macro for system-fatal errors is $DS_ERRSYS. This macro may be
issued from anywhere within a diagnostic program except the cleanup
code.

3.10

Looping
The VDS facility that is probably the most useful to repair technicians is

program looping. Program loops, often called scope loops, because they
aid the technician in tracing signals with an oscilloscope, are enabled when

the technician sets the VDS control flag LOOP (see the VAX/DS Diagnostic

Supervisor User’s Guide). Once this flag has been set, a loop will begin

executing any time an error macro ($DS_ERRxxxx) is issued.

3.10.1

Defining Loop Boundaries
Although actual execution of program loops is initiated automatically by the
VDS, it is the responsibility of the programmer to define the boundaries of

the loops.

Each loop will have a lower bound and an upper bound. There will be at
least one call to an error macro within these bounds. Whenever an error

macro is serviced with the LOOP flag set, the VDS begins execution of the

loop. Loop execution proceeds in the following sequence.
1

After servicing the error macro call, the VDS returns program control
to the instruction immediately following the error call in the diagnostic
program.

The diagnostic program continues execution until the loop’s upper
bound is reached.
From the upper bound, the VDS causes program control to branch to

the loop’s lower bound.
4

Execution of the diagnostic program continues until the upper bound is

reached again, regardless of whether or not the error macro is issued

again.

3-30

The cycle is repeated.

Core Components of a VAX/DS Diagnostic Program

Note that once the cycle is started through the execution of an error macro,
the macro may or may not be executed on subsequent passes through the
loop. This means that the loop will continue to execute even if the error
condition disappears. In fact, once a program loop has been initiated, it
will continue to execute indefinitely until a control-C is typed on the user’s
terminal.

Loop boundaries may be defined explicitly by the programmer. If they
are not, default values will then be used. For tests containing subtests, the
default lower and upper bounds are the $DS_BGNSUB and $DS_ENDSUB
macros of the subtest containing the error macro that was executed to
report the error condition. The programmer can explicitly define loop
boundaries by using the $DS_CKLOOP macro. This macro is placed after
an error macro, but before the next $DS_ENDSUB or $DS_ENDTEST. If
the the $DS_CKLOOQOP macro is contained within a test that consists of
subtests, it must be placed within the bounds of a subtest. The macro
takes the name of a program label as an argument. This label must be
located before the error macro, but after the most recent $DS_BGNSUB
or $DS_BGNTEST. The result is a loop whose lower bound is the label,

and whose upper bound is the $DS_CKLOOP macro itself. Figure 3-6
illustrates the various loop boundaries.

Figure 3-6

Examples of Loop Boundaries
$DS_BGNTEST

$DS_BGNTEST

$DS_BGNSUB

$DS_BGNTEST

$DS_BGNSUB

label:

]

$DS_ENDSUB

$DS_BGNSUB )

$DS_BGNSUB
label:

$DS_ERRxxxx

LOOP

$DS_ERRxxxx

»LOOP

LOOP

$DS_ERRxxxx
$DS_CKLOOP label

$DS_ENDSUB

$DS_ENDSUB
$DS_CKLOOP label

$DS_ENDTEST

$DS_ENDTEST
$DS_ENDTEST

ZK-4780-85

3-31

Core Components of a VAX/DS Diagnostic Program

3.10.2

Characteristics of Loops
Loops should be small. Each loop should generate a minimum amount of
electrical activity on the UUT. The less activity that is occurring, the easier

it will be for the technician to trace relevant signals.

Loops must be made up of code that is repeatable. There is no point in
creating a program loop unless the code within that loop can be executed
repeatedly. The code must cause the same electrical activity to occur each
time it is executed. For 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. In order to make

a loop’s code repeatable, it may occasionally be necessary to alter the
program flow within the loop after the first pass 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 useful in places where severe errors

occur. Ordinarily, the programmer may want to abort the program (using
the $DS_ABORT macro). However, if a loop is present, it may be desirable
to branch around the $DS_ABORT macro to allow the loop to continue.
Caution should be practiced when branching within subtests containing

$DS_CKLOOP macros. It is important not to branch past the
$DS_CKLOOP macro or the loop could be broken. For example, suppose

a loop is being executed, with a $DS_CKLOOP macro as the loop’s upper
bound. Suppose now that a section of code within the loop tests for a hard
error condition and then branches around a $DS_ERRHARD macro if the

error does not exist. If the branch goes past the $DS_CKLOOP macro, the
loop will be broken. Illustrations of proper and improper branching within
loops are shown in Figure 3-7.

Figure 3-7

Proper and Improper Branching Within Loops

PROPER BRANCHING
WITHIN A LOOP

label1:

label 1:

[]

[

TSTL
BNEQ
L]

IMPROPER BRANCHING
WITHIN A LOOP

ERRBITS
NO_ERROR

[]

TSTL
BNEQ

ERRBITS
NO_ERROR

NO_ERROR'
$DS_CKLOOP

*®

$DS_CKLOOP LABEL1
LABEL1

[ J

NO_ERROR:

ZK-4781-85

3-32

Core Components of a VAX/DS Diagnostic Program

3.10.3

Nesting Loops
Loops whose boundaries are defined with the $DS_CKLOOP macro
may be nested. Figure 3-8 illustrates nesting of loops. In Example A

of Figure 3-8, loop 2 and loop 3 are contained in loop 1. In Example B,
loop 3 is contained within loop 2, and loop 2 is contained within loop 1.
Figure 3-8

Nesting Loops

EXAMPLE A

EXAMPLE B

LABELT:

LABEL1:
LABEL2:

LABEL2:

LOOP 2

error macro 2

LABEL3:

$DS_CKLOOP LABEL2

>LOOP1

LABEL3:

LOOP 3

error macro 3

LOOP 3
error macro 3

>LO0P2

$DS_CKLOOP LABEL3

>Loop 1

$DS_CKLOOP LABEL3
error macro 1

error macro 2

$DS_CKLOOP LABEL1

$DS_CKLOOP LABEL2

error macro 1

$DS_CKLOOP LABEL1

J
ZK-4782-85

When loops are nested, the VDS always executes the smallest loop
containing the issued error macro. If error macro 2 was issued in Example

B, loop 2 would be executed.
The VDS will always execute the loop containing the most recently issued
error macro. In Example A, suppose error macro 1 was 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 time (perhaps because of an intermittent
hardware failure). Then loop 2 would begin execution and loop 1 would be
forgotten.

3-33

Core Components of a VAX/DS Diagnostic Program

3.10.4

User-Specified Looping
There is a method by which the user can request a loop to be executed

even though an error macro has not been issued. The /TEST, /ISUBTEST
and /PASSES qualifiers on the RUN and START commands (see the
VAX/DS Diagnostic Supervisor User’s Guide) can be used to specify a test or
subtest on which the user wishes looping to occur. When the specified
test or subtest is reached, looping begins on that portion of code. The
programmer should keep this feature in mind as subtests and tests are

designed.

3.11

Conditional and Unconditional Branching
The VDS provides several macros to facilitate conditional branching within
the diagnostic program.

$DS_BERROR, $DS_BNERROR
The “branch if error” and ““branch if no error’’ macros can be used
immediately after macros that call system services. The services will return
a status indication (in R0), and these macros cue on that status. The macros
accept as an argument the address to which the program should branch.

$DS_BCOMPLETE, $DS_BNCOMPLETE
The “branch if complete’’ and ‘“branch if incomplete’”” macros are also

used immediately following macros that call system services. Their

function is the inverse of that of the $DS_BERROR and $DS_BNERROR
macros. That is, $DS_BCOMPLETE is equivalent to $DS_BNERROR and

$DS_BNCOMPLETE is the same as $DS_BERROR. Choosing one set of

macros over the other is simply a matter of readability in the source code.
For some system services, it makes more sense to branch if the service
completed successfully, while for others it is more appropriate to branch if

there was no error.

$DS_BOPER, $DS_BNOPER
The “branch if operator present’” and ‘‘branch if operator not present”’
macros can be used anywhere in the diagnostic program. They cue on the
setting of the OPERATOR flag (see the VAX/DS Diagnostic Supervisor User’s

Guide). They make it possible to execute or skip certain segments of code,
depending on whether a user is or is not present.

$DS_BQUICK, $DS_BNQUICK
The “branch if QUICK flag set” and “‘branch if QUICK flag not set”
macros can be used anywhere in the diagnostic program. They cue on

the setting of the QUICK flag (see the VAX/DS Diagnostic Supervisor User’s
Guide). These macros allow you to create a ““quick mode”” in your program.

This mode is selected optionally if the user sets the QUICK flag.
Quick mode provides a fast program pass that does not perform thorough
testing and is used when the user is more interested in a fast run-time
than in careful, complete fault detection. The macros can be used to skip

around segments of code in quick mode. Determination of what segments
of code should be included or excluded in quick mode depends on specific
program requirements.

3-34

Core Components of a VAX/DS Diagnostic Program

$DS_BPASS0, $DS_BNPASS0
The “branch if pass 0" and ““branch if not pass 0"’ macros can be used
when it is necessary to cause program flow to change, depending on

whether or not the current program pass is the first one. The macros call
a system service that returns a status indication (in R0) of whether or not
the current pass is the first one, then an appropriate branch is generated.
These macros are only to be used in the program’s initialization code.

$DS_ESCAPE
The $DS_ESCAPE macro is used to exit from a test or subtest if an error
has been detected within that test or subtest. It is used when it is pointless
to execute the rest of the code within the test or subtest after the error was

detected. For example, there is no point in executing write tests on a disk
if it has been discovered that the disk is write-protected and a user is not
present.

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

current subtest or test, issuing an $DS_ESCAPE macro will cause program
control to pass to the end of the subtest or 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 summary routine. This
macro is often used in conjunction with the conditional branching macros,
as in the following example:
$DS_BGNTEST

$DS_BOPER

10%

$DS_EXIT

TEST

10s:

$DS_ENDTEST

QECLIT AR vax Fre7f

ign guid
\VAX diagn ostic des
.

‘

ide

3-35

Additional Components of a VAX/DS Diagnostic
Program

4.1

Introduction
The previous chapter described components that must exist in every

diagnostic program, such as initialization code and error reporting routines.
This chapter describes components that are required only for particular
diagnostic applications including input/output, memory management and
allocation, synchronous and asynchronous events, file management, and
multiprocessor issues. For detailed information regarding the VAX/DS
macros and system services, see Chapter 5.

4.2

Input/Output

4.2.1

I/0 with the Unit Under Test
42.1.1

I/0 in User Mode

In user mode (level 2R programs), all input/output operations must be
accomplished by using the VMS $QIO system service. The details of
performing I/O operations with the $QIO service are described in the
VAX/VMS I/O User’s Guide, which must be read before developing a level
2R program.

Initiating I/O activity in user mode is a process involving three steps, each
of which requires use of a VMS system service.
1

Assign a channel to the device.

A device cannot be referenced unless a channel that links the device to
the program has been assigned to the user. A channel is a data path
linking the device to the diagnostic program. Channel assignments
are accomplished by using the $ASSIGN system service. This service
request should be issued from the diagnostic program’s initialization
code.

When the diagnostic program has finished using the device, its
channel should be deassigned by using the $DASSGN system service.
This service should be requested in the program’s cleanup code.
Another useful VMS system service is the $GETCHN service that
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 1/O User’s Guide.
2

Allocate the device.

If the diagnostic program needs exclusive use of the device to be tested
(no other users allowed to reference the device while it is being tested),
the device must be allocated to the diagnostic program. Allocation is
necessary if the program requires a scratch medium in the unit under
test (UUT). If the program can use the currently loaded (nonscratch)
device medium in a nondestructive manner, device allocation is not
4-1

Additional Components of a VAX/DS Diagnostic Program

necessary. Device allocation is not performed directly by the diagnostic
program. Instead, the allocation request is issued by the VDS (via the

$ALLOCATE system service) when the user types the VDS SELECT

command (see the VAX/DS Diagnostic Supervisor User’s Guide). The
VDS determines whether or not to allocate the device by checking the

HP$M_ALLOC bit in the device’s p-table (see Section 3.2.2, P-Table

Format). If this bit is set (by the program developer who created
the p-table descriptor; see Section 3.2.3, P-Table Descriptors), the

$ALLOCATE service is requested. If the device cannot be allocated

because it has already been allocated to someone else, the VDS informs
the user.

An allocated device will be deallocated (by the VDS issuing a VMS

$DEALLOCATE service request) when the device is deselected or

when the VDS EXIT command is typed.

An instance when the diagnostic program might have to specifically

allocate and deallocate a device is in the case of error logging (not
VMS system error logging). If a level 2R program writes error logging
data to a device, it may be necessary to allocate the device. In this

case, the diagnostic program should use the VMS $ALLOCATE service
within the initialization code. The cleanup code will have to use the

$DEALLOCATE service to deallocate the device. Refer to the VAX/VMS
System Services Reference Manual.
Queue I/O requests.

Actual input/output operations are requested by using the $QIO and

$QIOW system services, which will place the request in an I/O queue.

These services require a set of parameters to pass to the service routine.
These parameters specify the following types of information:
a.

The channel number on which the data transfer is to take place.
The channel number is obtained from the VMS $ASSIGN service.

The type of transaction desired. This is indicated by using 1/O

function encoding.

I/O functions can be categorized into three groups, corresponding
to the I/O methods (physical, logical, and virtual). The type of

function to be used will depend on the type of device being
tested and the type of diagnostic program being written (refer

to Chapter 2).

The function that is to be performed by a $QIO service is indicated
by passing a 16-bit value to the service routine, which has the

format illustrated in Figure 4-1.

The function code is a 6-bit field indicating the type of I/O
operation to be performed.

Some function codes are device-

independent, and others are device-dependent. Table 4-1 contains
device-independent function codes for read and write functions in

the three I/O transfer modes.

Additional Components of a VAX/DS Diagnostic Program

The function modifier field is used to modify the operation
specified by the function code. Bits within this field can be set
in conjunction with the function code, and the $QIO service will
alter the function to be performed accordingly. For example, the

I0$_INHRETRY modifier can be used with an I0$_READVLBK
function to inhibit retries when read errors are encountered. Refer
to the VAX/VMS I/0 User’s Guide for a more detailed dicussion of
I/O function encoding, along with tables of function codes and
modifiers that are valid for each device supported by VMS.

Figure 4-1

$QIO0 Function Code and Modifier Fields

FUNCTION

MODIFIER

CODE
ZK-4783-85

Table 4-1

Device-Independent Read and Write Functions

Physical 1/O

Logical /O

Virtual 1/O

10$_READPBLK

I0$_READLBLK

I0$_READVBLK

10$_WRITEPBLK

I0$_WRITELBLK

I0$_WRITEVBLK

The method by which the program is to be signaled that the
I/O transaction has been completed. The desired method of
determination is indicated with the $QIO service call. Three
methods exist for synchronizing I/0O completion:
1

Waiting for an event flag

The number of an event flag (see Section 4.4.2.) can be
specified as an argument to the $QIO or $QIOW macros.
This event flag will be set by the system service when /O has
completed. The diagnostic program can wait for the specified

flag to be set (by using a system service). (The $QIOW service
is a combination of the $QIO and $WAITFR services.)

Testing an 1/O status block

The address of an 1/0O status block can be specified as an
argument to the $QIO macro. The $QIO service will cause
the first word of this block to be loaded with a status code
when the I/O operation has been completed. The program can

test the contents of the block to determine the status of the
I/O operation. The format of an I/O status block is shown in
Figure 4-2.

4-3

Additional Components of a VAX/DS Diagnostic Program

Figure 4-2

/0 Status Block Format

16
TRANSFER COUNT

o
STATUS

DEVICE-DEPENDENT DATA

ZK-4784-85

Refer to the VAX/VMS I/0 User’s Guide for more details about
the contents of the I/O status block.

Executing an AST routine

The address of an asynchronous system trap (AST) (see
Section 4.4.3.) can be specified as a $QIO argument. An
AST will be delivered (and the AST routine called) when the

I/O operation has been completed. This method of determining
I/O completion provides for the most asynchronous (and most
efficient, in regard to processor usage) 1/O activity.

The address of a buffer which will receive diagnostic information.
When a $QIO or $QIOW macro is issued, it is 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 the
I/O transfer method is physical (see Chapter 2) and if the process

possesses the “‘diagnostic’” VMS privilege (see the VAX/VMS

Command Language User’s Guide). To request the system service to
load the buffer, the programmer must:
1

Define a buffer area within the diagnostic program. This buffer
must be large enough to contain the contents of all the device’s
registers.

Specify the address of this buffer as the ‘P6’" argument to the

$QIO or $QIOW macro (see Chapter 5).

When the /O operation has completed, the buffer will contain the

final contents of the device registers, plus additional information.
The format of the buffer’s contents will generally be as indicated in
Figure 4-3.

4-4

Additional Components of a VAX/DS Diagnostic Program

Figure 4-3

Typical $QlO Diagnostic Buffer Format
31

0
OPERATION START TIME
IN 64-B!T FORMAT

OPERATION COMPLETION TIME
IN 64-B1T FORMAT
FINAL ERROR COUNTER CONTENTS
NUMBER OF DEVICE REGISTERS

DEVICE REGISTERS,

ONE PER LONGWORD

T
ZK-4785-85

4.2.1.2

/0 in Standalone Mode

In standalone mode (level 3 programs), I/O is performed by direct
reference to the device’s registers. Therefore, routines to initialize a
device’'s control registers, service its interrupts, and check for error
conditions must be contained within the diagnostic program.

The diagnostic program must initialize the bus adapters so that a data
channel can be created to transfer information across the buses. Because of
the differences inherent in the bus adapters of the various VAX processor
types, the VDS provides facilities for channel initialization that remove the
burden of dealing with processor-specific details from the diagnostic
programmer. This allows diagnostic programs to be automatically
compatible with all VAX processor types.

The VDS services, $DS_CHANNEL and $DS_SETMAP, are used to create
data channels in standalone mode. The $DS_CHANNEL service is used
to initialize the MASSBUS, UNIBUS, and VAXBI adapters. Depending on
the parameters included with the $DS_CHANNEL macro, the service will:
¢

Initialize the adapter

(lear the adapter

Enable or disable interrupts

Provide current adapter status

Details are provided in the description of the $DS_CHANNEL macro in
Chapter 5.

The $DS_SETMAP service will set up the adapter’s mapping registers so

that data transfers will reference the desired areas of main memory. Details
are provided in the description of the $DS_SETMAP macro in Chapter 5.
The $DS_SHOCHAN service provides automatic display on the user’s
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 $DS_CHANNEL system service detects an error condition.

4-5

Additional Components of a VAX/DS Diagnostic Program

The address of the interrupt service routine (ISR) is passed to the

$DS_CHANNEL service. Interrupt service routines in a diagnostic program
should be delimited by the $DS_BGNSERV and $DS_ENDSERV macros.
The VDS has an interrupt preprocessor that fields the interrupt initially,
then dispatches control to the specified interrupt service routine.
An interrupt service routine’s function should be minimal, such as
disabling further interrupts, confirming that the interrupt was expected
(vectored correctly), and saving device status. Error reporting should not

be done in an interrupt service routine unless it is to report unexpected
interrupts.

Typical program flow when using an interrupt service routine is as follows.
*

Main-Line Code

Clear and initialize channel
Set up I/O transfer
Start watchdog timer

Enable interrupts
Clear done flag
REPEAT
Test done flag
UNTIL done flag set OR watchdog timer finishes

IF done flag set
THEN cancel watchdog timer; report I/O status

ELSE report timeout error
*

Interrupt Service Routine
Disable interrupts

IF unexpected interrupt (wrong vector)

THEN set error status
ELSE save device status

Set done flag
Return

More information on interrupts can be found in the description of the

$DS_CHANNEL service in Chapter 5.

Other macros useful when performing I/O functions in standalone mode
are:

$DS_SETVEC — Stores the address of an ISR in a specified interrupt
or exception vector in the system control block (SCB). This is the only

method to modify the vectors in the SCB except in a multiprocessing
environment in an attached process. Attached processes cannot use
this service (see Section 4.6.8.1), and therefore must modify the SCB

directly.

$DS_CLRVEC — Restores the address of a VDS condition handler
in a specified vector in the SCB. This is the only method to clear

vectors in the SCB except in a multiprocessing environment in an

attached process. Attached processes cannot use this service (see
Section 4.6.8.1), and therefore must modify the SCB directly.

Additional Components of a VAX/DS Diagnostic Program

$DS_INITSCB — Reinitializes the system control block (SCB), which
contains all of the interrupt and exception vectors to their standard
(VDS-defined) values. Useful if several $DS_SETVEC macros have
been used.

e
e

$DS_PROBE — Attempts to access an address to determine whether or

not hardware (either memory or an I/O device) is connected to it.

$DS_SETIPL — Sets the processor’s interrupt priority level (IPL) to a
specified value.

4.2.2

1/0 with the User Terminal
All /O between a diagnostic program and the user’s terminal must be
accomplished by means of VDS macros. Macros are provided to:

Display messages consisting of simple ASCII strings or a combination
of ASCII strings and variable data

Prompt the user for a response; receive and store the response

Display the contents of a register and assign a mnemonic to each bit

Determine the user’s terminal type and characteristics

Message Display

42.2.1

Message strings consisting of a combination of ASCII strings and data
variables are displayed by means of the PRINT macros. This set of
macros has the general form $DS_PRINTx. There are four print macros,

known as $DS_PRINTB, $DS_PRINTX, $DS_PRINTF, and $DS_PRINTS.

The $DS_PRINTB and $DS_PRINTX macros are used only to print
error messages, and are used in conjunction with the error macros
($DS_ERRxxxx). The VDS control flags used to inhibit error messages
(see the VAX/DS Diagnostic Supervisor User’s Guide) are closely associated
to the $DS_PRINTB and $DS_PRINTX macros. The $DS_PRINTF macro is
used when it is necessary to provide the user with information unrelated
to error reports. The $DS_PRINTS macro is used for summaries (see
Section 3.7, Summary Routine).

The print macros are used to print simple ASCII strings, such as:
DEVICE

WRITE

LOCKED.

They can also be used to display the contents of data words or to print a
combination of ASCII strings and variable data, such as:
EXPECTED:

1010101010101010

(B)

RECEIVED:

1011101010101010

(B)

XOR:

0001000000000000

(B)

Using a print macro involves specifying the address of a format statement
and a list of variables. Format statements indicate the format in which
the variables are to be printed. The method used by the print macros
to format messages is the same as the $FAO system service provided by
VMS. In fact, the $FAO service is also provided by the VDS. This service
will format, but not print, a message. The print macros will both format
and print the desired message. It is also possible to format a message with
the $FAO service and then display it by using one of the print macros.
4-7

Additional Components of a VAX/DS Diagnostic Program

Another macro useful for displaying information to the user is

$DS_CVTREG. With this macro, specify the address of a register and the

address of a string of mnemonics. The mnemonics are the names assigned
to the bits within the register. The macro will read the register and produce
a character string showing which bits of the register are set. This string
can then be displayed using one of the print macros. Details on the print
macros are described in Chapter 5. The $FAOQ service is discussed in
Chapter 5 and in the VAX/VMS System Services Reference Manual.

It is sometimes useful to know the type and characteristics of the
user terminal.

For instance, you may want to format text displays

differently on a video terminal from that of a hardcopy terminal. The

$DS_GETTERM service may be used to determine the user terminal’s type

and characteristics.
4.2.2.2

Prompting the User
There are instances when it is necessary to solicit information from the
user. A common example 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 been completed. Also, there may be circumstances when it is
necessary to obtain additional information about the UUT (information
which is not contained in the p-table).
Note: It is important to fry to place all device-specific information in the p-tables

so that it can be specified in ATTACH commands before the diagnostic
program is started.

All solicitation of user responses during the diagnostic program’s execution
must be made through the use of the $DS_ASKxxxx macros. These macros
allow the programmer to specify a prompting message, the format in

which the user’s response is to be interpreted, and a storage area for the
response.

Specifically, there are five $DS_ASKxxxx macros:

$DS_ASKADR — Prompts the user for an address within a specified
range and stores the result.

$DS_ASKDATA — Prompts the user for a numeric value within a
specified range and stores the result.

$DS_ASKVLD — Same as $DS_ASKDATA, except allows programmer

to specify storage location of result as a field (using position and size)

within a large bit structure.

$DS_ASKLGCL — Prompts the user for a Y (yes) or N (no) response,

and stores the result as one bit, set or cleared.

$DS_ASKSTR — Prompts the user for a character string and stores the

result.

Additional Components of a VAX/DS Diagnostic Program

The macros also allow the programmer to specify a default value for the
response. If there is no user present (indicated by the state of the VDS
control flag OPERATOR, see the VAX/DS Diagnostic Supervisor User’s Guide),
the default value will automatically be used. If no default value exists, the
program will be aborted. Sometimes diagnostic programs require the user
to specify run-time options other than those that can be selected using
the VDS command language. In such cases, the $DS_ASKxxxx macros
can be used to prompt the user for these required run-time parameters.
One method of accomplishing this is to ask a set of questions that can be
answered with Y (yes) or N (no), such as:
DO YOU WISH TO RUN OPTION

DO YOU WANT

RUN

THE

DEVICE

IN MODE Y?

The responses to these question can be converted to set or cleared bits that
the diagnostic program can test. This method is suitable when the total
number of program options is small.

However, for a program with a large number of run-time options, the
program users might have to answer a large list of questions every time the
program is executed (assuming they did not want to use the default values
for these questions). In such cases, the programmer might want to just

prompt the user once and allow him or her to type a string of options, as:
OPTIONS ARE OPTION_X,
(DEFAULT
TYPE

OPTION_Y,

OPTION_Z

OPTION_X)

OPTIONS:

Allowing the user to type a list of the options wanted is more convenient

for the user, even though it is more difficult for the programmer to check
the strings typed to see if they are valid.

For a program having a very large set of run-time options, it might be
beneficial for the programmer to create a command language. An example
might be:

Commands:

OPTIONS — select options
MODES — select device modes
BEGIN — begin program execution

RESUME — continue after control-C

The user would type the VDS RUN or START command to start the

diagnostic program’s execution. In the program’s initialization code or
within a particular test, the program executes $DS_ASKxxxx macros to
prompt the user for command strings. The program parses and executes

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

4-9

Additional Components of a VAX/DS Diagnostic Program

The VDS provides two macros to facilitate command parsing. The

$DS_CLI macro is used to define the desired command language. The
$DS_PARSE macro compares an input stream (obtained from the user via
a $DS_ASKxxxx macro) and the command language defined with a set of

$DS_CLI macros and will either dispatch to the proper action routines or
inform the user if an illegal command has been typed.
4.2.2.3

Displaying HELP Text

Chapter 6 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 of the
HELP file. This can be accomplished by using the $DS_HELP macro. Read

Section 6.4.4, Help Files, and then refer to Chapter 5 for a description of

the $DS_HELP macro.

4.3

Memory Management and Allocation
Memory management in the VDS is dependent on the current run-time

environment: user mode or standalone mode. Discussions on memory
management in both environments are below.
Note: The memory management hardware may not be directly referenced by

diagnostic programs running under the VDS.
For a discussion of VAX memory management, see the VAX Architecture

Handbook.

4.3.1

Memory Management in User Mode
In user mode (level 2R programs), memory management hardware is

under the control of VMS and it is always enabled. All of the VMS
memory management system services are available for use by diagnostic

programs.

See the VAX/VMS System Services Reference Manual for the

uses and restrictions applying to VMS memory management services.

Allocation of new memory space should only be accomplished with the

VDS $DS_GETBUF macro, as described in Section 4.3.3.

4.3.2

Memory Management in Standalone Mode
In standalone mode, the memory management hardware may be enabled
or disabled; it is disabled by default. Unlike VMS, the VDS memory
management will not increase the size of the virtual address space available

to the diagnostic program. The memory management scheme in the VDS
serves three functions:
*

4-10

Identify programming errors such as missing literal signs. For example,
the MACRO-32 instruction MOVL 4, TEMP would generate an access
violation when memory location 4 was read.

Additional Components of a VAX/DS Diagnostic Program

(Create two hardware test environments by using memory management
as the variable.

Integrate the control of memory management within diagnostic
programs which test the memory management hardware and the
memory modaules.

Diagnostic programs may enable memory management with the
$DS_MMON macro. Once enabled, it may be disabled with the
$DS_MMOFF macro. Operators may enable and disable memory
management with the SET MM ON and SET MM OFF commands. These
commands override the $DS_MMON and $DS_MMOFF macros contained
within a diagnostic program. Therefore, if a user has issued the SET
MM ON command, the diagnostic program may not disable memory
management with the $DS_MMOFF macro.
Some diagnostic programs may not be able to execute if the memory

management hardware is enabled. If this is the case, the $DS_MMOFF
macro must be issued at the beginning of the program. If the status
returned from this macro indicates that the operator has enabled memory
management, the program must abort (with the $DS_ABORT macro),
printing an appropriate error message before doing so.

4.3.3

Memory Allocation
Many diagnostic programs need extra memory space for I/O buffers or
other uses. Additional memory space may be acquired by using the
$DS_GETBUF macro. Both user mode and standalone mode programs
should use this macro, since this method is the only way of ensuring
that there will be no memory allocation conflicts between the VDS
and the diagnostic program. The VDS manages all free memory. The

$DS_GETBUF macro is used to request the VDS to assign a certain number
of pages to the diagnostic program. The VDS will return the starting

address of the memory space it has assigned. (Space will be assigned as
a group of contiguous 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 is guaranteed
access to at least 96 kilobytes of buffer space.
Memory space is returned to the VDS free memory pool by using the

$DS_RELBUF macro. It is possible to change the protection of any page or
group of pages by using the $SETPRT macro.

4-11

Additional Components of a VAX/DS Diagnostic Program

4.4

Synchronous and Asynchronous Events

4.4.1

Introduction
A synchronous event is a condition that occurs as a direct result of the

diagnostic program. Such events are predictable and, by definition, can
only appear one at a time. Waiting for a bit to become set or creating a

time delay are both examples of synchronous events. An asynchronous
event is a condition that occurs independently of the diagnostic program.

It is possible for such unpredicted events to appear simultaneously and in

multiple numbers. 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 for a
detailed discussion of VAX exceptions.
Most diagnostic programs must handle occurrences of synchronous and
asynchronous events. Event flags are useful for synchronous processing of

events. AST routines and condition handlers are used for asynchronous
processing. There are both synchronous and asynchronous methods

available for handling time-critical situations.

4.4.2

Event Flags
Event flags are all-purpose flags, provided by the VDS, that can be used by

diagnostic programs to 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 via macros.

Whenever a new diagnostic program is loaded into memory by the VDS
LOAD or RUN command, all event flags are cleared.
There are 64 event flags, numbered from 0 to 63. The flags are divided
into two clusters, each containing 32 flags. Some event flag macros require
that the cluster be indicated.
Event flag 0 is reserved for exclusive use by the VDS and is not available to

diagnostic programs.
Flags 1 through 23 can be set or cleared by the user via the SET EVENT
FLAGS and CLEAR EVENT FLAGS commands, which means they can be

used to implement user selection of optional program features.
Flags 24 through 31 are used by VMS, and therefore cannot be used by

level 2R diagnostic programs. They are available, however, to level 3
programs.

Flags 32 through 63 are available to all diagnostic programs. Users cannot
modify these flags.
In user mode (level 2R programs), event flags are maintained by VMS. The

event flag macros call service routines within VMS. Event flags 0 through 63
are referred to as local event flags, since they can only be used internally
by a single process. Another set of event flags, numbered from 64 through
127, are referred to as common event flags since they can be shared by
cooperating processes. The VMS system service $ASCEFC must be used

Additional Components of a VAX/DS Diagnostic Program

to associate common event flags with processes in order for these flags to
be shared. See the VAX/VMS System Service Reference Manual for details.

In standalone mode (level 3), event flags are maintained by the VDS, and
the event flag macros call service routines within the VDS.

The following macros are used in both level 2R and level 3 programs to
reference event flags:
$SETEF — Sets specified event flags.

$CLREF — Clears specified event flags.
$READEF — Read the current status of specified event flags.
$WAITFR — Wait for a specified event flag to become set.
$WFLAND — Wait for a group of event flags to become set.

$WFLOR — Wait for one of a group of event flags to become set.
$QIOW — Queue an I/O request and wait for a specified event flag to
become set (indicating I/O completion). Equivalent to $QIO followed by

SWAITEFR.
Additionally, the $SETIMR (see Section 4.4.4, Timing) and $QIO (see
Section 4.2.1.1, I/O in User Mode) macros can optionally specify references
to event flags.

4.4.3

Asynchronous System Traps (ASTs)
An asynchronous system trap (AST) is a software-simulated interrupt
to a user-defined service routine (AST routine). ASTs enable the user
process to be notified asynchronously with respect to its execution of the

occurrence of a specific event. If an AST routine has been defined by the
user, the system interrupts the process and executes the AST routine when
that event occurs. The process by which AST routines are dispatched is
called AST delivery.
4.4.3.1

AST Delivery
Four macros, available to both level 2R and level 3 diagnostic programs,

facilitate the use of ASTs. These macros are $SETIMR, $QIO, $QIOW, and
$DS_CNTRLC. Each of these macros will accept the address of an AST
routine as an argument. The $SETIMR macro will cause the AST routine to
be entered when the specified amount of time has elapsed. The $QIO and
$QIOW macros cause the AST routine to be executed when the requested
I/O operation has completed. The $DS_CNTRLC macro will cause an AST
routine to be entered when the program user types a control-C.

ASTs may be enabled or disabled with the $SETAST macro. If ASTs are
disabled, ASTs will not be delivered and therefore the AST routines will
not be executed.
If a diagnostic program is waiting for an event flag (see Section 4.4.2,
Event Flags) or hibernating (see Section 4.4.4, Timing), ASTs will still be

delivered. After the AST routine has been executed, the program will be
returned to the state it was in prior to the AST delivery (unless, the AST
routine itself set the desired flag or woke the program).
4-13

Additional Components of a VAX/DS Diagnostic Program

4.4.3.2

AST Routines
An AST routine is entered via the MACRQO-32 instruction CALLG. Thus,

the routine must have an entry mask and must return by using RET
instruction. It must save (by specifying them in the entry mask) any
registers it uses, other than R0 or R1.
When an AST routine is entered, the argument pointer (AP) points to an
argument list in the format illustrated by Figure 4-4. The register values in
the argument list are those saved when the main-line code was interrupted

by delivery of the AST. The AST parameter is a value specified by the AST
parameter argument of the macro ($SETIMR, $QIO, or $QIOW) used to
request delivery of the AST. This argument can be used by the AST routine
to determine from where it was called.
Figure 4-4

Argument List Passed to an AST Routine

AST PARAMETER

R1
PC

PSL
ZK-4786-85

4.4.4

Timing
Facilities are provided for creating timing delays within a diagnostic
program. These facilities allow you to:
*

Specify a particular amount of time you wish to wait before proceeding

Cause the diagnostic program to stop executing until an expected event
occurs

Cause an asynchronous event to occur after a specified amount of time
has passed

The timing facilities provided by the VDS compensate for speed
differences among the various VAX process types. Therefore, all diagnostic
programs containing time-dependent operations must use the VDS timing

facilities in order to guarantee program compatability with all current and

future processor types.
The VDS timer services are accessed by macro calls. Some macros can
be used for both level 2R (user mode) and level 3 (standalone) programs,
while others may be used only for level 3 programs.

4-14

Additional Components of a VAX/DS Diagnostic Program

4.4.41

Timing Facilities Available in User Mode and Standalone Mode
The following is a list of macros that may be used by both level 2R and
level 3 programs to control time-dependent functions.
$GETTIM — Gets the current system time.

$SETIMR — Allows you to cause an event to take place after a specified
amount of time has passed.

$BINTIM — Converts an ASCII string that specifies a time into a numeric

value meaningful to the $SETIMR macro.

$ASCTIM — Converts a time from numeric representation to an ASCII
string.

$CANTIM — Cancels requests specified with the $SETIMR macro.
$HIBER — Causes processing to stop until an expected event occurs.
Referred to as “hibernation.”

$WAKE — Cancels a $HIBER request. Referred to as ““waking” the
program.

$DS_WAITMS — Delays sequential program execution for a specified
number of milliseconds.

$DS_CANWAIT — Cancels time remaining from a $DS_WAITUS or
$DS_WAITMS call

A typical use of these macros in standalone mode would be to issue a
$SETIMR macro that will cause an AST routine (see Section 4.4.3) to be
executed when the specified time has expired. Then a device’s interrupts
could be enabled. Some other processing could take place while waiting
for the interrupt. When the interrupt occurs, the interrupt service routine
could issue a $CANTIM macro to cancel the $SETIMR. If the interrupt does
not occur before the time period ends, the AST routine would be entered.
This routine could declare a timeout error. Program steps for this function
would be as follows:

Time O

I
|

Main Program:
Enable interrupts.

Continue.

THEN

IF error flag set

issue $DS_ERRxxxx macro

ELSE

TimeN

AST Routine:

Issue $SETIMR macro.

|
|
|
|
|
|
|

Interrupt Service Routine:

Process interrupt.
Issue $DS_CANTIM macro.
Return from interrupt.

IF interrupt does
not occur within
specified time
THEN
Set error flag.
Return.

continue.
(N > 0)

4-15

Additional Components of a VAX/DS Diagnostic Program

4.4.4.2

Timing Facilities Available in Standalone Mode Only

The following macro may be used only by level 3 programs.

$DS_WAITUS — Delays sequential program execution for a specified
number of microseconds.
A typical use of this service would be to enable a device’s interrupts,
followed by a call to the $DS_WAITUS service to see if an interrupt
occurred within a certain time frame.

The interrupt service routine

would set a flag to indicate that the interrupt occurred and would issue

a $DS_CANWAIT to cancel any time remaining from the wait service.
(Usually, the $DS_CANWAIT is optional and simply improves execution
time by eliminating unnecessary time remaining in wait loops.) After the

$DS_WAITUS call would be code to test the interrupt service flag. If the
flag is set, the interrupt occurred. If not, the entire time delay was used up,
indicating a time out condition. Program steps for this function would be
as follows:
Time 0

I
I
I
|
|
I
I
I
I
I
I
I

Main Program:

Interrupt Service Routine:

Set up device for I/O.
Enable interrupts.

Issue $DS_WAITxx macro call.

Process interrupt.

Test interrupt-occurred flag.

Set interrput-occurred flag.

IF flag not set

Issue $DS_CANTIM macro.

THEN

Return from interrupt.

issue $DS_ERRxxxx macro
ELSE
continue.

Time N

4.4.5

(N>
0

Condition Handling
The VDS contains condition handling routines that will handle all exception
conditions. It is therefore unnecessary under most circumstances for the

diagnostic program to provide exception handling facilities. However, the
VDS provides the ability for the diagnostic program to field exceptions
when necessary. The VDS searches for condition handlers in exactly the
same manner as VMS. As detailed in VMS documentation, handlers are

searched for in the following order:

4-16

If a primary handler exists, use it,

If secondary handler exists, use it.

Search call frames for address of handler.

Use ““last chance’’ handler.

Additional Components of a VAX/DS Diagnostic Program

If a handler is found, it can handle the condition and indicate a success

(8S$_CONTINUE) return, or not handle the condition and indicate a
resignal (SS$_RESIGNAL) return, which causes the handler dispatcher to
continue to search for a handler.
The VDS has a secondary condition handler, but it only services breakpoint
(BPT) and trace (T-bit) exceptions associated the the VDS’s breakpoint and

single-step facilities (see the VAX/DS Diagnostic Supervisor User’s Guide).
The main condition handling facility of the VDS is a last chance handler

that is capable of dealing with all exception conditions. This handler
will abort execution of the diagnostic program by causing the program’s

cleanup code to be executed.
In standalone mode, the VDS searches for a condition handler, and if none
is 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 on the
highest call frame of the VDS. This means that in user mode, the VDS last

chance handler will take precedence over the VMS last chance handler. It
also means that a diagnostic program cannot disable the VDS handler.

If a diagnostic program declares a handler in one of its call frames, that
handler will take precedence over the VDS last chance handler. In both

user mode and standalone mode, a condition handler may be specified by
loading the handler’s address into the first address of the call frame (the
address pointed to by the FP). In MACRO-32, this would be accomplished

with the instruction:
MOVAB

CONDHNDLR, (FP)

To declare a condition handler in BLISS-32, refer to the BLISS Language

Guide. In user mode, diagnostic programs may also declare condition
handlers by using the VM8 $SETEXP system service. Refer to the VAX/VMS
System Services Reference Manual.
When a condition handler is given control, it is passed two arguments.
The first argument is the address of a signal array and the second is the
address of a mechanism array. These arguments are passed in the manner

indicated by Figure 4-5.
Figure 4-5

Argument List Passed to a Condition Handler

<+—AP

ADDRESS OF SIGNAL ARRAY
ADDRESS OF MECHANISM ARRAY
ZK-4787-85

4-17

Additional Components of a VAX/DS Diagnostic Program

The signal array indicates the type of condition. Its format is shown in
Figure 4-6, where N is the total number of longwords (excluding the one
containing N) making up the array. Condition names are defined by the

$SSDEF macro (defined in STARLET.MLB listed in the VAX/VMS System
Services Reference Manual) and by the $DS_DSDEF VDS macro. If the
condition name parameter is DS$_UNEXPINT, the next argument is the
SCB vector offset.
Figure 4-6

Format of Signal Array

CONDITION NAME

0 TO 2 EXCEPTION-SPECIFIC
PARAMETERS

EXCEPTION PC
EXCEPTION PSL

ZK-4788-85

The mechanism array is illustrated in Figure 4-7.
Figure 4-7

Format of Mechanism Array

HANDLER ESTABLISHER FRAME FP
FRAME DEPTH

RO
R1

ZK-4789-85

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

fields the condition, it must place the status code SS$_CONTINUE in
RO before returning. If the handler does not field the condition, the

SS$_RESIGNAL status code must be placed in R0. Condition handlers
end with the MACRO-32 instruction RET. A condition handler may use

the SUNWIND macro to unwind the call frame (alter program flow) if it
cannot handle the condition. Unwinding is detailed in the discussion of

the SUNWIND macro in Chapter 5.
The condition handler will receive control when any exception condition

occurs. The handler must determine the type of exception (by examining
the signal array) and decide whether or not to handle the particular
condition. It is quite common to 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.

Additional Components of a VAX/DS Diagnostic Program

As an alternate method in standalone mode, the programmer may use the

VDS macro $DS_SETVEC to store the address of a condition handler in
the system control block (5CB). This allows the diagnostic program to field

specific exception conditions, instead of all of them. By using this method,
the VDS handler dispatcher is bypassed and control passes directly to the

handler pointed to by the exception vector. This handler must process the
exception and cannot resignal.

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

signal array.
Note: For additional information regarding condition handling, refer to the VAX

Architecture Handbook and the VAX/VMS Software Handbook.

4.4.6

Handling Control-Cs
Normally, when the user types a control-C, program control passes to a
VDS routine which aborts the current VDS function (such as 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 that is to be executed when a
control-C is typed.
When a control-C is typed, the VDS will pass program control to the

specified routine. This routine will perform any necessary processing and:
a.

Pass a return status code of zero (in R0), which will cause the VDS to

execute its own control-C handler. This technique is useful in cases
where it is desirable for the diagnostic program to perform some
processing of its own whenever a control-C is typed before the VDS

takes control.
b.

Pass a nonzero status code (in R0), to indicate that the VDS should
not execute its own control-C handler. In such a case, the VDS
will continue performing the function it was performing before the
control-C was typed.

¢.

Not return at all.

A possible use of options b and ¢ would be the case where a special

command language has been defined by the programmer (see
Section 4.2.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 might have the
same function as the VDS CONTINUE command (such as the RESUME
used above), in which case option b would be used. If the RESUME

command was not typed, the current function would be aborted and a new
command would be fetched from the user, so option c would be selected.

The $DS_CNTRLC macro also allows the programmer to disable control-C
servicing. This makes it possible to ensure that certain portions of code will

be executed without interruption, if necessary. Control-C servicing can be
disabled temporarily while this uninterruptable code is executing, and then

4-19

Additional Components of a VAX/DS Diagnostic Program

reenabled. If a control-C is typed while control-C servicing is disabled, the

control-C is not lost. It will be serviced when the servicing is reenabled.
It is important to note that Control-C servicing must not be disabled for longer

than 3 seconds at one time. Some run-time environments (APT in particular)
cannot tolerate a longer control-C response delay, nor do users appreciate

long periods of time when control-Cs are not serviced. 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 system service routine, the service routine will

check to see if a control-C has been typed. Suppose that by some chance
the program contains a large segment of code that does not call any system
service routines for a long period of time. If a control-C is typed, it will
not be acknowledged while this code is executing. In order to prevent this

problem, any large section of code (or small section that loops for a long

period of time) that does not call any system services must occasionally

issue the $DS_BREAK macro. This macro will call a service that simply
checks for a control-C and, if none has been received, merely returns. A

$DS_BREAK macro or some other system service must be issued at least every three
seconds. This is especially important in multiprocessor diagnostic programs
(see Section 4.6.10).

4.5

FILE MANAGEMENT

4.5.1

Introduction
It may be necessary for a diagnostic program to make reference to a
separate, subsidiary file. In such a case, two facilities are available:

The $DS_LOAD system service

Record management services (RMS)

The $DS_LOAD system service is useful for loading an entire file into a
buffer area of memory.
If more complex manipulations of a file are desired, such as referencing

specific records or blocks, the record management services should be used.
Level 2R (user mode) programs may use VAX-11 record management

services (RMS) to manipulate files. The entire range of RMS services is

available to the diagnostic program. Detailed information for VAX-11 RMS
is available in the VAX-11 Record Management Services Reference Manual.

Level 3 (standalone mode) programs are provided with a subset of the

VAX-11 RMS functionality. This functionality resides within the VDS. It
emulates VAX-11 RMS and is referred to in this manual as VDS RMS.
For those functions supported by VDS RMS, the program interface is
exactly the same as that of VAX-11 RMS; that is, both level 2R and level

3 programs will use the same macros. In user mode the service calls are
fielded by VMS, while in standalone mode they are handled by the VDS.
Table 4-2 lists the limitations of VDS RMS, as compared to VAX-11 RMS.

4-20

Additional Components of a VAX/DS Diagnostic Program

Table 4-2 Comparison of VAX-11 RMS and VDS RMS
VAX-11 RMS

e
e

Provides read and write access.
Supports sequential and

Supports sequential, random,

and random-by-RFA file access.

Console device cannot be

*
e

relative files.

Terminals can be accessed.

VDS RMS

referenced.

FAB, RAB, XAB, and NAM

e
e

Provides read access only.
Supports sequential files only.

Supports sequential and random-by-RFA
file access.

Terminals cannot be accessed.

Console device can be referenced
(RT-11 format only).

Only FAB, RAB, and FHC fields of XAB
are defined.

control structures are defined.

Also, many of the option bits defined in the VAX-11 RMS control structures
are not defined in VDS RMS.

When using RMS in a level 2R program, use the VAX-11 Record Management
Services Reference Manual as a reference guide. When using RMS in a level
3 program, use this manual as the main reference guide and the VAX-11
Record Management Services Reference Manual for additional information.
The RMS macros are defined in STARLET.MLB for MACRO-32 and
STARLET.L32 for BLISS-32. Note that these are VMS libraries and
therefore contain the VAX-11 RMS macro definitions. This means that
inclusion of unsupported RMS functions in a level 3 program will not be
detected until the program is actually executed. For a diagnostic program
to use RMS services on a file, the device on which the file resides must
have been previously attached. (This is true for both level 2R and level 3
programs.) If the device is the one from which the VDS was loaded, the
VDS will automatically build a p-table for the device. If the device is not
the VDS load device, the user can run the autosizer or manually attach the
device.

4.5.2

VDS RMS Overview

VDS RMS provides facilities for easily gaining access to and reading
sequential files on a disk or magnetic tape device, including the system'’s
console device. The records within a file may be accessed sequentially, or
they may be accessed randomly by a record’s file address (RFA), discussed
later.

VDS RMS consists of a set of routines that will service requests for reading
files, and a group of control structures that are used to pass information
about the file between the diagnostic program and the VDS. VDS RMS
supports three control structures: the file access block (FAB), an extended
attribute block (XAB), and the record access block (RAB). When a program

requests a file service, fields within these control structures will typically
need to be loaded. The control structures contain information such as the
name and type of file to be read, along with codes indicating how the file
is to be referenced.

4-21

Additional Components of a VAX/DS Diagnostic Program

4.5.3

The FAB, RAB, and XAB
The file access block (FAB) is a user control block that describes a
particular file. a FAB is allocated by using the $FAB macro. One FAB
must be defined for each file that is to be referenced.

The record access block (RAB) contains information about the file’s

records. There must be a RAB associated with each FAB. An RAB is
allocated by using the $RAB macro.

An extended attribute block (XAB) is an optional control block that

contains file attributes beyond those contained in a file’s FAB. While
VAX-11 RMS supports several different types of XABs, VDS RMS
supports
only the file header characteristics XAB (FHC XAB). The FHC XAB is
allocated with the $XABFHC macro.

Accessing the VDS RMS Control Structures
The various fields of the FAB, RAB, and XAB can be initialized at
program
assembly time by using the predefined keywords that exist for
each field.
The fields can also be loaded at run time. The fields defined for each
control block are named and described in the descriptions of the $FAB,

$RAB, and $XABFHC macros in Chapter 5.

VDS RMS control structure fields are defined by a mnemonic of the general

format:

structure$datatype_name

where structure is FAB, RAB, or XAB; datatype is a data type specifier

(see
Table 6-1); and name is the field name. Examples are: FAB$L_FNA
and
RABS$V_BIO.

To access a structure field at run time, use the field name as an offset
from the beginning of the structure. For example, suppose an FAB
has
been defined with the $FAB macro and has been labeled FAB_BLOCK.

Accessing fields of the FAB in a MACRO-32 program can be done with

instuctions such as:

MOVAB

FILE_NAME,

MOVB

RO, FAB_BLOCK+FABSB_FNS

FAB_BLOCK+FABSL_FNA

+Load

filename

addr.

;Load

filename

size.

In BLISS-32, the same fields would be referenced with the statement

FAB_BLOCK

[FABSIL_FNA]

FAB_BLOCK

[FAB$B_FNS)

4.5.4

FILE_NAME;

!Load

filename

addr.

-FILE_NAME_SIZE;

!Load

filename

size.

Offsets have been defined for some fields. Mnemonics are defined for
both the bit offsets and the mask values of these offsets. For example,
the
mnemonics FAB$V_BIO and FAB$M_BIO are defined for the bit offset
and
the mask value of BIO parameter in the FAC field of the FAB. Referencing
this bit at run time in MACRO-32 could be accomplished with the
following

(unrelated) instructions.
BISB

4-22

BBC

#FAB$M_BIO, FAB_BLOCK+FAB$B_FAC
#FABSV_BIO,FAB_BLOCK+FABS$B_FAC

;Load

filename

;jBranch

addr.

BIO clear.

Additional Components of a VAX/DS Diagnostic Program

Similar BLISS-32 statements would be:
FAB_BLOCK [FAB$B_FAC] = .FAB_BLOCK [FABSB_FAC] OR FABSM_BIO;
IF

.FAB_BLOCK [FAB$B_FAC] <FAB$V_BIO,1> THEN

...

;

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

FAC = <BIO,GET>,FOP

RWO,
-

XAB

FHCXAB

Similarly, fields can be loaded at run time with the $FAB_STORE or
$RAB_STORE macro in MACRO-32 or with $FAB_INIT or $RAB_INIT in
BLISS-32. This example shows how to use the $RAB_INIT macro.
$RAB_INIT

4.5.5

(BKT = 10,
FAB

FAB_BLOCK

RAC

SEQ,

FNA =

.FILE_NAME

[ADDRESS],

FNS

.FILE_NAME

[SIZE]);

Reading Files
Two methods 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 is more appropriate to the file
and operations being performed. It is also possible to combine the two
methods.

4.5.6

Record Processing
When using record processing, reading a file involves accessing records
within the file. The number, size, and contents of a file’s records are
immaterial to RMS and are determined by whatever utility created the file.
Two access methods are available for referencing records. The record
access method is specified by loading the record access (RAC) field in the
RAB. When specifying the RAC field, one of the following values may be
chosen.

SEQ — sequential access

Records retrieved through sequential access are returned in the order
in which they were stored. Once all the records have been retrieved,
any further attempt to sequentidlly access records in the file will cause
an end-of-file condition to be returned.
e

RFA — record’s file address access

When a record is read from a file, an internal representation of the
record’s location within the file is returned in the RFA field of the RAB.
VDS RMS can save the value contained in the RFA field and can use it
to again retrieve that record by using a random-by-RFA request.

Note: In VDS RMS, random-by-RFA access is supported for both disks and
magnetic tapes.
4-23

Additional Components of a VAX/DS Diagnostic Program

Before the records of a file can be read, a record stream to the file must
be established. A record stream is the association of a RAB to a FAB.
After the file has been opened with the $OPEN macro, the record stream

is established by placing the address of the FAB into the FAB field of the
RAB. Then a $CONNECT macro is issued.
Once the record stream has been established, records in the file can be
read using the $GET macro. The first $GET will cause the file’s first record

to be read, and each successive $GET will fetch the next record if the
RAB’s RAC field is set to SEQ. If the RAC field is set to RFA, then each

$GET will retrieve the record whose record file address (RFA) is stored in

the RAB’s RFA field.
To break the record stream after record processing has been completed,

a $DISCONNECT macro is issued. The $CLOSE macro is then used to

terminate processing of the file.

Example 4-1 illustrates record processing of a file.

Example 4-1

Record Processing with RMS

;

This

routine reads

a sequential

file

into

buffer.

BUFFER:

.PSECT

DATA,WRT,NOEXE

.BLKB

1000

BUFF_DESC:

Allocate

;

Descriptor

. LONG

;

Length

will

. LONG

BUFFER

;

Address

MY_FAB:

SFAB

FNM = <INFILE:>

;

File

MY_RAB:

S$RAB

FAB=MY_FAB, -

Record

1000-byte
for

buffer

set

run

time

buffer

access

block

access

block

UBF=BUFFER,
Usz=100

+PSECT

CODE,NOWRT,EXE

.ENTRY

SIMPLE,

"M<>

$OPEN

FAB=MY_FAB

Open the file.

BLBC

RO,EXIT

;

Exit

;

Connect

for

;

Exit

error.

SCONNECT
BLBC

RAB=MY_RAB
RO,EXIT

on
on

error.

record operations.

GET_RECORD:

$GET

RAB=MY_RAB

;

Get

BLBC

RO, CHECK_DONE

Branch

ADDL

MY_RAB+$W_RSZ,
-

;

Advance buffer

Get

record
on

error.

pointer

MY_RAB+RABSL_BUF
BRB

GET_RECORD

another

record

CHECK_DONE:
CMPL

RO, #RMSS_EOF

;

Done?

BNEQ

ERRORS

SCLOSE

FAB=MY_FAB

;

Return.

RET

ERRORS:

(Error

4-24

handler.)

error.

the

file.

Additional Components of a VAX/DS Diagnostic Program

4.5.7

BlockProcessing
Block processing makes it possible to directly read the blocks of a file,
ignoring the record structure that exists for the file.

To indicate that block I/O will be performed on a file, the BIO bit in the
FAC field of the FAB must be set before issuing the $§OPEN macro. To

perform block processing, the file must first be opened with the $OPEN
macro. Then a RAB must be associated with the file’s FAB by using
the $CONNECT 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 fetch the next sequential block of the
file.

When file processing has been completed, issue the $DISCONNECT
macro followed by the $CLOSE macro.

4.5.8

Mixing Block Processing and Record Processing
If the BRO bit in the FAC field of the FAB is set, both block processing and

record processing may be performed on the file. The BRO bit cannot be
set after the $OPEN macro has been issued.
It is possible to initially allow both block processing and record processing,
then at some later time to disable record processing and allow only block

processing. This is accomplished by setting the BIO bit in the ROP field of
the RAB (not the BIO bit in the FAC field of the FAB). Once this bit is set,
no further record processing will be allowed.

Mixing processing modes requires some caution. For example, when
switching from block reads to record reads on a disk, RMS’s next record
pointer and its next block pointer are both undefined, so the first $GET
after a SREAD and the first SREAD after a $GET must both use random-byRFA access. For magnetic tape devices, the pointers will indicate the next
block of the tape.

4.6

VDS in a Multiprocessor Environment
This section describes the VDS features that facilitate the execution of
diagnostic programs in a multiprocessor environment (one VAX system
with more than one processor, not a VAXCluster).
Note: The discussions that follow do not refer to the environment established

with the BOOT N command. BOOT N

is used in a multiprocessor

environment for uniprocessor operations only, whereas the services
discussed in these sections refer to multiprocessor operations. Refer to
the VAX/DS Diagnostic Supervisor User’s Guide for a detailed discussion on
the BOOT N command.

4-25

Additional Components of a VAX/DS Diagnostic Program

4.6.1

General Concepts
In a multiprocessor environment the processor used to boot the VDS is
called the primary processor (Pp). Each additional processor is called

an attached processor (Ap). (Attached processors are not related to the
VDS ATTACH command.) Processors labeled as primary and attached

are software definitions and do not imply any particular hardware
configuration. Refer to Chapter 2 of the VAX/DS Diagnostic Supervisor
User’s Guide for booting procedures on multiprocessor systems.
When the VDS is booted, it always assumes there is only one processor,

and there will always be only one copy of the VDS software. Control
portions of the VDS, such as the command line interpreter and the
command dispatcher, are executed only by the primary processor. Some
portions of the code, such as system services and exception handlers, may

be executed by any processor.

It is assumed that a common memory is shared by all processors.

Diagnostic programs are loaded by and initially executed by the primary
processor. A diagnostic program may consist of one or more secondary
portions that can be executed by one or more attached processors. In this

document, the code that will execute in the primary processor is referred
to as the primary process; code which will execute in an attached processor

is called an attached process. All multiprocessor diagnostic programs must

execute in kernel mode.
If a diagnostic program is going to test more than one processor, that
is, test the attached processors, each processor must be described by a
hardware parameter table (p-table). See Section 3.2 for more information

regarding p-tables.

4.6.2

Multiprocessing Macros
The VDS provides the following system services specifically for use in

multiprocessor environments:

$DS_BOOTATTACHED boots an attached processor, that is, the Ap
exits the halt state and enters the idle state. Prior to the state transition,

the attached processor’s SCB and stacks are built and initialized by the
primary processor.

$DS_STARTATTACHED causes an attached processor to exit the idle
state and enter the running state. The Ap will begin executing at the
address specified. This code (the attached process) must be delimited

by the $DS_BGNATTACHED and $DS_ENDATTACHED macros.

When execution of this code is complete, the processor is returned to

the idle state.

4-26

$DS_HALTATTACHED halts an attached processor, that is, the Ap
exits the idle state and enters the halt state. An Ap must be in the idle
state in order to be halted.

Additional Components of a VAX/DS Diagnostic Program

$DS_SHOWIDLE indicates which attached processors are currently in

the idle state.

$DS_EXIT is used to unconditionally branch to the end of the current
program segment. When the ATTACHED argument is used, the
branch destination is the $DS_ENDATTACHED macro (the call
to $DS_EXIT must be between the $DS_BGNATTACHED and
$DS_ENDATTACHED macros).

See Figure 4-8.

4.6.3

Executing in an Attached Processor

In order for a diagnostic program to execute an attached process, the
following steps must occur:
1

The attached processor must be booted using the
$DS_BOOTATTACHED service.

The attached process must be loaded either by including the code

within the source file of the code executing in the primary process or
by including it in a separate file. If you use a separate file, you must:

Call the $DS_GETBUF service to allocate memory space for the
attached process

Use the $DS_LOAD service or RMS services to load the file into
the space assigned by the $DS_GETBUF service

The $DS_STARTATTACHED service will pass the address of the
attached process to the attached processor. If the attached process has
been loaded into a buffer, the address is the same as the buffer itself.
The attached processor will begin execution; VDS system services may
be called.

You must repeat the process for each attached processor.

Figure 4-8

State Diagram for an Attached Processor

MR-2280-RA

The following table describes the conditions under which state transitions
will occur for a given attached processor. Any other state transitions are
undefined within the VDS.

4-27

Additional Components of a VAX/DS Diagnostic Program

Table 4-3

State Transitions for an Attached Processor

CURRENT

STATE

CONDITION

HALT

IDLE

The Pp executed the $DS_BOOTATTACHED
macro.

IDLE

HALT

The Pp executed the $DS_HALTATTACHED

IDLE

RUNNING

The Pp executed the $DS_STARTATTACHED

macro.

macro, or the Pp completed handling an
exception, CNTRL-C or breakpoint (see

Section 4.6.8)
RUNNING

IDLE

The Ap executed the $DS_ENDATTACHED
macro, i.e., completed the attached process, or

while executing the $DS_BREAK macro, it was
noted that an exception, CNTRL-C or breakpoint
occurred, and therefore the attached process was
preempted.

4.6.4

Using VDS System Services
Most system services may be called from attached processes. These
services provide an interlocking mechanism, transparent to the diagnostic
program, that ensures that only one processor will execute the service

routine at a time. If two or more processors often issue calls to the same

service, a large amount of system time may be spent waiting for one
processor to finish with the service so that the other one can use it. Also,

there is no way to determine which process will be serviced next; the order
is completely arbitrary. The next processor to execute the service will be

the first one to reference the interlocking flag after the service is released
(by the previous processor). It is assumed (but not guaranteed by the

software) that all requests will eventually be serviced.

The following services may not be called from an attached process:

$DS_CHANNEL

$DS_SETMAP
$DS_LOAD

$DS_PARSE
$DS_MMON

$DS_MMOFF
$DS_PRINTXx
$DS_ERRxxxx
$DS_ASKxxxx
$DS_SETVEC

$DS_CLRVEC
$DS_INITSCB
4-28

Additional Components of a VAX/DS Diagnostic Program

$DS_WAITMS
$DS_SETIMR
$DS_HIBER

$DS_WAKE

Additionally, the $DS_MMON and $DS_MMOFF services may not be
called from the primary process after it has booted any attached processors
($DS_BOOTATTACHED).

4.6.5

Memory Management
Memory mapping for all processors is identical. Any code within the VDS
that alters the page tables alters the tables for each processor because there
is one set of page tables for all processors. Page table base registers for
each processor simply point to the same address.

However, consider the following scenario:

A diagnostic program that creates attached processes runs.

Execution of the diagnostic program is stopped by control-C, a

breakpoint, or an exception condition.

A SET MM ON or SET MM OFF command is issued and then the
CONTINUE command is issued.

In this scenario, the state of memory management in the primary processor
will change when the SET MM command is issued. The state of memory

management in the attached processors, however, will not change until the
CONTINUE command is issued.

If each processor executes the $DS_GETBUF macro, $DS_RELBUF
cannot be used to separately release buffers allocated to each processor.
$DS_RELBUF deallocates the last allocated blocks regardless of which
process requested them. Therefore, all $DS_GETBUF and $DS_RELBUF
calls should be made by the primary process. Alternately, a globallyreferenced location can be used to track total buffer allocation. One
$DS_RELBUF call can then be issued to deallocate all allocated space at
once.

4.6.6

Timing
The primary processor may call the $DS_WAITUS, $DS_WAITMS, and

$DS_SETIMR services to establish timers. Attached processes may
only call the $DS_WAITUS service. It is important to note that only one
$DS_WAITUS request may be serviced at any time. If a process requests
the $DS_WAITUS service but the service routine is already in use by
another process, the requesting process is forced (by the VDS) to wait until
the service routine has completed its execution for the first process. The

result will be that the actual amount of time the second process has to wait
could be considerably longer than the actual wait time requested.

4-29

Additional Components of a VAX/DS Diagnostic Program

Be aware that if more than one process is waiting for service, it is arbitrary
as to which is serviced first, as there is no enqueueing of requests. It
is assumed (but not guaranteed by the software) that all requests will
eventually be serviced.

4.6.7

Input/Output
Only the primary processor may receive I/O device interrupts. (For some

processor types, this is a hardware restriction, for others, it is not. For
consistency’s sake, VDS implementation is the same for all processor

types.)

The $DS_CHANNEL service may be called only by the primary processor.
Device interrupt service routines only execute in the primary processor and

are considered a part of the main program. The main program may notify

an attached process that an interrupt has been received by setting an event
flag or by delivering an interprocessor interrupt to the attached processor.

It is important to remember that the $DS_CHANNEL service only allows

one device interrupt service routine in use at a time. Therefore, if several
devices are to be active at once, they must all be serviced by the same

interrupt service routine. (The routine can determine which device caused
the most recent interrupt, since the vector address is passed to the routine.)

4.6.8

Events
4.6.8.1

The SCB
Each processor has its own SCB that is initialized when the processor is
bootstrapped. All SCBs are initialized as follows:
*

All vectors in the first half page of the SCB point to the proper
exception handlers. Note that all handlers are the same for each
processor.

The rest of the SCB (the device interrupt vector area) points to the
VDS’s unexpected interrupt handler. Only the primary processor,
however, receives device interrupts (See Section 4.6.7, Input/Qutput).

The $DS_SETVEC, $DS_CLRVEC, and $DS_INITSCB services can only
be called by the primary process. If an attached process wants to modify
its SCB, it must do so directly. The SCB base address is returned by the

$DS_BOOTATTACHED service.

4.6.8.2

Exceptions and Unexpected Interrupts
The SCB of each processor is initialized so that exceptions vector into VDS

condition handlers that provide interlocking. The last chance handler stops

program execution on all processors, no matter which processor trapped

out. The primary processor reenters VDS CLI and issues the DS > prompt.
All attached processors reenter the idle state.
Diagnostic programs can override the VDS last chance handler by

specifying their own condition handlers, as described in Section 4.4.5,

Condition Handling.
4-30

Additional Components of a VAX/DS Diagnostic Program

Unexpected device interrupts are fielded by the primary processor (see
Section 4.6.7). The primary processor’s unexpected interrupt handler
reports the interrupt to the user and reenters VDS CLI, issuing the DS>
prompt. All attached processors are forced to reenter the idle state.
46.8.3

Interprocessor Interrupts

Diagnostic programs may implement interprocessor communication by
using interprocessor interrupts. In order to make use of interprocessor
interrupts, the SCBs of the various processors must be modified so that the
IP interrupt vector points to an interrupt service routine specified by the
program.

The VDS does not use interprocessor interrupts except during execution of
the $DS_HALTATTACHED service on VAX 88XX processors.
4.6.8.4

ASTs

Only the primary processor can execute a service that provides AST

delivery. These services, for level 3 programs, include $SETIMR,
$DS_CNTRLC, and indirectly, $DS_WAITMS.

4.6.8.5

Control-Cs
You can return to the VDS CLI and the DS> prompt by typing control-C.
Attached processors return to the idle state the next time they call the
$DS_BREAK service (see Section 4.4.6)

As is currently the case, a diagnostic program may declare its own
control-C handler to take precedence over the VDS control-C handler.
4.6.8.6

Breakpoints

Breakpoints can be set in attached processors. When a breakpoint is
executed by any processor, all processors in the running state exit that state
and enter the idle state (except for the primary processor, which enters
VDS command mode). Typing the CONTINUE command will cause all
processors to exit the idle state and return to the running state at the PC
from which they were preempted. Typing the NEXT command will cause
execution of the next instruction only if the breakpoint was executed by the
primary processor. This means that single stepping through code can only
occur in the primary process. However, breakpoints can be executed by
any processor.

Note: One or more breakpoints can be set in any one of the the processors

(primary or attached). However, breakpoints cannot be set in more than
one processor at a time, or unpredictable results will occur.
After a breakpoint has been executed, the general purpose registers (GPRs)
of the processor that executed the breakpoint can be examined. The GPRs
of the primary processor can always be examined; however, the GPRs
of any other attached processors will be inaccessible. (Commands for
examining registers are described in the VAX/DS Diagnostic Supervisor User’s
Guide.)

4-31

Additional Components of a VAX/DS Diagnostic Program

4.6.9

Communication Between the Primary and Attached Processes
The VDS does not provide services specifically for communication between
the primary process and the attached processes. However, the following
techniques and services can be used to design a scheme which will

facilitate necessary sycnchronization.

Event Flags — Useful for passing status information between the
primary and various attached processes. The $SETEF, $CLREF,

$SREADEF, $WAITFR, $WFLAND, and $WFLOR services can be used

by any process.

Interprocessor Interrupts — Available for use by the diagnostic
program.

See Section 4.6.8.3 and the VAX Architecture Standard

(SRM) for implementation specifics.

Common mailbox — A common data area can be specified in which to
pass information between the main process and the attached processes.
Dispatch vectors — Attached processes can call routines in the main
process via dispatch vectors, stored in a table in the main process, that
point to the routines. If these vectors are assigned absolute addresses,
attached processes not linked with the main process can reference
them.

(If the code for attached processes is linked with the main
process, dispatch vectors are unnecessary, since addressing references

may be relative and can be resolved at link time.)

4.6.10

Restrictions
The following restrictions apply to diagnostic programs using the
multiprocessing features of the VDS:

As with single processor systems, code executing in attached
processors must periodically call the $DS_BREAK service. This rule

is very important, as breakpoints, control-C’s, and exception handling
depend upon this rule being followed.
One simple method to ensure that all processors are periodically
issuing $DS_BREAK calls is to use the following scheme. The following
scheme, as shown in Table 4-4, is not sufficient if there are any sections
of code which loop but do not include calls to the $DS_BREAK
service.

4-32

Additional Components of a VAX/DS Diagnostic Program

Table 4-4

Algorithm for Demonstrating Use of $DS_BREAK

Primary Processor Code

Attached Processor Code

Continue_attached = FALSE;

$DS_BGNATTACHED

Attached_not_done = TRUE;

FOR N = 1 to maxtests DO

$DS_STARTATTACHED,————

BEGIN

WHILE Attached_not_done DO

Execute test(N);

$DS_BREAK;

END;

Attached_not_done = FALSE;
REPEAT

$DS_BREAK
IF errors THEN report errors.

UNTIL Continue_attached;

Attached_not_done = TRUE;

Continue.

Continue_attached = TRUE;

Continue.

$END_ATTACHED;

With the exception of $DS_BGNATTACHED and

$DS_ENDATTACHED, code executing in attached processors may
not use any of the program structure macros. (These macros include

$DS_BGNTEST, $DS_ENDTEST, $DS_BGNSUB, $DS_ENDSUB, and

the macros $DS_HEADER and $DS_DISPATCH that define such data
structures as the diagnostic header and the dispatch table, respectively.)
All initialization and clean-up code, looping, and error reporting must
be contained within code executed by the primary processor.
¢

The load image for a diagnostic program may not be larger than

approximately 63.5 kilobytes. If the total size of the code to be
executed by the primary and all attached processes exceeds the
maximum, you have to store the code for attached processors in

separate loadable images. (Refer to Section 4.6.3, Executing in an
Attached Processor.)

As stated previously, requests for system services are not enqueued.
Therefore, if several attached processes are simultaneously requesting
the same service, there is no way to determine which process will
be serviced next. It is assumed (but not guaranteed by the software)
that all requests will eventually be serviced. All services have an
interlocking mechanism, so that the next processor to execute the
service is the first one to reference the interlocking flag after the service
is released (by the previous processor.)

As discussed in Section 4.6.7, Input/Output, only the primary processor
can receive I/Q device interrupts.

Use the standard methods for declaring condition handlers, as
described in this guide as well as in the VMS documentation.
4-33

Additional Components of a VAX/DS Diagnostic Program

Code executing in an attached processor may not call the following

services:

$DS_CHANNEL
$DS_SETMAP
$DS_LOAD
$DS_PARSE
$DS_ MMON
$DS_MMOFF
$DS_PRINTx
$DS_ERRxxxx

$DS_ASKxxxx
$DS_SETVEC

$DS_CLRVEC
$DS_INITSCB
$DS_WAITMS
$DS_SETIMR
$HIBER
$WAKE
All multiprocessor diagnostic programs must execute in kernel mode.
It is recommended that the clean-up section call the

$DS_HALTATTACHED service for each attached processor, so that
each processor will be left in a known, static state.
After an attached processor has been booted via the

$DS_BOOTATTACHED service and after a breakpoint has been
executed by that processor, the EXAMINE and DEPOSIT commands
may be used to reference the processor’s GPRs and IPRs. The new
command, SET CPU, is used to select the processor to reference. The

PC of an attached processor cannot be modified with the DEPOSIT
command. Only the PSW portion of the PSL can be referenced.

4-34

VDS Macros and System Services

5.1

Introduction
This chapter describes in detail the format and function of each macro used
in VDS diagnostic programs. The macros are listed alphabetically, ignoring

the name’s prefix.

5.2

Coding System Service Macro Calls
The VDS system services are invoked by issuing a macro call for the

desired service and, if required, including an argument list to provide
values for the macro’s parameters. Before any system service macros can

be called, the $DS_DSSDEF macro must be declared, which defines the
system service entry points.

5.2.1

Fields of the Macro Name
Macro names consist of three fields. These fields are:

A prefix
This prefix may be $DS_d or §. Macro names having the $DS_ prefix

are defined exclusively for use with the VAX Diagnostic Supervisor.
Macro names having the § prefix are defined for use not only with the
VAX Diagnostic Supervisor, but also for any program running under
the VAX/VMS operating system.
Diagnostic programmers should not assume that a macro name’s prefix

implies any restriction on the run-time environment in which the macro
may be used. For instance, do 70t assume that macros with the $ prefix
may only be used for level 2R programs. Any run-time environment
restrictions that may exist for a particular macro will be noted in the

description of the macro.
A name

This name identifies the system service being invoked by the macro

call.

VDS Macros and System Services

A suffix
For MACRO-32 programs this suffix may be _S, _G, _L, or _DEF.

The _S suffix indicates that the system service routine is to be called

with a CALLS MACRO-32 instruction. If this suffix is used, the macro
call must include an argument list to provide values for required
parameters. (Specifying argument lists is detailed below.) Following is
an example of the _S form of the macro call:
$DS_ERRHARD_S

UNIT
=

LOG_UNIT,

MSGADR

HARD12_MSG,

PRLINK

HARD_MSGRTN,

SAVED_STATUS

If the _G suffix is used, the system service routine will be called with
a CALLG MACRO-32 instruction. In this case, only one argument is
specified with the macro call; the argument is the address of a list of

arguments to the 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. It will generate an
argument list. This argument list may later be passed to the system
service when the service is called with a _G suffix, if the list’s address
is used as the macro call’s argument. The following is an example of
the _L form of the macro call:
HARD_ARGLIST:

$DS_ERRHARD_L

UNIT

= LOG_UNIT,

MSGADR

HARD12

PRLINK

HARD

MSG,

MSGRTN,

SAVED_STATUS

The _DEF suffix simply generates symbolic names for the service’s
parameters. These symbolic names can be used to fill in fields of an

argument list that was defined with a _L. macro. Names will consist of
the service name, a $, an _, and the parameter name. The symbolic

names should be used as offsets from the beginning of the argument
list. The following is an example of the _DEF form of the macro call:
$DS_ERRHARD_DEF

MOVAL

HARD13_MSG,

HARD_ARGLIST+ERRHARDS_
MSGADR

For BLISS-32 programs, the suffix field of the macro call is always left
blank. System services are always called with a CALLS MACRO-32
instruction, and the macro call must include an argument list.

(Specifying argument lists in BLISS-32 is decribed in the next section.)
The following is an example of invoking a system service in BLISS-32.
$DS_ERRHARD
(UNIT

.LOG_UNIT,

MSGADR

HARD12_MSG,

PRLINK

HARD_MSGRTN,

.SAVED_STATUS);

VDS Macros and System Services

5.2.2

Macro Arguments
Most system services possess a set of input parameters for which values
must be provided when a service is invoked. Values are associated with
input parameters via arguments to the service’s macro call.

For MACRO-32 programs, macro arguments may be specified in either of
two ways:

Arguments may be specified as a list with each argument except the
last one followed by a comma. The position of each argument is

significant; thus, arguments must be listed 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 a macro call using positional specification of arguments is:
#3,,,

$SDS_GETBUF_S

Arguments may be specified by keywords. Keywords are symbolic
names that are assigned to input parameters. A keyword is defined for
every parameter of every macro, and that keyword is the name used
to identify the parameter in the description of the macro’s MACRO-32
format. For example, the $DS_GETBUF macro’s MACRO-32 format is
defined as:
$DS_GETBUF_x

pagcnt,

[retadr],

[phyadr],

[region]

(Brackets indicate optional arguments). Specifying this macro’s

arguments with keywords would appear as:
$DS_GETBUF_S PAGCNT=#3,

REGION=#1

Notice that when using keywords, it is not necessary to include commas
for unspecified arguments.

For BLISS-32 programs, macro arguments may also be specified

positionally or by keyword, but the choice is 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 formatspecifies keywords (capital letters followed by an equal
sign), the keyword must be used. If the description does not indicate
keywords, positional specification is required.

5.2.3

Use of RO and R1
Many system services make use of RO and R1. Never assume that these
two registers retain the same values after a system service call as they
had before the call. Unlike all other general purpose registers, which are
preserved during system service calls and do not change, RO and R1 are
not necessarily constant.

5-3

VDS Macros and System Services

5.2.4

Return Status Codes
All system services return an error status code in RO. This status code should
always be examined immediately after the diagnostic program regains program

control from the service. In addition to R0, some services return more status

information in R1.

All status codes have symbolic names associated with them. Each of these

names will have one of three possible prefixes. These prefixes are:

SS% — Most status codes begin with this prefix. For MACRO-32, these
codes are defined by the $SSDEF macro.

RMS$_ — Status codes associated with Record Management Services

(RMS) begin with this prefix. For MACRO-32, these codes are defined

by the $RMSDEF macro.
*

DS$_ — A few status codes begin with this prefix. Such codes are
defined for MACRO-32 by the $DS_DSDEF macro.

For status codes whose symbolic names begin with SS$_ br RMSS$_, the

low-order three bits indicate the severity of the error. Severity codes are as
follows:

Value (Binary)

Meaning

Symbolic Name

000

Warning

STS$K_WARNING

001

Success

STS$K_SUCCESS

010

Error

STS$K_ERROR

011

Informational

STS$K_INFO

100

Severe or fatal error

STS$K_SEVERR

101-111

Reserved

Symbolic names are defined by VMS with the $STSDEF macro.

SS$_NORMAL versus DS$_NORMAL — Most services return the normal

status to indicate that the service was successfully completed. For
some
services, the correct prefix on the normal return code is SS$_; for other

services, DS$_ is the proper prefix. These two status codes are nof
interchangable. Care must be taken that a program’s code uses the proper

normal status code for the particular service being invoked. Each service’s
macro description will indicate which code is correct.
For all status codes that indicate an error condition, bit 0 of R0 will be

cleared. For all other status codes, bit 0 of RO will be set. Thus for
MACRO-32 programes, it is possible to determine that an error has occurred

by simply using the BLBS or BLBC instruction. However, this method is
not recommended. Program readablility is improved if status codes
are

always tested by using symbolic names, as in the example:
$QI0O_G

QIO_ARGLIST

jEnqueue

CMPL

RO,

;If

BNEQ

QIO_ERROR

#SS$_NORMAL

I/0 request.

success,

;Else

branch

;Continue

then

continue.

the

error

handler.

VDS Macros and System Services

5.3

Conventions Used in this Chapter
In the macro descriptions that follow, certain conventions have been

adhered to. These conventions are as follows:

For macros that accept arguments, those arguments that are optional
have been indicated by enclosing the parameter name in brackets ([...]).
Macro parameters are listed in positional order; that is, if arguments
are to be listed positionally, they must be listed in the order indicated
in the macro format.

For MACROQO-32, the parameter name indicates the keyword that must
be used if arguments are to be specified with keywords.

For BLISS-32, keywords are indicated in capital letters. If a keyword is

not supplied in the macro format, the macro will not accept keyword
arguments. In such a case, arguments must be specified positionally.

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

— Values as arguments. If a value is required, the argument will

be interpreted as a value. Thus, if a literal is specified for the
argument, that literal will be interpreted as being the argument. If

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

—

Addresses as arguments. If an address is required, the argument
will be interpreted as an address. No translation of the argument
occurs.

—

Strings as arguments. If a string is required, the argument will
be interpreted as a literal string. For MACRO-32, strings must be
enclosed in angle brackets (<...>). For BLISS-32, strings must be
enclosed in single quotation marks (’..."), and if the string itself is to
contain the (") character, it must be included twice, as in 'Debbie”’s
Program’.

Some services require that the address of a 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 5-1.

Figure 5-1

Quadword String Descriptor

16 15
LENGTH OF STRING
ADDRESS OF STRING

ZK-4790-85

VDS Macros and System Services

String descriptors can be generated by using the .ASCID directive in
MACRO-32, the %ASCID directive in BLISS-32, or the $DS_STRING
macro.

5.4

System Service Descriptions
The following pages describe, in detail, how to use the VAX/DS system
services and macros.

$DS_ABORT

$DS_ABORT
The Abort Program or Test service can be used to stop execution of either
the whole diagnostic program or just the current test. If the program is
aborted, a system service is called. This service will execute the program’s
cleanup code and return control to the VDS command line interpreter. If
only the current test is aborted, the test is exited with the MACRO-32
instruction, RET, and the next selected test is called.

MACRO-32

$DS_ABORT

arg

(No suffix.)

BLISS-32
ARGUMENTS

$DS_ABORT

(ARG =arg),

PROGRAM or TEST. If PROGRAM is specified, then the program will be
aborted. If TEST is specified, the current test will be exited (with an RET
instruction), and the next selected test will be called. If no argument is
specified, the program will be aborted.

RETURN
STATUS

No status is returned, because $DS_ABORT TEST does not generate a
service call and $DS_ABORT PROGRAM does not allow program control
to return to the diagnostic program.

MACRO-32
EXAMPLE
$DS_ABORT

PROGRAM

$DS_ABORT

$DS_ABORT TEST

BLISS-32
$DS_ABORT

(ARG=PROGRAM);

$DS_ABORT

();

$DS_ABORT

(ARG=TEST);

5—

-J

EXAMPLE

$DS_S$SADD

$DS_SADD
The $DS_$ADD p-table descriptor macro is used to add the contents of the
value register (see Section 3.2.3.3) into a field of the p-table being built.
The field is fetched, the addition is performed, and the result is placed

back into the field.

MACRO-32

$DS_SADD

(offset, pos, size)

BLISS-32

$DS_SADD

(OFFSET

ARGUMENTS

= offset, POS = pos, SIZ =size);

offset

The byte offset into the p-table of the field to which the contents of the
value register are to be added.

pPoOsS
Bit position of the field, relative to the beginning of the byte specified by

“offset.”” If the field starts on a byte boundary, this value will be 0.

size
Number of bits making up the field. The size cannot be larger than 32.

NOTES

Bits added (or carried) beyond the field width are lost.

The contents of the value register are not changed.

.BYTE

pos

.BYTE

size

MACRO-32
EXAMPLE
OFFSET=HP$A_DEVICE,

$DS_SADD

<~X40>,

$DS_S$ADD

POS=0,

SIZE=32

offset

Beginning

~X8A

.WORD

Word

.BYTE

Bit

position

Code generated by macro (shown in Macro-32; Bliss-32 is equivalent):
;

structure

Bit

field

data

ADD
in

size

directive
word

offset

$DS_SADD

X000

BLISS-32
EXAMPLE
$DS_SADD

(OFFSET=%FIELDEXPAND(HPSA_DEVICE,O),
POS=%FIELDEXPAND(HP$SA DEVICE,1),
SI1ZE=%FIELDEXPAND(HP$SA_DEVICE,2));

$DS_S$ADD

(OFFSET=%X'40',

POS=0,

SIZ=32);

5-9

$ASCTIM

$ASCTIM
The Convert Binary Time to ASCII String system service converts the

contents of a quadword from 64-bit time format into an ASCII string. This
is the converse of the function performed by the $BINTIM service.

MACRO-32

SASCTIM_x

BLISS-32

SASCTIM

[timlen], timbuf, [timadr], [cvtfig]

([TIMLEN =timlen], TIMBUF = timbuf,
[TIMADR =timadr], [CVTFLG = cvtflg]);

ARGUMENTS

timlen

Address of a word to receive length of output string.

timbuf
Address of a character string descriptor (see Section 5.3) pointing to buffer
to receive converted string.

timadr
Address of the 64-bit time value to be converted. A value of 0 (the default)

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

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

RETURN

STATUS

SS$_NORMAL
-

SS$_IVTIME

full'y comp leted

ervice successfully

completed.

The specified relative time is equal to or greater than
10,000 days.

NOTES

The ASCII string returned by the service will be in the format specified

in the notes to the $BINTIM service.
2

To receive full absolute date and time, the ““timbuf’’ buffer length must
be 23 bytes. To receive the full relative day and time, the buffer length
must be 16 bytes. Specifying a shorter buffer length will cause the
returned string to be truncated to the buffer size. This may be useful
if, for example, only the absolute date is required, and not the time. It
is only necessary to provide a buffer that can hold the amount of the
returned string the caller wishes to receive.

5-10

$ASCTIM

”
MACRO-32
EXAMPLE
SASCTIM_S

STR_LENGTH, BUFPTR, TIME, #1

;
BLISS-32
EXAMPLE
SASCTIM (TIMLEN=STR_LENGTH, TIMBUF=BUFPTR, TIMADR=TIME, CVTFLG=1);

5-11

$DS_ASKADR

$DS_ASKADR
The $DS_ASKADR system service is used to obtain information from the
program user at run time. With this service, the diagnostic program can

Prompt the user with a message specified by the programmer

Obtain keyboard input from the user

Interpret and validate the input string

Store the value specified by the input string

The Ask for Address ($DS_ASKADR) system service is used when the
information requested from the user is an address.

MACRO-32

$DS_ASKADR_x

msgadr, datadr, [radix], [lolim],
[hilim], [defalt], [unused], [exword]

BLISS-32

$DS_ASKADR

(MSGADR =msgadr,

DATADR = datadr,
[RADIX = radix],

[LOLIM = lolim],
[HILIM = hilim],
[DEFALT = defalt],

[EXWORD = exword]);
ARGUMENTS

msgadr
Address of counted ASCII string to be used as user prompting message.

datadr
Address of longword to receive interpreted user response value.

radix
Radix in which the user response is to be interpreted. Legal values for
this parameter are defined by the macro $DS_PARDEF, and consist
of PAR$_BIN, PAR$_OCT, PAR$_DEC, and PAR$_HEX. The default is
hexadecimal.

lolim
Minimum acceptable value for numeric user reponse. The default is
(unsigned) 0.

hilim
Maximum acceptable value for numeric user response. The default is
(unsigned) FFFFFFFF (hexadecimal).

$DS_ASKADR

defalt

The value to be used if the user does not provide a response (user only
types return key). The default value for “’defalt” is 0. If no default is to be
used, then NODEF must be set in the ““exword”’ parameter.

unused

Reserved for expansion.

exword

The ““exception mask.” This is a longword containing “‘exception

flags.”” These flags are used to modify the interpretations of some of
the other parameters. Symbols for the exception flags are defined by
the $DS_PARDEF macro. Refer to the description of that macro for the
complete symbol names. The flags are:

NODEF — There is to be no default value for the user response. In

ATDEF — The argument specified for the ““defalt’”” parameter is the

ATLO — The argument specified for the “lolim” parameter is the

ATHI — The argument specified for the “hilim” parameter is the

other words, the ““defalt’”’ parameter is to be ignored.

address of a location containing the default value.

address of a location containing the low limit value.

address of a location containing the high limit value.

By default, all flags are cleared.
”

RETURN

STATUS

SS$_NORMAL
_

DS$_PROGERR

Senvi|

full ’

ervice successfully

leted

completed.

An incorrect number of arguments was supplied with
the macro.

NOTES

.
.
If the VDS control flag OPERATOR is clear and if no default value has
been specified for the prompting message, the diagnostic program will
be aborted. Thus, if the diagnostic program is intended to be executed
in an automated run-time environment (such as APT), these macros
cannot be used unless default values are provided.

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

If the VDS control flag PROMPT is set, the ranges and default values

To ensure that prompting messages are left-justified, precede each

Figure 5-2 illustrates the format of the ‘“valtab’’ table.

for user responses will be displayed along with the prompting message.
prompting message with a CR and LF.

5-13

$DS_ASKADR

Figure 5-2

Valtab Table Format

8 7

Unused

String Pointer 1

—& ASCIC string1

String Pointer 2

—& ASCIC string2

°.
)

String Pointer N

—& ASCIC stringN

ZK-4793-85

In a multiprocessing environment, $DS_ASKADR cannot be called
from within a block of code delineated by the $DS_BGNATTACHED

and $DS_ENDATTACHED macros.

“

MACRO-32

EXAMPLE
PROMPT :

.ASCIC

RESPONSE:

.LONG

/DEVICE ADDRESS:/
O

$DS_ASKADR_S -

5-14

MSGADR

PROMPT,

DATADR

RESPONSE,

RADIX

#PAR$_OCT,

LOLIM

#760000,

HILIM

#777777,

DEFALT

#764000

$DS_ASKADR

BLISS-32
EXAMPLE
BIND

PROMPT

UPLIT

(%ASCIC

LOW_LIM

760000,

HI_LIM

777777,

DEFAULT

764000;

‘IS

THE

DRIVE

WRITE-ENABLED?);

LITERAL

LOCAL
RESPONSE;

$DS_ASKADR

(MSGADR

PROMPT,

DATADR

RESPONSE,

RADIX

= PARS_OCT,

LAIM

.LOW_LIM,

HILIM

.HI_LIM,

DEFALT

.DEFAULT)

5-15

$DS_ASKDATA

$DS_ASKDATA
The $DS_ASKDATA system service is used to obtain information from the
program user at run time. With this service, the diagnostic program can

Prompt the user with a message specified by the programmer

Obtain keyboard input from the user

Interpret and validate the input string

Store the value specified by the input string

The Ask for Data ($DS_ASKDATA) system service is used when the
information requested from the user is a numeric value other than an

address.
e

MACRO-32

$DS_ASKDATA_Xx

msgadr, datadr, [radix], [mask],
[lolim], [hilim], [defalt], [unused],

[exword]
—

BLISS-32

$DS_ASKDATA

(MSGADR =msgadr,
DATADR = datadr,
[RADIX = radix],

[MASK = mask],

[LOLIM = lolim],
[HILIM = hilim],

[DEFALT = defalt],

[EXWORD = exword]);
e

ARGUMENTS

msgadr

Address of counted ASCII string to be used as user prompting message.

datadr
Address of longword to receive interpreted user response value.
Value is placed in bit position indicated by ‘“mask.”

radix
Radix in which the user response is to be interpreted. Legal values for
this parameter are defined by the macro $DS_PARDEF, and consist of
PARS$_BIN, PAR$_OCT, PAR$_DEC, and PAR$_HEX. The default radix is

decimal.

$DS_ASKDATA

mask
Mask indicating the bit positions within ““datadr’’ in which the interpreted
user response should be stored. The default value is FFFFFFFF
(hexadecimal), indicating 32 bits starting at bit 0.

lolim
Minimum acceptable value for numeric user reponse. Default is minus 2 to
the 31st power.

hilim
Maximum acceptable value for numeric user response. Default is 2 to the

31st power minus 1.

defalt
The value to be used if the user does not provide a response (user only
types return key). The default value for ““defalt”” is 0. If no default is to be
used, then NODEF must be set in the ““exword’” parameter.

unused
Reserved for expansion.

exword
The “exception mask.”” This is a longword containing ‘‘exception
flags.” These flags are used to modify the interpretations of some of

the other parameters.

Symbols for the exception flags are defined by

the $DS_PARDEF macro. Refer to the description of that macro for the
complete symbol names. The flags are:
¢

NODEF — There is to be no default value for the user response. In

other words, the ““defalt”” parameter is to be ignored.
¢

ATDEF — The argument specified for the ““defalt”” parameter is the

address of a location containing the default value.
e

ATLO — The argument specified for the ““lolim” parameter is the
address of a location containing the low limit value.

ATHI — The argument specified for the “‘hilim’’ parameter is the

address of a location containing the high limit value.
By default, all flags are cleared.

RETURN

STATUS

SS$_NORMAL
=

DS$_PROGERR

S |

full Y

ervice successfully

leted

completed.

eomp

An incorrect number of arguments was supplied with
the macro.

DS$_TRUNCATE

The value specified by the user was too large to fit
into the bit field specified by the caller. The value
was truncated in order to fit into the specified field.

5-17

$DS_ASKDATA

NOTES

If the VDS control flag OPERATOR is clear and if no default value has

been specified for the prompting message, the diagnostic program will
be aborted. Thus, if the diagnostic program is intended to be executed
in an automated run-time environment (such as APT), these macros
cannot be used unless default values are provided.
It is also required that if these macros are used in the DEFAULT
program section (see Section 3.8.3), default values must be provided.

If the VDS control flag PROMPT is set, the ranges and default values
for user responses will be displayed along with the prompting message.

To ensure that prompting messages are left-justified, precede each
prompting message with a CR and LF.

See Figure 5-2, Valtab Table Format, in the $DS_ASKADR macro
section.

In a multiprocessing environment, $DS_ASKDATA cannot be called
from within a block of code delineated by the $DS_BGNATTACHED

and $DS_ENDATTACHED macros.
g

MACRO-32

EXAMPLE
PROMPT :

.ASCIC

RESPONSE:

.LONG

$DS_ASKDATA_S

/DEVICE ADDRESS:/
0

MSGADR =

PROMPT,

DATADR

RESPONSE,

LOLIM

#0,

HILIM

#12,

DEFALT

BLISS-32

EXAMPLE
BIND

PROMPT

UPLIT

(%ASCIC

'IS

THE

DRIVE

WRITE-ENABLED?);

LOCAL
RESPONSE;

$DS_ASKDATA

5-18

(MSGADR = PROMPT,
DATADR

RESPONSE,

LOLIM

HILIM

132,

DEFALT

DEFAULT_PAGE_WIDTH)

$DS_ASKLGCL

$DS_ASKLGCL
The $DS_ASKLGCL system service is used to obtain information from the
program user at run time. With these services, the diagnostic program can
¢

Prompt the user with a message specified by the programmer

Obtain keyboard input from the user

|nterpret and validate the input string

Store the value specified by the input string

The Ask for Logical Response ($DS_ASKLGCL) system service is used
to ask the user a question that can be answered with a “‘yes’ or ‘‘no’’

response. Optionally, the caller can specify addresses of routines that will
automatically be branched to on a “‘yes’’ or ‘‘no’’ response.

MACRO-32

$DS_ASKLGCL_x

BLISS-32

$DS_ASKLGCL

msgadr, datadr, [pos], [yexfer],
[noxfer], [defalt]

(MSGADR = msgadr,
DATADR = datadr,
[POS = pos],

[YEXFER = yexfer],
[NOXFER = noxfer],
[DEFALT = defalt]),

ARGUMENTS

msgadr

Address of counted ASCII string to be used as user prompting message.

datadr
Address of longword to receive interpreted user response value.
Value will be placed in one bit, indicated by ““pos.”” The bit can be
compared with PAR$_NO and PAR$_YES, defined in $DS_PARDEF
(No = 0, yes = 1).

radix
Radix in which the user response is to be interpreted. Legal values for
this parameter are defined by the macro $DS_PARDEF, and consist of
PARS$ _BIN, PAR$_OCT, PAR$_DEC, and PAR$_HEX. The default radix is
decimal.

pPos
Bit offset from ‘‘datadr,” indicating where interpreted user response is to
be stored. The legal range is 0 through 7. Default is 0, indicating value
should be stored starting at bit 0 of ““datadr.”

5-19

$DS_ASKLGCL

lolim
Minimum acceptable value for numeric user reponse. Default is minus 2 to
the 31st power.

hilim
Maximum acceptable value for numeric user response. Default is 2 to the
31st power minus 1.

defalt
The value to be used if the user does not provide a response (user only
types return key). The default value for ““defalt’”” is 0, which is equivalent to
a “‘no”’ response. If no default is to be used, then NODEF must be set in
the ““exword’” parameter.
For the $DS_ASKLGCL macro, default values may be specified by the
symbols PAR$_NO and PARS$_YES, defined by the $DS_PARDEF macro.

yexfer
Address to branch to if user response is ““yes.”” Default is 0, meaning no
branch will take place.

noxfer
Address to branch to if user response is ““no.”” Default is 0, meaning no
branch will take place.
'

unused
Reserved for expansion.

exword
The ““exception mask.” This is a longword containing “‘exception

flags.”” These flags are used to modify the interpretations of some of
“the other parameters. Symbols for the exception flags are defined by
the $DS_PARDEF macro. Refer to the description of that macro for the
complete symbol names. The flags are:
¢

NODEF — There is to be no default value for the user response. In
other words, the ‘“defalt”” parameter is to be ignored.

ATDEF — The argument specified for the ‘“defalt’”” parameter is the
address of a location containing the default value.

ATLO — The argument specified for the “lolim’ parameter is the
address of a location containing the low limit value.

ATHI — The argument specified for the “hilim’’ parameter is the

address of a location containing the high limit value.
By default, all flags are cleared.

RETURN

STATUS

SS$_NORMAL

Service successfully completed.

DS$_PROGERR

An incorrect number of arguments was supplied with
the macro.

5-20

$DS_ASKLGCL

NOTES

.
:
If the VDS control flag OPERATOR is clear and if no default value has
been specified for the prompting message, the diagnostic program will
be aborted. Thus, if the diagnostic program is intended to be executed
in an automated run-time environment (such as APT), these macros

cannot be used unless default values are provided.

It is also required that if these macros are used in the DEFAULT

program section (see Section 3.8.3), default values must be provided.
If the VDS control flag PROMPT is set, the ranges and default values

To ensure that prompting messages are left-justified, precede each

See Figure 5-2, Valtab Table Format, in the $D5_ASKADR macro

for user responses will be displayed along with the prompting message.
prompting message with a CR and LF.
section.

In a multiprocessing environment, $DS_ASKLGCL cannot be called
from within a block of code delineated by the $DS_BGNATTACHED

and $DS_ENDATTACHED macros.

MACRO-32
EXAMPLE
/DEVICE ADDRESS:/

.ASCIC

PROMPT :
RESPONSE:

.LONG O

$DS_ASKLGCL_S MSGADR

PROMPT,

DATADR

RESPONSE

BLISS-32
EXAMPLE
BIND

PROMPT = UPLIT (%ASCIC ‘IS THE DRIVE WRITE-ENABLED?);

LOCAL

RESPONSE;

$DS_ASKLGCL (MSGADR=PROMPT, DATADR=RESPONSE) ;

$DS_ASKSTR

$SDS_ASKSTR
The $DS_ASKSTR system service is used to obtain information

from the

program user at run time. With these services, the diagnostic
program can

Prompt the user with a message specified by the programmer

Obtain keyboard input from the user

Interpret and validate the input string

Store the value specified by the input string
The Ask for Character String ($DS_ASKSTR) system service is used to
obtain an alphabetic character string from the user. 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 indicate to the
caller
which response was provided.

MACRO-32

$DS_ASKSTR_x

msgadr, bufadr, [maxlen], [valtab],
[defadr]

BLISS-32

$DS_ASKSTR

(MSGADR =msgadr,
BUFADR = bufadr,

[MAXLEN = maxlen],

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

ARGUMENTS

msgadr
Address of counted ASCII string to be used as user prompting message.

datadr
Address of longword to receive interpreted user response value.

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

maxlen
Size of the buffer specified in “‘bufadr.”” The default value is 72.

valtab
Address of table containing list of string pointers. See Note
4 for table
format. Each table entry points to a counted ASCII string that
represents
a valid user response. The system service will compare actual
user input
to the valid responses. If a match is found, the number of the
table entry
pointing to the matched string will be returned in R1. If a match
is not
found, the system service will inform the user that an invalid response
has
been issued and will then reissue the prompt message.

5-22

$DS_ASKSTR

If this parameter is 0 (the default), no validation will take place.

defadr

Address of counted ASCII string to be used as a default user response.
The default value for this parameter is 0, which means there is no default
user response.

radix
Radix in which the user response is to be interpreted. Legal values for
this parameter are defined by the macro $DS_PARDEF, and consist of
PAR$ BIN, PAR$_OCT, PAR$_DEC, and PAR$_HEX. The default radix is
decimal.

lolim

Minimum acceptable value for numeric user reponse. Default is minus 2 to
the 31st power.

hilim

Maximum acceptable value for numeric user response. Default is 2 to the
31st power minus 1.

defalt

The value to be used if the user does not provide a response (user only
types return key). The default value for ““defalt” is 0. If no default is to be
used, then NODEF must be set in the “exword’” parameter.

unused
Reserved for expansion.

exword
The ““exception mask.”” This is a longword containing ““exception
flags.” These flags are used to modify the interpretations of some of
the other parameters. Symbols for the exception flags are defined by
the $DS_PARDEF macro. Refer to the description of that macro for the
complete symbol names. The flags are:

NODEF — There is to be no default value for the user response. In
other words, the “defalt” parameter is to be ignored.

ATDEF — The argument specified for the “defalt” parameter is the

ATLO — The argument specified for the ““lolim”" parameter is the
address of a location containing the low limit value.

ATHI — The argument specified for the “hilim’ parameter is the
address of a location containing the high limit value.

address of a location containing the default value.

By default, all flags are cleared.

RETURN

STATUS

SS$_NORMAL
-

DS$_PROGERR

S _

full y

ervice successfully

leted

completed.

comp

An incorrect number of arguments was supplied with
the macro.

5-23

$DS_ASKSTR

DS$_TRUNCATE

The string supplied by the user was too long to fit
into the buffer pointed to by “*bufadr.”” The string
was truncated in order to fit into the buffer.

OTES

NOTE

1 If the VDS control flag OPERATOR is clear and if no default value has

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

If the VDS control flag PROMPT is set, the ranges and default values
for user responses will be displayed along with the prompting message.

To ensure that prompting messages are left-justified, precede each
prompting message with a CR and LF.

See Figure 5-2, Valtab Table Format, in the $DS_ASKADR macro

section.
5

In a multiprocessing environment, $DS_ASKSTR cannot be called from
within a block of code delineated by the $DS_BGNATTACHED and

$DS_ENDATTACHED macros.

L
.

MACRO-32

EXAMPLE
PROMPT :

.ASCIC

RESPONSE:

L.LONG

$DS_ASKSTR_S

/DEVICE

ADDRESS:/

MSGADR

PROMPT,

DATADR

RESPONSE,

MAXLEN

—

BLISS-32
EXAMPLE
BIND

PROMPT

UPLIT

(%ASCIC

’'IS

THE

DRIVE

WRITE-ENABLED?);

LOCAL

RESPONSE;

$DS_ASKSTR

5-24

(MSGADR=PROMPT,

DATADR=RESPONSE,

MAXLEN=5);

$DS_ASKVLD

$DS_ASKVLD
The $DS_ASKVLD system service is used to obtain information from the
program user at run time. With these services, the diagnostic program can
e

Prompt the user with a message specified by the programmer

Obtain keyboard input from the user

Interpret and validate the input string

Store the value specified by the input string

The Ask for Data Field ($DS_ASKVLD) system service is used to obtain a
numeric value from the user and insert the value into a data field indicated
by a position and size. This service is useful for loading fields in large data
structures (greater than 32 bits).

00—

$DS_ASKVLD_x

MACRO-32

msgadr, datadr, [radix], [pos], [siz€],
[lolim], [hilim], [defalt], [unused],
[exword]

[

BLISS-32

$DS_ASKVLD

(MSGADR =msgadr,
DATADR = datadr,
[RADIX = radix],

[POS = pos],
[SIZE = size],
[LOLIM = lolim],
[HILIM = hilim],

[DEFALT = defalt],
[EXWORD = exword]);
ARGUMENTS

msgadr

Address of counted ASCII string to be used as user prompting message.

datadr
Address of longword to receive interpreted user response value.
Value is placed in field indicated by “’pos’” and “’siz,”” where ““pos’’ is bit
offset from “’datadr.”

radix
Radix in which the user response is to be interpreted. Legal values for
this parameter are defined by the macro $DS_PARDEF, and consist of
PAR$_BIN, PAR$_OCT, PAR$_DEC, and PAR$_HEX. The default radix is
decimal.

5-25

$DS_ASKVLD

pos
Bit offset from “’datadr,”” indicating where interpreted user response is to
be stored. Default is 0, indicating value should be stored starting at bit 0 of

“datadr.” Legal range normally is 0 through the largest value that can be
stored in a longword. However, if a register is specified for “‘datadr,”” then

the legal range for “pos’’ is 0 through 31.

size
Number of bits in “datadr”” in which interpreted user response is to be

stored. Range is 1 through 32.

lolim
Minimum acceptable value for numeric user reponse. Default is minus 2 to

the 31st power.

hilim
Maximum acceptable value for numeric user response. Default is 2 to the

31st power minus 1.

defalt
The value to be used if the user does not provide a response (user only
types return key). The default value for ““defalt’’ is 0. If no default is to be
used, then NODEF must be set in the ““exword’’ parameter.

unused
Reserved for expansion.

exword
The “exception mask.”

This is a longword containing “’exception
flags.”” These flags are used to modify the interpretations of some of
the other parameters. Symbols for the exception flags are defined by
the $DS_PARDEF macro. Refer to the description of that macro for the
complete symbol names. The flags are:
*

NODEF — There is to be no default value for the user response. In
other words, the “defalt’” parameter is to be ignored.

ATDEF — The argument specified for the “‘defalt” parameter is the

address of a location containing the default value.
*

ATLO — The argument specified for the ““lolim” parameter is the
address of a location containing the low limit value.

ATHI — The argument specified for the ““hilim”’ parameter is the

address of a location containing the high limit value.

By default, all flags are cleared.

5-26

$DS_ASKVLD

“

RETURN
STATUS

SS$_NORMAL

Service successfully completed.

DS$_PROGERR

An incorrect number of argurhents was supplied with

DS$_TRUNCATE

The value specified by the user was too large to fit

the macro.

into the bit field specified by the caller. The value
was truncated in order to fit into the specified field.

—

NOTES

If the VDS control flag OPERATOR is clear and if no default value has
been specified for the prompting message, the diagnostic program will
be aborted. Thus, if the diagnostic program is intended to be executed
in an automated run-time environment (such as APT), these macros

cannot be used unless default values are provided.

It is also required that if these macros are used in the DEFAULT
program section (see Section 3.8.3), default values must be provided.
If the VDS control flag PROMPT is set, the ranges and default values
for user responses will be displayed along with the prompting message.
To ensure that prompting messages are left-justified, precede each
prompting message with a CR and LF.

See Figure 5-2, Valtab Table Format, in the $DS_ASKADR macro
section.

In a multiprocessing environment, $DS_ASKVLD cannot be called from
within a block of code delineated by the $DS_BGNATTACHED and
$DS_ENDATTACHED macros.

MACRO-32
EXAMPLE
PROMPT :

+ASCIC

RESPONSE:

.LONG

MSGADR
DATADR
RADIX

POS

SIZE
LOLIM

HILIM

$DS_ASKVLD_S

/DEVICE ADDRESS:/
O

PROMPT,
RESPONSE,

#PARS_DEC,
#0,

#4,
#1,

5-27

$DS_ASKVLD

LTI,

BLISS-32
EXAMPLE
BIND
PROMPT

.
=

UPLIT

(%ASCIC

'IS

THE

LOCAL
RESPONSE
;

$DS_ASKVLD

5-28

(MSGADR = PROMPT,
DATADR

RADIX

= PAR$_DEC,

RESPONSE,

POS

=0,

SIZE

LOLIM

HILIM

3);

DRIVE

WRITE-ENABLED?);

$ASSIGN

$ASSIGN
The Assign I/O Channel system service of VMS is used to provide an I/0
channel that can be used by the caller to communicate with a peripheral
device in user mode. Level 2R programs must issue the $ASSIGN macro
before the $QIO macro can be used. Refer to Section 5.3 for details of I/0O
operations in user mode.

This service can also be used to create a logical link with a remote node
on a network. Refer to the DECnet-VAX User’s Guide for details.

devnam, chan, [acmode], [mbxnam]

MACRO-32

$ASSIGN_x

BLISS-32

$ASSIGN

ARGUMENTS

devnam
Address of a character string descriptor (see Section 5.3) pointing to the

(DEVNAM =devnam, CHAN = chan,

[ACMODE = acmode],
[MBXNAM = mbxnam]),

device name string. The string may be either a physical device name or a

logical name. If the first character of the string is an underscore (_), the
name is a physical name. Otherwise, one level of logical name translation
is performed and the equivalence name, if any, is used.

If the device name contains a double colon (::), VMS assigns a channel to
the device NET0: and performs an access function on the network.

chan

Address of a longword to receive the channel number assigned.

acmode

Access mode to be associated with the channel. The specified access
mode is maximized with the access mode of the caller. I/O operations on
the channel can only be performed from equal and more privileged access

modes. Legal values are 0 for Kernel, 1 for Executive, 2 for Supervisor, and
3 for User.

mxbnam
Address of a character string descriptor (see Section 5.3) pointing to the
logical name string for the mailbox to be associated with the device, if
any. The mailbox receives status information from the device driver. An
address of 0 implies no mailbox. This is the default value.

$SASSIGN

e
II—

RETURN

STATUS

SS$_NORMAL

Service successfully completed.

SS$_REMOTE

Service successfully completed. A logical link is

established with the target on a remote node.

SS$_ABORT

A physical line went down during a network correct
operation.

SS$_ACCVIO

A device or mailbox name string or string descriptor
cannot be read by the caller, or the channel number
cannot be written by the caller.

SS$_DEVACTIVE

A mailbox name has been specified, but a mailbox

SS$_DEVALLOC

Warning. The device is allocated to another

is already associated with the device.

process.

SS$_DEVNOTMBX

A logical name has been specified for the associated

mailbox, but the logical name refers to a device that

is not a mailbox.

SS$_EXQUOTA

The target of the assignment is on a remote node
and the process has insufficient buffer quota to
allocate a network control block.

SS$_INSFMEM

The target of the assignment is on a remote node,

and there is insufficient dynamic system memory to

complete the request.

SS$_IVDEVNAM

No device name was specified, or the device or
mailbox name string contains invalid characters. If

the device name is a target on a remote node, this
status code indicates that the Network Control Block

has an invalid format.

SS$_IVLOGNAM

The device or mailbox name string has a length of 0
or has more than 63 characters.

SS$_NOIOCHAN

No I/O channel is available for assignment.

SS$_NOLINKS

No logical network links are available.

SS$_NOPRIV

The process does not have the privilege to perform
network operations.

SS$_NOSUCHDEV

Warning. The specified device or mailbox does not

exist.

SS$_NOSUCHNODE

The specified network node is nonexistent or

SS$_REJECT

The network connect was rejected by the network

unavailable.

software or by the partner at the remote node; or

the target image exited before the connect confirm

could be issued.

NOTES

Refer to the VAX/VMS System Services Reference Manual for notes

on the

$ASSIGN system service. This manual should be read before attempting

I/O operations in user mode.

5-30

$ASSIGN

MACRO-32
EXAMPLE
/TTA2:/
1

+ASCID
. BLKL

TTNAME :
TTCHAN:

; TERMINAL DESCRIPTOR
;sTERMINAL CHANNEL NUMBER

DEVNAM=TTNAME,

SASSIGN_S

CHAN=TTCHAN

BLISS-32
EXAMPLE
BIND

TTNAME = UPLIT

(%ASCID

’'TTA2:');

OWN

TTCHAN

SASSIGN

VECTOR;

(DEVNAM=.TTNAME,

CHAN=TTCHAN);

5-31

$DS_ATTACH

$DS_ATTACH
The Attach Device system service can be used to ‘‘attach’’ a device
automatically from within the diagnostic program, instead of requiring
the program user to issue the ATTACH command. Attaching devices is

discussed in Section 3.2. An example of when it might be desirable to use
the $DS_ATTACH macro is the case in which record management services
(RMS) are to be used to reference a file on a device other than the VDS

default load device.

MACRO-32

$DS_ATTACH_x

BLISS-32

$DS_ATTACH

ARGUMENTS

cmd, [omt]

(CMD =cmd, [PMT

= pmt]);

cmd

Address of a quadword descriptor that points to a valid ATTACH

command argument string. If the argument string does not contain every

necessary response to each ATTACH prompt, the “pmt’” parameter must

also be specified. (The argument string should not include prompting

strings).

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

error messages and prompting messages if the command string pointed

to by “cmd” is incomplete or in error. This parameter is optional only if
the programmer is absolutely sure that the specified command string will

always be correct for any hardware configuration. Using the contents of
this buffer is discussed in Note 1.

“

RETURN

STATUS

SS$_NORMAL

Service successfully completed.

DS$_BADTYPE

An invalid device type was specified in the argument
string.

DS$_BADLINK

The device link specified in the argument string is
not attached.

DS$_ILLUNIT

The device unit number was required and not given,
or was too large.

DS$_DEVNAME

The device name specified in the argument string is
invalid.

SS$_BADPARAM

A numeric argument was specified in an invalid radix
or was out of range.

SS$_INSFARG

The argument string was incomplete.

$DS_ATTACH

NOTES

If an argument in the argument string is invalid, or if the argument
string is incomplete, the following will occur:

One of the error status codes will be returned.

b. The length field of the quadword descriptor pointed to by “‘cmd”
will be altered to reflect the length of the valid portion of the
argument string.

c. The buffer described by ““pmt’”’ will contain a VDS-generated error
message and the user prompt for the invalid or missing argument.

The contents of the “‘pmt’” buffer can be used as the prompting
string”(“‘msgadr’’ parameter) of a $DS_ASKSTR macro. The user’s
response could then be added to the argument string, after the last
valid argument. The argument string’s size would then be readjusted
and the $DS_ATTACH macro would be reissued. (Note that a p-table
is not actually built until all arguments are valid, so this process can be

repeated until the user has supplied a complete argument string.) This
service will not display any information on the user’s terminal. Thus if
an error occurs, simply using $DS_ASKSTR macro to display the error
message and prompt is insufficient, since the user will have no idea
what device is being attached! It will be necessary for the program to
display an explanatory message indicating (1) that an attach was being
attempted and (2) which device was being attached.

”

MACRO-32
EXAMPLE
CMDLINE:

.ASCID

/RH780 SBI RHO 8 5/

$SDS_ATTACH_S CMDLINE;

—

BLISS-32
EXAMPLE
BIND

CMDLINE = UPLIT (%ASCID 'RH780 SBI RHO 8 5');

$DS_ATTACH

(CMD=.CMDLINE);

5-33

$DS_BCOMPLETE

$DS_BCOMPLETE
The $DS_BCOMPLETE and $DS_BNCOMPLETE program control

macros
can be used to test the return status of a system service (or
any routine
which returns a status code in R0) and branch if the
service’s operation
was ‘“‘complete’ or ‘‘incomplete.”’

“
MACRO-32

$DS_BCOMPLETE

aar

“

BLISS-32

Not supported for BLISS-32, since testing RO is implicit in

See the example below.

the language.

ARGUMENTS

adr

Address to branch to if tested condition is satisfied.
“

NOTES

For all error status codes, bit 0 is clear. Therefore, this
macro simply

generates the following code:
$DS_BCOMPLETE

BLBS

RO, adr

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

the service (or other) routine to determine the exact nature

of the error.

MACRO-32

EXAMPLE
$DS_GETBUF

#2,

$DS_BCOMPLETE

GOOD_BUF

RETADDR,

PHYSADDR

BLISS-32
EXAMPLE
IF

$DS_GETBUF

5-34

(PAGCNT=2)

THEN

...

$DS_BERROR

$DS_BERROR
The $DS_BERROR and $DS_BNERROR program control macros can be

used to test the return status of a system service (or any routine which
returns a status code in RO} and branch if the service’s operation was in
error or was error-free.

MACRO-32

$DS_BERROR

adr

BLISS-32

Not supported for BLISS-32, since testing R0 is implicit in the language.

ARGUMENTS

adr

See the example below.

NOTES

Address to branch to if tested condition is satisfied.

For all error status codes, bit 0 is clear. Therefore, this macro simply
generate the following code:
$bS_BERROR -

BLBC RO,adr

If an error status code is detected, the contents of R} should be

compared with all error codes that could possibly be returned from
the service (or other) routine to determine the exact nature of the error.

MACRO-32

EXAMPLE
$DS_GPHARD
$DS_BERROR

LOG_UNIT, ADDRI
10$

BLISS-32
EXAMPLE
IF NOT

$DS_GPHARD

(UNIT=.LOG_UNIT,

RETADR=ADDR1l)

THEN

...

5-35

$DS_BGNATTACHED

$DS_BGNATTACHED—S$DS_ENDATTACHED
In a diagnostic program that tests multiple processors, use the

$DS_BGNATTACHED and $DS_ENDATTACHED macros to delineate
code that is to be executed in an attached processor. These macros
are used whether the code is included in the loadable image of the main

diagnostic program or it is a separate loadable image. (See Section 4.6.)

$DS_BGNATTACHED indicates the beginning of the code and creates
a label that can be used with the $DS_STARTATTACHED service. The

$DS_ENDATTACHED macro generates code that will send the processor
back to its idle loop.

MACRO-32

$D§_BG NATTACHED

routine_name, mask

$SDS_ENDATTACHED
BLISS-32

$DS_BGNATTACHED

(ROUTINE_NAME = routine_name);

$DS_ENDATTACHED:;
ARGUMENTS

routine_name

Labels the routine and points to its first instruction.

mask
List of register names used in the entry mask.

$DS_BGNATTACHED

NOTES

You can include code that is contained in an attached process in
any number of separate executable files. The code in each file,
however, must be position-independent. You can only have one

attached process, delimited by one set of $DS_BGNATTACHED and
$DS_ENDATTACHED macros, per file.

If you want to place the code in a separate image, request a buffer

using the $DS_GETBUF service, load the image into the buffer, and
use the address of the buffer as the ““start_addr”” argument for the
$DS_STARTATTACHED macro.

You can enter the code using a CALL instruction.

It is recommended that you place data structures for the code in a
separate psect. If you must include the data structures in the same
psect as the code, place them (data structures) after the code and end
the executable section with a $DS_EXIT macro as shown:
.psect data
<data

$DS_BGNATTACHED RTN2Z

structures>
<executable

.psect

code>

code

$DS*BGNATTACHED RTN1

$DS_EXIT ATTACHED

<data

$DS_ENDATTACHED

structures>

5-37

$DS_BGNCLEAN

$DS_BGNCLEAN—S$DS_ENDCLEAN
The $DS_BGNCLEAN and $DS_ENDCLEAN macros are used to delimit
the program’s clean-up code. These macros create the connections which
make it possible for the VDS to locate and execute the clean-up code.

MACRO-32

$DS_BGNCLEAN

[<regmask>], [<psect>]
(clean-up code)

$DS_ENDCLEAN
BLISS-32

$DS_BGNCLEAN;

(clean-up code);

$DS_ENDCLEAN;
ARGUMENTS

regmask

List of general purpose register names to be placed in the entry mask.

psect
Any argument string that is valid for a MACRO-32 .PSECT statement. If
none is specified, the argument string “CLEANUP,LONG’’ will be used.

NOTES

.
In MACRO-32, the $DS_BGNCLEAN macro will generate the following
code:
. SAVE
.PSECT

psect

CLEAN_UP:
.WORD

"M<regmask>

In MACRO-32, the $DS_ENDCLEAN macro will generate the following
code:

CLEAN_UP_X:

$DS_BREAK
RET

.RESTORE

In BLISS-32, the $DS_BGNCLEAN macro will generate the following
code:

%SBTTL
PSECT

GLOBAL

‘CLEAN UP’
CODE

CLEANUP(WRITE);

ROUTINE

CLEAN_UP:NOVALUE

BEGIN

In BLISS-32, the $DS_ENDCLEAN macro will generate the following

code:
END

5-38

$DS_BGNCLEAN

MACRO-32
EXAMPLE
$DS_BGNCLEAN <R2,R3,R4,R5>,

<CLEANSECT, LONG>

$DS_ENDCLEAN

BLISS-32
EXAMPLE
$DS_BGNCLEAN;

$DS_ENDCLEAN;

5-39

$DS_BGNDATA

$DS_BGNDATA—S$SDS_ENDDATA
The $DS_BGNDATA and $DS_ENDDATA macros are used to optionally

provide lists of input arguments to a test.

Each time the VDS executes a

test for which argument lists have been specified, it 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 $DS_BGNDATA and $DS_ENDDATA macros must be located
immediately before the $DS_BGNTEST macro of the test to which the
parameter lists belong.

MACRO-32

$DS_BGNDATA

J[align], argument-list, [argument-list]

$DS_ENDDATA
BLISS-32

ARGUMENTS

This macro is not supported for BLISS-32.

align
Desired alignment for the psect containing the argument lists. Possible

values are BYTE, WORD, LONG, QUAD, PAGE, or an integer from 0 to
9. If an integer is specified, the psect will start at the next address that is a
multiple of two raised to the power of the integer.

argument-list
A list of arguments to be used by the test. Each argument must occupy a

longword. Each parameter list must be formatted as shown in Figure 5-3.

$DS_BGNDATA

Figure 5-3

Argument List Format for $DS_BGNDATA

0
N

1
ARGUMENT
ARGUMENT
2
| ]

ARGUMENT
N
ZK-4791-85

$DS_ENDDATA

The $DS_ENDDATA will provide termination for the set of lists by
generating a longword of 0.
e

NOTES

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

EXAMPLES
$DS_BGNDATA

. LONG

DATA_1,

DATA_2,

DATA_3,

DATA_4

.LONG

DATA_5,

DATA_6,

DATA_7,

DATA_8

.LONG

DATA_1,

DATA_3,

DATA_7,

DATA_S

$DS_ENDDATA

$SDS_BGNINIT

$DS_BGNINIT—$DS_ENDINIT
The $DS_BGNINIT and $DS_ENDINIT macros are used to delimit the

diagnostic program’s initialization code. These macros create the
connections that make it possible for the VDS to locate and execute

the initialization code.

MACRO-32

$DS_BGNINIT

[<regmask_>], [<psect_>]
(initialization code)

$DS_ENDINIT
BLISS-32

ARGUMENTS

$DS_BGNINIT;
$DS_ENDINIT;

(initialization code);

regmask
List of general purpose register names to be placed in the entry mask.

psect
Any argument string that is valid for a MACRO-32 .PSECT statement. If
none is specified, the argument string “INITIALIZE, LONG" will be used.

NOTES

In MACRO-32, the $DS_BGNINIT macro will generate the following

code:
. SAVE
.PSECT

psect

-WORD

~"M<regmask>

INITIALIZE:

In MACRO-32, the $DS_ENDINIT macro will generate the following

code:
INITIALI ZE_X:

$DS_BREAK
RET

+»RESTORE

In BLISS-32, the $DS_BGNINIT macro will generate the following code:
%SBTTL
PSECT
GLOBAL

'INITIALIZE’
CODE =

INITIALIZE(WRITE);

ROUTINE

INITIALIZE

NOVALUE

BEGIN

In BLISS-32, the $DS_ENDINIT macro will generate the following code:
$DS_BRERDK;
END

$DS_BGNINIT

MACRO-32
EXAMPLE
$DS_BGNINIT R2,R3,R4,R5,

INITSECT,LONG

SDS_ENDINIT

——
R0

BLISS-32
EXAMPLE
$DS_BGNINIT;

$SDS_ENDINIT;

$DS_BGNMESSAGE

$DS_BGNMESSAGE—$DS_ENDMESSAGE
The $DS_BGNMESSAGE and $DS_ENDMESSAGE macros should be used
to delimit each error reporting routine used in conjunction with the error

reporting macros ($DS_ERRxxxXx).

MACRO-32

$DS_BGNMESSAGE

[<regmask>]
(error reporting routine)

$DS_ENDMESSAGE
BLISS-32

$DS_BGNMESSAGE

(ROUTINE_NAME = routine_name);
(error reporting routine);

$DS_ENDMESSAGE;
ARGUMENTS

regmask
List of general purpose register names to be placed in the entry mask.

routine_name
Symbolic name to be associated with the error reporting routine.

NOTES

The error reporting routine must use $DS_PRINTB and $DS_PRINTX
macros to print messages. The most important information should

be printed first, using $DS_PRINTB macros. The most detailed
information, such as dumps of device registers, should be printed
last, using $DS_PRINTX macros. Refer to Section 3.9.1, Error Message
Formats, for example error messages.

Further details on error reporting routines are listed in the description
of the error macros ($DS_ERRxxxx).

In MACRO-32, the $DS_BGNMESSAGE macro generates an entry

mask. The $DS_ENDMESSAGE macro generates a RET instruction.

In BLISS-32, THE $DS_BGNMESSAGE macro generates the following

code:

GLOBAL

ROUTINE

%NAME(routine_name) (NUM,

Pl,

P2,

P3,

P4,

UNIT,

P5,

P6)

MSGADR,

PRLINK,

NOVALUE

BEGIN

The $DS_ENDMESSAGE macro generates the following code:
RETURN

END

5-44

$DS_BGNMESSAGE

EXAMPLE

Refer to the description of the $DS_ERRxxxx macros (later in this chapter)
for examples of $DS_BGNMESSAGE and $DS_ENDMESSAGE.

5-45

$DS_BGNMOD

$DS_BGNMOD—$DS_ENDMOD
The $DS_BGNMOD and $DS_ENDMOD macros must be included at the

beginning and end, respectively, of every source module making up the

diagnostic program.

MACRO-32

$DS_BGNMOD

[env], [tn], [st]
(source module)

$DS_ENDMOD
BLISS-32

$DS_BGNMOD
$DS_ENDMOD;

ARGUMENTS

(JENV =evn], [TEST =tn]);
(source module);

env
Used to indicate if the program is a level 2 program. If so, this value must
be 2. Otherwise, the value should be 0 (the default).

Note: In the past, this parameter was assigned one of four predefined
values: CEP_FUNCTIONAL, CEP_REPAIR, SEP_FUNCTIONAL, or

SEP_REPAIR. These symbols are meaningless and should not be used.
(SEP_FUNCTIONAL) is equivalent to 2.

tn
Value representing the number to be assigned to the first test in this

module, if this module contains tests. Default value is 1.

st
Value representing the number to be assigned to the first subtest in this
module, if this module contains subtests. Default value is 1.

“

NOTES

In BLISS-32, the $DS_BGNMOD and $DS_ENDMOD macros must be

contained within the bounds of the MODULE and ELUDOM keywords,

as follows.
MODULE

modnam

BEGIN

$DS_BGNMOD

$DS_ENDMOD;
END
ELUDOM

() ;

$DS_BGNREG

$DS_BGNREG—$DS_ENDREG
The $DS_BGNREG and $DS_ENDREG macros may be used to delimit a

storage area in which device register contents are placed.

MACRO-32

$DS_BGNREG

(register storage area)

$DS_ENDREG
BLISS-32

NOTES

$DS_BGNREG;
$DS_ENDREG;

(register storage area),

In MACRO-32, the $DS_BGNREG macro generates the label
“DEVREG:..”

In BLISS-32, the $DS_BGNREG macro generates the statement
OWN DEV_REG : VECTOR [0};

The $DS_ENDREG does not generate any source code.

$DS_BGNSERV

$DS_BGNSERV—$DS_ENDSERV
The $DS_BGNSERV and $DS_ENDSERV macros should be used to

delimit interrupt service routines.

MACRO-32

$DS_BGNSERV

adar
(interrupt service routine)

$DS_ENDSERV
BLISS-32

These macros are not supported for BLISS-32.

ARGUMENTS

addr

Symbolic name to be associated with the interrupt service routine.

The $DS_BGNSERV macro will generate the following code:
.ALIGN

LONG,

PUSHR

#"M<RO,R1>

;

ALIGN

SAVE

LONGWORD

BOUNDARY

ADDR:

AND

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

#"M<RO,R1>

;

RESTORE

;

RETURN

FROM

AND

SERVICE

$DS_BGNSTAT

$DS_BGNSTAT—S$SDS_ENDSTAT
The $DS_BGNSTAT and $DS_ENDSTAT macros should be used to 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

$SDS_BGNSTAT

(statistics tables)

SDS_ENDSTAT

BLISS-32

$SDS_BGNSTAT,;

(statistics tables);

S$DS_ENDSTAT;

NOTES

In MACRO-32, the $DS_BGNSTAT macro simply generates the label

"STATISTIC:". The $DS_ENDSTAT does not generate any code.
2

In BLISS-32, the $DS_BGNSTAT macro generates the following
statement:

GLOBAL STATISTIC : VECTOR [0];

The $DS_ENDSTAT macro does not generate any code.

$DS_BGNSUB

$DS_BGNSUB—$DS_ENDSUB
The $DS_BGNSUB and $DS_ENDSUB macros are used to delimit each
subtest existing in any particular test.

Refer to Section 3.8, Tests,

Subtests, and Sections, for a discussion of subtests.

MACRO-32

$DS_BGNSUB
(subtest)

$DS_ENDSUB
L

BLISS-32

$DS_BGNSUB;

(subtest);

$DS_ENDSUB;
NOTES

The macro automatically numbers each subtest. Subtests are numbered
from 1 to N for each test, where N is the total number of subtests
within the test.

the $DS_BGNSUB macro was issued. If the numbers do not match, the
VDS will stop execution of the diagnostic program.

5-50

$DS_BGNSUMMARY

$DS_BGNSUMMARY—$DS_ENDSUMMARY
The $DS_BGNSUMMARY and $DS_ENDSUMMARY macros are used

to delimit the summary routine. Summary routines are discussed in
Section 3.7.

MACRO-32

$DS_BGNSUMMARY

[<regmask>], [<psect>]
(summary routine)

$DS_ENDSUMMARY
BLISS-32

$DS_BGNSUMMARY;
$DS_ENDSUMMARY;

ARGUMENTS

regmask

(summary routine);

List of general purpose register names to be placed in the entry mask.

psect
Any argument string that is valid for a MACRO-32 .PSECT statement. If
none is specified, the argument string 'SUMMARY,LONG’ will be used.

NOTES

In MACRO-32, the $DS_BGNSUMMARY macro will generate the
following code:
.SAVE
. PSECT

psect

SUMMARY
:

WORD

"M<regmask>

s ENTRY

MASK

In MACRO-32, the $DS_ENDSUMMARY macro will generate the
following code:
SUMMARY_X:

$DS_BREAK
RET
. RESTORE

In BLISS-32, the $DS_BGNSUMMARY macro will generate the
following code:
PSECT

GLOBAL

CODE

SUMMARY

ROUTINE

(WRITE);

SUMMARY

NOVALUE

BEGIN

In BLISS-32, the $DS_ENDSUMMARY macro will generate the
following code:
$DS_BREAK;
END

5-51

$DS_BGNTEST

$DS_BGNTEST—S$DS_ENDTEST
The $DS_BGNTEST and $DS_ENDTEST macros are used to delimit each
test existing in a diagnostic program. Tests are discussed in Section 3.8,
Tests, Subtests, and Sections.

MACRO-32

$DS_BGNTEST

[<section-name,section-name,...>],
[<regmask>], [align]
(test code)

$DS_ENDTEST
BLISS-32

$DS_BGNTEST

([SECTION = <section-name,
section-name,... >],
[TEXT = test-name’]),

(test code),

$DS_ENDTEST;
ARGUMENTS

section-name
Name of a program section to which this test belongs. Refer to Section 3.8,
Tests, Subtests, and Sections.

regmask
List of general purpose register names to be placed in the entry mask.

align
Desired alignment for the psect containing the argument lists. Possible

values are BYTE, WORD, LONG, QUAD, PAGE, or an integer from 0 to
9. If an integer is specified, the psect will start at the next address that is a
multiple of two raised to the power of the integer.

text
Text string identifying the test. This test will be displayed on the user
terminal each time the test is executed, provided that the user has set the
VDS control flag TRACE. If the (') character is to be included within the
text string, it must be specified twice, as in:
TEXT ='Fred’’s test’

(In MACRO-32, the identifying message is defined by using the

$DS_SUBTTL macro.)

$DS_BGNTEST

NOTES

The $DS_BGNTEST macro will assign a test number to the test. The

test number is incremented each time the $DS_BGNTEST macro is
called within a source module. (The test number can be initialized
when the $DS_BGNMOD macro is called at the beginning of the
source module.)

In MACRO-32, the $DS_BGNTEST macro causes the following label to
be generated:
.WORD

TEST_xxx%x::

"M<

where ““xxx’’ is the current test number.

In MACRO-32, the $DS_ENDTEST macro generates the following code:
MOVL

#1,RO

;NORMAL EXIT

TEST_nnn_X::

$DS_BREAK
RET

In BLISS-32, the $DS_BGNTEST macro generates the following entry
point:
.ENTRY

"M< >
TEST_Xxx,

where ““xxx’’ is the current test number.
In BLISS-32, the $DS_ENDTEST macro generates the following code:
$DS_BREAK;

SS$_NORMAL
END;

$DS BGNTEST and $DS_ENDTEST are unavailable to attached
processors in multiprocessing environments.

5-53

$BINTIM

$BINTIM
The Convert ASCII String to Binary Time system service converts an ASCII

string to an absolute or offset time value in the system 64-bit time format

suitable for input to the $SETIMR service.

MACRO-32

SBINTIM_x

BLISS-32

$BINTIM

ARGUMENTS

timbuf, timadr

(TIMBUF =timbuf, TIMADR = timadr);

timbuf
Address of a character string descriptor (see Section 5.3) pointing to the
buffer containing the absolute or offset time to be converted. See notes for
input string format.
The maximum offset time that may be specified is 10,000 days.

timadr
Address of a quadword to receive the converted time in 64-bit format.

RETURN

STATUS

SS$_NORMAL

Service successfully

SS$_IVTIME

Syntax of the input string is invalid, or the specified

completed.

comp

time is out of range.

NOTES

For absolute time, the input string must be formatted as

dd-mmm-yyyy hh:mm:ss.cc
For absolute time, any of the fields may be omitted, but all punctuation

must be included. The system will fill in the current values for all
unspecified fields.

Examples are:
a.

5-DEC-1983 5:16:14.98 (16 minutes, 14.98 seconds after 5 A.M. on
5-DEC-1983)

5-54

- 14:00:00.00 (2 P.M. today)

- ::05 (5 seconds past the current time)

$BINTIM

For relative time (time offset from the current time), the input string
format is

dddd hh:mm:ss.cc

For relative time, any of the fields may be omitted, but all punctuation
must be included. The system will default all unspecified fields to 0.
Examples are:

a. 4 12:46:14.56 (4 days, 12 hours, 46 minutes, 14.56 seconds from
now)

0 5:12 (5 hours and 12 minutes from now)

0::10 (10 seconds from now)

MACRO-32
EXAMPLE
LASCID /0O 00:01:00.00/ ;DESCRIPTOR FOR 1 MINUTE.
: QUADWORD TO HOLD BINARY TIME.
.BLKQ 1

ONE_MIN:
BIN_TIM

S ONE_MIN,
$BINTIM

BIN_TIM

;

BLISS-32
EXAMPLE
BIND

ONE_MIN

LOCAL

UPLIT (%ASCID ‘0 00:01:00.007);

BIN_TIM : VECTOR [2];

! DESCRIPTOR FOR 1 MINUTE.

! QUADWORD TO HOLD BINARY TIME.

$BINTIM (TIMBUF=.ONE_MIN, TIMADR=BIN_TIM);

$DS_BITDEF

$DS_BITDEF
The $DS_BITDEF macro defines (for MACRO-32 programs) a bit mask for

each bit from O through 31. For BLISS-32 programs, these symbols may
be referenced without first issuing the $DS_BITDEF macro.

Symbols defined are:
BITO

00000001

(HEX)

BIT1

00000002

(HEX)

BIT2

00000004

(HEX)

BIT31

MACRO-32

ARGUMENTS

80000000

$DS_BITDEF

(HEX)

[gbl]

Can be LOCAL or GLOBAL

MACRO-32

EXAMPLE
$DS_BITDEF

GLOBAL

$DS_BNCOMPLETE

$DS_BNCOMPLETE
The $DS_BCOMPLETE and $DS_BNCOMPLETE program control macros
can be used to test the return status of a system service (or any routine
which returns a status code in RO) and branch if the service's operation
was ‘‘complete’’ or ‘‘incomplete.”

adr

MACRO-32

$DS_BNCOMPLETE

BLISS-32

Not supported for BLISS-32, since testing RO is implicit in the language.

ARGUMENTS

adr

See the example below.

Address to branch to if tested condition is satisfied.

NOTES

.
:
o
For all error status codes, bit 0 is clear. Therefore, this macro simply

generates the following code:
$DS_BNCOMPLETE -

BLBC RO,adr

If an error status code is detected, the contents of R0 should be
compared with all error codes that could possibly be returned from
the service (or other) routine to determine the exact nature of the error.

MACRO-32
EXAMPLE
$DS_GETBUF
$DS_BNCOMPLETE

$2,

RETADDR, PHYSADDR

BAD_BUF

BLISS-32
EXAMPLE
IF $DS_GETBUF (PAGCNT=2)

THEN

...

5-57

$DS_BNERROR

$DS_BNERROR
The $DS_BERROR and $DS_BNERROR program control macros

can be
used to test the return status of a system service (or any routine which

returns a status code in R0) and branch if the service’s operation
was in
error or was error-free.

MACRO-32

$DS_BNERROR

BLISS-32

Not supported for BLISS-32, since testing RO is implicit in the language.

adr

See the example below.

ARGUMENTS

adr
Address to branch to if tested condition is satisfied.

NOTES

For all error status codes, bit 0 is clear. Therefore, this macro
simply

generates the following code:
$DS_BNERROR -

BLBS

RO, 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 (or other) routine to determine the exact nature of the error.

MACRO-32
EXAMPLE
$DS_GPHARD

LOG_UNIT,

$DS_BNERROR

10%

ADDR1

BLISS-32

EXAMPLE
IF

NOT

5-58

$DS_GPHARD

(UNIT=.LOG_UNIT,

RETADR=ADDR1)

THEN

...

$DS_BNOPER

$DS_BNOPER
The $DS_BNOPER macro can be used to determine the presence of

an operator (user) during program execution. (The presence of a user
is indicated by the condition of the VDS control flag OPERATOR.) This
macro can be used to control whether certain portions of the program are
executed only if a user is present. $DS_BNOPER will cause a branch if
the operator flag is clear.

MACRO-32

$DS_BNOPER

adr

BLISS-32

Not implemented for BLISS-32. Direct reference of the corresponding VDS

ARGUMENTS

adr

control flag, as illustrated in the example below, is recommended.

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

MACRO-32
EXAMPLE
$DS_BNOPER

100%

BLISS-32
EXAMPLE
IF

.DSASV_OPER THEN

BEGIN

...

END;

5-59

$DS_BNPASSO

$DS_BNPASSO
The $DS_BNPASSO0 program control macro can be used within the
initialization code to determine if the current pass through the initializatio
n

code is the first one. It is often necessary to perform certain operations
the first time the initialization code is executed that should not be repeated

on subsequent passes through the initialization code, such as initialization
of run-time variables. (It is helpful to think of ‘“‘pass 0’’ as the execution

that takes place before the first pass through the tests occurs.)

$DS_BNPASSO will cause a branch if the current pass through the

initialization code is not the first one. This macro may only be used in
the initialization code.

MACRO-32

‘$DS_BNPASSO0

BLISS-32

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

ARGUMENTS

adr

Address to branch to if the tested condition is satisfied.

MACRO-32
EXAMPLE
$DS_BNPASSO

508

BLISS-32

EXAMPLE
IF

.DSA3V_PASSO

5-60

THEN

BEGIN

...

END;

$DS_BNQUICK

$DS_BNQUICK
The $DS_BNQUICK program control macro can be used to determine
if the VDS control flag QUICK has been set by the program user. The
$DS_BNQUICK will cause a branch if the QUICK flag is clear. If the flag
has been set, the diagnostic program should execute only the portions of

code deemed appropriate to the ‘“‘quick’’ mode of operation.

MACRO-32

$DS_BNQUICK

BLISS-32

Not implemented for BLISS-32. Direct reference of the corresponding VDS

ARGUMENTS

adr

control flag, as illustrated in the example below, is recommended.

adr

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

MACRO-32
EXAMPLE
$DS_BNQUICK

100%

BLISS-32
EXAMPLE
IF

.DSA$V_QUICK THEN

BEGIN

...

END;

5-61

$DS_BOOTATTACHED

$DS_BOOTATTACHED
In a multiprocessing environment, use the Boot Attached CPU system

service to bootstrap an attached processor on a multiprocessor system. It

will perform the following functions for the target processor:
1

Halt the processor, if it is not currently halted.

Perform all initialization necessary to enable the processor to execute
code, including initializing stacks, memory management registers, the

SCB, and the interval clock.
3

Cause the processor to enter the idle state (see Figure 4-8).

After you call the $DS_BOOTATTACHED, use the $DS_STARTATTACHED
service to cause the attached processor to leave the idle state and begin

executing a section of code while in the running state.

MACRO-32

$DS_BOOTATTACHED_x

BLISS-32

$DS_BOOTATTACHED

unit, scb_addr

(UNIT =unit

SCB_ADDR = scb_addr);
ARGUMENTS

unit
Logical unit number of the processor to be bootstrapped.

sch_addr
Address of the longword to receive the SCB address of the target
processor.

RETURN

STATUS

DS$_NORMAL

DS$_ILLUNIT

The specitied logical unit number is too large.

DS$_INVCPU

Cannot boot specified processor.

DS$_MEM_ALLOC_ERR

Could not allocate memory for attached processor’s

full

ervice successfully

(oeessTly

leted |

completed.

comp

SCB and stacks.

DS$_INITFAIL

Attached processor failed initialization.

$DS_BOOTATTACHED

00000

MACRO-32
EXAMPLE

$DS_BOOTATTACHED_S

LOG_UNIT,

PROC2Z_SCB

BLISS-32
EXAMPLE
$DS_BOOTATTACHED (UNIT =

.LOG_UNIT,

SCB_ADDR = PROCZ_SCB);

5-63

$DS_BOPER

$DS_BOPER
The $DS_BOPER macro can be used to determine the presence of an
operator (user) during program execution. (The presence of a user is
indicated by the condition of the VDS control flag OPERATOR.) This
macro can be used to control whether certain portions of the program are
executed only if a user is present. $DS_BOPER will cause a branch if the
OPERATOR flag is set.

MACRO-32

$DS_BOPER

BLISS-32

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

ARGUMENTS

adr

adr
Address to which to branch if the tested condition is satisfied.

MACRO-32
EXAMPLE
$DS_BOPER

100%

BLISS-32
EXAMPLE
IF

.DSA$V_OPER

5-64

THEN

BEGIN

...

END;

$DS_BPASSO

$DS_BPASSO
The $DS_BPASSO0 program control macro can be used within the
initialization code to determine if the current pass through the initialization
code is the first one. It is often necessary to perform certain operations

the first time the initialization code is executed that should not be repeated
on subsequent passes through the initialization code, such as initialization
of run-time variables. (it is helpful to think of ‘‘pass 0’' as the execution
that takes place before the first pass through the tests occurs.)

$DS_BPASSO will cause a branch if the current pass through the
initialization code is the first one. This macro may only be used in the
initialization code.

adr

MACRO-32

$DS_BPASSO0

BLISS-32

Not implemented for BLISS-32. Direct reference of the corresponding VDS

ARGUMENTS

adr

control flag, as illustrated in the example below, is recommended.

Address to branch to if the tested condition is satisfied.

MACRO-32

EXAMPLE
$DS_BPASSO

PASS1

BLISS-32
EXAMPLE
.DSASV_PASS0 THEN BEGIN

...

END;

5-6

$DS_BQUICK

$DS_BQUICK
The $DS_BQUICK program control macro can be used to determine if
the VDS control flag QUICK has been set by the program user. The

$DS_BQUICK will cause a branch if the QUICK flag is set. If the flag has

been set, the diagnostic program should execute only the portions of code

deemed appropriate to the ‘‘quick’’ mode of operation.

MACRO-32

$DS_BQUICK

BLISS-32

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

ARGUMENTS

adr

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

MACRO-32

EXAMPLE
$DS_BQUICK TAG1

BLISS-32
EXAMPLE
IF

.DSASV_QUICK THEN

aadr

BEGIN

...

END;

$DS_BREAK

$DS_BREAK
The Break system service causes a temporary return to the VDS to take

place. The main purpose of this return is to see if any asynchronous
events (including receipt of a control-C character from the user terminal)
have occurred and are waiting to be processed.

All diagnostic programs must return to the VDS at least 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 the VDS, so the $DS_BREAK service only
needs to be called if none of those macros has been issued in a particular
3-second interval. Be particularly careful that all potential program loops
(see Section 3.10) adhere to this constraint.
In a multiprocessor environment, code executing in attached processors
must also call $DS_BREAK periodically.

MACRO-32

$DS_BREAK

BLISS-32

$DS_BREAK;

(No suffix.)

“

RETURN

None.

STATUS
—

MACRO-32

EXAMPLE
$DS_BREAK

BLISS-32
EXAMPLE
$DS_BREAK;

5-67

$CANCEL

$CANCEL
The Cancel /0 on Channel system service can be used to cancel I/0
requests that were created with the $QIO and $QIOW system services.
The caller specifies the number of the channel for which I/O requests are

to be canceled, and the service will cancel all current and pending I/O
operations directed to the channel.

Level 3 programs may not use this service.

MACRO-32

SCANCEL_x

BLISS-32

$CANCEL

ARGUMENTS

RETURN

STATUS

chan

(CHAN =chan),

chan

Number of the I/O channel on which I/O is to be canceled.

SS$_NORMAL
-

SS$_EXQUOTA

full y

ervice successfully

leted

completed.

The process has exceeded its direct I/O quota.
User mode only.

SS$_INSFMEM

Insufficient memory space is available to perform the
Cancel I/0 service.

SS$_IVCHAN

An invalid channel number was specified; that is, a
channel number of 0 or a number larger than the

number of channels available.

SS$_NOPRIV

The specitied channel was not assigned, or was
assigned from a more privileged access mode. User
mode only.

NOTES

See the VAX/VMS System Services Reference Manual for discussions of
privilege restrictions, resource requirements, and other notes relating to

the SCANCEL service.

$SCANCEL

MACRO-32
EXAMPLE
SCANCEL_S

CHANNUM

BLISS-32
EXAMPLE
SCANCEL

(CHAN=.CHANNUM)
;

5-69

$SCANTIM

$SCANTIM
The Cancel Timer Request system service can be used to cancel timer
requests previously made with the $SETIMR macro. See Section 4.4.4,
Timing.

MACRO-32

SCANTIM_x

BLISS-32

SCANTIM

ARGUMENTS

reqidt

[reqidt], [acmode]

(JREQIDT
= reqidt], [ACMODE = acmode]);

The request identification number of the timer request to be canceled. A
request id numberis associated with each timer request when the $SETIMR
macro is used. The $SCANTIM service will only cancel the requests having

the specified id number. The default valueis 0, which means that all timer
requests should be canceled, regardless of their id numbers.

acmode (user mode only)
Access mode of the requests to be canceled. In user mode, the access
modeis maximized with the access mode of the caller. Only those timer
requests issued from an access mode equal to or less privileged than the
resultant access mode are canceled.

RETURN

ST ATUS

SS$_NORMAL

Service successfully completed.

L~~~

MACRO-32
EXAMPLE
SCANTIM_S

;Cancel

timer

!Cancel

all

request(s)

with

BLISS-32
EXAMPLE
SCANTIM

5-70

();

timer

requests.

ID of

$DS_CANWAIT

$DS_CANWAIT
The Cancel Wait system service is used to cancel a program wait state
that was created by using the $DS_WAITMS or $DS_WAITUS macro. See
Section 4.4.4, Timing.

MACRO-32

x
$DS_CANWAIT

BLISS-32

$DS_CANWAIT;

RETURN

STATUS

A A S

SS$_NORMAL

Service successfully completed.

00—

NOTES

The $DS_CANWAIT macro is only useful if it is included in an AST
routine or interrupt service routine that was entered while a $DS_WAITMS
or $DS_WAITUS service was being executed. See Section 4.4.4.

MACRO-32
EXAMPLE
$DS_CANWAIT_S

BLISS-32
EXAMPLE

5-7

$DS_CANWAIT;

$DS_$CASE

$DS_$CASE
The $DS_$CASE p-table descriptor macro is used to test the current
contents of the ‘‘value register’’ (see Section 3.2.3.3) and then load a new
value into the register, depending on the old contents. The $DS_$CASE
macro is used to specify pairs of values.

The current value register

contents are compared with the first value of each pair until a match is

found; the second value of the pair is then loaded into the value register.
There may be any number of pairs in the case list. If no pair matches the
value register, then the value register is not altered.

MACRO-32

$DS_SCASE

< <case_pair>, [<case_pair>,...]>

BLISS-32

$DS_SCASE

((case_pair), [(case_pair), ...]);

ARGUMENTS

case_pair
A pair of values, separated by a comma. Each value will be stored in a
longword.

NOTES

Code generated by macro (shown in Macro-32; Bliss-32 is equivalent):
.BYTE

~X8C

;

Beginning

.BYTE

;

Number

case

. LONG

matchl,

;

First

case

pair

;

Other

case

pairs

Last

(nth)

case

. LONG

match-n,

valuel

value-n;

MACRO-32
EXAMPLE
$DS_S$CASE <

<1,2>,

<2,3>,

<3,4>>

$SDS_SCASE <<1,<~"XFFFFF>>,<2,<~XFFFEFFFF>>>

5-72

CASE
pairs

pair

$DS_$CASE

BLISS-32
EXAMPLE
$DS_$CASE (
(1,2),

(2,3),
(3,4));
$DS_SCASE ((1,%X'FFFFF'),(2,%X'FFFEFFFF’ Yy

5-73

$DS_CFDEF

$DS_CFDEF
The $DS_CFDEF macro defines (for MACRO-32 programs) symbolic
names for the fields of a call frame. For BLISS-32 programs, these
symbols may be referenced without first issuing the $DS_CFDEF macro.

Symbols defined are:
CFS$L_ONCOND - Address

CFSW_PSW

NOTES

Processor

CF$W_MASK

CF$L_AP

Baved AP

CF$L_FP

Saved FP

CF$L_PC

Saved

CF$IL_REG

- Start of

condition

status
mask

saved RO through R11

These symbols are used as offsets from the current FP, as in

CF$W_PSW(FP).

MACRO-32

ARGUMENTS

$DS_CFDEF

[gbl]

gbl
Can be LOCAL or GLOBAL

MACRO-32
EXAMPLE
$DS_CFDEF GLOBAL

5-74

handler

word

$DS_CHANNEL

$DS_CHANNEL
The VDS Channel Adapter system service controls functions that are

initiated by referencing internal registers in the bus adapters. This service
takes into account all processor-specific differences in the adapters and
thus insulates the diagnostic program from those differences.
The Channel Adapter service enables the program to:

Initialize a MASSBUS adapter, a UNIBUS adapter, or a UNIBUS-like
VAXBI adapter, such as the KDB50.
Initialize a UNIBUS

Enable and disable interrupts from an adapter
Abort data transfers on a MASSBUS adapter
Purge a UNIBUS data path

Set or clear UNIBUS defeat parity
Request or clear adapter status

Run self-test on a VAXBI adapter

Stop a VAXBI adapter from issuing any more VAXBI transactions

For descriptions of the design and operation of the various bus adapters
for VAX processors, refer to the VAX Hardware Handbook.
The Channel Adapter system service may only be used by level 3
diagnostic programs.
00—

MACRO-32

$DS_CHANNEL_x

unit, func, [vecadr], [stsad], [time],
[bistsadr]

BLISS-32

$DS_CHANNEL

(UNIT =unit, FUNC = func,
[VECADR = vecadr],

[STSADR = stsadr], [TIME =time],
[BISTSADR = bistsadr]),

5-75

$DS_CHANNEL

ARGUMENTS

unit

Logical unit number of the device unit to be tested. The function specified
by ““func” is performed on the adapter to which this device unit is
attached.

func
Function code indicating the function to be performed by the

$DS_CHANNEL service. Must be a literal value. In MACRO-32, function

codes are defined by the $DS_CHCDEF macro. Note 1 describes function
codes.

vecadr
Address of interrupt service routine to receive control when an interrupt
occurs. The interrupt may come from the device specified by ‘“‘unit’’ or
from the adapter to which the device is attached. This parameter is only
used with the CHCS$_ENINT function code, in which case it is required.

stsadr
Address of a quadword to receive adapter status. Used only with the
CHC$_ENINT and CHC$_STATUS function codes, in which cases it is
required. Note
2 discusses adapter status.

time
The number of ten-millisecond time units to wait for the VAXBI node selftest to complete. Used only with the CHS$_SELF_TEST and CHC$_INITA
functions codes and only when referencing VAXBI nodes.

bistsadr
Address of a quadword to receive the contents of the BIIC CSR and the

BIIC BER registers. Used only with the CHC$_STATUS and CHC$_ENINT
function codes and only when referencing VAXBI adapters.
e
.

RETURN

STATUS

DS$_NORMAL

DS$_ERROR

The specified logical unit number is too large.

DS$_IHWE

Initial hardware error. An error condition detected

full

ervice successfully

(oesseTTy

leted

completed.

compreted.

in the adapter is preventing the function from being
performed. To determine the exact hardware error,

issue a CHC$_STATUS function.

DS$_IVWECT

The p-table for the device unit indicated with the
“unit” parameter contains an invalid vector address.

DS$_LOGIC

An attempt to set or clear a bit within an adapter
register has failed. Indicates a hardware failure.

DS$_NOSUPPORT

The specified function is not supported on the
processor type being used. This is not an error

condition. See Note 4.

5-76

$DS_CHANNEL

DS$_PROGERR

An invalid function code was specified.
A required argument was not included with the macro
call.

DS$_BIIC

BIIC self-test failed.

DS$_NODE

VAXBI node self-test failed. (BIIC self-test
succeeded.)

NOTES

1. Function Codes

Following is a list of valid function codes with their functions and return
status codes:

CHC$_INITA — Initialize the MASSBUS, UNIBUS, or VAXBI adapter
to which the device unit specified by ““unit” is attached. For VAXBI
nodes, self-test is invoked and ‘‘time’” may be specified. See Note 6.

Return status codes: DS$_NORMAL, DS$_ERROR, DS$_LOGIC,

DS$NOSUPPORT, DS$_BIIC, DS$_NODE

CHC$_INITB — Initialize the UNIBUS to which the device unit
specified by ““unit’”’ is attached.

Return status codes: DS$ NORMAL, DS$_ERROR, DS$_LOGIC,
DS$_NOSUPPORT

CHCS$_ENINT — Enable interrupts for the MASSBUS, UNIBUS, or
VAXBI adapter to which the device unit specified by ““unit” is attached.
Refer to Note 3 for details.

Return status codes: DS$ NORMAL, DS$_ERROR, DS$_IHWE,

DS$_IVVECT, DS$_LOGIC, DS$_PROGERR

CHCS$_DSINT — Disable interrupts for the MASSBUS, UNIBUS, or
VAXBI adapter to which the device unit specified by ““unit” is attached.

Return status codes: DS$_NORMAL, DS$_ERROR, DS$_IHWE,

DS$_IVVECT, DS$_LOGIC

CHC$_ABORT — Abort data transfers on the MASSBUS adapter to
which the device unit specified by “‘unit”’ is attached.

Return status codes: DS$NORMAL, DS$_ERROR, DS$_NOSUPPORT
e

CHC$_PURGE — Purge a buffered data path on a UNIBUS. The
buffered data path that is purged is the one specified by the last
DS$_SETMAP macro call. The UNIBUS will be the one to which the
device unit specified by “unit”’ is attached.

Return status codes: DS$ NORMAL, DS$_ERROR, DS$_NOSUPPORT
e

CHC$_CLEAR — Clear status bits. Clears error bits in the status

registers of the adapter 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, DS$_LOGIC,
DS$_NOSUPPORT

5-77

$DS_CHANNEL

CHC$_STATUS — Fetch status for the adapter to which the device
unit specified by “unit” is attached. The current status of the adapter
will be returned in the quadword specified by “‘stsadr.”” For status
definitions, see Status-1 Fields and Status-2 Fields located in Note 2.

Return status codes: DS$_NORMAL, DS$_ERROR

CHC$_SETDFT — Sets the Defeat Data Path Parity bit for the UNIBUS

adapter to which the device unit specified by ‘‘unit’”” is attached.
Return status codes: DS$_NORMAL, DS$_ERROR,

DS$NOSUPPORT

CHC$_CLRDFT — Clears the Defeat Data Path Parity bit for the

UNIBUS adapter to which the device unit specified by “‘unit’’ is

attached.

Return status codes: DS$_NORMAL, DS$_ERROR, DS$_NOSUPPORT

CHC$_SELF_TEST — Initiates self-test in the specified VAXBI node,

waiting either the amount of time specified by the time parameter or

ten seconds if time is not specified. (See Note 6 for exceptions to the

ten-second default value.)
Return status codes:

DS$_NODE

DS$_NORMAL, DS$_ERROR, DS$_BIIC,

CHC$_STOP — Stops a VAXBI node from issuing VAXBI transactions.
Return status codes: DS$_NORMAL, DS$_ERROR, DS$_LOGIC

2. Adapter Status

Adapter status is returned to the caller either when the CHC$_STATUS

function is requested or when an interrupt occurs.

In the latter case, the interrupt service routine (whose address was

specified with the ““vecadr”” parameter) can (and should) examine the

status quadword to see if errors have occurred.

The returned status quadword has the format shown in Figure 5-4.
Figure 5-4

Adapter Status Format

16 15

STATUS-1
VECTOR

STATUS-2

ZK-4794-85

Note: Both longwords are filled when an interrupt occurs. If the CHC$_STATUS
function is requested, however, only the first longword is filled in; the
second longword is cleared.

5-78

$DS_CHANNEL

Status-1 Field
Status-1 is a 4-byte bitmap, with each bit representing an error

condition. Each bit has a symbolic name in the form CHS$V_xxxxx
and a longword mask in the form CHS$M_xxxxxx. In MACRO-32,
these symbols are defined by the $DS_CHSDEF macro.
Status-1 bits are defined as follows. Unless noted, these bits also apply
to VAXBI systems.

Bit 0 — CHS$V_SYSERR — System error. Set if either of bits 9 or 10 is
set.

Bit 1 — CHS$V_CHNERR — Channel error. Set if any of bits 6, 7, 8,
25, 26, and 27 are set.

Bit 2 — CHS$V_DEVERR — Device error. Set if either of bits 4 or 5 is
set.

Bit 3 — CHS$V_PGMERR — Program error. Set if bit 11 is set.

Bits 0, 1, 2, and 3 — CHS$M_ERRANY (defined only as longword
mask) — Can be used to test if any error conditions of types SYSERR,
CHNERR, DEVERR, or PGMERR exist.

Bit 4 — CHS$V_DEVBUS — Bus error. Some type of error has
occurred on the bus.

Bit 5 — CHS$V_DEVTO — Device timeout. The referenced device did
not respond.

Bit 6 — CHS$V_CHNDPE — Data path parity error.
Bit 7 — CHS$V_CHNMPE — Map parity error.

A MASSBUS page

frame map parity error or a UNIBUS map register parity failure was

detected.

Bit 8 — CHS$V_CHPFOT — Power failure/Overtemp. A power failure
or overtemperature condition was detected.

Bit 9 — CHS$V_SYSMEM — System memory error. Set if any of a
number of error conditions relating to data transfers was detected.

Bit 10 — CHS$V_SYSSBI — SBI error. For processors having an SBI,
this bit is set if an SBI error condition is detected.

Bit 11 — CHS$V_PGMHDE — Hardware-detected program error. The
mapping registers were not set up correctly by the software, or the

software attempted to initiate a MASSBUS data transfer while one was
already in progress.

Bits 12 through 15 — Unused.

Bit 16 — CHS$V_MBAEXC — MASSBUS exception.
Bit 17 — CHS$V_MBANED — Nonexistent MASSBUS device. The
referenced MASSBUS device did not respond. Equivalent to bit 5.

Bit 18 — CHS$V_MBADTB — MASSBUS DTBUSY. Set if MASSBUS
DTBUSY is set (not an error bit).

Bit 19 — CHS$V_MBADTC — MASSBUS data transfer completed. Set
if MASSBUS DT CMP is set.
5-79

$DS_CHANNEL

Bit 20 — CHS$V_MBAATN — MASSBUS attention. Set if MASSBUS
ATTN is set.

Bit 21 — CHS$V_MBACPE — MASSBUS control parity error. Set if
MASSBUS MCPE is set.

Bit 22 — CHS$V_BUSINIT — UNIBUS INIT asserted. Set if UB INIT
is set.

Bit 23 — CHS$V_BUSIC — UNIBUS initialization completed. Set if
UBIC is set.

Bit 24 — CHS$V_BUSPDN — UNIBUS power down. Set if UB PDN is
set.

Bit 25 — CHS$V_MBAWCKLWR — MASSBUS write check lower error.
Set if MASSBUS WCK LWR ERR is set.

Bit 26 — CHS$V_MBAWCKUPR — MASSBUS write check upper error.
Set if MASSBUS WCK UP ERR is set.

Bit 27 — CHS$V_BUSNXM — UNIBUS nonexistent memory or device.
The referenced address does not respond.

Bit 28 — CHS$V_UIE — UNIBUS Interlock Error; set if a DATO(B)
does not follow a DATIP transaction on the UNIBUS.

Bit 29 — CHS$V_BADBDP — Bad Buffered Data Path; set if data path 6
or 7 is selected.

Bit 30 — CHS$V_BADPAR — Set if RAM parity error occurred.
Note: Whenever the status-1 field shows an error, the program should call

the $DS_SHOWCHAN service to display the bus adapter’s internal
registers on your terminal so that you can determine the exact cause of

the error.

Status-2 Field
Status-2 is a 2-byte bitmap that is returned for interrupts only. Each

bit has a symbolic name in the form CHI$V_xxxxx and a mask in the
form CHI$M_xxxxxx. In macro-32, these symbols are defined in the

$DS_CHIDEF macro.
Status-2 bits are defined as follows:
Bit 0 — CHI$V_CHNINT — Set if the adapter issues the interrupt.

Bit 1 — CHI$V_DEVINT — Set if the device issues the interrupt.

Bits 2-6 — CHI$V_IPL — (five-bit field starting at bit position
CHI$V_IPL and having a length defined by CHI$S_IPL) Contains
the interrupt priority level (IPL) of the interrupt.
Note: CHISV_CHNINT and CHI$V_DEVINT are not mutually exclusive; that

is, both a device interrupt and an adapter interrupt can occur at the
same time.

5-80

$DS_CHANNEL

Vector Field
The 2-byte vector field contains the vector address of the UNIBUS

device that caused the interrupt.
Bits 16-31 — CHI$V_RVR — Receive vector register.

Additional Status for VAXBI Nodes
If you specify the “bistsadr’” argument with the CHC$_STATUS or

CHCS$_ENINT functions, contents of the BIIC CSR and BI BER are
returned.

BIIC CSR contents are loaded into the first longword of the quadward

specified by bistsadr. Each bit has a symbolic name in the form
BIIC$V_. Unless noted, a mask is also defined in the form BIIC$M
.
In macro-32, these symbols are defined by the $BIICDEF macro.

BIIC CSR bits are defined as follows:

Bits 0 to 3 — BIIC$V_NODE_ID — Node ID. (Note about
BIIC$S_NODE_ID)
Bits 4 to 5 — BIIC$V_ARBCNTL — Arbitration mode. (Note about

BIIC$S_ARBCNTL)

Bit 6 — BIIC$V_SEIE — Soft error interrupt enable.
Bit 7 — BIIC$V_HEIE — Hard error interrupt enable.
Bit 8 — BIIC$V_UWP — Unlock write pending.

Bit 10 — BIIC$V_SST — Start self-test.
Bit 11 — BIIC$V_STS — Self-test status.

Bit 12 — BIIC$V_BROKE — Broken.
Bit 13 — BIIC$V_INIT — Initialization.

Bit 14 — BIIC$V_SES — Soft error summary.
Bit 15 — BIIC$V_HES — Hard error summary.
Bits 16-23 — BIIC$V_BIICTYPE — BIIC interface type. (Note about
BIIC$S_TYPE.)
Bits 24-31 — BIIC$V_BIICREVN — BIIC interface revision (Note about

BIIC$S_BIICREVN.)

BIIC BER contents are loaded into the second longword of the
quadword specified by bistsadr. Each bit has a symbolic name in
the form BIIC$V_. A mask is also defined in the form BIC$M
. In
macro-32, these symbols are defined by the $BIICDEF macro.
BIIC BER bits are defined as follows:

Bit 0 — BIIC$V_NPE — Null bus parity error.
Bit 1 — BIIC$V_CRD — Corrected read data.
Bit 2 — BIIC$V_IPE — ID parity error.
Bit 3 — BIIC$V_UPEN — User parity enable.

Bit 16 — BIIC$V _ICE — Illegal confirmation error.

5-81

$DS_CHANNEL

Bit 17 — BIIC$V_NEX — Non-existent address.
Bit 18 — BIIC$V_BTP — Bus timeout.
Bit 19 — BIIC$V_STO — Stall timeout.

Bit 20 — BIIC$V_RTO — Retry timeout.
Bit 21 — BIIC$V_RDS — Read data substitute.
Bit 22 — BIIC$V_SPE — Slave parity error.
Bit 23 — BIIC$V_CPE — Command parity error.

Bit 24 — BIIC$V_IVE — Indent vector error.

Bit 25 — BIIC$V_TDF — Transmitter during fault.
Bit 26 — BIIC$V_ISE — Interlock sequence error.

Bit 27 — BIIC$V_MPE — Master parity error.
Bit 28 — BIIC$V_CTE — Control transmit error.

Bit 29 — BIIC$V_MTCE — Master loopback error.

Bit 30 — BIIC$V_NMR — NOACK to multi-responder command
received.

3. Interrupts

The CHC$_ENINT function enables interrupts for the adapter provided
the adapter is capable of generating interrupts. Device interrupts must be
explicitly enabled by the diagnostic program. The CHC$_ENINT function
loads the appropriate vector addresses and MUST be used, even if the
adapter, itself, cannot generate interrupts.

Device vector addresses are loaded with the address of an interrupt
preprocessor within the VDS. When an interrupt occurs, program control is
vectored to the interrupt preprocessor.
The interrupt preprocessor:

Raises the processor’s IPL to 17 (hex)

Check for errors incurred by the bus adapter

Constructs the status quadword

Determines the type of interrupt: adapter, device, or “’passive release.”

If the interrupt is from an adapter or a device, the appropriate bit in
the status-2 field is set and control is passed to the user’s interrupt service
routine (“‘vecadr’’) with a JMP instruction. If a passive release has occurred,
an REI instruction is executed without calling the diagnostic program’s
interrupt service routine.

The diagnostic program’s interrupt service routine should compare the
vector in the status quadword with the vector in HP$W_VECTOR of
the interrupting device’s p-table to ensure that the interrupt is from the
expected device.

5-82

$DS_CHANNEL

It is not wise to request the CHCS$_INITA or CHCS$_INITB function while
interrupts are enabled as it may result in an undefined hardware state in
some devices.
4. Processor-Specific Considerations

Some functions are not relevant for certain processors. For example, the
CHC$_INITB is not relevant on a VAX-11/730 but, in order to allow a
diagnostic program to be compatible with all processor types, the VDS

does not reject the function. It returns the DS$_NOSUPPORT status code.

In this case, you should consider a the DS$_NOSUPPORT a success status,
since the low bit of the status code is set.
5. Multiprocessor Note

$DS_CHANNEL must be called by the primary processor. It cannot be
called by code executing in an attached processor.
6. CHC$_INITA function with VAXBI adapters

The only VAXBI adapters for which the CHC$_INITA function may
be used are the BUA, the BLA, and the KDB50. For these adapters,
self-test is invoked. The ““time’” argument can be used with self-test. If
time is not specified, the default value is 100 milliseconds for the BUA,
200 milliseconds for the BLA, and 10 seconds for the KDB50.

o
—

MACRO-32
EXAMPLE

Following is an example in MACRO-32 and BLISS-32 of code that initializes
a MASSBUS, enables bus interrupts, and issues a SEARCH function on an
RP06 disk drive.

$DS_CHANNEL_S -~
DRIVE,

$DS_SETIPL_S
#0
MOVL
NEXT_ADDR,RPDA(R2)

MOVL
CYLINDER,RPDC(R2)
$DS_CHANNEL_S -

208:

DRIVE,

Initialize MASSBUS

;
:

Lower IPL
Next disk address to access.

;

Desired cylinder.

#CHCS$_INITA

#CHCS$_ENINT,

CLRQ

CH_STATUS

MOVL
BBC

#SEARCH!GO, (R2)
#CHSSV_MBAATN, -

;
:

CH_STATUS,

;

BITL

)

; Enable interrupts.
SERVICE_RTN, CH_STATUS

20$

#ERR, RPDS (R2)

; Clear status quadword.

;

SEARCH function.
Wait for SEARCH to finish.
Check

for drive errors.

5-83

$DS_CHANNEL

b
e
e

BLISS-32
EXAMPLE

$DS_CHANNEL

RPDC)

.CYLINDER;

$DS_CHANNEL
UNIT

FUNC

= CHC$_ENIT,
CH_STATUS;

O;
RPCS)

GO;

REPEAT

ELSE

...

5-84

Wait

status

quadword.

function.

for

SEARCH to

finish.

<ERR,1>

<CHS$V_MBAATN,
1>;

RPDS)

...

.CH_STATUS

.(RP_BASE

THEN

Clear

then

...

interrupts.

1
UNTIL

access.

twm

SERVICE_RTN,

Enable

STSADR

. {RP_BASE

Desired cylinder.

IPL

disk address

VECADR

CH_STATUS

.DRIVE,

Lower

. (RP_BASE

.NEXT_ADDR;

RPDA)

CHC$_INITA);

(0);

. (RP_BASE

Initialize MASSBUS

.DRIVE,

FUNC

$DS_SETIPL

(UNIT

else

...

drive

errors

occurred

$DS_CHCDEF

$DS_CHCDEF
The $DS_CHCDEF macro defines (for MACRO-32 programs) the symbolic

names of the function codes associated with the $DS_CHANNEL service.
For BLISS-32 programs, these symbols may be referenced without first
issuing the $DS_CHCDEF macro.
Symbols defined are:
CHCS$_INITA
CHC$_INITB
CHC$_ENINT

CHC$_DSINT
CHC$_ABORT
CHC$_PURGE
CHC$_CLEAR
CHC$_STATUS
CHC$_SETDFT

CHC$_CLRDFT
CHC$_SELF_TEST
CHC$_STOP

MACRO-32

$DS_CHCDEF

ARGUMENTS

gbl

MACRO-32
EXAMPLE
$DS_CHCDEF GLOBAL

[gbl]

Can be LOCAL or GLOBAL

$DS_CHMDEF

$DS_CHMDEF
The $DS_CHMDEF macro defines (for MACRO-32 programs) symbolic
names of 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
CHM$_MFWDV
CHMS$_MFWDVO

CHM$_MREVN
CHM$_MREVNO

CHM$-MREVV
CHM$-MREVVO
CHM$_NFWDN
CHM$_NREVN

MACRO-32

ARGUMENTS

MACRO-32
EXAMPLE
$DS_CHCDEF GLOBAL

$DS_CHMDEF
bl

[gbl]

an be LOCAL or GLOBAL

$DS_CHSDEF

$DS_CHSDEF
The $DS_CHSDEF macro defines (for MACRO-32 programs) symbolic
names for the STATUS-1 bits associated with the $DS_CHANNEL service.
For BLISS-32 programs, these symbols may be referenced without first
issuing the $DS_CHSDEF macro.
Symbols defined are:
CHS$M_SYSERR
CHS$M_CHNERR
CHS$M_DEVERR

CHS$M_PGMERR
CHS$M_DEVBUS
CHS$M_DEVTO
CHS$M_CHNDPE
CHS$M_CHNMPE

CHS$M_CHPFOT
CHS$M_SYSMEM
CHS$M_SYSSBI
CHS$M_PGMHDE
CHS$M_MBAEXC
CHS$M_MBANED
CHS$M_MBADTB
CHS$M_MBADTC

CHS$M_MBAATN
CHS$M_MBACPE
CHS$M_BUSINIT
CHS$M_BUSIC
CHS$M_BUSPDN
CHSS$M_MBAWCLKWR

CHSSM_MBAWCKUPR
CHS$M_BUSNXM
CHS$M_UIE
CHS$M_BADBDP
CHS$M_BADPAR

MACRO-32

$DS_CHSDEF

ARGUMENTS

gbl

MACRO-32
EXAMPLE
$DS_CHSDEF GLOBAL

[gb]]

Can be LOCAL or GLOBAL

$DS_CKLOOP

$DS_CKLOOP
The $DS_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 macro creates a loop that is not
useful. A detailed discussion of program looping, including the use of the
$DS_CKLOOP macro, is provided in Section 3.10, Looping.

MACRO-32

$DS_CKLOOP

BLISS-32

Not supported for BLISS-32. See Note 2.

ARGUMENTS

/abel

label

Address of loop’s lower bound. After the $DS_CKLOOP is executed,
program flow branches to this address. The address must be lower than

the location of the $DS_CKLOOP macro, but higher than the most recent

$DS_BGNTEST or $DS_BGNSUB macro.

NOTES

If $DS_CKLOOQOP macros are used in a test that does not contain

subtests, the $DS_CKLOOP macros may be placed anywhere within
the test. For tests that contain subtests, the $DS_CKLOOP macros must
be placed within the subtests.
2

The $DS_CKLQOP has not been implemented for BLISS-32. However,
programs written in BLISS-32 (and MACRO-32, for that matter)

can define sufficiently small program loops with judicious use of

$DS_BGNSUB and $DS_ENDSUB macros.
3

5-88

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

$DS_CKLOOP

50—

EXAMPLES

$DS_?GNSUB

LOOP_BGN::

sos_éRRHARD

UNIT=LOG_UNIT, MSGADR=HRD1, PRLINK=HRDRTN1

$Ds_éKLoop

LOOP_BGN

$Ds_éNDSUB

5-89

$DS_CLI

$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 4.2.2.2, Prompting the
User). Actual parsing of

a command string can be performed by the

$DS_PARSE system service. That service will traverse a parse tree
previously constructed with the $DS_CLI macro.

A parse tree is created by using a set of $DS_CLI macros. Each time the
macro is used, a node of the tree is created. Most nodes will possess the

following:
¢

A character, string of characters, or special ‘“‘traversal code’’ that will
indicate what must be next in the input command string to constitute a
legal command.

An “‘action code’’ that will be passed to an ‘‘action routine’’ if there is

a match between the tree node and the input command string. Action
routines are detailed in the discussion of the $DS_PARSE macro.
¢

The address of a node to jump to if the current traversal path turns out

to be the wrong one (a mismatch has been encountered).

Once the tree has been created, the $DS_PARSE system service can
be used. That service will start at the root of the tree and traverse it,
comparing an input command string with the characters or ‘‘traversal
codes’’ contained in each node.

Each 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_CL! macro. Then the next
node in 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 to go to on a mismatch.

MACRO-32

$DS_CLI

BLISS-32

Not implemented for BLISS-32.

ARGUMENTS

char

char, action, miss, [ascii]

A character to be compared to the next character in the input string, or

A “traversal code,” indicating which types of characters should be
expected next in the input string. The traversal codes are defined by

the $DS_CLIDEF macro. They are discussed in Note 1.

action
Code to be passed to the action routine. The action routine is called every
time there is a match between the current node and the input string.

$DS_CLI

miss

Address of node to jump to if there is a mismatch at the current node.

ascli

ASCII string to be used as node content if CLISK_STRING is used for
“’char’’ (see Note 1). See examples for proper format.
X

NOTES

The ““char’”’ parameter may either be a single ASCII character or it may be a
traversal code. Its purpose is to indicate to the $DS_PARSE system service
what character, characters, or types of characters should be expected next
in the input string. The traversal codes are defined by the $DS_CLIDEF
macro. The actions that the $DS_PARSE service will take for each traversal
code are defined as follows:

CLI$K_ALNUM — Continue reading input string as long as alphabetic
or numeric characters are encountered.

CLI$K_ALPHA — Continue reading input string as long as alphabetic
characters are encountered.

CLI$K_NUM — Continue reading input string as long as numeric
characters are encountered. Numeric characters must be valid for the
current default radix setting (refer to the SET DEFAULT command in
the VAX/DS 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,
0-9, $, and _.

CLISK_FILE — Continue reading input string as long as valid filename
characters are encountered. (Filename characters are A-Z, 0-9, plus
the wildcard characters * and %.)

CLI$K_SPACE — Continue reading input string as long as spaces are
encountered. If no spaces exist at the current point in the input string,
do not call the action routine; branch to ““miss’ instead.

CLI$SK_COMMA — Find next nonspace input character, and see if it
is a comma. If so, find next nonspace input character, then call action
routine. Otherwise branch to ““miss.”

CLI$SK_SLASH — Find next nonspace input character, and see if it is
a slash (/). If so, find next nonspace input character, then call action
routine. Otherwise branch to ““miss.”

CLI$K_VALUE — Find next nonspace input character, and see if it is
a: oran =. If so, find next nonspace input character, then call action
routine. Otherwise branch to “‘miss.”’

CLI$K_EOL — Find next nonspace input character, and see if it is a
line terminator. If so, call action routine. Otherwise branch to ““miss.”

CLI$SK_DEC — Continue reading input string as long as valid decimal
numeric characters are encountered.

CLI$K_HEX — Continue reading input string as long as valid
hexadecimal numeric characters are encountered.
5-91

$DS_CLI

CLISK_OCT — Continue reading input string as long as valid octal
numeric characters are encountered.

CLI$K_STRING — Continue reading input string as long as the input
string matches the character string specified by the “‘ascii’’ parameter.

The comparison is considered to be a match even if only the first
character of the input string (starting at the current pointer position)

matches the character string.

CLI$K_BR — Call the action routine, then branch unconditionally to
the address specified by ““miss.”” No reading of the input string occurs.

CLI$K_BIF — Call the action routine, then branch to address specified
by ““miss” if bit 0 of RO is set. No reading of the input string occurs.

CLISK_CALL — Call action routine, then unconditionally branch to
another parse tree. Address of tree is specified by ““miss.” Do not
nest calls.

CLI$K_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 routine may set or clear bit 0 of
RO. The contents of R0 will then be saved for use by the CLISK_BIFS
macro.

CLI$K_BIFS — Used after return from a subtree. Call action routine,
then branch if the action routine had set bit 0 of RO during processing

of CLISK_RETURN macro.

(Contents of R0 will have already

changed, but its value will have been saved during processing of

CLI$SK_RETURN.)
CLI$SK_EXIT — Call the action routine, then stop traversing the tree.

The $DS_PARSE system service returns control to the caller, with R0

set to SS§_NORMAL. No reading of the input string occurs. This code
is used to indicate that the input string has been successfully parsed.

CLI$K_ERROR — Call the action routine, then stop traversing the tree.
The $DS_PARSE system service returns control to the caller, with R0
set to DS$_ERROR. No reading of the input string occurs. This code
is used to indicate an unsuccessful parse of the input string (an illegal
command string was specified).

5-92

$DS_CLI

EXAMPLES

Here is a simple but instructive example of a user-defined command
language. Suppose we wanted to create a command language to represent
some of the steps involved in baking a cake. Consider just the following
steps:

Add sugar.

Add salt.

Add milk.

Beat ingredients.

Bake cake.

Figure 5-5 illustrates a parse tree for this command language.
Figure 5-5

Sample Parse Tree

Leading spaces

ZK-4792-85

5-93

$DS_CLI

This tree would be described with $DS_CLI macros as 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,

NO_ACTION,

ADD_NODE

;Leading

spaces

ADD_NODE:

$DS_CLI

CLISK_STRING,

$DS_CLI

CLI$K_SPACE,

$DS_CLI

CLISK_STRING,

$DS_CLI

CLISK_EOL,

ADD,

B_NODE,

NO_ACTION,

MILK,

’ADD’

ILLCMDS

S_NODE,

NO_ACTION,

; ADD
s ADD<space>

'MILK’

BADARGS

s ADD<space>MILK

;sADD<space>MILRK<cr>

$DS_CLI CLISK_EXIT
B_NODE:

$DS_CLI

<"A'B’>,

$DS_CLI

CLI$K_STRING,

$DS_CLI

CLISK_EOL,

$DS_CLI

CLISK_EXIT

NO_ACTION,

BAKE,

ILLCMDS

EAT_NODE,

NO_ACTION,

‘AKE’

ILLCMDS

s BAKE
s BAKE<cCIr>

EAT_NODE:

$DS_CLI

CLI$K_STRING,

$DS_CLI

CLISK_EOL,

$DS_CLI

CLISK_EXIT

BEAT,

ILLCMDS,

NO_ACTION,

’EAT’

ILLCMD$

;s BEAT

s BEAT<cCr>

S_NODE:

$DS_CLI

<"A’S’>,

$DS_CLI

CLISK_STRING,

$DS_CLI

CLISK_EOL,

$DS_CLI

CLISK_EXIT

NO_ACTION,

SALT,

ILLCMDS$

UGAR_NODE,

NO_ACTION,

;1 ADD<space>S

’ALT’

BADARGS

;s ADD<space>SALT
sADD<space>SALT<cr>

UGAR_NODE:

$DS_CLI

CLISK_STRING,

$DS_CLI

CLI$K_EOL,

$DS_CLI

CLISK_EXIT

$DS_CLI

CLI$K_EXIT

$DS_CLI

CLISK_ERROR,

ILLCMD

$DS_CLI

CLISK_ERROR,

BADARG

SUGAR,

NO_ACTION,

DONE:

ILLCMDS:

BADARGS
¢

5-94

BADARGS,
BADARGS

‘UGAR’

; ADD<space>SUGAR
s ADD<space>SUGAR<cr>

$DS_CLIDEF

$DS_CLIDEF
The $DS_CLIDEF macro defines (for MACRO-32 programs) symbolic
names for the ‘‘traversal codes’’ used in associated with the $DS_CLI
macro.

Symbols defined are:
CLI$K_ALNUM
CLIS$K_ALPHA
CLI$K_NUM
CLI$K_SYMBOL
CLISK_FILE

CLI$K_SPACE
CLI$K_COMMA
CLISK_SLASH

CLIS$K_VALUE
CLI$K_EOL
CLI$K_DEC
CLI$K_HEX

CLI$K_OCT
CLIS$K_STRING
CLI$K_BR
CLISK_BIF
CLI$K_CALL
CLIS$K_RETURN
CLI$K_BIFS
CLIS$K_EXIT
CLI$K_ERROR

MACRO-32

$DS_CLIDEF

ARGUMENTS

gbl

MACRO-32
EXAMPLE
$DS_CLIDEF GLOBAL

[gbl]

Can be LOCAL or GLOBAL

$CLOSE

$CLOSE
The Close File service of RMS is used to close a file after all processing

of the file has been completed. The $CLOSE service will also perform a

$DISCONNECT operation.

MACRO-32

$CLOSE

fab, [err], [suc]

BLISS-32

$CLOSE

(FAB=fab, [ERR=err], [SUC = suc]);

ARGUMENTS

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 is in the RAB.)

err (user mode only)
Address of a routine to be executed on error return from the service.

suc (user mode only)
Address of a routine to be executed on successful return from the service.

RETURN

STATUS

RMS$_NORMAL
RMS$_CCF

Servi

full Y

ervice successfully

completed. leted

completed.

Cannot close file. (Status value will be placed in
STV of FAB))

Note: For further details on return status values, refer to the VAX-11 RMS
Reference Manual.

5-96

$CLOSE

)
R

NOTES

Table 5-1 lists the FAB fields used by the $CLOSE service IN

STANDALONE MODE. For user mode, refer to the VAX-11 RMS Reference

Manual.

Table 5-1

FAB Fields Used by $CLOSE (Standalone Mode)

Field Mnemonic

Field Name

Input:

IF1

Iinternal file identifier.

XAB

Extended attribute block address.

Output:

IFI

Internal file identifier (zeroed).

STS

Completion status code (also returned in RO).

STV

Status value.

MACRO-32
EXAMPLE
$CLOSE FAB_ADDR

50—

BLISS-32
EXAMPLE
SCLOSE

(FAB=FAB_ADDR);

5-97

$CLREF

$CLREF
The $CLREF macro is used to clear event flags.

(Event flags are

discussed in Section 4.4.2).

MACRO-32

$SCLREF_x

BLISS-32

$SCLREF

ARGUMENTS

efn

(EFN =efn);

efn

Number of the event flag to be cleared. In user mode, the number may be
from 1 through 23, or from 32 through 127. In standalone mode, flags 1

through 64 may be used.

RETURN

STATUS

SS$_WASCLR

Service successfully completed. The specified fla

was previously O.u !

SS$_WASSET

Service successfully completed. The specified flag
was previously 1.

SS$_ILLEFC

An illegal event flag number was specified.

SS$_UNASEFC

In user mode, indicates that the specified common
event flag (see Section 4.4.2 has not been

associated with the process issuing the CLREF
macro.

In standalone mode, indicates that an event flag
from 64 through 127 was specified. These flags are

not valid in standalone mode.

MACRO-32
EXAMPLE
SCLREF_S

;Clear

event

flag

t{Clear

event

flag

BLISS-32
EXAMPLE
SCLREF

5-98

(EFN=5);

$DS_CLRVEC

$DS_CLRVEC
The Clear Exception or interrupt Vector system service is used to load

an exception or interrupt vector with the address of the standard VDS

condition handler for the specified vector. The macro’s purpose is
to restore the standard VDS vector contents after the vector has been

modified with the $DS_SETVEC service.
Only level 3 diagnostic programs may use the $DS_CLRVEC macro.

MACRO-32

$DS_CLRVEC_x

BLISS-32

$DS_CLRVEC

ARGUMENTS

RETURN

vector

(VECTOR =vector);

vector

The vector address, relative to the base of the System Control Block (SCB).

DS$_NORMAL
-

STATUS

Semi

full

ervice successiully

DS$_IVVECT

sompe e

leted

completed.

Address specified for ““vector” is not a valid vector
address.

MACRO-32
EXAMPLE
$DS_CLRVEC_S

#7X60

sRestore VDS
;

handler

address

memory write timeout

for

vector

BLISS-32
EXAMPLE
$DS_CLRVEC

(%X’'60’);

tRestore VDS
!

handler

address

memory write timeout

for

vector

5-99

$DS_CNTRLC

$DS_CNTRLC
The Declare Control-C Handler system service has two purposes. It can

be used to:
e

Declare a control-C handiler that will receive control when the program

user types a control-C
e

Enable and disable delivery of control-Cs

Refer to Section 4.4.6, Handling Control-Cs, for a details on control-C
handlers and disabling delivery of control-Cs.
If the $DS_CNTRLC service is not used, the VDS control-C handler will be
invoked.

MACRO-32

$DS_CNTRLC_x

BLISS-32

$DS_CNTRLC

[astadr], [disabl]

(JASTADR = astadr],
[DISABL = disable]);

ARGUMENTS

astadr

Address of the control-C handler. Default value is 0, which causes VDS
control-C handler to be declared.

disable
Value used to indicate if control-C delivery should be disabled or enabled.

If disable is set to 1, control-C delivery will be disabled. If the value is 0
(the default), control-C delivery is enabled, and control-Cs will be delivered
to whichever control-C handler has been selected.

RETURN

STATUS

SS$_WASSET
2

Servi

full

leted. Control-C deli

ervice successfully completed.

Control-C

delivery

was previously disabled (the disable flag was
previously set).

SS$_WASCLR

Service successfully completed. Control-C delivery
was previously enabled (the disable flag was
previously clear).

5-100

$DS_CNTRLC

MACRO-32

EXAMPLES
$SDS_CNTRLC_S

CNTRLC_HDLR

;Let VDS handle control-Cs.

$DS_CNTRLC_S
$DS_CNTRLC_S

;I want to handle control-Cs.

DISABL=#1

;Disable control-Cs.

BLISS-32
EXAMPLES
$DS_CNTRLC (ASTADR=CNTRLC_HDLR);!I want to handle control-Cs.
$DS_CNTRLC ()3

tLet VDS handle control-Cs.

$DS_CNTRLC (DISABLE=1);

t{Disable control-Cs.

5-101

$DS_SCOMPLEMENT

$DS_SCOMPLEMENT
This p-table descriptor macro complements the current contents of the

value register.

MACRO-32

$DS_$COMPLEMENT

BLISS-32

$DS_SCOMPLEMENT;

NOTES

Code generated by macro (shown in Macro-32; Bliss-32 is equivalent):

.BYTE "X89 ; Complement value register

5-102

$SCONNECT

SCONNECT
The Connect RAB to FAB service of RMS is used to associate an RAB

to an FAB after the file described in the FAB has been opened with the

$OPEN service. The file cannot be read until after it has been connected.

MACRO-32

SCONNECT

rab, [err], [suc]

BLISS-32

$CONNECT

(RAB=rab, [ERR=err], [SUC =suc]);

ARGUMENTS

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 is in the RAB.)

err (user mode only)
Address of a routine to be executed on error return from the service.

suc (user mode only)
Address of a routine to be executed on successful return from the service.

RETURN

STATUS

RMS$_NORMAL

Servi

RMS$_CCR

An RAB is already associated with the specified

fully

ervice successtully

leted _

completed.

eom

FAB.

RMS$_FAB

The FAB block is invalid.

RMS$_IFi

The FAB’s IFI field is invalid.

RMS$_RAB

The RAB block is invalid.

RMS$_RAC

Invalid record access mode. In standalone mode,
only sequential and RFA access modes are allowed.

Note: For further details on return status values, refer to the VAX-11 RMS
Reference Manual.

5-103

$CONNECT

NOTES

Table 5-2 lists the RAB fields used by the $CONNECT service IN
STANDALONE MODE. For user mode, refer to the VAX-11 RMS Reference
Manual.

Table 5-2 RAB Fields Used by $CONNECT (Standalone Mode)
Field Mnemonic

Field Name

Input:

FAB

Address of FAB.

ROP

Record-processing options. (Only BIO is allowed.)

Output:

STS

MACRO-32
EXAMPLE
$CONNECT RAB_ADDR

BLISS-32
EXAMPLE
$CONNECT

5-104

(RAB=RAB_ADDR);

Completion status code. (Also returned in RO.)

$DS_CVTREG

$DS_CVTREG
The Convert Register Contents to Character String system service can be

used to produce an ASCIC character string that associates each field in a
register (or any longword) with a mnemonic and indicates the current value

of each field. When the string is constructed, the following algorithm is
used:

For fields consisting of only one bit, the field mnemonic is placed into
the output string only if the bit is set.

For fields greater than one bit in length, two options are available:
—

A mnemonic can be associated with the field, in which case the
mnemonic and the field’s numeric value (in the specified radix) are
placed into the output string.

—

Instead of associating a mnemonic with the field, the field's
VALUE can have a mnemonic assigned to it. In this case, only
the mnemonic is placed into the output string.

The string can be displayed on the user terminal by using one of the

$DS_PRINTX services.

MACRO-32

$DS_CVTREG_x

msb, data, mneadr, strbuf, maxlen,

[vi], [v2], [v3], [v4], [v5], [v6]
BLISS-32

$DS_CVTREG

(MSB=msb, DATA =data,
MNEADR = mneadr, STRBUF = strbuf,
MAXLEN =maxlen, [V1=v1], [V2=v2],
[V3=v3],

ARGUMENTS

[V4=v4], [V5=V5], [V6=VvE]),

msb

Most significant bit. Reading of the specified location’s fields progresses
from left to right, so this parameter indicates the first bit that is to be read.
Maximum value is 31.

data
Contents to be converted. (Note that this is not the address of the contents,
but the contents themselves.)

mneadr
Address of a string of mnemonics and field specifiers.
A mnemonic may be a string of any length, containing any character except
I=I,

IlI,

I@I.

5-105

$DS_CVTREG

Fields are specified in the following manner:

For one-bit fields, simply include the mnemonic and follow it by a
comma, such as ..., MNEM1, 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 the size of the field and
““radix’’ is the radix in which the field contents is to be displayed.
Valid values for “‘radix”’ are ‘X"’ (hexadecimal), “O’" (octal), and
D" (decimal). An example is IPL =5X.

—

If a mnemonic is to be associated with the field’s VALUE, the
format is “‘mnemonic =size@’’, where ‘‘size’’ is the size of the
field. The value’s mnemonic is specified using the ““v1’’ through
““v6'’ parameters.

If a bit is not to be included in any field, simply include a comma in
the mnemonics list; for example, ...,BIT10,BIT9,,,BITS,...

The first mnemonic in the list will be associated with the bit indicated
by the ““msb’’ parameter. Mnemonics will be assigned from left to
right until the mnemonics list has been exhausted, or until bit 0 has
been reached, whichever happens first.

strbuf

Address of a buffer to receive the character string.

maxlen
Length of the buffer pointed to by “’strbuf.”” The buffer may not be greater
than 255 bytes. Caution: If the character string overruns the specified
length, the buffer will not contain a valid string.

v1 through v6

Each of these, if used, is the address of a counted table of value

mnemonics. Each table will contain pointers to lists of mnemonics that
are 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 in the mnemonic string (pointed to by
““mneadr’”’). The first time that format is used, the table pointed to by “v1”

will be referenced; the second time the format is used, the table pointed to
by ““v2" will be referenced, and so on.

Each entry in a table will be the address of a mnemonic that is to be
associated with the field's value. The value contained in the field will be
used as an offset into the table. If the field’s value is 0, the first table entry
will be fetched; if the field’s value is 1, the table’s second entry will be
used, and so on. The mnemonic pointed to by the table entry must be
defined by an ASCIC string. The mnemonic will be placed into the output
string. Figure 5-6 illustrates the linkages involved in this mechanism.

5-106

$DS_CVTREG

RETURN
STATUS

DS$_NORMAL

Service successfully completed.

DS$_PROGERR

The output string was too large to fit into the butfer

provided, or was larger than 255 characters.
The string of mnemonics and field descriptors

contains an invalid field descriptor.
The value specified for ““‘msb’’ was greater than 31.
The total number of macro arguments was greater

than 11.

$DS_CVTREG Value Mnemonics Table Usage

ADDRESS OF

TABLE_T1

ADDRESS OF

vV2:

TABLE_T2

TABLE_T1:

T1_ADDR_1:

ASCIC /T1_STRING_1/

T1_ADDR_2

T1_ADDR_2:

.ASCIC /T1_STRING_2/

b))
|44

J)
|44

T1_ADDR_1

T1_ADDR_N

TABLE_T2:

TJ_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/

(

))

Figure 5-6

T2_ADDR_N

T2_ADDR_N:

.ASCIC /T3_STRING_N/
ZK-4795-85

5-107

$DS_CVTREG

NOTES

On return from the service, R1 will contain the total length of the
output string, even if the string overflowed.

A good convention to follow is to not leave any fields unlabeled. Fields

that must be zero (MBZ), are not used, or consist of ““don’t care’’ bits

should be identified 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 is 0.

MACRO-32
EXAMPLE

The following examples illustrate, in both MACRO-32 and BLISS-32, a
method of displaying the processor’s PSL.

PSI, NME:

.ASCIC

/CM,TP,MBZ=2"X,FPD,1S,CUR=2@,PRV=2@,MBZ,/

/I1PL=5~X,MBZ=8"~X,DV,FU,IV,T,N,Z%,V,C/
MODE_LIST:

. LONG

.ADDRESS

KERNEL

«ADDRESS

EXEC

. ADDRESS

SUPER

« ADDRESS

USER

KERNEL:

.ASCIC

/KERNEL/

EXEC:

.ASCIC

/EXECUTIVE/

SUPER:

.ASCIC

/SUPERVISOR/

USER:

.ASCIC

/USER/

OUT_BUF:

.BLKB

MOVPSL

255

;Fetch

$DS_CVTREG -

5-108

PSL

contents.

;Create string.

MSB

#31,

DATA

RO,

:Read

1PSL

all

MNEADR = PSL_MNE,

sMnemonics

STRBUF

;Output

OUT_BUF,

MAXLEN =

#255,

MODE_LIST,

= MODE_LIST

;Maximum
-

bits.

contents.

string.

buffer.

length.

;1st

table.

;12nd

table

(use

lst

one

again).

$DS_CVTREG

BLISS-32
EXAMPLE
BIND

PSL_MNE

UPLIT

(%ASCIC

'CM, TP,MBZ=2~X,FPD,IS,CUR=2@,PRV=2@,MBZ, IPL=5"X,MBZ=8"X,
DV,FU,IV,T,N,%,V,C’);
BIND
KERNEL

= UPLIT

(%ASCIC

‘KERNEL'),

EXEC

= UPLIT

(%ASCIC

‘EXECUTIVE’),

SUPER

= UPLIT

(%ASCIC

’SUPERVISOR'),

USER

= UPLIT

(SASCIC

'USER’);

OWN

MODE_LIST

VECTOR

OUT_BUF

VECTOR

[5]

INITIAL

(4,

KERNEL,

EXEC,

SUPER,

OWN

[255,

BYTE];

BUILTIN

MOVPSL;
LOCAL

PSL_STORE;

MOVPSL

(PSL_STORE);

tFetch PSL contents.

!Create

$DS_CVTREG

string.

(MSB

31,

tRead

all

DATA

.PSL_STORE,

!PSI,

MNEADR

= PSL_MNE,

!Mnemonics

STRBUF

OUT_BUF,

tOutput

255,

tMaxlength.

bits.

contents.

string.

buffer.

MAXLEN

= MODE_LIST,

t1st

= MODE_LIST);

!2nd table

table.

(use

1lst one again).

5-109

$DASSIGN

$DASSIGN
The Deassign I/O Channel system service of VMS is used to release an /O
channel that was previously assigned with the $ASSIGN service. Level 2R
diagnostic programs should use this macro when all I/0 operations on a

device have been completed. See Section 4.2.1.1 for details of I/O in user
mode.

MACRO-32

$DASSGN_x

BLISS-32

$DASSGN

RETURN

ST ATU S

chan

(CHAN =chan);
|

SS$_NORMAL

Service successfully completed.

SS$_IVCHAN

An invalid channel number was specified; that is, a
channel number of 0 or a number larger than the

number of channels available.
SS$_NOPRIV

The specified channel is not assigned, or was
assigned from a more privileged access mode.

NOTES

See the VAX/VMS System Services Reference Manual for notes on the

$DASSGN macro. That manual should be read before performing 1/0O
operations in user mode.

MACRO-32
EXAMPLE
$DASSGN_S CHAN_NUM

BLISS-32
EXAMPLE
$DASSGN

5-110

(CHAN=.CHAN_NUM);

$DS_SDECIMAL

$DS_SDECIMAL
This p-table descriptor macro reads a value from the ATTACH command
line.

If no more parameters are available on the command line, or if the

next parameter is not a decimal value, it will prompt the operator with the

prompt text value. The value that is read is stored in the ‘‘value register”’

(see Section 3.2.3.3) for use by a $DS_$COMPLEMENT, $DS_$STORE, or

$DS_$CASE statement.

MACRO-32

$DS_$DECIMAL

< prompt>, low, high

BLISS-32

$DS_$DECIMAL

(PROMPT
= ‘prompt’, LOW
= low,
HIGH = high);

ARGUMENTS

prompt

Character string that is to be printed as a prompt to the user. This prompt
will be used if the ATTACH command line does not contain the required
value.

low
The low limit for the value. If 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 limit for the value. If the value given is higher than this, an error
message followed by the prompt message will be displayed. The default
radix for this value is decimal.
“

\prompt\

- LONG

low

. LONG

high

~X82

Beginning

-BYTE

.ASCIC

Prompt

Code generated by macro (shown in Macro-32; Bliss-32 is equivalent):

Low limit

NOTES

High

DECIMAL prompt

string

limit

5-111

$DS_$DECIMAL

MACRO-32
EXAMPLE
$DS_$DECIMAL TR,

$DS_S$DECIMAL PROMPT=<NUMBER OF ARRAY CARDS>, LOW=0, HIGH=15

BLISS-32
EXAMPLE
$DS_SDECIMAL (PROMPT='TR’,

LOW=1,

HIGH=15);

$DS_$DECIMAL (PROMPT=‘NUMBER OF ARRAY CARDS’, LOW=0, HIGH=15);

5-112

$DEF
The $DEF macro, defined in the VMS system library STARLET.MLB, is

used to define a field in a data structure, such as p-table descriptors, as

discussed in Section 3.2.2.

$DEF is only defined between calls to $DEFINI and $DEFEND.

MACRO-32

$DEF

BLISS-32

Not supported for BLISS-32.

ARGUMENTS

sym

sym, alloc, siz

Symbolic name to be associated with the field.

alloc
Allocation unit. Use one of the MACRO-32 block storage directives for this
parameter. MACRO-32 block storage directives are of the form ‘*.BLKx,"’

such as .BLKW or .BLKQ.

siz
Size of the field. This indicates the number of allocation units to assign.

EXAMPLE
S$SDEF

FIELD1l,

.BLKL,

;Field named FIELD1

longword.

5-113

$DS_DEFDEL

$DS_DEFDEL
The $DS_DEFDEL macro is used to conserve memory space during

program assembly time. Some of the symbol definition macros cause

memory space to be allocated. If the $DS_DEFDEL macro is issued
AFTER the symbol definition macros, then any memory space allocated
during the symbol definition process will be deallocated. This will not
affect the symbol definitions themselves.

5-114

SDEFEND

SDEFEND—SDEFINI
The $DEFEND and $DEFINI macros, defined in the VMS library

STARLET.MLB, are used to define data structures, such as p-table

descriptors, as discussed in Section 3.2.2. (Use the $DEF macro to
define the fields within the data structure, itself.)

MACRO-32

$DEFINI

struc, gbl, dot
(data structure field definitions)
$DEFEND struc, gbl, suf

BLISS-32

Not supported for BLISS-32.

ARGUMENTS

struc

Symbolic name for stucture being defined by the $DEFINI macro.

gbl
GLOBAL or LOCAL. Indicates whether the data structure’s symbolic name

(““struc”’) will be defined globally or locally.

dot
Address of the first field within the data structure. The symbol defined by

the first $DEF macro will be assigned to this value. Subsequent fields are
assigned to the next sequential memory addresses. The argument can be
numeric (for example, 512), or symbolic (for example, BLOCK_ADDR). If
symbolic, the symbol must be defined before the $DEFINI macro call. The
default is 0.

suf
Structure name suffix. The default is ““DEF”’".

EXAMPLE
SDEFINI

TABLEl,

GLOBAL,

SDEF

FIELDl,

.BLKL,

OFFSET

SDEF

FIELD2,

.BLKB,

SDEFEND

TABLEl,

GLOBAL

In this example, a global data structure named ““TABLE1"" has been defined
to contain two fields, called FIELD1 and FIELD2. FIELD1 starts at location
TABLE1
+ OFFSET and consists of 2 longwords. FIELD2 immediately

follows FIELD1 and is one byte long.

5-115

$DEFINI

$DEFINI—S$SDEFEND
The $DEFINI and $DEFEND macros, defined in the VMS library

STARLET.MLB, are used to define data structures, such as p-table
descriptors, as discussed in Section 3.2.2.

(Use the $DEF macro to

define the fields within the data structure, itself.)

MACRO-32

$DEFINI

struc, gbl, dot
(data structure field definitions)

$DEFEND

struc, gbl, suf

BLISS-32

Not supported for BLISS-32.

ARGUMENTS

siruc

Symbolic name for stucture being defined by the $DEFINI macro.

gbl
GLOBAL or LOCAL. Indicates whether the data structure’s symbolic name
(“struc’’) will be defined globally or locally.

dot
Address of the first field within the data structure. The symbol defined by
the first $DEF macro will be assigned to this value. Subsequent fields are
assigned to the next sequential memory addresses. The argument can be
numeric (for example, 512), or symbolic (for example, BLOCK_ADDR). If
symbolic, the symbol must be defined before the $DEFINI macro call. The
default is 0.

suf
Structure name suffix. The default is "DEF”’.

EXAMPLE
SDEFINI

TABLEl,

GLOBAL,

SDEF

FIELD1l,

.BLKL,

OFFSET

SDEF

FIELD2,

.BLKB,

$DEFEND TABLEl,

GLOBAL

In this example, a global data structure named “TABLE1"" has been defined
to contain two fields, called FIELD1 and FIELD2. FIELD1 starts at location

TABLE1 + OFFSET and consists of 2 longwords. FIELD2 immediately
follows FIELD1 and is one byte long.

5-116

$DS_DEVTYP

$DS_DEVTYP
The $DS_DEVTYP macro is used to indicate to the VDS which types of

devices the diagnostic program is capable of testing.

MACRO-32

$DS_DEVTYP

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

BLISS-32

$DS_DEVTYP

([STRINGS = < string,[string],... >],)
[ADDRESSES = < address,
[address],... >]);

ARGUMENTS

string

Character string representing a device type, such as 'RK06" or "'TM03’. This
parameter is used to specify device types for which p-table descriptors
exist in the VDS.

address
Address of a p-table descriptor defined within the diagnostic program.
P-table desciptors must be defined within the diagnostic program if:
1

A p-table descriptor for the device does not exist in the VDS, or

The programmer wishes to override the VDS’s p-table descriptor for a
device. P-table descriptors are discussed in Section 3.2.2.

MACRO-32

EXAMPLE

SDS_DEVTYP <RP04,

RPO5,

$DS_DEVTYP <>,<DESCR1,

RPO6>
DESCR2>

BLISS-32

EXAMPLE
$DS_DEVTYP

(STRINGS=<RP04,

RPO5,

$DS_DEVTYP

(ADDRESSES=<DESCR1,

RP06>);

DESCR2>);

$DISCONNECT

$DISCONNECT
The Disconnect RAB from FAB service of RMS is used to break the

connection between an RAB and an FAB. This terminates the record

stream and deallocates all I/0 buffers and data structures.

MACRO-32

$DISCONNECT

BLISS-32

$DISCONNECT (RAB =rab, [ERR = err], [SUC = suc]);

ARGUMENTS

rab, [err], [suc]

rab

Address of the RAB to be disconnected. (The RAB will contain the address
of its associated FAB.)

err (user mode only)

Address of a routine to be executed on error return from the service.

suc (user mode only)
Address of a routine to be executed on succesgful return from the service.

RETURN

STATUS

RMS$_NORMAL
RMSS_IF!

RMSS$_ISI

fully

ervice successfully

leted

completed.

comp

The FAB’s IFi field is invalid.

Invalid stream id. The specified RAB and FAB were
not connected.

RMS$_FAB

The FAB block is invalid.

RMS$_RAB

The RAB block is invalid.

Note: For further details on return status values, refer to the VAX-11 RMS
Reference Manual.

5-118

$DISCONNECT

NOTES

Table 5-3 lists the RAB fields used by the $DISCONNECT service IN

STANDALONE MODE. For user mode, refer to the VAX-11 RMS Reference
Manual.
Table 5-3

RAB Fields Used by $DISCONNECT (Standalone Mode)

Field Mnemonic

Field Name

Input:

1SI

Internal stream identifier.

Output:
STS

Completion status code.
(Also returned in RO.)

MACRO-32
EXAMPLE
$DISCONNECT

RAB_ADDR

BLISS-32
EXAMPLE
$DISCONNECT

(RAB=RAB_ADDR);

5-119

$DS_DISPATCH

$DS_DISPATCH
The $DS_DISPATCH macro generates the diagnostic program ‘‘dispatch

table.”” This table contains the starting addresses of all the tests. (These
addresses are placed in the table by the linker.) The VDS uses the table
when dispatching control to the tests.

MACRO-32

$DS_DISPATCH

BLISS-32

$DS_DISPATCH;

NOTES

In BLISS-32 programs, the $DS_DISPATCH macro must be placed before

the $DS_HEADER macro. (Refer to the template in Appendix A.)

MACRO-32
EXAMPLE
$DS_DISPATCH

BLISS-32
EXAMPLE
$SDS_DISPATCH;

5-120

$DS_DSDEF

$DS_DSDEF
The $DS_DSDEF macro defines (for MACRO-32 programs) symbolic

names for status codes returned by system services that begin with the
prefix DS$_. Status codes beginning with the SS$_ prefix are defined

by the $SSDEF macro in STARLET.MLB. For BLISS-32 programs, these
symbols may be referenced without first issuing the $DS_DSDEF macro.

Symbols defined are:
DS$_NORMAL

DS$_WARNING

DS$_ERROR

DS$_SEVERE

DS$_OVERFLOW

DS$_NULLSTR

DS$_ILLCHAR

DS$_PROGERR

DS$_TRUNCATE

DS$_NOTDON

DS$_IVVECT

DS$_IVADDR

DS$_VASFUL

DS$_INSFMEM

DS$_MMOFF

DS$_IHWE

DS$_FHWE

DS$_LOGIC

DS$_ILLPAGCNT

DS$_FRABUF

DS$_MCHK

DS$_KRNLSTK

DS$_POWER

DSS_TRANSL

DS$_CHME

DS$_NOTIMP

DS$_IPL2HI

DS$_ICERR

DS$_ICBUSY

DS$_ARITH

DS$_UNEXPINT

DS$_CHMK

DS$_BADTYPE

DS$_BADLINK

DS$S_NEEDUNIT

DS$_ILLUNIT

DS$_DEVNAME

DS$_NOPCS

DS$_NOSUPPORT

DS$_INVCPU

DS$_MEM_ALLOC_ERR

DS$_NOTALLOWMP

DS$_AP_NORMAL_BREAK

DS$_INIT_FAIL

DS$_BIIC

DS$_NODE

MACRO-32

$DS_DSDEF

ARGUMENTS

gbl

[gbl]

Can be LOCAL or GLOBAL

MACRO-32
EXAMPLE
$DS_DSDEF GLOBAL

5-121

$DS_DSSDEF

$DS_DSSDEF
The $DS_DSSDEF macro defines (for MACRO-32 programs and BLISS-32
programs) the symbolic names of entry points for the system services.
For BLISS-32 programs, the macro must be defined globally in at least
one source module, as follows:
GLOBAL

S$DSSDEF;

Symbols defined are:
DSSABORT
DS$ASKLGCL
DS$SATTACH
DSSBREAK
DS$CKLOOP

DS$SASKDATA
DSS$ASKSTR
DS$BGNSUB
DSSCANWAIT
DSS$SCLRVEC

DSS$SASKADR
DS$SASKVLD
DS$SBRANCH
DSSCHANNEL
DS$CNTRLC

DS$CVTREG

DSSENDPASS

DS$SENDSUB

DS$SERRDEV
DSSERRSOFT
DS$FREEDBGSYM

DS$SERRHARD
DSS$SERRSYS
DSS$SGETBUF

DSSERRPREP
DSSESCAPE
DS$GETMEM

DS$GPHARD
DS$SINLOOP

DSSHELP
DSSLOAD

DSSINITSCB
DSSLOADPCS

DS$SMAPDBGBLOCK

DSSMMOFF

DS$MMON

DSSMOVPHY

DSSMOVVRT

DSSPARSE

DS$SPRINTB
DS$SPRINTSIG
DS$RELBUF

DSSPRINTF
DSSPRINTX
DS3SRELMEM

DSSPRINTS
DSS$SPROBE
DSS$SSETIPL

DS$SETMAP

DS$SSETPRIEXV

DSSSETVEC

DS$SHOCHAN

DS$SUMMARY

DSSWAITMS

DSSWAITUS

SYSSALLOC

SYSSASCTIM

SYSSASSIGN

SYSSBINTIM

SYS$SCANCEL

SYSSCANTIM
SYS$SCONNECT
SYSSDASSGN

SYS$SCLOSE
SYSSDISCONNECT
SYSS$SFRO

SYSSCLREF
SYS$DALLOC
SYSSFAOL

SYSSGET

SYSSGETCHN

SYSSGETTIM

SYSSLKWSET

SYSSNUMTIM

SYSSOPEN

SYS$QIO
SYSSREADEF
SYSSSETIMR

SYS$SQIOW
SYSS$SSETAST
SYSS$SETPRI

SYSSREAD
SYSSSETEF
SYSS$SETPRT

SYS$SETRWM
SYSSULWSET

SYSSSETSWM
SYSSUNWIND

SYSSULKPAG
SYSSWAITFR

SYS$SWFLAND

SYSSWFLOR

MACRO-32

$DS_DSSDEF

ARGUMENTS

¢gbl/

MACRO-32
EXAMPLE
$DS_DSSDEF GLOBAL

5-122

[gbl]

Can be LOCAL or GLOBAL

$DS_SEND

$DS_SEND
The $DS_S$END macro is used to terminate a p-table descriptor.

MACRO-32

$DS_SEND

BLISS-32

$DS_SEND;

NOTES

Code generated by macro (shown in Macro-32; Bliss-32 is equivalent):

.BYTE "X81 ; End of p-table descriptor

5-123

$DS_ENDATTACHED

$DS_ENDATTACHED—$DS_BGNATTACHED
In a diagnostic program that tests multiple processors, use the

$DS_BGNATTACHED and $DS_ENDATTACHED macros to delineate
code that is to be executed in an attached processor. These macros
are used whether the code is included in the loadable image of the main

diagnostic program or it is a separate loadable image. (See Section 4.6.)

$DS_BGNATTACHED indicates the beginning of the code and creates
a label that can be used with the $DS_STARTATTACHED service. The
$DS_ENDATTACHED macro generates code that will send the processor

back to its idle loop.

MACRO-32

$DS_BGNATTACHED

routine_name, mask

$DS_ENDATTACHED
BLISS-32

$DS_BGNATTACHED
(ROUTINE_NAME = routine_name);

$DS_ENDATTACHED:;

ARGUMENTS

routine_name

Labels the routine and points to its first instruction.

mask
List of register names used in the entry mask.

$DS_ENDATTACHED

NOTES

1 You can include code that is contained in an attached process in

any number of separate executable files. The code in each file,
however, must be position-independent. You can only have one
attached process, delimited by one set of $DS_BGNATTACHED and
$DS_ENDATTACHED macros, per file.

If you want to place the code in a separate image, request a buffer
using the $DS_GETBUF service, load the image into the buffer, and
use the address of the buffer as the “’start_addr’” argument for the
$DS_STARTATTACHED macro.

You can enter the code using a CALL instruction.

It is recommended that you place data structures for the code in a
separate psect. If you must include the data structures in the same

psect as the code, place them (data structures) after the code and end
the executable section with a $DS_EXIT macro as shown:
.psect data
<data

$DS_BGNATTACHED RTN2

structures>

<executable

.psect code

code>

$DS_BGNATTACHED RTN1

$DS_EXIT ATTACHED

$DS_ENDATTACHED

5-125

$DS_ENDCLEAN

$DS_ENDCLEAN—S$DS_BGNCLEAN
The $DS_BGNCLEAN and $DS_ENDCLEAN macros are used to delimit
the program’s clean-up code. These macros create the connections which
make it possible for the VDS to locate and execute the clean-up code.

MACRO-32

$DS_BGNCLEAN

[<regmask>], [<psect>]

(clean-up code)

$DS_ENDCLEAN

BLISS-32

$DS_BGNCLEAN;

(clean-up code);

$DS_ENDCLEAN;
ARGUMENTS

regmask

List of general purpose register names to be placed in the entry mask.

psect
Any argument string that is valid for a MACRO-32 .PSECT statement. If
none is specified, the argument string “CLEANUP,LONG”’ will be used.

NOTES

In MACRO-32, the $DS_BGNCLEAN macro will generate the following

code:

. SAVE
. PSECT

psect

CLEAN_UP:
. WORD

"M<regmask>

In MACRO-32, the $DS_ENDCLEAN macro will generate the following

code:

CLEAN_UP_X:

$DS_BREAK
RET
. RESTORE

In BLISS-32, the $DS_BGNCLEAN macro will generate the following

code:

%SBTTL
PSECT
GLOBAL

’'CLEAN UP’
CODE

CLEANUP(WRITE);

ROUTINE

CLEAN_UP:NOVALUE

BEGIN

In BLISS-32, the $DS_ENDCLEAN macro will generate the following

code:
END

5-126

$DS_ENDCLEAN

MACRO-32
EXAMPLE
$DS_BGNCLEAN <R2,R3,R4,R5>,

<CLEANSECT,LONG>

$DS_ENDCLEAN

BLISS-32
EXAMPLE
$DS_BGNCLEAN;

$DS_ENDCLEAN;

5-127

$DS_ENDDATA

$DS_ENDDATA—S$DS_BGNDATA
The $DS_BGNDATA and $DS_ENDDATA macros are used to optionally

provide lists of input arguments to a test. Each time the VDS executes a
test for which argument lists have been specified, it 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 $DS_BGNDATA and $DS_ENDDATA macros must be located
immediately before the $DS_BGNTEST macro of the test to which the
parameter lists belong.

MACRO-32

$DS_BGNDATA

[align], argument-list, [argument-list]

$DS_ENDDATA
BLISS-32

ARGUMENTS

This macro is not supported for BLISS-32.

align

Desired alignment for the psect containing the argument lists. Possible

values are BYTE, WORD, LONG, QUAD, PAGE, or an integer from 0 to
9. If an integer is specified, the psect will start at the next address that is a
multiple of two raised to the power of the integer.

argument-list
A list of arguments to be used by the test. Each argument must occupy a
longword. Each parameter list must be formatted as shown in Figure 5-3.

$DS_ENDDATA

The $DS_ENDDATA will provide termination for the set of lists by

generating a longword of 0.

NOTES

The VDS will call the test code with a CALLG instruction. Each time
the test is called, the address of the next argument list will be used as

the CALLG instruction’s argument list parameter. Thus the arguments
can be referenced within the test by offsets from the AP.

5-128

$DS_ENDDATA

EXAMPLES
$DS_BGNDATA
. LONG

DATA_1,

DATA_2,

DATA_3,

DATA
4

. LONG

DATA_5,

DATA_6,

DATA_7,

DATA_8

.LONG

DATA_1,

DATA_3,

DATA_7,

DATA
9

$DS_ENDDATA

5-129

$DS_ENDINIT

$SDS_ENDINIT—S$DS_BGNINIT
The $DS_BGNINIT and $DS_ENDINIT macros are used to delimit the

diagnostic program’s initialization code. These macros create the
connections that make it possible for the VDS to locate and execute
the initialization code.

MACRO-32

$DS_BGNINIT

[<regmask_>], [<psect_>]
(initialization code)

$DS_ENDINIT
BLISS-32

$DS_BGNINIT;
$DS_ENDINIT;

ARGUMENTS

regmask

(initialization code);

List of general purpose register names to be placed in the entry mask.

psect
Any argument string that is valid for a MACRO-32 .PSECT statement. If
none is specified, the argument string ““INITIALIZE, LONG” will be used.

NOTES

In MACRO-32, the $DS_BGNINIT macro will generate the following

code:
. SAVE
.PSECT

psect

.WORD

~M<regmask>

INITIALIZE:

In MACRO-32, the $DS_ENDINIT macro will generate the following
code:
INITIALIZE
X:

$DS_BREAK
RET

.RESTORE

In BLISS-32, the $DS_BGNINIT macro will generate the following code:
%SBTTL

PSECT

'INITIALIZE’

CODE

INITIALIZE(WRITE);

GLOBAL ROUTINE

INITIALIZE

NOVALUE

BEGIN

In BLISS-32, the $DS_ENDINIT macro will generate the following code:
$SDS_BREAK;
END

5-130

$SDS_ENDINIT

e
e
R

MACRO-32
EXAMPLE
SDS_BGNINIT R2,R3,R4,R5,

INITSECT,LONG

$DS_ENDINIT

BLISS-32
EXAMPLE
$DS_BGNINIT;

$DS_ENDINIT;

5-131

$DS_ENDMESSAGE

$DS_ENDMESSAGE—$DS_BGNMESSAGE
The $DS_BGNMESSAGE and $DS_ENDMESSAGE macros should be used

to delimit each error reporting routine used in conjunction with the error
reporting macros ($DS_ERRxxxXx).

MACRO-32

$DS_BGNMESSAGE

$DS_ENDMESSAGE
BLISS-32

[<regmask>]
(error reporting routine)

$DS_BGNMESSAGE

(ROUTINE_NAME = routine_name);
(error reporting routine);

$DS_ENDMESSAGE;
ARGUMENTS

regmask
List of general purpose register names to be placed in the entry mask.

routine_name
Symbolic name to be associated with the error reporting routine.

NOTES

The error reporting routine must use $DS_PRINTB and $DS_PRINTX

macros to print messages.

The most important information should

be printed first, using $DS_PRINTB macros. The most detailed
information, such as dumps of device registers, should be printed
last, using $DS_PRINTX macros. Refer to Section 3.9.1, Error Message

Formats, for example error messages.

Further details on error reporting routines are listed in the description

of the error macros ($DS_ERRxxxx).

In MACRO-32, the $DS_BGNMESSAGE macro generates an entry

mask. The $DS_ENDMESSAGE macro generates a RET instruction.

In BLISS-32, THE $DS_BGNMESSAGE macro generates the following

code:

GLOBAL

ROUTINE

%NAME(routine_name)(NUM,
P1,

BEGIN

P2,

P3,

P4,

UNIT,
PS5,

P6)

MSGADR,
:

PRLINK,

NOVALUE

The $DS_ENDMESSAGE macro generates the following code:
RETURN
END

5-132

$DS_ENDMESSAGE

EXAMPLE

Refer to the description of the $DS_ERRxxxx macros (later in this chapter)
for examples of $DS_BGNMESSAGE and $DS_ENDMESSAGE.

5-133

$DS_ENDMOD

$DS_ENDMOD—$DS_BGNMOD
The $DS_BGNMOD and $DS_ENDMOD macros must be included at the
beginning and end, respectively, of every source module making up the

diagnostic program.

MACRO-32

$DS_BGNMOD

[env], [tn], [st]

(source module)

$DS_ENDMOD
h

BLISS-32

$DS_BGNMOD

([ENV =evn], [TEST =tn]);
(source module);

$DS_ENDMOD;
ARGUMENTS

env

Used to indicate if the program is a level 2 program. If so, this value must
be 2. Otherwise, the value should be 0 (the default).

Note: In the past, this parameter was assigned one of four predefined

values: CEP_FUNCTIONAL, CEP_REPAIR, SEP_FUNCTIONAL, or
SEP_REPAIR. These symbols are meaningless and should not be used.

(SEP_FUNCTIONAL) is equivalent to 2.

tn
Value representing the number to be assigned to the first test in this
module, if this module contains tests. Default value is 1.

st
Value representing the number to be assigned to the first subtest in this

module, if this module contains subtests. Default value is 1.

“

NOTES

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

as follows.

MODULE modnam =

BEGIN

$DS_BGNMOD

$DS_ENDMOD;
END

ELUDOM

5-134

() ;

$DS_ENDPASS

$DS_ENDPASS
The End-of-Pass system service is used to indicate to the VDS that a

program pass has been pompleted‘This service must be included m the

initialization code of every program. Refer to Section 3.5, Inmallzatlon

Code for an explanatlon of how the $DS_ ENDPASS macro |s to be used

BLISS-32

$DS_ENDPASS;

BETURN

ThlS service does not Teturn a status code.

STATUS

MACRO-32

EXAMPLE
-

BNEQL

10$%

$DS_ENDPASS_S

105:

;

PTABLE_ADDR

DS$_ERROR

Get P-table for next unit.

RO,

LOG_UNIT,
CMPL

then

all

units

declare

)

$DS_GPHARD_S

else

Get

done,

end-of-pass

continue.

BLISS-32
EXAMPLE
IF

$DS_GPHARD
(DEVNAM

.LOGUNIT,

RETADR

PTABLE_ADDR)

EQL DS$_ERROR THEN

$DS_ENDPASS;

P-table

declare

all

units

for

unit.

done,

end-of-pass.

5-135

$DS_ENDREG

$DS_ENDREG—$DS_BGNREG
The $DS_BGNREG and $DS_ENDREG macros may be used to delimit a
storage area in which device register contents are placed.

MACRO-32

$DS_BGNREG

(register storage area)

$DS_ENDREG
BLISS-32

NOTES

$DS_BGNREG;
$DS_ENDREG;

(register storage area);

In MACRO-32, the $DS_BGNREG macro generates the label
In BLISS-32, the $DS_BGNREG macro generates the statement
OWN DEV_REG : VECTOR [0};

5-136

The $DS_ENDREG does not generate any source code.

$DS_ENDSERV

$DS_ENDSERV—$DS_BGNSERYV
The $DS_BGNSERV and $DS_ENDSERYV macros should be used to

delimit interrupt service routines.

MACRO-32

$DS_BGNSERV

addr
(interrupt service routine)

$DS_ENDSERV
BLISS-32

These macros are not supported for BLISS-32.

ARGUMENTS

addr

Symbolic name to be associated with the interrupt service routine.

The $DS_BGNSERV macro will generate the following code:
.ALIGN

LONG,

PUSHR

#~M<RO,R1>

;

ALIGN

;

SAVE

LONGWORD

BOUNDARY

ADDR:

AND

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

#"M<RO,R1>

RESTORE

¢+

RETURN

RO AND
FROM

SERVICE

5-137

$DS_ENDSTAT

$SDS_ENDSTAT—$DS_BGNSTAT
The $DS_BGNSTAT and $DS_ENDSTAT macros should be used to 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

$DS_BGNSTAT

(statistics tables)

$DS_ENDSTAT

BLISS-32

$DS_BGNSTAT;

(statistics tables);

$DS_ENDSTAT;

NOTES

In MACRO-32, the $DS_BGNSTAT macro simply generates the label

'STATISTIC:’. The $DS_ENDSTAT does not generate any code.
2

In BLISS-32, the $DS_BGNSTAT macro generates the following
statement:

GLOBAL STATISTIC : VECTOR [0];
The $DS_ENDSTAT macro does not generate any code.

5-138

$DS_ENDSUB

$DS_ENDSUB—$DS_BGNSUB
The $DS_BGNSUB and $DS_ENDSUB macros are used to delimit each
subtest existing in any particular test. Refer to Section 3.8, Tests,
Subtests, and Sections, for a discussion of subtests.

MACRO-32

$DS_BGNSUB
(subtest)

$DS_ENDSUB
BLISS-32

$DS_BGNSUB;
(subtest);

$SDS_ENDSUB;
NOTES

The macro automatically numbers each subtest. Subtests are numbered
from 1 to N for each test, where N is the total number of subtests
within the test.

The $DS_BGNSUB macro generates a call to a VDS routine that will
record the numbers of the current test and subtest. The $DS_ENDSUB
macro will generate a call to a VDS routine that will verify that the
current test and subtest numbers are the same as those stored when
the $DS_BGNSUB macro was issued. If the numbers do not match, the
VDS will stop execution of the diagnostic program.

5-139

$DS_ENDSUMMARY

$DS_ENDSUMMARY—$DS_BGNSUMMARY
The $DS_BGNSUMMARY and $DS_ENDSUMMARY macros are used
to delimit the summary routine. Summary routines are discussed in
Section 3.7.

MACRO-32

$DS_BGNSUMMARY

[<regmask>], [<psect>]
(summary routine)

$DS_ENDSUMMARY
BLISS-32

$DS_BGNSUMMARY;

(summary routine);

$DS_ENDSUMMARY;
ARGUMENTS

regmask
List of general purpose register names to be placed in the entry mask.

psect
Any argument string that is valid for a MACRO-32 .PSECT statement. If
none is specified, the argument string 'SUMMARY,LONG’ will be used.

NOTES

In MACRO-32, the $DS_BGNSUMMARY macro will generate the

following code:
. SAVE
.PSECT

psect

SUMMARY
:
WORD

"M<regmask>

;sENTRY

MASK

In MACRO-32, the $DS_ENDSUMMARY macro will generate the

following code:
SUMMARY_X:

$DS_BREAK
RET
- RESTORE

In BLISS-32, the $DS_BGNSUMMARY macro will generate the

following code:
PSECT
GLOBAL

CODE

SUMMARY

ROUTINE

(WRITE);

SUMMARY

NOVALUE

BEGIN

In BLISS-32, the $DS_ENDSUMMARY macro will generate the

following code:
$DS_BREAK;
END

5-140

$DS_ENDTEST

$DS_ENDTEST—$DS_BGNTEST
The $DS_BGNTEST and $DS_ENDTEST macros are used to delimit each
test existing in a diagnostic program. Tests are discussed in Section 3.8,
Tests, Subtests, and Sections.

MACRO-32

SDS_BGNTEST

[<section-name,section-name,...>],
[<regmask>], [align]
(test code)

$DS_ENDTEST
BLISS-32

SDS_BGNTEST

([SECTION = < section-name,
section-name,... >],
[TEXT = "test-name’]),
(test code);

SDS_ENDTEST;

ARGUMENTS

section-name

Name of a program section to which this test belongs. Refer to Section 3.8,

Tests, Subtests, and Sections.

regmask

List of general purpose register names to be placed in the entry mask.

align

Desired alignment for the psect containing the argument lists. Possible
values are BYTE, WORD, LONG, QUAD, PAGE, or an integer from 0 to
9. If an integer is specified, the psect will start at the next address that is a
multiple of two raised to the power of the integer.

(In MACRO-32, the identifying message is defined by using the

$DS_SUBTTL macro.)

5-141

$DS_ENDTEST

NOTES

The $DS_BGNTEST macro will assign a test number to the test. The
test number is incremented each time the $DS_BGNTEST macro is

called within a source module. (The test number can be initialized
when the $DS_BGNMOD macro is called at the beginning of the
source module.)

In MACRO-32, the $DS_BGNTEST macro causes the following label to
be generated:
TEST_xxx::

.WORD

"M<

where ““xxx’’ is the current test number.
In MACRO-32, the $DS_ENDTEST macro generates the following code:
MOVL

#1,R0

;NORMAL EXIT

TEST_nnn_X::

$DS_BREAK
RET

In BLISS-32, the $DS_BGNTEST macro generates the following entry

point:
.ENTRY

TEST_xxX,
M<

where “xxx”" is the current test number.

In BLISS-32, the $DS_ENDTEST macro generates the following code:
$DS_BREAK;
SS$_NORMAL
END;

$DS_BGNTEST and $DS_ENDTEST are unavailable to attached
processors in multiprocessing environments.

5~142

$DS_ERRDEF

$DS_ERRDEF
The $DS_ERRDEF macro defines (for MACRO-32 programs) the symbolic

names of the parameters associated with the $DS_ERRxxxx macros.
These symbols will most likely be used in error reporting routines.

For BLISS-32 programs, these symbols are not used in error reporting
routines because expansion of the $DS_BGNMESSAGE macro produces a
parameter list for the error reporting routine.

Refer to descriptions of the $DS_BGNMESSAGE and $DS_ERRxxxx
macros for examples of referencing $DS_ERRxxxx parameters in error

reporting routines.

Symbols defined are:
ERRS$_NUM
ERRS$_UNIT
ERRS$_MSGADR

ERRS_PRLINK

ERRS_P1

ERRS_P2
ERR$_P3
ERRS_P4

ERRS_P5
ERR$_D6

MACRO-32

$DS_ERRDEF

ARGUMENTS

gbl

[gbl]

Can be LOCAL or GLOBAL

NOTES

These symbols are used as offsets into the argument list, for example,

ERR$_P3(AP).

MACRO-32

EXAMPLE
$DS_ERRDEF GLOBAL

5-143

$DS_ERRDEV

$DS_ERRDEV
There are five error reporting system services used to report to the

program user any errors encountered by the program that relate to failures
in the device being tested.

The $DS_ERRDEV macro is used to report device-fatal errors. It can be

issued from anywhere in the diagnostic program except the cleanup code.
The error types are discussed in Section 3.9, Reporting Errors.
The error reporting system services will:

Display a ‘‘header message’’ consisting of the program title, the pass,
test, and subtest numbers, and the message specified by the error
macro’s ‘‘msgadr’’ parameter (see below).

Cause the message routine specified by the error macro’s *‘prlink’’
parameter (see below) to be called.

Test the VDS control flags HALT and LOOP. If HALT is set, execution

of the program will be stopped. If LOOP is set, a program loop will be
established (see Section 3.10, Looping).

MACRO-32

$DS_ERRDEV_x

[num], [unit], [msgadr], [prlink],

[p1],...[p6]
BLISS-32

$DS_ERRDEV

([NUM =num], [UNIT
= unit],
[MSGADR = msgadi],
[PRLINK = prlink],
[P1=p1],...,[P6=p6]),

ARGUMENTS

num

An identification number assigned to the error macro. If not specified, a
number is automatically assigned to the error macro at program assembly
time, according to the following algorithm.
*

The error number is set to 1 at the beginning of each test and each
subtest.

Each time one of the error reporting macros is encountered at assembly
time, the macro is assigned the current error number and then the error
number is incremented.

If a macro call possesses an argument for the “‘num’’ parameter, that

argument is used and the stored error number is not incremented.

5-144

$DS_ERRDEV

Thus, if the default value for “num” is always taken, each error reporting
macro within a given subtest will have a unique error number assigned to
it, and for each subtest the error macros will be numbered sequentially
starting with 1. If the $DS_ERRxxxx_L form of the macro is used, the
“num’’ argument must be specified by using the $DS_ERRNUM macro.

unit
The logical unit number of the unit currently being tested.

msgadr
Address of a counted ASCII string to be included in the error message
header. Should contain a short description of the error.

prlink
Address of an error reporting routine. Routine must be delimited by

$DS_BGNMESSAGE and $DS_ENDMESSAGE macros and must use
$DS_PRINTB and $DS_PRINTX macros for output.

p1 through p6
One to six optional parameters that may be used to pass arguments to the
error reporting routine whose address is contained in ““prlink.”

L
e
e

RETURN

None.

STATUS
S

NOTES

Registers R2 through R11 are preserved so that the routine pointed to
by “‘prlink’” can expect to find them intact.

In a multiprocessing environment, $DS_ERRxxxx cannot be called from
within a block of code delineated by the $DS_BGNATTACHED and

$DS_ENDATTACHED macros.
Error Reporting Routines:

pointed to be “prlink”’ is called. The error reporting routine must have the
following properties:
*

Itis called with a CALLG instruction, so it must have an entry mask.

It must be delimited by the $DS_BGNMESSAGE and

$DS_ENDMESSAGE macros.

It must print the second and third levels of the error message

(see Section 3.9, Reporting Errors) by using the $DS_PRINTB and

$DS_PRINTX macros, respectively.
*

It can reference arguments passed via the p1 through p6 parameters.
These parameters can be accessed using the symbols defined by the

$DS_ERRDEF macro.

5-145

$DS_ERRDEV

It must contain all of the $DS_PRINTB and $DS_PRINTX macros
that are used to display the error message. (If $DS_PRINTB and

$DS_PRINTX macros are used to display an error message, they must
be contained in an error reporting routine.)

MACRO-32
EXAMPLE
Note: These examples will produce error messages that adhere to the format
indicated in Section 6.5.2, Error Message Formats.
READERRMSG:
FMT_ GOODBAD:

.ASCIC

\!/!/Device base

/READ error while performing block transfer./

address!_:!_!SL\-

\!/Address of

expected buffer!_:!_!SL\\!/Address of received buffer!_:!_!SL\\!/Transfer size (words)!_:! !SL\\!/Words in error!_:!_!SL\
FMT_DUMPHDR:
FMT

DUMPBUF:

.ASCIC
.ASCIC

\!/!/ADDRESS:!_EXPECTED:!_ RECEIVED:!_XOR:!/!/\
\!SL!_ISL! _!SL!_!SL!/\

BUFDUMP:

$DS_BGNMESSAGE <R2,R3,R4,R5>
$DS_PRINTB_S

FMT_GOODBAD,
-

’

second

level

ERRS$_P5(AP),ERRS_P2(AP),ERRS_P1(AP),

error msg.

FMT_DUMPHDR

CLRL

MOVAL

REC_BUF,R3

MOVAL

EXP_BUF,R4

10
CMPW

(R3),(R4)

BEQL

208

INCL

XORL3

R3,R4,R5

$DS_PRINTX_S

FMT_DUMPBUF,
-

" MO WME WE WNE wE N we “e “wa ~o|

ERR$_P3 (AP}, ERRS .P4(AP)
$DS_PRINTX_S

header

for

Clear

error

count

buffer dump

Get addr.

of received buffer

Get

addr.

expected

buffer

REPEAT

See

this word

IF word is

good.

bad

THEN

Count

the

error.

XOR good and bad data
Print

line of

3rd msg.,

level

IF eight bad words

308

THEN

CMPL

(R3)+, (R4)+

“e

Increment buffer pointers.

CMPL

R3, #REC_BUF_SIZE

R3, (R4), (R3),R5

See

BRB

10$

BEQL

208:

30s:

CMPL

top

buffer

UNTIL entire buffer

$DS_ENDMESSAGE

$DS_BGNTEST

$DS_ERRHARD_S

UNIT=LOG_UNIT,

MSGADR=READERRMSG,

PRLINK=BUFDUMP,

P1=REC_BUF,

P2=EXP_BUF,

P3=$REC_BUF_SIZE,

P4=ERR_COUNT,

P5=DEV_BASE

$DS_ENDTEST

5-146

displayed,

stop.

reached.

done.

$DS_ERRDEV

50—

BLISS-32
EXAMPLE
LITERAL

REC_BUF_SIZE = 256;
BIND

READERRMSG

UPLIT

(%ASCIC

’'READ error performing block transfer.’);

OWN

REC_BUF

VECTOR

[REC_BUF_SIZE,WORD],

EXP_BUF

VECTOR

[REC_BUF_SIZE,WORD],

LOG_UNIT, ERR_COUNT,DEV_BASE;

$DS_BGNMESSAGE

(ROUTINE_NAME=BUFDUMP)

LOCAL

ERRORS,
XOR_VALUE;

BIND

FMT_GOODBAD1=

UPLIT

(%ASCIC

'!/!/Device base address!_:!_!SL'),

(%ASCIC

’!/Address of

(%ASCIC

’!/Address of received buffer!_:!_!SL’),

(%ASCIC

’!/Transfer

(%ASCIC

’!/Words

FMT_GOODBAD2=

UPLIT
FMT_GOODBAD3=

UPLIT

expected buffer!_:!_ISL'),

FMT_GOODBAD4=

UPLIT

size

(words)!_s:!_ISL’),

FMT_GOODBADS5=

UPLIT

in error!_:!_!SL’'),

FMT_DUMPHDR=

UPLIT (%ASCIC ’!/!/ADDRESS:!
EXPECTED:! RECEIVED:!_XOR:!/t/'),

FMT_DUMPBUF=

UPLIT
{

!
!

(%ASCIC

’!SL!_!SL!_!SL!_!SL!/’);

Display the second level of the error message.
$DS_PRINTB

( FMT_GOODBAD1,
P5) ;

$DS_PRINTB

(FMT_GOODBAD2,P2);

$DS_PRINTB

(FMT_GOODBAD3,P1);

$DS_PRINTB

( FMT_GOODBAD4,
P3) ;

$DS_PRINTB

P4) ;
(FMT_GOODBADS,

Display the third level of the error message.
First print the header and clear the error count.
$DS_PRINTX
ERRORS = 0;

(FMT_DUMPHDR);

Print header for buffer dump.

Clear

error

count

5-147

$DS_ERRDEV

Now

mismatches.

compare

INCR

the

expected

If more
INDEX

FROM

buffer

than
0

with

eight

the

errors

received

buffer.

are found,

we can

REC_BUF_SIZE

Display

all

stop.

BEGIN

.REC_BUF

[.INDEX]

NEQ

.EXP_BUF

[.INDEX]

THEN

BEGIN
ERRORS

.ERRORS

XOR_VALUE

.REC_BUF

$DS_PRINTX

[.INDEX]

XOR

.EXP_BUF

(FMT_DUMPBUF,
REC_BUF

[.INDEX],

.EXP_BUF

[.INDEX],

.REC_BUF

[.INDEX],

.XOR_VALUE)
;

END;

.ERRORS

EQL

THEN

EXITLOOP;

END;

$DS_ENDMESSAGE;

$DS_BGNTEST

(TEXT='Read tests’);

$DS_ERRHARD

$DS_ENDTEST;

5-148

(UNIT=.LOG_UNIT,

MSGADR=READERRMSG,

PRLINK=BUFDUMP,

P1=REC_BUF,

P2=EXP_BUF,

P3=REC_BUF_SIZE,

P4=.ERR_COUNT,

PS=.DEV_BASE);

[.INDEX];

$DS_ERRHARD

$DS_ERRHARD
There are five error reporting system services used to report to the
program user any errors encountered by the program that relate to failures
in the device being tested.
The $DS_ERRHARD macro is used to report hard errors. It can be issued

only from within tests (see Section 3.8.1).
The error types are discussed in Section 3.9, Reporting Errors.
The error reporting system services will:
¢

Display a ‘‘header message’’ consisting of the program title, the pass,

test, and subtest numbers, and the message specified by the error
macro’s ‘‘msgadr’’ parameter (see below).
e

Cause the message routine specified by the error macro’s ‘‘prlink’’
parameter (see below) to be called.

Test the VDS control flags HALT and LOOP. If HALT is set, execution

of the program will be stopped. If LOOP is set, a program loop will be
established (see Section 3.10, Looping).

MACRO-32

$DS_ERRHARD_x

[num], [unit], [msgadr], [prlink],

[p1],...[p6]
BLISS-32

$DS_ERRHARD

([NUM =num], [UNIT
= unit],
[MSGADR = msgadr],
[PRLINK = prlink],

[P1=p1],...,[P6 = p6]);
ARGUMENTS

num

An identification number assigned to the error macro. If not specified, a
number is automatically assigned to the error macro at program assembly
time, according to the following algorithm.

The error number is set to 1 at the beginning of each test and each
subtest.

Each time one of the error reporting macros is encountered at assembly
time, the macro is assigned the current error number and then the error
number is incremented.

If a macro call possesses an argument for the ““num’’ parameter, that
argument is used and the stored error number is not incremented.

5-149

$DS_ERRHARD

Thus, if the default value for ““num” is always taken, each error reporting

macro within a given subtest will have a unique error number assigned to
it, and for each subtest the error macros will be numbered sequentially
starting with 1. If the $DS_ERRxxxx_L form of the macro is used, the
“num” argument must be specified by using the $DS_ERRNUM macro.

unit
The logical unit number of the unit currently being tested.

msgadr
Address of a counted ASCII string to be included in the error message
header. Should contain a short description of the error.

prlink
Address of an error reporting routine. Routine must be delimited by

$DS_BGNMESSAGE and $DS_ENDMESSAGE macros and must use

$DS_PRINTB and $DS_PRINTX macros for output.

p1 through p6
One to six optional parameters that may be used to pass arguments to the

error reporting routine whose address is contained in “'prlink."”

RETURN

None.

STATUS
NOTES

Registers R2 through R11 are preserved so that the routine pointed to

by “prlink” can expect to find them intact.

In a multiprocessing environment, $DS_ERRxxxx cannot be called from
within a block of code delineated by the $DS_BGNATTACHED and

$DS_ENDATTACHED macros.
Error Reporting Routines:

The ““prlink’” parameter is used to link an error reporting routine to the
error macro. The error reporting system service first displays the header
message, including the text pointed to by ““msgadr.” Then the routine

pointed to be “prlink”’ is called. The error reporting routine must have the
following properties:

Itis called with a CALLG instruction, so it must have an entry mask.

It must be delimited by the $DS_BGNMESSAGE
and

$DS_ENDMESSAGE macros.
*

It must print the second and third levels of the error message

(see Section 3.9, Reporting Errors) by using the $DS_PRINTB and
$DS_PRINTX macros, respectively.
¢

It can reference arguments passed via the pl through p6 parameters.

These parameters can be accessed using the symbols defined by the

$DS_ERRDEF macro.

5-150

$DS_ERRHARD

It must contain all of the $DS_PRINTB and $DS_PRINTX macros
that are used to display the error message. (If $DS_PRINTB and
$DS_PRINTX macros are used to display an error message, they must
be contained in an error reporting routine.)

MACRO-32
EXAMPLE
Note: These examples will produce error messages that adhere to the format

indicated in Section 6.5.2, Error Message Formats.

FMT_GOODBAD:

.ASCIC

READERRMSG:
.ASCIC
/READ error while performing block transfer./
\!/!/Device base address!_:!_!SL\\t/Address of expected buffer! :!_{SL\\!/Address of received buffer!_:!_!SL\\!/Transfer size (words)!_
:! !SL\\!/Words in error!_:!_!SL\

FMT_DUMPHDR:

FMT_DUMPBUF

.ASCIC

\!/!/ADDRESS:!_EXPECTED:!_RECEIVED:!_XOR:!/!/\
\!SL!_!SL!_!SL!_!SL!/\

BUFDUMP:

$DS_BGNMESSAGE <RZ,R3,R4,R5>
; Print second level of
FMT_GOODBAD, $DS_PRINTB_S
ERRS$_PS(AP),ERRS_P2(AP),ERRS_P1(AP), -

error msg.

ERRS_P3(AP),ERRS_P4 (AP)
$DS_PRINTX_S

FMT _DUMPHDR

CLRL

MOVAL

REC_BUF,R3

MOVAL

EXP_BUF,R4

103:

CMPW
BEQL

(R3),(R4)
208

INCL

XORL3
R3,R4,R5
$DS_PRINTX_S
FMT_DUMPBUF,
-

Print header for buffer dump

Clear

error

count

Get

addr.

received buffer

Get

addr.

expected

REPEAT

buffer

;
;

See if this word is good.
IF word is bad

THEN

Count the error.

H
H

XOR good and bad data
Print a line of 3rd msg.

level

R3, (R4), (R3),R5

20s:

CMPI,

R2,#8

IF eight bad words displayed,

BEQL

308

;

THEN stop.

CMPL
CMPL

(R3)+, (R4)+
R3, #REC_BUF_SIZE
10$

;
H

BRB
30s:

;

Increment buffer pointers.
See if top of buffer reached.
UNTIL entire buffer done.

$DS_ENDMESSAGE

$DS_BGNTEST

$DS_ERRHARD_S

UNIT=LOG_UNIT,
PRLINK=BUFDUMP,

MSGADR=READERRMSG,

P1=REC_BUF,

P2=EXP_BUF,

P3=#REC_BUF_SIZE,

P4=ERR_COUNT,

P5=DEV_BASE

$DS_ENDTEST

5-151

$DS_ERRHARD

BLISS-32
EXAMPLE
LITERAL

REC_BUF_SIZE

256;

BIND
READERRMSG

UPLIT

(%ASCIC

'READ

error

performing

block

transfer.’);

OWN
REC_BUF

VECTOR

[REC_BUF_SIZE,WORD],

EXP_BUF

VECTOR

[REC_BUF_SIZE,WORD],

LOG_UNIT,ERR_COUNT,DEV_BASE;

$DS_BGNMESSAGE

(ROUTINE_NAME=BUFDUMP)

LOCAL
ERRORS,
XOR_VALUE;
BIND

FMT_GOODBAD1=
UPLIT

(%ASCIC

’

t/t/Device base address!_:!

!SL’),

(%ASCIC

’

!/Address

expected buffer!_:!

!SL’),

(%ASCIC

!/Address

received buffer!_:!

!SL’'),

(%ASCIC

t/Transfer

size

(%ASCIC

’

t/Words

error!_:!_!SL’),

(%ASCIC

’

/1 /ADDRESS:!_EXPECTE
RECEIVED:! XOR:!/!/'),
D:!

(%ASCIC

’

!SL!_{SL!_!ISL! _!SL!/’");

FMT_GOODBAD2=
UPLIT

FMT_GOODBAD3=
UPLIT

FMT_GOODBAD4=
UPLIT

(words)!_:!_!SL'),

FMT_GOODBAD5=
UPLIT

FMT_DUMPHDR=

UPLIT
FMT_ DUMPBUF=

UPLIT

Display the

second

level

the

error message.

$DS_PRINTB

(FMT_GOODBAD1,
P5) ;

$DS_PRINTB

(FMT_GOODBAD2,P2)
;

$DS_PRINTB

(FMT_GOODBAD3,P1);

$DS_PRINTB

(FMT_GOODBAD4,
P3);

$DS_PRINTB

(FMT_GOODBADS,
P4) ;

Display the third level of

the error message.

First print

clear the

the header

$DS_PRINTX
ERRORS

5-152

and

(FMT_DUMPHDR);

error

count.

header

for

Clear

error

count

buffer

dump.

$DS_ERRHARD

! Now compare the expected buffer with the received buffer.
! mismatches.

If more than eight errors are found,

INCR INDEX FROM 0

Display all

we can stop.

TO REC_BUF_SIZE DO

BEGIN

.REC_BUF

[.INDEX]

NEQ

.EXP_BUF

[.INDEX]

THEN

BEGIN

ERRORS =

.ERRORS +

XOR_VALUE

+REC_BUF

$DS_PRINTX

[.INDEX]

XOR

.EXP_BUF

[.INDEX];

(FMT_DUMPBUF,
REC_BUF

[.INDEX],

.EXP_BUF

[.INDEX],

.REC_BUF

[.INDEX],

.XOR_VALUE)
;
END;

.ERRORS EQL 8

THEN EXITLOOP;

END;

$DS_ENDMESSAGE;

$DS_BGNTEST

(TEXT='Read

$DS_ERRHARD

tests’);

(UNIT=.LOG_UNIT,

MSGADR=READERRMSG,

PRLINK=BUFDUMP,

P1=REC_BUF,

P2=EXP_BUF,

P3=REC_BUF_SIZE,

P4=.ERR_COUNT,

P5=.DEV_BASE)
;

$DS_ENDTEST;

5-153

$DS_ERRNUM

$DS_ERRNUM
The $DS_ERRNUM macro is used in conjunction with the $DS_ERRxxxx_L
macros.

It generates executable code that will dynamically load the
“num’’ argument of the argument list created by the $DS_ERRxxxx_L

macro.

MACRO-32

$DS_ERRNUM

BLISS-32

Not supported for BLISS-32.

ARGUMENTS

/abel, [num]

Iabel
Address of the argument list generated by the $DS_ERRxxxx_L macro.

num
Error number. If a value is specified, the value will be used as the ““num’’

parameter in the argument list. If a value is not specified, the current
assembly-time error number is used. Refer to the description of the

$DS_ERRxxxx system services for an explanation of the assignment of error

numbers at assembly time.

NOTES

Using the $DS_ERRxxx_L macro to create an argument list, 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 specific error message, displayed at run-time, to a specific point
in the program listing because the error number is not explicitly specified
as a macro argument. This may or may not be a problem, depending on

the program’s use and users.

EXAMPLE
ARG_LIST:

$DS_ERRHARD_L UNIT

sDeclare hard error
LOG_UNIT,

MSGADR = HARD_MSG1,

PRLINK =

HARD_RTN1,

list

= CSR_REG

$DS_ERRNUM ARG_LIST

5-154

arg.

sPut

error number

arg.

list

$DS_ERRPREP

$DS_ERRPREP
There are five error reporting system services used to report to the

program user any errors encountered by the program that relate to failures
in the device being tested.

The $DS_ERRPREP macro is used to report device preparation errors.
It can be issued from anywhere in the diagnostic program except the
cleanup code.

The error types are discussed in Section 3.9, Reporting Errors.
The error reporting system services will:

Display a ‘‘header message’’ consisting of the program title, the pass,
test, and subtest numbers, and the message specified by the error
macro’s ‘‘msgadr’’ parameter (see below).

Cause the message routine specified by the error macro’s *‘prlink”’

Test the VDS control! flags HALT and LOOP. If HALT is set, execution
of the program will be stopped. If LOOP is set, a program loop will be

parameter (see below) to be called.

established (see Section 3.10, Looping).

MACRO-32

$DS_ERRPREP_x

BLISS-32

$DS_ERRPREP

[num], [unit], [msgadr], [prlink],
[p1],...[p6]
= unit],
(INUM =num], [UNIT
[MSGADR = msgadr],
[PRLINK = prlink],

[P1=p1],...,[P6 = p6b]);

ARGUMENTS

num

An identification number assigned to the error macro. If not specified, a
number is automatically assigned to the error macro at program assembly

time, according to the following algorithm.

The error number is set to 1 at the beginning of each test and each
subtest.

Each time one of the error reporting macros is encountered at assembly

time, the macro is assigned the current error number and then the error
number is incremented.

If a macro call possesses an argument for the “num’’ parameter, that
argument is used and the stored error number is not incremented.

5-155

$DS_ERRPREP

Thus, if the default value for “‘num’” is always taken, each error reporting
macro within a given subtest will have a unique error number assigned to
it, and for each subtest the error macros will be numbered sequentially
starting with 1. If the $DS_ERRxxxx_L form of the macro is used, the

“num”” argument must be specified by using the $DS_ERRNUM macro.

unit
The logical unit number of the unit currently being tested.

msgadr
Address of a counted ASCII string to be included in the error message
header. Should contain a short description of the error.

prlink
Address of an error reporting routine. Routine must be delimited by

$DS_BGNMESSAGE and $DS_ENDMESSAGE macros and must use
$DS_PRINTB and $DS_PRINTX macros for output.

p1 through p6
One to six optional parameters that may be used to pass arguments to the
error reporting routine whose address is contained in ““prlink.”

RETURN

None.

STATUS
“

NOTES

Registers R2 through R11 are preserved so that the routine pointed to

by “prlink” can expect to find them intact.
*

In a multiprocessing environment, $DS_ERRxxxx cannot be called from
within a block of code delineated by the $DS_BGNATTACHED and

$DS_ENDATTACHED macros.

Error Reporting Routines:

The “'prlink” parameter is used to link an error reporting routine to the

error macro. The error reporting system service first displays the header

message, including the text pointed to by “‘msgadr.”” Then the routine
pointed to be “prlink” is called. The error reporting routine must have the
following properties:

ltis called with a CALLG instruction, so it must have an entry mask.

It must be delimited by the $DS_BGNMESSAGE and

$DS_ENDMESSAGE macros.

It must print the second and third levels of the error message

(see Section 3.9, Reporting Errors) by using the $DS_PRINTB and

$DS_PRINTX macros, respectively.

It can reference arguments passed via the p1 through p6 parameters.
These parameters can be accessed using the symbols defined by the

$DS_ERRDEF macro.

5-156

$DS_ERRPREP

It must contain all of the $DS_PRINTB and $DS_PRINTX macros
that are used to display the error message. (If $DS_PRINTB and

$DS_PRINTX macros are used to display an error message, they must

be contained in an error reporting routine.)

lI-.----I-----.-------I-I-I-------------.--.--------l

MACRO-32
EXAMPLE
Note:

These examples will produce error messages that adhere to the format
indicated in Section 6.5.2, Error Message Formats.
READERRMSG:

FMT_GOODBAD:

+ASCIC

FMT_DUMPHDR:
FMT_DUMPBUF:

.ASCIC
.ASCIC

/READ error while performing block transfer./

.ASCIC

\t/!/Device base address!_:!_!SL\\!/Address of expected buffer!_:!_!SL\\!/Address of received buffer!_:!_!SL\\!/Transfer size (words)!_:!_!SL\\!/Words in error!_:!_tSL\
\!/!/ADDRESS:!_EXPECTED:!_ RECEIVED:!_XOR:!/!/\
\!SL!_!SL!_!SL!_!SL!/\

BUFDUMP:

$DS_BGNMESSAGE <R2,R3,R4,R5>
FMT_GOODBAD,—
$DS_PRINTB_S

: Print second level of error msg.

ERRS_P5(AP),ERR$_P2(AP),ERR$_P1(AP),

ERR$_P3(AP), ERRS_P4(AP)

CLRL

Print header for buffer dump
; Clear error count

MOVAL

EXP_BUF,R4

; Get addr. of expected buffer

CMPW
BEQL

(R3), (R4)
208%

;
H

INCL

CMPL

R2,#8

$DS_PRINTX_S

MOVAL
10s$:

FMT_DUMPHDR

REC_BUF,R3

20$:

CMPL

CMPL
BRB

30%:

REPEAT

THEN

;

R3,R4,R5
XORL3
S FMT_DUMPBUF,$DS_PRINTX_
BEQL

1 Get addr. of received buffer

R3, (R4), (R3),R5

H
H
;

;

308

(R3)+, (R4)+

R3, #REC_BUF_SIZE
10$

;

See if this word is good.
IF word is bad
Count the error.

XOR dood and bad data
Print a line of 3rd msg. level
IF eight bad words displayed,

THEN stop.

Increment buffer pointers.

See if top of buffer reached.

: UNTIL entire buffer done.

$DS_ENDMESSAGE

$DS_BGNTEST

$DS_ERRHARD_S

UNIT=LOG_UNIT,
PRLINK=BUFDUMP,

MSGADR=READERRMSG,

P1=REC_BUF,

P2=EXP_BUF,

P3=#REC_BUF_SIZE,

P4=ERR_COUNT,

P5=DEV_BASE

$DS_ENDTEST

5-157

$DS_ERRPREP

“

BLISS-32
EXAMPLE
LITERAL

REC_BUF_SIZE

256;

BIND
READERRMSG

UPLIT

(%ASCIC

‘READ

error

performing

block

transfer.’);

OWN

REC_BUF

VECTOR

[REC_BUF_SIZE,WORD],

EXP_BUF

VECTOR

[REC_BUF_ SIZE,WORD],

LOG_UNIT, ERR_COUNT,DEV_BASE;

$DS_BGNMESSAGE

(ROUTINE_NAME=BUFDUMP)

LOCAL
ERRORS,

XOR_VALUE;
BIND
FMT_GOODBAD1=
UPLIT

(%ASCIC

’t!/!/Device

(%ASCIC

’!/Address

expected

buffer!_:!_ ISL’),

(%ASCIC

’!/Address

received

buffe
:! !SL’),
r!

(%ASCIC

’'!/Transfer

size

(%ASCIC

’!/Words

error!_:!_!SL’'),

(%ASCIC

'!/!/ADDRESS:!_EXPECTED:!_RECEIVED:!_XOR:!/!/’),

(%ASCIC

’!SL!_!SL!_!SL!

base

address!_:!_ !SL’'),

FMT_GOODBAD2=
UPLIT
FMT_GOODBAD3=

UPLIT
FMT_GOODBAD4=
UPLIT

(words)!_:!

ISL’),

FMT_GOODBAD5=

UPLIT

FMT_DUMPHDR=

UPLIT
FMT_DUMPBUF=

UPLIT

Display the second

the

error message.

$DS_PRINTB

(FMT_GOODBADI1,P5);

$DS_PRINTB
$DS_PRINTB

(FMT_GOODBAD2,P2);
(FMT_GOODBAD3,P1l);
(FMT_GOODBAD4,P3);

$DS_PRINTB

(FMT_GOODBAD5S,P4);

$DS_PRINTB

level

I1SL!/’);

Display the third level of the error message,
First print the header and clear the error count.
$DS_PRINTX
ERRORS

5-158

(FMT_DUMPHDR);

Print header

Clear

error

for buffer dump.
count

$DS_ERRPREP

{
!

Now compare the expected buffer with the received buffer.
Display all
mismatches.
If more than eight errors are found, we can stop.
INCR

INDEX

FROM 0

TO REC_BUF_SIZE

BEGIN

.REC_BUF

[.INDEX}

NEQ

.EXP_BUF

[.INDEX]

THEN
BEGIN

ERRORS =

.ERRORS

XOR_VALUE

=
.REC_BUF

$DS_PRINTX

[.INDEX]

XOR

.EXP_BUF

[.INDEX];

(FMT_DUMPBUF,
REC_BUF

[.INDEX]},

.EXP_BUF

[ .INDEX],

.REC_BUF

[ .INDEX],

.XOR_VALUE)
;

END;

.ERRORS

EQL

THEN

EXITLOOP;

END;

$DS_ENDMESSAGE;

$DS_BGNTEST

(TEXT='Read tests’);

$DS_ERRHARD

(UNIT=.LOG_UNIT,

MSGADR=READERRMSG,

PRLINK=BUFDUMP,

P1=REC_BUF,

P2=EXP_BUF,

P3=REC_BUF_SIZE,

P4=.ERR_COUNT,

P5=.DEV_BASE)
;

$DS_ENDTEST;

5-159

$DS_ERRSOFT

$DS_ERRSOFT
There are five error reporting system services used to report to the
program user any errors encountered by the program that relate to failures

in the device being tested.

The $DS_ERRSOFT macro is used to report soft errors. it can be issued
only from within tests (see Section 3.8.1).
The $DS_ERRSYS macro is used to report system-fatal errors. It can be
issued from anywhere in the diagnostic program except the cleanup code.
The error types are discussed in Section 3.9, Reporting Errors.
The error reporting system services will:
*

Display a ‘““‘header message’’ consisting of the program title, the pass
test, and subtest numbers, and the message specified by the error

’

macro’s ‘‘msgadr’’ parameter (see below).

Cause the message routine specified by the error macro’s “‘prlink’’
parameter (see below) to be called.

Test the VDS control flags HALT and LOOP. If HALT is set, execution

of the program will be stopped. If LOOP is set, a program loop will be
established (see Section 3.10, Looping).

MACRO-32

$DS_ERRSOFT_x

[num], [unit], [msgadr], [prlink],

[P1],...[p6]
BLISS-32

$DS_ERRSOFT

(INUM =num], [UNIT = unit],

[MSGADR = msgadr],
[PRLINK = prlink],

[P1=p]1],...,[P6 = p6]);

ARGUMENTS

nmum

An identification number assigned to the error macro. If not specified, a
number is automatically assigned to the error macro at program assembly
time, according to the following algorithm.
*

The error number is set to 1 at the beginning of each test and each
subtest.

Each time one of the error reporting macros is encountered at assembly
time, the macro is assigned the current error number and then the error

number is incremented.
*

If a macro call possesses an argument for the “‘num’’ parameter, that

argument is used and the stored error number is not incremented.

5-160

$DS_ERRSOFT

Thus, if the default value for ““num’’ is always taken, each error reporting
macro within a given subtest will have a unique error number assigned to
it, and for each subtest the error macros will be numbered sequentially
starting with 1. If the $DS_ERRxxxx_L form of the macro is used, the
“num’” argument must be specified by using the $DS_ERRNUM macro.

unit

The logical unit number of the unit currently being tested.

msgadr

Address of a counted ASCII string to be included in the error message
header. Should contain a short description of the error.

prlink

Address of an error reporting routine. Routine must be delimited by
$DS_BGNMESSAGE and $DS_ENDMESSAGE macros and must use
$DS_PRINTB and $DS_PRINTX macros for output.

p1 through p6
One to six optional parameters that may be used to pass arguments to the
error reporting routine whose address is contained in ““prlink.”
P

RETURN

None.

STATUS
|

NOTES

Registers R2 through R11 are preserved so that the routine pointed to
by ““prlink”” can expect to find them intact.

In a multiprocessing environment, $DS_ERRxxxx cannot be called from
within a block of code delineated by the $DS_BGNATTACHED and
$DS_ENDATTACHED macros.

Error Reporting Routines:

The “prlink”” parameter is used to link an error reporting routine to the
error macro. The error reporting system service first displays the header
message, including the text pointed to by “msgadr.” Then the routine
pointed to be ““prlink’ is called. The error reporting routine must have the
following properties:

Itis called with a CALLG instruction, so it must have an entry mask.

It must be delimited by the $DS_BGNMESSAGE and
$DS ENDMESSAGE macros.

It must print the second and third levels of the error message

(see Section 3.9, Reporting Errors) by using the $DS_PRINTB and
$DS_PRINTX macros, respectively.
e

It can reference arguments passed via the pl through p6 parameters.
These parameters can be accessed using the symbols defined by the
$DS_ERRDEF macro.

5-161

$DS_ERRSOFT

It must contain all of the $DS_PRINTB and $DS_PRINTX macros

that are used to display the error message. (If $DS_PRINTB and
$DS_PRINTX macros are used to display an error message, they must
be contained in an error reporting routine.)
.

MACRO-32

EXAMPLE
Note: These examples will produce error messages that adhere to the format
indicated in Section 6.5.2, Error Message Formats.
READERRMSG:

FMT_GOODBAD:

.ASCIC

\!/!/Device base

/READ

error while performing

address!_:!_!SL\-

\!/Address of expected buffer!_:!_!SL\\!/Address of received buffer!_:!_ !SL\\t/Transfer size (words)!_:!_ !SL\\!/Words
FMT_DUMPHDR:

FMT_DUMPBUF:

-ASCIC

in error!_:!_!SL\

\!/!/ADDRESS:! EXPECTED:! RECEIVED:!_XOR:!/!/\

+ASCIC

\!SL!_!SL!_!SL! !SL!/\

BUFDUMP:

$DS_BGNMESSAGE <R2,R3,R4,R5>
$DS_PRINTB_S

FMT_GOODBAD, ~

; Print second level of error msgqg.
ERR$_P5(AP),ERRS_P2(AP) ,ERRS_P1(AP), ERR$_P3(AP),ERRS_P4(AP)
FMT_DUMPHDRH Print header for buffer dump

$DS_PRINTX_S
CLRL

MOVAL

REC_BUF,R3

MOVAL

EXP_BUF,R4

10s:

30$:

Clear

Get

addr.

received buffer

Get

addr.

expected

REPEAT

error

count

CMPW

(R3), (R4)

;

See

20$%

IF word is bad

THEN

INCL

Count

XORL3

R3,R4,R5

XOR good and bad data

FMT_DUMPBUF,
-

this

the

word

good.

error.

line of

R3,(R4),(R3),R5

3rd msg.

level

CMPL

R2,%#8

BEQL

308

IF eight bad words displayed,

THEN stop.

CMPL

(R3)+, (R4)+

Increment

CMPL

R3,#REC_BUF_SIZE

See

BRB

108

UNTIL

$DS_ENDMESSAGE

buffer pointers.

top of

buffer

entire buffer

$DS_BGNTEST

$DS_ERRHARD_S

UNIT=LOG_UNIT,
PRLINK=BUFDUMP,

MSGADR=READERRMSG,
-

P1=REC_BUF,

P3=#REC_BUF_SIZE,
P5=DEV_BASE

$DS_ENDTEST

$-162

buffer

BEQL

$DS_PRINTX_S

20$:

P2=EXP_BUF, P4=ERR_COUNT, -

reached.

done.

block transfer./

$DS_ERRSOFT

BLISS-32
EXAMPLE
LITERAL

REC_BUF_SIZE = 256;
BIND

READERRMSG =

UPLIT

(%ASCIC

OWN

REC_BUF

VECTOR

’'READ error performing block transfer.’);

[REC_BUF_SIZE,WORD},

EXP_BUF : VECTOR [REC_BUF_SIZE,WORD],
LOG_UNIT,ERR_COUNT,DEV_BASE;

$DS_BGNMESSAGE

(ROUTINE_NAME=BUFDUMP)

LOCAL

ERRORS,
XOR_VALUE;

BIND

FMT_GOODBAD1=

UPLIT

(%ASCIC

'!/!/Device base address!_:!_!SL’),

(%ASCIC

’!/Address of

(%ASCIC

’!/Address of received buffer!_:!_!SL’),

(%ASCIC

’!/Transfer size

(%ASCIC

‘!/Words

FMT_GOODBAD2=

UPLIT
FMT_GOODBAD3=

UPLIT

expected buffer!_:! !SL’}),

FMT_GOODBAD4=

UPLIT

(words)!_:!_(SL’}),

FMT_GOODBAD5=

UPLIT

in error!_:!_!SL’'),

FMT_DUMPHDR=

UPLIT (%ASCIC ‘!/!/ADDRESS:!
EXPECTED:!_ RECEIVED:!_XOR:!/!/'),

FMT_DUMPBUF=

UPLIT
¢t

!
{

(%ASCIC

’!SL!_!SL! !SL!_!SL!/');

Display the second level of the error message.
$DS_PRINTB

(FMT_GOODBAD1,P5)
;

$DS_PRINTB

(FMT_GOODBAD2,P2);

$DS_PRINTB

(FMT_GOODBAD3,P1);

$DS_PRINTB

(FMT_GOODBAD4,
P3) ;

$DS_PRINTB

(FMT_GOODBADS,
P4) ;

Display the third level of the error message.
First print the header and clear the error count.

$DS_PRINTX
ERRORS

(FMT_DUMPHDR) ;

Print header for buffer dump.

Clear

error

count

5-163

$DS_ERRSOFT

Now

[}

mismatches.

compare

INCR

the

expected

If more
INDEX

FROM

buffer

than
0

with

eight

the

errors

received

are

REC_BUF_SIZE

found,

buffer.

we can

Display

all

stop.

BEGIN
IF

.REC_BUF

[.INDEX]

NEQ

.EXP _BUF

[.INDEX]

THEN
BEGIN

ERRORS

.ERRORS

XOR_VALUE

=
-REC_BUF

$DS_PRINTX

[.INDEX]

XOR

.EXP_BUF

(FMT_DUMPBUF,
REC_BUF

[ .INDEX],

.EXP_BUF

[.INDEX],

.REC_BUF

[.INDEX],

.XOR_VALUE)
;
END;

.ERRORS

EQL

THEN

EXITLOOP;

END;

$DS_ENDMESSAGE
;

$DS_BGNTEST

(TEXT='Read tests’);

$DS_ERRHARD

$DS_ENDTEST;

5-164

(UNIT=.LOG_UNIT,

MSGADR=READERRMSG,

PRLINK=BUFDUMP,

P1=REC_BUF,

P2=EXP_BUF,

P3=REC_BUF_SIZE,

P4=.ERR_COUNT,

P5=.DEV_BASE);

[.INDEX];

$DS_ERRSYS

$DS_ERRSYS
There are five error reporting system services used to report to the

program user any errors encountered by the program that relate to failures
in the device being tested.

The $DS_ERRSYS macro is used to report system-fatal errors. It can be
issued from anywhere in the diagnostic program except the cleanup code.
The error types are discussed in Section 3.9, Reporting Errors.
The error reporting system services will:

Display a “*header message’'’ consisting of the program title, the pass,
test, and subtest numbers, and the message specified by the error
macro’s ‘‘msgadr’’ parameter (see below).

Cause the message routine specified by the error macro’s ‘‘prlinkTM

Test the VDS control flags HALT and LOOP. If HALT is set, execution

parameter (see below) to be called.

of the program will be stopped. If LOOP is set, a program loop will be
established (see Section 3.10, Looping).

MACRO-32

$DS_ERRSYS_x

BLISS-32

$DS_ERRSYS

ARGUMENTS

num

[num], [unit], [msgadr], [prlink],

[p1],...[p6]
= unit],
(INUM =numj, [UNIT

[MSGADR = msgadr],
[PRLINK = prlink],
[P1=p1],...,[P6
= p6]);

An identification number assigned to the error macro. If not specified, a
number is automatically assigned to the error macro at program assembly
time, according to the following algorithm.

The error number is set to 1 at the beginning of each test and each
subtest.

Each time one of the error reporting macros is encountered at assembly
time, the macro is assigned the current error number and then the error
number is incremented.

If a macro call possesses an argument for the ““num’’ parameter, that
argument is used and the stored error number is not incremented.

5-165

$DS_ERRSYS

Thus, if the default value for “‘num’’ is always taken, each error reporting

“num’’ argument must be specified by using the $DS_ERRNUM macro.

unit
The logical unit number of the unit currently being tested.

msgadr
Address of a counted ASCII string to be included in the error message
header. Should contain a short description of the error.

prlink
Address of an error reporting routine. Routine must be delimited by
$DS_BGNMESSAGE and $DS_ENDMESSAGE macros and must use

$DS_PRINTB and $DS_PRINTX macros for output.

p1 through p6

One to six optional parameters that may be used to pass arguments to the

error reporting routine whose address is contained in ‘“prlink.”’

RETURN

None.

STATUS

NOTES

Registers R2 through R11 are preserved so that the routine pointed to

by ““prlink”’ can expect to find them intact.
*

In a multiprocessing environment, $DS_ERRxxxx cannot be called from
within a block of code delineated by the $DS_BGNATTACHED and

$DS_ENDATTACHED macros.

Error Reporting Routines:

The “prlink”” parameter is used to link an error reporting routine to the

error macro. The error reporting system service first displays the header
message, including the text pointed to by ““msgadr.” Then the routine

pointed to be ““prlink” is called. The error reporting routine must have
the
following properties:
*

Itis called with a CALLG instruction, so it must have an entry

It must be delimited by the $DS_BGNMESSAGE and

mask.

$DS_ENDMESSAGE macros.

It must print the second and third levels of the error message

(see Section 3.9, Reporting Errors) by using the $DS_PRINTB and
$DS_PRINTX macros, respectively.

It can reference arguments passed via the p1 through p6 parameter
s.
These parameters can be accessed using the symbols defined by the

$DS_ERRDEF macro.

5-166

$DS_ERRSYS

MACRO-32
EXAMPLE
Note: These examples will produce error messages that adhere to the format

indicated in Section 6.5.2, Error Message Formats.

FMT_GOODBAD:

.ASCIC

FMT_DUMPHDR!

.ASCIC

FMT_DUMPBUF:

+ASCIC

READERRMSG:

.ASCIC

/READ error while performing block transfer./

\!/!/Device base address!_:!_!SL\\t/Address of expected buffer!_:!_I!SL\\!/Address of received buffer!_:!_!SL\\{/Transfer size (words)!_:!_!SL\\{/Words in error!_s:!_{SL\

\!/{/ADDRESS:!_EXPECTED:!_RECEIVED:!_XOR:!/!/\
\!SL!_!SL!_{SL!_!SL!/\

BUFDUMP:

$DS_BGNMESSAGE

<R2,R3,R4,R5>

FMT_GOODBAD, ~

$DS_PRINTB_S

Print second

level

ERRS_PS (AP),ERRS_P2 (AP),ERRS_P1(AP),

error msg.

ERR$_P3(AP),ERRS_P4 (AP)
14

Print header

CLRL

FMT_DUMPHDR

;

Clear

MOVAL
MOVAL

REC_BUF,R3
EXP_BUF,R4

:
;

Get addr.
Get addr.

REPEAT

CMPW

{R3),(R4)

BEQL

20$

this word is good.
IF word is bad

THEN

INCL
XORL3

R2
R3,R4,R5

$DS_PRINTX_S

10s:

$DS_PRINTX_S

FMT_DUMPBUF,
-

for buffer

dump

error count

of
of

received buffer
expected buffer

See if

;
;

Count the error.
XOR good and bad data

Print a line of

3rd msg.

level

R3, (R4), (R3),R5

203%:

30$:

CMPL

R2,#8

;

IF eight bad words displayed,

BEQL

308

THEN

CMPL

(R3)+, (R4)+

;

Increment buffer pointers.

CMPL

R3, #REC_BUF_SIZE

See if

BRB

108

stop.

top of

buffer reached.

UNTIL entire buffer done.

$DS_ENDMESSAGE

$DS_BGNTEST

$DS_ERRHARD_S

UNIT=LOG_UNIT,
PRLINK=BUFDUMP,

MSGADR=READERRMSG,

P1=REC_BUF,

P2=EXP_BUF,

P3=#REC_BUF_SIZE,

P4=ERR_COUNT,

P5=DEV_BASE

$DS_ENDTEST

5-167

$DS_ERRSYS

BLISS-32
EXAMPLE
LITERAL

REC_BUF_SIZE

256;

BIND

READERRMSG

UPLIT

(%ASCIC

’'READ

error

performing

block

transfer.’):

OWN
REC_BUF

VECTOR

[REC_BUF_SIZE,WORD],

EXP_BUF

VECTOR

[REC_BUF_SIZE,WORD],

LOG_UNIT,ERR_COUNT,DEV_BASE;

$DS_BGNMESSAGE

(ROUTINE_NAME=BUFDUMP)

LOCAL
ERRORS,

XOR_VALUE;
BIND

FMT_GOODBAD1=

UPLIT

(%ASCIC

'!/!/Device

(%ASCIC

'!/Address

expected

buffer!
:t ISL’),

(%ASCIC

’!/Address

received

buffer!_:!

(%ASCIC

’'!/Transfer

size

(%ASCIC

‘!/Words

error!_:!_!SL’),

(%ASCIC

’!/!/ADDRESS:!_EXPECTED:!_RECEIVED:!_XOR:!/!/'),

(%ASCIC

’!SL!_!SL!_!SL!_{SL!/’);

base

address!_:!_!SL’),

FMT_GOODBAD2=

UPLIT
FMT_GOODBAD3=

UPLIT

!SL’),

FMT_GOODBAD4=

UPLIT

(words)!_:!_!SL’),

FMT_GOODBADS=

UPLIT

FMT _DUMPHDR=

UPLIT
FMT_DUMPBUF=

UPLIT

Display the second

the error message.

$DS_PRINTB

(FMT_GOODBADI,P5);

$DS_PRINTB

(FMT_GOODBAD2,P2);

$DS_PRINTB

(FMT_GOODBAD3,P1);

$DS_PRINTB

(FMT_GOODBAD4,P3);

$DS_PRINTB

(FMT_GOODBADS,P4);

Display the third

First print

ERRORS

level

the header

$D5_PRINTX

5-168

level

the error message.

and clear

(FMT_DUMPHDR);

the

error

count.

header

for

Clear

error

count

buffer

dump.

$DS_ERRSYS

Now compare the expected buffer with the received buffer.

mismatches.
INCR

If more than eight
INDEX

FROM

errors

are found,

0 "TO REC_BUF_SIZE

Display all

we can stop.

BEGIN

.REC_BUF

[.INDEX]

NEQ

.EXP_BUF

[ .INDEX]

THEN
BEGIN

ERRORS

.ERRORS

XOR_VALUE

=
.REC_BUF

$DS_PRINTX

[.INDEX]

XOR

.EXP_BUF

[ .INDEX];

(FMT_DUMPBUF,
REC_BUF

[ .INDEX],

.EXP_BUF

[ .INDEX],

.REC_BUF

[ .INDEX],

.XOR_VALUE)
;

END;
IF

.ERRORS

EQL

THEN

EXITLOOP;

END;

$DS_ENDMESSAGE;

$DS_BGNTEST

(TEXT='Read

$DS_ERRHARD

tests’);

(UNIT=.LOG_UNIT,

MSGADR=READERRMSG,

PRLINK=BUFDUMP,

P1=REC_BUF,

P2=EXP_BUF,

P3=REC_BUF_SIZE,

P4=.ERR_COUNT,

P5=.DEV_BASE);

$DS_ENDTEST;

5-169

$DS_ESCAPE

$DS_ESCAPE
The $DS_ESCAPE program control macro can be used to exit from a

test or subtest if a hardware failure has been detected from within 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 is encountered, program control
will branch to the next $DS_ENDSUB or $DS_ENDTEST (whichever is

specified).

MACRO-32

$DS_ESCAPE

BLISS-32

Not supported for BLISS-32. See Note 1.

ARGUMENTS

NOTES

arg

Indicates whether program control should branch to nearest $DS_ENDSUB
or nearest $DS_ENDTEST. The argument may be either SUB or TEST.

For programs written in BLISS-32, similar functionality can be obtained

by following the $DS_ERRxxxx macro with a LEAVE statement, as
shown in the example below.

MACRO-32
EXAMPLE
$DS_BGNSUB

$DS_ERRHARD

UNIT=LOG_UNIT,

$DS_ESCAPE

SUB

$DS_ENDSUB

5-170

MSGADR=HRDMSG3,

PRLINK=HRDRTN3

$DS_ESCAPE

[
)

BLISS-32
EXAMPLE
$DS_BGNSUB;

BEGIN

SUB3:

$DS_ERRHARD_S (UNIT=.LOG_UNIT,
LEAVE

MSGADR=HRDMSG3, PRLINK=HRDRTN3);

SUB3;

END;

$DS_ENDSUB;

5-171

$DS_EXIT

$DS_EXIT
The $DS_EXIT program control macro is used to unconditionally branch to
the end of the currently executing program segment. Exits can be made
from any of the following:
e

Atest

A subtest

An interrupt service routine

The summary routine

Code that is executing in an attached processor (See Section 4.6, VDS
in a Multiprocessing Environment).

MACRO-32

$DS_EXIT

BLISS-32

Not supported for BLISS-32. See Note 1.

ARGUMENTS

NOTES

arg

Indicates program segment type. Valid arguments are TEST, SUB, SERYV,
SUMMARY, and ATTACHED.

For programs written in BLISS-32, similar functionality can be obtained

by using the LEAVE statement, as shown in the example below.

MACRO-32
EXAMPLE
$DS_BGNSERV

SERV_RTN

$DS_EXIT

SERV

$DS_ENDSERV

5-172

$DS_EXIT

BLISS-32
EXAMPLE
$DS_BGNTEST;
T2_BLK1:
BEGIN

LEAVE T2_BLK1;

END;

$DS_ENDTEST;

5-173

$FAB

$FAB
The $FAB 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 is a data structure that is required for

performing file management operations using RMS. Refer to Section 4.5,
File Management.

This description only discusses FAB fields supported by VDS RMS. For
a discussion of VMS RMS-supported fields, refer to the VAX/VYMS RMS
Reference Manual.

Besides allocating the FAB, the $FAB macro also defines symbols for each
FAB field. Symbols are of the form ‘‘FABS$datatype_fieldname,’’ where
““datatype’’ is a data type specifier listed in Section 4.5.4.
“

MACRO-32

SFAB

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
h

BLISS-32

$FAB

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 ;

5-174

$FAB

L~
]

ARGUMENTS

All parameters are optional. Refer to descriptions of the RMS run-time
services to determine which fields are required for which services. Fields

may be loaded at run-time with the $FAB_STORE macro, or by directly
referencing FAB fields, as described in Section 4.5.4.

DNA = default-name-address
Address of a character string representing defaults to be used for the
filename, if the actual filename specification is incomplete. The default
string may contain all or some of the following fields:

Node

Device

Device directory

Filename

Filename extension

File version number

An example default string is
DEF_STRING:

.ASCII

/.DAT/

The DNS field must be used in conjunction with the DNA field.

DNM = default-name-filespec
A character string representing defaults to be used for the filename, if the
actual filename specification is incomplete. Using the DNM parameter is

an alternative to using the DNA and DNS parameters.
A MACRO-32 example of this parameter is DNM
= <.EXE;0>. A BLISS-32
example is DNM ="_EXE;(’.

DNS = default-string-size
Size of the string pointed to by ““default-name-address.” Used only if the
DNA parameter is also used.

FAC = fac-param
File access parameters. If the program is to perform $GET or $READ

operations, the FAC field must be set up before the $OPEN operation is
performed. Following are valid file access parameters:

BIO — Block I/O operations ($READ) will be performed.

BRO — Both Block I/O (SREAD) and Record I/O ($GET) operations will
be performed.

GET — Record I/O operations ($GET) will be performed. This is the
default.

5-175

$FAB

FNA = filename-address
Address of character string representing the name of the file on which
operations are to be performed. If any filename components are missing
from the string, those components will be extracted from the default string
specified by either the DNA or the DNM parameter. If components are
still missing, they will be defaulted to the fields that would be exhibited if
a SHOW LOAD user command were issued.
The FNS parameter must be used in conjunction with the FNA parameter.

FNM = filename-filespec
Character string representing the name of the file on which operations are
to be performed. This parameter is an alternative to the FNA and FNS
parameters, and would most likely be used in programs that always open
the same file. An example in BLISS-32 would be FNM =EVABC.DAT.

FNS = filename-string-size
Size of character string pointed to by “‘filename-address.”” The FNS
parameter is used only if the FNA parameter is also used.

FOP = RWO
Rewind on open. Indicates that a magnetic tape should be rewound before
a file on the tape is opened.

FSZ = header-size
Size of file’s fixed control area. Used only for files containing fixed-length
control records. Refer to the VAX/VMS RMS Reference Manual for details. It
is unlikely that a diagnostic program will make use of this field.

XAB = xab-addr
Address of the FHC XAB, if used. (The FHC XAB is declared with the
$XABFHC macro.)

NOTES

Read-Only FAB Fields

The following FAB fields are not loaded by the programmer under VDS

RMS. They are filled in by RMS services, and may be read after the service
has completed. (Some of these fields are read/write in VMS RMS.)
e

BID — Block identifier field. Indicates to RMS that a block is an FAB.

BLN — Block length field. Defines the length of the FAB.

DEV — Device characteristics field. A bitmap indicating various
characteristics of the device on which the file being referenced resides.

Following is a list of bits supported by VDS RMS:

5-176

—

DIR — Directory-structured device.

—

FOD — File-oriented device (disk and magnetic tape).

—

RND — Random access device.

—

SDI — Single directory device (master file directory only).

—

SQD — Sequential block-oriented device (magnetic tape).

$FAB

IFI — Internal file identifier field. Used to associate the FAB with an
internal access block.

MRS — Maximum record size.

ORG — File organization. Valid values for this field are:
—

REL — Relative file organization.

—

IDX — Indexed file organization.

—

SEQ — Sequential file organization.

Note: VDS RMS only supports operations on files having sequential
organization.

RAT — Record attributes. Indicates that special control information

has been attached to the records of a file. Refer to the VAX/VMS RMS
Reference Manual for a discussion of record attributes. It is unlikely that
a diagnostic program will make use of this field.
RFM — Record format. Indicates the format of the records in the file.

Possible values for this field are:
—

FIX — (FAB$C_FIX) Fixed length record format.

—

VEFC — (FAB$C_VEC) Variable length with fixed length control
record format.

—

VAR — (FAB$C_VAR) Variable length record format.

—

UDF — (FAB$C_UDF) Undefined record format.

—

If the file is on the console medium (RT-11 format), the RFM code

returned by the $OPEN service will be 4. There is no symbolic
repesentation for this value.

STS — Completion status code field. RMS services load this field with
a success or failure completion status before returning to the caller of

the service. The completion status code is also passed to the caller in
RO.
STV — Status value field. Sometimes used to pass additional status
information from a service to the caller.

5-177

$FAB

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

FAB Fields

Field and

Keyword

Name

Field Size

Description

Offset

ALQ

Longword

Allocation quantity

FABSL_ALQ

BID

Byte

Block identifier

FAB$B_BID

BKS

Byte

Bucket size

FAB$B_BKS

BLN

Byte

Block length

FAB$B_BLN

BLS

Word

Block size

FAB$W_BLS

CTX

Longword

Context

FAB$L_CTX

DEQ

Word

Default file extension

FABSW_DEQ

quantity

DEV

Longword

Device characteristics

FAB$L_DEV

DNA

Longword

Default file specification

FABSL_DNA

string address

DNS

Byte

Detaulf file specification

FAB$B_DNS

strinng size

FAC

Byte

FNA

Longword

File access

FAB$B_FAC

File specification string

FABSL_FNA

addr.

FNS

Byte

File specification string size =~ FAB$B_FNS

FOP

Longword

File-processing options

FAB$L_FOP

FSzZ

Byte

Fixed control area size

FAB$B_FSZ

IF!

Word

Internal file identifier

FAB$W_IFI

MRN

Longword

Name block address

FAB$L_MRN

MRS

Word

Maximum record size

FAB$W_MRS

NAM

Longword

Name block address

FAB$L_NAM

ORG

Byte

File organization

FAB$B_ORG

RAT

Byte

Record attributes

FAB$B_RAT

RFM

Byte

Record format

FAB$B_RFM

RTV

Byte

Retrieval window size

FAB$B_RTV

SDC

Longword

Spooling device

FAB$L_SDC

characteristics

SHR

Byte

File sharing

FAB$B_SHR

STS

Longword

Completion status code

FAB$L_STS

STV

Longword

Status values

FAB$L_STV

XAB

Longword

Extend attribute block

FABSL_XAB

address

5-178

$FAB

[

MACRO-32
EXAMPLE
$FAB

FAB_BLOCK:

DNM=<.EXE>,
FAC=BIO,

FNA=FILE_NAME,

FNS=FILE_NAME
SIZE

BLISS-32

EXAMPLE
OWN

FAB_BLOCK

$FAB

(FAC=GET,

FNM='EVXYZ.DAT');

5-179

SFAB_INIT

SFAB_INIT—S$FAB_STORE
The $FAB_STORE and $FAB_INIT macros can be used to load FAB
fields at run time. The $FAB_STORE macro is used for MACRO-32
programs. The $FAB_INIT macro is used in BLISS-32 programs. Refer to
the discussion of the $FAB macro for a description of FAB fields.

BLISS-32

$FAB_INIT

FAB=fab=address,
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-adadr;
e

NOTES

Refer to the discussion of the $FAB macro for descriptions of input
parameters. With the exception of FAB_address, all parameters are

optional.
e

BLISS-32

EXAMPLE
OWN

IN_FAB:

$SFAB_INIT

$FAB

(FAC=GET)

(FAB=IN_FAB,
FNM='FILE1.DAT',
FOP=RWO)
;

5-180

SFAB_STORE

$FAB_STORE—SFAB_INIT
The $FAB_STORE and $FAB_INIT macros can be used to load FAB
fields at run time. The $FAB_STORE macro is used for MACRO-32
programs. The $FAB_INIT macro is used in BLISS-32 programs. Refer to
the discussion of the $FAB macro for a description of FAB fields.

MACRO-32

SFAB_STORE

FAB =fab-address,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
NOTES

Refer to the discussion of the $FAB macro for descriptions of input
parameters. With the exception of FAB_address, all parameters are
optional.

MACRO-32

EXAMPLE
IN_FAB:

$FAB_STORE

SFAB

FAB=IN_FAB,
FNM=<FILE1l.DAT>,

XAB=XABFHC_ADDR

5-181

$FAO

$FAO—S$SFAOL
The Formatted ASCIl Output ($FAQO) system service provides a means by
which complex messages can be formatted into ASCII character strings.

This macro can be used to:
*

Insert variable character string data into an output string.

Convert binary values into the ASCII representations of their decimal,
hexadecimal, or octal equivalents and substitute the results into an

output string
The system service constructs an output string by referring to formatted

ASCII output (FAO) directives contained in a ‘‘control string’’ and using
those directives to operate on the contents of value parameters.
The $FAOL macro performs the exact same function as the $FAO macro,

but allows the specification of an address of a parameter list instead of
requiring each parameter to be listed explicitly in the macro call.

MACRO-32

$FAO_x ctrstr
$FAOL_x ctrstr

BLISS-32

[outlen], outbuf, [p1], [02], ...[pNn]
[outlen], outbuf, prmist

$FAOQO

(ctrstr, [outlen], outbuf, [p1], [P2], ...[on]);)

$FAOL

(CTRSTR =ctrstr, [OUTLEN = outlen],
OUTBUF = outbuf, PRMLST = prmist);)

ARGUMENTS

ctrstr

Address of a character string descriptor (see Section 5.3) pointing to the
“control string.”” The control string contains a set of Formatted ASCII
Output (FAO) directives. These directives are described in the notes of the

$DS_PRINTx macros.

outlen
Address of a word to receive length of output string constructed by the
service routine.

outbuf
Address of a character string descriptor (see Section 5.3) pointing to the
output buffer. The fully formatted output string is placed in this buffer.

p1 through pn ($FAO only)

0 to 20 directive parameters, contained in longwords. Depending on the

corresponding FAO directive, a parameter may be a value that is to be

converted, the address of a string that is to be inserted, a length, or an

argument count. Parameters are listed in the order they are referenced by

the control string. If more than 20 parameters must be specified, use the
$FAOL macro.

5-182

$FAO

prmist ($FAOL only)

Address of a list of longwords containing the directive parameters. The
list may be of any length. It may be an already existing data structure from

which certain values are to be extracted.

RETURN

STATUS

SS$_NORMAL

Service successfully completed.

SS$_BUFFEROVF

Service successfully completed, but the size of the
output string was greater than the maximum allowed

SS$_BADPARAM

An invalid FAO directive was specified in the control

and was truncated (see notes).
string.

NOTES

If the formatted output string is to be displayed on the user’s terminal, it is
important to select the proper $DS_PRINTx macro to cause the message to

be displayed. Refer to the description of the $DS_PRINTx macros.

MACRO-32
EXAMPLE
VALUES

200

(DEC)

This example will create the following string:
0000012C

FAODESC:

(HEX)

-400

(SIGNED)

;Descriptor for output buffer
.LONG 80

;Output buffer

. LONG FAOBUF

:Address of

length

buffer

FAOBUF:

.BLKB

: 80-character

FAOLEN:

.BLKW

;Word

buffer

to receive

length of

output

CNTRL_STRING:

.ASCID

VALl:

.LONG 200

VAL2:

.LONG 300

VAL3:

.LONG -400
$FAO_S

/VALUES

!UL

(DEC)

!XL

CTRSTR=CNTRL_STRING,
OUTBUF=FAODESC,
OUTLEN=FAOLEN,

P1=VALl,

(HEX)

P2=VAL2,

P3=VAL3

{SL

(SIGNED)/

$FAO

“

BLISS-32

EXAMPLE
OWN
FAOBUF

VECTOR

[80,

FAODESC

VECTOR

[2]

FAOLEN

VECTOR

VAL1

VECTOR

VAL?2

: VECTOR

VAL3

INITIAL

BYTE],

(80,

[1,

FAOBUF),

WORD],

INITIAL

(200),

INITIAL

(300),

VECTOR
INITIAL

(-400);

BIND

UPLIT

(%ASCID

$FAO

'VALUES

!UL

(DEC)

(CNTRL_STRING,
FAODESC,
FAOLEN,

VAL1l,

5-184

VAL2,

VAL3);

!XL

(HEX)

!SL

(SIGNED)');

$FAOL

$FAOL—S$FAO
The Formatted ASCII Output ($FAQ) system service provides a means by
which complex messages can be formatted into ASCII character strings.
This macro can be used to:

Insert variable character string data into an output string.

Convert binary values into the ASCII representations of their decimal,
hexadecimal, or octal equivalents and substitute the results into an
output string

The system service constructs an output string by referring to formatted
ASCI| output (FAO) directives contained in a ‘‘control string’’ and using
those directives to operate on the contents of value parameters.

The $FAOL macro performs the exact same function as the $FAO macro,
but allows the specification of an address of a parameter list instead of
requiring each parameter to be listed explicitly in the macro call.

MACRO-32

$FAO_x ctrstr [outlen], outbuf, [p1], [p2], ...[pN]
$FAOL_x ctrstr [outlen], outbuf, prmist

BLISS-32

$FAOQO (ctrstr, [outlen], outbuf, [p1], [P2], ...[pN]);)
$FAOL (CTRSTR =ctrstr, [OUTLEN = outlen],
OUTBUF = outbuf, PRMLST = prmist),)

ARGUMENTS

ctrstr
Address of a character string descriptor (see Section 5.3) pointing to the
“’control string.”” The control string contains a set of Formatted ASCII
Output (FAO) directives. These directives are described in the notes of the
$DS_PRINTx macros.

outlen

Address of a word to receive length of output string constructed by the
service routine.

outbuf

Address of a character string descriptor (see Section 5.3) pointing to the
output buffer. The fully formatted output string is placed in this buffer.

p1 through pn ($FAO only)

0 to 20 directive parameters, contained in longwords. Depending on the
corresponding FAO directive, a parameter may be a value that is to be
converted, the address of a string that is to be inserted, a length, or an
argument count. Parameters are listed in the order they are referenced by
the control string. If more than 20 parameters must be specified, use the
$FAOL macro.

5-185

$FAOL

prmist (8FAOL only)
Address of a list of longwords containing the directive parameters. The
list may be of any length. It may be an already existing data structure from
which certain values are to be extracted.

RETURN
STATUS

SS$_NORMAL

Service successfully

SS$_BUFFEROVF

Service successfully completed, but the size of the

completed.

comp

output string was greater than the maximum allowed

and was truncated (see notes).

SS$_BADPARAM

An invalid FAO directive was specified in the control
string.

NOTES

If the formatted output string is to be displayed on the user’s terminal, it is
important to select the proper $DS_PRINTx macro to cause the message to

be displayed. Refer to the description of the $DS_PRINTx macros.

MACRO-32

EXAMPLE
VALUES

200

This example will create the following string:

(DEC)

0000012C

FAODESC:

(HEX)

-400

;Descriptor
.LONG

;Output

(SIGNED)

for

buffer

. LONG

FAOBUF

;sAddress

FAOBUF:

.BLKB

;80-character

FAOLEN:

.BLKW

;Word

output

buffer

length

buffer
buffer

receive

length

output

CNTRL_STRING:

-ASCID
VAL1l:

.LONG

/VALUES

!UL

(DEC)

VAL2:

.LONG

300

VAL3:

.LONG

-400

$SFAO_S

CTRSTR=CNTRL_STRING,
OUTBUF=FAODESC,
OUTLEN=FAOLEN,

P1=VAL1l,

5-186

!XL

(HEX)

200

P2=VAL2,

P3=VAL3

!SL

(SIGNED)/

$FAOL

BLISS-32
EXAMPLE
OWN

BYTE],

VECTOR [80,
VECTOR [2]

FAOBUF
FAODESC

:
:

FAOLEN

: VECTOR [1,

VALl

VECTOR

VAL2

VECTOR

VAL3

VECTOR

INITIAL

INITIAL
INITIAL

(80,

FAOBUF),

WORD],

(200),

(300),
(-400);

BIND

UPLIT = (%ASCID ’'VALUES !UL (DEC)
$SFAO

!XL (HEX)

!SL (SIGNED)’);

(CNTRL_STRING,
FAODESC,
FAOLEN,

VAL1l, VAL2,

VAL3);

5-187

$DS_SFETCH

$DS_SFETCH
The $DS_S$FETCH macro is used in p-table descriptors. It will extract the
contents of a field within the p-table, and store the contents, right-justif
ied,
in the “‘value register’’ (see Section 3.2.3.3). It is possible to reference
a

device-dependent field that was filled with a previous $DS_$STORE macro,

or device-independent field that was filled by the VDS. The macro

can also

be used to facilitate temporary storage, by storing a value in the p-table

while the value register is needed for something else, then restoring

old value.

MACRO-32

$DS_SFETCH

offset, pos, size

BLISS-32

$DS_SFETCH

(OFFSET = offset, POS = pos,
SIZE = size);

ARGUMENTS

the

offset

The byte offset into the p-table of the field from which the contents are to
be fetched.

pos
Bit position of the field, relative to the beginning of the byte

specified by
“offset.”” If the field starts on a byte boundary, this value will
be 0.

size
Number of bits making up the field. The size cannot be larger than
32.

5-188

Code generated by macro (shown in Macro-32; Bliss-32 is equivalen
~X87

offset

«BYTE

pos

.BYTE

size

«BYTE

«WORD

Beginning

t):

Word

Bit position

NOTES

Bit

data

structure

FETCH directive
in word

field size

offset

$DS_SFETCH

MACRO-32
EXAMPLE
$DS_$FETCH OFFSET=HP$A_DVA,
$DS_$FETCH <~x40>,

POS=0,

SIZE=32

BLISS-32
EXAMPLE
$DS_$FETCH

(OFFSET=%FIELDEXPAND(HPSA_DVA,0),
POS=%FIELDEXPAND(HPS$A_DVA,1),
SIZE=%FIELDEXPAND(HPSA DVA,2));

$DS_$FETCH

(OFFSET=%X'40’,

POS=0,

SIZ=32);

5-189

$GET

$GET
The Get a Record service of RMS is used to read a record from a file. The
file must have been previously opened and connected with the $OPEN

and $CONNECT services, respectively. Records may be read from the file
sequentially or by the random-by-RFA method. These access methods are

discussed in Section 4.5, File Management.

MACRO-32

$GET

rab, [err], [suc]

BLISS-32

$GET

(RAB=rab, [ERR =err], [SUC = suc]);

ARGUMENTS

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 is in the RAB.)

err (user mode only)
Address of a routine to be executed on error return from the service.

suc (user mode only)
Address of a routine to be executed on successful return from the service.

RETURN

STATUS

RMS$_NORMAL

Service successfully completed.

RMS$_EOF

Attempt was made to read beyond end of file.

RMS$_FAB

The FAB block is invalid.

RMS$_IFI

The FAB’s IFI field is invalid.

RMSS$_ISI

The RAB’s 1Sl field is invalid.

RMS$_RAB

The RAB block is invalid.

RMS$_RER

Read error. (The device driver's return status will be

RMS$_RFA

Invalid RFA was specified in random-by-RFA mode.

in the STV field of the RAB.)

RMS$_RTB

Record retrieved was too big for the buffer provided,
and was truncated.

Note: For further details on return status values, refer to the VAX-11 RMS
Reference Manual.

5-190

$GET

NOTES

1 Table 5-5 lists the RAB fields used by the $GET service IN

STANDALONE MODE. For user mode, refer to the VAX-11 RMS

Reference Manual.

Table 5-5

RAB Fields Used by $GET (Standalone Mode)

Field Mnemonic

Field Name

Input:

IS!

Internal stream identifier.

RAC

Record access mode.

RFA

Record’s address. (Used only if RAC=RFA))

ROP

Record-processing options.

UBF

User record area address.

USz

User record area size.

Output:
RBF

Record address.

RFA

Record’s file address.

RSZ

Record size.

STS

Completion status code. (Also returned in RO).

STV

Status value. (See Return Status, above.)

MACRO-32
EXAMPLE
$SGET

RAB_ADDR

BLISS-32
EXAMPLE
$GET

(RAB=RAB_ADDR);

5-191

$DS_GETBUF

$DS_GETBUF
The $DS_GETBUF macro is used to obtain buffer space. In standalone
mode, the buffer space is allocated by the VDS from its free memory pool.
In user mode, the VDS calls the VMS $EXPREG system service (see the

VAX/VMS System Services Reference Manual for details).
The caller indicates the number of pages desired, and the service returns
the low and high addresses of the space allocated.

When the program no longer needs the allocated buffer space, it can be
returned to the free memory pool with the $DS_RELBUF macro.

MACRO-32

$DS_GETBUF_x

BLISS-32

$DS GETBUF

pagcnt, [retadr], [phyadr], [region]

(PAGCNT =pagcnt,
[RETADR
= retadr],
[PHYADR
= phyadi],
[REGION = region]);

ARGUMENTS

pagcent

Size (number of pages) desired for buffer.

retadr
Address of a 2-longword array to receive the virtual addresses of the low
and high buffer limits.

phyadr
Address of a 2-longword array to receive physical addresses of low and
high buffer limits. This parameter is only relevant in standalone mode.

region
Memory region from which caller wishes buffer space to be allocated.
Values are:

0: buffer allocated from P0 space (default).
1. buffer allocated from P1 space.
2: buffer allocated from system space.

In standalone mode, this parameter is only relevant if memory
management is turned on.

$DS_GETBUF

RETURN

STATUS

SS$_NORMAL

Buff

S§S$_ACCVIO

The “‘retadr’’

llocated

uffer space allocated.

array cannot be written by the caller.

User mode only.

SS$_EXQUOTA

The process exceeded its paging file quota. User
mode only.

SS$_ILLPAGCNT

Requested page count was less than 1.

SS$_INSFWSL

The process’s working set limit is not large enough
to accommodate the increased virtual address
space. User mode only.

S§S$_VASFULL

Insufficient virtual address space is available to fulfill
the buffer request. (See Note 4.)

RO =0

lllegal value was given for “‘region’’ parameter.

Standalone mode only.

NOTES

If P1 space is requested in user mode, the “‘retadr’” array will contain

the allocated space’s high address as its first element and the low
address as its second element.

In standalone mode, buffer space will always be allocated as contiguous
pages. If there is not a set of contiguous pages equal to the requested

buffer size, then the SS$_VASFULL status will be returned.
In standalone mode, buffer space is allocated starting at the lowest
available physical page.

If there are fewer pages available than the number requested, then the

number of pages available will be allocated. The beginning and ending
virtual addresses of this area will be placed in the ‘‘retadr’” array.
When the number of available pages is 0, the ““retadr’” and “‘phyadr”
arrays will contain address 0 as the low and high buffer limits.

Use the $DS_GETBUF service to allocate memory for an attached
process when the code to be executed is in a separate file. (Use

$DS_LOAD or RMS service to load the file into the buffer.)
In a multiprocessor environment, use the primary processor to make

all $DS_GETBUF (and $DS_RELBUF) calls.

5-193

$DS_GETBUF

e
e
R

MACRO-32
EXAMPLE
$DS_GETBUF_S

#10,

BUFLIMITS

;Ask

for

10 pages.

BLISS-32
EXAMPLE
$DS_GETBUF

tAsk for

5 pages

(PAGCNT=5,
RETADR=BUF_LIMITS,

REGION=1);

5-194

in Pl

space.

$SGETCHN

$GETCHN
The Get I/0O Channel Information system service returns information
about a device to which an /O channel has been assigned. Two sets of
information can be returned:
*

The primary device characteristics

The secondary device characteristics

In most cases, the two sets of characteristics are identical. However, there
are three instances in which the primary and secondary characteristics are
not the same:

If the device is associated with a mailbox, the primary characteristics

are those of the device and the secondary characteristics are those of
the mailbox.

|f the device is a spooled device, the primary characteristics are those
of the intermediate device and the secondary characteristics are those
of the spooled device.

|f the device is a logical link in a network, the secondary characteristics
describe the link.

If the diagnostic program is running in standalone mode, the primary and
secondary characteristics will always be identical.
This service is not available to level 3 programs.
Note:

It is recommended that all newly developed level 2R programs use the
VMS $GETDVI service instead of SGETCHN, because of plans to remove
support of SGETCHN from VMS. Refer the VAX/VMS System Services
Reference Manual.

MACRO-32

SGETCHN

chan, [prilen], [pribuf], [scdlen], [scdbuf]

BLISS-32

$SGETCHN

CHAN =chan, [PRILEN = prilen],
[PRIBUF = pribuf], [SCDLEN = scdlen],
[SCDBUF = scdbuf]

5-195

$GETCHN

ARGUMENTS

chan

Number of the 1/0O channel assigned to the device.

prilen
Address of a word to receive the length of the primary characteristics.

pribuf
Address of a character string descriptor (see Section 5.3) pointing to buffer
that will receive primary characteristics. The default is 0, implying no

buffer.

scdlen
Address of a word to receive the length of the secondary characteristics.

scdbuf
Address of a character string descriptor (see Section 5.3) pointing to buffer
that will receive secondary characteristics. The default is 0, implying no

buffer.
L

RETURN

STATUS

SS$_BUFFEROVF
_

full

leted. D

ervice successfully completed.

Device information

overflowed the buffer(s), so information was
truncated.

SS$_NORMAL

Service successfully completed.

SS$_ACVIO

A buffer descriptor cannot be read by the caller, or
a buffer or buffer length cannot be written by the
caller. User mode only.

SS$_IVCHAN

An invalid channel number was specified; that is, a
channel number of 0 or a number greater than the
number of channels available.

SS$_NOPRIV

The specified channel is not assigned or was
assigned from a more privileged access mode.
User mode only.

5-196

$GETCHN

NOTES

In standalone mode, the device characteristics are placed into the
specified buffer in the format illustrated in Figure 5-7.

Figure 5-7

Device Characteristics Buffer (Standalone Mode)

16 15

DEVICE CHARACTERISTICS

BUFFER SIZE

TYPE

CLASS

DEVICE-DEPENDENT INFORMATION
UNIT NUMBER

ZK-4796-85

Following the unit number is an ASCII string representing the device’s
generic name.

The ““device characteristics’” and ‘’device dependent information”
fields are the same as they are for user mode. Refer
to the VAX/VMS
I/0 User’s Guide for details.

In user mode, the device characteristics are placed into the specified
buffers in the format detailed in the VAX/VMS 1/0 User’s Guide.

Refer to the VAX/VMS System Services Reference Manual for privilege
restrictions and other notes on the use of this service in user mode.

MACRO-32
EXAMPLE
CHANNUM: .WORD

BUFFER:

.LONG DIBSK_LENGTH
.LONG

BBUF':

BBUF

.BLKB DIBSK_LENGTH

$GETCHN_S

CHANNUM, , BUFFER

5-197

$GETCHN

L
R

BLISS-32
EXAMPLE
OWN

CHANNUM

VECTOR

[WORD}],

BBUF

VECTOR

[DIBSK_LENGTH,

BUFFER

VECTOR

[2]

INITIAL

$GETCHN

5-198

(DIBSK_LENGTH,

BYTE],

BBUF),

(CHAN=.CH
, PRIBUF=BUFFER);
ANNUM,

$DS_GETTERM

$DS_GETTERM
The Get Terminal Characteristics service can be used to obtain the type
and characteristics of the user’s terminal.

MACRO-32

$DS_GETTERM_x

BLISS-32

$DS_GETTERM

ARGUMENTS

termchar
(TERMCHAR =termchar),

termchar

Address of a quadword to receive the terminal characteristics. See Note 1

for the format of the characteristics.

RETURN

STATUS
NOTES

Service successfully

SS$_NORMAL

completed.

The terminal characteristics are returned in a quadword with fields in
Figure 5-8.

Figure 5-8

Format of Terminal Characteristics
3

PAGE WIDTH

TYPE

PAGE

TERMINAL

LENGTH

CHARACTERISTICS

CLASS

ZK-4797-85

Values for the “‘type” field and ‘““terminal characteristics”’ are defined
by the $TTDEF macro of VMS.

Note: In standalone mode, only the ““type’” and ‘‘terminal characteristics”
fields are supplied. For terminal characteristics, only TTSM_SCOPE is
provided. In user mode, all fields and all terminal characteristics are
supplied.

$DS_GETTERM

A
Sy

MACRO-32
EXAMPLE
TERM_INFO:

.BLKQ

$DS_GETTERM_S

TERM_INFO

BLISS-32

EXAMPLE
OWN
TERM_INFO

$DS_GETTERM

5-200

VECTOR

[2];

(TERM_CHAR=TERM_INFO);

$GETTIM

SGETTIM
The Get Time system service furnishes the current system time in 64-bit
format. The time can be converted to ASCII by using the $ASCTIM service.

MACRO-32

SGETTIM

timadr

BLISS-32

$GETTIM

(TIMADR =timadr),

ARGUMENTS

RETURN

STATUS

timadr

Address of a quadword that is to receive the current time in 64-bit format.

SS$_NORMAL
SS$_ACCVIO

fully compierer
leted

ervice successfully

completed.

The quadword to receive the time cannot be written
by the caller. User mode only.

MACRO-32
EXAMPLE
$GETTIM_S

TIME

BLISS-32
EXAMPLE
SGETTIM

(TIMADR=TIME);

5-201

$DS_GPHARD

$DS_GPHARD
The Get Hardware Parameter Table system service will provide the caller
with the address of the p-table for the logical unit specified. The p-table’s
contents can then be accessed by the caller.

The macro is used in a

diagnostic program'’s initialization code, discussed in Section 3.5.

MACRO-32

$DS_GPHARD_x

devnam, adrloc

BLISS-32

$DS_GPHARD_x

(UNIT =devnam, RETADR = adrloc);

ARGUMENTS

devnam

The logical unit number of the device whose p-table is being requested.
Minimum value is 0. Maximum value is determined by VDS, depending
on the number of selected device units testable by caller. (See notes.)

adrloc
Address of longword to receive p-table base address.

RETURN

STATUS

SS$_NORMAL
DS$_ERROR

full

ervice successfully

leted ,

completed.

comp

The argument list does not contain exactly two
arguments.

The specified logical unit number is too large.

NOTES

If ““devnam’’ was initialized to 0 and incremented after each issuance

of the $DS_GPHARD macro, then the DS$_ERROR return status simply
means that the p-tables for all selected, testable device units have been

referenced. ““Devnam”’ should be reinitialized to 0. See Section 3.5,
Initialization Code, for details.

5-202

$DS_GPHARD

MACRO-32
EXAMPLE
INCL

LOG_UNIT

$DS_GPHARD_S LOG_UNIT,

P_TABLE

BLISS-32
EXAMPLE
LOG_UNIT =

.LOG_UNIT +

$DS_GPHARD (UNIT=.LOG_UNIT,

RETADR=P_TABLE} ;

5-203

$DS_HALTATTACHED

$SDS_HALTATTACHED
Use the Halt Attached CPU system service to stop program execution in
an attached processor in a multiprocessor environment (exit the IDLE state

and enter the HALT state, see Figure 4-8). In order to use this service,

you must bootstrap the processor with the $DS_BOOTATTACHED service.

MACRO-32

$DS_HALTATTACHED_x

BLISS-32

$DS_HALTATTACHED

ARGUMENTS

unit

(UNIT =unit);

unit
Logical unit number of the CPU to be halted.

RETURN

ST ATUS

DS$_NORMAL

Service Sfj'ccessfl':"y cor.npleted.

DS$_ILLUNIT

The specified logical unit number is too large.

DS$_INVCPU

The specified processor is the primary processor.

DSS$_INIT_FAIL

The processor failed to send console prompt

(VAX 82XX/83XX only).

In order to restart a halted processor, you must reboot
using the $DS_BOOTATTACHED service and then use the

$DS_STARTATTACHED service.

Once you halt a processor, the EXAMINE and DEPOSIT commands are
unavailable until you reboot using the $DS_BOOTATTACHED service.

$DS_HALTATTACHED should be used in the clean-up code, to place

each attached processor into a known, static state after testing.

5-204

$DS_HALTATTACHED

[

MACRO-32
EXAMPLE
$DS_HALTATTACHED_S

LOG_UNIT

BLISS-32
EXAMPLE
$DS_HALTATTACHED

(UNIT =

,LOG_UNIT);

5-205

$DS_HEADER

$DS_HEADER
The $DS_HEADER macro generates the diagnostic program header. The
header must be situated so that its starting address is virtual 512 (200
hexadecimal). (The diagnostic program may not use address space below

the header.)

MACRO-32

$SDS_HEADER

<pname>, rev, [update], [nunit]

BLISS-32

$DS_HEADER

(PNAME = ‘pname’, REV =rey,
[UPDATE = update], [NUNIT = nunit]);

ARGUMENTS

pname
Character string representing the program’s name. This string is displayed
on the user’s terminal when the program is started.

Note: In BLISS-32, if a (") character is to be included in the string, it must be
included twice, as in

PNAME ="MARY’’'S PROGRAM'.

The string should contain the following information:

The program’s name (EVKAC, EVRAD, and so on)

The program’s level (2, 2R, or 3)

The type of program (logic test, function test, or exerciser; see

Chapter 1)
*

The types of devices that the program can test

Refer to the examples below.

rev
Numeric value representing the program revision level.

update
Numeric value representing the program patch level. The default is 0.

nunit
Numeric value representing the maximum number of device units that can
be tested by the program. The default is 0.

Refer to the templates in Appendix A to determine the exact location

of the $DS_HEADER macro in relation to other macros appearing in

the program. The arrangement of macros depends on whether the
program is written in MACRO-32 or BLISS-32.

$DS_HEADER

MACRO-32
EXAMPLE
$DS_HEADER <Dz11

LINE ASYNC

MUX

TEST>,

REV

01,

UPDATE

NUNIT

BLISS-32
EXAMPLE
$DS_HEADER
(PNAME

$DS_HEADER

‘Dz11
<DZ11l

8
8

LINE ASYNC
LINE ASYNC

MUX
MUX

TEST’,
TEST>,

REV =
REV =

01,
01,

UPDATE
UPDATE

=
=

O,
0,

NUNIT =
NUNIT

8);
8

. SAVE

L$L_HEADLENGTH:

.PSECT

S$HEADER,

PAGE,

.LONG

A_HEADEND -.

L$L_ENVIRON:

.LONG

S$SENV

L$L_REV:

.LONG

L$L_UPDATE:

.LONG

L$SA_NAME:

NOEXE,

NOWRT

; LENGTH OF HEADER DATA BLOCK.
;

PROGRAM ENVIRONMENT.

;

PROGRAM REVISION

;

DIAGNOSTIC

ENGR PATCH ORDER.
LOCATION AFTER

.ADDRESS T_NAME

; PROGRAM NAME TEXT ADDRESS.

L$A_LASTAD:

.ADDRESS

LASTAD

;

FIRST

L$A_DTP:

.ADDRESS

DISPATCH

;

TEST

L$A_DEVP:

.ADDRESS AL_DEVTYP

;

DEVICE

TYPE

L$A_DREG:

.ADDRESS

;

DEVICE

L$SL_UNIT:
L$SA_ICP:

.LONG
.LONG

DEV_REG

0[5]

FREE

LEVEL.

DISPATCH

TABLE

LIST

PROGRAM.

POINTER.

; NUMBER OF UNITS THAT CAN BE TESTED.

.ADDRESS INITIALIZE

; INITIALIZATION CODE POINTER.

L$A__CCP:

.ADDRESS

CLEANUP

;

CLEAN-UP CODE POINTER.

L$A_REPP:

.ADDRESS

SUMMARY

;

SUMMARY REPORT

L$A_STATAB:

.ADDRESS

;

STATISTIC TABLE POINTER.

L$I_ERRTYP:

.LONG

L$A_TSTCNT:

.ADDRESS

0
SECTION

;

LIST

OF TYPES
OF

CODE

POINTER.

$ERRSOFT AND

$ERRHARD.

SECTION NAME ADDRESSES.

A_HEADEND:

T NAME:

LASTAD:

.ASCIC

\DZ1l

LINE ASYNC

.PSECT,

_LAST,

.PSECT,

SYSTCNT,

MUX

TEST/

PAGE
NOEXT,

NOWRT,

OVR,

LONG

5-207

$DS_HELP

$DS_HELP
The Display Help Text service can be used to display text contained in a
help file. Help files are described in Chapter 6. This service is functionally
identical to the VDS command HELP.

$DS_HELP_x

BLISS-32

$DS_HELP

ARGUMENTS

keylst

(KEYLST
= keylst);

MACRO-32

Address of a character string descriptor (see Section 5.3) that points to a list
of help file keywords. This list is exactly equivalent to the keywords that
would be included as parameters to the HELP command (see the VAX/DS
Diagnostic Supervisor User’s Guide). To reference the help file EVXYZ HLP,
for diagnostic program EVXYZ, the first keyword in the list must be EVXYZ.

RETURN

The return status may be any status that may be returned from the\$OPEN,

STATUS

these services.

$CONNECT, $READ, or $CLOSE services of RMS. Refer to descriptions of

T
|

MACRO-32

EXAMPLE
KEYSTRING:

.ASCID

/EVXYZ MANUAL OPTIONS/

$DS_HELP_S

KEYSTRING

BLISS-32
EXAMPLE
BIND KEYSTRING = UPLIT

$DS_HELP

5-208

(%ASCID

(KEYLST=KEYSTRING);

’'EVXYZ MANUAL OPTIONS’);

$DS_SHEX

$DS_SHEX
The $DS_$HEX p-table descriptor macro is used to read a value from
the ATTACH command line. If no more parameters are available on the

command line, or if the next parameter is not a hex value, the user will be
prompted with the prompt text value. The value that is read is left in the
“value register’’ (see Section 3.2.3.3) for use by a $DS_$COMPLEMENT,

$DS_$STORE, or $DS_$CASE statement.

MACRO-32

$DS_SHEX

<prompt>, low, high

BLISS-32

$DS_SHEX

(PROMPT
= ‘prompt’, LOW =low,
HIGH = high);

ARGUMENTS

prompt

Character string that is to be printed as a prompt to the user. This prompt
will be used if the ATTACH command line does not contain the required
value.

low
The low limit for the value. If the value given is lower than this, an
error message followed by the prompt message will be displayed. For
MACRO-32, the default radix for this value is hexadecimal. For BLISS-32,
the default radix is decimal.

high
The high limit for the value. If the value given is higher than this, an
error message followed by the prompt message will be displayed. For
MACRO-32, the default radix for this value is hexadecimal. For BLISS-32,
the default radix is decimal.

NOTES

Code generated by macro (shown in Macro-32; Bliss-32 is equivalent):
.BYTE

~X84

;

Beginning

.ASCIC

\prompt\

Prompt

.LONG

~“X<low>

Low limit

. LONG

~X<high>

;

High

HEX prompt

string

limit

5-209

$DS_SHEX

MACRO-32
EXAMPLE
$DS_SHEX <WCS

Last

address>,0,FFFO

BLISS-32
EXAMPLE
$DS_SHEX

5-210

(PROMPT='WCS

Last

address’,

LOW=0,

HIGH=%X'FFFO0');

$HIBER

$HIBER
The Hibernate system service allows a diagnostic program to make
itself inactive. A hibernating program can be interrupted to process
asynchronous events. After the diagnostic program’s event handler has
been executed, the program will be returned to its state of hibernation.
This state will remain in effect until the program is awakened with the
$WAKE system service.

MACRO-32

$HIBER_S
Note: (Only the _S form of the macro is supported.)

BLISS-32

SHIBER;

[

RETURN

ST ATUS
|-

SS$_NORMAL
O

NOTES

Service successfully completed.

In standalone mode, the only way for a hibernating program to be
awakened is for an event handler (for example, an AST routine or
interrupt service routine) to call the $WAKE service.

In user mode, a hibernating process may be awakened by another
process. Refer to the VAX/VMS System Services Reference Manual for
details.

In a multiprocessing environment, $HIBER cannot be called from
within a block of code delineated by the $DS_BGNATTACHED and
$DS_ENDATTACHED macros.

MACRO-32
EXAMPLE
$HIBER_S

BLISS-32
EXAMPLE
$HIBER;

5-211

$DS_HPEO_DECL

$DS_HPEO_DECL
The $DS_HPEO_DECL is used for BLISS-32 programs.
Symbols defined are:
HPEST_DEVICE

-~ An ASCII string representing a device if
name$ggan

HPESA_EPB

— Address

the extended p-table

HP$SW_EXT_DRIVE - The unit number of

BLISS-32

in the

format.

$SDS_HPEO_DECL

block.

the device.

($DS_xxxx_DEF);

FORMAT

ARGUMENTS

NOTES

$DS_xxxx_DEF

““xxxx”’ represents the name of the device for which p-table fields are to be
defined, such as $DS_HPEQO_DECL ($DS_KA_DEF).

These symbols should be used as offsets from the base of the extended

p-table. The following code shows how to compute the address of the
EPB.
MOVL

PTABLE, R2

MOVZWL
ADDL2

HPSWSIZE(R2),
R2,R3

;

Address of

;
;

Move size of p-table into R3
Compute end of extended p-table

SUBL2
MOVL

$#4,R3

Address of EPB stored here

(R3) ,R4

;

Move address

ptable in R2

into R4

Refer to Section 3.2.4, Referencing Extended P-Tables from a
Diagnostic Program.

BLISS-32
EXAMPLE
$DS_HPEO_DECL

5-212

($DS_KA_DEF);

$DS_HPEODEF

$DS_HPEODEF
The $DS_HPEODEF macro defines (for MACRO-32 programs) the

symbolic names of the device-independent fields of an extended p-table.
Symbols defined are:
HPEST_DEVICE

- An ASCII

string representing

a device if

in the

name$ggan format.

HPES$A_EPB

~ Address of the extended p-table block.

HPSW_EXT_DRIVE - The unit

MACRO-32

$DS_HPEODEF

number of

the device.

[gbl]

FORMAT

ARGUMENTS
NOTES

gbl

an be LOCAL or GLOBAL

These symbols should be used as offsets from the base of the extended

p-table. The following code shows how to compute the address of the
EPB.
MOVL

PTABLE,R2

MOVZWL

HPS$SWSIZE(R2),

;

Address

;

Move size of

ADDL2

R2,R3

Compute

end of

SUBL2

#4,R3

;

Address

MOVL

(R3),R4

;

Move

ptable in R2
p-table

into R3

extended p-table

EPB stored here

address

into R4

Refer to Section 3.2.4, Referencing Extended P-Tables from a
Diagnostic Program.

MACRO-32
$DS_HPEODEF GLOBAL

5-213

$DS_HPO_DECL

$DS_HPO_DECL
The $DS_HPO_DECL macro defines (for BLISS-32 programs) the
sysmbolic names of the device-independent fields of a p-table.

Symbols defined are:
HP$Q DEVICE

Quadword

HPS$W_SIZE

Total

descriptor

device name

length of p-table

HP$B_FLAGS

Initialization

HP$B_DRIVE

Unit

flags

number

HP$T_DEVICE

Start

HP$A_DEVICE

Hardware

device

name

address

HP$A_DVA

Base of

address

HPSA_LINK

Address

string
device

space assigned to device
for device’s link

p-table

HP$W_VECTOR

Device’s

vector

HPST_TYPE

Start

HP$A_DEPENDENT

Start

counted string for device type
device-dependent portion of p-table

Device-dependent

fields

BLISS-32

$DS_HPO_DECL

ARGUMENTS

$DS_xxxx_DEF

NOTES

These symbols should be used as offsets from the base of the p-table.
For example, if the p-table base address was placed in R2, the vector

($DS_xxxx_DEF),

“xxxx"’ represents the name of the device for which p-table fields are to be
defined, such as $DS_HPO_DECL ($DS_KA_DEF).

field could be referenced as HP$W_VECTOR(R2). Refer to Section 3.2.4,
Referencing P-Tables from a Diagnostic Program.

BLISS-32

EXAMPLE
$DS_HPO_DECL

5-214

($DS_KA_DEF)
;

$DS_HPODEF

$DS_HPODEF
The $DS_HPODEF macro defines (for MACRO-32 programs) the symbolic
names of the device-independent fields of a p-table.

Symbols defined are:
HP$Q_DEVICE
HP$W_SIZE

Quadword descriptor of device name
Total length of p-table

HPSB_DRIVE

Unit number

HP$B_FLAGS

HPS$T_DEVICE
HP$A_DEVICE

HP$A_DVA
HP$A_LINK

HP$W_VECTOR

HPST_TYPE
HPS$A_DEPENDENT

Initialization flags

- Start of device name string
- Hardware address of device

Base of address space assigned to device
Address of p-table for device’s link
Device’s vector

Start of counted string for device type
Start of device-dependent portion of p-table

Device~dependent fields

MACRO-32

$DS_HPODEF

ARGUMENTS

gbl

NOTES

[gbl]

Can be LOCAL or GLOBAL

These symbols should be used as offsets from the base of the ptable. For example, if the p-table base address was placed in R2, the
vector field could be referenced as HP$W_VECTOR(R2). Refer to
Section 3.2.4, Referencing P-Tables from a Diagnostic Program.

MACRO-32
EXAMPLE
$DS_HPODEF GLOBAL

5-215

$DS_SINITIALIZE

$SDS_SINITIALIZE
The $DS_S$INITIALIZE p-table descriptor macro must be the first macro in
every p-table descriptor. It is used to indicate the device type, the p-table’s
total size, the maximum number of units allowed by the hardware, and the

name of the device driver required for a level 2 diagnostic program to
reference the device.

MACRO-32

$DS_SINITIALIZE

device, length, max, driver

BLISS-32

$DS_SINITIALIZE

(DEVICE =device,
LENGTH =length, MAX = max,
DRIVER = driver);

ARGUMENTS

device

Character string representing the device type of the hardware being
described by the p-table, such as RK611, RK06, RM03, RH780, and so

on. The string specified here will be the string that the user must type as
the first argument to the ATTACH command, as in ATTACH RK611.

length
The length (in bytes) of the p-table that is to be created. The length
includes both the device-independent and the device-dependent fields.
Generally, a symbolic name for this value is created with a $DEF macro

during memory allocation specifications, as illustrated in Section 3.2.2.

max
The maximum number of units that can exist. This number is controlled by
the hardware design. For example, the number would be 8 for an RK07,
since that is the maximum number of RK07 drives that can exist on an

RK711 controller.

Some devices, such as controllers and adapters, are not assigned a unit
number. For these cases, “‘max” should be 0. If this value is greater

than 0, and if the $DS_$NAME macro is not used, the device’s generic
name will be required to contain a unit number. If, on the other hand, the

$DS_$NAME macro is used, then whether or not a unit number must be

typed is controlled by the $DS_$NAME statement.

The default value for ““max’’ is 0.

driver
The name of the QIO driver (if any) needed by level 2 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 to the string EVQ and followed by the file type
.EXE. Thus, the driver’s filename is EVQdn.EXE.

$DS_SINITIALIZE

—
5

Code generated by macro (shown in Macro-32; Bliss-32 is equivalent):
\Device\

-.BYTE

Length

Length of

.BYTE

Max_Units

ASCIC device type

.ASCIC

Maximum unit

«WORD

~A"Driver"

TMo

.BYTE

~X80

NOTES

p-table
number

Driver suffix
End of initialization statement

MACRO-32
EXAMPLE
$DS_SINITIALIZE

DEVICE=DMC11, LENGTH=HP$K_DMC11_LEN,

DRIVER=<XM>

$DS_SINITIALIZE

DEVICE=DW780,

LENGTH=HPS$K_DW780_LEN,

MAX=3

$DS_SINITIALIZE

RK611,

HPSK_RK611_LEN,

BLISS-32
EXAMPLE
$DS_SINITIALIZE

(DEVICE='DMCil’,
LENGTH=HP$K_DMC11_LEN,
DRIVER='XM’);

$DS_SINITIALIZE

(DEVICE='DW780°’,

LENGTH=HP$K_DW780_LEN,
MAX=3);

$DS_SINITIALIZE

(DEVICE='RK611'’,

LENGTH=HP$K_RK611_
LEN);

5-217

$DS_INITSCB

$SDS_INITSCB
The Initialize System Control Block system service will load the VDS

default values into all vectors within the SCB. It can be used to restore
VDS exception and interrupt handling to all vectors if the diagnostic
program has previously defined its own handlers using the $DS_SETVEC
service.

This system service is only available to level 3 diagnostic programs.

MACRO-32

$DS_INITSCB_x

BLISS-32

$DS_INITSCB;

“

g‘E;'lrjgg
NOTES

SS$_NORMAL
1

In a multiprocessing environment, $DS_INITSCB only alters the SCB

of the primary process.

MACRO 32

EXAMPLE
$DS_INITSCB_S;

BLISS-32

EXAMPLE
$DS_INITSCB;

5-218

Service successfully completed.

$DS_INLOOP

$DS_INLOOP
The $DS_INLOOP program control macro can be used to determine
if a program loop is being executed. Program looping is discussed in
Section 3.10.

MACRO-32

$DS_INLOOP_x

BLISS-32

$DS_INLOOP;

RETURN

STATUS

DS$_NORMAL
DS$:ERROR

A program loop is being executed

A program loop is not being executed.

MACRO-32
EXAMPLE
$DS_INLOOP_S

BLISS-32
EXAMPLE
$DS_INLOOP;

5-219

$DS_LOAD

$DS_LOAD
The $DS_LOAD system service can be used for reading a file into a buffer
area. This service may be employed when the full range of processing
options provided by RMS is not needed. (The $DS_LOAD service uses
RMS to implement its functionality.)

MACRO-32

$DS_LOAD_x

BLISS-32

$DS_LOAD

file, default, length, address, retlen,
retrec, [vbn]

(FILE =file, DEFAULT
= default,
LENGTH = length, ADDRESS = address,
RETLEN =retlen, RETREC =retrec,
[VBN =vbn]),

ARGUMENTS

file
Address of a quadword descriptor (see Section 5.3) describing a character
string that represents the name of the file to be loaded. The filename
format is:
NODE::DEV:[DIRECTORY]FILENAME.EXT;VER.
If any fields of the filename are missing, they will be filled in with fields

specified by the ““default” parameter.

default
Address of a quadword descriptor (see Section 5.3) describing a character
string that represents the default fields for the filename.

length
Size, in bytes, of 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.

5-220

$DS_LOAD

retrec

Address of a longword to receive RMS file attributes of the file. The first
word of the longword will contain the FAB MRS (maximum record size)
field. The third byte will contain the FAB RFM (record format) field. The
fourth byte will contain the FAB FSZ (fixed header size) field. Refer to the
discussion of the $FAB macro for descriptions of these fields.

vbn
Virtual block number. This is the number of the first virtual block to be
read. The default value is 1, which will cause reading to begin with the first
block of the file.

The $DS_LOAD service can return any of the statuses associated with the
$OPEN, $CONNECT, $READ, $DISCONNECT, or $CLOSE services of

RETURN
STATUS

RMS. Refer to the descriptions of these services for lists of return statuses.

NOTES

In a multiprocessing environment, $DS_LOAD cannot be called from
within a block of code delineated by the $DS_BGNATTACHED and
$DS_ENDATTACHED macros.

MACRO-32
EXAMPLE
sFilename descriptor

NAMEDESC:

:Store filename string length here.
;Address of filename string

.LONG O
.LONG BUFF

BUFF:

DEFDESC:

sStore filename here.

.BLKB 30

;Default filename string descriptor

.ASCID

/.EXE;0/

BUF_SIZE = 512
BUFFER: .BLKB

BUF_SIZE

FILE_LENGTH:
.LONG

FILE_ATTR:

.LONG 0

$DS_LOAD_S NAMEDESC, DEFDESC, #BUF_SIZE,

BUFFER, FILE_LENGTH,FILE_ATTR

5-221

$DS_LOAD

BLISS-32
EXAMPLE
LITERAL

BUF_SIZE =

512;

OWN

BUFFER

BUFF

VECTOR

NAMEDESC:

VECTOR

[30,

VECTOR
INITIAL

[BUF_SIZE,

BYTE],

[2]

BYTE],

Store

Filename descriptor

filename here.

(O,

{

Store

BUFF) ,

Address of filename string

FILE_LENGTH

VECTOR,

FILE_ATTR

VECTOR;

filename string

length here.

BIND

DEFDESC

UPLIT

(%ASCID

$DS_LOAD

'.EXE;0');t

(FILE=NAMEDESC,

ADDRESS=BUFFER,

5-222

Default

filename

DEFAULT=DEFDESC,

string descriptor

LENGTH=BUF_SIZE,

RETLEN=FILE_LENGTH,

RETREC=FILE_ATTR);

$DS_SLITERAL

$DS_SLITERAL
This p-table descriptor macro is used to load a literal value into the value

MACRO-32

$DS_SLITERAL

BLISS-32

$DS_SLITERAL

(LIT=Iit);

FORMAT

Value (longword) to be loaded into the ““value register” (see
Section 3.2.3.3).

Code generated by macro (shown in Macro-32; Bliss-32 is equivalent):
.BYTE
. LONG

~X86
1it

; Beginning of LITERAL
: Literal value

MACRO-32
EXAMPLE

$DS_SLITERAL LIT="XFF

$DS_SLITERAL ~0776

BLISS-32
EXAMPLE
$DS_SLITERAL (LIT=%X'FF’);

$DS_$LITERAL (LIT=%0'776');

5-223

$DS_SLOGICAL

$DS_SLOGICAL
This p-table descriptor macro is used to read a ‘‘yes’’ or ‘‘no’’ response

from an ATTACH command line. The expected response is one of the
strings 'YES’ or 'NO’. They may be abbreviated, and may be upper or
lower case. The value register will be loaded with a 0 if the response was
“no,” or with a 1 if the response was ‘‘yes.”’

MACRO-32

$DS_SLOGICAL

<prompt_>

BLISS-32
FORMAT:

$DS_SLOGICAL

(PROMPT
= ‘prompt’);

ARGUMENTS

prompt

NOTES

Code generated by macro (shown in Macro-32; Bliss-32 is equivalent):

A character string representing the prompting message to be displayed by
the ATTACH command processing routine of the VDS.

.BYTE

~X8B

;

Beginning

+.ASCIC

\prompt\

;

Prompt

MACRO-32

EXAMPLE
$DS_$LOGICAL <Load WCS_>

BLISS-32
EXAMPLE
$DS_SLOGICAL

5-224

(PROMPT='Load WCS'’);

string

LOGICAL

prompt

$DS_MEMSIZE

$DS_MEMSIZE
The $DS_MEMSIZE macro returns the size, in pages, of physical memory.
This macro cannot be called if you are running in user mode.

MACRO-32

SDS_MEMSIZE_x

BLISS-32

$DS_MEMSIZE

ARGUMENTS

memsiz

(MEMSIZE = memsiz);

Address of the longword to receive the number of pages of physical
memory.

RETURN

SS$_NORMAL
-

STATUS

DS$_NOSUPPORT

Servi G

full

ervice successfully

leted

SUCCESSIy
o o
VDS is running under VMS. Service is not supported

completed.

online.
'

MACRO-32
EXAMPLE
PAGE_COUNT :

.BLKL

sné_MEMSIZE_s PAGE_COUNT

BLISS-32
EXAMPLE
OWN
PAGE_COUNT

$DS_MEMSIZE

VECTOR;

(MEMSIZ=PAGE_COUNT);

5-225

$DS_MMOFF

$DS_MMOFF
The Turn Memory Management Off (DS$_MMOFF) system service is

provided for disabling the memory management hardware in standalone
mode.

Only level 3 diagnostic programs may disable memory management on or

off. If a level 3 program disables memory management on or off, it must
use this service to do so.
Memory management is discussed in Section 4.3, Memory Management

and Allocation.

MACRO-32

$DS_MMOFF_x

BLISS-32

$DS_MMOFF;

RETURN

SS$_WASCLR

Servi

SS$_WASSET

Service successfully completed. Memory

DS$_WARNING

The $DS_MMOFF macro was issued, but memory

STATUS

full

leted. M

ervice successfully completed.

Memory

management was previously disabled.
management was previously enabled.

management was not disabled because a SET MM

ON user command had previously been issued (see
the VAX/DS Diagnostic Supervisor User’s Guide.)

NOTES

The user command SET MM ON has precedence over the

$DS_MMOFF macro. Thus, a program cannot shut off memory
management if the user has turned it on.

In a multiprocessing environment, $DS_MMON and $DS_MMOFF

cannot be called from within a block of code delineated by the

$DS_BGNATTACHED and $DS_ENDATTACHED macros.
Additionally, the primary processor cannot call $DS_MMON or

$DS_MMOFF after an attached processor has been booted with the
$DS_BOOTATTACHED service.

MACRO-32
EXAMPLE
$DS_MMOFF_S

5-226

;Turn off memory management.

$DS_MMOFF

BLISS-32
EXAMPLE

(This example illustrates the case of a program that cannot execute if
memory management is enabled. If the program cannot turn memory
management off, it aborts.)

!
!

Turn off memory management.
If the user has turned it on,
call routine to report the problem, then abort the program.

$DS_MMOFF;
IF

DS$_WARNING

THEN

BEGIN
REPORT
MM ON

$DS_ABORT

();

END;

5-227

$DS_MMON

$DS_MMON
The Turn Memory Management On (DS$_MMON) system service is
provided for enabling the memory management hardware in standalone

mode.

Only level 3 diagnostic programs may enable memory management. If a
level 3 program enables memory management, it must use this service to
do so.

Memory management is discussed in Section 4.3, Memory Management
and Allocation.

MACRO-32

$DS_MMON_x

BLISS-32

$DS_MMON;

RETURN

SS$ WASCLR

Senvi

SS$_WASSET

Service successfully completed.

STATUS

full

ervice successtu

leted. M

compieted.

emo

management was previously disabled.

Memory

management was previously enabled.

NOTES

The user command SET MM ON has precedence over the

$DS_MMOFF macro. Thus, a program cannot shut off memory
management if the user has turned it on.

In a multiprocessing environment, $DS_MMON and $DS_MMOFF

cannot be called from within a block of code delineated by the

$DS_BGNATTACHED and $DS_ENDATTACHED macros.
Additionally, the primary processor cannot call $DS_MMON or

$DS_MMOFF after an attached processor has been booted with the

$DS_BOOTATTACHED service.

MACRO-32
EXAMPLE
$DS_MMON_S

5-228

yTurn on memory management.

$DS_MMON

00—

BLISS-32
EXAMPLE

(This example illustrates the case of a program that cannot execute if

memory management is enabled. If the program cannot turn memory
management off, it aborts.)

Turn off memory management.

call routine to report the problem,

If the user has turned it on,
then abort the program.

$DS_MMOFF;

IF DS$_WARNING
THEN

BEGIN

REPORT_MM_ON

$DS_ABORT

();

()

END;

5-229

$DS_SNAME

$DS_SNAME
The $DS_$NAME p-table descriptor macro is used if device name
validation is desired.

If used, the macro must immediately follow the

$DS_SINITIALIZE macro. When this macro is present, the device generic

name (the third argument to the ATTACH command) must conform to the
naming conventions specified. (See note 1 for exceptions.)
All device names can be described by the general formula ‘ggan’; where

'gg’ is a generic device prefix (not necessarily only two characters), ra’
is a letter representing which controller or bus adapter the device is on,
and 'n’ represents the device’s unit number on that controller or adapter.

Both the ra* and 'n’ portions are optional, but every device must have
a 'gg’ portion.

For most devices, 'gg’ is fixed by the physical type of

the device; or, it may be determined by its LINK device (the controller to

which it is attached). The $DS_$NAME statement allows specification and
enforcement of these rules.

MACRO-32

$DS_SNAME

flags, generic

BLISS-32

$DS_SNAME

(FLAGS =flags, GENERIC = generic);

flags
Q

ARGUMENTS

Flag bits that control the format of the device name. Symbolic names for

the flags are defined by the $DS_PTDDEF macro. The flag bits are:

Bit 0 — PTD$M_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_$INITIALIZE macro.
Bit 1 — PTD$M_CONTROLLER — The ’a’ portion of the generic name
is required for this device. If the bit PTD$M_INHERIT_CON is also set,
the ra’ portion must match the ‘a’ portion of the controller to which
this device is attached.

Bit2 — PTDSM_NAME — Only the 'gg’ portion of the generic name is
required. This is most common for network devices, which are known
by their DECnet names (for example, YODA, STAR, GALAXY).

Bit 3 — PTD$M_INHERIT_PRE — The - gg' device name prefix is
inherited from the controller to which the device is attached. This, for
example, allows a VT100 to require a name of the form 'TTan’ when
attached to a DZ11 (+TTa’), or 'TXan’ when attached to a DMF32A
(rTXar).

Bit 4 — PTD$SM_INHERIT_CON — The ra’ controller designator
portion of the device name is inherited from the controller to which the
device is attached. This, for example, allows a VT100 to require a name
of the form 'TTAn’ when attached to DZ11 *TTA", or 'TTBn’ when
attached to DZ11 'TTB".

$DS_SNAME

Bits 5 to 7 are reserved for future expansion and must not be set by any

p-table descriptor.

Additionally, several special names are defined that combine common sets
of these flag bits. They are:

PTD$M_INHERIT — This combines the bits PTD$M_INHERIT_PRE
and PTD$SM_INHERIT_CON. This is the normal permutation of the two
bits.

PTD$M_DEVICE — This combines the bits PTD$M_CONTROLLER
and PTD$M_UNIT. It would commonly be used for devices that are
connected directly to a bus, rather than a controller, and therefore
require both 'a’ and /'n’ portions but should not inherit them from
their LINK device.

PTD$M_ENDDEVICE — This combines the bits
PTD$M_CONTROLLER, PTD$M_UNIT, and PTD$M_INHERIT. It
would commonly be used for devices that have controllers, such as an
RKO07 that is attached to an RK711, and should inherit the controller’s
name prefix and controller letter.

The default is PTD$M_DEVICE.

generic
The 'gg’ portion required for this device. If the flag PTD$M_INHERIT_PRE
is set, this argument is used only if the device is linked to HUB.
]

NOTES

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 compatibility with APT scripts and VDS

scripts that do not adhere to proper naming conventions.

Code generated by macro (shown in Macro-32; Bliss-32 is equivalent):
.BYTE

~X8D

;

Start

.BYTE

flags

Generic

NAME

+ASCIC

T"generic"

;

Enforced generic

name

statement
format

flags

name

MACRO-32
EXAMPLE

$DS_SNAME

FLAGS=PTD$M_ENDDEVICE,

$DS_$NAME

PTD$M_UNIT,

GENERIC=DM

5-231

$DS_SNAME

BLISS-32
EXAMPLE
$DS_SNAME

(FLAGS=(PTDSM_ENDDEVICE),

$DS_S$NAME

(FLAGS=(PTDSM_UNIT),

5-232

GENERIC='DM’);

GENERIC='KA’);

$DS_SOCTAL

$DS_SOCTAL
The $DS_$OCTAL p-table macro is used to read a value from the ATTACH
command line. If no more parameters are available on the command line,
or if the next parameter is not an octal vaiue, the prompting message
will be displayed to the user. The value that is read is stored in the
“‘value register’’ (see Section 3.2.3.3) for use by a $DS_$COMPLEMENT,
$DS_$STORE, or $DS_$CASE statement.

MACRO-32

$DS_SOCTAL

prompt, low, high

BLISS-32

$DS_SOCTAL

(PROMPT =prompt, LOW =low,
HIGH = high);

ARGUMENTS

prompt

Character string that is to be printed as a prompt to the user. This prompt
will be used if the ATTACH command line does not contain the required
value.

low

The low limit for the value. If the value given is lower than this, 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.

high

The high limit for the value. If the value given is higher than this, 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.

NOTES

Code generated by macro (shown in Macro-32; Bliss-32 is equivalent):
.BYTE

~X83

Beginning of OCTAL prompt

.ASCIC

\prompt\

;

Prompt string

.LONG

~Olow

;

Low limit

. LONG

~Chigh

;

High limit

5-233

$DS_SOCTAL

MACRO-32
EXAMPLE
$DS_S$OCTAL CSR,760000,777776
$DS_SCCTAL PROMPT=<VECTOR_>,

LOW=2,

HIGH=776

BLISS-32

EXAMPLES
$DS_$OCTAL

(PROMPT='CSR’,

$DS_S$SOCTAL

(PROMPT='VECTOR’,

5-234

LOW=%0'760000’,
LOW=%0'2’,

HIGH=%0'777776');

HIGH=%0'776');

$OPEN

The Open Existing File service of RMS is used to make a file available for
processing. Opening a file is the first step in processing the information
within the file. This service uses parameters within the FAB to determine
which file to open and what access attributes to assign to the file.

MACRO-32

$SOPEN

fab, [err], [suc];

BLISS-32

$SOPEN

(FAB=fab, [ERR =err], [SUC = suc]);

ARGUMENTS

fab

Address of the FAB. The FAB is declared using the $FAB macro.

err (user mode only)
Address of routine to execute on error return from open service.

suc (user mode only)
Address of routine to execute on successful return from open service.

RETURN

STATUS

RMS$_NORMAL

Servi

RMS$_ACC

Error accessing file.

RMS$_DME

Dynamic memory exhausted. Insufficient dynamic

full.

leted

ervice successfully completed.

memory available.

RMS$_DEV

Bad device specification.

RMS$_FAB

Error in FAB.

RMS$_FNF

File not found.

RMS$_FNM

Bad file name.

RMS$_ORG

Invalid file organization. In standalone mode, file
organization must be sequential.

RMS$_RER

File read error.

Note: For further details on return status values, refer to the VAX-11 RMS
Reference Manual.

NOTES

Table 5-6 lists the FAB fields used by the $OPEN service IN
STANDALONE MODE. For user mode, refer to the VAX-11 RMS
Reference Manual.

$OPEN

Table 5-6

FAB Fields Used by $OPEN (Standalone Mode)

Field Mnemonic

Field Name

Input:

DNA

Default file specification string address.

DNS

Default file specification string size.

FAC

File access.

FNA

File specification string address.

FNS

File specification string size.

FOP

File processing options.

FSZ

Fixed control area size; unit record devices only.

IFl

Internal file identifier (must be 0).

RAT

Record attributes (unit record devices only).

RFM

Record format; unit record devices only.

XAB

Extended attribute block address.

Output:
ALQ

Allocation quantity; contains the highest numbered block

allocated to the file.
BLS

Block size.

DEV

Device characteristics.

FSZ

Fixed control area size; applies only to ‘“‘variable with fixed
length” control records

MACRO-32

EXAMPLE
$OPEN FAB_BLOCK

BLISS-32
EXAMPLE
$OPEN

5-236

(FAB=FAB_BLOCK)
;

IFI

Internal file identifier.

MRS

Maximum record size.

ORG

File organization.

RAT

Record attributes.

RFM

Record format.

STS

Completion status code (also returned in RO).

$DS_PAGE

$DS_PAGE
The $DS_PAGE macro is used in conjunction with the $DS_SBTTL macro.
if the $DS_PAGE macro with a nonzero argument is placed immediately
before the $DS_SBTTL macro, the following actions will take place:
¢

Printing of the $DS_SBTTL call in the assembly listing will be
suppressed, but the expansion of the $DS_SBTTL macro will be
printed.

The subtitle will appear at the top of a new page.

The result of these actions is that the SBTTL statement accompanying
text generated by the $DS_SBTTL macro will appear at the top of the next
page in the assembly listing.

num

MACRO-32

$DS_SBTTL

BLISS-32

Not supported for BLISS-32.

ARGUMENTS

num

Flag indicating whether or not the subtitle generated by the $DS_SBTTL
macro should appear on a new page. If this value is 0, the subtitle will

appear on the current page, and printing of the $DS_SBTTL macro call
will be suppressed. If the value is nonzero, a new page will be started.
The subtitle will appear at the top of the new page, and printing of the
$DS_SBTTL macro call will be suppressed.

EXAMPLES
$DS_PAGE

$DS_SBTTL <READ/WRITE TESTS>

5-237

$DS_PARDEF

$DS_PARDEF
The $DS_PARDEF macro defines (for MACRO-32 programs) symbolic

names for values that can be used with the ‘‘radix,”’ ‘‘defait,”’ and
““exword’’ parameters to the $DS_ASKxxxx macros.

For BLISS-32

programs, these symbols may be referenced without first issuing the

$DS_PARDEF macro.
Symbols defined are:
PARS_BIN

PARS_DEC
PAR$_HEX

PARS_OCT
PARS_NO

PARS$_YES
PAR$V_NODEF

PAR$M_NODEF

PARSV_ATHI

PARSM_ATHI

PARSV_ATDEF

PARSM_ATDEF

PARS$V_ATLO

PARSM_ATLO

MACRO-32

$DS_PARDEF

ARGUMENTS

gbl

MACRO-32
EXAMPLE

$DS_PARDEF GLOBAL

5-238

[gbl]

Can be LOCAL or GLOBAL

$DS_PARSE

$DS_PARSE
The Parse Command String system service can be used in a diagnostic

program for which a unique command language has been defined (see

Section 4.2.2.2, Prompting the User). This service will parse a command
string by searching a predefined command tree, looking for a matches
between the command string and nodes of the tree. Every time a match
is found, the service will dispatch to an ‘“‘action routine.”” Details are

presented in the notes below.

MACRO-32

$DS_PARSE_x

BLISS-32

$DS_PARSE

ARGUMENTS

bufadr

bufadr, tree, action

(BUFFER =bufadr, TREE =tree,
ACTION = action);

Address of a quadword descriptor (see Section 4.3) pointing to the
command string.

tree
Address of the tree of valid commands. This tree should be defined by

using the $DS_CLI macro.

action
Address of action routine. See notes for routine format.

RETURN
.

STATUS

SS$_NORMAL

Service successfully

DS$_ERROR

While traversing the command tree, an error

completed.

comp

node (defined by CLISK_ERROR, see $DS_CLI
description) was encountered. In other words, an
illegal command string was specified.

NOTES

The command string to be parsed should be fetched from the user by

issuing the $DS_ASKSTR macro.
2

The $DS_PARSE system service will traverse the parse tree until a
CLI$K_EXIT or a CLI$K_ERROR code is encountered (see DS$_CLI
description), at which point it will return to the caller.

$DS_PARSE

As the tree is traversed, the action routine will be called each time
there is a match between the contents of the current node of the tree
and the input stream. If a match is found, the action routine is called
and then the next node in the current path is checked. Otherwise, a
branch to the node specified by the ‘“miss’”’ parameter of the $DS_CLI
macro occurs.

In a multiprocessing environment, $DS_PARSE cannot be called from
within a block of code delineated by the $DS_BGNATTACHED and
$DS_ENDATTACHED macros.

Action Routines:

-Parameters will be passed to the action routine as follows:
e

RO — Will contain action code specified for current node in parse tree.

R7 — Will contain current value of pointer used by VDS when
traversing tree.

R8 — Will point to next unparsed character in the input string.

R9 — Will contain number of unparsed characters remaining in input
string.

R10 and R11 — Will contain quadword value of last numeric string read
from input buffer.

Generally, the programmer will specify a unique action code for each
tree node, using the $DS_CLI macro. Sometimes a “‘null”’ action code
is used, because it is not necessary for the action routine to do anything
for nodes which do not completely identify a command, parameter, or

qualifier. In other words, it is usually necessary to perform an action

only when the parser is sure it has found something recognizable. When
the action routine is called, the action code is passed in R0. The action
routine can thus use a MACRO-32 CASE instruction or a BLISS-32 CASE

expression, or some other means, to dispatch to a unique subroutine for
each code. These subroutines will often just set bits in a bitmap indicating
what command, command parameter, or command qualifier has been
parsed. When the entire command string has been parsed,

a command

dispatching routine can be called. This dispatcher can examine the bitmap
to determine which command processing routine to call.

5-240

$DS_PARSE

An example action routine corresponding to the sample parse tree defined
in the description of the $DS_CLI macro (earlier in this chapter) would be

as follows:
ACTION_RTN::

CASEL

RO,

#0,

105

.WORD

ACT_NO_ACTION-10$

.WORD

ACT_ADD-10$

.WORD

ACT_BAKE-10%

.WORD

ACT_BEAT-10$

.WORD

ACT_MILK-10$

.WORD

ACT_SALT-10$

.WORD

ACT_SUGAR-10$

.WORD

ACT_ILLCMD-10$

.WORD

ACT_ BADARG-10$

ACT_NO_ACTION:

RSB

ACT_ADD:
BISB

#1@ADD,

CMD_BLOCK

RSB
ACT_BAKE:
BISB

# 1€BAKE,

CMD_BLOCK

#1@BEAT,

CMD_BLOCK

#1@MILK,

PARAM_BLOCK

$1€saLT,

PARAM_BLOCK

RSB

ACT_BEAT:

BISB

RSB
ACT_MILK:

BISB
RSB

ACT_SALT:
BISB

RSB
ACT_SUGAR:

BISB

#1@5UGAR,

PARAM_BLOCK

RSB
ACT_ILLCMD:

BISB

#1€ILLCMD,

ERROR_BLOCK

#1@BADARG,

ERROR_BLOCK

RSB

ACT_BADARG:
BISB

RSB

5-241

$DS_PARSE

MACRO-32
EXAMPLE

This example fetches a command string, attempts to parse the string, and
then either calls a command dispatcher or an error handler.

$DS_ASKSTR_S

MSGADR=PROMPT_MSG,

Prompt

user

for

input

string.

STRING_BUF+1,

CMD_BUFFER
CMD_BUFFER+4

BUFADR=CMD_BUFFER,

STRING_BUF,

MOVAL

—e

MOVZBL

$DS_PARSE_S

SS$_NORMAL

then go

ASK_ERRHNDLR

Put

RO,

BNEQ

address

BUFADR=STRING_BUF
CMPL

error

occurred

Parse the

string

error

handler

length

and string

in guadword descriptor
input

string.

TREE=TREE_ROOT,
-

PARSE_ERRHNDLR

BSBW

CMD_DISPATCHER

5-242

SS$_NORMAL

RO,

CMPL

BNEQ

then

ACTION=ACTION_RTN

unsuccessful

Good

parse

error
-

parse

handler

process

command.

$DS_PRINTB

$DS_PRINTB
The Format and Print ASC!l Message system services provide a means by
which complex messages can be formatted into ASCII character strings
and displayed on the user terminal. The macros that call these services
are commonly referred to as the “‘print’’ macros. These macros can be
used to

Insert variable character string data into an output string

Convert binary values into the ASCII representations of their decimal,
hexadecimal, or octal equivalents and substitute the results in an

output string

The system services construct an output string by referring to formatted
ASCII output (FAO) directives contained in a ‘‘control string’’ and using
those directives to operate on the contents of value parameters.
Once the system service creates the output string, it is automatically
displayed on the user terminal.

The $DS_PRINTB macro (*‘print basic error message’’) is used exclusively
to display the second message level of error messages (see Section 3.9,
Reporting Errors). Display of messages generated with this macro will be
inhibited if either of the VDS control flags IE2 or IE3 is set (see the VAX/DS
Diagnostic Supervisor User’s Guide).

MACRO-32

$DS_PRINTB_x

format, [p0], [p1], [P2], [P3], [04],

BLISS-32

$DS_PRINTB (format, [00], [p1], [p2], [P3], [pzi], [p5], [

[p5], [p6], [P7], [P8], [P9], [pa], [Pb],
[pc], [pd], [pel, [pf]

p6], [07], [08], [P9], [Pa], [pbl, [pc], [pal,
[pel, [p]);

ARGUMENTS

format

Address of a counted ASCII string. This is the “’control string,” which
consists of the fixed text of the output string plus FAO directives for
formatting variable data. FAO directives are listed below. Variable data is
passed in parameters p0 through pf.

pO through pf

0 to 16 directive parameters, contained in longwords. Depending on the
corresponding FAO directive, a parameter may be a value that is to be
converted, the address of a string that is to be inserted, a length, or an
argument count. Parameters are listed in the order they are referenced by
the control string.

5-243

$DS_PRINTB

RETURN

STATUS

SS$_NORMAL

SS$_BUFFEROVF

Service successfully completed.

Service successfully completed, but the size of the
output string was greater than the maximum allowed

and was truncated (see notes).
SS$_BADPARAM

An invalid FAO directive was specified in the control
string.

“

NOTES

VDS stores the output string in an internal buffer as it is being created.
This buffer can contain up to 512 characters. If the output string is

greater than 512 characters, the string is truncated and the truncated
message is displayed.

If it is necessary to format a message containing more than 16

parameters, it is possible to

Use several PRINT macros in succession, or

Use the $FAO or $FAOL macros to format the message. The

message should then be printed using the proper print macro (for

example, PRINTX for a level 3 error message).

In MACRO-32, the $FAO_S macro form uses a PUSHL instruction
for all parameters (p1 through pn) specified with the macro call. In
other words, all arguments are assumed to be values, not addresses.
Therefore, if an address is desired, precede the argument with a #
character, or load the address into a register.

In a multiprocessing environment, $DS_PRINTxxx cannot be called
from within a block of code delineated by the $DS_BGNATTACHED

and $DS_ENDATTACHED macros.

An FAOQ directive has the following format:

'DD
where
!

indicates that the following character is to be interpreted as an FAO

directive, and
DD

is a 1- or 2-character FAO directive. A directive requires a parameter
to be included in the parameter list of the macro call.

Note that all directives must be specified in uppercase letters.

Optionally, a directive may include:
*

A repeat count, which has the following format:

In(DD)
where n is a decimal number that indicates that the directive should
be repeated for the next n parameters.

5-244

$DS_PRINTB

An output field length, which has the following format:
lengthDD

where length indicates the field length that the output resulting
from the specified directive should have.
¢

Both a repeat count and an output field length:
In(lengthDD)

Repeat counts and output field lengths may be specified as

variables by using a pound sign (#) in place of an absolute numeric
value. If a pound sign (#) is specified for a repeat count, the next
argument included in the macro call must contain the count. If
a pound sign (#) is specified for an output field length, the next
argument must contain the length value. If an output field length
is specified as a variable, and a repeat count is also specified
(by variable or by value), then only one length parameter will be
fetched from the argument list, and each output string generated by
the repeat count will have that length.

A control string may be any length and may contain any number
of FAO directives. The only restriction is on the use of the
exclamation point (!) character (ASCII code "X21). If a literal
exclamation point (!) is required in the output string, the directive
double exclamation points (!!) must be used. Each character in the

control string that is not part of an FAO directive is copied into the
output string. Thus, if a portion of the message being formatted is
a nonvolatile character string, that string can be placed directly into
the control string. If an invalid FAO directive is encountered in the
control string, creation of the output string ceases at that point and
an error status is returned to the caller.
No tests are made to determine if the correct number of parameters have

been included in the macro call. If fewer parameters have been specified
than are referenced by the control string, the system service routine will
continue to fetch parameters past the end of the parameter list.
Table 5-7 lists the FAQO directives.

Table 5-8 summarizes how the length of each field in the output string is
determined, if no field length has been specified.

5-245

$DS_PRINTB

Table 5-7

FAO Directives

Directive

Function

Parameter(s)

Character String Substitution:
IAC

IAD

Inserts a counted ASCII

Address of the string; the first byte

string.

must contain the length

Inserts an ASCII string.

1) Length of string
2) Address of string

IAF

Inserts an ASCII string.

1) Length of string

Replaces all nonprintable

2) Address of string

ASCII codes with periods

().
IAS

Inserts an ASCII string.

Address of quadword

character string
descriptor pointing
to the string

Numeric Conversion (zero-filled):

Converts a byte to octal.

Value to be converted to

IOW

Converts a word to octal.

ASCI! representation

1oL

Converts a longword to

octal.
IXB

Converts a byte to

For byte or word conversion, FAO

IXW

hexadecimal.

uses only the low-order byte or

IXL

Converts a word to

word of the longword parameter.

hexadecimal.

Converts a longword to hex.
ZB

Converts an unsigned

1ZW

decimal byte.

1ZL

Converts an unsigned
decimal word.
Converts an unsigned
decimal longword.

Numeric Conversion (blank-filled):
iuB

Converts an unsigned

Value to be converted to ASCII

IUw

decimal byte.

representation

Converts an unsigned
decimal word.

Converts an unsigned’
decimal longword.

ISB

Converts a signed decimal

ISW

byte.

uses only the low-order byte or

ISL

Converts a signed decimal

word of the longword parameter

word.

Converts a signed decimal
longword.

5-246

For byte or word conversion, FAO

$DS_PRINTB

Table 5-7 (Cont.)
Directive

FAO Directives

Function

Parameter(s)

Output String Formatting:

)

Inserts new line (cr/if).

Inserts a tab.

Inserts a form feed.

Inserts an exclamation point.

196S

Inserts the letter S if most
recently converted numeric
value is not 1.

1%T

Inserts the system time.

None

Address of a quadword time value
to be converted to ASCIL. If 0 is
specified, the current system time
is used.

19D

Inserts the system date and
time.

In<
1>

Defines output field width of
n. characters. All data and

None

directives within delimiters

are left-justified and blankfilled within the field.

In*c

Repeats the specified
character in the output string
n times.

Parameter Interpretation:

I-

Reuses last parameter in the

None

list.

I+

Skips next parameter in the
list.

Note:

If a variable repeat count and/or a variable output field length is specified
with a directive, parameters indicating the count and/or length must
precede other parameters required by the directive.

5-247

$DS_PRINTB

Table 5-8

FAO Field Lengths and Fill Characters

Action When
Conversion or

Action When

Explicit

Output Field

Length is

Substitution

Default Length

Longer Then

Shorter Than

Type

of Output Field

Default

How FAO Determines Output Field Lengths and Fill Characters:

Hexadecimal

2 (zero-filled)

ASCII result is

byte

4 (zero-filled)

right-justified and

truncated on the

word

8 (zero-filled)

blank-filled to the

left.

longword

specified length.

Octal

3 (zero-filled)

Hex or octal output

byte

6 (zero-filled)

is zero-filled to the

word

11 (zero-filled)

default output field

longword

length, then blankfilled to specified
length.

Signed or

As many

ASCIl result is

unsigned

characters as

right-justified and

unsigned decimal

decimal

necessary

blank-filled to the

output fields are

specified length.

Signed and

completely filled
with asterisks (*).

Unsigned

As many

ASCII result is right-

zero-filled

characters as

justified and zero-

decimal

necessary

filled to the specified
length.

ASCII string

Length of input

ASCHi string is left-

ASCII string is

substitution

character string

justified and blank-

truncated on the

filled to the specified

right.

fength.

0ttt
]

MACRO-32
EXAMPLE
BYTES

TRANSFERRED:

The following examples will display this message:
XXXXXxXxX

BAD:

yyyyyvyyy

where ““x00000x’” and “yyyyyyyy’’ represent real values.

FMT_ERRCOUNT :

.ASCIC

?!/!/BYTES TRANSFERRED:!SL!

$DS_PRINTB_S

5-248

FMT_ERRCOUNT,

4(AP),

BAD:!SL!/!/?

ERR_CNT

$DS_PRINTB

BLISS-32
EXAMPLE
BIND

FMT_ERRCOUNT =

UPLIT

(%ASCIC ’!/!/BYTES TRANSFERRED:!SL!_ BAD:!SL!/!/');

$DS_PRINTB (FMT_ERRCOUNT,

.TOTAL,

.ERR_CNT) ;

5-249

$DS_PRINTF

$DS_PRINTF
The Format and Print ASCIl Message system services provide a means
by
which complex messages can be formatted into ASCII character strings
and displayed on the user terminal. The macros that call these services
are commonly referred to as the ‘‘print’’ macros. These macros can
be

used to
*

Insert variable character string data into an output string

Convert binary values into the ASCI| representations of their decimal,
hexadecimal, or octal equivalents and substitute the results in an

output string

The system services construct an output string by referring to formatted
ASCII output (FAOQ) directives contained in a ‘‘control string’’ and using
those directives to operate on the contents of value parameters.

Once the system service creates the output string, it is automatically
displayed on the user terminal.
The $DS_PRINTF macro (*‘print forced message’’) is used to display

informational messages that are not related to device errors. These

messages are referred to as ‘‘forced’’ messages because they are printed

regardless of the state of the flags which inhibit message displays (see the
VAX/DS Diagnostic Supervisor User’s Guide).

MACRO-32

$DS_PRINTF_x

format, [p0], [p1], [02], [p3], [P4], [P5],

[p6], [p7], [P8], [pY)], [pa], [pb], [pc],
[rd], [pe], [pf]
BLISS-32

$DS_PRINTF

(format, [p0], [p1], [p2], [03], [04], [P5],

[p6], [P7], [P8], [PY], [pal, [pb], [pc], [pd],
[pel, [pf]);
ARGUMENTS

format

Address of a counted ASCII string. This is the ‘“control string,”” which
consists of the fixed text of the output string plus FAO directives

for

formatting variable data. FAO directives are listed in Table 5-7. Variable
data is passed in parameters p0 through pf.

pO through pf
0 to 16 directive parameters, contained in longwords. Depending on
the

corresponding FAO directive, a parameter may be a value that

is to be
converted, the address of a string that is to be inserted, a length,
or an

argument count. Parameters are listed in the order they
are referenced

the control string.

5-250

$DS_PRINTF

RETURN

SS$_NORMAL
_

STATUS

SS$_BUFFEROVF

Servi)

full Y

ervice successfully

leted

completed.

Service successfully completed, but the size of the
output string was greater than the maximum allowed
and was truncated (see notes).

SS$_BADPARAM

An invalid FAQO directive was specified in the control
string.

NOTES

VDS stores the output string in an internal buffer as it is being created.
This buffer can contain up to 512 characters. If the output string is
greater than 512 characters, the string is truncated and the truncated
message is displayed.

If it is necessary to format a message containing more than 16
parameters, it is possible to
e

Use several PRINT macros in succession, or

Use the $FAO or $FAOL macros to format the message. The
message should then be printed using the proper print macro (for
example, PRINTX for a level 3 error message).

In MACRO-32, the $FAQ_S macro form uses a PUSHL instruction
for all parameters (p1 through pn) specified with the macro call. In
other words, all arguments are assumed to be values, not addresses.
Therefore, if an address is desired, precede the argument with a #
character, or load the address into a register.

In a multiprocessing environment, $DS_PRINTxxx cannot be called

from within a block of code delineated by the $DS_BGNATTACHED
and $DS_ENDATTACHED macros.
5

MACRO-32
EXAMPLE

FAOQO Directives. See Note 5 of the $DS_PRINTB macro.

The following examples will display this message:

This machine is not supported by this diagnostic.

NON_SUPPORTED_CPU:

.ASCIC

"!/ This machine is

$DS_PRINTF_S

not supported by this diagnostic.!/"

@#NON_SUPPORTED_CPU

5-251

$DS_PRINTF

BLISS-32
EXAMPLE
BIND

NON_SUPPORTED_CPU

UPLIT

$DS_PRINTF

5-252

(%ASCIC

’!/!/This machine

(NON_SUPPORTED_CPU);

not supported by this

diagnostict/’),

$DS_PRINTREV

$DS_PRINTREV
The Print Revision Level service may be used in diagnostic programs that

test devices for which a hardware, firmware, and/or patch revision level is
accessible to the program. Such programs may want to indicate whether
the device’s revision levels are compatible with the revision levels expected

by the program.
This service will:

Compare actual and expected device revision levels specified by the
diagnostic program

Display a message indicating the device’s revision level (hardware
firmware, or patch), and also indicating whether the revision levels
being compared are hardware levels, firmware levels, or patch levels.
A module number may be printed, and hardware revision numbers may

be converted to a letter code.

Cause the hardware revision level, firmware revision level and/or patch
level to be included in all error messages (generated via $DS_ERRxxxx
macros) that are subsequently displayed for the unit in question.

If the device being tested has a software-readable hardware, firmware,

or patch level, the $DS_PRINTREYV service should be called for each
selected device. These calls should be made in the ‘‘pass 0’ section of
the initialization code.
If the device has all three (hardware, firmware, and patch) revision types,
then the service should be called three times for each selected device;
once to report the hardware revision, once for the firmware revision, and

once for the patch level.
For each logical unit, $DS_PRINTREV can be called four times for each

type of revision level. This allows you to check and report revision levels for

each module (up to four) of a device with multiple modules (boards). For
example, it would be desirable to call $DS_PRINTREV twice for hardware
revision levels if a logical unit was a 2-board device, and each board had

an associated hardware revision level.

(You can use the ‘“‘modulenum”

parameter to differentiate the modules.)
When called, the service will immediately display (at the programmer’s

option) a message indicating the actual revision level and/or messages
indicating whether the actual revision level matches the revision level
expected by the diagnostic program. One of the following messages may

be printed. (DEVNAME will be replaced by the generic name of the unit in
question, and MODNAME will be replace by the ASCII string specified by
the “‘modulenum’ parameter, described later.)

Hardware revision level of DEVNAME MODNAME: ***#**=
Hardware revision level of DEVNAME MODNAME is less than that

expected by diagnostic program.

Hardware revision level; ****»»

5-253

$DS_PRINTREV

Revision level expected by program: ***»»»
Hardware revision level of DEVNAME MODNAME is equal to that expected

by diagnostic program.
Hardware revision level: *****»
Revision level expected by program;

»=*»=*=**

Hardware revision level of DEVNAME MODNAME is greater than that

expected by diagnostic program.

Hardware revision level: **»=*=*~
Revision level expected by program: ****»*»
If firmware or patch levels are being reported, the word ‘‘hardware’’ in the
messages will be replaced with the word ‘‘firmware’’ or ‘‘patch’’.

Each time an error service is called ($DS_ERRxxxx) for a unit for which
the $DS_PRINTREV macro has been called, the hardware revision level,
firmware revision level, and/or patch level will be displayed as part of the

error message. The message will be displayed AFTER all of the error text
has been printed. It will be inhibited if the IE1 flag is set. The format of
this display will be:
***%k*x*

program title

Pass

test

Hard

error while testing

program rev.

subtest #,

error

DEVNAME:

**kk+k

date
text

text

for DEVNAME:

MODNAME:

Hardware =

Firmware = X;

Patch

MODNAME:

Hardware = Y;

Firmware = Y;

Patch

*xxxx*

End of

hard

error

number

level(s)

]

Revision

***x*x*

(If any of the levels or the module number are not being reported, they will
not appear in the revision level message.)

MACRO-32

$DS_PRINTREV__x log_unit, actual_rev, expected_rev,
rev_type,

[printmask], [prlink], [modulenum]

BLISS-32

$DS_PRINTREV

(LOG_UNIT =log_unit,
ACTUAL_UNIT = actual_rev,
EXPECTED_REV = expected_rev,
REV_TYPE =rev_type,
[PRINTMASK = printmask],

[PRLINK = prlink],
[MODULENUM = modulenum]);

5-254

$DS_PRINTREV

ARGUMENTS

log_unit

Logical unit number of device whose revision level is to be checked. This
number should be between 0 and 127.

actual_rev

Longword containing the actual hardware, firmware, or patch revision level
for the device whose logical unit number is specified with the ““logunit”
parameter. See Note 3. (The diagnostic program determines this value by
accessing the hardware.)

expected_rev

Longword containing the hardware, firmware, or patch revision level which
was expected by the diagnostic program. See Note 3. (This value is placed
in the diagnostic program at compilation time.)

rev_type
Longword mask indicating the type of revision code (hardware, firmware,
or patch) being compared. Bit definitions are:

Bit 0 — PRV$V_HWREYV, PRVSM_HWREV — Set this bit to indicate a
hardware revision level.

Bit 1 — PRV$V_FWREV, PRV$SM_FWREV — Set this bit to indicate a
firmware revision level.

Bit 2 — PRVS$V_PREV, PRV$M_PREV — Set this bit to indicate a patch
level.

(Only one bit should be set per service call.)

printmask
Longword mask used to control $DS_PRINTREV functions. Bit definitions
are;

Bit 0 — PRMSK$V_LSS, PRMSK$M._LSS
— If set, inhibits message
that would normally be displayed if the actual revision is less than
expected.

Bit 1 — PRMSK$V_EQL, PRMSK$M_EQL — If set, inhibits message
that would normally be displayed if the actual revision is equal to that
expected.

Bit 2 — PRMSK$V_GTR, PRMSK$M_GTR — If set, inhibits message
that would normally be displayed if the actual revision is greater than
expected.

Bit 3 — PRMSK$V_ALWAYS, PRMSK$M_ALWAYS — If set, displays

Bit4 — PRMSK$V_TRANSL, PRMSK$M_TRANSL — If set, will convert
a hardware revision number to a letter code which represents the
functional revision as defined by DEC STD 012. Setting this bit will not
result in conversion for firmware or patch revisions. The conversion
pattern is shown in Table 5-9.

the message which lists only the actual revision level.

5-255

$DS_PRINTREV

Table 5-9

Revision Number to Letter Conversion

Field contents [bits <n:0>]

Functional Rev.

0.....0000

pre-release

0.....0001

0.....0010

0.....0011

0....11010

0....11011

0....11100

0...11101

0...110100

0...110101

0..1001110

1010111110

By default, bits 0 through 4 are clear. A message will be displayed stating
whether the actual revision is greater than, less than, or equal to the
revision expected by the program. No conversion will be performed on
revision numbers. (Inhibiting messages does not affect the inclusion of the
hardware, firmware or patch revision levels in error messages generated by

$DS_ERRxxxx macros.)

prlink
Address of a message routine. This optional routine will have the same
format as an error reporting routine used with a $DS_ERRxxxx macro.
That is, the routine should be delineated with $DS_BGNMESSAGE
and $DS_ENDMESSAGE macros and should use $DS_PRINTB and
$DS_PRINTX macros for displaying text. The message will be printed
when the $DS_PRINTREYV service is called.

modulenum
Address of a counted ASCII string which represents the unique module
identifer for a device module (board).

5-256

. $DS_PRINTREV

Note: If you associate a module identifier with a device, you MUST supply the
“*modulenum’’ argument with each $DS_PRINTREYV call for that device,
whether you are specifying the hardware revision, software revision, or
patch level. (See the example.)

”

RETURN

STATUS

Servi _

DS$_NORMAL

full

leted

ernvice successfully completed.

Exceeding maximum number of devices or modules

DS$_OVERFLOW

in data structure.

DSS$_ILLUNIT

Logical unit does not exist in p-table.

DS$_BADTYPE

Revision type is invalid.

DS$_ERROR

Hardware revision is out of bounds.

DS$ _MEMALLOCERR

Not enough memory available through
EXE$SALONONPAGED.

”

NOTES

Symbols are defined by the $DS_PRINTREV_DEF macro.

This macro should only be used for devices having software-accessible

The format of the revision level is irrelevant, but the values passed via
the ““actual_rev’’ and ““expected_rev’’” parameters must be in the same
format. The service will perform an unsigned comparison of the two
values to determine which message to display. Revision numbers will
be displayed as unsigned decimal values unless conversion to a letter

hardware, firmware, or patch revision numbers.

code is desired.

Recommended Usage:

This macro is probably best used for determining if the current version
of a diagnostic program is incompatible with older hardware. Since new
revisions of the diagnostic program may only run on hardware above
a certain revision level, the diagnostic should only set bits 1 and 2 in
printmask. This causes a message to be displayed only if the actual
revision level is less than that expected by the program. If you do not set
bit 2 in printmask, a misleading message may result if the actual hardware,
firmware, or patch levels were updated without a corresponding change to
the diagnostic’s expected revision levels.

Normally, the hardware revision level should be converted to the
corresponding functional revision letter code by setting bit 4 in
““printmask”’.

5-257

$DS_PRINTREV

L
]

MACRO-32

EXAMPLE
T1001:
.ASCIC

"T1001"

$DS_PRINTREV_S Unit_Num,
-

;Device’s

= CPU_Rev

;Actual

rev,

;Lowest

hardware

Expected_rev

[

Log_Unit
Actual_Rev

[

unit

;

printing.)

number

read

from

rev

that

work with this

(Converted to

"A"

;

Printmask = #~X1E,-

T1001

diagnostic.

hardware parameter.

;Inhibit

equal

greater

;

message,

enable

;

message,

convert

sAddress

;

before

#prvém_hwrev,-;Indicate that this is

Modulenum

’

Rev_Type

will

logical

ascic

than

informational
to

letter.

message

"T1001".

$DS_PRINTREV_S Log_Unit

= Unit_Num,-

Actual_Rev

;Device’s

= uCode_Rev,- ;Actual

Expected_rev

#20,-

:Lowest

;
Rev_Type

unit

;

#~XE,-

Modulenum = T1001

read from HW.
ucode rev that will

work with

this

firmware rev

;Inhibit

equal

;

message,

;

message.

;Address
;

number

diagnostic.

#prvsm_fwrev,-;Indicate that this

Printmask

logical

rev,

enable

parameter.

ascic

greater

than

informational

message

"T1001".

$DS_PRINTREV_S Log_Unit

Unit_Num,
-

Actual_Rev

;Device’s

Patch_Rev,
- tActual

Expected_Rev

#1,_

;Lowest

logical

rev,

unit

number

read from

ucode patch

rev

that

;will work with this diagnostic.
Rev_Type

#prvSm_prev,- 1Indicate
;

Printmask =

#~XE,-

Modulenum = T1001

H Inhibit

that

level

equal

;

message,

;

message.

sAddress
;

5-258

patch

"T1001".

this

parameter.

enable

greater

than

informational

ascic message

$DS_PRINTS

$DS_PRINTS
The Format and Print ASCIl Message system services provide a means by
which complex messages can be formatted into ASCII character strings
and displayed on the user terminal. The macros that call these services
are commonly referred to as the ‘‘print’’ macros. These macros can be
used to
e

Insert variable character string data into an output string

Convert binary values into the ASCII representations of their decimal,
hexadecimal, or octal equivalents and substitute the results in an
output string

Once the system service creates the output string, it is automatically
displayed on the user terminal.
The $DS_PRINTS macro (‘‘print summary message’’) is used exclusively to
display program summary messages (see Section 3.7, Summary Routine).
Display of messages generated with this macro will be inhibited if the VDS

control flag IES is set (see the VAX/DS Diagnostic Supervisor User's Guide).

MACRO-32

$DS_PRINTS_x

format, [p0], [p1], [P2], [P3], [P4], [P5],

[p6], [p7], [P8], [P9], [Pal, [Pb], [pc],
[pd], [pe], [pf]
BLISS-32

$DS_PRINTS

(format, [p0], [p1], [p2], [3], [04], [P5],

[p6], [p7], [P8], [PY], [Pal, [Pb], [pc,
[pd], [pe], [pf]);
ARGUMENTS

format

Address of a counted ASCII string. This is the ““control string,” which
consists of the fixed text of the output string plus FAO directives for
formatting variable data. FAO directives are listed in Table 5-7. Variable
data is passed in parameters p0 through pf.

pO through pf
0 to 16 directive parameters, contained in longwords. Depending on the
corresponding FAO directive, a parameter may be a value that is to be
converted, the address of a string that is to be inserted, a length, or an
argument count. Parameters are listed in the order they are referenced by
the control string.

5-259

$DS_PRINTS

RETURN

SS$_NORMAL

STATUS

Service successfully

’
Service successfully

SS$_BUFFEROVF

completed.

completed, but the size of the

output string was greater than the maximum allowed

and was truncated (see notes).

SS$_BADPARAM

An invalid FAO directive was specified in the control
string.

NOTES

Use several PRINT macros in succession, or

Use the $FAO or $FAOL macros to format the message. The
message should then be printed using the proper print macro (for
example, PRINTX for a level 3 error message).

and $DS_ENDATTACHED macros.

FAO Directives. See Note 5 of the $DS_PRINTB macro.

mmmme
e
——

MACRO-32
EXAMPLE
MEMORY

ERROR

The following examples will display this message:

SUMMARY

1-FEB-1989

16:26:11.

FMT_SUM_HEAD:

«ASCIC

"!/Memory

$DS_PRINTS_S

5-260

Error

Summary

@#FMT_SUM_HEAD

!%T.!/"

$DS_PRINTS

X
S

BLISS-32
EXAMPLE
BIND
FMT_SUM_HEAD

ASCIC

$DS_PRINTS

(’!/!/Memory Error Summary as of

!%T.!/’),

(FMT_SUM_HEAD);

5-261

$DS_PRINTSIG

$DS_PRINTSIG
The Print Signal Array system service will format and print the contents

of a signal array. Signal arrays are passed to condition handlers when
exception conditions occur. Refer to Section 4.4.5, Condition Handling.

MACRO-32

$DS_PRINTSIG_G

argptr

(Only the _G form of the macro is supported.)

BLISS-32

$DS_PRINTSIG

ARGUMENTS

RETURN

STATUS

(ARGPTR = argptr);

argptr

Address of the signal array.

SS$_NORMAL

Service successfully

SS$_RESIGNAL

The VDS does not support condition handling for

completed.

comp

the detected condition. The signal array will not be

displayed. The following conditions will always result
in this return status:

SS$PAGRDERR, SS$_FAIL,

SS$_DEBUG, and SS$_ARTRES.

MACRO-32

EXAMPLE

These examples illustrate use of the macro within a condition handler.
Condition handlers receive the signal array address as the first argument
on the argument stack.

$DS_PRINTSIG_G

@4(AP)

;Display signal

array

BLISS-32

EXAMPLE
$DS_PRINTSIG

5-262

(ARGPTR =

.(.AP +

4));

!Display

signal

array

$DS_PRINTX

$DS_PRINTX
The Format and Print ASCIl Message system services provide a means by
which complex messages can be formatted into ASCII character strings
and displayed on the user terminal. The macros that call these services
are commonly referred to as the ‘‘print’’ macros. These macros can be
used to

Insert variable character string data into an output string

Convert binary values into the ASCIl representations of their decimal,
hexadecimal, or octal equivalents and substitute the results in an
output string

The system services construct an output string by referring to formatted
ASCII output (FAQ) directives contained in a ‘‘control string’’ and using
those directives to operate on the contents of value parameters.

Once the system service creates the output string, it is automatically
displayed on the user terminal.

The $DS_PRINTX macro (‘‘print extended error message’’) is used
exclusively to display the third message level of error messages (see
Section 3.9, Reporting Errors). Display of messages generated with this
macro will be inhibited if the VDS control flag IE3 is set (see the VAX/DS
Diagnostic Supervisor User’s Guide).

MACRO-32

$SDS_PRINTX_x format, [p0], [p1], [P2], [P3], .[p4], [p5],

BLISS-32

$DS_PRINTX (format, [p0], [p1], [p2], [P3], [p4]; [p5],‘

ARGUMENTS

[p6], [P7], [P8], [PY], [Pa], [Pb], [pc],
[pd], [pel, [pf]

[p6], [p7], [P8], [PY9I, [Pal, [Pb], [pcl, [pd],
[pel, [pf]);

format

Address of a counted ASCII string. This is the ““control string,”” which
consists of the fixed text of the output string plus FAO directives for
formatting variable data. FAO directives are listed in Table 5-7. Variable
data is passed in parameters p0 through pf.

pO0 through pf

5-263

$DS_PRINTX

RETURN

SS$_NORMAL
|

STATUS

S§S$_BUFFEROVF

Servi_

full

leted

ervice successfully completed.

Service successfully completed, but the size of the

output string was greater than the maximum allowed

and was truncated (see notes).

SS$_BADPARAM

An invalid FAQ directive was specified in the control
string.

NOTES

VDS stores the output string in an internal buffer as it is being created.
This buffer can contain up to 512 characters. If the output string is

greater than 512 characters, the string is truncated and the truncated
message is displayed.
2

If it is necessary to format a message containing more than 16

parameters, it is possible to

Use several PRINT macros in succession, or

Use the $FAO or $FAOL macros.to format the message. The
message should then be printed using the proper print macro (for

example, PRINTX for a level 3 error message).

In a multiprocessing environment, $DS_PRINTxxx cannot be called

from within a block of code delineated by the $DS_BGNATTACHED

and $DS_ENDATTACHED macros.
5

FAOQO Directives. See Note 5 of the $DS_PRINTB macro.

MACRO-32
EXAMPLE
PC

The following examples will display this message:

Failure:

ERROR Address:

453AE(X)
11B6(X)

SCB Vector:

10(X)

Error

5900(D)

Code:

Error_Msg_Level3:

«ASCIC

\!/PC

at Failure:!_!AC(X)\-

\!/Error Address:!_!AC(X)\\!/SCB Vector:!_ !AC(X)\\!/Error Code:!_ !AC(D)\
$DS_PRINTX_S

5-264

ErrorMsg_level3,R11,R10,R8,R7

$DS_PRINTX

{5
U

BLISS-32
EXAMPLE
LOCAL

FAIL_PC,
ERR_ADR,

SCB_VEC,
ERR_CODE;
BIND

ErrorMsg_Level3 =

UPLIT

(%ASCIC
.
.
.

\!/!\PC at Failure:!_!AC (X)\\!/ Error Address:!_!AC (X)\\!/ SCB Vector:!
!AC (X)\\!/ Error Code:!-!AC (D)\)

$DS_PRINTX (ErrorMsg_Level3,

.FAIL_PC,

.ERR_ADR,

.SCB_VEC,

.ERR_CODE);

5-265

$DS_PROBE

$DS_PROBE
The Probe Device Address system service of the VDS may be used to

determine if a device resides at a particular physical address. The service
is passed the address to be checked and the logical unit number of the
device that is expected to be at that address, and it will return a status
code indicating whether or not the address exists.

This service is only available to level 3 programs.

MACRO-32

$DS_PROBE_x

BLISS-32

$DS_PROBE

ARGUMENTS

address, length, unit

(ADDRESS = address, LENGTH = length,
UNIT = unit);

address
The physical address whose existence is to be determined.

length
Size of the location specified by “address.” Valid values are 1 for byte, 2
for word, and 4 for longword.

unit
Logical unit number of the device expected to be at the specified address.

RETURN

STATUS

SS$_NORMAL
-

S o

fully

ervice successfully

leted

completed.

comp”

An invalid value was specified for “‘length’’ or “‘unit”’.

DS$_MCHK

The specified address does not exist, or the device

existing at address does not respond.

5-266

DS$_ERROR

DS$_LOGIC

The device is not functioning correctly.

SS$_ACCVIO, DS$_TRANSL

Page tables do not allow access.

$DS_PROBE

MACRO-32
EXAMPLE

This example probes devices on a MASSBUS controller.

CLRL

R11

$DS_PROBE_S

(R10)[R11]
= #4

UNIT

Get MBA controller register
base address.

Init.
See if

address.

controller register pointer
the drive unit exists.

TMe

LOG_UNIT

“e

LENGTH

Get p-table

wme

ADDRESS =

R3
B~A"HP$A_DEVICE(R3),R10

PTABLE,

MOVL

Get p-table.

MOVL

PTABLE

LOG_UNIT,

$DS_GPHARD_S -

$DS_BERRCR ERR10

(Continue)

(Report error - device not there.)

ERR10:

00—

BLISS-32

EXAMPLE

$DS_GPHARD (UNIT=.LOG_UNIT, RETADR=PTABLE);
CONTROLLER_BASE = .PTABLE [HPSA _DEVICE];
DEVICE_ADDR =
WHILE

.CONTROLLER_BASE;

.DEVICE_ADDR LSS

LAST_DEVICE

BEGIN

IF NOT

$DS_PROBE

(ADDRESS=.DEVICE_ADDR,
LENGTH=4,

THEN BEGIN

UNIT=.LOG_UNIT)

...Report error - drive not there...

ELSE DEVICE_ADDR =

END

.DEVICE_ADDR + NEXT_DEVICE

END;

5-267

$DS_PSLDEF

$DS_PSLDEF
The $DS_PSLDEF macro defines (for MACRO-32 programs) symbolic
names for fields of the process status longword. For BLISS-32 programs,

these symbols may be referenced without first issuing the $DS_PSLDEF
macro.

Symbols defined are:
PSLS$V_CBIT

PSL$SM_CBIT

PSL$V_VBIT

PSL$M_VBIT

PSLSV_ZBIT

PSLSM_ZBIT

PSL$V_NBIT

PSL$SM_NBIT

PSL$K_KERNAL
PSLSK_EXEC

PSL$K_SUPER
PSL$K_USER

MACRO-32

$DS_PSLDEF

ARGUMENTS

gbl

MACRO-32
EXAMPLE
$DS_PSLDEF GLOBAL

5-268

[gbl]

$DS_PTDDEF

$DS_PTDDEF
The $DS_PTDDEF macro defines (for MACRO-32 programs) symbolic
names for the flags associated with the $DS_$NAME p-table descriptor
macro. For BLISS-32 programs, these symbols may be referenced without
first issuing the $DS_PTDDEF macro.

Symbols defined are:
PTD$M_UNIT
PTD$M_CONTROLLER

PTDSV_UNIT

PRE
PTD$M_INHERIT
CON
PTD$M_INHERIT

PTDSV_INHERIT_PRE
PTD$V_INHERIT_CON

PTDS$M_NAME

PTD$V_CONTROLLER

PTDSV_NAME

PTD$M_INHERIT

PTD$M_DEVICE

PTDS$V_ENDDEVICE

50—

MACRO-32

$DS_PTDDEF

MACRO-32
EXAMPLE
$DS_PTDDEF

5-269

$Qlo

$QI0O—$QIOW
The Queue I/O Request system service ($QIO) initiates an /O operation
in user mode by queueing a request to an I/0O channel. The channel
must have been previously assigned with $ASSIGN service. Once the I/0O

request has been queued, control returns to the caller. Notification that
the 1/0 operation has completed can be accomplished by one of three
methods:
*

An AST routine can be caused to execute when I/O has completed.

The diagnostic program can specify that an event flag be set when 1/0
has completed.

The diagnostic program can specify that an |/0 status block be filled in

when /0 has completed.

These methods for notification of /0 completion are discussed in

Section 4.2.1.1, I/O in User Mode.
The Queue /O Request and Wait for Event Flag system service ($QIOW)
combines the operations of the $QIO and $WAITFR (Wait for Single Event
Flag) system services.
The $QIO and $QIOW services may not be used by level 3 programs.

MACRO-32

$QI0_x

efn, chan, func, [iosb], [astadr], [astorm], [p1],

[p2], [p3], [P4], [PS], [PE]
BLISS-32

$QI0

(EFN =efn, CHAN =chan, FUNC = func,
[IOSB = iosb], [ASTADR = astadr],
[ASTPRM = astprm], [P1=p1], [P2 =p2],

[P3=p3], [P4 =p4], [P5=p5], [P6=pb]);
ARGUMENTS

efn

Number of the event flag that is to be set at request completion.
Note: If an event flag is not specified, the default is 0. Since event flag 0 is

used by the VDS, a nonzero value for this parameter must ALWAYS be

specified, for both the $QIO and the $QIOW macros, whether or not the
diagnostic program actually tests this flag as a means of determining that
the 1/O operation has completed.

chan
Number of the 1/O channel assigned to the device to which the request is
directed. Obtained by using the $ASSIGN macro.

5-270

$QlI0

func
Function code and modifier bits that specify the operation to be performed.
An introduction to function codes is provided in Section 4.2.1.1, I/O in

User Mode. Complete documentation of function codes is located in the
VAX/VMS 1/0 User’s Guide.

iosb
Address of a quadword I/O status block that is to receive final completion
status. See ‘’Synchronizing I/O Completion” in Section 4.2.1.1, I/O in User
Mode.

astadr
Address of the entry mask of an AST routine to be executed when the I/O
completes. The AST routine will execute at the access mode from which

the $QIO macro was issued. See ‘’Synchronizing I/O Completion” in
Section 4.2.1.1, I/O in User Mode.

astprm
AST parameter to be passed to the AST routine. See Section 4.4.3.

p1to pb6
Optional device- and function-specific parameters. Refer to the VAX/VMS
I/0 User’s Guide.

The first parameter may be specified as “‘p1’” or as ’plv,”” depending on
whether an address or a value is required, respectively. If the keyword
is not used, ““p1”’ is the default and the argument is considered to be an
ADDRESS.
P2 through P6 are always interpreted as VALUES.

RETURN

STATUS

_|
SS$_NORMAL

ervice successfully
Semi
full completed.
leted. The The /O reques t

SS$_ABORT

A network logical link was broken.

SS$_ACCVIO

The 1/0 status block cannot be written by the caller.

packet was successfully queued.

This status code may also be returned if parameters

for device-dependent function codes are incorrectly

specified.
SS$_DEVOFFLINE

The specified device is offline.

SS$_EXQUOTA

The process has exceeded its butfered I/0 quota,
direct /0 quota, or buffered I/O byte count quota

and has disabled resource wait mode with the Set

Resource Wait Mode ($SETRWM) system service; or
the process has exceeded its AST limit quota.

SS$_ILLEFC
SS$_INSFMEM

An illegal event flag number was specified.
Insufficient system dynamic memory is available to
complete the service, and the process has disabled
resource wait mode with the Set Resource Wait

Mode ($SETRWM) system service.

5-271

SS$_IVCHAN

An invalid channel number was specified; that is, a
channel number of 0 or a number larger than the
number of channels available.

NOTES

SS$_NOPRIV

The specified channel does not exist or was

SS$_UNASEFC

The process is not associated with the cluster

assigned to a more privileged access mode.
containing the specified event flag.

See the VAX/VMS System Services Reference Manual for discussions of
privilege restrictions, resource requirements, and other notes relating to
the $QIO and $QIOW macros.

MACRO-32
EXAMPLE
$QIO_S

EFN=#1,

CHAN=TTCHAN1,

sEvent flag

;Channel

FUNC=#I0S_WRITEBLK,

;Virtual write function

P1=BUFADD, -

;:Buffer

P2=#BUFSIZE

;Buffer size

address

BLISS-32
EXAMPLE
IF NOT

(STATUS=$QIOW

(EFN=32, CHAN=.LOG_UNIT,
FUNC=IO$_SETMODE OR IO$M_ATTAST,
I0SB =

SETMODE_IOSB,

P1=ATNAST)

THEN
BEGIN

(Report
END;

5-272

error.)

$QIOwW

$QIOW—-$QIO
The Queue I/0 Request system service ($QIO) initiates an 1/O operation
in user mode by queueing a request to an I/O channel. The channel
must have been previously assigned with $ASSIGN service. Once the I/0O

request has been queued, control returns to the caller. Notification that

the 1/O operation has completed can be accomplished by one of three
methods:

An AST routine can be caused to execute when I/O has completed.

The diagnostic program can specify that an event flag be set when /O

has completed.
*

The diagnostic program can specify that an 1/0 status block be filled in

when 1/O has completed.
These methods for notification of I/O completion are discussed in

Section 4.2.1.1, 1/O in User Mode.
The Queue I/O Request and Wait for Event Flag system service ($QIOW)
combines the operations of the $QIO and $WAITFR (Wait for Single Event

Flag) system services.
The $QIO and $QIOW services may not be used by level 3 programs.

MACRO-32

$QIOW_x

efn, chan, func, [iosb], [astadr], [astprm],

[p1], [P2], [P3], [P4], [P5], [P6]
BLISS-32

$QIOW

(EFN =efn, CHAN =chan, FUNC = func,

[IOSB =iosb], [ASTADR = astad],
[ASTPRM = astprm], [P1=p1], [P2 = p2],

[P3=p3], [P4=p4], [P5=pb], [P6 = pE]);
ARGUMENTS

efn
Number of the event flag that is to be set at request completion.

Note: If an event flag is not specified, the default is 0. Since event flag 0 is
used by the VDS, a nonzero value for this parameter must ALWAYS be

specified, for both the $QIO and the $QIOW macros, whether or not the
diagnostic program actually tests this flag as a means of determining that
the I/O operation has completed.

chan
Number of the 1/O channel assigned to the device to which the request is
directed. Obtained by using the $ASSIGN macro.

5-273

$QIOW

func
Function code and modifier bits that specify the operation to be performed.
An introduction to function codes is provided in Section 4.2.1.1, I/O in
User Mode. Complete documentation of function codes is located in the
VAX/VMS 1/O User’s Guide.

iosb
Address of a quadword I/O status block that is to receive final completion
status. See ‘’Synchronizing I/O Completion” in Section 4.2.1.1, I/O in User
Mode.

astadr

Address of the entry mask of an AST routine to be executed when the I/O
completes. The AST routine will execute at the access mode from which
the $QIO macro was issued. See ‘’Synchronizing I/O Completion” in
Section 4.2.1.1, I/O in User Mode.

astprm
AST parameter to be passed to the AST routine. See Section 4.4.3.

p1to p6
Optional device- and function-specific parameters. Refer to the VAX/VMS
I/0 User’s Guide.

The first parameter may be specified as ““p1”” or as “’plv,”” depending on
whether an address or a value is required, respectively. If the keyword
is not used, ““pl”’ is the default and the argument is considered to be an
ADDRESS.

P2 through P6 are always interpreted as VALUES.

RETURN
STATUS

SS$_NORMAL

Service successfully completed. The /0O request
packet was successfully queued.

SS$_ABORT

A network logical link was broken.

SS$_ACCVIO

The VO status block cannot be written by the caller.
This status code may also be returned if parameters
for device-dependent function codes are incorrectly

specified.

SS$_DEVOFFLINE

The specified device is offline.

SS$_EXQUOTA

The process has exceeded its buffered I/O quota,
direct I/O quota, or buffered 1/0 byte count quota
and has disabled resource wait mode with the Set
Resource Wait Mode ($SETRWM) system service; or

SS$_ILLEFC

An illegal event flag number was specified.

the process has exceeded its AST limit quota.

SS$_INSFMEM

Insufficient system dynamic memory is available to
complete the service, and the process has disabled
resource wait mode with the Set Resource Wait
Mode ($SETRWM) system service.

5-274

$Qiow

SS$_IVCHAN

An invalid channel number was specified; that is, a
channel number of 0 or a number larger than the
number of channels available.

NOTES

SS$ _NOPRIV

The specified channel does not exist or was
assigned to a more privileged access mode.

SS$_UNASEFC

The process is not associated with the cluster
containing the specified event flag.

See the VAX/VMS System Services Reference Manual for discussions of
privilege restrictions, resource requirements, and other notes relating to
the $QIO and $QIOW macros.

Two potential problems exist when the $QIOW service is used:
e

If the I/O device is malfunctioning, the event flag may never be set
and service will never return to the diagnostic program.

If the I/O device is slow or overloaded, the restriction that controlCs be checked at least every three seconds may be violated (see
Section 4.4.6, Handling Control-Cs).

It is therefore better for diagnostic programs to use the $QIO and
$WAITFR services. Additionally, the $SETIMR service should be used

to limit the amount of time in which the program will wait for the event
flag, in case it never becomes set.

MACRO-32
EXAMPLE
$QIO_S

EFN=%#1,

CHAN=TTCHAN1,

:Event
-

flag

:Channel

FUNC=#I0$_WRITEBLK,

;Virtual write

P1=BUFADD, -

;Buffer address

P2=#BUFSIZE

sBuffer size

function

BLISS-32
EXAMPLE
IF NOT

(STATUS=S$QIOW

(EFN=32,

CHAN=.LOG_UNIT,

FUNC=IO$_SETMODE OR IO$SM_ATTAST,
IOSB =

SETMODE_IOSB,

Pl=ATNAST)

THEN

BEGIN
(Report

error.)

END;

5-275

$RAB

$RAB
The $RAB macro is used to allocate an RMS record access block (RAB)
at program compilation time and, optionally, to load values into the various
fields within the RAB. An RAB is a data structure that is required for

performing file management operations using RMS. Refer to Section 4.5,
File Management.

This description only discusses RAB fields supported by VDS RMS. For

a discussion of VMS RMS-supported fields, refer to the VAX/YMS RMS
Reference Manual.
Besides allocating the RAB, the $RAB macro aiso defines symbols for

each RAB field. Symbols are of the form ‘‘RAB$datatype_fieldname,"’
where ‘‘datatype’’ is a data type specifier listed in Table 6-1.

MACRO-32

SRAB

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

$RAB

(BKT = bkt-code,
FAB = fab-address,
RAC =rac-param,

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

UBF = user-buffer-address,

USZ = user-buffer-size);
T

ARGUMENTS

BKT = bkt-code

Bucket code. Used only with block I/O. Should be loaded with the number
of the first virtual block that is to be read by the $READ service. If 0 is
specified, reading will begin at block 0 for the first SREAD, or at the block
pointed to by the internal ‘“'next block pointer” for subsequent $READs.

FAB = fab-address
Address of the FAB describing the file to be accessed.

5-276

$RAB

RAC = rac-param
Record access mode. Indicates the type of access to be used in retrieving
records from the file. Valid values are

SEQ — Sequential record access. This is the defauit.

RFA — Random access by record’s file address (RFA).

Refer to Section 4.5.6, Record Processing, and Note 2 below.

RHB = header-buffer-address
Address of buffer to store record header buffer. Used only for files

consisting of variable records with fixed-length control. The $GET service
will load the record’s header into the specified buffer. The size of this
buffer must match the size specified by the FSZ field of the FAB.

ROP = BIO
Block I/O. Only meaningful if BRO was set in the FOP field of the FAB

before $OPEN was issued. If so, then setting the BIO record processing
option will enable record processing and block processing to be mixed.

UBF = user-buffer-address
Address of a buffer to receive record fetched by $GET or block fetched by
$READ. Buffer size is specified with USZ.

USZ = 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 under
VDS RMS. They are filled in by RMS services, and may be read after

the service has completed. (Some of these fields are read/write in VMS
RMS.)
e

BID — Block identifier field. Identifies the block as a RAB.

BLN — Block length field. Contains the length of the RAB.

ISI — Internal stream identifier. Associates the RAB with an FAB.

RBF — Contains the address of the last record read.

RFA — Record’s file address. File address of last record read. See

Note 2.
®*

RSZ — Length, in bytes, of the last record read.

STS — Completion status code field. RMS services load this field
with a success or failure completion status before returning to the

caller of the service. The completion status code is also passed to
the caller in RO.

STV — Status value field. Sometimes used to pass additional status
information from a service to the caller.

5-277

$SRAB

Record’s File Address (RFA)

After a successful $GET operation, the file address of the record read
into memory is stored in the RFA field. The program can extract this
field and store it elsewhere in memory. Then if it is later necessary to

re-read the record, the program returns the extracted address to the
RFA, sets the record access mode to random-by-RFA (by setting RFA

in RAC), and issues another $GET.
The RFA field is six bytes long. There are two ways to reference the
field:

RAB$W_RFA is the field’s offset into the RAB. RAB$S_RFA is the
field’s size. Thus the field may be copied as follows:
MOVAL

RABBLK,

MOVC3

#RABSS_RFA,

RO
RABS$W_RFA(R0),

SAVE_RFA

RABSLRFAQ is the offset of the first longword of the six-byte field.
RAB$WRFA1 is the offset of the last word of the field. Thus the
field may be copied as follows:
MOVAL

RABBLK,

MOVL

RABSL_RFAO(RO),

SAVE_RFA

MOVW

RABSW_RFA4(R0),

SAVE_RFA+4

Table 5-10 lists all of the RAB fields.
Table 5-10

RAB Fields

Field and
Keyword

5-278

Name

Field Size

Description

Offset

BID

Byte

Block identifier

RAB$B_BID

BKT

Longword

Bucket code

RABSL_BKT

BLN

Byte

Block length

RAB$B_BLN

CTX

Longword

Context

RABS$L_CTX

FAB

Longword

File access block address

RABS$L_FAB

ISI

Word

Internal stream identifier

RABS$W_ISI

KBF

Longword

Key buffer address

RABS$L_KBF

KRF

Byte

Key of reference

RAB$B_KRF

MBC

Byte

Multiblock count

RAB$B_MBC

MBF

Byte

Muttibuffer count

RAB$B_MBF

PBF

Longword

Prompt buffer address

RABSL_PBF

PSZ

Byte

Prompt buffer size

RAB$B_PSZ

RAC

Byte

Record access mode

RAB$B_RAC

RBF

Longword

Record address

RABS$L_RBF

RFA

3 words

Record’s file address

RABS$W_RFA

RHB

Longword

Record header buffer

RAB$L_RHB

ROP

Longword

Record-processing options

RABS$L_ROP

RSz

Word

Record size

RAB$W_RSZ

$RAB

Table 5-10 (Cont.)

RAB Fields

Field and

Keyword

Name

Field Size

Description

Otfset

STS

Longword

Completion status code

RABS$L_STS

STV

Longword

Status value

RABSL_STV

STVO

Word

Low-order word of status

RAB$W_STVO

value

STV2

Word

High-order word of status

RAB$W_STV2

value

TMO

Byte

Timeout period

RAB$B_TMO

UBF

Longword

User record area address

RABS$L_UBF

uUsz

Word

User record area size

RAB$W_USZ

10—

MACRO-32
EXAMPLE
.BLKB 50

BUFFER:
BUF_SIZE

BUFFER

FAB_BLOCK:

$FAB

FNM=<INFILE.DAT>

RAB_BLOCK:

$SRAB

FAB=FAB_BLOCK,
RAC=SEQ,

UBF=BUFFER,

USZ=BUF_SIZE

0
—

BLISS-32
EXAMPLE
LITERAL

BUF_SIZE = 50;
OWN

BUFFER
FAB_BLOCK

:
:

VECTOR
S$FAB

RAB_BLOCK

$RAB

[BUF_SIZE, BYTE],
(FNM='FILE1.DAT'),
( FAB=FAB_BLOCK,
RAC=SEQ,
UBF=BUFFER,
USZ=BUF_SIZE);

5-279

SRAB_INIT

The $RAB_INIT macro can be used to load RAB fields at run time in

BLISS-32 programs. Refer to the discussion of the $RAB macro for a

description of RAB fields.

BLISS-32

$RAB_INIT

(RAB =rab-address,
BKT

= bkt-code,

FAB = fab-address,

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

ROP = BIO,
UBF = user-buffer-address,

USZ = user-buffer-size);
Refer to the discussion of the $RAB macro for descriptions of input
parameters. With the exception of RAB_address, all parameters are

optional.

e
RREEEEEE——

BLISS-32
EXAMPLE
OWN

IN_RAB:

$RAB(FAB=IN_FAB);

L.OCAL
INBUF

VECTOR

SRAB_INIT

[50,

BYTE];

(RAB=IN_RAB,
UBF=INBUF,

5-280

UBZ=BUF_SIZE);

$RAB_STORE

$RAB_STORE
The $RAB_STORE macro can be used to load RAB fields at run time for
MACRO-32 programs. Refer to the discussion of the $RAB macro for a
description of RAB fields.
X
——

MACRO-32

SRAB_STORE

RAB=rab-address,BKT = bkt-code,-

FAB = fab-address,RAC =rac-param,RHB = header-buffer-address,ROP = BIO,UBF = user-buffer-address,USZ = user-buffer-size
PRERRmmmmmmEE

MACRO-32
EXAMPLE
BUF_SIZE =

IN_RAB:

S$RAB

IN_BUF:

.BLKB

BUF_SIZE

$RAB_STORE

RAB=IN_RAB,

UBF=IN_BUF,

UBZ=#BUF_SIZE

5-281

$READ

SREAD
The Read File service of RMS is used to read a specified number of bytes,
starting at a block boundary, from a file. The file must have been opened
and connected, using the SOPEN and $CONNECT services, respectively.

MACRO-32

SREAD

rab, [err], [suc]

BLISS-32

$READ

(RAB=rab, [ERR =err], [SUC =suc]);

ARGUMENTS

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 is in the RAB.)

err (user mode only)
Address of a routine to be executed on error return from the service.

suc (user mode only)
Address of a routine to be executed on successful return from the service.

RETURN

ST ATU S

RMS$_NORMAL

Service successfully completed.

RMS$_EOF

Attempt was made to read beyond end of file.

RMS$_FAB

The FAB block is invalid.

RMSS$_IF!

The FAB'’s IFI field is invalid.

RMS$_ISI

The RAB’s ISl field is invalid.

RMS$_RAB

The RAB block is invalid.

RMS$_RER

Read error. (The device driver's return status will be
in the STV field of the RAB.)

Note: For further details on return status values, refer to the VAX-11 RMS
Reference Manual.

$READ

NOTES

Table 5-11 lists the RAB fields used by the $READ service in standalone
mode. For user mode, refer to the VAX-11 RMS Reference Manual.

Table 5-11

RAB Fields Used by $READ (Standalone Mode)

Field Mnemonic

Field Name

Input:

BKT

Bucket number. Must contain the virtual block number of
the first block to be read.

ISI

Internal stream identifier.

UBF

User record area address. This is where the block will be
stored.

uSsSZz

User record area size. Indicates length of the transfer, in
bytes.

Output:
RBF
RFA

Record address.

Record’s file address. Contains the virtual block number of
the first block transferred.

RSz

Record size. Indicates the actual number of bytes
transferred.

STS

Completion status code. (Also contained in RO.)

STV

Status value. (See Return Status, above.)

)
B

MACRO-32
EXAMPLE
SREAD RAB=RAB_BLOCK

= =

BLISS-32
EXAMPLE
$READ (RAB=RAB_BLOCK);

5-283

SREADEF

SREADEF
The $READEF macro is used to obtain the current status of all flags within
an event flag cluster. Event flags are discussed in Section 4.4.2.

MACRO-32
FORMAT:

$SREADEF_x

BLISS-32

$READEF

ARGUMENTS

efn, state

(EFN =efn, STATE = state);

efn
Number of any event flag within the cluster to be read. A flag of number 1
through 31 specifies cluster 0, and a flag of number 32 through 63 specifies

cluster 1.

state
Address of a longword to receive the status of all event flags within the
cluster.

RETURN

STATUS

SS$_WASCLR
2

SS$_WASSET

full

leted. Th

ervice successfully completed.

flag is clear. User mode only.

fied

e specified

event

Service successfully completed. The specified event
flag was set. User mode only.

SS$_NORMAL

Service successfully completed. Standalone mode

SS$_ACCVIO

The address specified in the ‘‘state’” parameter

only.

could not be written by the caller. User mode only.

SS$_ILLEFC
SS$_UNASEFC

An illegal event flag number was specified.
In user mode, indicates that the specified common
event flag (see Section 4.4.2) has not been
associated with the process issuing the $CLREF
macro.

In standalone mode, indicates that an event flag

from 64 through 127 was specified. These flags are

not valid in standalone mode.

5-284

$READEF

MACRO-32
EXAMPLE
SREADEF_S

FLAGS

BLISS-32
EXAMPLE
SREADEF

(EFN=3,

STATE=FLAGS);

5-285

$DS_RELBUF

$DS_RELBUF
The $DS_RELBUF macro is used to deallocate buffer space that was
previously obtained with the $DS_GETBUF macro. The pages deallocated
will be the pages that were most recently allocated. In user mode, the
VDS calls the VMS $CNTREG service (see the VAX/VMX System Services
Reference Manual).

MACRO-32

$DS_RELBUF_x

BLISS-32

$DS_RELBUF

pagcnt, [retadr], [region]

(PAGCNT =pagcnt,
[RETADR = retadr],

[REGION = region]);
ARGUMENTS

pagcent

Size (number of pages) of buffer space to be deallocated.

retadr
Address of a 2-longword array to receive virtual addresses of low and high
limit of address space deallocated.

region
Memory region from which caller wishes buffer space to be deallocated.

Values are:

0: buffer allocated from PO space. (Default.)
1: buffer allocated from P1 space.
2: buffer allocated from system space.
In standalone mode, this parameter is only relevant if memory
management is enabled.

5-286

$DS_RELBUF

“

RETURN

STATUS

SS$_NORMAL

Buffer space deallocated.

SS$_ACCVIO

The “‘retadr’’ array cannot be written by the caller.

DS$_FRAGBUF

The deallocated space was not contiguous. This

User mode only

condition could only exist if the specified page count
was greater the page count specified with the most
recently issued $DS_GETBUF macro, since space is
always allocated in contiguous chunks in standalone
mode. Standalone mode only.

SS$_ILLPAGCNT

The specified page count was less than 1.

SS$_PAGOWNVIO

In user mode, indicates that a page in the specified
range is owned by a more privileged access mode.

In standalone mode, indicates that an attempt was
made to deallocate more pages than had been
previously allocated with GETBUF macros.
B

MACRO-32
EXAMPLE

BUF_LIMITS:
.QUAD

$DS_RELBUF #10,

BUF_LIMITS

;Release 10 pages.

BLISS-32

EXAMPLE:

OWN

VECTOR

[2];

BUF_LIMITS

$DS_RELBUF

(PAGCNT=10,

RETADR=BUF_LIMITS);

5-287

$DS_SBTTL

$DS_SBTTL
The $DS_SBTTL macro should be used at the beginning of each test and

subtest. It will perform the following functions:
e

It will generate text containing the test and subtest numbers, along
with the contents of a programmer-specified character string. This text

will be included in a .SBTTL 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 is set.
*

If the macro is at the beginning of a test, a new program section
(PSECT) is assigned to the test. (A subtest will be included in the
PSECT of the test to which it belongs.)

The code of the test or subtest will be aligned as specified by the
programmer.

MACRO-32

$DS_SBTTL

BLISS-32

Not supported for BLISS-32.

ARGUMENTS

ascii, [align]

ascii

Character string representing text to be used as program subtitle and to be
displayed when VDS TRACE flag is set.

align
Desired program section alignment for the test or subtest. Possible values
are BYTE, WORD, LONG, QUAD, PAGE, or an integer from 0 to 9. If an
integer is specified, the psect will start at the next address that is a multiple
of two raised to the power of the integer.

NOTES

The $DS_SBTTL macro should be used in conjunction with the

$DS_PAGE macro.

EXAMPLES
$DS_SBTTL -

5-288

ALIGN

BYTE,

ASCITI

<READ/WRITE

SWAP

DATA

TEST>

$DS_SCBDEF

$DS_SCBDEF
The $DS_SCBDEF macro defines (for MACRO-32 programs) symbolic
names for the vector offsets in the system control block. For BLISS-32
programs, these symbols may be referenced without first issuing the
$DS_SCBDEF macro.
Symbols defined are:
SCBS$L_ZERO

SCBS$IL,_MACHCK

SCB$L_KNLSTK

SCBSL_POWER

SCB$L_OPCDEC

SCB$I,_OPCCUS

SCB$L_ROPRAND

SCB$I,_RADRMOD

SCB$L_ACCESS

SCBSL_TRANSL

SCB$L_TBIT

SCB$L_BREAK

SCB$L_COMPAT

SCB$L_ARITH

SCB$L_CHMK

SCB$L_CHME

SCB$L_CHMS

SCBS$I,_CHMU

SCB$L_SFTLVL1

SCB$L_SFTLVL2

SCBS$I,_SFTLVL3

SCBS$IL_SFTLVL4

SCB$L_SFTLVLS

SCB$L_SFTLVL6

SCBS$I,_SFTLVL7

SCBS$IL_SFTLVLS

SCB$L_SFTLVLY

SCBS$L_SFTLVL10

SCB$I_SFTLVL11

SCB$I,_SFTLVL12

SCB$L_SFTLVL13

SCB$I_SFTLVL14

SCBS$L_SFTLVL15

SCB$L_TIMER

MACRO-32

$DS_SCBDEF

ARGUMENTS

gbl

[gbl]

Can be LOCAL or GLOBAL

MACRO-32
EXAMPLE
$DS_SCBDEF GLOBAL

5-289

$DS_SECDEF

$DS_SECDEF
The $DS_SECDEF macro is used to declare all of the names of the test
sections (see Section 3.8.3) of the diagnostic program. This macro must
appear in every source module that contains tests. The macro is used in
conjunction with the $DS_SECTION macro.

MACRO-32

$DS_SECDEF

A, [B,C,D,E F, G H, I J K L M N,
O, P]

--III--II-IIIlIIIIlIII--I-I--II---I--IIIlII--lIIIIIIIIIIIII-IIII-I---I

III-I--.

BLISS-32

$DS_SECDEF

(A, [B,C,D,E, F,G H,I,J K L, M, N,

O, P));
ARGUMENTS

A,B,...,O,P
List of 1 to 16 test section names. This list must be identical to the list
included with the $DS_SECTION macro, even if the module in which the

$DS_SECDEF macro is being placed does not include tests belonging to

every listed section.

NOTES

The macro automatically includes the section name DEFAULT at the

beginning of the section name list.

The test section names must appear in capital letters.

MACRO-32
EXAMPLE
$DS_SECDEF READTESTS,

WRITETESTS,

SEEKTESTS

BLISS-32
EXAMPLE
$DS_SECDEF

(READTESTS,

WRITETESTS,

SEEKTESTS) ;

$DS_SECTION

$DS_SECTION
The $DS_SECTION macro is used to declare all of the names of the test
sections (see Section 3.8.3) of the diagnostic program. This macro must
appear in the source module that contains the $DS_HEADER macro.
The $DS_SECTION macro is used in conjunction with the $DS_SECDEF
macro.

MACRO-32

$DS_SECTION

A, [B,C,D E F,G H, I, J K L M,N,

BLISS-32

$DS_SECTION

(A, [B,C,D,E,F,G H, I, J K L MN,

ARGUMENTS

A,B,...,O,P

O, P]

O, P));

List of 1 to 16 test section names. This list must be identical to the list

included with the $DS_SECDEF macro.

NOTES

1
2

The macro automatically includes the section name DEFAULT at the

beginning of the section name list.

The test section names must appear in capital letters.

MACRO-32
EXAMPLE
$DS_SECTION READTESTS,

WRITETESTS,

SEEKTESTS

BLISS-32
EXAMPLE
$DS_SECTION

(READTESTS,

WRITETESTS,

SEEKTESTS);

5-291

$SETAST

$SETAST
The Set AST Enable system service is used to enable and disable the

delivery of ASTs to the diagnostic program.

MACRO-32

$SETAST_x

BLISS-32

$SETAST

ARGUMENTS

enbflg

(ENBFLG = enbflg),

enbfi
AST enable indicator. A value of 1 enables AST delivery, while a value of
0 disables AST delivery.

RETURN

STATUS

SS$_WASCLR

Service successfully completed. AST delivery was

SS$_WASSET

Service successfully completed. AST delivery was

previously disabled.

‘

previously enabled.

For notes on enabling and disabling AST delivery in user mode, refer
to the VAX/VMS System Services Reference. Manual.

€

N
;Enable delivery of ASTs

2
N

SSETAST_S

(1)

mow

23
>0
%:n
- Q

EXAMPLE

$SETAST

-292

(ENBFLG=0);

!Disable delivery of ASTs

$SETEF

$SETEF
The Set Event Flag system service is used to set event flags. (Event flags
are discussed in Section 4.4.2.)

MACRO-32

x
$SETEF

BLISS-32

$SETEF

ARGUMENTS

efn

(EFN =efn);

efn

Number of the event flag to be set. In user mode, the number may be
from 1 through 23 or from 32 through 127. In standalone mode, flags 1
through 64 may be used.

RETURN

Service successfully completed. The specified flag

SS$_WASCLR

STATUS

was previously 0.

Service successfully completed. The specified flag

SS$_WASSET

was previously 1.

An illegal event flag number was specified.

SS$_ILLEFC

In user mode, indicates that the specified common

SS$_UNASEFC

event flag (see Section 4.4.2) has not been

associated with the process issuing the $SETEF
macro.

In standalone mode, indicates that an event flag
from 64 through 127 was specified. These flags are
not valid in standalone mode.

MACRO-32
EXAMPLE
SSETEF_S #4

;Set event flag number 4.

BLISS-32
EXAMPLE
SSETEF

(EFN=4);

!Set

event flag number

5-293

$SETIMR

$SETIMR
The Set Timer system service allows the caller to request that an event flag

be set, and optionally that an AST be delivered, after a specified amount

of time has elapsed.

It is possible to make a number of concurrent timer requests. The caller
will be notified (via event flag and AST delivery) when each specified time

interval has completed.

MACRO-32

$SETIMR_x

BLISS-32

$SETIMR

ARGUMENTS

efn, daytim, [astadr], [reqidt]

(EFN =efn, DAYTIM = daytim,
[ASTADR = astadr], [REQIDT = reqidt]);

efn

Number of the event flag to be set after the specified time has elapsed.
Note: If not specified, defaults to event flag 0, which will cause VDS errors.

daytim
Address of quadword containing expiration time. A positive value indicates
an absolute time at which the timer is to expire. A negative value indicates
an offset from the current time. In standalone mode, only negative values
are allowed. (See notes for specifying time.)

astadr
Address of the entry mask of an AST routine to be called when the
specified time interval expires. If not specified, defaults to 0, indicating no
AST routine is to be called.

reqidt
Identification number for the timer request. Default value is 0. A unique
number may be specified for each timer request, 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, if an AST routine is specified, the number will be passed to
the AST routine as the AST parameter.

5-294

$SETIMR

”

RETURN
STATUS

SS$_NORMAL

Service successfully completed.

SS$_ACCVIO

The expiration time cannot be read by the caller,

user mode only.

SS$_EXQUOTA
e

[n user mode:

Timer entry quota or AST limit quota exceeded, or
insufficient system dynamic memory to complete the
request.

In standalone mode:

The interval clock is already in use and hence is
unavailable to this system service.

An illegal event flag number was specified.
Insufficient dynamic memory to allocate a timer

SS$_ILLEFC
SS$$_INSFMEM

queue entry.

SS$_UNASEFC
¢

|n user mode:

Indicates that the specified common event flag (see
Section 4.4.2) has not been associated with the
process issuing the CLREF macro.
*

In standalone mode:

Indicates that an event flag from 64 through 127 was
specified. These flags are not valid in standalone
mode.

DS$_NOTIMP

An absolute time value was specified for “‘daytim.”

DS$_IPL2HI

The current IPL is too high. The IPL must be less

Only offset time values are allowed in standalone
mode. Standalone mode only.
than 2. Standalone mode only.

NOTES

;

To create a valid argument for the ““daytim”’ parameter, first specify
the time as an ASCII string, then use the $BINTIM macro to convert
the ASCII string into the quadword format required by the “daytim”
parameter.

You can also specify delta time values when you assemble a macro-32
program, using two MACRO .LONG directives to represent a time
value in terms of 100-nanosecond units. The arithmetic is based on the
following formula:

1 second = 10 million * 100 nanoseconds

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

.LONG -10*1000*1000*5, ~1 ; five seconds

The value 10 million is expressed as 10*1000*1000 for readability. Note
that the delta time value is negative.

5-295

$SETIMR

If you use this notation, however, you are limited to the maximum
number of 100-nanosecond units that can be expressed in a longword.

In terms of time values, this is somewhat more than seven minutes.

In user mode, if the specified absolute time has already passed, the
timer expires at the next clock cycle (within 10 milliseconds).
Each time the interval clock interrupts, the queue of timer requests
is scanned to determine if any of the specified time intervals have

expired. In standalone mode, the clock has been set up to interrupt

every 10 milliseconds when $SETIMR requests are being processed.

In standalone mode, do not attempt to use the $DS_WAITUS service

while $SETIMR requests are still pending.

In a multiprocessing environment, $SETIMR cannot be called from
within a block of code delineated by the $DS_BGNATTACHED and

$DS_ENDATTACHED macros.

IIlll-IIIlIlIIIIIIIIllIIIIIlIlllllllIlllIlllIIllIIIIIIllIlll

IllIIlllIlIIIllIllIIIIIIIIIIIIIIIIIIIIIIIII

MACRO-32

EXAMPLE
DAYTIME:
.QUAD

.ENTRY

AST_RTN,

;

AST

;jStore

64-bit

~M<R2,R3,R4>

routine.

RET

SSETIMR_S

5-296

#5,

DAYTIME,

AST_RTN

time

here.

$SETIMR

—

BLISS-32
EXAMPLE
OWN

DAYTIME

VECTOR

$SETIMR (EFN=8,

[2];

DAYTIM=DAYTIME);

5-297

$DS_SETIPL

$DS_SETIPL
The Set Interrupt Priority Level system service is used to change the

processor’s interrupt priorty level (IPL).

Only level 3 diagnostic programs are allowed to change the processor's
interrupt priority level. These programs may not change the IPL without

using this macro.

MACRO-32

$DS_SETIPL_x

BLISS-32

$DS_SETIPL

ARGUMENTS

/evel

(LEVEL =level),

Jevel
The level to which the IPL is to be set.

RETURN

SS$_NORMAL

STATUS

ervi
Servi

full

successfully

leted .

complete

“

MACRO-32

EXAMPLE
$DS_SETIPL_S

#31

;Set

IPL to 31

(decimal).

BLISS-32

EXAMPLE
$DS_SETIPL

(LEVEL=31);

tSet

IPL

to 31

(decimal).

$DS_SETMAP

$SDS_SETMAP
The Set Adapter Mapping system service of the VDS will set up the
mapping registers of a bus adapter so that data will be transferred to or
from the desired physical address space. The service may be used to set,
clear, validate, or invalidate an adapter’s mapping registers.

MACRO-32

$DS_SETMAP_x

unit, func, phyadr, [mapbas],
[bytcnt], [datpth]

BLISS-32

$SDS_SETMAP

(UNIT =unit, FUNC = func,
PHYADR = phyadr,

[MAPBAS = mapbas],
[BYTCNT

= bytcnt],

[DATPTH = datpth]),
ARGUMENTS

unit

Logical unit number of the device to be tested.

func
Function code indicating the function to be performed. Function codes are
listed in Note 1.

phyadr

Address of a 2-longword array that contains the physical addresses of the
beginning and the ending of the physical address space from which or to
which data is to be transferred. Commonly, this is the ““phyadr’” array
filled in by the $DS_GETBUF service. The value specified as the ending
address is used to validate the “bytcnt’” parameter.

mapbas
This argument is used to optionally select the first (lowest addressed)
map register to be employed in mapping virtual program addresses to
physical memory addresses. The service will start with the map register
specified and set up (or clear) enough map registers to map the address
range indicated by “phyadr”.

For a MASSBUS operation, the argument must be a value from 0 to 255
(decimal), where 0 selects the first map register, 1 selects the second, and
so on. The MBA Virtual Address Register will be automatically set up to
point to the specified map register.

For a UNIBUS operation, the argument must be a value from 0 to 495
(decimal), where 0 selects the first map register, 1 selects the second, and
SO on.

The default value is 0.

5-299

$DS_SETMAP

For descriptions of address translation in bus adapters, refer to the VAX
Hardware Handbook.

bytcnt
Number of bytes composing a data transfer. For MASSBUS operation, the
2’s complement of this value is stored in the MBA byte counter. Maximum
value allowed is 65535 (decimal).
For both MASSBUS and UNIBUS operation, this value is used when
setting up map registers — enough pages are mapped to handle the
number of bytes specified.

The default value is 0. If the default is used, one page (512 bytes) is

mapped.

datpth
Value indicating the UNIBUS data path. The default is 0, indicating the
direct data path. Values from 1 through 15 may be specified to select one
of the buffered data paths. This field is ignored if the UNIBUS adapter
does not support buffered data paths.
“

RETURN

STATUS

DS$_NORMAL

Servi

DS$_ERROR

The specified logical unit number is too large.

DS$_IHWE

fullTy

ervice successfully

leted ,

completed.

eon

Initial hardware error. A hardware error was detected
in the bus adapter before the specified function
was performed. The function was not performed.

Call the $DS_CHANNEL service, specifying the
CHC$_STATUS function to determine the error type.

$DS_PROGERR

An invalid function code was specified.
The byte count specified is too large to be mapped
starting at the specified map register. Lower the
byte count or lower the starting map register number.

The byte count specified will not fit into the buffer
limits indicated by ‘‘phyadr.”
“

NOTES

Function Codes
Following is a list of valid function codes. For MACRO-32, these codes
are defined by the $DS_CHMDEF macro.

CHMS$_INVALIDATE — Clear the “*valid”’ bits for all map registers
in the bus adapter to which the device unit specified by ““unit’ is

attached.

CHMS$_MFWDN — Set up map registers for a forward transfer
according to “’phyadr,”” “‘mapbas,”” and “‘bytcnt”’ parameters, and
set the “valid” bit in each register used. Do not invalidate any

registers. If MASSBUS, load MBA virtual address register and

MBA byte counter.

5-300

$DS_SETMAP

CHMS$_MFWDNO — Set up map registers for a forward transfer
according to ““phyadr,”” “‘mapbas,”” and ‘‘bytcnt” parameters, and
set the ““valid”’ bit in each register used. Do not invalidate any
registers. Indicate that a byte offset transfer will be performed
(UNIBUS only).

CHM$_MFWDV — Invalidate all map registers. Set up map

registers for a forward transfer according to ““phyadr,”” ““mapbas,”
and “bytcnt’’ parameters, and set the “*valid’” bit in each register
used. If MASSBUS, load MBA virtual address register and MBA
byte counter.

CHMS$_MFWDVO — Invalidate all map registers. Set up map

registers for a forward transfer according to “’phyadr,”” ““mapbas,’
and “‘bytcnt”’ parameters, and set the ““valid’’ bit in each register
used. Indicate that a byte offset transfer will be performed

(UNIBUS only).

CHM$_MREVN — Set up map registers for a reverse transfer
according to “‘phyadr,”” ““mapbas,”’ and “‘bytcnt’” parameters, and
set the ““valid’’ bit in each register used. Do not invalidate any
registers. If MASSBUS, load MBA virtual address register and
MBA byte counter.

CHM$_MREVNO — Set up map registers for a reverse transfer
according to “‘phyadr,” ““mapbas,”” and “‘bytcnt’” parameters, and
set the “‘valid’’ bit in each register used. Do not invalidate any
registers. Indicate that a byte offset transfer will be performed
(UNIBUS only).

CHM$_MREVV — Invalidate all map registers. Set up map

registers for a reverse transfer according to ““phyadr,”” “‘mapbas,”
and “’bytcnt’’ parameters, and set the “valid”’ bit in each register
used. If MASSBUS, load MBA virtual address register and MBA
byte counter.

CHM$_MREVVO - Invalidate all map registers. Set up map

registers for a reverse transfer according to ““phyadr,”” ““mapbas,”
and “‘bytcnt’’ parameters, and set the “valid”’ bit in each register
used. Indicate that a byte offset transfer will be performed
(UNIBUS only).

CHM$_NFWDN — Do not alter map register contents. If
MASSBUS, load MBA virtual address register and MBA byte
counter for forward transfer.

CHMS$_NREVN — Do not alter map register contents. If
MASSBUS, load MBA virtual address register and MBA byte
counter for reverse transfer.

In a multiprocessing environment, $DS_SETMAP cannot
be called from within a block of code delineated by the
$DS_BGNATTACHED and $DS_ENDATTACHED macros.

5-301

$DS_SETMAP

MACRO-32

EXAMPLE
BUF_SIZE

1024

LOG_UNIT:

.BLKL

BUFFER:

.BLKQ

$DS_SETMAP_S

LOG_UNIT,

#CHMS$_MFWDV,

BUFFER,,$#BUF_SIZE

BLISS-32

EXAMPLE
LITERAL
BUF_SIZE

1024;

OWN

LOG_UNIT

VECTOR,

BUFFER

VECTOR

$DS_SETMAP

[2];

(UNIT=,1OG_UNIT,

FUNC=CHM$_MFWDV,

PHYADR=BUFFER,

5-302

BYTCNT=BUF_SIZE);

$SETPRT

$SETPRT
The Set Protection on Pages system service allows a program to change
the protection code associated with one or more pages of virtual memory.

MACRO-32

SSETPRT

inadr, [retadr], [acmode], prot, [prvprt]

BLISS-32

$SSETPRT

(INADR =inadr, [RETADR = retadr],
[ACMODE = acmode], PROT = prot,
[PRVPRT = prvprt]),

ARGUMENTS

inadr

Address of a 2-longword array containing the starting and ending virtual
addresses of the pages for which the protection code is 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 is used; the low-order nine bits are ignored.

retadr
Address of a 2-longword array to receive the starting and ending virtual
addresses of the pages that had their protections changed. See Note 2.

acmode

Access mode on behalf of which the request is being made. The specified
access mode is maximized with the access mode of the caller. The result
must be equal to or more privileged than the access mode of the owner of
the pages being changed.
This parameter is ignored in standalone mode.

prot
New protection, in bits 0 through 3. Symbolic names for the various page
protection codes are described by the $PRTDEF macro which is defined in
STARLET.MLB.

prvprt
Address of a byte to receive the protection previously assigned to the last
page whose protection was changed. Useful if only one page was changed.

$SETPRT

RETURN

STATUS

SS$_NORMAL

Service successfully completed.

SS$_ACCVIO
e

User mode:
—

The input address array cannot be read by

the caller, or the output address array or
the byte to receive the previous protection

cannot be written by the caller.
—

An attempt was made to change the

protection of a nonexistent page.

Standalone mode:

The specified address range was in the reserved
virtual address space (C0000000 to FFFFFFFF).

SS$_EXQUOTA

The process exceeded its paging file quota while
changing a page in a read-only private section to a

read/write page. User mode only.

SS$_IVPROTECT

The specified protection code has a numeric value

of 1 or is greater than 15. User mode only.
SS$_LENVIO

In user mode, a page in the specified range is

beyond the end of the program or control region.
In standalone mode, a page in the specified range

is beyond the end of the program, control, or system
region.

SS$_NOPRIV

A page in the specified range is in the system

address space. User mode only.

SS$_PAGOWNVIO

Page owner violation. An attempt was made to

change the protection on a page owned by a more
privileged access mode. User mode only.

DS$_PROGERR

The specified address range was improperly

formatted. Standalone mode only.
e

NOTES

In standalone mode, setting page protection is only meaningful if
memory management has been enabled.

If an error occurs while changing page protections, the return array, if
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 minus one (-1).

5-304

$SETPRT

MACRO-32
EXAMPLE
ADDR_RANGE:

.BLKQ

$SETPRT

INADR=ADDR_RANGE,

PROT=#PRT$C_UW

BLISS-32

EXAMPLE
OWN

ADDR_RANGE

SSETPRT

VECTOR

[2];

(INADR=ADDR_RANGE,

PROT=PRTS$C_UW);

5-305

$DS_SETVEC

$DS_SETVEC
The Set Exception or Interrupt Vector system service is used to load an
exception or interrupt vector with the address of a service routine (see
Note 3).

Only level 3 diagnostic programs may use the $DS_SETVEC macro.
Vector contents may not be changed by any means other than the use of
this macro.

MACRO-32

$DS_SETVEC_x

BLISS-32

$DS_SETVEC

vector, srvadr, [code]

(VECTOR =vector, SRVADR = srvadr,

[CODE
= codg]);

ARGUMENTS

vector

The vector address, relative to the base of the System Control Block (SCB).
Refer to the VAX Architecture Handbook for a list of vector addresses in the

SCB. See Note 1.

srvadr
The address of a service routine which is to receive control when an
exception or interrupt is delivered through the specified vector. The
address must be on a longword boundary.

code
Used to indicate the stack on which the event is to be serviced.

Can be 0 or 1. (The default is 0.)
e

If 0, service the event on 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.
e

If 1, service the event on the interrupt stack.

If the event is an

exception, raise the IPL to 1F (hexadecimal).

The value specified for this parameter is loaded into bits <1:0> of the
specified vector.

$DS_SETVEC

RETURN
STATUS

DS$_NORMAL

Service successfully completed.

DS$_IVADDR

Address specified for ‘*srvadr’’ routine does not start
on a longword boundary.

DS$_IVWECT

Address specified for ‘‘vector’” is not a valid vector
address.

DS$_ICBUSY

The caller specified the interval clock’s vector, and
the interval clock was already active.

NOTES

The old contents of the specified vector are returned in R1.

When setting device interrupt vectors, remember that the SCB is

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, to find the SCB offset for a particular UNIBUS device’s

vector address, read HP$W_VECTOR in the device’s p-table, then
OR this value with the contents of HP$W_VECTOR in the p-table
associated with EACH adapter existing between the device and the

processor. The number and type of adapter depend on the processor
type. (The device’s p-table contains the actual UNIBUS vector, and the
adapters’ p-tables contain relative offsets into the SCB for the bases of
the vector areas for the adapters.) It therefore becomes obvious that
referencing device vectors in the SCB will cause a diagnostic program

to become processor-dependent. Using the $DS_CHANNEL service
for I/O operations eliminates the need to load SCB vectors and thus
keeps diagnostic programs processor-independent.
In a multiprocessing environment, $DS_SETVEC cannot be called from
within a block of code delineated by the $DS_BGNATTACHED and
$DS_ENDATTACHED macros.

5-307

$DS_SETVEC

MACRO-32
EXAMPLES
$DS_SETVEC_S

VECTADDR,

$DS_SETVEC_S

#4,

SERV_RTN

MCHK_SERVICE

BLISS-32

EXAMPLE
$DS_SETVEC

5-308

(VECTOR=.VECTADDR,

SRVADR=SERV_RTN,

CODE=1);

$DS_SHOCHAN

$DS_SHOCHAN
The Show Channel Status system service of the VDS will display on the

user’s terminal the contents of internal bus adapter registers. This service
should be used whenever the $DS_CHANNEL or $DS_SETMAP services
detect adapter faulits.
The display will consist of the name of each register, the mnemonic name

of each bit field within the register, and the current value of each bit field.
This service is only available to level 3 diagnostic programs.

MACRO-32

$DS_SHOCHAN_Xx

BLISS-32

$DS_SHOCHAN

ARGUMENTS

unit

(UNIT =unit);

unit

Logical unit number of device currently being tested. Adapter to which this

unit is attached will be the one whose registers are displayed.

RETURN

STATUS

NOTES

$DS_NORMAL

Service successfully completed.

$DS_ERROR

Logical unit number is too large.

It may be useful to include the $DS_SHOWCHAN macro in an error
reporting routine (refer to the error reporting macros, $DS_ERRxxxx).

MACRO-32
EXAMPLE

SDS_SHOCHAN_S LOG_UNIT

;Display adapter status.

BLISS-32
EXAMPLE
$DS_SHOCHAN

(UNIT=.LOG_UNIT);

5-309

$DS_SHOWIDLE

$DS_SHOWIDLE
In a multiprocessor environment, use the Show ldle Processors service to

determine which attached processors are currently executing in the idle
state. Attached processors are placed in the idle state when:

The $DS_BOOTATTACHED service has completed bootstrapping the
processor.

An attached process, delimited by the $DS_BGNATTACHED and
$DS_ENDATTACHED macros, finishes executing.

A multiprocessor diagnostic program is stopped by a control-C,
breakpoint, or an exception.

MACRO-32

$DS_SHOWIDLE_x

BLISS-32

$DS_SHOWIDLE

ARGUMENTS

bitma

bitmap

(BITMAP = bitmap),

Address of the longword to receive a bitmap indicating which attached

processors are currently executing in the idle state. There are 32 bits (0
through 31); each bit corresponding to a logical unit number. You need to
look at the bits that correspond to logical unit numbers actually associated
with attached processors. (See Note 1.)

RETURN

STATUS
NOTES

DS$_NORMAL

Senvice successfully

completed.

y.comp

One method for using this service is to create a bit mask. Each time

you issue a $DS_GPHARD call and receive the address of a p-table
for an attached processor, set the bit in the mask corresponding

to the logical unit number for that p-table. When you call the

$DS_SHOWIDLE service, test only the bits that are set in the mask
you created.

5-310

$DS_SHOWIDLE

MACRO-32
EXAMPLE

.LONG O
.LONG 0

IDLE_MASK:
IDLE_PROC:

$DS_SHOWIDLE_S (IDLE_PROC)

CMPL
BEQL

IDLE_MASK, IDLE_PROC
3003

;1 Get idling processors.

: Are they all idling?

: Yes, branch.

BLISS-32
EXAMPLE

$DS_SHOWIDLE (BITMAP=IDLE_PROC);

IF (.IDLE_MASK NEQ .IDLE_PROC)

! Get idling processors.

t If any are not idling then...

THEN

5-311

$DS_STARTATTACHED

$DS_STARTATTACHED
In a multiprocessor environment, you can use the Start Attached CPU
system service to cause an attached processor to begin executing
a section of code (enter the running state). Before you can use
this service, you must bootstrap the specified processor with the
$DS_BOOTATTACHED service.

You must delimit the section of code to be executed with the

$DS_BGNATTACHED and $DS_ENDATTACHED program structure

macros. The service, in conjunction with these macros, causes
the specified processor to leave the idle state (entered via the

$DS_BOOTATTACHED service) and start executing the code delimited

by the macros. When it finishes executing, the processor re-enters the
(Refer to the description of the $DS_BGNATTACHED and

idle state.

$DS_ENDATTACHED macros for details.)

MACRO-32

$DS_STARTATTACHED_x

BLISS-32

$DS_STARTATTACHED

unit, start_addr

(UNIT = unit,
START_ADDR = start_addr);

ARGUMENTS

unit
Logical unit number of the processor to be bootstrapped.

start_addr
Address of the code to be executed in the attached processor.
This argument must be the address of the code generated by a

$DS_BGNATTACHED macro.

RETURN

STATUS

DS$_NORMAL

Service successfully completed.

DS$_ILLUNIT

The specified logical unit number is too large.

DS$_INVCPU

Can’t start the specified processor.

May

mean the processor doesn’t exist or the
processor was not executing in its idle state (see

$DS_BOOTATTACHED).

$DS_STARTATTACHED

MACRO-32
EXAMPLE

$DS_BGNATTACHED

ROUTINE1

$DS_ENDATTACHED

$DS_STARTATTACHED_S

LOG_UNIT,

ROUTINEl

BLISS-32
EXAMPLE

$DS_BGNATTACHED (ROUTINE_NAME=ROUTINE1);

SDS_ENDATTACHED;

$DS_STARTATTACHED (UNIT = .LOG_UNIT,

START_ADDR=ROUTINEl);

5-313

$DS_$STORE

$DS_S$STORE
The $DS_$STORE p-table descriptor macro is used to load the
contents of the “‘value register’’ (see Section 3.2.3.3) into a field of

the p-table being built. The macro can be used to store values read

by the $DS_$DECIMAL, $DS_$OCTAL, $DS_$HEX, $DS_$STRING,
or $DS_$LOGICAL statements, or generated by the $DS_$LITERAL,

$DS_$FETCH, $DS_$COMPLEMENT, or $DS_$CASE statements. It can

also be used to facilitate temporary storage. A value can be stored in the
p-table temporarily while the value register is needed for something else,
then later restored with the $DS_$FETCH statement. This macro does not

change the contents of the value register.

MACRO-32

$DS_S$STORE

offset, pos, size

BLISS-32

$DS_$STORE

(OFFSET

ARGUMENTS

= offset, POS = pos,
SIZE = size);

offset

The byte offset into the p-table of the field into which the contents of the
value register are to be placed.

POS
Bit position of the field, relative to the beginning of the byte specified by
“offset.”” If the field starts on a byte boundary, this value will be 0.

size
Number of bits making up the field. The size cannot be larger than 32.

Code generated by macro (shown in Macro-32; Bliss-32 is equivalent):

pos

.BYTE

size

structure

.BYTE

;

Beginning

~X88
offset

Word

.BYTE
. WORD

Bit

position

NOTES

Bit

field

MACRO-32

EXAMPLES
$DS_SSTORE

OFFSET=HP$L_RK611_CSR,

$DS_$STORE

<~X40>,

5-314

POS=0,

SIZE=32

data

STORE
in

size

directive

word

offset

$DS_$STORE

“

BLISS-32

EXAMPLES
$DS_$STORE

(OFFSET=%FIELDEXPAND(HPS$L_RK611_CSR,0),

$DS_S$STORE

(OFFSET=%X’'40',

POS=%FIELDEXPAND (HPSL_RK611_CSR,1),
SIZE=%FIELDEXPAND (HP$L_RK611 CSR,2));

POS=0,

SIZ=32);

5-315

$DS_STRING

$DS_STRING
The $DS_STRING macro can be used to generate a quadword descripto

(see Section 5.3) for a given character string. In MACRO-32 programs,
.ASCIC and .ASCIZ formats for the string may also be generated.
This
enables the programmer to reference the same string in any of the three
formats.

MACRO-32

$DS_STRING

<text>, [label1], [label2]

BLISS-32

$DS_STRING

(‘text’);

ARGUMENTS

text
Character string for which a quadword descriptor is to be construct

ed.

label1
Label to be placed at the .ASCIC construction of the character string.

parameter may not be referenced by keyword.)

(This

label2
Label to be placed at the .ASCIZ construction of the character string.

parameter may not be referenced by keyword.)

NOTES

The quadword descriptor will be constructed at the current PC. It

(This

may

be accessed by placing a label at the macro call, as illustrated in the

example.

MACRO-32

EXAMPLE
MSG_LABEL:

$DS_STRING <THIS

iCreate descriptor for
A MESSAGE.>,

MSG_LABEL1l,

MSG_LABEL2

5-316

string.

;

iInclude

label

for

.ASCIC

;Include

label

for

.ASCIZ

$DS_STRING

—
(0

BLISS-32

EXAMPLE
BIND

MSG_LABEL = $DS_STRING (THIS IS A MESSAGE.);

5-317

$DS_S$STRING

$DS_S$STRING
The $DS_$STRING p-table descriptor macro is used to read a string from
an ATTACH command line. If the string exists on the ATTACH command
line, it will be used; otherwise, the prompting message will be displayed.

The string read from the command line is compared against a list of
valid strings, and the number of the match string (0, 1, 2, and so on, in

the order given) is returned in the value register. This can be used, for
example, to determine if a DZ-11 line card to be tested is EIA or 20MA, by

the statement $DS_$STRING (Line type, EIA, 20MA) which would return 0
if the response was EIA, or 1 if the response was 20MA.

MACRO-32

$DS_$STRING

<prompt_>, <string, [string,...]_>

BLISS-32

$DS_$STRING

(‘prompt’, ‘string’, [‘string’, ...]);

ARGUMENTS

prompt

Character string to be used as a prompting message.

string
A character string with which the input string is to be compared. The
number of the first string that exactly matches the input will be returned.

Code generated by macro (shown in Macro-32; Bliss-32 is equivalent):
.BYTE

~X85

;

Beginning

.ASCIC

\prompt\

;

Prompt

.ASCIC

\stringil\

;

ASCIC

string

;

ASCIC

strings

.ASCIC

\stringn\

;

ASCIC

.BYTE

List

MACRO-32
EXAMPLES
$DS$SSTRING <Module type>,

<<EIA>,

SDSSSTRING PROMPT=<Node type>,

5-318

<20MA>>

STRINGS=<780,750,730>

STRING

string

terminator

prompt

$DS_$STRING

50—

BLISS-32
EXAMPLES
$DS_SSTRING

(’Module type’,

$DS_$STRING (’Node type’,

‘EIA’,

’780',

"20MA’);

‘750’,

'730');

5-319

$DS_SUMMARY

$DS_SUMMARY
The Print Summary system service will cause the diagnostic program’s
summary routine to be executed.

Summary routines are discussed in
Section 3.7. Note that the summary routine will also be executed when

the $DS_ENDPASS service is called, if the requested number of program
passes have been executed.

MACRO-32

$DS_SUMMARY_x

BLISS-32

$DS_SUMMARY:;

“

RETURN

STATUS

No status returned.

“

MACRO-32

EXAMPLE
$DS_SUMMARY_S

BLISS-32
EXAMPLE
$DS_SUMMARY
;

5-320

SUNWIND

SUNWIND
The Unwind Call Stack system service allows a condition handler to

“unwind’’ the procedure call stack to a specified depth. ‘‘Unwinding’’ is
the process of stepping through a specified number of call frames on the
stack so that when the condition handler returns, the specified call frame
will be used instead of the one placed on the stack when the condition
handler was called. In other words, the normal execution flow is altered.
Optionally, an address can be specified that will be placed in the return
PC argument of the call frame that was stepped to.

For further discussion of unwinding, refer to sections on condition handling
in the VAX/VMS System Services Reference Manual.

MACRO-32

SUNWIND_x

BLISS-32

SUNWIND

ARGUMENTS

depadr

[depadr], [newpc]

(/DEPADR =depadr], [NEWPC = newpc]),

Address of a longword indicating the depth to which the stack is to be
unwound. A depth of 0 indicates the call frame that was active when
the condition occurred (the frame that would normally be used when the
condition handler returns), 1 indicates the caller of that frame, 2 indicates
the caller of the caller of the frame, and so on. If the depth is specified as
0 or less, no unwind occurs and a successful status code is returned. If no
value is specified for this parameter, the unwind is performed to the caller
of the frame that established the condition handler.
newpc
Address to be given control when the unwind is complete. This value is

placed in the return PC argument of the call frame that is stepped to. If no
value is specified for this parameter, the return PC argument is not altered.

RETURN

STATUS

SS$_NORMAL

Service successfully completed.

SS$_ACCVIO

The call stack is not accessible to the caller. This
condition is detected when the call stack is scanned
to modify the return address. User mode only.

SS$_INSFRAME

There are insufficient call frames to unwind the
specified number of frames.

SS$_NOSIGNAL

No signal for an exception condition is currently
active.

SS$_UNWINDING

An unwind is already in progress.

5-321

SUNWIND

L
—.

NOTES

The actual unwind does not occur when the service is called. The

service simply modifies the return addresses in the call frames so that
when the condition handler returns, an ““unwind’’ procedure is called

from each frame that is being unwound.

e
.

MACRO-32

EXAMPLE

In this example, the SUNWIND will cause the return PC of the call
frame created by the CALLS ROUTINEI instruction to be replaced by

OUTADDR, and the RET instruction on the condition handler will cause
that call frame to be referenced.
ROUTINE1:

MOVAB

CALLS

COND_HNDLR,

(FP)

ROUTINE?2

RET

ROUTINEZ:

(Condition occurs.)

RET
COND_HNDLR:

MOVL

#1,

SUNWIND_S

DEPTH,

RET

OUTADDR:

5-322

DEPTH

OUTADDR

SUNWIND

BLISS-32
EXAMPLE
ROUTINE

ROUTINEl

BEGIN

.FP

COND_HNDLR;

ROUTINE2

();

END;

ROUTINE

ROUTINEZ

BEGIN

{Condition occurs.)

END;
ROUTINE

COND_HNDLR

BEGIN

rDEPTH = 13
SUNWIND

(DEPADR=DEPTH,

NEWPC=ERRORS+2);

END;

ROUTINE

ERRORS

BEGIN

END;

5-323

SWAITFR

SWAITFR
The $WAITFR macro calls a system service that will wait until a

specified event flag is set before returning.
in Section 4.4.2.

Event flags are discussed

If the specified flag is already set, the service routine

returns immediately. Otherwise, control is not returned to the caller until

the flag has been set.

MACRO-32

SWAITFR_x

BLISS-32

SWAITFR

ARGUMENTS

efn

(EFN=efn);

efn
Number of the event flag to wait for.

RETURN

STATUS

SS$_NORMAL
SS$_ILLEFC

SS$ _UNASEFC

Servi

full y

ervice successfully

leted

completed.

comp

An illegal event flag number was specified.

In user mode, indicates that the specified common
event flag (see Section 4.4.2) has not been
associated with the process issuing the $SETEF
macro.

In standalone mode, indicates that an event flag

from 64 through 127 was specified. These flags are
not valid in standalone mode.

NOTES

While the system service routine is waiting for the event flag to be

set, ASTs can interrupt the service. Program control will return to

the SWAITFR system service after execution of the AST routine has
completed.

SWAITFR

MACRO-32
EXAMPLE
SWAITFR_S

BLISS-32
EXAMPLE
SWAITFR

(EFN=5);

5-325

$DS_WAITMS

$DS_WAITMS
The Millisecond Wait system service is used to create a delay of a
specified number of milliseconds. When the service routine is called,
control is not returned to the caller until the requested amount of time

has elapsed (unless an asynchronous event occurs that causes a routine
containing a $CANTIM or $DS_CANWAIT macro to be executed; see
Note 1.)

MACRO-32

$DS_WAITMS_x

BLISS-32

$DS_WAITMS

ARGUMENTS

time, [tag]

(TIME =time, [RETTIM =tag]);

time

Length of delay in time units. One time unit equals 10 milliseconds.

tag
Address of longword to receive amount of unused time, if delay was
canceled before all requested time was used up (see Note 1).

RETURN

STATUS

SS$_NORMAL

Service successfully

DS$_PROGERR

A value less than the overhead to complete the

completed.

comp

system service was specified for the ‘“‘time”’
parameter. Note: the overhead refers to the machine-

dependent amount of time required to execute this
system service.

SS$_EXQUOTA

The interval clock is already in use and hence is
unavailable to this system service.

NOTES

If an asychronous event (AST delivery or hardware interrupt) occurs,
and the routine handling the AST or interrupt issues a $CANTIM

or $DS_CANWAIT macro, the SWAITMS service will, on regaining
program control after return from the event handler, store the unused

delay time in the address specified by ‘‘tag’’ and return control to the
caller.

In a multiprocessing environment, $DS_WAITMS cannot be called
from within a block of code delineated by the $DS_BGNATTACHED

and $DS_ENDATTACHED macros.

$DS_WAITMS cannot be used if the IPL is greater than 2 and $SETIMR
requests have been issued and are still pending.

5-326

$DS_WAITMS

MACRO-32
EXAMPLE
$DS_WAITMS_S

#100,

TIME_LEFT

BLISS-32
EXAMPLE
$DS_WAITMS

(TIME=200,

RETTIM=TIME_LEFT);

5-327

$DS_WAITUS

$DS_WAITUS
The Microsecond Wait system service is used to create a delay of a
specified number of microseconds. When the service routine is called,
control is not returned to the caller until the requested amount of time has
elapsed (unless an asynchronous event occurs which causes a routine
containing a $CANTIM or $DS_CANWAIT macro to be executed; see
Note 1.)

This macro may only be used by level 3 diagnostic programs.

MACRO-32

$DS_WAITUS_x

BLISS-32

$DS_WAITUS

ARGUMENTS

time, [tag]

(TIME =time, [RETTIM = tag]),

time

Length of delay in time units. One time unit equals 10 microseconds.

tag

Address of longword to receive amount of unused time, if delay was
canceled before all requested time was used up (see notes).

RETURN

STATUS

SS$_NORMAL

DS$_PROGERR

Service successfully

completed.

y
comp
A value less than the overhead to complete the

system service was specified for the “time”
parameter. Note: the overhead refers to the machinedependent amount of time required to execute this

system service.

SS$_EXQUOTA
e

In user mode:

Timer entry quota or AST delivery quota exceeded,
or insufficient dynamic memory space.
¢

[In standalone mode:

The interval clock is already in use and is therefore
unavailable to this system service.

5-328

$DS_WAITUS

NOTES

If an asychronous event (AST delivery or hardware interrupt) occurs,

and the routine handling the AST or interrupt issues a $CANTIM or
$DS_CANWAIT macro, the $DS_WAITUS service will, on regaining
program control after return from the event handler, store the unused
delay time in the address specified by “tag’” and return control to the

caller.

Do not use the $DS_WAITUS service if $SETIMR requests have been
issued and are still pending.

For information on using this service in a multiprocessor environment,
refer to Section 4.6.

MACRO-32
EXAMPLE
$DS_WAITUS_S

#50,

TIME_LEFT

BLISS-32
EXAMPLE
$DS_WAITUS

(TIME=40,

RETTIM=TIME_LEFT);

SWAKE

$WAKE
The Wake system service reactivites a process that is in hibernation as a
result of execution of the $HIBER system service.

MACRO-32

$WAKE_x

BLISS-32

SWAKE

ARGUMENTS

pidadr (user mode onIy)

[pidadr], [porcnam]
([PIDADR =pidadr], [PRCNAM = prcnam]);

Address of a longword containing the process indentification of the process
to be awakened.

prcnam (user mode only)
Address of a character string descriptor (see Section 5.3) pointing to the
process name string.

Refer to the VAX/VMS System Services Reference Manual for details on the
interpretation of these parameters.

RETURN

ST ATU S

SS$_NORMAL

Service successfully completed.

SS$_ACCVIO

The name string or string descriptor cannot be read
by the caller, or the process id number cannot be
written by the caller. User mode only.

SS$_IVLOGNAM

The process name string is invalid.

SS$_NONEXPR

Warning. The specified process does not exist, or
an invalid process id was specified.

SS$_NOPRIV

The caller’s process does not have the privilege
required for waking the specified process.

NOTES

In standalone mode, the only meaningful use of this macro is to place it

in an event handler that will be executed while the diagnostic program
is in hibernation. This will awaken the program so that it may continue
executing.

In a multiprocessing environment, $WAKE cannot be called from
within a block of code delineated by the $DS_BGNATTACHED and

$DS_ENDATTACHED macros.

SWAKE

MACRO-32
EXAMPLE
$WAKE_S

BLISS-32
EXAMPLE
SWAKE

();

5-331

$SWFLAND

SWFLAND
The $WFLAND macro calls a system service that will wait until a specified

group of event flags is set before returning. Event flags are discussed
in Section 4.4.2. All of the event flags must be in the same event flag
cluster. If the specified flags are already set, the service routine returns
immediately. Otherwise, control is not returned to the caller until all

specified flags have been set.

MACRO-32

SWFLAND_x

BLISS-32

SWFLAND

ARGUMENTS

efn, mask

(EFN =efn, MASK = mask);

efn

Number of any event flag in the cluster being used.

mask
32-bit mask in which bits set to 1 indicate event flags that must be set
before the system service returns.

RETURN

STATUS

SS$_NORMAL
-

Seni|

full y

ervice successfully

leted

completed.

comp

SS$_ILLEFC

An illegal event flag number was specified.

SS$_UNASEFC

In user mode, indicates that the specified common
event flag (see Section 4.4.2) has not been
associated with the process issuing the macro.
In standalone mode, indicates that an event flag

from 64 through 127 was specified. These flags are
not valid in standalone mode.

NOTES

While the system service routine is waiting for the event flags to be

set, ASTs can interrupt the service. Program control will return to
the SWFLAND system service after execution of the AST routine has
completed.

5-332

SWFLAND

MACRO-32
EXAMPLE
SWFLAND_S

#0,

FLAG_MASK

SWFLAND_S

#0,

#000000F0

BLISS-32
EXAMPLE
$WFLAND

(EFN=0,

MASK=.FLAG_MASK);

SWFLAND

(EFN=0,

MASK=%X’'000000F0’);

5-333

SWFLOR

SWFLOR
The $WFLOR macro calls a system service that will wait until any one of

a specified group of event flags is set before returning. Event flags are
discussed in Section 4.4.2. All of the event flags must be in the same
event flag cluster. If any one of the specified flags is already set, the
service routine returns immediately. Otherwise, control is not returned to
the caller until one of the specified flags has been set.

MACRO-32

SWFLOR_x

BLISS-32

SWFLOR

ARGUMENTS

efn, mask

(efn, mask);

efn
Number of any event flag in the cluster being used.

mask
32-bit mask in which bits set to 1 indicate event flags that are to be tested
by the system service.

RETURN

STATUS

SS$_NORMAL
SS$_ILLEFC

SS$_UNASEFC

S _

full y

ervice successfully

leted

completed.

comp

An illegal event flag number was specified.

In user mode, indicates that the specified common
event flag (see Section 4.4.2) has not been
associated with the process issuing the macro.
In standalone mode, indicates that an event flag

from 64 through 127 was specified. These flags are
not valid in standalone mode.

NOTES

While the system service routine is waiting for an event flag to be
set, ASTs can interrupt the service. Program control will return to

the $WFLOR system service after execution of the AST routine has
completed.

5-334

$SWFLOR

MACRO-32
EXAMPLE
SWFLOR_S

#0,

FLAG_MASK

SWFLOR_S #0,

#000000F0

BLISS-32
EXAMPLE
$WFLOR

(EFN=0,

MASK=FLAG_MASK);

SWFLOR

(EFN=0,

MASK=%X’'000000FO0’);

5-335

$XABFHC

$XABFHC
The $XABFHC will allocate the File Header Characteristics Extended
Attribute Block (FHC XAB), which is an optional data structure used by

RMS. If the $XABFHC macro is used, and if a pointer to the FHC XAB is

specified in the FAB, then the $OPEN operation will load the FHC XAB
with file header characteristics obtained from the header of the file that
was opened.

Besides allocating the XAB, the $XAB macro also defines symbols for

each XAB field. Symbols are of the form XAB$datatype_fieldname, where

‘““datatype’’ is a data type specifier listed in Table 6-1.

MACRO-32

$XABFHC

BLISS-32

$XABFHC;

NOTES

FHC XAB Fields

Following are the FHC XAB fields filled in by VDS RMS. Refer to the
VAX/VMS RMS Reference Manual for fields filled in by VMS RMS.
®*

ATR — Record attributes. Same as RAT field of FAB.

BLN — Length of the XAB.

COD — Type of XAB. (Only FHC XAB type is allowed.)

EBK — Virtual block number of end-of-file.

FFB — First free byte in end-of-file block.

HSZ — Fixed length control header size. Same as FSZ field of FAB.

LRL — Longest record length.

MRZ — Maximum record size. Same as MRS field of FAB.

®*

RFO — File organization and record format. Combines ORG and RFM
fields of FAB.

SBN — Starting block number of the file if it is contiguous; otherwise
field is 0.

$XABFHC

MACRO-32

EXAMPLE
XAB_BLOCK:

S$XABFHC

BLISS-32
EXAMPLE
LOCAL
XAB_BLOCK

S$XABFHC;

5-337

Creating a VDS Diagnostic Program

6.1

Introduction
The previous chapters have presented the building blocks needed to
construct a diagnostic program that will execute under the VAX Diagnostic
Supervisor (VDS). This chapter describes the steps required to create a

VDS diagnostic program. It also specifies all standards and conventions to

which a diagnostic program must adhere.

6.2

Program Development Process

6.2.1

Overview
Creating a diagnostic program involves several distinct, consecutive phases.
Each phase is required, and the phases must be entered in the same order
that they are described here.

6.2.2

Consultation Phase
The consultation phase of program development consists of informal

gathering and exchanging of information relating to the hardware product
for which the diagnostic program is to be written. This phase should

begin soon after an engineering or product management group has made a
commitment to develop a new product.

Goals of this phase are to formulate a testing strategy for the product (what
types of diagnostic programs should be developed), identify a few key
project milestones (dates), and estimate staffing and funding requirements.

The consultation phase begins before staffing and funding commitments
have been negotiated. Typically, the result of this phase is a cursory project
plan.

Participants will include management and senior technical personnel from

the engineering group or product line developing the product, the future
program’s user community (generally field service and manufacturing

personnel), and the diagnostic programming group.
An important note: If it is desirable for the hardware design of a new

product to provide aids that will enhance the fault detection of a diagnostic
program, the diagnostic programming group must then request these aids

as soon as possible in order to ensure that they will be incorporated into
the device’s final design. Negotiations for design changes to aid diagnosis

should thus commence during this phase of the project.

Creating a VDS Diagnostic Program

6.2.3

Planning Phase
This phase begins after staffing and funding commitments have been
made. This phase and all following phases are performed by the diagnostic
program’s project leader and his or her staff.
The goal of the planning phase is to develop a plan for implementation
of the project. This project plan will include a description of the

diagnostic program and will specify project goals, schedules, development
requirements, training requirements, and maintenance requirements.

The result of this phase is a Diagnostic Engineering Project Plan adhering to

the format specified by Section 7C3-1.A of the Software Development Policies
and Procedures.

6.2.4

Functional Specification Phase
After the project plan has been completed, the task of defining the
functional operation of the diagnostic program begins.
The goal of this phase is to clearly define 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 will include specific statements

about the program’s intended uses and users, plus goals regarding the
program’s performance and run-time parameters.
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.

6.2.5

Design Phase
The program’s design phase may be entered when the functional
specification phase has been completed.
The goal of the design phase is to develop a design specification that

defines the methods that will be used to implement the functionality
defined in the functional specification. This phase answers the question,
“How will the program’s functionality be provided?”” For example, if the

functional description states that the program will test a certain section of
the device’s logic, then the design specification will describe the algorithm

to be used to perform the test.
Some of the methods that may be used to specify designs are:
*

Detailed hierarchy charts

Interface specification blocks

HIPO diagrams

Creating a VDS Diagnostic Program

Structured flowcharts

Program Design Language 1 (PDL1) (See below.)

The result of this phase will be a Diagnostic Engineering Design
Specification, adhering to the format specified in Section 7C3-3.A of the
Software Development Policies and Procedures. This document also describes
PDL1.

6.2.6

DesignIimplementation Phase
After the design has been completely specified, it may be implemented.
Design implementation is the phase in which coding and debugging occur.

The schedule on which coding and debugging of the various pieces of
the program is based depends greatly upon the availability 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.

Implementation of programs for new hardware must often be carried
out in two stages, referred to as “prototype support” and “‘final product

support.”

Prototype support involves providing the engineering group responsible for
the product with a preliminary version of the program. This version will be
used to help verify the integrity of the hardware design. The engineering
group will generally expect this version to be ready for use within a matter

of days after the hardware is ““powered up’’ for the first time. Specific
requirements for prototype support depend on the particular product.

These requirements should be specified in the Project Plan and Functional
Specification.

Unfortunately, it may be necessary to provide prototype support before
the planning and specification phases described have been completed.
Therefore, it is important to carefully coordinate all phases of program

development so that the needs of all users can be met on schedule. For
example, some portions of the design specification or even the functional
specification may have to be delayed until debugged code supporting the
prototype 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 use. User
requirements for the final product may be different from user requirements

for prototype support. Knowledge of the hardware’s operation that was
gleaned by the programmer during development of prototype support will
aid him or her in 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 carefully
coordinate the two development processes. Hardware design engineers

and manufacturing personnel will often desire working versions of the
diagnostic program before the scheduled completion date. Thus, it is

6-3

Creating a VDS Diagnostic Program

common for diagnostic programmers to provide ‘‘prerelease’” versions of
the program before the final program has been completed. A prereleased
program may or may not provide the full functionality that will exist in the
final program.

6.2.7

Design Verification Phase
Once the final program has been completed, its functionality and operation
must be assessed to ensure that the program meets all of the functionality
goals that were originally set, and that it adheres to all applicable operating
standards (such as using VDS macros properly). Assuring overall program
quality is performed by following the steps indicated in Section 6.8, Quality
Assurance.

6.3

Program Structure
Chapter 3 and Chapter 4 described all of the required and optional
components of a VDS diagnostic program. Since all VDS diagnostic
programs are made up of the same basic components, it is useful to
arrange these components in the same order and format in the source code
of every program. This will aid program maintainers by ensuring a large
measure of consistency from one program to the next.
In all diagnostic program sources, program components should be divided
into a series of source modules. There should be a ““header module”” and
one or more ‘‘test modules.”

6.3.1

Header Module
The header module contains all of the tables used by the VDS, the
initialization, cleanup, and summary routines, plus any routines used
globally by the diagnostic program. Components of the header module
should be arranged in the following order:
1

Module cover page (copyright statement, title and author, and
maintenance history)

Functional description of module

Declarations of libraries and BLISS require files

User-defined macro definitions

Symbol definitions

Diagnostic header ($DS_HEADER)

Dispatch table ($DS_DISPATCH)

Statistics table ($DS_BGNSTAT, $DS_ENDSTAT) (optional)

Section names declaration ($DS_SECTION)

10 Device mnemonics list (§DS_DEVTYP)

Creating a VDS Diagnostic Program

ASCII text:

Other ASCII strings

¢.

Error message strings

12 Initialization code ($DS_BGNINIT, $DS_ENDINIT)

13 Cleanup code ($DS_BGNCLEAN, $DS_ENDCLEAN)
14 Summary routine ($DS_BGNSUMMARY, $DS_ENDSUMMARY)
15 Error reporting routines ($DS_BGNMESSAGE, $DS_ENDMESSAGE)
16 Other (optional) global subroutines, including interrupt service routines,
condition handlers, and so on.
Note: If a program has many global routines and data structures, they should be

placed in a separate module.

Test Modules
Each test module will contain one or more tests. The number of tests
modules and the number of tests per module are unrestricted. Each test

module should be formatted as follows:
1

Module cover page (copyright statement, title and author, and

Functional description of module

Declarations of library and require files

User-defined macro definitions

Symbol definitions

maintenance history)

Section names declaration ($DS_SECDEF)

6.3.2

For each test in module:

Test name (3DS_SBTTL)

$DS_BGNTEST

Cc.

Test header

For each (optional) subtest in test:

—

Subtest header

—

$DS_BGNSUB

—

Subtest code

—

$DS_ENDSUB

$DS_ENDTEST

Creating a VDS Diagnostic Program

6.3.3

‘Module Templates
Template files have been created to help the programmer follow the above
formats. There is a header module template and a test module template.

Each template contains the program-independent fields of each program
component. The programmer simply fills in the program-dependent
fields of each module. These templates are named HEADER.MAR and

TEST.MAR for MACRO-32, and HEADER.B32 and TEST.B32 for BLISS-32.
The templates are reproduced in Appendixes A and B.

6.4

Program Documentation

6.4.1

Introduction
A diagnostic program should be considered to be made up of two
parts: the code and the documentation. Each of these parts is of equal
importance. Documentation should NEVER be thought of as auxiliary to

the code, to be hurriedly added at the end of the project if time permits.
The best documentation is that which is developed before and during code
development.
Diagnostic program documentation serves two purposes:
*

Users of diagnostic programs probably refer to and depend on program

documentation more than users of any other software. This is because
identification of hardware failures requires a very exact understanding

of what function is being performed by a particular section of code and
which areas of the hardware circuitry are likely to be activated to carry

out that function. It is sometimes necessary for the program user to
read the program’s listing files to see what signals are being activated
within a test or subtest.
*

As is the case with any software product, program maintenance is
usually performed by persons other than the product’s author. Those

who must enhance, correct, or otherwise update a diagnostic program
depend on the documentation for understanding the program’s
function, design, and implementation.

Documentation for VDS diagnostic programs consists of the following three
parts:

A documentation file containing hardware requirements, operating
instructions, and functional descriptions of the program’s tests

Source code documentation providing detailed functional descriptions
of every test, subtest, routine, and line of code

““Help” files that the user can access with the VDS HELP command,
and that summarize the program’s operating instructions

Creating a VDS Diagnostic Program

6.4.2

Documentation File
The documentation file will be distributed with the diagnostic program.
The documentation file for program EVXYZ will be called EVXYZ.DOC.
A template for the documentation file is available in both RUNOFF and
non-RUNOFF formats. A reproduction of the template can be found in
Appendix C.

The documentation file will contain the following information:
1

Cover page

The cover page contains identification information such as the
program’s name, release date, and maintainer, along with copyright
and disclaimer statements.
Table of contents

Abstract

The abstract is a short description of the program, summarizing
information found in later sections of the document. This section

should identify which types of hardware will be tested, and should also
state the program level (level 2R or level 3).
Hardware requirements

This section lists the minimum hardware required for the program to
execute, plus any optional hardware. Include special connectors or
other special hardware required by the program.
List the processor types with which the program is compatible. Do
NOT make generalized statements, such as ‘“‘all VAX processors,”’
since the program may not be executable on future processors.
Software 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 properly in order for the
diagnostic program to correctly diagnose faults on the hardware being
tested.
Operating instructions

In most cases, the VAX/DS Diagnostic Supervisor User’s Guide should be
the only reference needed for operating instructions.

Options
If the program has special instructions (such as using a user-defined

command language), that information should be provided in this
section.

Event Flags
If any user-controllable event flags are used by the program, they

should be listed.
6-7

Creating a VDS Diagnostic Program

Program functional description
a.

Program overview

This is a general functional description of the program. The
program’s purpose and testing strategy should be included.
b.

Program size

The load time and run-time memory requirements should be

specified. Include memory required by any auxiliary data files.
¢.

Program run times

The execution time of each program section is listed here. If a
QUICK mode is provided, also include its execution time.
d.

Run-time dynamics
Indicate how the program allocates resources during execution

time. Include both memory and device allocations. Specify the
mimimum buffer space needed.

Fault detection

Describe the fault coverage (include percentage) and error
resolution of which the program is capable.
Include sample error messages, if error reporting routines are used.

Performance during hardware failures

Indicate how the program will handle unexpected exceptions
resulting from hardware failures, power failure, and the like.
¢g.

Program applications

List the uses for which the program was designed, such as
manufacturing, customer services, engineering, and customers.
h.

Test descriptions

For each test, include:
—

A functional description of the test

—

The step-by-step flow of the test

—

Debug aids contain hints to the program user about what
should be looked at next if the test fails. This is very important
for logic tests.

Maintenance history
Each time the program is updated, the update must be described here.
The description must include the date of the change, the program’s
version number, and the programmer’s name.

6-8

Creating a VDS Diagnostic Program

Source Code Documentation
6.4.3.1

Diagnostic Codes

Each diagnostic program released by DIGITAL is assigned a “‘diagnostic
code’’ that uniquely identifies it. Codes for VAX diagnostic programs
consist of five characters, the first of which is E. The code is assigned by
the Release Engineering group.

Module Cover Page

Each module must have a cover page. The cover page will include:

Module and program names, including version numbers (see above).
Copyright statement

6.4.3.3

Module Names

For the diagnostic program with the diagnostic code EVXYZ, the header
module should be named EVXYZ0.MAR if it is a MACRO-32 program, or
EVXYZ0.B32 if it is a BLISS-32 program. Test modules should be named
EVXYZ1.MAR (or .B32), EVXYZ2.MAR (or .B32), and so on.

WODN

6.4.3.2

6.4.3

Module abstract
Author

Maintenance history. Each time the module is updated, the update
must be described in the maintenance history. The description must
include the date of the change and the module’s version number.

The format of the cover page is illustrated in the header module template
example contained in Appendix A.

6.4.3.4

Test and Subtest Prefaces

Each test and each subtest must possess a preface. Prefaces for tests and
subtests must contain the following information:
1

Test description

This will contain a detailed description of what is being tested and how
the test is implemented.
2

Assumptions

List assumptions being made about the state of the hardware before
the test is executed. For example, if this test will not function properly
unless certain parts of the hardware are good, list those parts.
3

Test steps

In this section list the test steps. A pseudo language is very useful for
this purpose.
4

FErrors

Provide a detailed description of all errors reported by this test.

Creating a VDS Diagnostic Program

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

The format of test and subtest prefaces is illustrated in the test module
template in Appendix B.

6.4.3.5

Subroutine Preface
Each subroutine must possess a preface. Subroutine prefaces must contain
the following information:
Functional description
This must be a detailed description of what function the routine performs
and how the function is performed.

Calling sequence
Indicate how the routine is to be called. For example:
CALLS

#4,ROUTINE

BSBW

Entered via

CALLG ARGPTR,ROUTINE

ROUTINE

exception

vector

Inputs
List all input parameters that are explicitly passed to the routine.
Explicitly passed input parameters are those pushed onto the stack

before a routine is called. (In BLISS-32, explicit input parameters are
those that are listed in parentheses after the routine name.)
Implicit inputs

List all input parameters that are not explicitly passed on the stack.
This list will include ANY variable referenced by the routine but not

defined locally in the routine and not passed explicitly. For example,
parameters passed in registers are implicit inputs.

Note: Use of implicit inputs should be kept to a minimum. They adversely
affect program maintainability and routine transportability.

Outputs
List all output parameters that are explicitly passed back to the caller.
Explicitly passed output parameters are those that are:
*
*

Pushed onto the stack by the routine, or
Stored into locations whose addresses were explicitly passed to the

routine.

Implicit outputs

List all output parameters that are implicitly returned to the caller.

Implicit output parameters are ANY variables that are modified by the
routine but were not explicitly passed to the routine. For example, if
a variable stored in a register is updated, that variable is an implicit
output.

6-10

Creating a VDS Diagnostic Program

Note: Use of implicit outputs should be kept to a minimum. They adversely
affect program maintainability and routine transportability.
Completion codes

Indicate all completion codes that could be returned by this routine. If
the routine passes along completion codes received from subordinate
subroutines, these codes must also be listed. Also indicate how the
completion code is passed. (Placing the code in R0 is the standard
method.)

Side effects
List here any actions taken by this routine that could affect the
operation of other routines. Examples are initializing data structures or
altering the state of global flags.

Also, if the routine places the hardware in some unusual or
indeterminate state, indicate that here.
Registers used

Identify the purpose of each general purpose register used by the
routine, so anyone reading the code can quickly determine the
functions of the registers.

The format of a routine preface is illustrated in the header module template
of Appendix A.
6.4.3.6

Source Code Comments
It is extremely important that the source code be accurately commented.

Comments within the source code can take three forms:

Block comments are used to identify major functions within routines.
Group comments are within blocks of code delimited by block
comments. They are useful when you emphasize a command on
the page.

Line comments are those which appear at the end of each line of
the program. It is extremely important that line comments appear
following every MACRO-32 instruction.
Examples of these forms follow:
Block Comments
MACRO32
<skip>
p++

;

This is a block comment.

;

and extends

fully across

It begins at the left-hand margin
the page.

;——

<skip>

BLISS-32

<skip>
!4++

This is a block comment.

and extends

fully across

It begins at the left-hand margin
the page.

<skip>

6-11

Creating a VDS Diagnostic Program

Group Comments

TMo

the code being

a group comment.

commented,

and

indented the same amount

extends

fully

across

the page.

This

MACRO-32

BLISS-32

This

a group comment.

the code being commented,

and

indented the same

extends

fully

amount

across

the page.

Explain what

the

IF-THEN-ELSE

statement will

do.

]

...

THEN

....

ELSE
BEGIN

Explain what

the

REPEAT-UNTIL loop will

do.

REPEAT
UNTIL

...

;

END;

Clear

the

data

buffers.

Clear
REPEAT

longword

good data

Clear

longword

bad

WAGOOD_DATA[R6 )

CLRL

WABAD_DATA[RG]

AOBLSS

#16,

Clear

CLRL

15%

Increment pointer
UNTIL

entire

buffer

data

buffer
buffer

and branch back
is

cleared

“e

not match,

expected

they do

good data

Compare

R6,

buffer pointer

CLRL

15%:

—e

Line Comments

printed

buffer

and received
store

and

bad

data,

one

the

expected

data

buffer,

longword

and

time.

received values

respectively,

so they

If
the
can

later.

6-12

MOVL

4(AP),

Put

byte

MOVL

8(AP),

;

Put

address

received

data

R3.

MOVL

12(AP),

;

Put

address

expected

data

R4.

CLRL

;

Clear

CLRIL

;

Clear buffer pointer.

count

error

R2.

count.

Creating a VDS Diagnostic Program

These examples illustrate several concepts:
Every MACRO-32 instruction has a comment.

It is useful to indicate structured programming constructs where

applicable. Notice the REPEAT-UNTIL construct in the example.

IF-THEN-ELSE, WHILE-DO, CASE constructs, and so on, can be
flagged similarly, enhancing readability. Capitalize keywords and
indent comments within a construct.

Comments provide useful information. For example, the last comment
in the last example says, *‘Clear buffer pointer.” It does not say “Clear
R5,” which would be useless to anyone reading the code.

6.4.4

Help Files
6.4.4.1

Description of Help Files

A help file is a 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 used to determine which portions of the text
to display.

A help file must be provided for every diagnostic program. For program

EVXYZ, the help file must be named EVXYZ.HLP. A user can reference
this file by typing ‘"HELP EVXYZ".

The purpose of a diagnostic program’s help file is to provide the program
user with a quick reference source that will summarize the program’s
unique characteristics. Information contained in a help file should include:
A program abstract

ATTACH procedures

A list containing the name and function of each program section

Descriptions of devices not supported by the VDS (devices for which
p-table descriptors reside in the diagnostic program instead of in the
VDS)

A list containing the number and use of any user-selectable event flags
referenced by the program

A description of the program’s “’quick mode” operation
Descriptions of tests requiring manual intervention

The format of the program’s summary message, if one exists
6.4.4.2

Creating Help Files

Help files consist of keywords and associated text. Keywords are used
by the VDS to locate the proper text to display. For instance, if a user
typed HELP EVXYZ SECTIONS, the VDS would search the help file
named EVXYZ.HLP for the keyword ““sections,” and then display the text
following that keyword. There are two types of keywords, referred to as
““numbered keywords’”’ and “qualifier keywords."”’

6-13

Creating a VDS Diagnostic Program

6.4.4.2.1

Numbered keywords
Each numbered keyword is preceded by a number from 1 through

5. This
number indicates the keyword’s level. Level 1 is the highest level,
and
is used to indicate the file’s main topics. Keywords with larger numbers
are considered to be subtopics of those with smaller numbers. If the file

contains a level 1 keyword followed by several level 2 keywords, followed
by another level 1 keyword, the level 2 keywords between the first and
second level 1 keywords are subtopics of the first level 1 keyword. If
the
second level 1 keyword was followed by another set of level 2 keywords,

they are subtopics of the second level 1 keyword.

The level number must be the first character of a new line. There
must be
one or more spaces or tabs between the level number and the

keyword.

When the user types a HELP command, the VDS will display the text
following the specified keyword. It will also display the keywords (but not
the text) of the next-lowest level subtopics associated with the specified
keyword. For example, suppose a portion of a help file consisted of the

following:
4

SECTIONS
Program

EVXYZ

HELP

for
2

SECTIONS

sections.

Type

section-name

a particular

section.

describing

DEFAULT

section.)

describing

MANUAL

section.)

READ_TESTS
describing

READ_TESTS

section.)

WRITE_TESTS
(Text

following

MANUAL

(Text

the

DEFAULT

(Text

EVXYZ

details

(Text

contains

describing

WRITE_TESTS

section.)

ATTACH

If the user typed “HELP EVXYZ SECTIONS”’, the following would

displayed:

SECTIONS
Program

for

EVXYZ

contains

HELP

EVXYZ

details

Additional
DEFAULT

the

SECTIONS

following

sections.

Type

section-name

a particular

section.

information available:

MANUAL

READ_TESTS

WRITE_TESTS

Any time a topic is specified with a HELP command, the VDS displays the
text associated with the topic and lists the subtopics (keywords with

higher level number) associated with the topic.

All of the subtopics of a topic are listed directly underneath the topic in the
help file. Thus, all the level 3 subtopics associated with a level 2 keyword

would directly follow that level 2 keyword.

6-14

Creating a VDS Diagnostic Program

In the above example, suppose the user typed, "HELP EVXYZ SECTIONS
DEFAULT"”. The VDS would display the text associated with the level 2

keyword “‘default,” and then would list any level 3 keywords that follow
the text for ““default.”” (The sample help file above does not associate any
level 3 keywords with “’default.”’)
6.4.4.2.2

Qualifier keywords
It is unlikely that a diagnostic program’s help file will require qualifier

keywords, since they are only used to indicate command line qualifiers.
They are not preceded by a level number; instead, they begin with the

slash (/) character. However, a level number is implicitly associated with a
qualifier keyword; that number is one greater than the number specified in

the most recently specified numbered keyword. That keyword should be
““Qualifiers’”’. This is illustrated in the following example:

START

Execute

a previously

loaded

image.

Format:

START
2

[qualifiers]

Qualifiers

/SECTION:section-name
Select

program

section

tests

to be

executed.

/TEST:first:last
Select

range

executed.

The slash (/) character must be the first character of a new line. The

keyword must immediately follow the slash (/). Following the keyword
there may be an additional string, as in /QUAL:string.
Note: If one qualifier keyword directly follows another, with no text in between,

the second qualifier keyword will be treated as part of the text for the first.
This is useful for qualifiers of the form /qual and /NOqual.

6.4.4.2.3

Text

Text must immediately follow the keyword with which it is associated.
Keywords must start on a new line. Each line of the text must be indented

one space from the left margin. Text associated with level 1 keywords

should not extend beyond column 65. Text associated with keywords of
any other level should not extend beyond column 60. The text is more

easily readable if it does not exceed the length of the display screen (no

scrolling should occur).
6.4.4.3

Contents of Help Files
Help files for diagnostic programs must contain the following level 1

keywords and associated text:
1

ATTACH — Describe the attach procedures for the program. That
is, list the set of ATTACH commands that are necessary to create the
proper links from the unit under test to the processor.

6-15

Creating a VDS Diagnostic Program

DEVICE — Under this keyword, include a level 2 keyword for every
device tested by the diagnostic program. Under each level 2 keyword,
provide either of the following:

For devices with p-table descriptors contained in the VDS, the
text should state, ““Type HELP DEVICE device-type for device
description.”’

For devices with p-table descriptors contained in the diagnostic
program, provide a device description similar to the device
description that is obtained from typing ‘"HELP DEVICE device-

type.”
3

EVENT — List any user-selectable event flags referenced by the
program and describe their function.

HELP — This text should contain an abstract of the program. The text
associated with the HELP keyword is displayed when a user types
"HELP EVXYZ’ without including a keyword. In other words, this is the

default keyword.
5

QUICK — Describe the operation of the program when the QUICK flag
is set.

SECTIONS — List and describe each section of the program. Be sure
to include the DEFAULT section. If a MANUAL section exists, clearly
detail the actions that must be performed by the user.

SUMMARY — If the program contains a summary routine, provide an
explanation of the information displayed by that routine.

The above keywords must appear in every help file. Other keywords

should be added to provide information on unique program characteristics.
The keywords must be placed in the help file in alphabetical order.
A sample help file is provided in Appendix D.

6.5

Diagnostic Program Considerations

6.5.1

Run-Time Environments
One of the main purposes of the VAX Diagnostic Supervisor, as stated in
Chapter 2, is to insulate the diagnostic program from the various runtime
environments that exist for diagnostic programs.
Thus, if all of the rules, guidelines, and conventions described in this
manual are followed, any diagnostic program written should be capable
of executing in any of the run-time environments under which diagnostic
programs are expected to run.

Possible run-time environments for VDS diagnostic programs include (but
are not limited to):

6-16

User mode

Standalone mode

Automated Product Test (APT)

Creating a VDS Diagnostic Program

6.5.2

Remote Diagnosis (APT/RD)

Error Message Formats
As stated in Chapter 3, error messages are displayed by invoking the

$DS_ERRxxxx services. Error messages consist of three levels. They should
adhere to standard formats.
The format of the first message level (the message header) is controlled by

the VDS.
The formats of the second and third message levels are controlled by the
programmer. These parts of the error message are constructed with the

error-reporting routines called by the $DS_ERRxxxx services and delimited
by $DS_BGNMESSAGE and $DS_ENDMESSAGE macros.
When error-reporting routines are constructed, messages should be
formatted as follows:

Invalid contents of a register.
A message that reports invalid contents of a register should indicate the
expected contents, the actual (received) contents, and an exclusive-OR
(XOR) of the expected and received values. Mnemonics of bits set in

the XOR value should be displayed. Indicate the radix of all values
displayed.
Example:

EXPECTED:

5068 (X)

RECEIVED:

0000 (X)

XOR:

5068(X)

;TIE,SAE,RIE,MSE,MAINT,

FUNC=READ

Reporting data comparison errors for buffers
When data comparison errors are detected in data transfer buffers, the

error message should include:
—

The base address of the failing device

—

The address of the buffer

—

The size of the data transfer

—

The number of comparison errors

—

The buffer address and contents of all bad data

Example:
Device base address

60010500(X)

Expected

buffer

address

OE10(X)

Received

buffer

address

1010(X)

Transfer

size

256

Words

in error

words

Address:

Expected:

Received:

XOR:

0E104

1010

1000

0010

0E110

1010

1000

0010

OE1CO

1010

1000

0010

0E1F0

1010

1000

0010

If there is a large number of errors, only display the first eight.
6-17

Creating a VDS Diagnostic Program

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

144270(0)

RPWC

777710(0)

;SC,TRE,DVA,RDY,FUNC=WRITECHECK

RPBA

001000(0)

RPDA

001001(0)

;TRACK=2,SECTOR=1

RPCS2

040203(0)

;WCE,OR,UNIT=3

(eté.)

6.5.3

Volume Verification
All diagnostic programs that write onto magnetic media must provide

a mechanism to ensure that a customer’s database is not inadvertently

destroyed.
Some disks provide for a portion of the medium (called ‘“maintenance
tracks”’) to always be reserved for diagnostic purposes. If a diagnostic
program writes only on the maintenance tracks, the customer’s database

will not be affected.
If a device being tested does not provide maintenance tracks, or if the

diagnostic program does not limit itself to only using the maintenance
tracks on a device that does provide them, the entire medium must be

protected; a method must exist for verifying that the medium loaded in the
device under test may be written.
Thus, for devices that do not provide maintenance tracks, diagnostic
programs must check the volume name of a storage medium before
executing any tests that will write on that medium. By convention, media

that contdin no stored data, and therefore are available for the writing of
test patterns by diagnostic programs are named SCRATCH.

Volume verification must take place in a program’s initialization code.
The program must read the storage medium’s home block to determine
the medium’s volume name. (Refer to the FILES-11 On-Disk Structure
Specification for a description of the home block’s format.) If the volume
name is SCRATCH, the medium may be used and testing may begin. If

the volume name is anything other than SCRATCH, the program must

ask the user (via the $DS_ASKLGCL system service) if it is acceptable
to use the medium. If the response is “‘no’’ (the user does not wish the
medium to be used), then the program should issue a $DS_ABORT call.

A DEFAULT RESPONSE MUST BE PROVIDED FOR THE $DS_ASKLGCL
SERVICE, AND THE DEFAULT MUST BE ““NO.”’ This 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.

Creating a VDS Diagnostic Program

The volume verification code should only be executed the first time through
the initialization code (use the $DS_BPASSO or $DS_BNPASS0 macro).
Otherwise, the user would have to respond to the $DS_ASKLGCL question
for every program pass.

Note: Previous editions of this guide have indicated that, when asking the user

if it is acceptable to use a nonscratch medium, the user prompt passed

to the $DS_ASKLGCL service must begin with a null character. This
null will force the VDS to check the user terminal for a response to the
question, even if the program is being run by a command file (script). (If
the program is being run by a command file, all responses are obtained
from the command file unless the prompt string begins with a null.)
This is not good practice, because it forces limitations onto the user
regarding how the program may be executed. It should be 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 preceded with a null character. (Refer to the
VAX/DS Diagnostic Supervisor User’s Guide for a description of command
files.)

6.5.4

Long Silences
A long silence is a long period of time in which there is no communication

between the diagnostic program and the user. Sometimes long silences are
good and sometimes they are not.
A long silence is good when the diagnostic program is running for a long

period of time, either because the program’s execution time per pass is
long or because a large number of passes has been selected by the user.

If the user’s terminal is a hardcopy terminal, long silences save paper and
decrease the risk of the unattended, jammed printer scenario; i.e., printer

jams and halts which cause the diagnostic to hang indefinitely since no
attendant is present to restart it.

On the other hand, a long silence is bad when a user is present at the
terminal, monitoring the program’s progress. In this case, the user would
like to be kept abreast of the program’s status during long executions in
order to be assured that the program is not hung. If a long silence occurs,
the only way a user can monitor program progress is to type a control-C,

then SHOW STATUS, then CONTINUE. Thus, a diagnostic program must
have the capability of both eliminating and providing long silences.

To eliminate long silences in programs with long execution times per pass,
the program should cause a message to be displayed at least once per
minute. An AST routine may be used for this purpose. The message

should be a simple, succinct indication to the user that program execution
is progressing properly.

To provide for long silences when the user desires them, a means of
disabling the above-mentioned AST routine should be provided. For

example, the AST routine should check the status of the OPERATOR flag

(by using the $DS_BOPER or $DS_BNOPER macros) and only print the
message if the flag is set.

6-19

Creating a VDS Diagnostic Program

6.5.5

Hardware Preparation
Hardware preparation is the act of setting the device under test in some

physical state before testing begins. Hardware preparation may include
setting switches, connecting a cable, loading a special medium into the

device, and the like.
Ideally, diagnostic programs should be written so that no hardware
preparation has to take place. If this is not possible, hardware preparation

should be kept to an absolute minimum, since it lengthens testing time and
is a nuisance for the program user.
All hardware preparation should occur before the program is started. If the

program requests hardware preparation during execution, it is referred to
as ““manual intervention” (see Section 6.5.6, and is considered to be even
more of a nuisance.
If a program detects a preparation error (hardware not set up correctly), the

$DS_ERRPREP service should be used to report the error.

6.5.6

Manual Intervention
The term manual intervention refers to user actions during program

execution. A program requiring manual intervention is 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 a piece of hardware
to (or removing one from) the system under test, or it might be a simpler

action, such as typing a response on the terminal.
Ideally, no diagnostic program should ever require manual intervention,

because manual intervention complicates the operation of the program
from the user’s point of view.
If inclusion of manual intervention cannot be avoided, the following rules

must be followed:
*

If the manual intervention involves any actions other than responding
to questions at the user terminal, the tests that require these actions

must be placed in a program section called MANUAL. Examples of
such actions are setting a write-enable switch, connecting a cable, or
watching patterns generated by a program that tests video display
terminals.

Each test within the MANUAL section must use the $DS_BOPER or

$DS_BNOPER macro to determine if a user is present. If a user is not
present, the test must call the $DS_ABORT service.

Communication with the user must be performed by using the

$DS_ASKxxxx macros.
e

If $DS_ASKxxxx macros are includedin the MANUAL section, it is not
necessary to provide default responses.

6-20

Creating a VDS Diagnostic Program

If $DS_ASKxxxx macros are used anywhere other than in tests within
the MANUAL section, default responses must be provided. If default
responses are included, and if the user clears the OPERATOR flag, the
default responses will automatically be used and the user will not have
to be present. (This is also true for the DEFAULT section.)

6.5.7

Quick Mode
Quick mode is a mode of program execution in which the main objective is
to provide a relatively fast execution time per pass. It is a convenient mode
to provide in programs having long execution times. It should provide a
fast pass/fail testing capability with little or no fault isolation. It will be
employed when a user wants a quick verification of hardware integrity.

The decision of whether or not a diagnostic program will provide a quick
mode is one shared between the programmer and the program'’s users.
Specific functions of a particular program’s quick mode are also to be

decided by mutual agreement between the programmer and users. As a
guideline, if total execution time for one full program pass under normal
operating conditions is greater than two minutes, you should consider
including a quick mode in your diagnostic program.

If quick mode operation is provided, it is to be executed only if the user
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 flag.

Use caution to determine which functions of the diagnostic program will
not be utilized in quick mode. The program must be documented so that
the user will understand the exact functional differences between normal
and quick modes, since frequently intermittent errors will surface only
while running under normal (non-quick) mode.

6.5.8

Naming Symbols
To maintain consistency between diagnostic programs, it is important

to obey certain conventions when creating names for symbols. These
conventions are as follows:

The dollar sign ($) character is included in all publicly defined symbols
located in the VDS and in all other system level software provided
by DIGITAL. To differentiate private symbols (those available only to
the program in which they are defined) from public symbols, private
symbols should not include the dollar sign ($) character. Since all
symbols defined in diagnostic programs are private, the dollar sign ($)
should never be used.

Note: There is one exception to this rule; since p-table descriptors are
public, their names should include dollar signs. See Section 3.2.3,
P-Table Descriptors, for details and examples.

To determine the characters allowed in a symbol name, and the
maximum length of a symbol name, refer to the reference manual
for the language in which the program is being written.
6-21

Creating a VDS Diagnostic Program

Global variable names are of the form:
Gt_variablename
where ““t” is a letter indicating the variable type (see Table 6-1).

Global arrays are of the form:
A_arrayname
Structure field names are of the form:
structure_t_fieldname

where

lltll

is a letter indicating the variable type (see Table 6-1).

Entry points to global routines having nonstandard calls

form:

are of the

entryname_Rn

where registers RO through Rn are not preserved by the routine
therefore must be saved by the caller.

When naming bits and bit fields in hardware registers, use
mnemonics specified in the hardware documentation.

Table 6-1 contains letters used for data types.

Data Type or Usage
Address

Byte integer
Single character
Double precision floating

Reserved to DIGITAL
Single precision floating

General value

Reserved for integer extensions

Reserved to customers for escape to other codes

Integer value for counters

Z22Tr
X &~

Letter

w
6-22

Letters Used to Indicate Data Types

TmMMmOoOO
W >

Table 6-1

Constant

Longword integer
Field mask

Numeric string (all byte forms)
Reserved to DIGITAL as an escape to other codes

Packed string

Quadword integer
Reserved for records (structure)
Field size

and

the bit

Creating a VDS Diagnostic Program

Letters Used to Indicate Data Types

Letter

Data Type or Usage

N <Xgs<cH

Table 6-1 (Cont.)

Text (character) string

Smallest unit of addressable storage

Field position (assembler); field reference (BLISS-32)
Word integer

Context dependent (generic)
Context dependent (generic)

Unspecified or nonstandard

Some examples of symbol names are:
A_RP_REG

- Address of storage array for RPxx controller registers

RP_REG_I_RPDS - Offset RPDS into array RP_REG

GW_BYTE_COUNT - Address of global word containing byte count

6.6

Linking a Diagnostic Program
Before a diagnostic program is released, it must be linked as a “’system
image,”” using the command line:
$

LINK/SYSTEM=S512

EVXYZ1l,

EVXYZ2,

where EVXYZ1, EVXYZ2, and so on, are the source modules for program
EVXYZ.

If the symbolic debugger for diagnostic programs (VDSDEBUG) is to be
used during program development, another linking procedure must be
used. Refer to the VAX Diagnostic Debugger User’s Guide for a description of
that procedure.

6.7

Debugging a Diagnostic Program
Two facilities are available in debugging diagnostic programs.

The VDS command language provides several commands that are
useful for debugging programs. Commands are available for examining
and altering memory locations within the diagnostic program, setting
breakpoints, and ‘‘single-stepping’’ through the program. Refer to the
VAX/DS Diagnostic Supervisor User’s Guide for details.

More debugging capabilities are provided by the VAX Diagnostic Debugger
(VDSDEBUG,). This is a separate program that can run under the VDS
in conjunction with a diagnostic program. It provides such features as
breakpoints, watchpoints, queue traversal, referencing program locations by
their symbolic names, plus examining and depositing contents of program
locations as numeric data, character strings, or MACRO-32 instructions.
Refer to the VAX Diagnostic Debugger User’s Guide for details and operating
instructions.

6-23

Creating a VDS Diagnostic Program

6.8

Quality Assurance

6.8.1

Quality Requirements
All diagnostic programs must meet certain quality standards.

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 provide accurate, detailed

documentation that gives both users and maintainers all the information
they will need to perform their jobs. Documentation must adhere to

the guidelines spelled out earlier in this chapter.

Functional quality
The program must provide all of the functional capabilities contained
in the functional specification.

Operational quality
The program must operate in accordance with the rules established in

this manual.

6.8.1.1

Documentation Quality
Following is a list of the documentation that must be provided with every

diagnostic program:
Documentation file

The documentation file must adhere to the format presented in

Appendix C.
Map file
For program EVXYZ, the map file EVXYZ.MAP produced by the linker

must be provided.
Listing file
For program EVXYZ, the listing file produced by the MACRO-32

assembler or BLISS-32 compiler must be provided. For MACRQO-32
programs, a cross-reference table must be included. Within the

listing, the guidelines spelled out in Section 6.4.3, Source Code
Documentation, must be followed.
Help file
A help file must be provided. It must match the format presented in

Section 6.4.4, Help Files.

6.8.1.2

Functional Quality

The program developer must ensure that all functions described in the
program’s functional specification have been properly implemented.

6-24

Creating a VDS Diagnostic Program

6.8.1.3

Operational Quality

To ensure the execution quality of a diagnostic program, the following steps
must be performed. It is strongly suggested that you perform steps 2-6 in
the order shown):

Load and normal start.
a.

Load the VDS.

Issue the proper ATTACH and SELECT commands.

¢.

Load and start the program with the LOAD and START commands
or the RUN command.

The program should execute without errors and stop after one
program pass.

For EACH SECTION of the program, the following should be
performed:

Trace mode

Issue the SET TRACE command, then START. Check that test
numbers and trace messages coincide with program documentation
for the section being executed.
b.

Multiple passes

Execute the section again, specifying a pass count of at least 10.

For each test of the program, the following steps must be performed:
a.

Reverse order testing

Execute each test, one at a time, starting with the highest-numbered
test and ending with test number 1. Allow each test to complete
one pass.

Multiple loop-on-test

Execute each test individually, specifying a pass count of at least
10.

¢.

Multiple loop-on-subtest

Execute each subtest of each test individually, specifying a pass
count of at least 10.

Control-C response

For each test, start the test and type control-C. A response to
the control-C should occur within three seconds. When the VDS
prompt is displayed, type CONTINUE. The program must continue
from where it was interrupted and must successfully complete the
pass.

Event flags

Check that all event flags are used only as indicated by the
program’s documentation.

6-25

Creating a VDS Diagnostic Program

Power off
Shut off the power for the device under test. The program must
display a message stating that the device is without power.
Write Protection
Write-protect the device under test. Tests that write to the device

should display messages indicating that the device is writeprotected.

Off line
Place the device off-line. The program should state that the device
is off-line.

Minimum hardware configuration

Set up a hardware configuration that matches the minimum
hardware configuration specified in the functional specification.
All tests must execute on this configuration.
Maximum hardware configuration

Set up a hardware configuration that matches the maximum

hardware configuration specified in the functional specification.
All tests must execute on this configuration, and all units of the

device under test must be tested.
Module extender board
Place each logic module of the device under test on an extender
board, one at a time, and verify that each test will execute

successfully.
Transportability

Repeat all of the steps in this section on every VAX processor type
on which the program is supposed to run.
. Marginal testing

If the program has been specified to be executed successfully under
marginal conditions (voltage, timing, and so on), execute each test

under these conditions.
Error reporting and loop-on-error
—

Make sure that no $DS_ERRxxxx macros are ever executed
when the cleanup code is run (typing ABORT will cause the

cleanup code to be run).
—

Set the LOOP and HALT flags. This will cause every error
reporting macro ($DS_ERRxxxx) to be executed. This can be
accomplished either by causing hardware failures on the device
under test or by temporarily patching the program.

6-26

Creating a VDS Diagnostic Program

For EVERY $DS_ERRxxxx macro, do the following;:
CLEAR the IE1, IE2, and IE3 flags.
Make sure that all error messages are printed, and that they
are of the proper format (see Section 6.5.2, Error Message
Formats).

Make sure that the entire message has been printed before
the DS> prompt is displayed.
Clear the IE3 flag.
Type CONTINUE, and make sure that a loop begins
executing.

The $DS_ERRxxxx macro should be reexecuted, but this
time the third level of the error message should not be
displayed.
When the DS> prompt appears, clear the IE2 flag.
Type CONTINUE.

The $DS_ERRxxxx macro should be reexecuted, but this
time the second and third levels of the error message
should not be displayed.
Clear the IE1 flag.
Type CONTINUE.

The $DS_ERRxxxx macro should be reexecuted, but this
time none of the error message should be displayed.

Set the IE1 flag and clear the HALT flag.
Type CONTINUE.

Allow the loop to execute several more times.
The following step must be performed for the DEFAULT section.

No operator

Clear the OPERATOR flag, then execute the DEFAULT section for

one pass. The program must execute successfully, and the user
must not be required to type any characters on the terminal or

perform any other form of manual intervention.
The following additional steps must be performed for programs that
execute in standalone mode:
Memory Management on
Turn memory management on and execute each test for several

passes. Each test should execute successfully unless the program

should not be executed with memory management turned on, in
which case the program should abort without errors.

6-27

Creating a VDS Diagnostic Program

Invalid address
Using the ATTACH command, specify an incorrect device address.
The program should display a message indicating that an invalid

address has been specified.
*

APT compatibility

To verify that the program will execute under the APT run-time
environment, run the program under APT for eight hours.

The following step must be performed for programs that execute in
user mode. Make sure that all units are properly deallocated after the

diagnostic program has finished. Issue the following VDS and VMS
commands in order:
*

ATTACH device-name

SELECT device-name

RUN program-name

Type control-C

ABORT

Type control-Y

SHOW DEVICE

None of the devices that were tested, used for error logging, or made
use of in any way by the diagnostic program should be still allocated.

6.8.2

Automated Quality Assurance
In order to aid the programmer in determining the quality of a diagnostic

program, the VDS provides 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 the RUN or

START command. Operating instructions for Auto-QA are described in the
VAX/DS Diagnostic Supervisor User’s Guide.

Following is a list of the quality assurance checks performed by Auto-QA.

Note that Auto-QA only checks the DEFAULT program section. Quality
assurance of other program sections must be performed manually.

Normal Start Check
This check will perform a normal load and execution of the diagnostic
program with the TRACE flag set.

The program must make an error-free pass, printing out the normal
trace messages and terminating with End-of-Pass. If the program does
not execute an error-free pass, an appropriate QA error message will

be printed. The trace messages must be visually checked by the user.

This check also makes sure that the DEFAULT section does not request
input from the user. (The OPERATOR flag is cleared.)

6-28

Creating a VDS Diagnostic Program

This check is equivalent to the following sequence of VDS commands:
DS>

CLEAR FLAG ALL

DS> SET FLAG TRACE

DS> RUN diagnostic-program-name
DS>

CLEAR FLAG TRACE

Multiple Passes Check
This check will execute 10 passes (by default) of the diagnostic

program. The program must make 10 error-free passes and terminate

after the tenth pass. If this does not happen, an error message will be
printed.
The number of passes executed by the diagnostic program can be

changed by the user.
This check is equivalent to the following VDS command:
DS> START/PASS:10

Infinite Loop-On-Test Check

This check will execute each test in the diagnostic program’s DEFAULT
section 100 times (by default). The diagnostic must execute each test
the given number of times. If the diagnostic does not execute properly,
an error message will be printed.

The number of times each test is executed can be changed by the user.
This check is equivalent to the following VDS commands:
DS> START/PASS:100/TEST:1:1
DS> START/PASS:100/TEST:2:32

DS> START/PASS:100/TEST:i:n:n

where 'n’’ is the highest numbered test in the DEFAULT section. The
tests are executed in ascending order.
Infinite Loop-On-Subtest Check
This check will execute each subtest in each of the tests in the
diagnostic program’s DEFAULT section 100 times (by default). The
program must loop on each subtest the given number of times. If the
program does not execute properly, an error message will be printed.
The number of times each subtest is executed can be changed by the

user.

;

6-29

Creating a VDS Diagnostic Program

This check is equivalent to the following Supervisor commands:
DS> START/PASS:100/TEST:1:1/SUBTEST:1
DS> START/PASS:100/TEST:1:1/SUBTEST:2

DS>

START/PASS:100/TEST:1:1/SUBTEST:ml

DS>

START/PASS:100/TEST:2:2/SUBTEST:1

DS> START/PASS:100/TEST:2:2/SUBTEST:2

DS>

START/PASS:100/TEST:2:2/SUBTEST:m2

DS>

START/PASS:100/TEST:n:n/SUBTEST:1

DS>

START/PASS:100/TEST:n:n/SUBTEST:?2

DS>

START/PASS:100/TEST:n:n/SUBTEST:mx

where ““n”’ is the highest-numbered test in the DEFAULT section, and
“mx”" is the number of subtests in test “‘x.”

The tests and subtests are executed in ascending order.
Run Individual Tests in Reverse Order Check
This check executes the tests in the diagnostic program’s DEFAULT

section in reverse order. This check ensures that a test does not
depend on results from a previous test, and that each test is a
standalone entity. If the diagnostic program does not execute properly,
an error message will be printed.
This check is equivalent to the following VDS command:
DS>

START/TEST:n:n

DS>

START/TEST:n-1:n-1

DS>

START/TEST:1:1

where “‘n’’ starts at the highest numbered test in the DEFAULT

section, and descends to the first test. That is, the tests are executed in

descending order.

6-30

Template for the VDS Diagnostic Program Header
Module

Header Module Template for Macro-32 Programs
This is a template to aid in the development of the header module of a
diagnostic program that will run under the VAX Diagnostic Supervisor
(VDS). 1t is not intended to be a tutorial for writing the program.
Areas that must be deleted or replaced by the programmer are enclosed
within matching sets of triple asterisks.

Areas that may be optionally modified are enclosed within matching sets
of double asterisks.

Comments marked with one asterisk are for informational purposes and
should be deleted.

Template for the VDS Diagnostic Program Header Module

+TITLE

***

.IDENT

/01/

PROGRAM

.LIST

MEB

.NLIST

CND

+PSECT

HEADER,

LONG,

***

NOWRT

CHANGE ALIGNMENT

WORD

CHANGE

DISPLACEMENT,

THIS

LONG

PAGE

FOR

DEBUG

DIGITAL EQUIPMENT CORPORATION,

(C)

1983

MAYNARD,

MASSACHUSETTS

01754

THIS

COMPUTER

ABOVE

MAY NOT

EXCEPT

TERMS.

-DEFAULT

NAME

SOFTWARE

REMAIN

FURNISHED

SYSTEM AND

NOTICE.

PROVIDED OR

FOR USE
TITLE

SUCH

TO AND

UNDER A LICENSE
BE

COPIED

THIS

SOFTWARE,

OTHERWISE

OR ANY

THE

ONE

THE

ONLY

ON A

SINGLE

INCLUSION

OF THE

OTHER COPIES

MADE AVAILABLE

SYSTEM AND
OWNERSHIP

FOR USE

ONLY WITH

THEREOF,

TO ANY OTHER

WHO AGREES
SOFTWARE

THESE

PERSON
LICENSE

SHALL AT ALL

TIMES

DEC.

NP
WO

INFORMATION

CORPORATION.

NOT

THIS

CONSTRUED

SOFTWARE

SUBJECT

CHANGE

A COMMITMENT

WITHOUT

DIGITAL

NOTICE

EQUIPMENT

SOFTWARE ON

RESPONSIBILITY

EQUIPMENT

WHICH

FOR

IS NOT

THE

USE

SUPPLIED

RELIABILITY

ITS

BY DEC.

FACILITY:

VAX

DIAGNOSTIC.

ABSTRACT:

***

Short

ENVIRONMENT:

VAX

DIAGNOSTIC

SUPERVISOR.

AUTHOR:

***

NAME

***

description

program.

**=*

DATE

VERSION

Ol.

MODIFIED

BY:

TMo

DEC ASSUMES

THE

AND SHOULD

MAY

« PAGE

DECLARATIONS

INCLUDE

FILES:

«.SBTTL

. LIBRARY

\SYSSLIBRARY :DIAG.MLB\

;**

Declare programmer-defined

(Libraries

are searched

libraries

;

VAX FAMILY DIAGNOSTIC LIBRARY.
here.

in reverse to the order

listed.)

H
+

MACROS:

USER MACROS

(OPTIONAL).

***

EQUATED

SYMBOLS:

weo

;***

A-2

$DS_BGNMOD

*%%

$DS_DSSDEF

GLOBAL

USER

EQUATED

SYMBOLS

ENVIRONMENT ***

***

# SUPERVISOR SERVICE ENTRY VECTORS

Template for the VDS Diagnostic Program Header Module

. PAGE

.SBTTL.

PROGRAM

HEADER DATA BLOCK.

j++

THE

TMo

ALLOW

“e

THE

FUNCTIONAL DESCRIPTION:
PROGRAM

BEGINNING AT

THE

HEADER

DATA

DIAGNOSTIC

BLOCK

CONTAINS

SUPERVISOR TO

SUPERVISOR LOOKS

PARAMETERS

FOR

THE

WHICH

PROGRAM.

HEADER

INFORMATION

200(HEX).

VIRTUAL ADDRESS

THE

CONTROL

$DS_HEADER
+.SBTTL

<***PROGNAME***>,

REV=01,

UPDATE=0,

NUNIT=**]1*%*

DISPATCH TABLE.

P+
;

;

THE

;

BEGINNING

DISPATCH

;

LIST

;

DISPATCH.

THE

TABLE

EACH

TEST

LINKER.

COLLECTION

AND

THIS

GROUPED
IS

DONE

OF ADDRESSES
TOGETHER
BY

GENERATED

THE

INTO A CONTIGUOUS

DEFINING

PSECT

CALLED

;

;—

$DS_DISPATCH

.SBTTL

PROGRAM GLOBAL DATA

.PSECT

DATA,LONG

SECTION.

FUNCTIONAL DESCRIPTION:

“we

* **

* *

ALL
THIS

DYNAMICALLY
IS

THE

MODIFIED

ONLY

PSECT

DATA

WHICH

SHOULD
WILL

STATISTICS

TABLE.

. PAGE

$DS_BGNSTAT

$DS_ENDSTAT
;***

QTHER GLOBAL

DATA

(OPTIONAL).

***

PLACED

NORMALLY
BE

THIS

WRITE

SECTION,

ENABLED.

***

**x*

Template for the VDS Diagnostic Program Header Module

. PAGE

PROGRAM

TEXT

SECTION.

+
+

FUNCTIONAL

DESCRIPTION:

CHARACTER

SECTION

CONTAINS

ALL

THE

DATA

STRUCTURES

THAT ARE

MADE

STRINGS.

PROGRAM

SECTION

NAMES.

THIS

.SBTTL

$DS_SECTION
.

<***

SECTION

NAMES

<**%*

DEVICES

***>

DEVICE

’

MNEMONICS

LIST.

[

DEVICE:

$DS_DEVTYP
.

[

NAMES

DEVICE

REGISTERS

AND

BIT

MNEMONICS

[

’

1
.

***

ASCII

***

USE

NAMES

WITH

THE

DEVICE

REGISTERS

$DS_CVTREG MACRO

AND

THEIR

ROUTINE,

BITS

***

;

FORMATTED ASCII

OUTPUT

STATEMENTS.

i
7 ***

MESSAGES

THE

OPERATOR,

ETC.

(OPTIONAL).

;+
[

STRINGS

USED

REPORT

ERRORS

i ***

ERROR

REPORT

MESSAGES.

(OPTIONAL)

***

(OPTIONAL)

FOR

***

Template for the VDS Diagnostic Program Header Module

«PAGE

CODE.

+
+

INITIALIZATION

FUNCTIONAL

DESCRIPTION.

.SBTTL

ROUTINE

DESCRIPTION

WILL
OF

YOUR

EXECUTED AT
ROUTINE.

THE

BEGINNING

EACH

PASS.

***

CALLING

SEQUENCE:

THIS
il

THE

DIAGNOSTIC

SUPERVISOR

CALLS

THIS

ROUTINE

WITH A

CALLG

INPUT

PARAMETERS:

INSTRUCTION.

NONE

IMPLICIT

INPUTS:

NONE

*=*

OUTPUT

PARAMETERS:

*%*

NONE

IMPLICIT

OUTPUTS:

NONE

COMPLETION

CODES:

NONE

SIDE

EFFECTS:
**

NONE

$DS_BGNINIT
;***

DEVICE

INITIALIZATION

CODE.

***

$DS_ENDINIT

A-5

Template for the VDS Diagnostic Program Header Module

«PAGE
E
+

CLEAN-UP CODE.

FUNCTIONAL DESCRIPTION:

***

CALLING SEQUENCE:

DESCRIPTION OF YOUR ROUTINE.,

*
*»

THIS ROUTINE IS EXECUTED AT THE COMPLETION OF THE LAST PROGRAM PASS.

.SBTTL

THE DIAGNOSTIC SUPERVISOR CALLS THIS ROUTINE WITH A CALLG

INPUT PARAMETERS:

“o

INSTRUCTION.

NONE

IMPLICIT

INPUTS:

NONE

*#*

OUTPUT PARAMETERS:

NONE

IMPLICIT OUTPUTSS

NONE

COMPLETION CODES:

NONE

SIDE EFFECTS:
*%

NONE

*%*

j*#**

A-6

$DS_BGNCLEAN
DEVICE "SHUT-DOWN" CODE.
$DS_ENDCLEAN

*%*

Template for the VDS Diagnostic Program Header Module

.PAGE

SUMMARY REPORT CODE.

+
+

.SBTTL

FUNCTIONAL DESCRIPTION:

THIS ROUTINE ISSUES A SUMMARY REPORT UPON REQUEST FROM THE

G CALL IS MADE.
OPERATOR OR WHEN A $DS_SUMMARY_
DESCRIPTION OF YOUR ROUTINE. ***

CALLING SEQUENCE:

THE DIAGNOSTIC SUPERVISOR CALLS THIS ROUTINE WITH A CALLG

e MO WE WO WE We Ve We We WG WO WO Ve WA WS WE _NWE We Ve W N Ve Ve Ve Vo W

INSTRUCTION.

INPUT PARAMETERS:
*%*

NONE **

IMPLICIT

INPUTS:

NONE **

OUTPUT PARAMETERS:
*%*

NONE

IMPLICIT OUTPUTS:
*%

NONE

COMPLETION CODES:
**

NONE **

SIDE EFFECTS:
**

NONE

$DS_BGNSUMMARY

;*** SUMMARY REPORT CODE.
$DS_ENDSUMMARY

(OPTIONAL)

***

A-7

Template for the VDS Diagnostic Program Header Module

+SBTTL
pRE

GLOBAL SUBROUTINES.

OPTIONAL GLOBAL

+
+

FUNCTIONAL

DESCRIPTION:

wE
NG

SEQUENCE:

CALLING

NONE

INPUT

PARAMETERS:

NONE

IMPLICIT

INPUTS:

NONE

OUTPUT

PARAMETERS

NONE

IMPLICIT

OUTPUTS:

NONE

COMPLETION

CODES:

NONE

SIDE

EFFECTS:

NONE

REGISTERS

USED:

NONE

SUBROUTINES,

SERVICE

INTERRUPT

¥ & K

$DS_ENDMOD
. END

A-8

ROUTINES,

SUCH AS
CONDITION

ERROR REPORTING
HANDLERS,

ETC.

ROUTINES,

Template for the VDS Diagnostic Program Header Module

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. It is not intended to be a tutorial for writing the program.
Areas that must be deleted or replaced by the programmer are enclosed

within matching sets of triple asterisks.

Areas that may be optionally modified are enclosed within matching sets
of double asterisks.

A-9

Template for the VDS Diagnostic Program Header Module

STITLE

’'***

MODULE

***

IDENT =

title

#*wx~/

module_name ***

(

'01-00’

(c)

1983

DIGITAL EQUIPMENT CORPORATION,
THIS

SOFTWARE

ONLY

1IN

MASS.

IS FURNISHED UNDER A LICENSE AND MAY BE USED AND
COPIED
WITH
THE
TERMS
OF
SUCH
LICENSE AND WITH THE

ACCORDANCE

INCLUSION OF THE ABOVE

COPIES

MAYNARD,

THEREOF MAY NOT

OTHER PERSON.

NO TITLE

THIS SOFTWARE OR
ANY
OTHER
BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY
TO AND OWNERSHIP OF
THE
SOFTWARE
IS
HEREBY

TRANSFERRED.
THE
AND

INFORMATION
SHOULD

IN THIS

NOT

SOFTWARE

CONSTRUED

SUBJECT

TO CHANGE

A COMMITMENT

CORPORATION.
DIGITAL ASSUMES

NO RESPONSIBILITY

SOFTWARE ON EQUIPMENT WHICH

FOR THE

USE

WITHOUT

RELIABILITY

IS NOT SUPPLIED BY DIGITAL.

! ++
!

FACILITY:

VAX-11

ABSTRACT:

***

ENVIRONMENT:

VAX~-11l

DIAGNOSTIC

abgtract ***

SUPERVISOR

AUTHOR:

***

MODIFIED BY:

*®

DIAGNOSTIC

A-10

your

hame

***, 6

DATE:

***

cdate

***,

NOTICE

BY DIGITAL EQUIPMENT

VERSION:

V01.0

ITS

Template for the VDS Diagnostic Program Header Module

%SBTTL 'Declarations’
L4+

TABLE OF CONTENTS:

*** routine names #**%*

~-e

FORWARD ROUTINE

144+

EXTERNAL DECLARATIONS:

EXTERNAL ROUTINE

*** routine names *** ;

! In module...

L++

INCLUDE FILES:

*x* Declare user-defined libraries and "require" files here ***
! VMS MACRO LIBRARY
LIBRARY 'SYS$LIBRARY:STARLET';
! VAX DIAGNOSTIC FAMILY LIBRARY
LIBRARY ’SYS$LIBRARY:DIAG';
1++

MACRO DEFINITIONS:

MACRO

*%% OPTIONAL USER-WRITTEN MACROS *** %;

L4+

DIAGNOSTIC SUPERVISOR MACROS:

fmmm

$DS_BGNMOD (ENV = *** environment **¥);
$DS_DISPATCH

$DS_DSSDEF
$DS_DSADEF
L+

PROGRAM SECTION NAMES:

$DS_SECTION (*** section names **¥*);
1+4

DEVICE MNEMONICS LIST:

$DS_DEVTYP (STRINGS = (*** device types ***),
ADDRESSES = (*** addresses of PT-desc ***));

A-11

Template for the VDS Diagnostic Program Header Module

Data

Block’

’'Program Header

%SBTTL

FUNCTIONAL

The program header

allows

The

DESCRIPTION:

beginning

data block contains

the Diagnostic

Diagnostic

Supervisor

address

for

the program.

the header

information

200 (HEX).

virtual

looks

the parameters which

to control

$DS_HEADER

(PNAME ='***
REV =

UPDATE
NUNIT

***’,

=
=

O,
***

’‘Program Global

pnumber

Data

units

*x*¥);

Section’

+
+

%SBTTL

program name

FUNCTIONAL
* % K

ALL

DYNAMICALLY MODIFIED

]
i

DESCRIPTION:

L4+

DEVICE

TABLE

$DS_BGNREG

$DS_ENDREG

STATISTICS

TABLE.

$DS_BGNSTAT

$DS_ENDSTAT
++

EQUATED

GLOBAL

SYMBOLS:

LITERAL

**%*

enter

OWN

STORAGE:

literals

***

;

!
1

***

A-12

enter

variables

***

GLOBAL

DATA

SHOULD

PLACED

THIS

SECTION,

***

Template for the VDS Diagnostic Program Header Module

%SBTTL

'Program Text Section’

FUNCTIONAL DESCRIPTION:

!
|

This section contains all the character strings.

!
!
!

NAMES OF DEVICE REGISTERS AND BIT MEMONICS:

GLOBAL

BIND

*%** ASCII names of device registers and their bits (optional)
for use with the $DS_CVTREG macro routine ***

L+

FORMATTED ASCII OUTPUT STATEMENTS:

*** messages to the operator,

etc.

(optional)

***

14+

STRINGS USED TO REPORT ERRORS

!
| R—

***

%SBTTL

enter

statements

***;

‘Initialization Code’

FUNCTIONAL DESCRIPTION:

!
!

This routine will be executed at the beginning of each pass

;

of the diagnostic.

i
i

FORMAL PARAMETERS:
** NONE **

;

IMPLICIT INPUTS:

i
;
:

** NONE **
IMPLICIT OUTPUTS:
** NONE **

COMPLETION CObES:

** NONE **

]

;

SIDE EFFECTS:

]

;

** NONE **

]

$DS_BGNINIT
BEGIN

***

jnitialization code ***

END;

$DS_ENDINIT

A-13

Template for the VDS Diagnostic Program Header Module

%SBTTL

’‘Clean-up Code’

FUNCTIONAL DESCRIPTION?

The clean-up code is

program pass.

***

Description of

FORMAL PARAMETERS:

NONE

*»

!
!

IMPLICIT

INPUTS:

H
!

NONBE

]
!

IMPLICIT OUTPUTS:

NONE

w*»

COMPLETION CODES:

NONE

*»

SIDE EFFECTS:

!
!

*%*

NONE

H
[J—

$DS_BGNCLEAN
BEGIN

***

cleanup code *ww

END;

$DS_ENDCLEAN

A-14

executed

your

the completion of

routine goes

here.

#*w»

the last

Template for the VDS Diagnostic Program Header Module

%SBTTL

’‘Summary Report Code’

14+

FUNCTIONAL DESCRIPTION:

!
!

This routine displays a summary report when the operator types
a SUMMARY command or when a $DS_SUMMARY call is issued.

*** Description of the summary routine goes here.

* %K

FORMAL PARAMETERS:

NONE

IMPLICIT

INPUTS:

]

*%*

NONE

IMPLICIT

OUTPUTS:

NONE

COMPLETION

CODES:

NONE

[)

SIDE EFFECTS:

NONE

H
11—

$DS_BGNSUMMARY
BEGIN

**%

gummary code

***

END;

$DS_ENDSUMMARY

A-15

Template for the VDS Diagnostic Program Header Module

***

Optional

global

subroutines,

interrupt

service routines,

be placed

here.

Subroutines’

FUNCTIONAL

DESCRIPTION:

+
+

‘Global

%SBTTL

***

PARAMETERS:

FORMAL

NONE

INPUTS:

IMPLICIT

NONE

OUTPUTS:

IMPLICIT

NONE

*%*

CODES:

COMPLETION

NONE

EFFECTS:

SEm

SIDE

NONE

USED:

REGISTERS

‘Summary

Report

FUNCTIONAL

DESCRIPTION:

FORMAL

PARAMETERS:

Gem

+
+

%SBTTL

NONE

IMPLICIT

INPUTS:

NONE

IMPLICIT

OUTPUTS:

NONE

COMPLETION

CODES:

NONE

SIDE

EFFECTS:

NONE

*=*

REGISTERS

USED:

NONE

$DS_ENDMOD;
END

ELUDOM

A-16

Code’

such

error

reporting

condition handlers,

etc,

routines,
should

Template for VDS Diagnostic Program Test Modules

B.1

Test Module Template for Macro-32 Programs
This is a template to aid in the development of a test module of a
diagnostic program that will run under the VAX Diagnostic Supervisor
(VDS). It is not intended to be a tutorial for writing the program.
Areas that must be deleted or replaced by the programmer are enclosed
within matching sets of triple asterisks.

Areas that may be optionally modified are enclosed within matching sets
of double asterisks.

Comments that contain only one asterisk are for informational purposes
and should be deleted.

Template for VDS Diagnostic Program Test Modules

+TITLE

***

.IDENT

/01/

+LIST

MEB

.NLIST

CND

THIS
ABOVE

N N NG
NE NP

WORD

VERSION NUMBER ***

CHANGE

THIS

CORPORATION,
FURNISHED

SYSTEM AND

REMAIN

PROVIDED

FOR USE

MAY

MAYNARD,

UNDER A
BE

THIS

OTHERWISE
SYSTEM AND

OWNERSHIP

FOR USE

ONLY WITH

SOFTWARE,

MASSACHUSETTS

LICENSE

COPIED

SUCH

TITLE TO AND

THE

INFORMATION

THIS

SHOULD

CONSTRUED

NOT

OR ANY

ONE

OF THE

SOFTWARE
AS

SUBJECT

COMMITMENT

DEC

ASSUMES

RESPONSIBILITY

WHICH

FOR

IS NOT

THE

USE

SUPPLIED BY

VAX

DIAGNOSTIC.

ABSTRACT:

***

Short

this

description

ENVIRONMENT:

VAX

DIAGNOSTIC

SUPERVISOR.

AUTHOR:

***

MODIFIED

BY:

B-2

NAME

DATE

***

VERSION

O1l.

WITHOUT

LICENSE

**x

NOTICE

EQUIPMENT

RELIABILITY

DEC.

module.

THESE

DIGITAL

“e

FACILITY:

THE

THEREOF,

SHALL AT ALL TIMES

CHANGE

SINGLE
OF

TO ANY OTHER PERSON

+
+

WO WS
+
+

ON EQUIPMENT

ON A

COPIES

SOFTWARE

ONLY

OTHER

WHO AGREES

DEBUG

01754

INCLUSION

MADE AVAILABLE

CORPORATION.

FOR

THE

DEC.

AND

SOFTWARE

LONG

1980

NOT

MAY

(C)

SOFTWARE

TERMS.

DISPLACEMENT,

EQUIPMENT

COMPUTER

EXCEPT

*#*%*

j***

+
<+

DIGITAL

NE WE e

WO Ne NG NG NS WE ws

-DEFAULT

PROGRAM MODULE NAME

ITS

Template for VDS Diagnostic Program Test Modules

.PAGE

.SBTTL

DECLARATIONS

—e

INCLUDE FILES:

.LIBRARY

\SYSSLIBRARY:DIAG.MLB\

; VAX FAMILY DIAGNOSTIC LIBRARY

MACROS:

—e

;** List programmer-defined libraries here.
;** (Libraries are searched in reverse order.)

(OPTIONAL). ***

EQUATED SYMBOLS:

s *** PROGRAMMER-DEFINED MACROS

s*%% SYMBOLS FOR LOCAL USE AND SUPERVISOR INTERFACE ***
;*** AND USER EQUATED SYMBOLS (OPTIONAL). ***

PROGRAMMER~DEFINED LOCAL AND GLOBAL STORAGE

SECTION DEFINITIONS:

~eo

$DS_BGNMOD <*#** ENVIRONMENT *%x %> TEST=*** NUMBER OF FIRST TEST IN MODULE***
; CHANNEL SERVICE SYMBOLS (LEVEL 3)
GLOBAL
SDS_CHDEF
: SUPERVISOR SERVICE ENTRY VECTORS
GLOBAL
$DS_DSSDEF

$DS_SECDEF

<*** SECTION NAMES ***>

Template for VDS Diagnostic Program Test Modules

. PAGE

<*%**

TEST NAME

***>

+
+

TEST

DESCRIPTION:

AND HOW THE

WILL

CONTAIN A BRIEF DESCRIPTION
TEST

OF WHAT

BEING TESTED

IMPLEMENTED.

THIS

$DS_SBTTL

ASSUMPTIONS:

WHAT

PARTS

OF THE

BEFORE THIS

TEST

BEFORE

THE

HARDWARE
IS

TEST
MUST

EXECUTED.

IS
BE

RUN,

SUCH AS

FUCTIONING

PROPERLY

***

ASSUMPTIONS MADE

***

STEPS:

**%

SECOND

TEST

DETAILED DISCRIPTION OF THE

THIRD

FIRST

STEP,

TEST AND TEST

FLOW ***

INITIALIZATION

STEP

NG
WE
NG

DETAILED DISCRIPTION OF THE

ERROR 02:
ERROR 03:

ERRORS DETECTABLE AND REPORTED

***

ERROR 01:

ERRORS:

THIS

SECTION WILL CONTAIN

DEBUG:

TEST

THE UNIT

INSTRUCTIONS ON
UNDER

HOW TO USE

THIS

TEST.

DEBUGGING

BLOCK COMMENTS
IS

<**%

SECTION NAMES

***>, ALIGN=BYTE

$DS_BGNTST

DOING

EXPLAIN WHAT A SPECIFIC

BLOCK OF CODE

CHANGE

PAGE

THIS TO

FOR

DEBUG

SUBTEST DESCRIPTION:

Template for VDS Diagnostic Program Test Modules

SUBTEST

STEPS:

*** BRIEF DESCRIPTION OF WHAT THE SUBTEST CHECKS ***

DETAILED FLOW OF TEST SEQUENCE **¥*

ERRORS:

**x*

BRIEF DESCRIPTION OF EACH OF THE ERRORS
THAT CAN BE DETECTED BY THIS TEST ***

**%*

DEBUG:

—-

WME

*%%* HELPFUL HINTS FOR TRACKING HARDWARE FAULTS ***

BLOCK COMMENT

-e

$DS_BGNSUB

$DS_ENDSUB
$DS_ENDTEST
$DS_ENDMOD
.END

Template for VDS Diagnostic Program Test Modules

B.2

Test 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 replaced by the programmer are enclosed
within matching sets of triple asterisks.

Areas that may be optionally modified are enclosed within matching sets

of double asterisks.

B-6

Template for VDS Diagnostic Program Test Modules

BTITLE "*** title ***’

*** module_name ***

MODULE

IDENT =
)

(

'01-00’

BEGIN
! ++

(c)

1983 BY

DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS.

!
H

{
{
{
{
{

THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER
COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY
OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY

TRANSFERRED.

!
!

THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT

CORPORATION.

{ DIGITAIL ASSUMES NO RESPONSIBILITY FOR THE USE OR

RELIABILITY

! SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL.

ITS

H
1-

FACILITY:

VAX-11 DIAGNOSTIC

ABSTRACT:

*%x*

ENVIRONMENT:

VAX-11 DIAGNOSTIC SUPERVISOR

gbhstract ***

AUTHOR: *** your name ***,6 DATE: *** date ***,6 VERSION: v01.0
MODIFIED BY:

GEm

1++

INCLUDE FILES:

[

**% List all programmer-defined libraries and "require” files here. ***

LIBRARY

’SYSSLIBRARY:DIAG';

L4+

SUPERVISOR MACROS

[ .

$DS_BGNMOD (ENV = *¥x* environment **x*,
TEST = *** gtarting test number ***);
$DS_DSADEF
$DS_DSSDEF

$DS_SECDEF (*** section names ***);
144

EXTERNAL DECLARATIONS

EXTERNAL ROUTINE

*%%* routine name ***

;

EXTERNAL
*ek

names

*rk

B-7

Template for VDS Diagnostic Program Test Modules

%BSBTTL

***

gubtitle

*%*’

DESCRIPTION:

TEST

***

This will

t++

and

how the

contain
is

brief

description of what

implemented.

being

tested

***

ASSUMPTIONS:

swm

test

***

Assumptions made before

which portions
properly

test

run,

this

test

executed.,

such

***

STEPS:

TEST

***

Detailed

before

the

the hardware must be functioning

***

description

First

the

test

and

test

flow **x

tEm

***

Initialization **»
Second step ***

step,

***

Third step

***

Error

0l:

***

ERRORS:

Error

02:

***

Error

03:

Detailed

description

the
#***

***

description

**»

***

description

***

errors

detectable

and reported

DEBUG:

description

This

section will

contain

test

in debugging

the unit

instructions
under

test.

on
***

***

$DS_BGNTEST
TEST

(SECTION = ***
’'***

test

name

section names

***,

*%*’);

***

Block

BEGIN

comment

code

doing

explain what

**=*

specific

block

how to

use

this

**x

Template for VDS Diagnostic Program Test Modules

%SBTTL

'***

gubtitle ***’

144

SUBTEST

DESCRIPTION:

]

***

!
!

Brief

description

of what

the

subtest

checks

**x*

.
SUBTEST

STEPS:

***

Detailed

flow of

test

sequence

***

]

ERRORS:

]

***

Brief

***

Helpful

hints

Block

comment

description

each

the possible

errors

detected

***

]

DEBUG:

for

tracking

hardware

faults

***

]

!
f e

$DS_BGNSUB
44

***

code

doing

explain what

specific

block

***

[

BEGIN

***

subtest

code

***

END;

$DS_ENDSUB

END;

$DS_ENDTEST

$DS_ENDMOD
END

ELUDOM

B-9

Template for Diagnostic Program Documentation
File
This is a template for VAX Diagnostic documentation files. Everything to
be changed, added, or deleted is enclosed within matching double angle
brackets, <<’ and “>>"".

Template for Diagnostic Program Documentation File

IDENTIFICATION

Product code:

ZZ-< < maindec code, including version > >

Product name:

< < program name > >

Product date:

< < submission date > >

Maintainer:

< < diagnostic engineering group > >

The information in this document is subject to change without notice
and should not be construed as a commitment by Digital Equipment

Corporation. Digital Equipment Corporation assumes no responsibility for

any errors that may appear in this document.

The software described in this document is furnished under a license and
may be used or copied only in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on
equipment that is not supplied by Digital or its affiliated companies.

DECsystem-10

DECSYSTEM-20

DECUS

MASSBUS

PDP

UNIBUS

VAX

VMS

< < any additional trademarks > >
< < Digital logo > >

Table of
1.0

Abstract

2.0

Contents

Hardware Requirements

¢«

¢t

3.0

Software

Prerequisites

5.0

Operating

7.0

4.0

6.0

C-2

Requirements

Instructions

5.1

Options

5.2

Event

Flags

Program Functional

Description

6.1

Program OVerview

6.2

Program Siz€

6.3

Program Run Times

.«

6.4

Run-time Dynamics

6.5

Fault Detection

6.6

Performance During

.«

Hardware Failures

Program Applications

Test

.« «

¢«

6.8

6.7

Maintenance History

Descriptions

...

.«

¢«

o«

Template for Diagnostic Program Documentation File

Abstract
< < program abstract; from 3 to 20 lines > >

C.2

Hardware Requirements
< < minimum hardware configuration; optional hardware > >

Cc3

Software Requirements
< < software environment, e.g. VAX Diagnostic Supervisor > >

C.4

Prerequisites
< < hardware that should be verified before running this program > >

C.5

Operating Instructions
< < Refer to the VAX Diagnostic Supervisor User’s Guide (AA-FK66A-TE) for
instructions on how to load and start the Diagnostic Supervisor and also
how to load and execute the programs. The operator must ATTACH and
SELECT the device << e.g., KA880 > > before starting this program. > >

C.5.1

Options
< < any operator options, such as MANUAL section > >

C.5.2

Event Flags
< < The following event flags are used by this program.> >
*

<<eventflag1>>

<<eventflag2>>

<< etc.

C.6

Program Functional Description

C.6.1

Program Overview
< < purpose, strategy, transportability > >

C-3

Template for Diagnostic Program Documentation File

C.6.2

Program Size
< < names and sizes of all associated files > >

C.6.3

Program Run Times
< < quick verify, default, with options > >

C.6.4

Run-Time Dynamics
< < memory allocations, side effects, sequence of testing on multiple

units > >

C.6.5

Fault Detection
< < error resolution, error message formats, fault coverage (%) > >

C.6.6

Performance During Hardware Failures
< < unsuspected traps, power failure > >

C.6.7

Program Applications
<< field service (RD), manufacturing (APT), customers, engineering > >

C.6.8

Test Descriptions
<< for each test/subtest, “Test description”, ““Test steps’’, and “Debug

aids” > >

C.7

Maintenance History
< < date, version: description of changes > >

C-4

Sample Help File

Below is the help file for the diagnostic program EVKAS. All help files
should follow the following format:
1 TESTS

TEST INST

1 MOVF

2 MNEGF

3 TSTF

4 CVTBF

5 CVTWF

6 CVTLF

7 CVTFB

8 CVTFW

9 CVTFL

10 CVTRFL

11 CMPF

12 ADDF2

13 ADDF3

14 SUBF2

15 SUBF3

16 MULF2

17 MULF3

18 DIVF2

19 DIVF3

20 EMODF

21 POLYF

22 ACBF

23 MNEGD

24 MOVD

25 TSTD

26 CVTBD

27 CVTWD

28 CVTLD

29 CVTDB

30 CVTDW

31 CVTDL

32 CVTFD

33 CVTDF

34 CVTRDL

35 CMPD

36 ADDD2

37 ADDD3

38 SUBD2

39 SUBD3

40 MULD2

41 MULD3

42 DIVD2

43 DIVD3

44 EMODD

45 POLYD

46 ACBD

1 ATTACH

The CPU must be attached. For more help, type HELP EVKAS ATTACH
(processor mnemonic).

When running in Stand-Alone mode, only the primary CPU should be
selected. The SELECT ALL command should not be used after running the
Autosizer.

2 KA62A
DS> ATTACH KA62A HUB KAn (1) (2)
(1) XMI node Id ?(node-id)

(2) FPU Present ?(YES or NO)

2 KA884
DS> ATT KA884 HUB KAn (1) (2)
(1) Primary (YES or NO)
(2) cpUu Id (0,1,2 or 3)

Sample Help File

1 HELP
This program exercises the floating point instructions that can

be executed
in any mode, i.e., non-priviledged instructions. The program is capable
of running under the Diagnostic Supervisor in either the standalone
environment or as a user task under VMS. It is also designed to
run on any

member of the VAX family of computers. Currently supporte
d processors
include the 8840 and 6200.

1 SECTION

Sections have been allocated to test certain groups of instructions.

more information, type HELP EVKAS SECTION (section name).

For

2 F_FLOATING
Single Precision Floating Point Instructions:

MOVF, MNEGF, TSTF, CVTBF, CVTWF, CVTLF, CVTEFB, CVTFW,
CVTFL, CVTRFL, CMPF, ADDFn, SUBFn, MULFn, DIVEn, EMODF,
POLYF, ACBF.

2 DOUBLE
Double Precision Floating Point Instructions:
MNEGD, MOVD, TSTx, CVIBD, CVTWD, CVTLD, CVTDB,
CVTDW,
CVTDL, CVTFD, CVTDF, CVTRDL, CMPx, ADDDn, SUBDn,
MULDn,
DIVDn, EMODx, POLYD, ACBD.
2 MOVXMNEGX

All MOVx and MNEGx Single, Double Floating Point Instructi

ons

MOVF, MNEGF, MNEGD, MOVD.

2 CVTXX
All CVTxy and CVTxyz Single, Double, Floating Point Instructi

ons

CVTBF, CVTWF, CVTLF, CVTFB, CVTFW, CVTFL, CVTRFL,
CVTBD,
CVTWD, CVTLD, CVTDB, CVIDW, CVTDL, CVTFD, CVTDF,
CVTRDL.
2 ADDSUBMULDIV
All ADDxn, SUBxn, MULxn and DIVxn Single, Double

Instructions:

Floating Point

ADDFn, SUBFn, MULF, DIVFn, ADDDn, SUBDn, MULDn,
2 EMODX

All EMODx Single, Double Floating Point Instructions:
EMODF, EMODD

2 POLYX
All POLYx Single, Double Floating Point Instructions:
POLYF, POLYD

2 ACBX

All ACBDx Single, Double Floating Point Instructions:

ACBF, ACBD

DIVDn

Sample Help File

1 EVENT

Event flags 2 through 6 are active with this program.
2 FLAG2

Disables the interval timer interrupting during instruction execution.
2 FLAG3

Enables the interval timer interrupting while page faulting is also enabled.
2 FLAG4

Enables the continuation of a subtest after an error (normally, the subtest is
aborted).

2 FLAGS

Disables the DIVP instruction execution during interval timer interrupting.
2 FLAG6

Enables the user to create a custom section of tests by asking what tests
are to be executed. If this flag is set, the diagnostic prompts the user for
the test numbers that the user wants executed. When you have finished
entering, hit Carriage Return to the response for a test number and the
diagnostic will begin. You may input any number of test numbers.
in the
IMPORTANT: If you select a particular section and that test number is NOT
section, THE TEST WILL NOT EXECUTE; i.e., SECTION takes priority
over FLAG6 selections. To obtain a list of the instructions and which test
executes that instruction, type HELP EVKAS TESTS.
sxxxx+ THIS FLAG DOES NOT WORK IF THE OPERATOR FLAG BIT IS
CLEAR & % ¥ % K &

1 QUICK

The QUICK flag disables the execution of the instructions with page
faulting so that each instruction test case is only executed once for each
addressing mode combination.
1 SUMMARY

The summary report gives an error count by test number. No report is

generated if there were no errors.

D-3

Index

A
ABORT command ¢ 3-23

$BINTIM » 4-15, 5-54

Action routines » 5-240, 5-241

Block processing ¢ 4-25

Adapters

Breakpoint facility ¢ 4-17

bus ¢ 3-20, 4-5

Buffers ¢ 3-4, 4-11

displaying internal registers of ¢ 4-5
interrupts from ¢ 3-23

mapping registers ¢ 4-5
MASSBUS ¢ 4-5

status of¢ 4-5

UNIBUS ¢ 3-10, 4-5
VAXBIl ¢ 4-5
Adapter status ¢ 5-78

BIIC BER field « 5-81
BIC CSR field « 5-81

status-1 field ¢ 5-79
vector field ¢ 5-81

$ALLOCATE ¢ 3-20, 4-2
Allocate devices ® 4-1,4-2

Allocating devices » 3-20
APT
e 2-1,6-16
APT/RD e 6-17

$ASCEFC » 4-13
$ASCTIM e 4-15, 5-10
$ASSIGN ¢ 3-20, 4-1, 5-29
AST delivery ¢ 4-13

AST routines » 4-4, 4-13, 4-14, 4-15
ASTse 4-13
Asynchronous system traps

See ASTs

ATTACH command » 3-5, 3-6, 3-11, 3-12, 3-14,
3-15, 3-21, 4-8, 4-21
Attached process e 4-27

Calling system service macros e 5-1

$CANCEL » 5-68
$CANTIM ¢ 4-15, 5-70
Channels ¢ 3-23, 4-1, 4-2, 4-5
assigne 4-1

deassigning ® 4-1
Character string descriptors e 5-5

Clean-up code ¢ 3-1, 3-3, 3-21, 3-23, 3-29, 3-30,
4-1, 4-17

$CLOSE » 4-24, 4-25, 5-96
$CLREF o 4-13, 4-32, 5-98
Cluster exerciser ¢ 2-8
Command language
creatingae 4-9

Condition handling e 3-23, 4-6, 4-12, 4-16, 4-17,
4-18, 4-19

$CONNECT » 4-24, 4-25, 5-103
CONTINUE command = 4-31
Control-c e 3-31

Control-c handler ¢ 4-9, 4-19, 4-20
Control flags

See VDS control flags
Customer service representatives » 1-6

definition ¢ 4-26

Attached processor
definition ¢ 4-26

Automated Product Test ¢ 2-1
Automated Product Test (APT) ¢ 3-4, 3-15
Auto-QA
See quality assurance

automated
Autosizer e 3-15, 3—-18, 4-21

D
$DASSGN ¢ 4-1

$DASSIGN ¢ 5-110
Debugging a diagnostic program ¢ 6-23

$DEF» 3-11, 5-113
$DEFEND ¢ 3-11, 5-115, 5-116
$DEFINl» 3-11, 5-115, 5-116
Degree of resolutione 1-5, 1-6

index~1

Index

DESELECT command e 4-2

$DS_BGNATTACHED ¢ 4-26, 5-36, 5-124

Design specifications ¢ 6-3

$DS_BGNCLEAN ¢ 3-23, 5-38, 5-126, 6--5, A-6,

Device mnemonics liste 3-19

A-14

Diagnostic buffer

$DS_BGNDATA ¢ 3-24, 5-40, 5-128

Diagnostic program header ¢ 3-18

$DS_BGNINIT ¢ 3-20, 5-42, 5-130, 6-5, A-5, A-13
$DS_BGNMESSAGE ¢ 5-44, 5-132, 6-5, 6-17

Diagnostic programs

$DS_BGNMOD ¢ 3-1, 5-46, 5-134, A-2, A-11,

See $QIO diagnostic buffer

B-3, B-7

overview ¢ 1-1

$DS_BGNREG ¢ 5-47, 5-136, A-12
$DS_BGNSERV » 4-6, 5-48, 5-137

user goals

customere 1-2

$DS_BGNSTAT « 3-24, 5-49, 5-138, 6-4, A-3,

user requirements
customerse

A-12

1-2

customer service representatives e 1-2, 1-3

depending on producte

1-3

design engineers ¢ 1-3

manufacturinge 1-3

users ofe 1-2

detecting failing hardware ¢ 1-1

during design of new products » 1-1
in manufacturing e 1-1

$DISCONNECT » 4-24, 4-25, 5-118
Dispatch e 3-19
Documentation e 6-7 to 6-16

to 6-13

Documentation files ¢ 6-7, 6-8

DS$_NORMAL ¢ 5-4

$DS_$ADD » 3-13, 5-8
$DS_$CASE » 3-13, 5-72
$DS_$COMPLEMENT ¢ 3-13, 5-102
$DS_$DECIMAL ¢ 3-13, 5-111
$DS_$END » 3-13, 5-123
$DS_$FETCH e 3-13, 5-188
$DS_$HEX » 3-13, 5-209
$DS_SINITIALIZE » 3-12, 5-216
$DS_$LITERAL » 3-13, 5-223
$DS_SLOGICAL » 3-12, 5-224
$DS_$NAME ¢ 3-12, 5-230
$DS_$OCTAL ¢ 3-13, 5-233

$DS_$STORE » 3-13, 5-314
$DS_$STRING » 3-13, 5-318
$DS_ABORT ¢ 3-23, 3-26, 3-30, 3-32, 4-11, 5-7
$DS_ASKADR ¢ 4-8, 5-12
$DS_ASKDATA ¢ 4-8, 5-16

$DS_ASKLGCL » 4-8, 5-19
$DS_ASKSTR ¢ 4-8, 5-22

$DS_ASKVLD ¢ 4-8, 5-25
$DS_ASKxxxx e 3-12, 3-23, 3-26, 4-8, 4-28
$DS_ATTACH ¢ 5-32
$DS_BCOMPLETE » 3-34, 5-34
$DS_BERROR ¢ 3-34, 5-35

Index-2

B-5

$DS_BGNSUMMARY ¢ 3-24, 5-51, 5-140, 6-5,
A~-7, A-15

$DS_BGNTEST » 3-1, 3-24, 3-26, 4-33, 5-52,
5-141, B-8

uses of

in source code * 6-9

$DS_BGNSUB » 3-25, 3-31, 4-33, 5-50, 5-139,

$DS_BGNTST e+ B-4
$DS_BITDEF » 5-56
$DS_BNCOMPLETE ¢ 3-34, 5-57
$DS_BNERROR ¢ 3-34, 5-58

$DS_BNOPER » 3-26, 3-34, 5-59, 6-19
$DS_BNPASS0 ¢ 3-21, 3-35

$DS_BNPASSO ¢ 5-60

$DS_BNQUICK » 3-34
$DS_BOOTATTACHED » 4-26, 4-27, 5-62
$DS_BOPER ¢ 3-26, 3-34, 5-64, 6-19

$DS_BPASSO ¢ 3-21, 3-35
$DS_BPASSO ¢ 5-65

$DS_BQUICK ¢ 3-34, 5-61, 5-66
$DS_BREAK ¢ 4-31, 4-32, 5-67
$DS_CANWAIT ¢ 4-15, 5-71
$DS_CFDEF « 5-74

$DS_CHANNEL ¢ 3-20, 4-5, 4-28, 4-30, 5-75
$DS_CHCDEF » 5-85

$DS_CHDEF « B-3
$DS_CHMDEF » 5-86
$DS_CHSDEF » 5-87
$DS_CKLOOP ¢ 3-2, 3-31, 3-33, 5-88
$DS_CLie 4-10, 5-90
$DS_CLIDEF « 5-95
$DS_CLRVEC ¢ 4-6, 4-28, 4-30, 5-99
$DS_CNTRLC ¢ 4-13, 4-19, 4-31, 5-100
$DS_CVTREG * 4-8, 5-105, 6-5, A-4, A-13

$DS_DEFDEL » 5-114
$DS_DEVTYP e 3-19, 5-117, 6-4, A-4, A-11

$DS_DISPATCH « 3-19, 5-120, 6-4, A-3, A-11
$DS_DSADEF ¢ A-11, B-7
$DS_DSDEF ¢ 5-121
$DS_DSSDEF ¢ 5-1, 5-122, A-2, A-11, B-3, B-7

$DS_ENDATTACHED » 4-26, 5-36, 5-124

Index

$DS_ENDCLEAN e 3-23, 5-38, 5-126, 6-5, A-6,
A-14

$DS_ENDDATA ¢ 3-24, 5-40, 5-128
$DS_ENDINIT » 3-20, 5-42, 5-130, 6-5, A-5, A-13
$DS_ENDMESSAGE » 5-44, 5-132, 6-5, 6-17
$DS_ENDMOD ¢ 3-1, 5-46, 5-134, A-8, A-16,
B-5, B-9

$DS_ENDPASS ¢ 5-135
$DS_ENDREG ¢ 5-47, 5-136, A-12
$DS_ENDSERV ¢ 4-6, 5-48, 5-137
$DS_ENDSTAT » 3-24, 5-49, 5-138, 6-4, A-3,
A-12

$DS_ENDSUB ¢ 3-25, 3-31, 4-33, 5-50, 5-139,
B-5, B-9

$DS_ENDSUMMARY ¢ 3-24, 5-51, 5-140, 6-5,
A-7, A-15

$DS_ENDTEST » 3-1, 3-24, 3-31, 4-33, 5-52,
5-141, B-5, B-9

$DS_ERRDEF ¢ 5-143
$DS_ERRDEV¢ 3-29, 5-144

$DS_ERRHARD ¢ 3-29, 5-149
$DS_ERRNUM ¢ 5-154
$DS_ERRPREP ¢ 3-29, 5-155
$DS_ERRSOFT ¢ 3-29, 5-160
$DS_ERRSYS ¢ 3-30, 5-165
$DS_ERRxxxx e 3-27, 3-30, 3-35, 4-7, 4-28,
6-17

$DS_ESCAPE ¢ 3-35, 5-170
$DS_EXIT » 3-29, 3-35, 4-27, 5-172

$DS_GETBUF ¢ 4-10, 4-11, 4-27, 4-29, 5-192
$DS_GETTERM e 4-8, 5-199

$DS_GPHARD » 3-15, 3-20, 5-202
$DS_HALTATTACHED » 4-26, 4-31, 5-204
$DS_HDRDEF ¢ 3-2
$DS_HEADER ¢ 3-18, 5-206, 6-4, A-3, A-12

$DS_HELP ¢ 5-208
$DS_HIBER ¢ 4-29

$DS_HPEODEF ¢ 3-8, 5-213
$DS_HPEO_DECL ¢ 5-212
$DS_HPODEF ¢ 3-8, 5-215
$DS_HPO_DECL ¢ 3-17, 5-214

$DS_INITSCB ¢ 4-7, 4-28, 4-30, 5-218
$DS_INLOOP ¢ 3-32, 5-219
$DS_LOAD ¢ 4-20, 4-27, 4-28, 5-220
$DS_MEMSIZE ¢ 5-225
$DS_MMOFF ¢ 4-11, 4-28, 4-29, 5-226
$DS_MMON ¢ 4-11, 4-28, 4-29, 5-228
$DS_PAGE ¢ 5-237

$DS_PRINTREV¢ 5-253
$DS_PRINTS ¢ 3-24, 4-7, 5-259

$DS_PRINTSIG » 4-19, 5-262
$DS_PRINTx» 4-28

$DS_PRINTX ¢ 3-27, 4-7, 5-263
» 4-7, 5-266
$DS_PROBE
$DS_PSLDEF « 5-268
$DS_PTDDEF » 5-269
$DS_RELBUF ¢ 4-11, 4-29, 5-286
$DS_SBTTL» 5-288, B—4

» 5-289
$DS_SCBDEF

$DS_SECDEF » 3-26, 5-290, B-3, B-7
$DS_SECTION » 3-19, 3-26, 5-291, 6-4, A-4,
A-11

$DS_SETIMR

4-29

$DS_SETIPL¢ 4-7, 5-298
$DS_SETMAP ¢ 3-20, 4-5, 4-28, 5-299
$DS_SETVEC » 4-6, 4-28, 4-30, 4-34, 5-306

$DS_SHOCHAN» 4-5, 5-309
$DS_SHOWIDLE » 4-27, 5-310

$DS_STARTATTACHED ¢ 4-26, 4-27, 5-312
$DS_STRING¢ 5-316
$DS_SUMMARY
« 5-320
$DS_WAITMS » 4-15, 4-29, 4-31, 5-326
$DS_WAITUS ¢ 4-16, 4-29, 5-328
$DS_WAKE ¢ 4-29

E
Error logging ¢ 4-2

Error reporting

error messages ® 3-26
message formats ¢ 3-26, 3-27, 6-17, 6-18

VDS control flags and o 3-28
Error reporting routines ¢ 5-44, 5-132, 5-143,

5-145, 5-146, 5-150, 5-151, 5-156, 5-157,
5-161, 5-162, 5-166, 5-167
Error Reporting Routines ¢ 3-3, 3-27
Errors

device-fatal ¢ 3-29
hard ¢ 3-29

preparation ¢ 3-28

softe 3-29

system-fatal ¢ 3-30
Event flags ¢ 4-3, 4-13
Exceptions e 3-23, 4-12, 4-16, 4-18

$DS_PARDEF ¢ 5-238

BPT e 4-17

$DS_PARSE ¢ 4-10, 4-28, 5-239
$DS_PRINTB ¢ 3-27, 4-7, 5-243
$DS_PRINTF ¢ 4-7, 5-250

T-bite 4-17
Exception vectors ® 4-6
EXIT command e 4-2

Index-3

Index

Extended attribute block

see XAB
F.

H
Halt-on-error e 3-28

Hardcore e

1-1, 1-5, 2-4, 2-5

$FAB ¢ 4-22, 5-174

Hardware environments ¢ 2-4, 2-5

$FAB_INIT » 5-180, 5-181
$FAB_STORE ¢ 4-23, 5-180, 5-181

Hardware Parameter Tables

$FAQ ¢ 4-7,5-182, 5-185

Hardware preparation ¢ 6-20

FAQ directives ¢ 5-182, 5-185, 5-243, 5-244,

Help files ¢ 4-10, 6-13

See P-tables

5-245, 5-247, 5-248, 5-250, 5-259, 5-260,

creatinge 6-13

5-263, 5-264

description of¢ 6-13

to 6-16

$FAOL» 5-182, 5-185

keywords ine 6-13 to 6-16

Fault detection ¢ 6-3

text ine 6-15, 6-16

Fault isolatione 1-6, 6-3
Field-replaceable unit

$HIBER ¢ 4-15, 5-211
HUB e 3-5, 3-10

See FRU ¢ 1-1
File access block

See $FAB
Flags

See Event Flags
See VDS control flags
Formatted ASCIl Output

See FAO
Functional specifications ¢ 6-2, 6-3, 6-24

/O e 3-3

/O function encoding ¢ 4-2

/O methods
in level 1 programs ¢ 2-6

in level 2 programs ¢ 2-7

in level 2R programs e 2-6, 2-7
in level 3 programs ¢ 2-7

in level 4 programs ¢ 2-7
in level 5§ programs ¢ 2-7

$GET ¢ 4-24, 5-190

$GETCHN ¢ 4-1,5-195
$GETTIM ¢ 4-15, 5-201
ggan format e 5-230

Goals
testing e 1-5

users e 1-2

Guidelines for writing diagnostic programs
level 1 guidelines » 2-10
level 2 guidelines o 2-11

level 2R guidelines ¢ 2-10

level 3 guidelines ¢ 2-11, 2-12
level 4 guidelings ¢ 2-12

level 5 guidelines » 2—-13

Index-4

logical WO o 2-6, 2-7

physical /O e 2-6, 2-7
virtual /O ¢ 2-6, 2-7
I/0O status block ¢ 4-3

Idle State ¢ 4-27
Implicit inputs ¢ 6-10
Implicit outputs » 6-10

Initialization code ¢ 3-1, 3-2, 3-15, 3-20, 3-21,

3-29, 3-35, 4-1, 4-9
Interrupts e 4-5, 4-15, 4-16, 5-82
Interrupt service routines ¢ 3-3, 3-35, 4-6, 4-15,
4-16

IPLe 4-7

Index

Multiprocessing (cont’d.)

dispatch vectors ¢ 4-32

event flags ¢ 4-32

Level 1 programs e 2-5, 2-6, 2-10

interprocessor interrupts ¢ 4-31

Level 2 programs e 2-7, 211

macros ¢ 4-26

Level 2R programs ¢ 2-6, 2-7, 2-9, 2-10, 3-20,

mailbox ¢ 4-32

exceptions » 4-30
input/output ¢ 4-30

4-1, 4-10, 4-12, 4-13, 4-14, 4-20, 4-21

Level 3 programs » 2-7, 2-8, 2-9, 2-10, 2-11,
2-12, 4-5, 4-13, 4-14, 4-20, 4-21

main/attached process communication ¢ 4-32
memory mapping ® 4-29
restrictions ¢ 4-32

Level 4 programs ¢ 2-7, 2-8, 2-12

SCBe 4-30

Level § programs e 2-5, 2-7, 2-8, 2-9, 2-13

system services

Linking a diagnostic program e 3-4, 6-23
Logical unit number » 3-21

Looping ¢ 3-2, 3-28, 3-30, 3-31
and the $DS_BREAK macro ¢ 4-20
characteristics of o 3-32

interlocking o 4-28
timing e 4-29

unexpected interrupts ¢ 4-30
VDS e 4-25

Multiprocessing Routings » 3-3

loop boundaries » 3-30, 3-31

defaults fore 3-31
nesting loops ¢ 3-33

user-specified » 3-34

Loops e

1-6

N
NEXT command

4-31
——

Macro-instructions ¢ 1-8
Macro-programs e

1-8, 1-9

$OPEN e 4-24, 4-25, 5-235

Macros

arguments ¢ 5-3
multiprocessing ® 4-26
name fields e 5-1
program control ¢ 3-2
program structure ¢ 3-1
return status codes » 5-4

symbol definition ¢ 3-2
Manual intervention ¢ 3-26, 6-20, 6-21
Mechanism array e 4-17, 4-18
Memory allocation e 4-11
Memory layout e 3-4
Memory management e 4-10, 4-11
Memory protection e 4-11
Micro-instructions ¢
Micro-programs e

1-8

1-9

Modifying SCB » 4-30
Mulitiprocessing

AST ¢ 4-31

breakpoints ¢ 4-31

control-C e 4-31
diagnostic program size ® 4-33

P
Passes » 3-19, 3-21, 3-23, 3-29, 3-34, 3-35,

5-60, 5-65
PASSES » 3-34
Prerelease of diagnostic programs ¢ 6-4
Primary process

definition » 4-26
Primary processor

definition » 4-26
Program development phases

consultation phase » 6-1
design implementation phase e 6-3
design phase ¢ 6-2

design verification phase » 6-4
functional specification phase ¢ 6-2
planning phase ¢ 6-2

Program loops ¢ 3-30
Program sections table ¢ 3-19

Index-5

Index

Program sections table (cont’'d.)

$DS_SECTION ¢ 3-19
Project plans ¢ 6-1, 6-2, 6-3
P-tables e 3-5

and the $ALLOCATE service e 4-2
construction of by VDS e 3-5

contents of¢ 3-6, 4-8

control-Cs and » 4-19

device’s link e 3-5
device-dependent fieids ¢ 3-7, 3—10, 3-11

creating names fore 3-14
device-dependent fields of

creating names fore 6-21
device-independent fields ¢ 3-7, 3-8, 3-11
format of¢ 3-7

getting a unit’s p-table ¢ 3-20

ggan format e 5-230

$RAB_INIT ¢ 5-280
$RAB_STORE ¢ 4-23, 5-281
Random-by-RFA ¢ 4-23, 4-25

$READ ¢ 4-25, 5-282
$READEF ¢ 4-13, 4-32, 5-284
Record access block

See $RAB
Record management services

See RMS
Record processing ® 4-23, 4-24, 4-25
Return status codes

ROe 5-4
R1e 5-4

RFA e 4-24

RMS e 4-20, 4-22, 4-23, 4-25, 4-27
RUN command

HUB linke 3-5
logical unit number and » 3-21

p-table descriptors ¢ 3-10, 3-11, 3-14

and device allocation ¢ 3-20
and device mnemonics liste 3-19

referencing from a diagnostic program e 3-15
UNIBUS adapters and ¢ 3-10
5-307

1-3

considerations when programming e 6-16

networks e

1-4

standalone mode *
user modee

creating e 3-11
location of ¢ 3-15, 6-13, 6-16

vector specification e

3-1, 3-19, 3-34, 4-9

Run-time environments »

1-4

1-3, 1-4

e
]

S
SCB e 3-10, 4-19, 5-306
Scope loops ¢ 3-30

Script

down-line loading ® 2-2

Sections e 3-26

$QI0 ¢ 4-1, 4-3, 4-14, 5-270, 5-273
$QIO Diagnostic Buffer ¢ 4-4

$QIOW ¢ 4-13, 5-270, 5-273
Quadword descriptors ¢ 5-5
Quality assurance » 6-4
automated ¢ 6-28, 6-29, 6-30

quality requirements

documentation quality ¢ 6-24

functional quality « 6-24
operational quality» 6-25, 6-27, 6-28

Quick e 3-34
Quick mode » 6-21

DEFAULT e 3-26, 6-21, 6-27

MANUAL ¢ 6-20, 6-21

SELECT command e 3-19, 3-21, 4-2

SEQe 4-24
Sequential record access ¢ 4-23

$SETAST ¢ 4-13, 5-292
$SETEF ¢ 4-13, 4-32, 5-293
$SETIMR ¢ 4-13, 4-14, 4-15, 4-29, 4-31, 5-294
$SETPRT ¢ 4-11, 5-303
Signal array » 4-18, 4-19
Single-step facility e 4-17

Size of a diagnostic program ¢ 3-4
Source modules
header module « 6-4, 6-5

R
RO register ¢ 5-3
R1 registere 5-3

$RAB ¢ 4-22, 5-276

Index-6

test modules ¢ 6-4, 6-5

SS$_NORMAL ¢ 5-4
Standalone mode ¢ 2-1, 3-4, 3-20, 4-5, 4-6,
4-10, 4-11, 4-13, 4-14, 4-15, 4-16, 4-17,
4-19, 4-20, 6-16

START command ¢ 3-1, 3-19, 3-34, 4-9

Index

Subpasses ¢ 3-19, 3-20
SUBTEST » 3-34
Subtests * 3-25

characteristics of ¢ 3-25

Tests, types of
exercisers ¢ 1-7
function tests e
logic tests »

1-7

global ¢ 3-25

Timing ¢ 4-14

legal and illegal uses of ¢ 3-25

Timing facilities ® 4-15

looping ine 3-31

multiprocessing ¢ 4-29

numbering of¢ 3-25
user-specified looping on ¢ 3-34
SUMMARY command ¢ 3-23

Summary routine ¢ 3-1, 3-21, 3-23, 3-24, 3-35,
4-7

Symbols
dollars signs in e 6-21

naming ¢ 6-21, 6-22, 6-23
private ¢ 6-21

public ¢ 6-21

System Control Block

See SCB
System under test

See SUT ¢ 1-1

U
Unit under test

See UUT

Unit Under Test (UUT).
See UUT e 3-5

SUNWIND e 5-321

User mode ¢ 2-1, 3-4, 3-9, 3-20, 3-23, 3-30, 4-1,
4-10, 4-11, 4-12, 4-14, 4-15, 4-17, 4-20,
6-16

UUT « 1-1, 3-3, 3-24, 3-28, 3-29, 3-32, 4-1

Tables e 3-2
TEST e 3-34

Testing

bottom-up e 1-8

CPU cluster e 2-8, 2-9

parallel ¢ 1-7, 3-3, 3-20, 3-22
peripheral devices ¢ 2-9, 2-10
serial » 1-7, 3-3, 3-20, 3-22, 3-29
top-down e 1-8

Testing goals e 1-5, 1-6
Testing scopee 1-5

Tests e 3-1, 3-2, 3-24

and sections ¢ 3-26
and subtests e 3-25

characteristics of ¢ 3-24
Dispatch Table and ¢ 3-19
global routines in ¢ 3-24

input arguments ¢ 3-24

manual intervention in ¢ 3-26
passes and ¢ 3-19

subpasses and e 3-19

Value register ¢ 3-12, 5-8, 5-72, 5-111, 5-188,
5-209, 5-223, 5-233, 5-314
VAX Diagnostic Debugger ® 6-23
VAX diagnostic strategy

program levels ¢ 2-4, 2-5, 2-6
VDS

human interface ¢ 2-2
program interface ¢ 2-2

purposes of ¢ 2-3
VDS control flags ¢ 4-7
HALT « 3-28

IE2 ¢ 5-243
IE3 e 5-243
IES » 3-23, 5-259

LOOP « 3-28, 3-30

OPERATOR ¢ 3-26, 3-34, 4-9, 6-18, 6-19,
6-21, 6-27

QUICK » 3-34, 6-21
Vectors ¢ 5-82, 5-307
VMS e 3-30

VMS privileges ¢ 4-4

types of

function tests e 2-11, 3-24
logic tests o 2—-11, 3-24

user-specified looping on ¢ 3-34

index-7

Index

w
$WAITFR » 4-3, 4-13, 4-32, 5-324
$WAKE ¢ 4-15, 5-330
$WFLAND ¢ 4-13, 4-32, 5-332

SWFLOR ¢ 4-13, 4-32, 5-334
Writable control store e

X
$XABFHC » 5-336

Index-8

1-9, 2-9

VAX
Guide
Design
Diagnostic
AA-FK67A-TE

READER’S COMMENTS

Your comments and suggestions help us to improve the quality of our publications.
For which tasks did you use this manual? (Circle your responses.)
(@) Installation

(b) Operation/use

(e) Training

(f) Other (Please specify.)

(d) Programming

Did the manual meet your needs? Yes[

No[

Why?

Please rate the manual in the following categories. (Circle your responses.)
Excellent

Good

Fair

Poor

Unacceptable

4
5
Illustrations, examples (useful)
4
5
Overall ease of use
4
5
Page Layout (easy to find information)
4
5
Print Quality (easy to read)
What things did you like most about this manual?

3
3
3
3

2
2
2
2

1
1
1
1

Accuracy (product works as described)
Clarity (easy to understand)
Completeness (enough information)
Organization (structure of subject
matter)

Table of Contents, Index (ability to

5
5
5
5

4
4
4
4

find topic)

3
3
3
3

2
2
2
2

What things did you like least about this manual?

Please list and describe any errors you found in the manual.

Page

Description/Location of Error

Additional comments or suggestions for improving this manual:

Name
Street

Job Title
Company

State/Country

Telephone Number

City

Postal (ZIP) Code

Department

Date

1
1
1
1

Affix

Stamp
Here

DIGITAL EQUIPMENT CORPORATION

CORPORATE USER PUBLICATIONS
200 FOREST STREET MRO1-3/L12
MARLBOROUGH, MA 01752-9101

VAX
Diagnostic Design Guide
AA-FK67A-TE

READER’S COMMENTS

Your comments and suggestions help us to improve the quality of our publications.
For which tasks did you use this manual? (Circle your responses.)
(a) Installation

(e) Training

(b) Operation/use

(d) Programming

(f) Other (Please specify.)

Did the manual meet your needs? Yes[

No[

Why?

Please rate the manual in the following categories. (Circle your responses.)
Excellent

Good

Fair

Poor

Unacceptable

Accuracy (product works as described)

Clarity (easy to understand)
Completeness (enough information)
Organization (structure of subject

5
5
5

4
4
4

3
3
3

2
2
2

1
1
1

Mustrations, examples (useful)
Overall ease of use

5
5

4
4

3
3

1
1

Page Layout (easy to find information)

5
5

4
4

3
3

2
2
2
2

matter)
Table of Contents, Index (ability to
find topic)

Print Quality (easy to read)

What things did you like most about this manual?

What things did you like least about this manual?

Please list and describe any errors you found in the manual.
Page

Description/Location of Error

Additional comments or suggestions for improving this manual:

Name

Job Title

Street
City
State/Country

Company
Department
Telephone Number

Postal (ZIP) Code

Date

1
1

Affix

Stamp
Here

DIGITAL EQUIPMENT CORPORATION

CORPORATE USER PUBLICATIONS
200 FOREST STREET MRO1-3/L12
MARLBOROUGH, MA 01752-9101