Digital PDFs

--

February 1977

324 pages

Original

10MB

view download

OCR Version

9.8MB

view download

Document:	Software Engineering Manual
Order Number:	--
Revision:	000
Pages:	324
Original Filename:

OCR Text

Page 1

pigital Eauipment Corporation COMPANY CONFIDENTIAL
Title:

VAX-11 Software Engineering Manual -- Rev 3

Specification Status:

draft

Architectural Status:

under ECO control

File:

SEPRR3.RNO

PDM #:

not used

Date:

19-Feb-77

Superseded

Specs:
L

none

F. Bernaby, P. Conklin, S. Gault, T. Hastings, P. Marks,
R. Murray, I. Nassi, M. Spier

Author (s):

Conklin

Typist:

Reviewer (s):

Abstract:

R. Brender, D. Cutler, R. Gourd, T. Hastings,
S.

Poulsen, D. Tolman

I. Nassi,

This manual presents the VAX-1l1l programming conventions and
and
for,
as developed
engineering practices
software
These
Group.
Engineering
Central
the
by
adopted
conventions and practices are standard within Central
corporate
we hope that they be used by other
Engineering;
helper®,
"programmer's
the
Designed to be
groups as well.
as
well
as
conventions
the manual contains the coding
and
e
administrativ
practical data of technical, procedural,
the ssoftware
to
useful
conceptual nature that would be
engineer.

Revision History:

Rev
Rev
Rev
Rev

#
1
2
3

Description
Original
Revised from Review
After 6 months experience

Author
M. Spier
P. Marks
P. Conklin

Revised Date
14-Apr-76
21-Jun-~-76
19~-Feb-77

CONTENTS
19-Feb~-77
Change History

Rev

[End

Rev

Page

990

Convert

Remove

Move

Remove

Note

Split chapter 6 into 6 and 7. Add chapters 8-11,
especially BLISS. Add the BLISS transportability guidelines.
Add Chapter 15 for diagnostics.

standard

unwritten

for

relationship

SEPRR3.RNO]

manual

chapter

format.

sections.

introductory
request

RUNOFF

note

review

BLISS

preface.
from

preface.

conventions.

VAX
SOFTWARE

ENGINEERING MANUAL

19 PEBRUARY
Revision

1977
3

I
l
I
|
|
|

NOT

DUPLICATE

For additional copies, contact:

Ike Nassi

ML 21-4/E20

Digital Equipment Corporation,

|
|
|
I
:
l

Maynard, Massachusetts

Revision 1,
Revision 2,
Revision 3,

April, 1976
June, 1976
February, 1977

The information in this document is subject to change
without notice and should not be construed as a
Digital
commitment by Digital Equipment Corporation.
for any
ibility
respons
no
assumes
tion
Equipment Corpora
errors that may appear in this document.

This draft standard does not describe any program or
product which 1is currently available from Digital
Nor does Digital Equipment
Eaquipment Corporation.

Corporation commit to implement this standard in any
Digital Equipment Corporation
program or product.
makes no commitment that this document accurately
describes any product it might ever make.

Digital Equipment Corporation's software is furnished
under a license and may only be used or copied in
accordance with the terms of such license.

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

The

following

Corporation:

are

trademarks

Digital

Equipment

RAD-8
RSTS

COMSYST

DIBOL
DIGITAL
DNC

KAl0
KI1O0

LAB-8

RSX

DDT
DEC

EDUSYSTEM
FLIP CHIP

MASSBUS
OMNIBUS

RTM
SABR

CDP
COMPUTER LAB

COMTEX

EDGRIN

DECCOMM
DECUS
DECsystem-10

FOCAL
GLC-8
IDAC

DECtape

INDAC

DECsystem-20

IDACS

LAB-K

0s/8
PDP
PHA
PS/8

QUICKPOINT

RT-11

TYPESET-8
TYPESET-10
TYPESET-11
UNIBUS

PREFACE

Over the years, much ado has been
made
about
coding
standards
3nad
conventions.
Everyone believed that conventions are good, so long as

they are not the other quy's conventions!
Committees were formed, and
reformed,
and
left
to
die
for
1lack
of consensus.
We repeatedly
refused
to
follow
conventions
that
we
deemed
"imperfect"”
and
conseaquently

great

deal of
multitude

vast

foolishness
mandated.

and

followed

this
of

none

all.

has

been foolish nit-picking on the part
of
entrepreneurs.
The
time
has
come to stop
recoanize the reasons for which code uniformity

our
the

Standards, conventions and uniform practices all aid us
in
producing
reasonably
professional, maintainable products of consistent quality.

Any individual can always have a private opinion as to what is "qood",
or
"right®",
or
"efficient®TM
or
"aesthetic".
Any
collection
of
individuals invariably comes up with as many divergent opinions on the
subject
as
there
are
individuals.
We
should all be sufficiently
mature and sufficiently professional to be willing to compromise
with
both
our
egos
and
our
fellow peers;
to compromise just enough to
accept objectively a set of reasonable conventions that will establish
the uniformity and consistency of all of our software products.
The Methodology qroup
has
compiled
presented in this manual.
They apply
are

based

reviewed

existing

the

PDP-11

Coding

the

coding

practices.

Conventions

manual

consisting

was

Peter

with

Peter

Dave Cutler, Roger
Gourd,
Steve
Poulsen
and
Mike
Spier.
conventions
have
been
broadened
to the BLISS environment by
with
Ron
Brender,
Rich
Grove,
and
Dave
Tolman.

Transportability
issues
Marks and Ike Nassi.
We want
people

This

Committee

Conklin,
These
review

conventions
and
practices
all VAX-1ll programming.
They

have

been

addressed

concert

these conventions to be adopted
willingly,
through arbitrary managerial edict.
This is

not
best

forced
upon
accomplished

by having
you
formulate
to
vyourself
exactly
WHY
vyou
find
some
convention
to be objectionable;
then try and propose --to yourself-an alternate one, and reflect on whether or not the new one is
really
that
much
superior,
and why.
All that we ask of you is to convince
yourself that these conventions are no less reasonable than any
other
set

conventions.

sufficient
professional
conventions.

Then,

maturity

hope,

vyou

adopt

will

and

willing

show

these

TREFACE

19-FEB-77

Rev

Page

This document is the result of integrating and reorgqanizing the BLISS
Software Engineering Manual and the VAX Assemhler Software Engineering
Manual published during the summer of 1976. New chapters have been
covering transportability, naming conventions, and
incorporated,
external interface specifications. We solicit constructive criticism
In particular, the last chapter
and recommendations for enhancement.
to address in future editions.
like
contains a list of topics we would
is
This
these topics.
toward
contribute
to
free
feel
Please
way
desirable
a
is
this
feel
you
If
completely a home grown document.
to proceed, you should feel a responsibility to review this carefully

The value of the
quality and applicability of the

and to contribute material you feel appropriate.

document

depends

submitted material.

directly

the

CONTENTS

Page

INTRODUCTION

CHAPTER 2

HOW TO USE THIS

CHAPTER

METHODOLOGICAL

CHAPTER 4

MANUAL

POLICY

PROGRAM STRUCTURE

4.1
4.2
4.3
4.3.1
4.3.2
4.3.3
4.4
4.5
4.6
4.6.1
4.6.2
4.7
4.7.1

4.7.2
4.8
4.8.1
4.8.2

CHAPTER

THE MODULE PREPACE
. . .
e o o o o o o o o
THE MODULE'S DECLARATIVE PART e o o o o o o o o
THE MODULE'S ACTUAL CODE
. . . . & 2 v ¢ o« « .
The ROUTINE PREPACE . . . ©. ©. ¢ v ¢« « « o« « .
The Routine's Declarative Part
. . . . . . .
The Routine's Code
. . . . . ¢ ¢ v ¢ ¢« ¢ « «
MODULE TERMINATION
. . © ¢ ¢ ¢ ¢ ¢ o o o o o o«
ANNOTATED SAMPLE LAYOUTS
. .
e o o o o o
SAMPLE LAYOUT OF THE MODULE PRBPACB
e o o« o
Example Of The Assembler Module Pteface e o o
Example Of The BLISS Module Preface . . . . .
SAMPLE LAYOUT OF THE MODULE DECLARATIONS
. . .
Example Of The Assembler Module Declarations
Example Of The BLISS Module Declarations
. .
SAMPLE LAYOUT OF THE ROUTINE PREFACE
. . . . .
Example Of The Assembler Routine Preface
. .
Example Of The BLISS Routine Preface
. . . .

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

4=5
4-6
4-7
4-7
4-8
4-9
4-9
4-10

b
w W

)

mcnfiumcn
|

o
o

MAKING A NEW COBOL LANGUAGE MODULE
.
MAKING A NEW FORTRAN LANGUAGE MODULE

¢S

MAKING A NEW ASSEMBLY LANGUAGE MODULE
MAKING A NEW BASIC LANGUAGE MODULE
.
MAKING A NEW BLISS LANGUAGE MODULE
.

.1
.2
.3
.4

TEMPLATE

CHAPTER

19-Feb-77 -- Rev 3

CONTENTS

FUNCTION VALUE

=«

MODULE: DATA SEGMENT
MODULE: FILE NAME . .
MODULE: PREFACE . . .
PARAMETERS: FORMAL
.
PARAMETERS: INPUT AND

ROUTINE: PREFACE
. .
SIDE EFFECTS

.
.

[] [ ] [ )

[

g v/

o
o

SIGNALS . . . .
VERSION NUMBER

.«

PROGRAM

MODULE

LEGAL NOTICES

FJe

Cle

HISTORY: MODIFICATION .
IMPLICIT INPUTS AND OUTP T S

NN EWNNN
et et O

FUNCTIONAL DESCRIPTION

oW
W W N

FACILITY STATEMENT

EXCEPTIONS

[ [

CONFIGURATION STATEMENT
ENVIRONMENT STATEMENT .

it et

COMMENT: LINE . . . .
COMMENT: MAINTENANCE
. .
COMPLETION CODES

t
e
]
O\O\O\O\C\O'\O\C\G\O\O\
]

L [ ) [ [J [ ) [ ] ] [ ] [ ]

DOCUMENTING
. . .
GROUP

COMMENT:
COMMENT:

.«

GLOBAL
LOCAL

.
.

LABEL

LABEL:

7.16

LIBRARIES

7.17
7.18

LISTING CONTROL
.
SLOCAL MACRO

[

TR T

[]

[}

~ -~

\lf\l\l\l\l\l\l\l\l\l\l\l\l
OO
WNON

INTERLOCKED INSTRUCTIONS

FILES

-t ) O
o e N fo o

= O
N

INCLUDE

.
.
.

.
.

SFORMAL MACRO . «
. IDENT STATEMENT

[

&
&

«
.+

«
«

.
.

«
«

.
.

LABEL:

p—

[]

VARIABLES

DECLARATION:
DESCRIPTOR
EXPRESSIONS

.
.
.
.

EQUATED SYMBO LS

DECLARATION:

7.15

.
.
.
.

CALL INSTRUCTIONS . .
CASE INSTRUCTIONS . .
CONDITIONAL ASSEMBLY
CONDITION HANDLER . .

== \O oo ~JoOU & Wi+
(o

ASSEMBLER FORMATTING AND USAGE

7.13
~J

[] [ [] [) [

BLOCK

[ ] [ ) L] L J [

e AW =)

[]

[

COMMENT

L] [ [ ] L ] L] L] ® L] ® [ ] [ ] ® [ ] [ ) [ ] » | ] [ ] L] L ] L

SEQUENC

[] * ° [} L] L ] ® [ ] [ ] [ [ 4 L] [ ] [ ] L} [ ] | ] [ ] L J ® ° [ 4 [ ] ® ] ® [ ) [} [ ] [ ]

CALLING

[]

® [ ] [] [ ] [ ] [] L J

-3

L[]

COMMENT:

6.30

NN N NN NNNNI
NN

AUTHOR

[]

o
o
o
o
o
o
o
e

— OO~V
WN -

ABSTRACT

6.12
6.13
6.14
6.15
6.16
6.17
6.18
6.19
6.20
6.21
6.22
6.23
6.24
6.25
6.26
6.27
6.28
6.29

CHAPTER

COMMENTING CONVENTIONS

6
R
XAk a XAk a X a XAl

CHAPTER

Page

7-14

STATEMENT
.
INSTRUCTIONS

ENTRY

7.25

.PSECT

71.26

QUEUE

7.27
7.28
7.29

RELATIVE

ADDRESSING

ROUTINE:

BODY

ROUTINE:

ENTRY:

PROCE

.
.
.
. .
.
DECLARATION

.WEAK

DECLARATION

CHAPTER

BASIC

FORMATTING

AND

CHAPTER

BLISS

FORMATING

&
e
°
o
6
o
0
o

EXPRESSION:

INCR/DECR

EXPRESSION:

SELECT

EXPRESSION:

WHILE/UNTIL/DO

SWITCH
.

MODULE:

SWITCHES

NAME

REQUIRE

.
.

FILES

®
[
[}
[]

[]

LABELS

9-15

[]

MODULE

[]

IDENT

[]
[}
[]

., .
IF/THEN/ELSE

O
R
N T
R
N ]
GNO\D\D\O\D\D%DGHO\D\D\D\DUDM
ONdAANWMBWWNDN

FORMAT

—
[ O
www N -~ O

EXPRESSION:

R I

[]

CASE

BLOCK

[]

EXPRESSION:
EXPRESSION:

[]

.
. .
.
. .
ASSIGNMENT

[]

EXPRESSION:

[)

[]

ORDER

ROUTINE

[]

DECLARATION:

FORWARD
MACRO

[]

.
.

[]

.
.

[]

.
.,

DECLARATION:

EXPRESSION:

FORMAT

DECLARATION:
EXPRESSION

o
¢

USAGE

[]

USAGE

[

[]

DECLARATION:

AND

[]

DECLARATION

LOCAL

[]

STACK

[]

VARIABLES:

.
.VALIDATE

[]

UNWIND

STATEMENT

[]

7.44
7.45

.
.

7.42

.TITLE

SYNCHRONIZATION:

7.40

EXTERNAL
GLOBAL

SYMBOL:

.
STRING INSTRUCTIONS
STRUCTURES
. . . .
SYMBOL
., .
. .
.
.

SYMBOL:

7.43

71.34
7.35
7.36
7.37
7.38
7.39
7.41

{Ne

.SBTTL STATEMENT
STATEMENT . . . .
STATEMENT: BLOCK

7.32
7.33

NON-STANDARD
ORDER

ROUTINE:
ROUTINE:

7.30

7.31

MULTIPLE

.
.

[}

.
.

FORMAL

.
.

[]

PROCEDURE:

SOWN MACRO

PARAMETERS:

.
.

[]

PROCEDURE

7.24

LSB: .ENABL/.DSABL
MACROS
. .
. .
.
.

9-16

7.19
7.2
7.21
7.22
7.23

FORTRAN FORMATTING AND USAGE

CHAPTER

NAMING CONVENTIONS

12.1
12.2
12.3

PUBLIC SYMBOL PATTERNS
OBJECT DATA TYPES . . ¢
FACILITY PREFIX TABLE .

FUNCTIONAL AND INTERFACE SPECIFICATIONS

[

.
[]

12-2
12-6
12-7

. . . .
Procedure Parameter Qualifiers
Optional Arguments And Default Values .

ROUTINE INTERFACE TYPES

¢«

NOTATION FOR DESCRIBING PROCEDURE ARGUMENTS
.
o

.
o

Repeated Arguments
. ¢« « ¢ o
ExamplesS

¢
o

«
o

Summary Chart Of Notation .

¢
o

BLISS TRANSPORTABILITY GUIDLINES
.

INTRODUCTION

Purpose And Goals
. .
Organization
GENERAL STRATEGIES
Introduction
Isolation .
Simplicity

.
.

¢«

TOOLS

Literals

Predeclared Literals
User Defined Literal
.

MACROS

Module Switches
Reserved Names
REQUIRE Files

14.:/
14.4.1

.
¢
.

ROUTINES
TECHNIQUES
Data

.«
.

ooocooomoooooooooo

14.1
14.1.1
14.1.2
14.2
14.2.1
14.2.2
14.2.3
14. l

[]

CHAPTER

[
L]

.
o
.

COBOL FORMATTING AND USAGE

CHAPTER

[]
.

[}

[]

.
o
.

13.1
13.2
13.2.1
13.2.2
13.2.3
13.2.4
13.2.5

[

[}
[]

.
¢
.

CHAPTER

[]

[]
[}

®
[
[]

[}
[]

[)

[}

[]
[]

[]
[

[]

[)
[]

[]

[

[
[
[}

[

[]

[

[]

[]
L]

[]
[

[]

BLOCK

[}

DECLARATIO

[]

.
.
.

[]

STRUCTURE:

.
.
.

[]

STRUCTURE:

FORMAT
NAME .
ORDER

[]

9.22
9.23
9.24
9.25

ROUTINE:
ROUTINE:
ROUTINE:

ROUTINE

9.20
9.21

[

19-Feb-77 =-- Rev 3

CONTENTS

¢
o

o
o

<
o

.
o

[

14.4.1.1
14.4.1.2
14.4.1.3
14.4.2

14.4.2.1
14.4.2.2
14.4.2.3

14.4.2.4
14.4.3
14.4.3.1
14.4.3.2
14.4.3.3

14.4.4
14.4.4.2

14.4.4.3
14.4.4.4
14.4.4.5

14.4.4.6
14.4.5
14.4.5.1
14.4.5.2

14.4.5.3

14.4.5.4
14.4.5.5
14.4.5.6

.
-

.
.

Usage

Character

Strings

Scalar
String

.
.

Structures

FLEX

. .
..

1l4-15
14-15

1l4-16

14-18

.
-

14-18
14-20

14-21

.
.

14-22
14-22

.
.

14-23

14-24

14-25%

14-25

14-25
14-25
14-26

14-29

.
.
¢«

.
«

.
.
.

14-33
14-39
14-39

e
o

o«
o

«
o

.
.

1l4-39
1l4-30

.
Field Selectors
GEN VECTOR
. &
Summary . . . f

=
&
4

v
e

4«
e

l4-43

¢
e

4
e

o
e

o
.

v
.

.
.

18-44
14-47

15-1

VECTOR

DIAGNOSTIC

15=-2

e
e
v

s+
o
v

s
s+
¢

s+
s
&«

s+
e«
o

&
e«
o«

.«

15-=3

o
o

o
.

15-4
15=5

15.2.9

Report

Ptable
Table

.
.

. .
Subroutines

.
.

15-8

.
¢«
o
¢«

¢«
<
o
«

.
«
o«
«

.
.
«
.

.
.
.
.

15-8
15=-9
15-9
15-10

¢«
.

v
.

«
.

&«
.

«
.

.
.

15-10
15-11

o«

«
.

o
«

15-13
15-16

15-16

15-17

v
.

¢
.

Hardware

.
.+ & ¢
¢
Parameter Code

¢
.

Software

Parameter

o
CONVENTIONS

MACRO

EXPANSION

ASSEMBLER

SAMPLE

Code

15-6
15-7

¢«
.
&
¢

CONVENTIONS

.
.

Test

.
.

Hardware

«
.

15.2.13
15.2.14

o
.

Program

o
.

15.2.11

¢«
.

.
¢«
«
v

15.2.12

¢
.

.
.

Code . .
Intialize Code
Cleanup Code
.

v
.
.
.
&
¢

.
.

15.4

e
o«

Software
Dispatch

SYMBOL

e
o

SECTIONS

15.2.6

15.3

e
4

CONVENTIONS

15.2.7
15.2.8

.
.

Program Header Section
. .
Program Equates(declaratxons)
Program Data
. . . . . ¢ ¢ ¢
Program Text
. . . ¢«
¢« ¢« ¢« ¢
Program Error Report
. .
. .
Hardware Ptable . . . .
. . .

15.2.15

.
.

PLIT Items = . . . . v v «
Literal PLIT Items - . .
.
An Example Of Initialization - .,
Initializing Packed Data . . .
Structures And Field Selectors
. .
Introduction
. . . . .
. ¢« +
¢ ¢

INTRODUCTION

15.2.10

.
.

And

And Initialization
Introduction
. . . .
.
PLITs In General . .

DIAGNOSTIC

15.2.5

.
.

Declarations . .
«
Address Calculatlons
Introduction
. . . . . . . . . . . . .
Addresses And Address Calculations .
Relational Oprs And Control Expressions
BLISS-10 Addr. Versus BLISS-36 Addr. Data: Character Sequences . .
. . . .
.
.
Introduction
. . . . . . . . . .
. .
.
Usage As Numeric Values - ., .,
.
., .
.
.

15.1

15.2.4

APPENDIX

Transoortable
Data: Addresses

15.2

15.2.1
15.2.2
15.2.3

.
Genesis

PLITs

14.4.4.1

CHAPTER

Introduction
Problem

.
.

CONTENTS

19-Feb-77

Rev

APPENCIX

BLISS

SAMPLE

APPENDIX

COMMON

BLISS

‘fnd

Prefix]

SAMPLE

Page

Digital

Equipment

Title:

VAX-11

Specification

Corporation

Software

Engineering

Status:

draft

Architectural Status:

under

File:
PDM

Date:

not

Specs:

Typist:

Conklin

Reviewer (s):

Marks,

Spier

Brender,

Cutler,

Poulsen,

Tolman

The

Revision

History:

control

Abstract:

Rev

none

Conklin,

Rev

23-Feb-77

Rev

Introduction

Page

used

Author:

Rev

ECO

CONFIDENTIAL

SE1R3.RNO

Superseded

Rev

COMPANY

Gourd,

introduction gives a chapter
manual and how it is organized.

Description

Original
Revised from
After

Review

months

experience

Hastings,

chapter

overview

Nassi,

the

Author
M. Spier

Revised Date
14-Apr-76

Marks

Conklin

21-Jun-76
23-Feb-77

Introduction
Change

Rev

[End

23-Feb-77

Rev

general

Page

1-990

History

Rev

Change

the

Add

Chapter

Add

Chapter

Add

purpose

Split

Add

Collect

SE1R3.RNO]

chapter

chapters
loose

contents

and

quide

99).

manual.

into

and

15.

ends

through

last

11.

chapter

the

chapte.s.

CHAPTER

INTRODUCTION

23-Feb-77

This

manual

VAX-11

concerned

environment.

with

software

does

not

between

Rev

engineering

discuss

practices

define

the

1in

the

differences

VAX-11
and
other
environments.
Designed
to
be
the
"programmer's
helper",
the manual contains the coding conventions as
well as practical data of technical,
procedural,
administrative
and
conceptual

This

nature

manual
0

has

that

two

would

useful

provide

the

Software

Engineer

found

notes

symbol

construction

present

such

the

software

engineer.

purposes:

normally
and

langquage

recommended

commenting,

with

reference

information

manuals

such

not

usage

rules.

standards,

formatting,

conventions,

and

practices

documentation.

Conventions, standards and practices can
assure
good,
professional,
maintainable
products
of consistent quality.
They need not encroach
on the programmer's "right" to be creative in his or her expression of
a

program.

Chapter

1 is the introduction
and
gives
a
gquide
to
the
organization.
It includes a chapter by chapter overview.

Chapter
exact

tells

how

information

use

needed.

this
It

manual.

also

gives

manual.

Chapter

policies
the

basic

include
include

the

which

methodological

lead

the

structure

programs

policy

specifics
into

the
goals
to be attained
the choice of language, the

tells
the

statements.

the

how

notations

format.
modules.
The

manual's

find
used

These

They
policy

are

the
the

the

also

outline
statements

by following them.
These policies
layout of
the
source
text,
the

Introduction

23-Feb-77

separation

into modules,

Rev

and

Page

the

1-2

sharing of code.

Chapter 4 is a
program
structure
overview.
It
1lists
the
source
module's
textual
elements,
and
gives
examples of the parts of the
program.
This pulls together in
one
place
the
details
documented
later in chap<er 6.
Chapter
5
gives
the
standard
module
template
files
and
the
instructions
for
wusing
them.
The standard template contains all of
the standard boilerplate as a convenience to save excessive retyping.

Chapter 6 details the commenting conventions.
These
are
consistent
across
all source languages.
The entries are arranged alphabetically
for ease of reference.
There is extensive
cross-referencing
to
aid
retrieval.
For each item, it gives the background and the rules, and
then gives templates and examples.

Chapters 7 through 11 give usage and formatting conventions
for
each
of
our
programming
languages.
The languages covered are assembler,
BASIC, BLISS,
COBOL,
and
redundancy
between
these

Fortran.
chapters,

Although
we
felt

there
1is
it better

occasional
to minimize
retrieval difficulty at the expense of some duplication.
The chapters
are
layed
out in the same style as Chapter 6.
When a topic deserves
more than a page to describe, an outline is given
here
and
a
cross
reference is made to a fuller presentation in some other chapter.

- Chapter 12 is the naming conventions.
These include the formation
symbols reserved to Digital and the list of facility prefixes.
Chapter

gives

documentation.
specifying

Chapter

programs

details

procedure

arguments.

contains

across

In particular,

external

and

for

the

transportation

Chapter 15 contains additional information and guidelines for

diagnostics

programs.

The last chapter

Chapter

BLISS
writing

is a collection of loose ends and future sections.

The appendices give
[End

interface

it includes details on the notation for

guidelines

architectures.

forming

full sample programs written to this standard.

Digital

Equipment

Title:

VAX-1ll

Corporation

Software

Engineering

Specification

Status:

draft

Architectural

Status:

under

File:

SE2R3.RNO

PDM

not

Date:

How

Page

Use

Rev

Gourd,

Hastings,

control

used

Specs:

none

Author:

Conklin,

Typist:

Conklin

Reviewer (s):

Abstract:

R.
S.

Marks,

Brender,
Poulsen,

Chapter

D.
D.

gives

its
notations.
in it.

Revision
#
1

ECO

CONFIDENTIAL

26-Feb-77

Superseded

Rev
Rev

COMPANY

Spier

Cutler,
Tolman

guide

the

use

suggests ways

the

manual

looking

1I.

Nassi,

and

gives

information

History:
Description
Original

Author

Rev

Revised

from Review

Rev

After

months

experience

Revised

Spier

Date
14-Apr-76

Marks

21-Jun-76

Conklin

26-Feb-77

How to Use this Manual
Chanqge Histocry

26-Feb-77 -- Rev 3

Rev 2 to Rev 3:

Replace usage cross reference notation.

Note split of commenting and usage chapters.

[End of SE2R3.RNO]

Page 2-990

CHAPTER
HOW

USE

THIS

26-Feb-77

This

manual

assumes

purpose

language

features

The introduction
explaining
what
lists individual

keywords

Suppose

that

you

should
commenting.

each

within the
COMMENT, ROUTINE,
told

that

look

the

your
the

if
source

you

name

the

some

your

This
and

will

enable

you

have

immediately

the

exact

amount

needs.

keyworded

item

such

for
for

Keyworded

data

may
©

needs

told

which

the

manual,

table

contents

The index
etc.)

under

was

better

"C"

that

the

your

poor,

you could
formatting and

the

The

comments.
chapter on
useage
or

look

usage

up
for

requireda,

pertinent

information

certain

organized

information

that

additional

chapters.

sts

Its

about

important

point

pertaining

your

the
that

is
not
confused
with
the
information
reason.
The
manual is deliberately not
back-cover sequential reading.

"B"

item(s)
"B"

"A"

reference
those

program

to retrieve
information

get

other

The

languages.

use

chapters

Chapters.
STATEMENT,

chapter

cross referenced.
knowledge or use of

Knowledge

Use

the

concept

require

within

then

VAX-11

precise

specific

front-

related
0

the

information

some

organized

"A"

additional

needed

You may

the

were
statement

statement’s
language.

immediate

contains.

sections

were

Rev

indicates

chapter

Similarly,
of

MANUAL

with

guide

put.

(chapter

typically

formatting
under

may

(e.g.,

You

familiarity

serve

and

"C":

which

you

"C":

is
in

"SEE

"B"

ALSO"

also

the

and

keyword

"C".

pointer

indicates

understand.

occurrence

with

indicate

turn.

rules

should

first

prefixed

pointer

keywords

the

The

keywords

"B"

word

"see"

possible

need

and

serving
to

the

"¢

consult

How to Use this Manual

26-Feb-77 -- Rev 3

Page 2-2

For example
There may be variants of a single keyworded concept.
by the
ordered
are
s
keyword
the
case,
LABEL and LOCAL LABEL. In this
by
ed
retriev
be
to
1is
variant
any
and
main concept (e.g., LABEL),
colon
the
use
We
word.
key
ing
qualify
the
suffixing that keyword with
"." ag a qualification delimiter within the manual (e.g., LABEL:
.
LOCAL)

Finally, whenever this manual is reissued, all changes relative to the
immediately preceding version of the manual will be indicated by means
of a left margin change bar, as illustrated to the left of this entire
paragraph.

[End of Chapter

Digital Equipment Corporation COMPANY CONFIDENTIAL

VAX-11

Title:

Software

Engineering

Specification Status:

draft

Architectural

under

Status:

File:

SE3R3.RNO

PDM

not

Date:

Specs:

Conklin,

Typist:

Conklin

Reviewer (s):

R.
S.

Abstract:

source

WIN
= =

Revision

Marks,

Brender,
Poulsen,

Chapter

These

Rev

Gourd,

Hastings,

control

none

Rev

used

Author:

Rev

26-Feb-77

Superseded

Rev

ECO

Policy

Page 1

D.
D.

Spier

Cutler,
Tolman

1I.

Nassi,

3
gives
the
methodological
policy
statements.
include
the
choice
of language, the layout of the

text,
code.

the

separation

into

modules,

and

the

sharing

History:

Description
Original
Revised from Review
After 6 months experience

Author
M. Spier
P. Marks
P. Conklin

Revised Date
14-Apr-76
21-Jun-76
26-Feb-77

Call/return interface
Choice of language
Code sharing
Control
working set

Field support personnel

Functionality

Implementation

language
«

programs

system
Language

choice of

Modifiability
Modular

Quality

Read

code

Readable system code
Sharing
code

Support personnel

System code
readable

System 1mplementat10n language

Transportability

Working set control

Methodological

History

Change

Rev

to Rev

Policy

Page

transportability.

Remove reference to page boundaries.

Allow code

Document reasons for structure and for

Limit

Remove
i m]

in application languages.

interface data types to call

standard.

references to self-initializing.

[End of SE3R3.RNO]
TM__

26-Feb-77 -- Rev 3

3-990

CHAPTER

METHODOLOGICAL

26-Feb-77

All

system programs for
the
application
language
or
implementation languages:
o

The

BLISS-32

VAX-11

these,

assembler

will

default

the

used

Hardware

drivers,

dependent

performance
Cases

functionality

where

BLISS;

for

non-standard

choice

example,

are

written

two

official

for

language.

code

implementation

such

machine

interrupt

dependency
the use of

rule

out

needed

routines

impossibility,
which

that

which

written

(as

is
are

have

been

This

coded

BLISS

language

only

handlers

not
to

1is

The

with

1/0

high

supplied

be. invoked

BLISS

distinct

undesirability).
would

1in

system

possible.

coupled
BLISS.

way.

Routines
which
cannot
be
ccmpilation
difficulty
routines

the

assembly

routines,

extreme
requirements

family

system

where

much

for:
0

one

Assembler,

replace

Rev

VAX-11

Macro

BLISS

intended

POLICY

by
in

because

of
functional

from

SEE ALSO:

Block

Comment:

Wwhenever the attention of the reader should be called to a
code,

sequence

any of the following:

When several paths join, note the conditions which cause flow

All exceptions converge at this point with:

to reach this point.

...<register and stack status>

At the

top of a loop.

: Loop looking for a handler to call.
.

[

When some data

base

been

built,

such

complex

wide

comment

At this point the stack has the following format:

“O

sequence on the stack.

has

saved R2
number of

...

WME

00 (SP)
04 (SP)

particular

This might be in

a group comment should be used.

The group comment consists of a number of page

lines:

the <comment delimiter> is enterred, left aligned, in

the line's first character position.

The first and last lines of the group comment are just a
<comment delimiter> and are set off from surrounding code by
Both the blank
a blank line before and after the group.
ry and help
mandato
are
lines
blank
the
comment lines and
distinguish the comments and code visually.

The body of the group comment consists of

descriptive

separated from the <comment delimiter> by a space.

text,

Tabular information is separated from the <comment delimiter>
by

tab.

Commenting
COMMENT:

6.8

Conventions

COMMENT:

line

comment

being

comment

1is

any

The

text

Rev

placed

text.

1line

text
of
the
{comment delimiter>.
statement

the

Page

6-7

the

end

preceded

by as many tabs
with column 41.

hand

into

are
41

the

code

side

should

the

text

with
(5

adjacent

comment

whereas

necessary

non-comment

aligned

space,

meaning

assembly

right

column

the

delimiter>,

comments

overflows

starting

comment

preceded

explain

<comment

margin).

the

every

The

and

All
assembly
language
{comment delimiter>
in

left

used

following

Each

comment

line

normally

commented.

of
the
line.
commented.

LINE

statement

28-Feb-77

LINE

field,

tabs

the
from

the

then

its

normally

position

the

would

comment

the

comment is too long to be contained on a single
line,
1f the statement was too long to be commented on the same
line, then the comment may be placed (or
continued)
on
the
following
1line,
placing the <comment delimiter> in the same
column as the first line and including a space after it.

For

commenting

multiple-line

fragmented

statement.
The

comment's

text

should

convey

text
(e.g.,
instruction
pointer to first buffer in

into

B".)

the

MOVAL A,B
free area"

rule

comment,

meaning

should

the

statement

associated

commented

program

"Initialize

or such, not "Move
the
address
thumb, symbols should not appear 1in a

rather say what the object is or means.
If a line of code
totally
self
evident
to
the most casual reader then it need not
given
redundant
commenting
text,
however
it
must
have

<comment delimiter>
(see
example).
If a comment
successive lines of code, indicate commonality
by
lines with comments of the form "!<space> .
.

matter

<comment
style

changed
would

taste,

some

coders

see

applies
tagging

is
be

a
several
follow-on

place
a
single
space
after
the
modifications to a module should follow the
the original author.
The
original
source
should
not
be
to
the
modifier's
style because then a differences listing
useless.

delimiter>.

All

Commenting Conventions
COMMENT:

LINE

28-Feb-77 -- Rev 3

Example:

page 6-8

STATEMENT

;Compute multiple-line function

OBVIOUS STATEMENT

STATEMENT
STATEMENT

HERPR

STATEMENT

sHere we do something new

; and extend the comment to the
+
:

OBVIOUS STATEMENT

next two lines.

A SOMEWHAT LONG STATEMENT +And its comment
A SOMEWHAT LONGER STATEMENT ;And its long comment
+
+

which continues on
additional line(s).

A VERY VERY VERY VERY VERY VERY LONG STATEMENT

A FRAGMENTED
|

STATEMENT

:And its comment on next line

:The statement's comment

Commenting
COMMENT:

6.9

Conventions

28-Feb-77

Rev

Page

6-9

MAINTENANCE

COMMENT:

MAINTENANCE

ALSO:

SEE

Author

History:
Modification
Version Number

When an existing module is
modified
(as
distinct
from
"originally
coded"),
each
1logical unit of modification is assigned a maintenance
number in the detailed current history section of the module
preface.

Use
a
worked

are

new

on.

never
a

two

logical

numbers

round

the

reasons

(such

release
to

for

unit

of modification
increase by one, are

permissable

after

release

100s)

make

the

level.

Add

maintenance

each line of source code that
having maintenance comments:

room

bump

the

number

for

SPR

fixes

comment
is

that is being
decimal,
and

--derived

affected.

There

from
are

The

modifications
may
well
be
distributed
all
over
the
module.
The maintenance comment enables you to find all the
places where a correction of a single functional problem
was
made.
This is especially useful if the correction has to be
further corrected by someone other than the original modifier
and/or

in
2.

number

number--

for each
maintenance

reset.

that

number

The

the

if it
field.

has

understood

the

software

specialist

All

too often it happens that
as
we
correct
bug
"B",
innocently modify an instruction which was the correction
a previous bug "A".
Bug "B" is fixed at the expense
of
reappearance

bug

"A"

(or

one

1its

relatives).

we
for
the
If

modification of a program leads you to the modification of
a
line
that
already
has a maintenance comment, then find out
(from the detailed current history)
who
the
modifier
was,

consult
effecting
In

many

cases

the

that
your

edit

person,
and
modification.

numbers

modules
in
a
facility.
facility's version number

the

others

should

include

may

In
this
should have

only

module

exercise

assigned

extreme

caution

1in

across

all

defining
history

the
and

consistently

case,
the
module
a full maintenance
specific changes.

Commenting Conventions
COMMENT:

MAINTENANCE

Page 6-10

28-Feb-77 -- Rev 3

The following rules apply to maintenance comments:

The maintenance comment consists of a <comment delimiter>
followed by a code letter, followed by a maintenance number.

The code letter may be

A - this line was ADDED to the text

the
effect
case,
In this
DELETED.
1line was
D - this
a
Place
1line out.
the
commenting
by
“*deletion”
position of
character
<comment delimiter> in the first
marking it as a candidate for future physical
line,
the
deletion.

M - This line was MODIFIED.

The maintenance comment is placed after
comment at column 80

IRegqular comment

the

1line's

regular

!<maintenance_comment>

If the modified line already has an existing maintenance
comment, then add the new one in front of the existing one

!Regular comment

!<new_mc>!<previous_mc>

Example:

The maintenance number is assigned in

the

section of the module preface, as follows:
1 02

detailed

current

SPR #4711: describe the SPR problem

The number is now used in maintenance comments for all lines
affected by the modification called for by SPR #4711:

history

MODIFIED STATEMENT
ADDED STATEMENT

DELETED STATEMENT

IStatement's comment
Istatement's comment

1Statement's comment

text
1M02
tAQ2

D02

1If the statement is a multiple-line one, make sure to place
NOTE:
(or effect a "commenting out®TM deletion) on all
maintenance comments
component lines of the statement.

Commenting

Conventions

COMPLETION

CODES

6.10

The

COMPLETION

most

28-Feb-77

Rev

Page

6-11

CODES

reliable

means

for

indicating

software

detected

exception

condition
occurring in a called procedure is for the called procedure
to return a condition value as a function value and for the caller
to
check the return value for TRUE or FALSE.
TRUE is bit 0 set and FALSE
is bit 0
cleared.
TRUE
means
that
the
requested
operation
was

performed
both

successfully;

cases,

the

procedures

rest

are

FALSE

the

written

is necessary to indicate an
value, then generate a call

means

error condition occurred;
in
condition
value.
Thus,
most
rather than subroutines.
If it

value

is a
functions,

exceptional situation without
to LIB$SIGNAL, see Signals.

The low order three bits, taken together, represent
the

error.
> wNo
O

Severity

values

the

are:

severity

Warning
Success
Error

Reserved

Severe

Error

Reserved

code

returning

Bits

<31:16>
indicate
the
facility,
see
the
Naming
Conventions
chapter.
Bits
<15:3>
distinguish
distinct
conditions
or
system
messages within the
facility.
Bits
<2:0>
can
vary
for
a
given
condition depending upon environment, condition handling, etc.
Status
codes

are

expressed

fac$S
Return

and

symbolic

names

the

format:

mnemonic

status

branching

the

values

assembler

BLBC

can

tested

error

checking
follows:

testing

routine

the

low-order

low bit

bit

not

set,

RO,errlabel

The
error
checking
routine
may check for specific values.
It must
always ignore <2:0> when checking for a particular
condition
because
<2:0> can vary depending upon the severity in the current environment.

For

example

illegal

assembly

event

CMPV

flag

codes

successful

return

resource.

For

(SSETEF)
when

the

error

following

instruction

condition:

checks

for

#3,#29,R0, #<SS$_ILLEFC@-3>

Successful

set

language,

number

other

than

includes

example,

SS$

NORMAL

information

the

return

system service indicates
the service was called.

are

defined.

about

the

SS$ WASSET

that

the

1In

some

from

requested

the

cases,

status

Set

Event

flag was

a
a

Flag

already

Commenting Conventions

CONFIGURATION STATEMENT

Page 6-12

CONFIGURATION STATEMENT

6.11
SEE

28-Feb-77 -- Rev 3

ALSO:

INCLUDE Files
Preface
Module:

The configuration statement is part of the environment statement in
the module preface, and serves to indicate to the programmer how the
The module may be part of a large system
module is to be assembled.
It may also have
with a system-wide conditional assembly arrangement.
alone or in
either
ts,
its own peculiar conditional assembly requiremen
ions.
conjunction with system-wide convent

State the name(s) of the include file(s) <containing conditional
State the conditional assembly
(if any).
parameters
assembly
If the variables are peculiar to
variables affecting this module.
state the values that they may assume, and what thesr
this module,
values

mean.

Example:
!
!

ENVIRONMENT:

This module may be assembled with various parameters

of the macro SFAC CHANGE DEF with the changed symbols in

!
!

!
!
1

changed. This is done by supplying a special copy

it as a library file. The symbols which can be changed
are the default lines per page (DEF LINES PPAGE) which

is normally 55, and the maximum line width (MAX LINE WIDTH)
which is normally 132.

Commenting

Conventions

ENVIRONMENT

STATEMENT

6.12

ENVIRONMENT

AL
SEE E ALSO:
Configuration

28-Feb-77

For

Statement.

For

execution time
module
may assume.
single.

compile

environment

For

time

6.13

SEE

standard

the

describe

example,

procedure

ordinary

such as

hardware

environments,

it may

processor,
or
that
this
interrupts
disabled.
The
module
user mode, that ASTs are
disabled,
the

6-13

environmental
assumptions
which
both compilation assumptions such

configuration files and execution

Page

Statement

environments.

anything out
environment.

STATEMENT

This paragraph gives any special
module
may
make.
These include

handled

Rev

any
assume

module

might
or

library.

which

the

invoked

storage
1In

software

Confiquration

situations
which
that the hardware

1is
always
assume that

that

see

general,

module

a
as

runs

with

only

allocation
document

assumes

the
is a

about

in
is

here

its

EXCEPTIONS

Signals

6.14

FACILITY

This

section

STATEMENT

which

this

for

list

the

module

preface

is a part.
facilities.

gives

See

the

full

Naming

name

of the facility
Conventions chapter
'

Commenting Conventions

FUNCTIONAL DESCRIPTION

e e

e — — — —— —— — — — — ——

e oorus | o

= TR —— —

6.15

28-Feb-77 -- Rev 3

Page 6-14

FUNCTIONAL DESCRIPTION

s
The functional description section of the module and routine preface
should
and
routine
should describe the purpose of the module or
document its interfaces precisely and completely

any
The functional description should also include the basis for ces
referen
ure
literat
include
critical algorithms used. This should
numerical
when available. For example, specify why a particular ular way of
algorithm 1is wused in the math library or why a partic
sorting was chosen.

The functional description appears in one of three places:
o As a self-contained short description on the first
the module and routine prefaces.

As the second or more page(s)
In this case an
prefaces.

page

of the module and routin
abstract appears on the first

page.

In this case an
As a separate functional specification.
abstract appears on the first page of the module and routine
prefaces and a reference to the specification is included.

Commenting Conventions
FUNCTIONAL DESCRIPTION

28-Feb-77

Rev

Page

6-15

Example:
I ++

FUNCTIONAL

DESCRIPTION:

!
!

EXP(X)

computed

using

the

following

approximation

technique:

!
!

X
X

|X|

> 88.028 then overflow
<= -89.416 then EXP(X)

2**-28

then

EXP (X)

2%*Y

2#%%7

0.
1.

!
!

}

Otherwise,
EXP(X)

O*k&y

where
TN

!
!

integer (X*1og2(E))
frac(X*1og2(E)) * 16

integer
(V) /16
frac(V)/1l6

2**W =

!
!

(P + W*Q)

(P - W*Q)

P and Q are first degree polynomials in W**2., The
coefficients of P and Q are drawn from Hart $1121.

!
!
!

Powers

arithmetic is done in double precision and then rounded
to single precision at the end of calculation. The relative
error is less than or equal to 10**-16.4.

!
!

2**(1/16)

are

obtained

from

table.

All

Commenting Conventions
FUNCTION

6.16

Page 6-16

28-Feb-77 -- Rev 3

VALUE

FUNCTION VALUE

SEE ALSO:

Parameters:
Parameters:

Side Effects

Formal
Input and Output

These sections of a routine preface should include

all

locations

global or own storage which are read or written by the routine. Any
locations which are addressed by parameters should not be documented
in these sections, see Parameters: Formal, and Parameters: Input and
Output.

ADDITIONAL SPECIFICS TO BE SUPPLIED

Commenting

Conventions

LEGAL

NOTICES

6.19

LEGAL

standard

page
legal

Rev

will

DEC

copyrig
ht
4

plainly

the

directly
0

statement

must

always

any

DEC

produced

program
a

listing

language

The

legal

use

the

notices may undergo revision.
proper current version.

The

legal
them.

the

source).

notices

are

always

developing a new module,
first release, not of the

When

modifying

existing

upper

program

that

Add the year of modification to the
existing
copyright
statement;

DIGITAL

6-19

(C)

are

the

following

first

The
they

(regardless

has

sure

was

that

you

bring

emphasis

year

the

legal

notices,

and

form:

1977

EQUIPMENT CORPORATION,

SOFTWARE

COMPUTER

validity,

the

preface.
so that

year
stated
by
the
DO
NOT
wupdate
that
existing year:
add
the
current
one
(if
different),
separating it from the last date with a comma (",").

notices

year stated
first coding.

(2)

statements'

Make

the

Verify

the

processor

case

(1)

legal

ABOVE

was

appear

of the module
program text,

from

the

THIS

Page

printed

When

stated

listing

to
0

NOTICES

of
every
source
file.
It is part
notices must be part of the original

whether

The

28-Feb-77

FURNISHED

SYSTEM AND

MAY

NOTICE.

MAYNARD,

MASSACHUSETTS ‘01754

UNDER A

BE
THIS

MAY

LICENSE FOR USE ONLY ON A SINGLE
COPIED ONLY WITH
THE INCLUSION OF THE
SOFTWARE, OR ANY OTHER COPIES THEREOF,

NOT BE PROVIDED OR
OTHERWISE MADE AVAILABLE TO ANY OTHER PERSON
EXCEPT FOR USE ON SUCH SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE
TERMS.
TITLE TO AND
OWNERSHIP OF THE
SOFTWARE
SHALL AT ALL TIMES
REMAIN IN DEC.
THE

INFORMATION

THIS

AND

SHOULD

CONSTRUED

NOT

SOFTWARE
AS

SUBJECT

COMMITMENT

CORPORATION.
DEC

ASSUMES

SOFTWARE

The
not

license
license

RESPONSIBILITY

EQUIPMENT WHICH

FOR

NOT

THE

USE

SUPPLIED

CHANGE
BY

WITHOUT

DIGITAL

NOTICE

EQUIPMENT

RELIABILITY

ITS

DEC.

paragraph should be omitted from software which
DEC
does
(e.g., distributed through DECUS or not owned by DEC).

Page 6-20

28-Feb-77 -- Rev 3

Commenting Conventions
MODULE

6.20

MODULE

The
The module is a single body of text that is assembled as a unit.
is
that
y
facilit
oOr
program
larger
module 1is normally part of a
created by linking all of the component modules

object code.

There must be some self evident 1identity Jjustifying the module's
That is to say, the module 1is not just an arbitrary
existence.
Typically, the
concoction of code, but a self evident unit of code.
module consists of either:

A single function or database,

(e.g., all conversion
A collection of related functions
for an independent
small
routines) each of which would be too
module.

The word "module" is used in its hardware sense: a "black box" unit
that may be attached or detached, plugged in or out. In order to have
this desirable property of a "plug-in module", the module's interface
Use formal argument carrying calls
has to be as clean as possible
for all routines in the module, avoid all functional side effects. 1In
non-standard interfaces, try using a "“standard"
of
case
the
non-standard interface (i.e., an interface that is uniform within the
program of which the module is part.)
The module should contain
THE FUNCTIONALITY,
THE WHOLE FUNCTIONALITY

AND NOTHING BUT THE FUNCTIONALITY!

Then, if it is known that a certain functionality 1is wholly and
exclusively 1localized to a given module, it becomes possible to
replace the module by a more efficient one, or selectively 1link it
into the larger program depending on the runtime requirements. The
ability to do this is more wuseful and important than any local
that would jeopardize the module's functional
efficiency "hackery'
identity. When in doubt, place each routine in a separate module.
Combine

few routines primarily when doing so allows own storage to

be used rather than global storage.

6.21

MODULE:

SPECIFICS

DATA SEGMENT

TO BE

SUPPLIED

Never combine many routines.

Commenting
MODULE:

6.22
Each

Conventions

FILE

MODULE:
module

28-Feb~77

Rev

Page

6-21

the

NAME

FILE

exists

file
reflects the
of which it may be

NAME
as

distirnct

module's
part.

source

text

funct ionality

and

file.

also

The

the

name

larger

facility

The

module is stored in a filename which is the non-facility
part
of
the
name,
see
the Naming Conventions chapter.
The file type is the
standard
one
for
the
source
1language.
There
is
no
special
significance
to
the file generation version (i.e., it need not match
the edit number or increase from release to
release).
The
file
|is
stored in a directory which corresponds to the facility.

6.23

MODULE:

PREFACE

The

module preface provides uniform documentation of the
module.
It
contains
certain
control items (TITLE and IDENT) which are needed by
the linker, as well as the standard DEC copyright statement needed
for
the
protection
of
DEC's
1legal
ownership rights.
Apart from these
items, the module preface contains all of the information
that
might
be
needed
in
order
to
know
what the module is and does, what the
module's history is, and how the module relates to the larger
software
product
of which it is a part.
This documentation should include the
design basis for any critical algorithms.

The

module

Structure

preface

adhere
to
the
mechanically.
information from

documentation.
uniform

1is

Overview

standard
For

the

This

syntactical

described

chapter.

and

All

format,

example,
it
module preface

can only be

construction.

illustrated

module

prefaces

that

should

the

Program

rigorously

they

be
order

achieved

should

can
be
processed
possible
to
extract
to
compile
technical

the module preface
:

is of

Commenting Conventions
PARAMETERS:

6.24

FORMAL

Page 6-22

28-Feb-77 -- Rev 3

PARAMETERS: FORMAL

SEE ALSO:

Implicit Inputs and Outputs

Parameters:
Procedure

Routine:

Input and Output

Preface

eturn mechanism with
The VAX-11 hardware has a built-in advanced call/r
specifies a list
caller
The
g.
passin
nt
provision for automatic argume
ters which
parame
s
expect
ure
proced
The called
of arguments.
correspond one-to-one to the caller's arguments.

ents of each
The procedure's parameters will be bound with theas argum
"formal parameters”
caller, at the moment of call. They are known
address) on their
because they have no identity (i.e., specific memory
own, but assume the identity of whatever arguments the present caller
chooses to supply.

The argument list pointer

caller-supplied argument list.

always points

the

base

the

Commenting Conventions
PARAMETERS:

6.25

28-Feb-77

-- Rev

Page

6-23

INPUT AND OUTPUT

PARAMETERS:

INPUT AND OUTPUT

ALSO:
Calling Sequence
Implicit Inputs and
Parameters:
Formal

SEE

Outputs

These sections of a routine
preface
should
include
passed
on
the stack or in registers.
Any parameters
are addressed directly in own or global storage should

as
the
in

1implicit
inputs and outputs.
CALL AP-list mechanism should

the

calling

ADDITIONAL

sequence.

SPECIFICS

any
parameters
whose locations
be
documented

Any parameters which are passed via
be documented as
formal
parameters

SUPPLIED

Page 6-24

28-Feb-77 -- Rev 3

Commenting Conventions
PROGRAM

6.26

PROGRAM

SEE ALSO:

Module
Procedure

which
An executable program consists of one or more object modules
e by
retabl
interp
be
to
way
a
such
in
have been combined and formatted
an operating system and its hardware.

The following general rules govern the division of program information
into modules:

o
o

There is exactly one module within the

program,

termed

main module, where execution of the program begins.

the

If need be, any storage that is referenced by more than one
module (i.e., global storage) is declared in one or more
modules whose sole purpose 1is to declare/allocate global
storage.

that
Separate program operations are divided 1into modules lity.
capabi
single
a
to
d
contain all of the routines relate
output
Examples

are

generation,

Module

size

incremental

symbol

and so on.

1is

kept

table

moderate

modification

and

management,
to

order

binary

facilitate

keep the system resources

needed for compilation within reasonable limits.

o
o

When in doubt, place each routine in a separate module.
Even the main routine is CALLed by an outer environment.
Typically this environment is the command interpretter.

Commenting
ROUTINE:

6.27

The

the

Conventions

28-Feb-77

ROUTINE:

Rev

External

view,

a
be

uniform

functional

the

routine

high-level

1in

dccumentation

appearance:

"large

function.

1invoked

precisely

with

From

any

the

other

way

being

given

fail

for

behavior

a
and/or

file
protection

either

reason.

specifies

valid

the

The

routine

completion

name

parameter,

the

specified

routine's

<case

codes

that

may

The routine's execution
may
effects
that
are
not
evident
from
interface.
Such side effects are documented

process

file

include

read

the

(an

which
<code).

reading

the
WHAT

routine

code

effects

explain

the

The

routine's

preface

Overview

REMEMBEkK:

precise

preface

determine

dependent

well

file.

on
It

the
may

have

functional

its

invocation

the

storage

routine's

allocation,

signals.

the

manner

provides

how

CALLed

all

routine

the

being

execution
and
that

prefaces

they

can

in
the
Program
should rigorously
be
processed
to

which specifies how
RESPONSIBILITY to invoke
expects to
be
invoked!

esoteric

accomplishes.

illustrated

routine

necessary

certain

would remain
unnoticed
from
functional
specification
should

routine

CALLER'S

which

exception

otherwise

1is
described
chapter.
All
adhere to the standard format,
so
compile technical documentation.

Structure

the

and

dependent
on
environmental

specification:
The short functional specification
incorporated
1in
the
routine preface should be sufficiently
logical and lucid to enable the casual reader to get
a fairly
accurate
1idea
of what the routine does.
This specification
should NOT describe HOW the algorithm operates;
for that one

can

called!

changes

operations,

Functional

elusive

The

status,

would

has

returned.

effects:

This

preface specifies the
functional
failure:

side

preface.

point
of
performing

supplied
form
and
nature.
The
specifications
of
the

behavior:
The routine's
behavior
is
1its input parameter value(s) and possible
conditions.
For example, the routine OPEN FILE

Side

for

and

Runtime

existence

routine,

instruction,

predetermined

both

6-25

the external
instruction,

scale"

arguments of
a
predetermined
routine
preface
provides
exact
anticipated argquments.

Page

PREFACE

routine preface provides
following purposes:
o

PREFACE

called.

information

the

routine

needed

The
in

routine
order

Commenting Conventions

28-Feb-77 -- Rev 3

Page 6-26

SIDE EFFECTS

6.28

SIDE EFFECTS

SEE ALSO:

Implicit Inputs and Outputs

Signals

any functional side
This section of the routine preface describes tion
interface. This
effects that are not evident from its invoca
status, file
s
would include changes in storage allocation, proces
ng out of
anythi
here
nt
In general, docume
operations, and signals.
effect
its
If
nment.
the ordinary which the routine does to its enviro
as
them
nt
docume
ons,
is to modify own or global storage locati
implicit outputs rather than as side effects.

ADDITIONAL SPECIFICS TO BE SUPPLIED

Commenting

Conventions

28-Feb-77

-- Rev

Page

6-27

SIGNALS

6.29

ALSO:

SEE

Completion Codes
Condition Handler
Side Effects
UNWIND

The most reliable means for indicating a software
detected
exception
condition
occurring in a called procedure is for the called procedure
to return a completion code as a function value and for the caller
to
check
this
return
value
for
TRUE or FALSE.
If it is necessary to
indicate an exceptional situation
without
returning
a
value,
then
generate a CALL to LIBSSIGNAL to signal the exception.
See Appendix D
of the System Reference Manual for
details
on
signalling.
Current

practice
detected
When

1s
to
wuse
this
exceptions and for

language

standard
condition

contains

message

system

user

procedure
handlers.

handler

for indicating the occurrence
issuing system messages.

wishes

1issue

LIBSSIGNAL.
This
By convention, the

which

from

uses

the

system

signal,

calls

routine searches the
top
of
the
stack

condition
message

message to the standard output device.
the default action depending on bit <0>

value

file.

The
of

argqument
It

hardware

then

the

stack for
normally

retrieve

1ssues

the

default handler then takes
the
condition value.
If

the
bit
1s set (TRUE) then execution is continued following the call
to LIBSSIGNAL.
If
the
bit
1is
clear
(FALSE)
then
execution
1is
terminated
and
the <condition value
1is
available
to
the
command
processor to control execution of the command stream.
When

1t
to

a language or user
calls
the standard
W ew

LIBSSIGNAL

Thus, the
simple:
1.

except

rules

for

Normally

this

to
procedure

that

issue a signal and
never
LIB$STOP.
This routine is

execution

handling

never

exceptional

return

indicator
2.

wishes

a
completion
failure.

not

possible

the

normal

continue
low

order

after

addition,

and

signals

RI.
in

the

situation

execution,

cases

code

desirable,

bit

set.

message,

routine

Thus,
routine

after

then
1If

then

the

the
the

the

LIBSSIGNAL

1issuing

normal

preserves

possible

without

alterring

its

are

<caller

message

former if
and
the

the

message

value

should

bit

should

all

registers

insert

debugging

usage.

very

Call the
continue
continue.

situation

order

1is

procedure
.

1issue

condition

low

identical

continues.

calling
either
LIBS$SSIGNAL
or LIBSSTOP.
the signalling procedure can meaningfully
latter if the signalling procedure cannot
3.

continue,

1is

have

the

terminate
clear.

1including

tracing

Commenting Conventions

Page 6-28

28-Feb-77 -- Rev 3

VERSION NUMBER

6.30

VERSION NUMBER

SEE ALSO:

Configuration Statement

In the example of the configuration statement, the normal definition
library for this compilation is assumed to contain a dummy macro named
The
$FAC_CHANGE_DEF which can be superseded by a user supplied one.

default

values are defined only if the symbols are not defined by the

time the macro has been expanded.

INCLUDE FILES:

WMo

“O

the equated symbols section:

This is done in the source file

EQUATED SYMBOLS:

wWO

SFAC_CHANGE_DEF

.IIF NDF DEF_LINES_PPAGE, DEF_LINES PPAGE=55
.IIF NDF MAX LINE WIDTH, MAX LINE WIDTH=132

Assembler Formatting and Usage
CONDITION HANDLER

7.4

28-Feb-77 -- Rev 3

Page 7-4

CONDITION HANDLER

SEE ALSO:
Completion Codes
Signal
UNWIND

the
For the primary purpose of handling hardware detected exceptions,
system supplies a mechanism for the programmer to specify a
vAX-11
This
function ¢to be called when an exception occurs.
handler
mechanism may also be used for software detected exceptions.

Each procedure activation has a condition handler potentially attached
1Initially, the longword
to it via a longword 1in its stack frame.
contains 0, indicating no handler. A handler is established by moving
the address of the handler's procedure entry point mask to the
establisher's stack frame.

In addition, the operating system provides two exception vectors at
These vectors are available to declare handlers
each access mode.
which take precedence over any handlers declared at the procedure
These are used, for example, to allow a debugger to monitor
level.
all exceptions, whether or not handled. Since these handlers do not
obey the procedure nesting rules, they should not be used by procedure
library code. Instead, the stack based declaration should be used.
When a condition handler gets control, it is given several

arguments.

One of these indicates whether the exception occurred in “this”
handler's establisher or in a descendant of it. Another argument is
the specific condition which occurred. This is in the same form as a
completion code and bits <31:3> identify the specific condition.
For further details, see Appendix D of the System Reference Manual.
It describes in detail when the handler is called and what its formal
parameters are. In addition, the options of the handler are detailed.

Pormatting and Usage
DECLARATION: EQUATED SYMBOLS

28-Feb-77

Assembler

7.5

DECLARATION:

SEE ALSO:

Label:

Local

Procedure:

Entry

Relative Addressing

Symbol

A label is a symbol which names a statement.
by a colon.

The label

1is

delimited

A label should be meaningful in that it
should
convey
information about the purpose of the block it precedes.

some

Left align all labels in column one of the source text.

on
not
A label should be placed on a line of its own (i.e.,
same
line
as the labelled item), and be commented unless it
1logical
the
explain
should
The comment
is a local label.
execution
circumstances
what
under
and
label,
the
of
meaning
reaches the label.

labels,
(synonymous)
A statement may sometimes have several
subsequent lines, and
on
placed
are
they
case
which
in
generally
1is
practice
This
NOTE:
commented individually.
Generally, each item in the program should have
discouraged.
Only in rare cases will a single item
at most a SINGLE name.
justifiably require several names, such as when two distinct
functions have been combined.

The labelled statement is placed on the immediately following
line.

Example:

A LABEL:

STATEMENT

ANOTHER_LABEL:
SYNONYMOUS LABEL:
STATEMENT

;Result is Negative

:Statement's Comment

:Used if GEN SWITCH = OFF
:Used if GEN SWITCH = ON
:Statement's Comment

Assembler Formatting
LABEL: GLOBAL

7.14

SEE

LABEL:

and

Usage

28-Feb-77

Rev

Page

7-11

GLOBAL

ALSO:

Declaration:
Equated
Symbol:
Global

Symbols

A global label is declared
or in an entry operator.

by means of

the double colon

"::"

Example:
PRINT::

+.WORD

;Global

M<register

list>

;Register

routine

save mask

.ENTRY

PRINT, "M<register

list>

;Global print routine

operator

Assembler Formatting and Usage
LABEL:

LOCAL

7.15

LABEL:

SEE

Page 7-12

28-Feb-77 -- Rev 3

LOCAL

ALSO:

.ENABL/.DSABL

LSB:

1is a
"n"
The local label is a special purpose construct "n$:" where
The value of an explicitly stated "n" may be in the
decimal constant.
Local labels have a
(decimal).
range of integers 1 through 65535
limited

scope

of reference defined by

by an explicit local symbol block.

(non-local)

label brackets, or

The local label is left aligned in column one of
text, on the same line as its named statement.

Local labels serve as necessary

but

otherwise

the

source

mnemonically

meaningless statement identifiers within a block statement.

flow of
for
then
Local labels SHOULD NOT BE USED other
DO NOT use
identification within a block statement!
control
of
sequences
1logically unrelated
throughout
local labels
If need be, label block statements mnemonically
statements.
1local
following
in order to force a change of scope for the
labels.

Local labels need be unique only within their given scope;
local label's name may be reused within a new scope.

from "10§:"
Always number your local 1labels sequentially,
appearance.
of
order
the
in
10
of
increments
upwards by

When inserting a new local label between two existing ones,
give it a number within the range of the two existing labels:
Dbetween
"17$:"
“20$:",
and
"10$:"
between
insert "15$:"
"15$:"

and

"20$:".

and
The numbers should be multiples of ten at first release,
should be renumbered on any release which makes extensive
renumbered in the course of
They should not be
changes.

maintenance patches or updates.

Assembler
LABEL:

Example

Formatting

and Usage

28-Feb-77

Page

7-13

(correct):
label

scope

;Begin

local

label

scope

e
-e

LABEL2:
STATEMENT
10S:

LABEL1l:
50S:
STATEMENT
60S:

local

wWme

STATEMENT
STATEMENT

Example

;Begin
WO

STATEMENT

30S:
120$:

Rev

LOCAL

LABEL1:

10S:
20S:

(incorrect):
;Begin local label scope
;First label not "10S:"
;Free standing local label

STATEMENT

’

STATEMENT
STATEMENT

;Decreasing label
;Increment larger

number
than 10

Assembler

Formatting

and Usage

LIBRARIES

7.16

LIBRARIES

SPECIFICS TO BE

7.17

LISTING CONTROL

SPECIFICS TO BE

7.18

LSB:

SEE

Local

SUPPLIED

MACROS

SPECIFICS

7.21

Stack

.ENABL/.DSABL

SPECIFICS TO BE

7.20

SUPPLIED

SLOCAL MACRO

SEE Variables:

7.19

SUPPLIED

SOWN

SUPPLIED

MACRO

ALSO:

Structures

SPECIFICS

SUPPLIED

28-Feb-77

Rev

Page

7-14

Assembler Formatting
PARAMETERS: FORMAL

7.22

PARAMETERS:

ALSO:
Implicit

and

Usage

28-Feb-77

Rev

Page

7-15

FORMAL

SEE

Inputs

Parameters:

and

1Input

Outputs
and

Output

Procedure

Routine:

Preface

Structures

Variables:
The

VAX-11l

provision
of

procedure's

because

they

chooses

The

a
built-in
call/return
argument passing.
The caller

called

one-to-one

caller,
but

has

automatic

arguments.

own,

Local

hardware

for

correspond
The

Stack

the

parameters

moment

have

procedure

caller's

will

identity
identity

The

argument list
pointer
caller-supplied
argument

The

definition of
routine preface:
SFORMAL

PAR1, PAR2,

PARN>

offset

symbolic

parameters

with

list
which

bound with the
arguments
of
each
They are known as "formal parameters"
(i.e., specific memory address) on their

whatever

always

1list.

The

accessed as 1*4(AP), and the Nth
as
those
arguments
absolutely,
define
symbolically equated

arguments.

specifies

call.

the
supply.

assume

expects

mechanism

relative
formal

arguments

points

first

the

caller

at
the
base
of
the
argument list element is

N*4(AP).
Rather
each
procedure
to AP.

parameters

present

made

than
address
parameter as a

the

end

the

;
;PARl.at.mf

symbolic

name

;PAR2.at.mf

symbolic

name

;PARn.at.mf

symbolic

name

where the .at.mf specifies the access type, the data type, the passing
mechanism,
and
the passing format.
See the Functional and Interface
Specifications chapter for more details.

Assembler

Formatting

PARAMETERS:

the

and

body

the

procedure,

symbolically:
o

Call

Usage

you

refer

now

Rev

reference:

the

form

refer to the value
@PARn(AP).
Refer
to
the form PARn (AP).

parameter

Call

the

form

refer to
PARn(AP).
You

value:

to the parameter's
read only.
o

28-Feb-77

FORMAL

Page

the

Nth
ADDRESS

Call

by descriptor:
the descriptor is referenced as
reference.
The
structure typically has a more
referencing algorithm.

Giving
the
advantages:

formal

parameters

symbolic

The code is
readable.
The
meaningful than the notation

happens

changed,
N+Ith

revised;
preface's

reflected
The

that

the
any

the

names

notation
@12 (AP).

Nth

has

the

@FILNAM(AP)

in
call
specific

following

procedure's

wused

such modification is made
documenting
comment
and
is
in the module's documentation.

symbols

the

interface
has
to
be
to
be the Nth argument now is the
the parameter
definitions
have
to
be
referencing
code
1itself remains unaffected.

and
what
argument, only

Moreover,

parameter

the value of the
Nth
parameter
by
cannot make any meaningful reference
address.
Warning:
the arqument
1list
is

parameters

the

7-16

appear

cross

reference

within

thus

listing.

the
routine
automatically

Assembler

Formatting

and

Usage

28-Feb-77

Rev

Page

7-17

PROCEDURE

7.23
SEE

PROCEDURE
ALSO:

Parameters:

Routine:

Multiple
non-standard
Order

Routine:
Routine:
The

Formal

Entry:

procedure

code,

or
procedure

body of

recursively

has

certain

code

that

itself,
functional

through

CALLed by some other
body
of
perform a certain function.
The
behavior which
may
be
controlled
to

caller
supplied
arguments.
To the procedure, the caller's
arguments are locally known as formal parameters;
the procedure
does
not have to know what the caller's arquments' exact memory address is.
VAX-11

provides one calling mechanism supported
The
choice
of
the
instruction
1is
strictly
callee always uses AP to reference arguments:

In
it

two
instructions.
to the caller.
The

The CALLG instruction where
caller supplied area, and

the

arqument

iist

The

CALLS

the

argument

onto

the

list

has

instruction
stack

where

the

caller,

immediately

prior

either

case, the argqument list itself is read only.
normally
consists
of an array of pointers to the
variables.
This is NOT mandated by the machine!
The
may well contain the values of the arquments.

stored

been

pushed

the

call.

By convention,
actual argument
argument
list

According to these conventions, all argument lists by default
contain pointers to the argument variables (known as "call by
reference").

If a procedure is
called
with
value"),
then this fact must be
procedure preface,
in
form
of
Parameters:
Formal).

The procedure
permanently

allocation)

variables).
procedure,
procedure.

utilization,
and

allows
importantly,

and

the

that

The
in

use
the

may have local
allocated
in

argument
values
("call
by
prominently displayed in the
a
specific
notation
(see

variables.
Such
memory
(as
a

variables may
.BLKB,
.BLKW

they may be allocated on the
stack
Stack
local variables are allocated
and
de-allocated
automatically
upon

(see
stack
1local
upon entry into the
return
from
the

the

procedure

stack
of
to

locals

are

truly

called

local

recursively.

Even

the

activation

procedure

their values getting clobbered, by
the procedure, is extremely low.

some

of stack locals is recommended.
Note that registers
category
of
stack
1local variables, assuming that

either
.BLKL

The
wuse of stack locals results in more efficient memory
better working set behavior in
the
paging
environment,

chance
external

specified

be
or

saved

the

procedure's

entry

mask.

other

code

are
they

also
were
the

general,

Assembler

Formatting and Usage

28-Feb-77 =-- Rev 3

Page 7-18

PROCEDURE

only
non-stack
variables to be used by a procedure are the variables
corresponding
to
some
permanent
database
that
the
procedure
1is
responsible for maintaining.
As a rule, any variable whose value MUST
be remembered across procedure call/returns is permanently
allocated;
all other variables are temporaries and should be stack resident.

Assembler
PROCEDURE:

7.24

Formatting

and

Usage

28-Feb-77

Rev

Page

7-19

ENTRY

PROCEDURE:

ALSO:
Routine:

ENTRY

SEE

Entry:

Multiple

The procedure entry consists of the procedure name label, and
of
the
procedure entry mask.
The first word of a procedure that is called by
either CALLG
or
CALLS
1s
interpreted
by
the
hardware
to
be
a
register-save
mask.
The mask, which is a word (=2 bytes), specifies
those registers that are to be saved by
the
calling
mechanism.
It
also specifies the integer and decimal overflow enables.
You have to specify
registers
used
by
preserved

Use

the

and

those
your

restored

"M operator

registers
procedure,

upon

explicitly.
You
specify
the
so
that
their
values will be

return.

specify the

list of

ROUTNAME :

registers
;Name

.WORD

"M<R2,R3,R4,R10>

.ENTRY

GLOBAL_ROUTNAME, "M<R2,R3,R4,R10>

;Save

four

to be
the

saved:

procedure

registers

NOTE:

Whenever

you

modify

masks

may

Being

cause

overzealous

bugs

in
which

;Save

four

registers

existing

program,

and

decide

that

specified

the

specifying "efficient"
register
are
extremely difficult to find;

use

1in

save
not

necessarily in YOUR procedure, but rather in the procedure that CALLed
That
calling
procedure
may
be from the library, and the bug
symptom may be extremely horrible and
impossible
to
trace
to
YOUR
procedure which caused the bug by clobbering the caller's register(s).
you.

If your
specify

procedure invokes a
all registers used

non-standard routine your entry mask
by that routine (even if that routine

a PUSHR).
This is necessary to allow for the
case
of
a
exception being generated and a condition handler UNWINDing
(See Condtion Handler, Signal, and UNWIND.)

must
does

signal
or
the stack.

Assembler

Formatting

.PSECT

STATEMENT

7.25

..PSECT

and

Usage

28~ Feb-77

Rev

Page

PSECTs have

the

following

Code

PIC

USR CON

REL

LCL

attributes.

EXE
SHR
SHR NOEXE

NOWRT Align (2)

NOSHR NOEXE
LCL NOSHR NOEXE

RD
RD

WRT Align(2)
WRT Align(2)

Literals NOPIC USR CON REL LCL
LCL

NOPIC USR CON
NOPIC USR CON REL
NOPIC USR OVR REL GBL NOSHR NOEXE RD
REL

Since the assembler defaults attributes,
are sufficient and hence preferred:
.PSECT
. PSECT
.PSECT
.PSECT

Code
Literals
Own/Global
Common

the

WRT Align(2)

following

declarations

name,PIC,SHR,NOWRT,
LONG
name,SHR,NOEXE
,NOWRT , LONG

name ,NOEXE,
LONG
name ,OVR,GBL ,NOEXE, LONG

Subsequent references to the PSECT should give just the name
attributes.

7.26

QUEUE

7-20

STATEMENT

Typically,

Own
Global
Common

INSTRUCTIONS

SEE ALSO:

Synchronization:

SPECIFICS TO BE

Process

SUPPLIED

with

Assembler
RELATIVE

7.27
SEE

Formatting

and

Usage

28-Feb-77

Rev

ADDRESSING

RELATIVE

Page

7-21

the

form

ADDRESSING

ALSO:

Expressions

The

assembler

allows

the

"SYMB+OFFSET".

The

current

counter

location

formulation of

assembler

also

value dot

relative

allows

addresses

reference

made

its

(".").

Under NO CIRCUMSTANCES is it allowed to
references within the executable code.

make
Code

relative address
of the form:

.+4

:This

NO-NO

JMP

LABEL-23

;This

NO-NO

or,

ABSOLUTELY NOT TOLERATED!

Relative addressing, including
dot-relative
addressing,
is
useful
--and sometimes necessary-- in the definition of data
structures or in the declaration of tables.
See expressions,
formal parameters and stack local variables for examples.

Assembler Formatting and Usage
ROUTINE:

7.28

Page 7-22

28-Feb-77 -- Rev 3

BODY

ROUTINE:

BODY

SEE ALSO:
Block
Comment:
Procedure
Block
Statement:

The
routine's
body
consists
of
the
sequence
of
instructions
representing
the
function
performed
by that routine.
The sequence
should be decomposed into major groups
of
instructions,
where
each
group performs
a well defined logical operation.
Each such group is
known as a block statement, and is preceded by its block comment.
It
should be possible to get a fairly complete knowledge of the routine's
logic from simply reading the block comments.

Block statements
must
naturally
must go down the
where an upwards

appear in a logical sequence.
The
routine's
1logic
flow in a top-down sequence.
All jumps (or branches)
page!
The only exception is in the case
of
1loops,
jump is necessary.

NO SPAGHETTI-BALL CODE

IS TO BE TOLERATED!

Note that most loops have their "end" test at the beginning.
This
|is
no
exception
to the above rule in that the loop label is at the top,
then the end test including the branch to
the
followed by the branch back around the loop.

exit,

then

the

body

In general, a routine will not have a
common
exit
point
because
a
single
RSB or RET instruction performs the return.
However, if there
is common code in several paths just before
return,
this
should
be
combined as one exit sequence located at the end of the routine.

Assembler
ROUTINE:

7.29

Formatting
ENTRY:

ROUTINE:

routine may

and

Usage

28-Feb-77

ENTRY:

Two

have

same

several

For

a
o

entry

outwardly

algorithm
example,

OCTAL,

Rev

and

the

DECIMAL

common

Page

points,

for

different

have

routines

and

interface

an
to

differ

routines

convert

the

identical

binary

character

only by

following

effectively

otherwise

HEXADECIMAL

and

either

use

value

the
line without a terminating
the line and issues a <newline>.

In either case, each entry
routine
header.
Define
(setting
a
non-uniform

conversion

radix.

flag

and/or

<newline>,

the

is
to
be
documented
with
a
full
entry point, do some setup computation
copying
the
arguments
in
the
case
of

clarity's

sake.

transfer

routine

to
a common
headers
were

label.

1In
ommitted

binary

octal

conversion

entry

BIN_TO_OCT, M<register

list>

Example:

The

.ENTRY
MOVL

#8 ,RADIX

;Set

common

;Binary

to octal

radix

wpe

{separator>

binary

to decimal

conversion

entry

The

-ENTRY
MOVL
BR

BIN TO DEC, M<register

list>

$#10,RADIX

;Set

common

;Binary

to decimal

radix

{separator>

Binary

hexadecimal

conversion

entry

“e

The

-ENTRY

BIN_TO_HEX, M<register

MOVL

#16 ,RADIX

{separator>

second

the

following

have

point

parameters),
then
example, the mandatory

into

representations

the

interface.

A single function may have two or more variants necessit
ating
different
interfaces.
Por example, both PRINT and PRINT NL
are entries to the routine that prints
a
1line.
The
first

prints
prints

COMMON :

7-23

MULTIPLE

reasons:

MULTIPLE

list>
;Set

;Binary

radix

;Common

hex

conversion

code

the
for

Assembler
ROUTINE:

7.30

Formatting and Usage

28-Feb-77 -- Rev 3

Page 7-24

NON-STANDARD

ROUTINE:

SEE ALSO:

.VALIDATE Declaration
.WEAK Declaration

A global symbol is defined by means of the double colon "::" for label
symbols, and by means of the double equate "==" for equated symbols.
Example:

SWITCH::

TRUE==

7.40
SEE

Instructions

.TITLE

SUPPLIED

STATEMENT

ALSO:

Module:

The

PROCESS

ALSO:

SPECIFICS TO BE

SEE

;Global value TRUE

SYNCHRONIZATION:

QUEUE

7.41

;Global variable SWITCH

.BLKW

Preface

.TITLE statement is the very first statement of the

module.

Its

operand is the module name. Any text following the module name is
The text following the
used in the header of the object code listing.

module name should be a terse functional description of the module.
Example:

.TITLE

FILE MGR - The STARLET file manager subsystem

Assembler Formatting and Usage

28-Feb-77 -- Rev 3

Page 7-32

UNWIND

7.42

UNWIND

SEE ALSO:

Condition Handler
Signal

If a condition handler gets control, it has several options over the
flow of control. It can resignal the condition for another handler to
take control, or it can signal a distinct condition for the same
Alternatively, it can continue from the signal. The final
purpose.
option is to terminate the procedures in progress, unwind the stack,
and branch to a specific recovery address. This would be done when
the current operation is to be aborted, but the program is not to Dbe
terminated.

When an unwind is requested, each stack frame is examined in order to
Before
restore all the saved registers and Program Status Word (PSW).«condit
ion
a
if
each stack frame is removed, it is examined to see
first.
called
is
I1f so, the handler
handler has been established.
This allows a procedure to gain control if it is aborted or 1if any
routine below it aborts. This might be used, for example, to release
any resources such as dynamic storage which the routine might have
acquired.

7.43

.VALIDATE DECLARATION

SEE ALSO:

External
Symbol:
Global
Symbol:
.WEAK Declaration

symbol which
This is used in addition to a global declaration for any
l modules.
is made global only to validate consistency across severa
For example, if two modules assume that the length of a particular
structure is 47, then both might declare
.VALIDATE STR_LEN
STR_LEN==47

are the
This would cause the LINKER to validate that both declarations
e
any
The .VALIDATE declaration should not be made if mark routin
same.
global
to
references STR LEN as an external. It is used only

definitions whose purpose is totally redundant.

VARIABLES:

STACK LOCAL

VARIABLES: STACK LOCAL

7.44
SEE

Pagqe 7-33

28-Feb-77 == Rev 3

Assembler Formatting and Usage

ALSO:

Exoressions

Formal

Parameters:
Structures

(the

(=} |94

o
L=

wor

v
ay

be allocated starting with

va'fi - b 1l

\¥4

jo TR/,]

Stack local variables are allocated at the base of the procedure's
stack frame, and given symbolic names that are offsets relative to the
orocedure's stack frame pointer FP.
J

the

longword

following
g

l1lowin

that would be used by a PUSHL instruction).

FP
FI

To declare stack local variables, you have to:
and

(1)

Define their symbolic offset names,

(2)

explicitly allocate space for them on the stack.

Definition of stack local variables

-y

Symbolic definition is performed using the $LOCAL macro, as in:

<I1,8>,J,<K,2>,~
<B,1>>

SLOCAL

‘

;Quad
:Long
;Word
:Byte

variable
variable
variable
variable

I
J
K
B

The routine entry point

The actual allocation is performed using a SUBLZ2 instruction, as in:

ROUTNAME:
.WORD

SUBL2

“M<register list>

#SSLOCAL_SIZE,SP

;The routine's name

;Save mask

:Advance SP past allocation

whenever you want to reference one of the stack local variables, do so
by using its symbolic name VAR based on the contents of FP (e.qg.,
“"WAR(FP)").

MOVB
ADDL3

Such

as:

R7,B(FP)
1 (FP) ,4+1(FP),J(FP)

;Store byte in local B
:Add both halves of I into J

Compare the allocation of these 1local variables to the structure
definition shown in the structures section. Notice the difference
that is due to the stack's backwards growth.

Assembler

Formatting and Usage

.WEAK

DECLARATION

7.45

.WEAK DECLARATION

SEE

28-Feb-77 -- Rev 3

Page

7-34

ALSO:

‘The .WEAK declaration
can
be
made
on
either
external
or
global
definitions.
In
both cases its meaning is that the symbol should be
matched
by
the
LINKER
if
defined,
but
that
this
reference
or
definition should not force the loading of a library module.
When used on a global declaration, then the definition of
the
symbol
in
this
module
1is
not sufficient to cause this module to be loaded
from a library.
Thus, it should be used for any
subordinate
symbols
defined in a library module.

—

——

——r

—

——

—

——

.VALIDATE Declaration

When used on an external, then the reference to this symbol
will
not
cause
it
to
be defined by loading a library module.
1If some module
which is loaded defines the symbol, then it will be defined
for
this
reference.
If
nothing
defines
the
symbol,
it
1is
automatically
satisfied as defined as 0 without any error messages.
Thus, it can be
used
to
establish
a pointer to an optional module or data base.
If
the module is loaded, the pointer is defined.
Otherwise
the
pointer
has

value

(End of

Chapter

Digital

Equipment Corporation COMPANY CONFIDENTIAL

Title:

VAX-11

Software Eng.

Specification Status:

draft

Architectural Status:

under

File:
PDM

Date:

BASIC Formatting

-- Rev

Page

ECO control

SEBR3.RNO
not

used

23-Feb-77

Superseded Specs:

none

Author:

Typist:

Conklin

Reviewer (s):

Abstract:

Chapter 8 gives each piece
of
the
BASIC
usage conventions in detail.
The items are
order.
gives

Each item includes references
to
the
background
and
the
rules,

templates

Revision

Rev #

and

formatting

and

in alphabetical

SEE ALSO:
Declaration:
Declaration:

FORMAT
FORWARD
MACRO

Declaration:
Routine

We group the BLISS declarations as follows:
1.

FORWARD declarations

REQUIRE declarations

All other declarations

ROUTINE declarations

The first, second and
The third
sections.
STRUCTURES, LITERALS,
routine-wide scope,

fourth groups are discussed in their own
group 1lumps all other declarations (e.g.,
MACROS, etc.), which have module-wide or

into one major group.

The ordering of the different declarations within this third group
important and is based on the following rules:

1is

Group logically related declarations together. For example,
a specific structure may be used in conjunction with certailn
macros. These declarations would then appear together as a
group.

As much as possible, these logical groups will appear in

the

Separate the logical groups from each other

use

specific
Within a 1logical group of declarations group
will
MACROS
all
,
example
For
declarations together by type.

order of their use within the module or routine.
appropriate

the

separators.

be defined via one or more MACRO declarations.

A word of caution: Owing to the nature of the BLISS language, it 1s
necessary to declare all variables, structures, routines, etc. before
they are used. Care should be taken so as not to use something before
it is declared.

1In any event, the compiler will complain.

Bliss

Formating

EXPRESSION

9.6

and

Usage

21-Feb-77

Page

9-5

EXPRESSION

SEE:

9.7

Expression:

Assignment

Expression:

CASE

Expression:
Expression:

Block

Format

Expression:

IF/THEN/ELSE

Expression:

INCR/DECR

Expression:

SELECT

Expression:

WHILE/UNTIL/DO

EXPRESSION:

ASSIGNMENT

Assignment

expressions
name

The

following
o

Examples

rules

are

usually of

the

form:

expression

apply

assignment

expressions:

If the entire assignment expression will
not fit on one
line
because
of
its length then place the variable and the
equal
sign on one line and continue
the
expression
indented
one
logical tab on the next line.
'

(correct):
name

a-short-expression:

(Note

=
name

name

the

space

before

sign.,)

and

after

a-short-expression:

a-long-long-long-long-expression;

comment

the

comment

long

this

long

comment

for

expression

EXPRESSION:

9.8

Page 9-6

21-Feb-77

Bliss Formating and Usage
CASE

EXPRESSION:

CASE

according

set

CASE expressions are

the

following

skeletal

example:

CASE

1index

FROM low-case TO high-case OF
SET

case-label-action:

case-label-action;

case-label-action;
TES

where case-label-action 1is:
[case-label]:
!

Explanatory

for

this

comments

case.

case-action;
or

[case-label]:

The

following

case-action;

rules apply to CASE expressions:

The body of the CASE expression is indented one
with

comment

respect

the

keyword CASE.

1logical

from

tab

separated
is
case-label-action
Each
case-label-action by at least one blank line.

dependent
1is
The choice of format for the case-label-action
A
case-action.
the
of
expressions)
of
(number
size
the
on
a
small
format;
first
the
wuse
will
case-action
large
case-action

o
o

the

second

another

format.

Each of the case-actions follows

the

rules

for

expression

formatting.

It is desirable that the

case-label

descriptive

and

A
value.
1its
to
bound
been
has
that
name
meaningful
reader
case-label then becomes a
label
or
signal
to
the
indicating what value caused this case-action to be used.

Bliss

Formating

EXPRESSION:

9.9

EXPRESSION:

block

into

following
0

The

Usage

21-Feb-77

Page

provides

single

rules
block

apply

for

expression
expressions

The

expression

block

Constituent

means

structural

successor

indented

9-7

BLOCK

expression

expressions
The

and

BLOCK

BLOCK
is

same

grouping

level

and/or

expressions:

separated

declarations

entity.

(and/or

declarations

the

and

from

comments)

preceded

its
by

predecessor
a

blank

block

and

line.

comment.

expressions
of
a
block
the BEGIN-END delimiters.

In a block expression, the last expression in
the
block
followed by a ";" unless the value of the block expressi
on
actually used in an enclosing expression.

are

EXPRESSION:

9.10

FORMAT

EXPRESSION:

Specific

FORMAT

formatting

expression.

Page 9-8

21-Feb-77

Bliss Formating and Usage

rules

In general,

apply

for

each

kind

the following rules apply:

Expressions generally appear

Expressions are

left

justified

separate

lines.

current

the

executable

indentation

level.

Expressions which

fit

on one

line may appear

on one

line.

Expression subparts, when indented, are indented one
logical
tab
to
the
right of the start of the expression.
Specific
indentation rules are given in the appropriate sections.
Compound-expressions consisting of more
than
one
1line
are
bounded by BEGIN-END delimiters rather than by parentheses.

In general,

for arithmetic expressions:

Place one

space around

the binary

"+"

Place one

space before

the

unary

Place no

spaces around

the

"*"

In lists, place one space before the
after each "," and the ")".

"+"

and

and
and

"-".
"-".

"/" operators.
"("

and

one

space

Bliss Formating and Usage
EXPRESSION:

9.11

21-Feb-177

IF/THEN/ELSE

EXPRESSION:

expressions

Page

9-9

placed

IF/THEN/ELSE

are written
IF

test

in either

THEN

two

consequence

formats:

ELSE

alternative

THEN
consequence

ELSE

alternative;
[ X R “3

one
o

If the
one of

the

first

line

case,

only

the

entire

expression

fits

may

one

Otherwise,

the second format is used.
The
alternative
expressions
are
indented
one
respect to the keyword IF.

test is a compound test
the following manners:
IF

test

AND

then

test

AND

the

IF expression

line.

consequence

logical

1is

and
tab with

written

test

THEN
consequence

ELSE

alternative
or

test

AND

test

AND

test

THEN
consequence

ELSE

alternative
o

The
one

first
line.

format is used when the compound
Otherwise, the second format is

test
used.

can

fit

21-Feb-77

Bliss Formating and Usage
EXPRESSION:

9.12

Page

9-10

INCR/DECR

EXPRESSION:

INCR/DECR

INCR/DECR expressions are written according to one

the

following

formats:

INCR

loop-index

FROM

first

last

step

loop-body;
or

INCR

loop-index
FROM first TO
loop-body;

last

step DO

The following rules apply to INCR/DECR expressions:
o

Use the first format when the FROM-TO-BY expression will
on one line.
Otherwise, use the second format.

fit

The

the

loop-body

keyword

indented one logical

INCR/DECR.

tab with respect

Bliss

Formating

EXPRESSION:

9.13

and

EXPRESSION:

SELECT

Usage

21-Feb-77

Page

SELECT

expressions

9-11

SELECT
are

set

example:
SELECT

according

select-index

the

following

skeletal

SET

select-label-action;

select-label-action;
TES

where

select-label-action

is:

[select-label]:
!

Explanatory

for

this

comments

select-label.

select-action
or

The

following
o

rules

[select-label]:

select-action;

apply

expressions:

The body of the
with respect to
Each

SELECT

the

expression is
keyword SELECT.

of the select-label-action
least one blank line.

indented

expressions

comment

one

logical

tab

separated

choice
of
format
for
the
select-label-actions
is
dependent
on
the
size
(number
of
expressions)
of
the
select-action.
A large
select-action
will
use
the
first
format;
a small select-action the second format.

It is desirable that the select-label be
a
descriptive
and
meaningful
name
that
has
been
bound
to
its
value.
A
select-label then becomes a label or
signal
to
the
reader
indicating
what condition or value caused this select-actio
n
to be SELECTed.

The

Bliss Formating and Usage

EXPRESSION: WHILE/UNTIL/DO

9.14

21-Feb-77

Page 9-12

EXPRESSION: WHILE/UNTIL/DO

WHILE/UNTIL/DO expressions are written in the following manner:
WHILE test DO
loop-body;
or

loop-body

WHILE

test;

The following rules apply to WHILE/UNTIL/DO expressions:
o The keyword WHILE or UNTIL 1is aligned with

the

cutrent

indentation level.

the
The loop-body is indented one logical tab with respect to sion
expres
for
rules
the
s
follow
and
keyword WHILE or UNTIL
formatting.

Bliss Formating and
IDENT MODULE SWITCH

9.15

The

1IDENT MODULE

IDENT

switch

the

module.

9.16

LABELS

module's

label

names.
The

9.17

Usage

21-Feb-77

has,

1ts

parameter,

is delimited
rules

hence

it must

conform

by a colon

apply

current

version

to the

the

number

last entry

rules

for

in the

constructing

":".

labels:

Labels, when used, appear alone
which
they
refer
follows
on
logical tab with respect to the

A label is meaningful
information about the

MODULE:

the

corresponds

ABBREVIATED HISTORY.

following

9-13

SWITCH

This version number

name,

Page

in
the
block it

on
a
line.
The
block
the
next
1line indented
label.

sense
that
it
is labelling.

conveys

to
one

some

SWITCHES

Module switches
apoear
in
the
module
declaration
and
allow
the
programmer to provide information about the module and to control some
aspects of
the
compiler's
treatment
of
the
module.
Of
special
importance
1s the IDENT switch (see IDENT Module Switch) and the MAIN
switch which specifies which routine is to be used
to
begin
program
execution.
o

Each module switch will
IDENT
switch is first,
switches follow.

appear on
a
1line
the MAIN switch is

by
itself.
second;
any

The
other

Bliss Formating and
MODULE: SWITCHES

Example

Usage

21-Feb-77

Page

(correct):
MODULE

EXAMPLE

(

)

IDENT

‘03!,

MAIN

BEGINHERE,

RESERVE

(RO,

Rl)

9-14

Bliss

Formating

and

Usage

21-Feb-77

Page

9-15

NAME

9.18

A name

consists

of one

fifteen

ABCDE...

abcde

underline

dollar

...

characters

following
o

the

sets:

23456728239

" "

"§"

No distinction is made between upper and
string literals.
Thus, Date
Of Birth is
The

from

rules

apply

names:

Freely use the
wunderline
"
improve
readability
and
WRITEARECORD

becomes

when
constructing
comprehension.
For

names
to
example:

WRITE
A RECORD.

The ability of a programmer
symbol
simply
by
virtue
characteristic.
Predefined and
only for their

lowercase letters
except
1in
equivalent to date
of birth.

to
of

infer
1its

various
name is

syntactically meaningful
intended purpose.

names

attributes of
a
a very desirable

are

used

Bliss Formating and Usage
REQUIRE FILES

9.19

21-Feb-177

Page 9-16

REQUIRE FILES

place
one
The purpose of REQUIRE files is to centralize in
declarations and definitions that are common to multiple modules.
LITERAL
and
declarations,
MACRO
Data STRUCTURE declarations,
files.
declarations are the principal contents of REQUIRE
REQUIRE files consist of the following:
file-name - description

A copyright statement and disclaimer.

A MODULE PREFACE.

The
file.
The text of the REQUIRE
formatting rules for declarations.

file-name ~ LAST LINE

text

conforms

the

Bliss

Formating

and

Usage

21-Feb-77

Page

9-17

ROUTINE

9.20
SE E:

Declaration: Order
Routine: Format
Routine: Name
Routine: Order
Routine: Preface

9. 21

The

ROUTINE:

following
o

The

All

FORMAT

rules

apply

routine

for

ROUTINE

declaration

formatting:
start

routine body is to be indented
right of the routine declaration.

other
1indentation
follows
and/or expression formats.

ROUTINE:

the

one

the

left

margin.

1logical

rules

tab

for

The

ROUTINE:
following
o

All

NAME

stated

ORDER
rules

routine

constitute
o

the

declaration

Global routine names should follow
the
naming
conventions
earlier.
Local routine names may be chosen at as desired.

9.23

apply

the

declarations

the

last

set

ordering

appear

routine

together

of declarations

Routines are ordered by their use.
calls routine "B" then routine "B"

declarations:
as

group

and

a module.

That is, if
routine
is declared after "A".

"A"

ROUTINE:

Page 9-18

21-Feb-77

Bliss Formating and Usage
ORDER

The
ordering
of
routines
1is
reflected
1in
declaration group appearing at the beginning of

Mutually recursive

routines are ordered

the
FORWARD
the module.

principle

entry

first.

9.24

DECLARATION

STRUCTURE:

SEE:

STRUCTURE:

Block

The format for the structure declaration is as follows:
STRUCTURE

structure-name

[access formal list;allocation formal list]=

[structure size]
structure body:;

The following rules apply to the structure declaration:
o

The
of

structure declaration

format generally conforms

that

macros

The

structure-name

indented one logical

The structure size and structure body

The structure body contains one expression.
The format rules
regarding
expressions
are
in
force
starting
with
the

tab.

logical

indicated

are

tab.

1indented

another

indentation level.

In the instance where the expression part of
the
structure
simple, it may be contained on one line as seen below:

body

STRUCTURE

BLOCK[O,P,S,E;N,UNIT
[N*UNIT]

$UPVAL]

(BLOCK+O*UNIT)<P,S,E>;

or, may be of such complexity as to require the use of most rules
formatting

expressions.

for

DECLARATION

STRUCTURE:

Page 9-19

21-Feb-77

Bliss Formating and Usage

STRUCTURE

VECTORICH[I;N,UNIT = $UPVAL]

[N*UNIT]

BEGIN
LOCAL

T=.1;

. T LSS

1 OR

.T GTR N

THEN

BEGIN

;
ERROR(.T)
T=1;
END;

VECTORICH +

(.T -

* UNIT

END;

9.25
SEE:

BLOCK

STRUCTURE:

Declaration

The structure called BLOCK is a predeclared structure which may be
used without an explicit declaration. If declared it would look as
follows:

STRUCTURE

BLOCK[O,P,S,E;N,UNIT = fUPVAL]
[N*UNIT]
(BLOCK + O

UNIT)<P,S,E>;

Consider the following example.
OWN

A
B
c

=
=
=

X:BLOCK[2];

.X[0,0,16,0];
.X[(0,16,16,0]
.X[1,0,32,0]

X is defined as a two word BLOCK whose first word has two fields, each
16 bits long and whose second word is a field 32 bits long. The above
assignment statements use the BLOCK definition to access each field.

Bliss

Formating

STRUCTURE:

and

Usage

21-Feb=-77

Page

BLOCK

9-20

NOTE

For
a
further
explination
structure
declaration
and
structures,
see
the
chapter

Structures

The

BLISS

access

programmer

BLOCK

using

the

BLISS

of
the
built-in
on
Data

Language

Guide.

strongly

urged to hide
the
"field macro" as follows:

4-tuple

used

¢to

MACRO
FIELD

ONE

0,0,16,0%,

FIELD_TWO

0,16,16,0%,

FIELD THREE = 1,0,32,0%;
the

access

QO
w P

Thus

the

BLOCK

.X[FIELD ONE];
.X[FIELD_TWO]
;
.X[FIELD THREE] ;

This achieves a greater degree
changes to the structure of X.
[end

becomes:

chapter

readibility

and

facititates

future

Digital

Equipment

Title:

VAX-1l1

Corporation COMPANY CONFIDENTIAL

Software

Eng.

Specification

Status:

draft

Architectural

Status:

under

File:

SElOR3.RNO

PDM

not

Date:

COBOL Formatting

Page

Rev

ECO control

used

23-Feb-77

Superseded

Specs:

Author:

Typist:

none

Conklin

Reviewer (s):

Abstract:

Chapter
usage

gives

conventions

each

piece

detail.

order.

Each

gives

item

the

background

templates

and

includes

examples.

the
The

COBOL

items

references

and

the

are

rules,

formatting
in

related
and

and

alphabetical

then

topics,
gives

Revision History:
Rev

Description

Author

Revised

Date

COBOL Formatting and Usage
Change History

Rev

to Rev
1.

Create

null

[End of SE10R3.RNO]

chapter.

23-Feb-77

Rev

Page

10-990

CHAPTER 10
COBOL

FORMATTING AND

23-Feb-77

This chapter contains detailed
and
1instruction
usage.
For
alphabetically by topic.
Each

topics.

Most

illustrating

the

entries

specific

also

Chapter

10]

information
on
formatting
standards,
ease
of
reference,
it
1is organized
topic includes
references
to
related

include

examples

topic.

THE

[End of

-- Rev

USAGE

CONTENTS

ARE

TBS

sample templates

Digital

Equipment

Title:

VAX-11

Specification

Corporation

Software

Status:

SEIll1R3.RNO

PDM

not

Date:

Fortran

CONFIDENTIAL

Formatting

Page

Rev

draft

Afchitectural Status:
File:

Eng.

COMPANY

under ECO control

used

23-Feb-77

Superseded

Specs:

none

Author:

Typist:

Conklin

Reviewer (s):

Abstract:

Chapter
usage

gives

conventions

order.

gives

Each

item

each

piece

detail.

includes

the
background
templates and examples.

Revision
Rev

the
The

Fortran
items

references

and

the

are

rules,

formatting
in

and

alphabetical

re lated
topics,
and
then
gives

History:
Description

Author

Revised

Date

Fortran Formatting and Usage
History

Change

Rev

to Rev
1.

Create

null

[End of SE11R3.RNO]

chapter.

23-Feb-77 -- Rev 3

Page 11-990

CHAPTER
FORTRAN

FORMATTING AND

This chapter contains detailed
and
instruction
usage.
For
alphabetically by topic.
Each

topics.

Most

illustrating

the

entries

specific

also

[End

Chapter

11]

USAGE

information
on
formatting
standards,
ease
of
reference,
it
1is organized
topic includes
references
to
related

include

topic.

THE

CONTENTS

examples

ARE

TBS

sample

templates

Digital Equipment Corporation COMPANY CONFIDENTIAL

Title:

draft

Architectural Status:

under ECO control

PDM

Date:

VAX-11 Software Engineering Naming Conventions =-- Rev 3

Specification Status:

File:

Page

SE12R3.RNO
not

used

28-Feb-77
.

VAYC

£3 4> |>4

A4\

’

ot o

SaNAd

Design

Nassi,

Document

Author:

Conklin,

Typist:

Conklin

Reviewer (s):

Abstract:

Gault

R. Brender, D. Cutler, R. Gourd, T. Hastings,

Tolman

Chapter 12 gives the system wide naming conventions for all

public
symbols.
These rules are to be followed by all DEC
appear
in
software for all symbols which
are
global
or
parameter definition files.
This chapter also includes the
list of all facility prefixes.

Revision History:

Rev #
Rev 1
Rev 2
Rev

Description
Original
Revised from Review
After 6 months experience

Author
S. Gault
S. Gault
P. Conklin

Revised Date
Oct-70
Jan-77
28-Feb-77

name

.PSECT

Bit
Bit

REF

name,

BLOCK

name
.

size
.

field
name

Call

non-standard

Code, condition
Completion code
Condition value
value

Constant
Data

type

.
.

.
12-7

name
.

.
.

Definition macro name,
Entry point
global . .

structure

Facility prefix table
Field offset name
.

Global entry point .
Global variable name

.
.

array name

Global

style

Interface

12-2

e
name
Module name

.
.

12-2
12-1
12-1
12-3
12-3

name

Macro

Mask

12-4
12-4

Name

.
.

private
public .
Name

pattern

Non--standard
Offset

call
.

name

Pattern
NAME

Prefix

.
.

12-1
12-7
12-2
12-1

name

12-4

name

12-2

12-7

o«

Private name
Public name
REF BLOCK
Register
SAVE

LService
Sign

facility

macro

out

Status

table,

code

12-3

12-2

String . . . . . .
Structure definition
Style of interface .

macro
.

name

12-6
12-4

12-7

Transportable
data

types

12-6

Page 12-990

28-Feb-77 -- Rev 3

Naming Conventions
Change History

Rev 2 to Rev 3:
Add table of prefixes.

Add reasons for the rules.

Add BLISS field extract macro names. Add .PSECT names.
non-CALL entry names. Change $C_ to $K_ for constants.

Add

Note

Add transportable data types of A, C,

and

of X and Y
reservations of I and R for specific purposes, use

for context dependent purposes, use of Z for unspecified or
nonstandard forms, use of N and P for decimal strings, and O
as a general escape valve.

Add all known facility prefixes.
Reserve data type J to customers.

Note reserved status codes<2:0>.
facility.

Note that <31:16>

Add facility codes to section 7.3.

indicate

Change non-call routine name pattern to agree with OTS.
Change BLISS field reference mnemonics. Reserve E to DEC.
10.

Clarify that numeric string is all byte forms.

11.

Add argument style column to facility table.

12.

Clarify that system macro names are general

and

don't

have

13.

Clarify that BLISS field names have offset,

position,

size,

14.

Clarify that

15.

Clarify that masks are not right justified.

16.

Add facility to structure def macros.

17.

Define sizes of transportable codes for reference.
to be good for counters (16 to 18 bits).

the facility name.
and sign.

assembler V symbols are within containing field.

18.

Add B32,
prefix.

FAB,

10, NAM, NET,

Remove CHF prefix.

PLI,

RAB,

RM,

19.

Ban local synonyms for public symbols.

20.

Move completion code description to chapter 6.

GSWP,

Change

TST,

XAB

Naming Conventions

Change History

28-Feb-77 -- Rev 3

Page

integer.

21.

Clarify that H

22.

Clarify that the N and P count is a digit count.

23.

Clarify private symbol

usage.

24.

Add

all

facility codes

[End of SE12R3.RNO]

12-991

for

procedure

library facilities.

CHAPTER
NAMING

CONVENTIONS

28-Feb~-77

Rev

The
conventions
described
1in
this
chapter
were
derived
to
implementors
in
producing meaningful public names.
Public names
all names which are global (known to the linker) or
which
appear
parameter

macro

definition

files

and

libraries

facility.

These public names
following reasons:
o)

By using
written

are

all

constrained

names reserved
software
will

to
not

DEC,
be

these

we
ensure
invalidated

in more

rules

aid
are
in

than one

for

the

that
customer
by
subsequent

By using definite patterns for different uses, we
allow
the
reader
to
judge
the
type of object being referenced.
For
example, the form of macro names is different
from
offsets,
which is different from status codes.
By using certain codes within a
size
of
an
object
with
1its
likelihood
that
the
reference
instructions.

pattern,
we
name.
This
will
use

associate
the
increases
the
the
correct

By using a facility code in symbol definitions, we
give
the
reader an indication of where the symbol is defined.
We also
allow separate groups of implementors to choose
names
which
will not conflict with one another.
Never

define

local

symbol
s hould
the reade r.

synonyms

wused

for
every

public

symbols.
reference to give

The
full
public
maximum clarity to

Naming Conventions

PUBLIC SYMBOL PATTERNS

12.1

Page 12-2

28-Feb-77 -- Rev 3

PUBLIC SYMBCL PATTERNS

rs and
All DEC public symbols contain a currency sign. Thus, custome
without
s
symbol
use
applications developers are strongly advised to
currency signs to avoid future conflicts.

tion as
Public symbols should be constructed to convey as much informa
follow
names
private
tly,
Frequen
name.
possible about the entity they
the
as
same
the
is
then
ion
convent
private
a similar convention; the
are
These
sign.
y
currenc
the
of
instead
ne
public one with an underli
y
used both within a module and globally between modules of a facilit
into
which is never in a library. All names which might ever be bound case
a user's program must follow the rules for public names; 1in thebe used
of undocumented names a double currency sign convention can
such as in 3 below.

Public names are of the following forms:
1.

Service macro names are of the form:
Smacroname

A trailing S or A distinguishes the stack and separate
These names appear 1in the system macro
arglist forms.
The
library and represet a call to one of many facilities.
name.
macro
the
in
appear
facility name usually does not

Facility specific public macro names are of the form:
$facility macroname

System macros which use local symbols or
ones of

macros

always

use

the form:

Sfacility$Smacroname

This is the form to be used for symbols generated by a macro
and used across calls to it and for internal macros which are
not documented.

Status codes and condition values are of the form:
facility$_status

See completion codes in the Commenting Conventions chapter.
5.

Global entry point names are of the form:
facilitySentryname

Naming
PUBLIC

Conventions
28-Feb-77
SYMBOL PATTERNS

Global entry
the form:

point

names

Rev

which

Page

have

non-standard

calls

12-3

are

facilitySentryname
Rn
where

registers RO to Rn are not preserved.
caller of such an entry point must include at
R2 through Rn in its own entry mask.

Global

variable

names

are

the

Note

that

least

the
registers

form:

facility$Gt variablename
The letter G
representing

section.

stands for global variable and the t
the type of the variable as defined

Addressable

letter

global arrays use the
and are of the form:

letter

is
in

(instead

a letter
the next

the

facilitySAt arrayname
The

letter

stands

for

global

array

letters
representing the type of
to the list in the next section.
In

the

assembler,

public

structure

and

the

1is

one

array element

offset

names

according

are

the

form:

structure$t

fieldname

The t is a letter representing
defined
1in the next section.
is the
byte
offset
to
the

the
The

data type of
value of the

start

the

the field
as
public symbol
datum

1in

the

offset

and

structure.

10.

the

single

assembler,

bit

names

public

are

structure

the

bit

field

form:

structure$V_fieldname
The value of the public symbol is
start
of
the
containing
field
control block).
In

the

assembler,

the

form:

public

structure

the
bit
offset
from
(not from the start of

bit

field

size

names

the
the

are

structure$S fieldname
The value
field.

the

public

symbol

the

number

bits

1in

the

Naming Conventions

PUBLIC SYMBOL PATTERNS

12.

Page 12-4

28-Feb-77 -- Rev 3

For BLISS, the functions of the symbols in the previous three
items are combined 1into a single name used to reference an
Names are of the form:
arbitrary datum.
structure$x fieldname

where x is t for standard sized data and x is V for arbitrary
The macro includes the offset, position,
and bit fields.
suitable for use in a REF BLOCK
extension
sign
and
size,
Most typically, this name is definable as
ctructure.
MACRO

structure$V _fieldname =
structure$t fieldname,

structure$V _fieldname,

!assembler meaning

strucutre$S fieldname,
<sign extension> §%;

13.

Public structure mask names are of the form:
structure$SM fieldname

The value of the public symbol is a mask with bits set for
each bit in the field. This mask is not right justified;
rather it has structure$V fieldname zero bits on the right.
14.

Public structure constant value names are of the form:
structure$K constantname

15.

.PSECT names are of the form:
facilityS$mnemonic

16.

Module names are of the form:
facilityS$mnemonic

The module is stored in a file with filename "mnemonic" in

directory corresponding to the facility.
17.

Public structure definition macro names are of the form:
$facility structureDEF

Invoking this macro defines all the structure$xxx symbols.
Example of

IOCS$SIODONE

usage:

Entry point of the routine IODONE in the 1/0 subsystem.

K Offset in the UCB structure to a byte datum containing
PRI
UCB$SB_FOR
the fork priority.

Naming

Conventions

PUBLIC

SYMBOL

28-Feb-77

Rev

Page

12-5

PATTERNS

UCBSL_STATUS

Offset

CRBSM BUSY

Mask

CRBS$V_BUSY

Bit

in the UCB
containing status
pattern

offset

for

the

structure
bits.
the

CRB

busy

bit

structure

longword

the

CRB

the

datum

structure.

busy

bit.

Naming Conventions

Page 12-6

28-Feb-77 -- Rev 3

OBJECT DATA TYPES

12.2

The following are the letters used for the various data types
reserved for the following purposes:

NKXYXESCHNIOITOYOZRCERUHKHIOTMMOMDO
XY

letter

data

type

are

usage

(*)
address
byte integer

(*)
single character
double precision floating
reserved

DEC

single precision floating
(%)
general value
(¥)
integer value for counters
reserved for integer extensions
reserved to customers for escape to other

codes

constant

longword integer
field mask

numeric string (all byte forms)
reserved to DEC as an escape to other
packed string
quadword integer
reserved for records
field size

codes

(structure)

text (character) string
smallest unit of addressable storage
(*)
field position (assembler); field reference

word

integer

context dependent
context dependent
unspecified or

and T strings are

(BLISS)

(generic)
(generic)

non-standard

typically

variable

1length.

Frequently

1in

structures or I/0 records they contain a byte-sized digit or character
count preceding the string.
If so, the location or offset is
to
the
count.
Counted strings cannot be passed in CALLs.
Instead, a string

descriptor

is generated.

* - The letters A, C, G, H, and U should be used in preference
to
L,
B,
L,
W,
and
B respectively when transportability is involved.
The following table defines their

sizes:

letter

A
C
G
H
U

16
8
16
16
8

32
8
32
16
8

18
7
36
18
36

— —— — — —— — — — i o—— — — — — — —— — T S——— ——— — — T

. — ———— — — — — ——— — — — — — — — — — — —— — — ewmm ——— — e

— ———

Naming Conventions
FACILITY PREFIX TABLE

FACILITY

12.3

28-Feb-77

Rev

Page

12-7

PREFIX TABLE

Following is a list of all the facility prefixes.
This list will grow
over
time
as
new facility prefixes are chosen.
No one should use a
new code without first "signing out" the prefix
with
the
author
of
this chapter.
Each facility has a typical style of interface, see the
Functional and
Interface
Specifications
chapter,
and
a
condition

value<31:16>

code.

interface

prefix

facility

type
(see

BAS
B32
BLI
CH
CHF
CME
COB

BASIC support library
BLISS-32 support library
BLISS transportable support
Character handling (BLISS)
Condition Handling Facility
Compatibility mode emulator
COBOL support library

DEB
FAB
FOR
10
LIB
MTH
NAM
NET

Debugger
RMS File Access Block
Fortran support library
Input/Output functions
Miscellaneous routines
Math library
RMS Name Block
Network ACP

OTS
PLI
PR
PRV
PSL

Common Object Time System
PL/1 support library
Processor Registers
Privileges
Program Status Longword fields

arguments

RMS

RM
RMS

RMS internals and
Record Management

SRM

System

SS
SYS
TST

System Service Status
System Services
Test packages

Codes

XAB

RMS

Access

Block

compilers

also

Individual

Access

library

RAB

formed
list.

Record

Reference

Extra

Block

status
System
Manual

information

products

such

Chap

codes
Misc.

offsets

get

condition

<31:16>

13)

Y
v
\'
J
\"

26
27
20
??
25

?2?

\'
any
F
J

24
21
22

\"
?
-

23
??
-

v
\"

\Y
any

0
-

unique

facility

codes

from
the
product name.
They must be signed out in the
Facility prefixes should be chosen to avoid conflict with

above
file

types.

Structure

name prefixes are typically local to a facility.
Refer
to
the individual facility documentation for its structure name prefixes.
This does not cause problems since these names are not global, so
are
not

known

time

only

[End

the

invoking

Chapter

12]

1linker.

the

They

become

structure's

known

assembly

definition macro

compile

explicitly.

Digital

Equipment

Title:

VAX-1ll

Corporation

Software

Eng.

Specification Status:

draft

Architectural

under

File:
PDM

Date:

Status:

COMPANY CONFIDENTIAL

Interface

Page

Specifications

-- Rev

ECO control

SE13R3.RNO
not

used

28-Feb-77

Superseded

Specs:

Part
of OTS

Author:

Conklin,

Typist:

Conklin

Reviewer (s):

R.
D.

Abstract:

design

chapter
2

Hastings

Brender,

Tolman

D. Cutler,

Gourd,

1I.

Nassi,

Spier,

Chapter 13 describes the standards and conventions used
by
all
modules in the VAX-1ll Procedure Library, including the
Object Time System.
The necessary standards are
specified
to
permit many different individuals to contribute modules
independently to ' the
VAX-11
1library
with
a
consistent
interface
objectives,
arguments

documentation.
this
chapter

are

passed,

and

To
also
in

achieve
these
standardizes

particular,

the

modularity
the
way
way

which

strings are returned.
It describes a language
independent
notation
for
procedure
parameters, including the type of
access, the data type, the argument passing mechanism,
and

the

form of

the arqument.

Revision History:
Rev
Rev
Rev
Rev

#
1
2
3

Description
Original
Revised from Review
Integrated with Soft

Author
T. Hastings
T. Hastings
Eng

Manual

Conklin

Revised Date
17-Jan-77

21-Jan-77
28-Feb-77

<access type> notation .
<arg form> notation
<arg mechanism> notation

13-5

.
.

<data type> notation
<name> notation
Compiler

library

Default value
.
Descriptor, call
Form,

. .
by

arg

General

library

Interface

type

Library
compiler
general

math . . . . . . .
object time system
procedure
. . .« «

.
o

.
.
+

Math

.
.

library

13-1
13-1

.
o

13-1
13-1

13-1

Notation
<access

form>

<arg mechanism>
<data type>
. .

.
.

<name>

.
.
.

<arg

type>

procedure

.«

argument

Object time system
Optional argument
Output string
. .

.
.
.

.
.
.«

.
.
.

Procedure
Procedure

notation
. . . . .

.
.

argument
library

Reference,
Repeated

Value,

call

argument

call

.
.
.

13-3

Functional

and
History

Change

Rev

to
1.

Rev

Interface

Specs

Extracted

Added

procedure

routine

specification

interface

languages.
Remove

descriptor

code

table.
Quad

by-value

Note

Change
Note

Add

<data

type>

and

that

string

data

references

data

types

Drop

label

12.

Add

summary

13.

Add data type cp.

14.

Allow

arg

value
(Allocation

Rev

Add

<data

Add

<arg

Add

braces

Add

<arg

Page

13-99¢

for

to
h,

OTS

chapter

applications

redundant

alphabectical

values.

compatibility.

always

data

pair

the

length

ultimate

first.

use.

size.

form.

to be less than
still longword.)

codes

code

form>

use of
other than

for

and

repeated

default

code

reference

use.

lc.

arguments.

value

<data type>
32 bits.

type>

las,

longword

notation

la,

with

for

call

including

descriptor.

args

form>

<data

function

from

table.

type>

Clarify

Change

only

and

descriptor

type

11.

for

only

option

length

Allow

notation

types

numbers

sys

Clarify

Rev

(PL2R1).

Rev

28-Feb-77
--

value

compatibility.

<arg

mechanism>

Functional and Interface Specs

28-Feb-77 -- Rev 3

Change History

Change <data type> la to a for compatibility.

Change <data type> las to arl, arw, arb.

[End of SE13R3.RNO]

Page 13-991

CHAPTER
FUNCTIONAL AND

INTERFACE

28-Feb-77

SPECIFICATIONS

Rev

This chapter describes the
standards
and
conventions
used
by
all
modules
in
the
VAX-11
Procedure Library, including the Object Time
System.
The
necessary
standards
are
specified
to
permit
many
different
1individuals
to
contribute
modules
independently
to the
VAX-11 library with a consistent interface documentation.
To
achieve
these
modularity
objectives,
this chapter also standardizes the way
arguments are passed, and in particular, the way in which strings
are
returned.
It describes a language independent notation for procedure
parameters, including the type of access, the data type, the
argument
passing mechanism,

and the

form of the argument.

The VAX-11] Procedure Library is a collection of routines that
provide
various services to the calling program.
It is made up of a number of
sub-libraries.
The Math library contains
all
those
functions
that
perform
the
traditional
Fortran mathematical functions.
The common
Object Time System is a collection of resource and environment control
routines
that
are
common
to all application language environments.
Each compiler has a
1library of
routines
for
which
it
implicitly

generates
code.
Finally, the general library contains routines that
are of general use and typically would be
called
explicitly
by
the

progr ammer.

ROUTINE

13.1

Page 13-2

28-Feb-77 -- Rev 3

Functional and Interface Specs
INTERFACE TYPES

ROUTINE INTERFACE TYPES

languages
to mix
able
In order to achieve the VAX-11l goal of being
within a program, all routines are designed with certain attributes in
The data types and mechanism passing rules are constrained to
common.
A common notatiocon is
maximize the ability to interface to routines.
interface.
the
of
‘used to express the specification
are
forms
arqument
and
mechanisms,
types,
The access types, data
defined
in
the VAX-11
System Reference Manual.
Section 2 of this
interface notation for
the procedure
chapter lists them and gives
them.
In the design of a procedure interface, in addition to the data
types that must be designed, four other choices are important.
1.

Whether the routine is CALLed or has a non-CALL interface.

Whether its

How output strings are returned;

Whether the routine has a

reference.

scalar

input

are

arguments

next paragraph.

this is

function

value

value is a status code or a scalar result.

value

discussed

1in

the

whether

the

and

it is generally preferable to have only one
The facility table in the Naming
choices.
interface
these
style of
for
1is
conventional interface
the
what
indicates
chapter
Conventions
be
can
combinations
Other
below.
defined
are
These
each facility.
against
off
traded
be
must
confusion
user
of
prospect
the
but
chosen

Within any given facility,

the possible inefficiency of forced consistency.

Output strings can be returned by one of four methods.

length
fixed
The simplest is for the caller to allocate a
The callee writes
string buffer and pass a descriptor of it.
the result to this buffer with blank fill.

fixed

The next most general is for the caller to allocate

string descriptor.
The third mechanism is to pass a varying
maximum buffer and
a
allocates
caller
the
case,
this
In
both the maximum
for
fields
passes a descriptor that contains

length string buffer that can hold the maximum length result.
where
The caller passes two arguments, one is the address of
the actual length and the other is a descriptor to
to write
always
are
arguments
By convention, these two
the buffer.
first.
length
adjacent in the arqument list with the

length

and the actual length.

length field in the descriptor.

The callee updates the actual

string
The fourth method is for the caller to pass a dynamic
string
the
allocates
callee
the
case
this
In
descriptor.
the
1into
length
buffer and places both the address and the

Functional
ROUTINE

and

Interface

INTERFACE

dynamic

Specs

28-Feb-77

TYPES

Rev

Page

descriptor.

The choice between these methods is a function of
what
assumptions can be made in the design of the procedure.
length method, no assumptions are made.
The others
all

the
calling
language
can
substrings.
The dual arqument

variable

13-3

1length

strings,

but

support
form
can

gives most

variable

1length

used

the

environmental
For the fixed
assume
that
strings

without

advantages

or
requiring

them to

languages that support them.
The varying
and
dynamic
schemes
both
require
languages
that support varying length strings.
Furthermore,
the
dynamic
method
requires
the
support
of
a
dynamic
storage

management

system.

The
the

most common combinations of interface specifications are
given
in
following
table.
The
column
"scalars"
shows how scalars are
passed.
The column "strings" shows how output strings
are
returned.
The column "function" shows what kind of function value
is returned.

type

call

instr-

passing

output

uction

scalars

function

strings

value

(non-CALL)

JSB

(by

CALL

(Function)

Value)

parameter
AP

value

length,descr

.1lc

CALL

Fortran

reference

none

CALL

COBOL

reference

fixed

CALL

any

BASIC

reference

CALL

fixed

reference

none

dynamic

any

scalar

Functional

and

Interface Specs

28-Feb-77 -- Rev

NOTATION FOR DESCRIBING PROCEDURE ARGUMENTS

13.2

NOTATION

FOR

DESCRIBING

Page

13-4

PROCEDURE ARGUMENTS

A concise language-independent
notation
1is
wused
to
describe
each
argument
to
a library procedure.
It is suggested that this notation
be used for documenting all procedures in the procedure library and in
the
procedure
header
1itself
wunder
CALLING
SEQUENCE
or
FORMAL
PARAMETERS.
The notation is a compatible extension to the one used in
the VAX-11 System Reference Manual.
However, the goal of the notation
is to describe the formal parameter specified by each list entry in
a
language

1independent way.

The

System Reference Manual only describes

the immediate
operand
specifier,
rather
than
the
argument
being
pointed
to.
Therefore, additional qualifiers have been added to the
System Reference Manual notation.
Note that
if
a
parameter
1is
an
address
which
1is
saved
for
1later access by another procedure, the
notation should reflect the ultimate access to be made by
the
second
procedure.

The notation specifies for each argument:
1.

A mnemonic

The

The data type of the argument

(longword,

The argument passing mechanism

(value,

The

13.2.1

name

type of

access

form of

the

the procedure will make

argument

(scalar,

(read,

write,...)

floating,...)

reference,

descriptor)

array,...)

Procedure Parameter Qualifiers

Subroutines are described as:
CALL

and

subroutine name(argl,

arg2,

...,

argn)

functions are described as:
function_value

where

argi

and

function_name(argl,

function value

<name>.<access

arg2,

...,

argn)

are:

type><data type>.<arg mechanism><arg

form>

where:

<name> is a mnemonic for the procedure
function value specifier.

formal

specifier

Functional and Interface Specs
28-Feb-77
NOTATION FOR DESCRIBING PROCEDURE ARGUMENTS

<access type> is a single letter
that the procedure will (or may)
r

argument

may

read

argument

may

modified,

argument

may

written

Rev

Page

denoting the type of
make to the argument:

13-5

access

only

i.e.,

read

and

written.

only.

argument is an address
to
be
(optionally)
JMPed
to
after
stack
unwind (return).
No <data type> field is
given since the argument is a sequence of instructions,
e.g.,

Fortran

ERR=,

argument
1is
an
address
of
a
procedure
to
be
(optionally)
CALLed
after stack unwound (return).
No
<data type> field is given
since
the
argument
is
a
sequence of instructions.
argument

is an address of a procedure subroutine to
(optionally)
CALLed
without
wunwinding the stack.
<data type> field is given
since
the
argument
is

sequence

argument
CALLed

field

instructions.

of a
unwinding

indicates

reserved

for

(address).
is

address

without

the
wuse

Not

specified.

data
1in

function to
stack.

the

type
the

the

System

be
No
a

be (optionally)
The <data type>

function
Reference

value.
Manual

wused here since the object pointed to

reserved for use in the System Reference Manual (branch
destination).
Not used here since a branch destination
cannot be a procedure formal.
reserved
(variable

for
bit

use
1in
field).

the

System

Reference

Manual

Functional and Intertace Specs

28-Feb-77 -- Rev 3

NOTATION FOR DESCRIBING PROCEDURE ARGUMENTS

Page 13-6

<data type> is a letter denoting the primary data type with
trailing qualifier letters to further identify the data type.

Note that the routine must reference only the size
to avoid improper access violations.
Letters

specified

Use

Unspecified

\Y
bu

Bit (variable bit field)
Byte Logical (unsigned)

u
wu
lu

Smallest unit for addressable storage
Word Logical (unsigned)
Longword Logical (unsigned)

lc
qu

Longword containing a completion code
Quadword Logical (unsigned)

Single character

Absolute virtual address
Character pointer

a
cp

Byte Integer

(signed)

arb Byte containing a relative virtual address (*)

W
h

Word Integer (signed)
Integer value for counters

Longword Integer

arw Word containing a relative virtual address (¥*)
(signed)

General value

of
f
d

Quadword Integer (signed)
Single-Precision Floating
Double-Precision Floating

t
nu

text (character) string
Numeric string, unsigned

nz
p

Numeric string, zoned sign
Packed decimal string

Data type indicated in descriptor

arl Longword containing a relative virtual address (*)

Complex (Floating)
Double-Precision Complex

fc
dc

nl
nlo
nr
nro

Numeric string, left separate sign
Numeric string, left overpunched sign
Numeric string, right separate sign

Numeric string, right overpunched sign

* - arl, arw, and arb is a self-relative address wusing the
same format as the hardware displacements. That is the
self-relative address is a signed offset in bytes with
respect to the first byte following the argument.

Functional

and

Interface

Specs

28-Feb-77

Rev

Page

13-7

<arg mechanism> is a
single
letter
indicating
mechanism that the called routine expects:

the

argument

NOTATION FOR DESCRIBING PROCEDURE ARGUMENTS

—

——

value,

i.e., call-by-value
where
the
contents
of
the
argument
1list
entry
1is
1itself
the
argument
of
the
indicated data type.
Note:
Call-by-value argument
list
entries are always allocated as a longword.
The quadword
data types can
be
wused
as
values
only
for
function
values,
never
as a formal parameter.
Note:
the VAX-11
calling standard requires that <access type>
must
be
r
whenever <arg mechanism> is v, except for function values
where <access type> is always w and
<arg
mechanism>
is
v.

—

usually

amm ————

amem

reference, i.e., call-by-reference where the contents
of
the
argument
1list
entry is the longword address of the
argument of the indicated data type.
1If the argument
is
a
scalar
of the indicated data type or is a label, <arg
form> must be absent.
If the argument is an array,
<arg
form> must be present.

- e

emems

descriptor, i.e.,
of
the
argument

descriptor.

Gen
e emme

4 e

The
specify
further
information about the argument, see the
System Reference Manual Appendix
C.
Note:
when
<arg
mechanism>
1s
d, <arg form> must be present to indicate
type

<arg

form>

Null

means

scalar

ey
s

the

descriptor.

letter

denoting

the

form of

the

argument:

indicated

data

type.

—

COAMS

-t

call-by-descriptor where
the
contents
list entry is the longword address of a
descriptor is two or more longwords that

array

reference

array
descriptor,
i.e.,
call-by-descriptor as indicated by
<arg
mechanism>.
For
array
call-by-reference
the
contents
of the argument list entry is the address of an
array of items of the indicated data type.
The length is
fixed,
1implied
by entries in the array, e.g., a control

call-by-reference

block,
prior

determined

agreement.

contents

the

address

Reference

string

Manual

argument
1list
entry
1is
array
descriptor
block
Appendix C.

descriptor,

contents

i.e.,

the

string.
length
nor

When

modified

the

and

separate

1list

longword
the

length,

entry

string
data

the

string
1is
address
fields
string

argument

the

see

call-by-descriptor

argument

address
of
a
two
descriptor contains
the

another argument,
or
specified
For
array
call-by-descriptor,

filled

updated

1is

written
in

with

1longword

the

System

where
the

the

and

the

longword

descriptor.
type,

by
the

The

address

neither

the

descriptor

are

trailing

spaces

written

length.

28~-Feb-77 -- Rev 3
Functional and Interface Specs
NOTATION FOR DESCRIBING PROCEDURE ARGUMENTS

Page 13-8

v - varying string descriptor, i.e., call-by-descriptor where
of the argqument list entry is the longword
contents
the
The
descriptor.
string
1longword
three
a
address of

and
address,
type,
data
1length,
contains
descriptor
Reference
System
the
of
C
Appendix
See
length.
maximum
When the string is written, the length field of
Manual.
and
address
the
but
modified
also
the descriptor is
'
maximum length fields are unaltered.

d - dynamic string descriptor, i.e., call-by-descriptor where
of the argument list entry is the longword
contents
the
same
the
address of a two longword string descriptor of
both
However, when the string is written,
s.
as
format
1is
Space
the length and address fields may be modified.
procedure
the
1in
routines
dynamically by
allocated
library and is garbage collected periodically
the
p - Procedure descriptor, i.e., call-by-descriptor where
longword
the
1is
entry
1list
argument
the
of
contents
The
descriptor.
longword procedure
two
address of a
the
and
procedure
the
of
address
the
contains
descriptor
function.
a
is
it
if
returns
procedure
the
that
type
data
<access type> must be ¢, f, j, or s.

13.2.2

Optional Arguments And Default Values

CALL
Optional arguments are enclosed 1in square brackets, e.g.
(unit.rb.v {,err.j.rl [,end.j.rl]]). The caller may omit
SU
FORSREAD
optional parameters at the end of a parameter list by passing a
The caller may omit optional parameters anywhere by
shortened list.
A
passing a 0 value as the contents of the argument list entry.
optional.
as
indicated
caller may not omit a parameter that is not
The called procedure is not obligated to detect such a programming
(=) after an argument inside square brackets
An equal sign
error.
indicates the default value if the argument is omitted. For example,
success.wlc.v = SYSSDELLOG (lognam.rt.ds [,tblflg.rb.v=0]).

13.2.3

Repeated Arguments

Arguments or pairs of arguments that may be repeated one or more times
FORSOPEN
CALL
e.g.
braces,
inside
indicated
are
omitted
be
may
that
arguments
Repeated
}).
({keywd.rw.v, info.rl.v
e.g.
brackets,
square
inside
braces
inside
indicated
entirely are
CALL FORSCLOSE ([{logical unit.rl.v}]).

Functional and Interface Specs
NOTATION FOR DESCRIBING PROCEDURE

13.2.4
Cinmoe

s A

28-Feb-77
ARGUMENTS

Rev

Page

13-9

Examples
anale

ALY &

VY AV

MTHSSTIN

Ssa sy Wy

—

(anala

\Riid i

CALL FORSREAD_SF

(unit.rb.v,

radiame

AR
-

+§F

=1\

LUAULAQIIOeL L1l
-—

format.mbu.ra

[,err.j.rl

[,end.j.rl]}])

Note:
That (1) end may be omitted,
(2)
err
omitted.
However,
wunit
and
format
must

and
end
may
both
be
always
be present.
The
argument count byte in the argument list specifies how many
arguments
are
present.
Alternatively err, end, or both could have a 0 argument
list entry in the above.

Common

combinations are:

Completion

code:
longword call-by-value input arg:
address of an array of signed words for input:
address of a control block:
address of a precompiled format statement:
label to jump to:

floating input call-by-reference arg:
floating complex call-by-reference input arg:
read only Fortran character string:
BASIC character string to be written:

Status.wlc.v

=...
no of pages.rlu.v
array.rw.ra
fab.mz.ra

format.rbu.ra
error label.j.r
angle
in rad.rf.r

angle.rfc.r

string rt.ds
string.wt.dd

rage i13-1u

Summary <“hart Of Notation

13.2.5

w
j
¢
s

Read

Modify

Write

RET and JMP
RET and CALL

=zuh CALL
function CALL

—

———

—

———
A
—

anegm

omm—

—

— e

cm—

———

28-Feb-77 -- Rev 3
Functional and Interface Specs
NOTATTIOHN FOR DESCRIBING prOCLLULUKE ARGUMENTS

z
v

bu
C

u
wu

lu
a
cp
lc¢
gu
b
arb
W
h
arw
1
o]

Unspecified
Bit

(variable bit field)

Byte Logical (unsigned)
Single character

Smallest unit for addressable storage
Word Logical (unsigned)

Longword Logical (unsigned)
Absolute virtual address
Character Pointer
Longword containing a completion code
Quadword Logical (unsigned)
Byte Integer (signed)
Byte-sized relative virtual address
Word Integer (signed)
Integer value for counters
Word-sized relative virtual address
Longword Integer (signed)
General value

address

—

——

m—t——

——— —

—

arl Longword-sized relative virtual
Quadword Integer (signed)
g
n Floating
Single-Precisio
f
Double-Precision Floating
d
Complex (Floating)
fc
Double-Precision Complex
dc

—

t
nu

string,
string,
string,
string,
string,

Numeric
Numeric
Numeric
Numeric
Numeric

Packed decimal

———am
i
e

——

—

—— —

nl
nlo
nr
nro
nz

text (character) string
Numeric string, unsigned

Data type

left separate sign
left overpunched sign
right separate sign
right overpunched sign
zoned sign

string

<arg

form>

mem

indicated in descriptor

Reterence

Descriptor

<null>

scalar

A<
o

Value

varying
dynamic

procedure

array

fixed

string

length string
string

Functional

and

Interface

Specs

28-Feb-77

NOTATION FOR DESCRIBING PROCEDURE ARGUMENTS
[End of Chapter

13]

Rev

Fage 13-11

Digital

Equipment Corporation COMPANY CONFIDENTIAL

TITLE: BLISS Transportability Guidlines
Specification Status:

draft

Architectural

Under

status:

File:

SE14F3.FNO

PDM

not

Date:

Rev

Page

ECO Control

used

21-Feb-77

Superseded

Specs:

Author (s):

Typist;

Hesley,

Marks,

Reviewer (s):

R.
S.

Abstract:

none
R.

Murray,

BLISS

Brender,

Nassi

Murray

Hawkinson,

Chapter

D.
D.

addresses

programs.

Cutler,

Tolman,

Hastings,

the process

Tools

of
writing
transportable
techniques
are discussed in

and

detail.

Revision

Conklin,

Winslow

History:

Rev

Description

Author

Revised

Rev
Rev
Rev

1
2
3

Original
Skipped
SEM Integration

I.
I.

Nassi
Nassi

Murray

22-Dec-76
25-Jan-77
21-Feb-77

Date

BLISS Transportability Guidlines
;change history

Rev

Software Engineering Manual
as

Rev

to Rev

Page 14-990

to Rev

21-FEB-77 -- Rev 3

integration,

this document

added

chapter

revision

chapters

[end of SE14R3.RNO]

skipped

Rev

align

revision

histories

all

CHAPTER

BLISS TRANSPORTABIBILTIY GUIDLINES

21-FEB-77

-~ Rev

This Chapter addresses the task of writing transportable programs.
It
is
shown
that
the writing of such code is much easier if considered
from the beginning of the
project.
The
properties
which
cause
a
program
to
loose transportablilty are explored.
Techniques by which
the programmer may avoid these pitfalls are discussed.

BLISS Transportability Guidlines

21-FEB-77 -- Rev 3

Page 14-2

INTRODUCTION

14.1

INTRODUCTION

Purpose And Goals

14.1.1

The purpose of this document is to facilitate the process of edwriting
to be
transportable BLISS programs, that is, BLISS programs intend
various
are
There
s.
machine
nt
differe
y
executed on architecturall
kinds of solutions to the problem of transportability, each requiring
different levels of effort. We feel free in recommending various
When program text should be rewritten, for
kinds of solutions.
so. However, it is our belief that 1large
doing
example, we suggest
be written which will require absolutely no
can
s
portions of program
modification in order to be functionally equivalent over differing

architectures.

desirability,

o
o

The levels of solutions wé see, in order of decreasing

are:

no change is needed to program

perfectly straightforward.

text

transportability

parameterization solves the transportability problem - the
program makes use of some features that have an analog on all
the other architectures.

parallel definitions are required - either programs make use
of features of an architecture that do not have analogs
across all other architectures, or different, separately
in
interact
program
a
of
aspects
transportable
non-transportable ways.

The goal is to make transportability as painless as possible, which
means that the effort needed in transporting programs should be
minimized.

that
notion
the
is
here
presented
ideas
Central to the
the
from
red
transportability is more easily accomplished if conside
a
becomes
beginning. Transporting programs after they are running
l
paralle
running
We suggest frequently
much more complex task.
compilations, for instance. It is fortunate therefore, that with the
right tools and techniques, transportability is not difficult to
is
achieve. We would also like to point out that the first program, we
project
ming
program
Before undertaking a large
the hardest.
suggest writing and transporting a less ambitious program.

These guidelines are the result of a concentrated study of the
We make no claim that
problems associated with transportability.
some of what 1is
that
claim
do
We
these guidelines are complete.
We have attempted
mers.
program
to
ious
contained here will be non-obv
not forewarned,
is
er
programm
the
if
to identify those areas which,
ns to all
solutio
ing
suggest
be
will
We
cause problems.
will
identified problems.

BLISS Transportability Guidlines
INTRODUCTION

Many

the

currently
of viewing
language
BLISS-36.

14.1.2

problems

that

are

21-FEB-77

discussed

here

-- Rev

have

solutions

Page

14-3

that

are

being
incorporated into the BLISS lanquage, so another wav
this document is as a partial rationale for some
of
these

changes,

and

rationale

for

the

definition

BLISS-16

and

Organization

These guidelines are organized into three sections.
The
section
on
General
Strategies
discusses
some
high level approaches to writing
transportable BLISS software.
The section on Tools describes
various
features
of
the
BLISS
language
that
can
be
used
in
solving
transportability problems.
The section on Techniques analyzes various
transportability problems and suggests solutions to them.

BLISS Transportability Guidlines
GENERAL STRATEGIES

14.2

Page 14-4

21-FEB-77 -- Rev 3

GENERAL STRATEGIES
Introduction

14.2.1

This section presents certain gross or global considerations that
important to the writing of transportable BLISS programs, namely:
o

Isolation,

Simplicity

and

Isolation

14.2.2

The following maxim should be kept in

mind when you

and/or coding a program that is to be transported:
o

are

designing

If it is NON-transportable, isolate it.

for which it is desirable to
You will probably encounter situations your
BLISS program. In these
use machine-specific constructs 1in
facilitate any future
will
cases, simply isolating the constructs
movement of the program to a different machine.

program or system will
In most cases, only a small percentage of the
it is running. By isolating
be sensitive to the machine on which
effort involved in
those sections of a program or a system, nedthe mainl
y to these easily
transporting the program will be confi
identifiable, machine-specific sections.

Specifically, follow these rules:

ated - place the
If machine-specific data is to Dbe alloc
allocation in a separate MODULE or in a REQUIRE file.
If machine-specific data is to be accessed - place the access

n is to be
If a machine-specific function or instructio
file.

isolate this part of
If it is impossible or impractical to nt
it heavily. Make it
comme
your program from its module,
is
code
this
that
r
reade
the
to
obvious
very

the ROUTINE or
in a ROUTINE or in a MACRO and then place
file.
RE
REQUI
MACRO in a separate MCDULE or in a
isolate it by placing it too in a REQUIRE

used,

non-transportable.

context of a routine or
The above rules are applicable in the local
instance, in the
In a larger or more global context (for
module.
design of an entire system) isolation is implemented by the technique

BLISS

Transportability
GENERAL STRATEGIES

modularization.

separating

system

the

entire

small

machine

parts

from

system

section

written
new

those

dependent

the

Guidlines

System

the

simplified.

the
a

the

rest

total

transportable

with

21-FEB-77

minimum

It
system.

~--

Rev

Page

which

are

machine

system,

the

task

becomes
The

major

matter

of
of

manner) should easily make
of re-coding effort.

operating
transporting

portion

14-5

recoding
the

the

code

move

a
(i1f

BLISS

is a language which facilitate
s both the design and
programming
programs and systems in a modular
fashion.
This feature should be
taken advantage of when writing a trans
portable system.

14.2.3
A

Simplicity

basic concept
simplicity in

BLISS

was

software.
high-level
machine

same

the

which

have

transportable

the

BLISS

language.

developed

the

for

features

program

control

the

will

allow

used

explicitly, making
complexity of data

the
it

language
often

the program
allocation,

the

systems

among
to the
running.
The programmer is
allocation
of
data,
for

underlying

excess.

causing
case

simplicity

unique
access

access

that

often

is
nearly
allows ready

the

very

software

implementation

over

features

are

non-transportable,

that

a
such

order

features

program
features

of
identify

to
be

invoked

inherently more complex.
Reducing
the
example, results in a transporta
ble
the BLISS language.
This reduction of complexity is
one
of
themes that runs through the guide
lines.

subset

the

of
basic

effect,

because

complete

language

hardware

those

use

As
a
result
of
this,
BLISS
programming languages in that it

example.

The

writing

originally

allowed

the

coding

number

for

transportable

options

available

programs
has

been

is
a
simpler
task
reduced.
Simplicity

in the coding effort is one of the
reasons
for
the
development
of
higher-level
1languages
1like BLISS.
The use of the defaults in BLISS
will result in programs which are much
more easily transported.

BLISS Transportability Guidlines

Page 14-6

21-FEB-77 -- Rev 3

TOOLS

14.3

TOOLS

This section on tools presents various language features that provide
These features are either
a means for writing transportable programs.
for
designed
specifically
been
have
intrinsic to BLISS or
uses.
ing
engineer
e
/softwar
transportability
The tools described here will be used throughout the companion section
on

techniques.

14.3.1

Literals

Literals provide a means for associating a name with a compile-time
In this section, we will consider some built-in
constant expression.
In
in writing transportable programs.
literals which will aid us
addition, we will discuss restrictions on user-defined literals.

14.3.2

Predeclared Literals

is
1in writing transportable programs
key techniques
the
One of
The
tool.
ion
parameterizat
primary
a
are
Literals
parameterization.
machine specific literals
BLISS lanquage has a set of predeclared,
that can be most useful.

three
These literals parameterize certain architectural values of the
the literals are dependent on the machine
The values of
machines.
their
are
Here
for.
compiled
that the program is currently being
names

and values:

Literal

vAX-11 11

Description

Name

10/20

Bits per addressable unit
Bits per address value
Bits per BLISS value

$BPUNIT
$BPADDR
$BPVAL

36
18
36

8
32
32

8
16
16

Units per BLISS value

$UPVAL

The names beginning with

'%'

are the literal names that can

These literal names will be used throughout the guidelines.

used.

Bits per value is the maximum number of bits in a BLISS
value.
Bits
per
unit
1is
the number of bits in the smallest unit of storage that
can have an address.
Bits per address refers to the maximum number of
bits
an
address
value
<can
have.
Units per value is the quotient

$BPVAL/$BPUNIT.

associated with

a value.

the

maximum

number

addressable

units

BLISS Transportability Guidlines

21-FER=77

TOOLS

We can derive
example:

other

useful

values

from

=--

these

Rev

built-in

Page

14-7

literals,

For

LITERAL

HALF_VALUE

defines

the

14.3.2.1

number

User

$BPVAL

half

bits

Defined

A literal is not
and restrictions

Literals

word

(half

longword

VAX-11)
.

strictly speaking
associated with a

a self-defining
term.
literal are arrived at

The
wvalue
assigning

certain
semantics
to
its
source
program
representation.
convenient
to
define
the
value
of
a literal as a function
characteristics of a particular architecture, which
means
that

are

certain

architectural

literals.
Because

the

size

representation

BLISS

dependencies

value

literal,

inherent

determines

there

the

are

two

string-literals.
the

machine

word

types

The
size.

BLISS

values
The

literals:

values

for

are:

Double
not

precision

supported

numeric

section

are
is 32

different
bits:
on

are constrained

signed

number,

-(2**31)

(2%*31)

10/20:

-(2**35)

(2%*35)

]

11:

-(2**15)

(2%*15)

= (2** ($BPVAL-1))

floating

ooint

numbers

BLISS-36

BLISS-16.

literal,

value
1is
the
when
stored,
longword).
A
the

and/or

%C'single-character',

the

on
the

and

by
i,

(2**(%BPVAL-1))-1

($D'number'

has

transportability

VAX-11:

ALL:

use

numeric-literals

of numeric-literals

ranges

the

value

some

considerations.
BLISS value (machine word)
sizes
each
of
the three machines.
On VAX-11l, the size
10/20 systems, it is 36;
and the 11 value i- 16.
There

1in

It
1is
of the
there

been

BLISS-32)

implemented.

are

Its

ASCII code correspondina to the character in quotes
and
it
1is
right-justified
in
a
BLISS
value
(word
or
more
thorough discussion of its usage can be found in
entitled:
"Data:
Character Sequences".

Page 14-8

21-FEB-77 =-- Rev 3

BLISS Transportability Guidlines
TOOLS

There are two ways of using string-literals: as integer-values and as
character strings. When string-literals are used as values, they are
representational
the
of
out
This arises
not transportable.
following table
The
sizes.
word
differing
from
differences and
type string
$%ASCII
an
for
es
differenc
potential
these
illustrates
literal:

10/20

vax-11

right to

left to

right to

Maximum number of
characters.

Character placement.

left

right

left

This type of string literal usage and also its use as a
string are discussed in the section entitled: "Data:

character
Character

Sequences”.

14.3.3

MACROS

of
BLISS macros can be an essential tool 1in the develop)mentduring
(expand
e
Because they evaluat
programs.
transportable
compilation, it is possible to tailor a program to a specific machine.
two
A good example can be found in the section on structures. There,macros
The
e.
ortabl
transp
tely
macros are developed which are comple
vector of
can determine the number of addressable units needed for a bits.
of
terms
in
ed
specifi
is
elements, where the element size

There are
available.

macros
conditionalization
to compile selectively only

machine
be used

pre-defined
also
These macros can

certain declarations and/or expressions depending on which compiler is
being

run.

Their definitions for the bliss-32 set are:
MACRO

$BLISS16[]
$BLISS36[]

$BLISS32([]

= %
= %

,
,

= %REMAINING %

;

The net
es.
There are analogous definitions for the other machinto
6 and
$BLISS1
ts
effect is that in the BLISS-32 compiler, the argumen
d
replace
be
will
2
$BLISS36 will disappear, while arguments to $BLISS3
by the text given in the argument list.

BLISS

Transportability

Guidlines

21-FEB-77

Rev

TOOLS

14.3.4

Module

switch and a corresponding on-off switch
in
the
writing of transportable programs.
This
provided for two reasons:

indicate

the

intended

provide

diagnostic

checking

features.

programmer

(environments)

can

for

therefore

which

indicate

program

Diagnostic checking
consists
certain lanquage features are

[

o
=

[

If
no
LANGUAGE
switch
1is
specified,
languages,
and
as
a
consequence, only
facilities are made available.

Each

not

compiler will
in the list of

Within
warni..5

the

certain

target

module

language

architectures

module

header

several

BLISS

switches

processors

are

,...)

1))

[

]

(language-type

LANGUAGE

where

is:

syntax

the

goals

compiler
determining
whether
for all of the intended target
:

The LANGUAGE switch may be used
in
the
declaration
to
designate
which
of the
intended to compile the module.
The

use

intended.

of
the
available

environments.

the

scope

diagnostic

intersection

the

LISS36,

The

14-9

are provided to
aid
switch, LANGUAGE, is

transportability

and
o

Page

Switches

A module

the

give a warning diagnostic
language-types.

lanquage
for

any

specified

switch,
language

set of

BLISS16

BLISS32.

default

most

each

its

own

compiler

construct

languages.

is
all
three
restricted language

which

language

will
is

not

give
in

1is

a
the

BLISS Transportability Guidlines

21-FEB-77 -- Rev 3

Page 14-10

TOOLS

NOTE

particular
the
this writing
As of
that will be subject
features
lanquage
to be detailed.
to diagnosis have yet

serve to
now will
it
using
However,
the
make
to
document the program, and
immune to compiler enhancements
program
under
features
certain
restrict
that
.
settings
certain switch

Here is an example of how the LANGUAGE switch would be used:
MODULE FOO(...,LANGUAGE (BLISS36, BLISS16, BLISS32),...)
BEGIN

BEGIN
1+

! BLISS16 no longer

SWITCHES

in effect.

LANGUAGE (BLISS36,

BLISS32);

Any use of language features, within
this block, which are specific to
BLISS16 will result in a diagnostic
warning.

The compilation of this section
of code by a BLISS-16 compiler will
result in a diagnostic warning.

END;

L+

All three language settings are restored.

BLISS Transportability Guidlines

21-FEB-77

Rev

Page

14-11

TOOLS

Reserved Names

14.3.5

______

represents

Hence,

the

if one

115C

BLISS

reserved

names

reserved

names.

all

three BLISS dialects.
program,
writing a transportable
one
should
names
as
a
user-defined name, since such use

of
any
using
results in a compiler

diagnostic.

should not be used when writing code

with

*ADDRESSING MODE

RECORD

*ALIGN

INCR

REF

INCRA

AND

*INCRU

REP

BEGIN

INITIAL

REQUIRE

BIND

INRANGE

RETURN

BIT

KEYWORDMACRO

ROUTINE

LABEL

SELECT

*BUILTIN
BY

*BYTE
CASE

CODECOMMENT

LEAVE

SELECTA

LEQ

SELECTONE

LEQA

SELECTONEA

*LEQU

*SELECTONEU

COMPILETIME

LIBRARY

DECR

LINKAGE

SET

DECRA

LITERAL

*SHOW

LOCAL

*SIGNED

*DECRU
DO

*SELECTA

*LONG

STACKLOCAL

ELSE

LSS

STRUCTURE

ELUDOM

LSSA

ENABLE

*L.SSU

SWITCHES
TES

END

MACRO

THEN

EQL

MAP

EQLA

MOD

UNDECLARE

MODULE

UNTIL

*EQLU
EQV

NEQ

EXITLOOP

NEQA

EXTERNAL

*NEQU

UPLIT

*VOLATILE

*WEAK

FIELD

NOT

FORWARD

NOVALUE

FROM

*WORD
XOR

GEQ

GEQA

OTHERWISE

*GEQU

OUTRANGE

GLOBAL

OWN

GTR

PLIT

GTRA

PRESET

*GTRU

*PSECT

asterisk

intended to be transportable.

WHILE

WITH

BLISS

Transportability

Guidlines

21-FEB-77

Rev

Page

14-12

TOOLS

14.3.6

REQUIRE Files

REQUIRE files are a way of
gathering
machine
and/or expressions together in one place.

specific

declarations

In many cases, it will be either impossible or unnecessary to
code
a
particular
BLISS
construct (e.g.
routines, data declarations, etc.)
in a transportable manner.
Developing parallel REQUIRE files, one for
each

machine,

can

often

provide

solution to transporting

these

constructs.

For example, if a certain set of routines are very
machine
specific,
then
the solution may be to code two or three functionally equivalent
routines, one for each machine type, and segregate them each in
their
own REQUIRE file.

Each BLISS compiler has a pre-defined search
rule
for
REQUIRE
file
names
based on their file types.
Each compiler will search first for
a file with a specific file type, then it will search for a file
with
the file type '.BLI'.

The

rules

for each compiler

Compiler

Hence,

are:

1st

2nd

BLIS36

.B36

.BLI

BLIS16

.B16

.BLI

BLIS32

.B32

.BLI

the

following REQUIRE declaration:

REQUIRE

'IOPACK';

will search for IOPACK.B36,
which
compiler
1is
being

IOPACK.B1l6
or
run.
Failing

I/0 Package

IOPACK.B32,
depending
on
that
it
will
1look
for

IOPACK.BLI.

Inherent in these search rules is
a
naming
convention
for
REQUIRE
files.
If
the
file is transportable, give it the file type '.BLI'.
If it is specific to a particular dialect, give it
the
corresponding
file

type

(e.g.

'.B36').

BLISS Transportability Guidlines
TOOLS

14.3.7

21-FEB-77 -- Rev 3

Page 14-13

ROUTINES

The key to transportability is the ability to identify
properties
of
an
environment,
abstract
the property by giving it a name, and then

define the semantics of the property in all
applicable
environments.
The
closed
subroutine
has
1long
been
reqarded
as
the
principal
abstraction mechanism in programming lanquages.
With
BLISS,
we
see
other
abstraction
mechanisms
being
used,
1like structures, macros,
literals, require files, etc., but the routine
can
still
be
easily
used as a transportability abstraction mechanism.
For instance, when designing a system of transportable
modules
which
uses
the concept of floating point numbers and associated operations,
there will be a
need
to
perform
floating
point
arithmetic.
The
question
naturally
arises
as
to
the
environment
in
which
the
arithmetic should be done.
1If the floating point
arithmetic
resides
entirely
in
a
well-defined set of routines, and no knowledge of the
various representations of
floating
point
numbers
1is
used
except
through
these
well
defined
interface
routines,
then
it
becomes

possible to perform "cross-arithmetic"”, which becomes highly desirable
when
writing
cross-compilers,
for instance.
Even if the ability to
perform cross—arithmetic is
not
desired,
isolating
floating
point
operations in routines is a good idea since these routines can then be
reused more easily in another project.
A little thought will indicate
that
the
floating point routines themselves have to be transportable
if they are
going
to
perform
cross-arithmetic,
but
need
not
be
transportable if cross arithmetic is a non-goal.
The principal objection to using routines as an abstraction
mechanism
is
that the cost of calling a procedure is non-trivial, and that cost
is strictly program overhead.
Composing this sort of
abstraction
in
the
1limit
will
produce
serious
performance degradation.
For this
reason, a programmer should probably try not to use the routine as
an
abstraction
mechanism
if
a
small
amount
of
forethought
will be
sufficient to enable the writing of a single transportable module.

BLISS Transportability Guidlines

21-FEB-77 -~ Rev 3

Page

14-14

TECHNTQUES

14.4

TECHNIQUES

s you how to write
This section on techniqgues show
nized in dictionary
orga
The section 1is
programs.
ion contains:
sect
subEach
construct or concept.
o

transportable
form by BLISS

A discussion of the construct or concept.

Transportability problems that its use may engender.
Specific guidelines and restrictions on the use

Examples - both transportable and non-transportable.

the

construct or concept.

The examples, in all cases, attempt to use the tools described
TOOLS section.

in the

BLISS

Transportability

Guidlines

TECHNIQUES

14.4.1

Rev

Page

14-15

Data

14.4.1.1

Introduction

This

section

For

the

deals

sequence

(string)

Calculation"

the

allocation

this

section

allocation
addresses, etc.)

the

own

"Data:

the

1in

data

their
and

with

purposes

discussed

found

21-FEB-77

of
A

data

we
data.

address

not deal
These
types

BLISS

program.

with

character
data
are

sections

(See:

"Data:

Addresses

and

Character

Address

Sequences").

Primarily,

discuss

scalar

data

(e.g.

counters,

presentation

integers,

pointers,

of more complex forms of data
can
entitled:
"Structures and Field-Selectors"
Initialization".
First
there
is
a
discussion

sections

and
of

"PLITs
and
transportability

problems
encountered
due
to
differing
machine
architectures.
Next
a
discussion
of
the
BLISS
allocation-unit
attribute
1is
presented.
Finally,
a discussion of other BLISS data
attributes that must be considered when
writing transportable programs
is discussed.

14.4.1.2

Problem

Genesis

The
allocation
of
data
(via
the
declarations)
tends
to be one of the
program in terms of transportability.
data arises chiefly from two sources:

When

The

machine

The

flexibility

are

transported

allocating

architectures
of

considering
to

data

another

on. (at

the

writing

least

two)

GLOBAL,
etc.
areas of a BLISS
of
transporting

and

BLISS

machine,

OWN,
LOCAL,
most sensitive
This
problem

language.

a
are

BLISS

program

confronted

architecturely

with

that

will

the

problem

different

machines.

Although

we have already discussed differing
word
sizes,
there
are
differences.
On
the
VAX-11 machine data may be fetched in
longwords (32 bits), in words (16 bits) and
in bytes (8 bits);
on the
11,
both
words
and
bytes may be fetched.
Only 36-bit words on the
10/20 systems may be directly fetched (i.e.
without a byte pointer).
further

If we were writing our program
in
MACRO-10
or
MARS
we
would
not
consider
these
differences
to
be important - clearly, our assembly
language program was not intended to be transportable.
What

decisions,

transportable

how

many

These
chief

bits

however,
allocation

are

going

must
of

the
data?

BLISS
Need

allocated?

questions (and their answers) can be
source
of
data
transportability

language

itself.

programmer
he

she

make

the

concerned

with

complicated
by
the
problems,
namely the

other
BLISS

BLISS Transportability Guidlines

Page 14-16

21-FEB-77 -- Rev 3

TECHNIQULS

BLISS is different than many other higher-level languages in that it
allows ready access to machine-specific control, particularly in
who 1s
storage allocation. This is fortunate for the programmerprogra
mmer
This
re.
softwa
ent
writing highly machine-specific, effici
be
will
data
of
bits
many
how
y
needs much more control over exactl
ns
decisio
the
ate
complic
can
,
This feature of BLISS, however
used.
that need to be made by the BLISS programmer who is writing ora
Does he or she allocate scalars by bytes,
transportakle program.
by words, or by longwords?

14.4.1.3

Transportable Declarations -

Consider the
BLISS-32:

following

OWN

simple

example

PAGE _COUNTER: BYTE;

data

declaration

1in

Page counter

le named
The programmer has allocated one byte (8 bits) for a variab
ing
request
in
were
ons
intenti
her
or
his
what
PAGE_COUNTER. No matter
The
table.
anspor
non-tr
is
ation
declar
this
e,
only one byte of storag
concept of BYTE (in this context) does not exist on the 10/20 systems.
In fact, in BLISS-36 the use of the word

BYTE

results

error

message.

I1f this declaration had been originally coded as:
OWN

PAGE _COUNTER;

! Page counter

machines.
then this could have been transported to any of the ofthree
has not
pages)
number
the
g
storin
The functionality (in this case,
e by
storag
te
alloca
to
er
compil
been lost. We allowed the BLISS
ation.
declar
OWN
the
in
nit
tion-u
alloca
default by not specifying any
allocatioun-unit
In all the BLISS dialects the default size for guideli
ne 1is:
consists of $BPVAL bits. Thus our first transportable
o

Do not use the allocation-unit attribute

scalar

data

declaration.

Besides the allocation-unit there
present transportability problems
allocating data:

are other
if used.

attributes that may
In particular, when

BLISS

Transportability

Guidlines

2]1-FEB-77

TECHNIQUES

not

use

the

Extension

following

(SIGNED

=--

Rev

Page

14-17

attributes:

and

UNSIGNED),

Alignment,
Volatile,
Range,

Weak

which
Do

say:

think

you

really need to
structure attributes?

twice

before

specify

any

you

data

write

declaration.

attributes

other

than

The Extension-attribute specifies
whether
the
sign
bit
is
to
be
extended in a fetch of a scalar.
This attribute is meaningful only on
VAX-11] and
1is
not
supported
by
BLISS-36
or
BLISS-16.
No
sign
extension can be performed if the allocation unit is not specified.
The Alignment-attribute tells
data
segment
1is
to
start.
BLISS-16;
hence,
it
is

alignments

are

available

the

compiler

not

what address boundary
a
supported
in BLISS-36 or

non-transportable.

dependent on

the

size

Suitalbe

the

default

scalar.

The

Volatile-attribute notifies the compiler that code
to
fetch
the
contents of this data segment must be generated anew for each fetch in
the BLISS program.
It is not supported in BLISS-36
or
BLISS-16
and
will result in a compiler diagnostic.

The Range-attribute specifies the number of bits needed
to
represent
the
value
of
a
1literal
that
is
declared
global in a separately
compiled module.
The STARLET linker is the only linker that currently
supports external literals.
The

Weak-attribute
1is
supported
by
BLISS-36
transportable program.

These
BLISS

guidelines
programmer

actually

reason
values

to
are

case

the

are
of

allocated

STARLET-specific

BLISS-16.

scalar

can

relatively

simple,

yet

they

needing

worry

about

how

the

compiler.

There

specify an allocation-unit or
almost always sufficient.
of

attribute

data,

the

use

any

the

not

and
be

should

wused

not
in

relieve

the

1is

program data will
often
very
1little

attributes.

default

The

default

allocation-unit

will
sometimes
result
in
the
allocation
of
more storage than is
strictly necessary.
This gain in program data size
(which,
in
most
instances,
1is small) should be weighed against a decrease in fetching
time for a particular scalar value, and the knowledge that because
of
the
default
alignment
rules,
no
storage
savings may, in fact, be
realized.
In the
(among

BLISS language, the default size
other
reasons)
because this is

accessed

unit

data

for

a particular

of
the

$BPVAL
bits
largest, most

machine.

Which

was
chosen
efficiently

say,

the

BLISS

Transportability

Guidlines

21-FEB-77

Rev

Page

14-18

TECHNIQUES

saving of

bits

does

not

necessarily mean

a more efficient program.

There will undoubtedly be cases where it is impossible
to
avoid
the
use
of
one
or
more
of
the
above attributes.
1In fact, it may be
desirable to take advantage of a specific machine feature.
In
these
cases follow this guideline:
o

Conditionalize
which

may

and/or

heavily comment

the

use

This guideline is the "escape-hatch", if you
will,
in
guidelines.
It should only be used sparingly and where

use it often will only result in

re-written when the program has
and that's not our goal.

14.4.2

Data:

14.4.2.1

declarations

non-transportable.

to be

code

that

transported

will

this
set
justified.

need

of
To

another machine -

Addresses And Address Calculations

Introduction -

This section
will
discuss
address
values
and
calculations
using
address
values.
First, there will be a presentation of the problems
that might occur when using an address or the
result
of
an
address
calculation
as
a
value.
A transportable solution to some of these
problems is then presented.
Next,
a
discussion
of
the
need
for
address
forms
of
the
BLISS
relational
operators
and
control
expressions and how and when to use them will be presented.
Finally,
some
important
differences
1in
the interpretation of address values
between BLISS-10 and BLISS-36 are discussed.

14.4.2.2

Addresses And Address Calculations

The value of an undotted variable name in BLISS
1is
an
address.
In
most
cases,
this
address value is used only for the simple fetching
and storing of data.
When address values are used for other purposes,
we
must be concerned with the portability of an address or an address
calculation.
By address calculation we mean any arithmetic operations
performed

address

values.

The primary reason for our concern is the different sizes (in bits) of
addressable
units, addresses, and BLISS values (machine words) on the
three machines.
For convenience in
writing
transportable
programs,

these
size
literals.
A
entitled:

values
have
been
parameterized
table of
their
values
can
be

"Literals".

and are now predeclared
found
1in
the
section

Page 14-19

21-FEB-77 -- Rev 3

BLISS Transportability Guidlines

TECHNIQUES

an effect on writing
To see how these size differences can have
type of address
a common
let's consider
transportable programs,
from
value
address
an
computes
namely an expression that
expression;
some
is,
That
offset.
an
and
(a pointer or an address)
a base
expression of the form:

base

index

...

Now consider the following BLISS assignment expression using this form
of address calculation:
OWN

2;
ELEMENT

2 =
ELEMENT

. (INPUT_RECORD +

1);

second
the
of
contents
the
The intent (most likely) was to access
in the data segment named INPUT RECORD and to place that value
value

2.
in an area pointed to by ELEMENT

on each machine as we shall see.

The effect, however,

is different

are
we
INPUT_RECORD)
(in this case,
to an address
By adding 1
1In
machine.
the
on
computing the address of the next addressable unit
(8
byte
next
the
of
BLISS-32 and BLISS-16 this would be the address

but in BLISS-36 this would be the address of the next word (36
bits),
This is probably not a transportable expression because of the
bits).
different sizes of the addressable units and the resultant values.

Based on the above example, we introduce the following guideline:
o

When a complex address calculation is not an
of

the

algorithm

intrinsic

part

being coded, do not write it outside of a

structure declaration.

There is a way, however, of making such an address
It involves the use of the values of the
transportable.
1In the last example, if the index had been 4 in
literals.
2 in BLISS-16 then in each case we would have accessed the

calculation
predeclared
BLISS-32 or
next word.

in
4
We need to calculate a multiplier that will have a value of
already
multiplier
a
Such
BLISS-36.
in
1
2 in BLISS-16 and
BLISS-32,
is
definition
Its
literal.
predeclared
another
exists as
$BPVAL/%BPUNIT,

and it is called

%UPVAL.

BLISS Transportability Guidlines

Page 14-20

21-FEB-77 -- Rev 3

TECHNIQUES

Using this literal in our example we would have:
ELEMENT
2

. (INPUT_RECORD +

$UPVAL);

The address expression is now tranportable.
This
last
example
raises
an
interesting
point.
If
an
address
calculation
of this form is used then it is very likely that the data
segment should have had
a
structure
such
as
a
VECTOR,
BLOCK
or
BLOCKVECTOR associated with it.
The last example could have then been
coded

as:

OWN

INPUT_RECORD:

FLEX VECTOR[RECORD SIZE,$BPVAL],
ELEMENT
27

2 =
ELEMENT

.INPUT_RECORD[1];

The transportable structure FLEX VECTOR and a more thorough discussion
Structures and
of structures can be found in the section entitled:
Field

Selectors.

14.4.2.3

Relational Operators And Control Expressions -

The previous example illustrated the use of address values 1in the
Other common uses of addresses are in
context of computations.
comparisons (testing for equality, etc.) and as indices in loop and
The use of address values in these contexts
select expressions.

points to another set of differences found amongst the three machines.

In BLISS-32 and BLISS-16, addresses occupy a full word ($BPADDR equals
However,
and unsigned integer comparisons must be performed.
$BPVAL)
36
versus
('3
word
machine
the
than
smaller
are
in BLISS-36, addresses
efficiency
for
performed
are
operations
integer
signed
and
bits)
reasons.

It can be seen that to perform a simple

relational

values:

1 LSS ADDRESS_2
ADDRESS

test

address

BLISS Transportability Guidlines

TECHNIQUES

requires
evaluate

21-FEB-77 -- Rev 3

two different
interpretations.
correctly
on
the 10/20 systems.

machines, the following would have had to
comparison to have been made correctly:
...

Page 14-21

This
expression
would
But, on the VAX-1ll and 11

have

ADDRESS
1 LSSU ADDRESS
2

been

coded

for

the

...

Another type of relational operator, designed specifically for address
values,
1is
needed.
Such
operators
exist
and
are referred to as
address-relational-operators.
BLISS-36, BLISS-16 and
BLISS-32
have,
in
fact,
a
full
set of them (e.g.
LSSA, EQLA, etc.) which support
address comparisons.

In BLISS-16 and BLISS-32, the address-relationals
are
equivalent
to
the
unsigned-relationals.
In BLISS-16, the address-relationals are
equivalent to the signed-relationals.
For all practical cases, a user
need
not
be
concerned with this, since this "equivalencing" permits
" equivalent address comparisons to be performed across architectures.

(SELECTA),
SELECT
the
of
forms
address
are
there
addition,
In
SELECTONE
(SELECTONEA) ,
INCR
(INCRA)
and
DECR
(DECRA)
control
expressions.
The following guidelines establish
a
usage
for
these
operators and contol expressions:
o

If address values are to be compared,

use the address form of

If an address is used as an index
1in
INCR
or
DECR
expression,
use
the

a
SELECT,
SELECTONE,
address
form of these

the

relational operators.

control expressions.

A violation of either

these

gquidelines

can

have

unpredictable

results.

14.4.2.4

BLISS-10 Addresses Versus BLISS-36 Addresses -

1in
There i3 a fundamental conceptual change from BLISS-10 to BLISS-36
data
a
of
value
the
BLISS-10 defines
the defined value of a name.
in
segment name to be a byte pointer consisting of the address value
in
36
and
0
the 1low half of a word, and position and size values of
as
value
the
BLISS-36, however, defines
the high half of the word.
This
address in the low half and zeros in the high half.
simply the
since it
transportability,
reasons of
change was made solely for
allows BLISS to assign uniform semantics to an address.

The fetch and assignment operators are redefined
Thus the expressions:
address part of a value.

use

only

the

Page 14-22

21-FEB-77 -- Rev 3

BLISS Transportability Guidlines

TECHNIQUES

. X3

F(.Y)

are the same in both BLISS-10 and BLISS-36, but
Y

assigns a different value to Y in BLISS-36 and in BLISS-10.

Field selectors are still available but must be thought of as extended
fetch and assignment operators, instead of as value
the
to
operands
Thus the meaning of:
applied to a name.
operators
producing
Y<0,18>

appear

never

.X<3,7>;

but

is unchanged,

is invalid.

= X<3,7>;

selectors
field
position
bit
since
,
declaration
structure
a
of

it is highly recommended that

Moreover,

outside

and size are apt to be highly

machine

dependent.

discussion can be found in the section entitled:

thorough

Structures and Field

Selectors.

Data:

14.4.3

14.4.3.1

Character

Sequences

Introduction -

1in
This section will discuss the use of character sequences (strings)
Historically, there has been no consistent method for
BLISS programs.
hoc
Ad
them.
dealing with strings and the functions operating upon
having been implemented by
rule,
the
functions have been
string
section
This
individuals or projects to suit their particular needs.
will begin by looking at quoted strings in two different contexts.

will discuss transportability problems associated with quoted st-inys,
their

use.

and guidelines

for

Quoted strings

are used in two different contexts:

as values

(integers)

character

strings

and

BLISS

Transportability

Guidlines

21-FEB-77

Rev

TECHNIQUES

14.4.3.2

Usage

Numeric

Values

Page

14-23

The

use of quoted strings as values (in assignments
and
comparisons)
illustrates
the
problem
of
differing
representations on differing
architectures.
Describing the natural translation of a string literal
for
each
architecture
will
illustrate
the
problem.
For example,
consider the following code sequence:

OWN
CHAR FOO;

CHAR_FOO

natural

would

interpretation

allocated

increasing
of

byte

BLISS-32

the

have

the

following

CHAR _FOO:

BLISS-16

would

characters

from
three

not

are

allow

allowed

hold

this
per

use
is
characters

three

addresses within

CHAR_FOO would

literal

'FOO';

for

and

longword.

that
would

one
longword
be assigned to

1In memory,

the

representation:

0 O

value

(32)

assignment

because

string-literal.

This

the

fact that BLISS-16 works with a maximum of
8-bit ASCII characters require 24 bits.

two

ASCII

restriction

only

arises

16-bit

values

and

the 10/20 systems a word would
be
allocated
and
the
characters
would
be positioned starting at the high-order end of the word.
Thus
the string-literal would have the following representation in memory:

CHAR_FOO:

(36)

Even if the 10/20 string-literal had been right-justified in the word,
it
still would not equal the VAX-11 representation, numerically.
So,
in fact, the following would not be transportable:

WRITE

INTEGER(

'ABC'

);

since 'ABC' is invalid syntax in BLISS-16, has the
in BLISS-36, and the value 4276803 in BLISS-32.
Based

these

not

problems

use

with

representation

string-literals

our

numeric

value

first

values.

=-33543847936

guideline

is:

BLISS Transportability Guidlines

21-FEB-77 -- Rev 3

Page 14-24

TECHNIQUES

In those cases where it is necessary to perform a numeric operation
(e.g. a comparison) with a character as an argument, you must use the
$C form of integer literal. This literal takes one character as |its
argument and returns as a value the integer index in the collating
sequence of the ASCII character set, so that:
$C'B'

= 3X'42'

= 66

The $C notation was introduced to standardize the interpretation of a
ASCII-based environments.
possible
all
across
string
quoted
as "right-adjusting” the
of
thought
be
$C'quoted-character' can
bits.
$BPVAL
ning
contai
string
character in a bit

14.4.3.3

Usage As Character Strings -

The necessity of using more than one character in a literal leads us
to the other situation in which quoted strings are used: as character
strings.

To facilitate the allocation, comparison and manipulation of character

sequences, a built-in character sequence function package has been
introduced to the BLISS language. It has been implemented in BLISS-32
and BLISS-36 and plans exist to implement it in BLISS-16.

These built-in functions provide a very complete and powerful
operations on characters.

Our next guideline is:

set

You must use the built-in function package when allocating
and operating upon character sequences. This is the only way
one can guarantee the portability of strings and string
operations.

the
A more detailed description of these functions can be found e inGuide,
Character Handling Functions chapter of the BLISS-VAX Languag
Second Edition.

BLISS Transportability Guidlines

21-FEB-77 -- Rev

Page

14-25

TECHNIQUES

Initialization

PLITs And

14.4.4
14.4.4.1

Introduction

This section is primarily concerned with PLITs and their uses.
First,
there
is
general
discussion of PLITs and the contexts in which they
often appear.
A presentation of how scalar PLIT items should be
used
follows.
Next,
the
problems
involved
1in using string literals in
PLITs and suggested guidelines for their use are presented.
Finally,
the
use
of
PLITs to initialize data segments will be illustrated by
the development of a transportable table of values.

14.4.4.2

PLITs

General

Because BLISS values are a maximum of a machine word
in
1length,
any
literal
that requires more than a word for its value needs a separate
mechanism, and that mechanism is the PLIT (or
UPLIT).
Hence,
PLITs

are
a
means
for defining references to multi-word constants.
PLITs
are often used to initialize data segments (e.g.
tables) and are used
to define the arguments for routine calls.

PLITs
themselves
are
elements
and
their
transportable.

transportable;
however,
machine
representation

their
are

constituent
not
always

A PLIT consists of one or more values (PLIT items).
PLIT items may be
strings,
numeric
constants,
address constants or any combination of
these last three, providing that the value of each is known
prior
to
execution time.

14.4.4.3

Scalar

PLIT

Items

The first transportability problem that might be encountered with
the
vse
of
PLITs
1is in the specification of scalar PLIT items.
As with
any other declaration of scalar items (pointers, integers,
addresses,
etc.) it is possible to define them with an allocation-unit attribute.
For example, in BLISS-32, we can specify such machine
specific
sizes
as
BYTE
and
LONG.
Thus the following example is non-transportable
ana, i fact, will not compile on BLISS-36 or BLISS-16:

BIND

This

last example

Do not
PLIT

PLIT

provides

use

item.

BYTE(l,

the

first

allocation-units

LONG

-4);

PLIT guideline:

the

specification of

PLIT or

BLISS Transportability Guidlines

21-FEB-77 -- Rev 3

Page 14-26

TECHNIQUES

Thus, the BIND should have been coded as follows:
BIND

This last gquideline is necessary because of

the

differences

1in

the

sizes of words on the three machines, a feature of the architectures.
the
in
architectures
machine
of
A discussion of the role
:
entitled
section
the
1in
found
be
transportability of data can
entitled:
section
the
1in
"Data". Further guidelines are presented
"ITntializing Packed Data".

14.4.4.4

String Literal PLIT Items -

The next guideline is based on the representation of PLITs in memory.
Specifically the problem is encountered when scalar and string PLIT
items appear in the same PLIT.

The difficulty arises primarily from the representation of characters
on the different machines. A more thorough discussion of character
"Data:
entitled:
representation can be found 1in the section
Character Sequences”.

Care must be exercised when strings are to be used as items in PLITs.
For example, we may wish to specify a PLIT that consists of two
If we
elements: a 5-character string and an address of a routine.
specify

it as:

21-FEB-77 -- Rev 3

BLISS Transportability Guidlines

Page 14-27

TECHNIQUES

BIND

ABC ROUT);

CONABC = PLIT('ABCDE',

then the VAX-11 representation is as follows:
CONABC:

/ DCBA/

(32)

/ address /

(32)

/ B A/

(16)

/ D C/

(16)

E /

(16)

on the 11,

it would be:

CONABC:

/
/ address

and the 10/20 representation would be:
/ ABCDE/ (36)

CONABC:

/ address

(36)

The three PLITs are not equivalent. Three longwords are required for
the BLISS-32 representation, four words are needed for BLISS-16, and
two words are needed for the BLISS-36 representation. If we wished to
access the two elements of this PLIT by the use of an address offset,
we would have problems. For example, the second element (the address)
is accessed by the expression:

CONABC

in the BLISS-36 version, but not in the BLISS-32 or BLISS-16 versions.

For the BLISS-32 version, we would need the expression:
CONABC

...

BLISS Transportability Guidlines

Page 14-28

21-FEB-77 -- Rev 3

TECHNIQUES

and for BLISS-16,

it would have to be:
...

CONABC

...

Taking a data segment's base address and adding to it an offset (as in
A
to transportability.
particularly sensitive
is
case)
this
section
the
1in
found
be
can
addresses
of
discussion on the use

entitled:

"Data:

Addresses and Address Calculations".

to
This section on addresses suggests the use of the literal, %UPVAL,
of
number
the
is
value
Its
ility.
transportab
of
ensure some degree
already
As
(machine word).
addressable units per BLISS value
is 2;
it
BLISS-16,
1in
4;
equals
literal
the
BLISS-32,
in
discussed,
1.
is
value
its
6,
and in BLISS-3
Multiplying an offset by this value can,

some

address calculation that will be transportable.
second element in the above PLIT, one would write:
...

CONABC + 1*%UPVAL

cases,

ensure

So to access the

...

But this won't work for the VAX-1l representation. An offset value of
8 is needed because the string occupies two words (BLISS values). The
situation is similar for the 11 version, where the string occupies 3
words and would need a offset value of 6 not 2.

1in general, with
(and,
The problem with this particular example
literal but in its
string
a
of
use
the
in
not
1is
strings in PLITs)
that will
characters
of
number
the
Because
PLIT.
position within the
section:
the
(see
machines
three
all
on
differs
value
fit in a BLISS
will
PLIT
a
in
string
a
of
placement
the
),
Sequences
Data: Character
PLIT
remaining
the
for
ents
displacem
different
in
result
very often
'

items.

There is a relatively simple solution to this problem:

In a PLIT there can only be a maximum of one string

and that literal must be the last item in a PLIT.

Following this guideline, the example should have been coded:
BIND

CONABC = PLIT( ABC_ROUT,

'ABCDE');

literal,

BLISS Transportability Guidlines

21-FEB-77

-- Rev 3

Page

14-29

the

PLIT

TECHNIQUES

and

this expression:

CONABC

1*3%UPVAL

would have resulted in the address of
(in this case the string).

14.4.4.5

the

second element

An Example Of Initialization -

As mentioned in the beginning of this section, PLITs are often used to
initialize
data segments such as tables.
A data segment allocated by
an OWN or GLOBAL declaration can be initialized by using
the
INITIAL
attribute.
The
INITIAL
attribute
specifies the initial values and
consists of a list of PLIT items.
A good example which shows how relatively easy
it
1is
to
initialize
data in a transportable way is to illustrate the process one might use
to build a table of employee data.
Information on each employee
will
consist
of
three elements:
an employee number, a cost center number
and the employee's name.
The employee's name will be a fixed
1length,
5-character field.
For
example,
information:

1line

345

the

table

201

would

contain

the

MARKS

Converting this line into a list of PLIT items which conform
section's guidelines would result in the following:

(345,

following

201,

this

'MARKS')

Notice that no allocation units were specified and that the
character
string
was specified last.
We will now use this line to initialize a
small table of only one
line.
The
table
will
have
the
built-in
BLOCKVECTOR
structure
attribute.
The
table declaration would look
like:
OWN
TABLE:

BLOCKVECTOR([1,
3]
INITIAL
(

345,
201,
'MARKS'

) s

BLISS Transportability Guidlines

21-FEB-77

=--

Rev

Page

14-20

TECHNIQUES

A problem, however, has developed.
This definition would work well in
BLISS-36.
That
1is, three words would have been allocated for TABLE.
The first word would have been initialized with the
employee
number;
the
second
word
with the cost center;
and the third with the name.
But the declaration would not be
<correct
1in
BLISS-32
or
BLISS-16,
simply
because
not
enough storage would have been allocated for
the initial values.
BLISS-32 would have required 4 longwords and
'
BLISS-16, 5 words.

all
the

The problem arises as a
result
of
the
way
1in
which
strings
are
reprtesented
and
allocated
on
the
three machines (see the section:
Data:
Character Sequences).
The solution is simple.
We only need to
determine
the
number of BLISS values (words) that will be needed for
the character string on each machine.
There is a function
that
will
give
this
value.
It
1is
named CHSALLOCATION and it is part of the

Character Sequence Function Package.
It
takes
as
an
argument
the
number
of
characters to be allocated and returns the number of words
needed to represent a string of this length.
We can use this wvalue as
an allocation actual in the table definition, as follows:

OWN
TABLE
:

BLOCKVECTOR[1,2

CHSALLOCATION(S)]

INITIAL
(

345,
201,
'MARKS'

) ;

The declaration is now
transportable.
By
wusing
the
CHSALLOCATION
function we can be assured that enough words will be allocated on each
machine.
No recoding will be necessary.
We are free to add other
the
representation
or

lines to the table and not
allocation
of
the
data.

be concerned
with
Here is a larger

example of the same kind of table.
We won't develop it step by
but point out and explain some of the highlights.

step,

BLISS

Transportability

Guidlines

21-FEB-77

TECHNIQUES

The

Rev

Page

example:

Table

Parameters

LITERAL
NO_EMPLOYEES

EMP_NAME

SIZE

25,
5

EMP_LINE

SIZE

CHSALLOCATION (EMP_NAME SIZE);
1+

Employee

Name

Padding

Macro

MACRO
NAM
PAD (NAME)
E

NAME,

REP

CHSALLOCATION(EMP_NAME_SIZE

$CHARCOUNT (NAME))

Employee

Size:

Information

NO_EMPLOYEES

(0)

$%;

Table

EMP_LINE_ SIZE

EMP_TABLE:
BLOCKVECTOR [NO_EMPLOYEES,

EMP_LINE SIZE]

INITIAL
(

345,
201,
NAME_PAD ('MARKS

PETER'),

207,
345,
NAME

) 3

PAD('NASSI

ISAAC')

14-31

BLISS Transportability Guidlines

TECHNIQUES

21-FEB-77 -- Rev 3

Page 14-32

The literals serve to parameterize certain values that are subject to
EMP LINE SIZE has as its value the number of
literal
The
change.

words needed for a table
entry.
The
character
sequence
function,
number of words needed for EMP_NAME
the
returns
CHSALLOCATION,
- SIZE
-

characters.

The macro will, based on the length
of
the
employee
name
argument
zero-filled words to pad out the name field. Thus,
gererate
(NAME),
each
we are assured of the same number of words being initialized for
important
is
This
be.
might
size
its
what
matter
no
name,
employee
a
fixed 1length of
the
to
because storage is allocated according

character
course,

field

(employee

name).

be less than that value.

The actual string length may, of

This last example was developed with the specification that the
employee name field was fixed in length (EMP_NAME SIZE). What if,

however, we wished to have the table hold variable length names?

That

for certain reasons, we wished to allocate only enough storage to
is,
hold the table data, not the maximum amount.

is
The table structure developed above won't work because it
to
were
we
If
field.
predicated upon the constant size of the name
use variable length character strings, either too much or not enough
storage would be allocated. And there would be no consistent way of
We
accessing the employee name (where would the next one start?).
in
determine
name,
employee
every
of
if we knew the 1length
could,
practical
very
a
not
is
this
But
needed.
advance the number of words
solution.

One transportable solution is to remove the character string from the
table and replace it with a pointer (a word in length) to the string.
The Character Package has a function, CH$PTR, which will construct a
pointer to a character sequence. As an added benefit, this pointer
can be used as an argqument to the functions in the Character Package.
The cost of this technique 1is the addition of an extra word (the
character sequence pointer)

for each table entry.

BLISS Transportability Guidlines

21-FEB-77 -- Rev 3

TECHNIQUES

Page 14-33

Here is a typical example, again based on the employee table:

Table

Parameters

LITERAL

NO_EMPLOYEES = 2,
EMP_LINE_SIZE = 3;
1+

Macro to construct a CS-pointer to employee name

| -

MACRO
NAME PTR(NAME)

=
CHSPTR(UPLIT(

NAME

))

§%&;

Employee Information Table

Size:

NO_EMPLOYEES by EMP_LINE_SIZE
-

OWN

EMP_TABLE:

BLOCKVECTOR [NO_EMPLOYEES,

EMP_LINE_SIZE]

INITIAL(

345,
201,
NAME PTR('MARKS

PETER'),

207,
345,
NAME PTR('NASSI

ISAAC')

) :

14.4.4.6

1Initializing Packed Data -

transportability considerations
In this section we will discuss some
By packed data, we
1initialization of packed data.
in the
involved

mean that for data values vl, v2, ..., vn with bit-positions pl, p2,
pn and bit-sizes of sl, s2, ..., sn, respectively, the value of
...,

BLISS

Transportability

Guidlines

21-FEB-77

represented

the

vl1"pl

OR v2"p2 OR

...

OR vn'pn

Rev

Page

14-34

TECHNIQUES

the

PLIT-item would

following

expression:

where

and

for

all

max(pl,

p2,

...

pn)

$BPVAL

$%$BPVAL

1
-2**g]

The

...,

OR operator

could

2**(si

replaced

the

addition

operator

(+),

but

the
result would be different if, by accident, there were overlapping
values.
Notice that the packing of data in a transportable manner
is
dependent on the value of $BPVAL.

We will

illustrate

the

initialization of packed data by modifying

employee
table
example
field within a block, it

reference

(i.e.,

that
is a

offset,

example, the field
would look like:

was developed above.
common
practice
to

position

reference macros

and

for

size)

the

When
make

into a macro.

original

the

accessing a
each
field

So,

employee

for

table

MACRO

0,0,%BPVAL,0
1,0,%BPVAL,0
2,0,%BPVAL,0

EMP ID

EMP_COST_CEN
EMP_NAME PTR

§,
%,
%;

We can make use of these macros in developing an initialization macro.
In
essence,
we
are making use of some already parameterized values.
This is another example of how we can use parameterization as
one
of
the key techniques in writing transportable code.
If we
ELMP_ID

knew

that

and

two fields

the

number

EMP_COST_CEN

bits

would

into one BLISS value

each

needed
not

represent

exceed

16,

the
could

in BLISS-32 and BLISS-36.

values
pack

these

In BLISS-16

the definition of the employee table, as it now stands, would allocate
only 16 bits for each field, since $BPVAL equals 16.
1In BLISS-36,
we
will
<choose to use an 18-bit size for these two fields, since we know
that both DECsystem-10 and
DECsystem-20
hardware
have
instructions
that operate efficently on half-words.
Thus,

for

BLISS-36

and

BLISS-32

the

field

reference

macros

like:

MACRO
EMP_ID

EMP_COST CEN

0,0,%¥BPVAL/2,0 &,
0,%BPVAL/2,%BPVAL/2,0

would

1look

BLISS Transportability
TECHNIQUES

Guidlines

21-FEB-77

EMP_NAME PTR

Based

arguments

these

the

macros,

initial

can

values

now

and

1,0,%BPVAL,0

write

then do

Rev

Page

14-35

macro

the

that

proper

will

packing:

take

MACRO
SHIFT(W,P,S,E)

EMP INITIAL(ID,CC,NAME)
(]

ID*SHIFT(EMP=ID) OR
!
CC“SHIFT(EMP_COST_CEN)
NAME PTR

(

First
P

NAME‘SHIFT(EMP_NAME_PTR))
!

The macro
reference

Second

SHIFT simply extracts the position parameter
of
the
macro.
The initialization macro, EMP INITIAL, makes

this shift value

in packing the words.

The goal here

the
wuser
to
specify
as
arguments
only
the information
initialize the table, and not to specify information that is
its representation.

field
use of

require

needed to
part
of

BLISS Transportability Guidlines

21-FEB-77 -- Rev 3

Page

14-36

TECHNIQUES

An example of using these macros to

initialize packed data follows:

Employee

Field

Reference

macros

MACRO

EMP ID
= 0,0,%$BPVAL/2,0 %,
EMP_COST_CEN
= 0,%BPVAL/2,%BPVAL/2,0
EMP_NAME PTR
= 1,0,%BPVAL,0 %;

MACRO
!+

!
!

Macro to create the shift value from the
position parameter of a field reference macro

SHIFT(W,P,S,E)

!
!

Employee table initializing macro
Three values are required

EMP_INITIAL(ID,CC,NAME)[]

ID"SHIFT
(EMP ID) OR
CC"SHIFT
(EMP COST CEN)

NAME"SHIFT
(EMP NAME PTR)

!
%;

First
!

Second

Employee table definition and

initialization

OWN

EMP

TABLE:

BLOCKVECTOR [NO_EMPLOYEES,
INITIAL(

EMP_LINE SIZE]

EMP_ INITIAL(
345,
201,
'MARKS PETER’,
207,

345,
'"NASSI

ISAAC'

))

What

has

been

illustrated

the

example

the

parameterization
of
certain
values
such
as
field
sizes.
In
transporting this program we can
benefit
from
the
localization
of
certain machine values as in the field reference macros.
This code is

BLISS

Transportability

TECHNIQUES

Guidlines

transportable between BLISS-32
with
the
BLISS-16
compiler,

and
we

21-FEB-77

Rev

)

age 14-37

BLISS-36.
To compile this
program
need to change the field reference

macros.
The packing macros would no longer
be needed,
thofiéfi-—£5;§
could be used for consistency purposes.
In that case, they would also
need

changed.

a final example of initializing packed data,
BLOCK
structure
that
1is
defined
in section

Language

are
with

Guide.
Details as to
discussed in the Language
initializing this type of

will
use
another
12.7.3 of the BLISS-32
what DCB is and how
it
accesses
data
Guide.
Here, we will only be concerned

structure.

?he DCB BLOCK consists of five fields.
Four of the fields are
packed
into
one word, their total combined size being 32 bits, and the fifth
field which is 32 bits in length occupies another word.
In this
easily

case it
between

is possible to transport the DCB
initialization
very
BLISS-32
and BLISS-36.
The reason is that the total
number of bits required for each word does not
exceed
the
wvalue
of
¥BPVAL for each machine.
Hence, in this case at least, we do not have
to modify the design of the BLOCK in any way.
Typically, however, one
would
design
the
structure
for
each target machine.
This is most
easily accomplished by placing its definition in a REQUIRE
file.
We
will
again
make
use
of the field reference macros as we did in the
previous example.

21-FEB-77 -- Rev 3

BLISS Transportability Guidlines

Page 14-38

TECHNIQUES

ized.
Here is the example showing a way in which it could be initial
The
CTOR.
BLOCKVE
a
it
making
by
re
structu
the
d
Wwe have extende
example:

DCB

LITERAL

size

parameters

DCB_NO_BLOCKS = total number of blocks,
DCB_SIZE = size of a block;

DCB Field Reference macros

MACRO

A = 0,0,8,0 %,
DCB
B = 0,8,3,0 %,
DCB
DCB_C = 0,11,5,0 %,
D = 0,16,16,0 &,
DCB
E =1,0,32,0 %;
DCB

MACRO
I+

1 Macro to create the shift value from the
! position parameter of a field reference macro
SHIFT(O,P,S,E)
L+

= P %,

DCB initializing macro.

Five values are required.
=

DCB_INITIALIZE(A,B,C,D,E)[]

A“SHIFT (DCB_A)
B"SHIFT (DCB_B)
C"SHIFT (DCB_C)
D"SHIFT (DCB D)

OR
OR
OR
,

E"SHIFT (DCB_E)

§;

DCB Blockvector definition and initialization

| P

OWN

DCB_AREA:

BLOCKVECTOR[DCB_NO BLOCKS, DCB_SIZE]
(
INITIAL

DCB INITIALIZE
1,2,3,4,

21-FEB-77

Rev

Page

14-39

= O

BLISS Transportability Guidlines
TECHNIQUES

Note that this structure could be transported to
BLISS-16
by
making
suitable
changes to the field reference macros and the packing macro.
The only consideration might be whether the
1last
field,
DCB E,
did

require a full 32 bits.

14.4.5

Structures And Field Selectors

14.4.5.1
1Introduction - Two BLISS constructs
will
be
discussed
1in
this
section:
structures and field selectors.
While the use of one
does not necessarily imply the use of the other, we will see that
for
transportability
reasons
field
selector
wusage
will be confined to
structure declarations.
Hence,
these
two
constructs
need
to
be
discussed

together.

We will begin with a general discussion of
structures,
in
which
it
will
be
shown
that a certain machine specific feature of structures
can be used in a transportable manner.
The best way to illustrate the
process
of
writing
transportable
structures
1is to take the reader
through the intellectual considerations that contribute to its design,
so
the
development of a transportable structure - FLEX VECTOR - will

be presented.
Finally,

14.4.5.2

this

a more general

Structures

point

field

structure

selectors

will

GEN VECTOR - will

discussed.

developed.

Structure declarations are sensitive to transportability in
that
one
may
specify parameters corresponding to characteristics of particular
architectures.
Also, in BLISS-32,
the
reserved
words
BYTE,
WORD,
LONG,
SIGNED,
and
UNSIGNED
have
values
of
1,
2,
4,
1
and
0
respectively when used as structure actual parameters.
We can take advantage of the ability to specify architecture-dependent
information in developing transportable structure declarations.
Later
in

this section we will develop a structure which will

use

the

UNIT

parameter
to
gain
a degree of transportability.
The UNIT parameter
specifies the number of
addressable
allocation-units.
This
number
will
be
allocated

used
in
determining
the
amount
for each element of the structure.

As
mentioned
transportability

storage

that

repeatedly
problem is

in
these
guidelines,
the
prime
differing machine architectures.
Machine
aren't the same.
That is, the number of
bits

word-sizes, for example
per
machine-word
differs on all

three machines.
The machine word is
also the maximum size of a BLISS value.
There are two other important
architectural
differences:
bits per address and bits per addressable

unit.

Page 14-40

21-FEB-77 -- Rev 3

BLISS Transportability Guidlines
TECHNIQUES

Bits per address is the maximum size, in bits, of a memory address.
in bits, of the smallest
is the size,
addressable-unit
Bits per
directly addressable unit in memory.

per
bits
value),
(BLISS
word-size
machine
of
values
The
addressable-unit and bits per address for the three machines have been
$BPUNIT
$BPVAL,
names
implemented as predeclared literals, with the

A table of their values can be seen in the

and $BPADDR, respectively.

"Literals".

section entitled:

14.4.5.3

FLEX_VECTOR -

We can make use of these

let's

state

values

developing

FLEX VECTOR.

the use to which this structure will be put:

First

We wish to

define a structure that will by default allocate and access a vector
If the default
smallest addressable units.
consisting of only the
want to be
we
used,
not
is
declaration
structure
the
in
value given

able to specify the vector element size in terms of the number of
It should be noted that the existing VECTOR mechanism will not
bits.

this.

The
For example, we would like to have a vector of 9-bit elements.
each
first decision that has to be made is whether or not we want
For this example,
element to be exactly 9 bits, or at least 9 bits.
we choose the smallest natural unit whose size is greater than or
addressable
(in length)
Since there are no 9-bit
equal to 9 bits.

units

units.

on any of the machines, we have a choice of 8, 16, 32 or 36-bit

We can see that 9 bits will fit in the only addressable

unit

the

On the 11 we will need two bytes or a
10/20 systems - the word.
we will again need two bytes.
machine
16-bit word and on the VAX-11l

How then do we develop a structure that will do this allocation and
will also be transportable and usable on the three systems? Clearly
the structure will need some knowledge of the machine architecture.
This is where the role of parameterization comes in.

1In fact we
The predeclared literals have all the information we need.
($BPUNIT).
e-unit
addressabl
per
bits
values
of
set
one
need only

Oth.r formals
This parameter will be one of the allocation formals.
that we will need are the number of elements (N) and the index

parmeter

(I)

We begin

FLEX VECTOR:

for accessing the vector.

showing

STRUCTURE

the

access

FLEX VECTOR[

and

allocation

formal

I; N, UNIT = $BPUNIT, EXT = 1 ]

1list

for

BLISS Transportability Guidlines

21-FEB-77

Rev

Page

14-41

TECHNIQUES

Notice that by
not specified)
Now

The
and,

must

setting
will be

develop

UNIT ecual
%BPUNIT.

formula

for

the

¥BPUNIT

the

default

(if

structure-size

UNIT

expression.

expression
will
make
wuse of the allocation formals UNIT and N:
in addition, the value of the parameter S$BPUNIT.

If UNIT were only allowed to
$BPUNIT
(i.e.
1*$BPUNIT,
structure-size expression of

Dividing

the

element

size

assume values
of
integer
multiples
of
2*3%BPUNIT,
etc.),
we
would only need a
the following form:

(UNIT)

each
element
in
the
vector
value would then be multiplied
total

size

the

data

$BPUNIT would

qive

must

[

size

allocated.

We wish, however, for the structure to be more
flexible
will be able to specify any size element (within certain

structure-size

the

in terms of an integer multiple.
This
by the number of elements to
give
the

in
that
we
limits).
The

slightly more complex:

(UNIT

$BPUNIT

]

The structure-size expression now computes enough
$BPUNIT's
to
hold
the
entire
vector.
The
reader
should try some values of UNIT for
differing $BPUNIT in order to see how this expression evaluates.
This

sub-expression:

(UNIT

which we will

call

transportability

NO OF UNITS

$BPUNIT

very

and flexibility

S$BPUNIT

important

effecting

the

of this particular structure.

The

key to transporting this structure is the knowledge that it has
of
a
certain
machine
architectural parameter:
bits per addressable-unit.
Th:- narticular expression makes use of this knowledge, hence, it
can

adapt
t¢ any machine.
This sub-expression will
the structure-body expression.
The

structure-body

address-expression.

used

This

twice more

expression

consist of the name of the structure (the base address) plus
based on the index I.
1In addition, a field selector will be
access the proper number of bits at the calculated address.
The offset
index
1I.
the

field

will

an offset
needed to

is simply the
expression
NO_OF _UNITS
multiplied
by
the
(Remember that indices start at 0).
The size parameter of
selector

the

expression

NO_OF UNITS

multiplied

the

BLISS Transportability Guidlines

Page 14-42

21-FER-77 -- Rev 3

TECHNIQUES

size

like:

The structure-body will look

an addressable-unit - $BPUNIT.

(FLEX_VECTOR +

I *

((UNIT + $BPUNIT - 1)

/ $BPUNIT))

<0, ((UNIT + $%BPUNIT - 1)/%BPUNIT)*%BPUNIT,BXT){

parameter

1in

the

field-selector

The following table shows the structure

the

three

The value of

the

position

constant 0 for we are always starting at an addressable boundarvy.
different values of UNIT:

machines

a
for

vaX-11

UNIT = 0

no storaqge

UNIT =1 to 8

[N * 1] Bytes

UNIT = 9 to 16

[N * 2] Bytes

UNIT = 17 to 32

[N * 4] Bytes

FLEX_VECTOR<0,0,1>

(FLEX_VECTOR + 1)<0,8,1>

(FLEX_VECTOR + I *

2)<0,16,1>

(FLEX_VECTOR + I * 4)<0,32,1>

UNIT = 0 to 16

same as VAX-11

10/20

UNIT = O

no storage
(FLEX_VBCTOR)(0,0,I)

UNIT = 1 to 36

[

N ] Words

(FLEX_VECTOR + I)<0,36,1>

From the table above we can see that if the default value for UNIT
were set to $BPVAL, this structure would be eauivalent to a VECTOR of
longwords on VAX-11, and a VECTOR of words on the 10/20 and 11
systems.

Elements in a data seagment which has this particular structure
attribute are accessed very efficiently because they are always on
addressable boundaries. Also, they are always some multiple of an
addressable unit

in length.

BLISS Transportab111ty Guidlines

21-FER-77 -- Rev 3

TECHNIQUES

Page 14-43

If we
wish
this
structure
to
access
elements
exactly
the
specified
then
we
need
only change the size parameter of the
selector.

This

expression

...

This

is a

then becomes:

FLEX VECTOR<O,

UNIT>;

less efficient means of accessing data

multiple

S$%BPUNIT)

14.4.5.4

Field

size
field

because

the

compiler

(when UNIT is

needs

selecting instructions in the case of the VAX-1l1]
and a series of masks and shifts for the 11,

and

to generate

10/20

not

field

machines

Selectors -

In the last structure declaration, it was necessary to make use
of
a
field
selector.
At this, we will discuss the use of field selectors
in a more general context.
The use of field selectors can be non-transportable because they
make
use
of the value of the machine word size.
The unrestricted usage of
field selectors may cause problems in a program when it
is
moved
to
another machine.
These problems are best illustrated by the following
table of restrictions on position (p)
and
size
(s)
for
the
three
machines:

Machine:

10/20

0<p
< 36

< s

p+s

<36

0 <
p,

From

the

table

can

The most

The

moderate

The

least

If we wished
would
have

to
to

see

<o
<16

s <16
S

0 <

the

constant

that:

restrictive

the

restrictions

restrictive

ensure
abide

VAX-11

11.

are

those

10/20.

is VAX-11l.

the transoortable use of
field
selectors,
we
by the set of restrictions imposed in BLISS-16.

These, however, are restrictions imposed by the values
of
There
is also a contextual restriction on the use of field
The following guideline should be followed:

Field
selectors
may
only
user-defined structures.

appear

1in

the

p
and
s.
selectors.

definition

Page 14-44

21-FEB-77 -- Rev 3

BLISS Transportability Guidlines

TECHNIQUES

By restricting the domain of field selectors to structures, we are

1in

will

fact isolating their use.

We will now develop another transportable structure which
affected by the table of field selector value restrictions.
14.4.5.5

GEN_VECTOR -

You have probably noticed that FLEX_VECTOR does not attempt to pack
data. Using the example of 9-bit elements, we can see that there27 will
on
be some wasting of bits - from 7 bits on the 11 and VAX-11 to
the

10/20

systems.

e a certain
We can develop a variation of FLEX_VECTOR which will provid
elements it
9-bit
of
For example, 1in the case
degree of packing.
word and
10/20
a
would be possible to pack at least four of them into this vector
is not
y,
Unfortunatel
three into a VAX-11 1longword.
its
of
on
ficati
identi
the
and
maximally transportable, but its design
non-transportable aspects should be very helpful.

This structure, which will be named

GEN_VECTOR,

will

pack

many

will make use of
elements as possible into a BLISS value (word) so wealloca
tion 1is 1in
since
But,
.
%BPVAL
l
the machine specific litera
as a value the
rerms of $BPUNIT, we will need a literal that has
l has been
number of allocation units in a BLISS value. This thelitera
name $UPVAL, and
predeclared for transportability reasons and has
is de{ined as %BPVAL/%BPUNIT.

Elements will not cross word boundaries.

hecause

the

restrictions

parameter of a 10/20 and 11

placed

field

This constraint is in effect

the

selector.

value of the position

For

the

same

reason

elements can not be longer than 3%BPVAL, as given in the table of field
selector restrictions above.

of GEN_VECTOR will need
As in FLEX VECTOR, the allocation expression units
needed by the entire
to calculate the number of allocation
nts (N) and
of
vector. This will again be based on the number e theeleme
ts will be
elemen
But becaus
the size of each element (S).
more complicated.
packed, the expression will be slightly

The first value we need is the number of elements that will fit
BRLISS value.

The expression:

1in

($BPVAL/S)

number of BLISS
will compute this value. Given this, to obtain thewe divide
this value
,
vector
entire
the
for
values or words needed
into

BLISS Transportability Guidlines

21-FEB-77 -- Rev 3

Page

14-45

TECHNIQUES

(N/ ($BPVAL/S))

We now have the total number of words (in
wunits
of
$BPVAL)
needed.
However,
data
1is
not
allocated
by
words on both of the machines.
Multiplying this
wvalue
by
SUPVAL
will
result
in
the
number
of
allocation units needed by the vector:

((N/($BPVAL/S)) *$UPVAL)

For clarity's sake and because this expression will be used
will make it into a macro with N and S as parameters:

again

MACRO

WHOLE
VAL (N,S)

((N/(¥BPVAL/S)) *%UPVAL) %;

The name of the macro suggests that we have calculated the
number
of
whole
words
needed.
1If, in fact, N were an integral multiple of the
number of elements in a word then this macro would be
sufficient
for
allocation purposes.

Since we can't
count
on
this
always
happening,
we
need another
expression
to calculate the number of allocation units needed for any
remaining elements.

The number of elements

of the last division in this expression:

left over

the

remainder

(N/ ($BPVAL/S))

The MOD function will

calculate

(N MOD

this value,

follows:

($BPVAL/S))

If we then multiply this value by the size of
each
element
have the total number of bits that remain to be allocated:

(N MOD

(%BPVAL/S))

will

This value will always be strictly less than
$BPVAL.
For
the
same
reasons
outlined above we will make this expression into a macro with
N

and

parameters:

BLISS Transportability
TECHNIQUES

Guidlines

21-FEB-77

Rev

Page

14-46

MACRO
PART

VAL(N,S)

((N

MOD

Taking this value, adding
a
$BPUNIT
will
give
us
the
remaining bits:

(%BPAVAL/S))

S)%;

"fudge
factor"
and
then
dividing
number of allocation units needed for

(PART VAL(N,S)

The total
structure

%BPUNIT

-1)/%BPUNIT

number of allocation
units
has
been
allocation expression will look 1like:

(WHOLE_VAL(N,S)
(PART VAL(N,S)

by
the

calculated

and

the

+
+

$BPUNIT

1)/%BPUNIT]

As it works out, the structure-body expression for GEN VECTOR will
be
simple
to
write
because
of
the expressions that have already been
written.

The accessing of an element in GEN _VECTOR requires that we compute
an
address offset which is then added to the name of the structure.
This
of fset is some number of addressable units based on the value
of
the
index
1I.
We
already
have
an expression which will calculate this
number of addressable units.
It is the macro
WHOLE VAL.
Thus,
the
first part of the accessing expression will look like:

GEN_VECTOR

Note

that

the macro was

called with

WHOLE VAL(I,S)

the

index

parameter

This expression will result in the structure
being
aligned
on
addressable
boundary.
But
since
the element may not begin at
point (that is, the element may be located
$BPVAL
bits
1in length), one more value 1s
pos.tion parmeter of
a
field
selector.

calculate

this

value

based

the

index

some
this

somewhere
within
a
unit
needed.
That value is the
The
macro
PART VAL
will

The

size parameter is the value S.
The
position
parameter
will
be
calculated at run-time, based on the value of the index I. . Since I is
not constant, we can no longer use this structure
in
BLISS-16.
The
position
and
size parameters of a field selector in BLISS-16 must be
[

BLISS

Transportability

Guidlines

21-FEB-77

TECHNIQUES

compile-time

constants.

See

the

above.

This
will

completes the
look like:

definition

table

GEN

Rev

field

VECTOR.

Page

selector

14-47

restrictions

The

entire

1)/%BPUNIT]

declaration

STRUCTURE
GEN_VECTOR[I;N,S,EXT=1]

[WHOLE_VAL(N,S)
(PART
(GEN

VAL(N,S)

VECTOR

$BPUNIT

WHOLE VAL(I,S))

<PART_VAL(I,S),S,EXT>;

The reader should compile
BLISS-32 and BLISS-36.

14.4.5.6

No
the

Summary

this

structure

and

see

how

works

claim

is made that either
problems associated with

will have unique and
not
been discussed,
examples
a
feeling

these two structures
will
solve
all
transporting vectors.
Many such problems
different solutions.
BLOCKS or BLOCKVECTORS have

but it is
for
the

structures.

hoped that the reader will
techniques
1involved
in

get from the
transporting

There is no easy solution to transporting data structures.
One should
consider,
when
developing
data
structures,
the
machines that the
program or system is targeted for and make full use of the predeclared
literals such as %$BPUNIT.
This exercise in
the
development
illustrated two points:

parameterization

field

selector

By parameterizing
advantage

of
transportable

The

transportable

structures

has

and

usage.

certain machine-specific

the powerful
structures.

STRUCTURE

values

mechanism,

and
we

have

accessing of odd (not addressable) units of data
is
by the use of field selectors.
The field selector should
in structure declarations.

taking

full

developed

two

accomplished
only be used

BLISS Transportability Guidlines

TECHNIQUELS
[end

chapter

14}

21-FEB-77 -- Re

v 3

_
8
Page 14-4

Digital

Equipment

Title:

VAX-11

Corporation

Software

Ena.

Specification

Status:

draft

Architectural

Status:

vuvnder

File:

SEl15R3.RNO

PDM

not

Date:

COMPANY

CONFIDFNTIAL

Diagnostic

ECO

Conventions

Page

Rev

control

used

28-Feb-77

Superseded

Specs:

Diagnostic

Author:

Bernaby

Typist:

Conklin

Reviewer(s):

Abstract:

Conventions

Kenney

Chapter
to
the

15 contains the diagnostic conventional
extensions
rest of this document.
It represents an effort to

produce diagnostic

Revision

Codina

products

consistent

manner.

History:

Rev

Description

Rev

Original

Rev
Rev

2
3

skipped to maintain numbers
Integrated with SE manual

Author
F.

Bernaby

Conklin

Revised

Date
Sep-76

28-Feb-77

Diagnostic conventions

15-1

Diagnostic

Conventions

28-Feb-77

Change History
Rev

[End

Rev

Just

merge

Update

file.

module

of SE15R3.RNO]

preface.

Rev

_
Page 15-990

CHAPTER
DIAGNOSTIC

CONVENTIONS

28-Feb-77

15.1

Rev

INTRODUCTION

vaX-1l1l diagnostics will be written
expressed in this manual.
These conventions will
1.

achieve clear

adc:ted

and

in conformance with

the conventions

to:

meaningful

documentation

individual

tests.

reduce

the

need

for

diagnostic

users

simplify the program maintenance task.

analyze

test code.

Diagnostic Conventions
DIAGNOSTIC

15.2

SECTIONS

Page 15-2

28-Feb-77 -- Rev 3

DIAGNOSTIC SECTIONS

Each diagnostic will be sub-divided into 15 sections.
provide a logical way of partitioning the program,
PROGRAM

HEADER

PROGRAM EQUATES
PROGRAM DATA
PROGRAM TEXT
PROGRAM ERROR REPORT
HARDWARE PTABLE
SOFTWARE PTABLE
DISPATCH TABLE
REPORT CODE
INITIALIZE CODE
CLEANUP CODE

PROGRAM SUBROUTINES
HARDWARE TEST
HARDWARE PARAMETERS

SOFTWARE PARAMETERS

These

sections

provides the module nreface for vrogram
area for macro & symbol definitions
area for data used by more than one test
area for all ASCII messages
area reserved for print module
table of hardware parameters
table of software parameters
table of test addresses for test sequencing
print module for statistical reports

routine for initializing unit under test (ut)
routine for cleaning up error states in u
area for routines used by more than 1 test
actual diagnostic test code
code used by supervisor to get hardware
ptable entries
code used by supervisor to get software
ptable

entries

Diagnostic Conventions

DIAGNOSTIC SECTIONS

15.2.1

Page 15-3

28-Feb~77 -- Rev 3

Program Header Section

SYSEXR - System exerciser
/2-3/

MAYNARD,

MASSACHUSETTS 01754

THIS SOFTWARE 1S FURNISHED
UNDER A LICENSE FOR USE ONLY ON A SINGLE
COMPUTER
SYSTEM AND
MAY BE
COPIED ONLY WITH
THE INCLUSION OF THE
ABOVE COPYRIGHT NOTICE.
THIS SOFTWARE, OR ANY OTHER COPIES THEREOF,
MAY NOT BE PROVIDED OR
OTHERWISE MADE AVAILABLE TO ANY OTHER PERSON
EXCEPT FOR USE ON SUCH SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE
TERMS.
TITLE TO AND
OWNERSHIP OF THE
SOFTWARE
SHALL AT ALL TIMES
IN DEC.

REMAIN

THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE
AND SHOULD
NOT BE CONSTRUED
AS A COMMITMENT
BY DIGITAL
EQUIPMENT
'

CORPORATION.

DEC ASSUMES
NO
RESPONSIBILITY
FOR
THE USE OR
RELIABILITY OF ITS
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC.

FACILITY:

diagnostic exerciser

ABSTRACT:

"¢

.TITLE
.IDENT

ENVIRONMENT:

System

AUTHOR:

Frank Bernaby,

CREATION DATE:

16-Sep-76

MODIFIED

BY:

VWG

This program will exercise the VAX-11 system. It generically
treats devices as magtape, disk, or terminals.
Up to 32 units may be selected for testing.

02
03

Joe Hacker, 4-Jul-77: VERSION 2
Added I/0 tests for 6250 tape drives.
Brought module preface to standard form.

Diagnostic Conventions

DIAGNOSTIC

15.2.2

SECTIONS

Page 15-4

28-Feb-77 -- Rev 3

Program Equates(declarations)

<EXAMPLE>
s ++

CONTROL

-y

LISTING

LIST

s LIST

MACRO'S

MACRO

CONDITIONALS

EXPANSION

sNO

MC,MD,CND
ME

MACRO LIBRARY CALLS

-9

.NLIST
.LIST

0QIO$S,Q0I0$C,DPBS,WTEFSC

INCLUDE

FILES:

SYSMAC.SML

we¢

.MCALL

s ++

;

EXTERNAL SYMBOLS:

DEBUG

’

.GLOBAL DEBUG

; ENTRY

POINT OF

DEBUGGER

s ++

; EQUATED SYMBOLS

UBA REGISTER DEFINITIONS

-y

weo

;s ++

UBA_BASE_ADDRESS=177000

UBA_CSR_OFFSET=0
UBA_FMR-OFFSET=2
UBA_IRP_OFFSET=4
UBA_IRC_OFFSET=6
UBA Sv4 UFFSET=10
UBA SVS OFFSET=12
UBA_SV6_OFFSET=14
UBA SV7 _OFFSET=16

;UBA

BASE

ADDRESS

; CONTROL/STATUS REGISTER
; FAILED

MAP

; MAP

POINTER

; MAP

CONTFENTS

; REQ
; REQ
; REQ
; REQ

SEND
SEND
SEND
SEND

VECTOR #4
VECTOR #%
VECTOR = !
VECTOR #7

Diagnostic
DIAGNOSTIC

15.2.3

Conventions
SECTIONS

28-Feb-77

Rev

Page

Program Data

WNE

+
+

THIS

TABLE

MUST

UBA

ADDRESS

IS REFERENCED WHEN ONE OF THE UBA REGISTERS
ADDRESSED. THE UBA REFERENCE IS AN INDIRECT
REFERENCE THROUGH THIS TABLE. EXAMPLE:

TABLE

WTM

@UBACSR, RO

;READ

CSR

INTO

MOVW

TABLE_UBA_ ADDRESSES:

UBACSR:

.LONG

UBAFMR:

.LONG

UBAIRP:

UBAIRC:

.LONG

UBA BASE ADDRESS+UBA

UBASV4:

.LONG

UBA BASE ADDRESS+UBA
_Sv4

UBASV5:

BASE

ADDRESS+UBA

FMR

OFFSBT

IRP_OFFPSET
.

UBATM
_BASE ADDRBSS+UBA IRC OFFSET
OFFSET

UBATM
_BASE ADDRBSS+UBA SV5 _OFFSET
"~

.LONG

UBASV7:

UBA

.LONG

BASE

ADDRESS+UBA SV6 _OFFSET

UBA BASETM ADDRESS+UBA Sv7 OFFSET

+
+

UBA

.LONG

UBASV6:

DEVICE

STATUS

BUFFER

THIS

THE

UBA_BASE_ADDRESS+UBA_CSR_OFFSET

AREA

RESERVED

CONCLUSION OF
VIA

THE

FOR

STORING

DEVICE

I/0 OPERATION.
QIO

THIS

STATUS

MECHANISM.

PROVIDED

DEVICE

STATUS:

.BLKL

s RESERVE

LONG

WORDS

15-5

Diagnostic Conventions
DIAGNOSTIC SECTIONS

15.2.4

Page 15-6

28~-Feb-77 -- Rev 3

Program Text

s ++

;

QUESTIONS

’

QST1 UBA BASE:

QST2 UBA_VECTOR:
OST3 UBA LEVEL:
QST4 RECORD LENGTH:
QSTS_DATA_PATTERN:

.ASCIZ

.ASCIZ
.ASCIZ
.ASCIZ
.ASCIZ

SENTER

UBA BASE

ADR:

SENTER UBA VECTOR ADR:

SENTER UBA BR LEVEL: %
SENTER RECORD LENGTH: %
SENTER DATA PATTERN: %

FORMAT STATEMENTS

-y

RKCS_DECODE:

FMT1

FMT2_TIMEOUT:

KLEN/

FMT3_MACHINE_CHECK:

FMT4 SEEK_ERROR:

.ASCIZ

/SARKCS: $XWSA :
/SATIMEOUT WHILE

.ASCII

/SAMACHINE CHECK ABORT: $XWEN3XW3A ITEMS/
/ ON STACK, PC= $XL%A SP= RXLIN/
/SASEEK BAD ERROR REGISTER: $XW8N/
/SNSNSAPROGRAM ABORTING OPERATIONSN/
/SNPROGRAM SUMMARY/
/SNWORDS TRANSFERRED: $%XL/
/SNHARD ERRORS: S$XL/
/$SOFT ERRORS: S$XL%N/

.ASCIZ

FMTS5 ABORT:

.ASCIZ

.ASCII

FMT6 PROG_SUMMARY:

.ASCII

.ASCIZ

SRWSN/
REFERENCING RKO5 REGISTEI

Diagnostic
DIAGNOSTIC

15.2.5

Conventions
SECTIONS

Program Error

28-Feb-77

Rev

Page

15-7

Report

PRINT ENTRY

POINTS

FOR

ERROR

MESSAGES

A
2 4

MSGl_TIMEOUT:

PRINT
PRINT

RSB

MSG2_MACHINE_CHK:

PRINT
RSB

MSG3_DEV_STATUS:

PRINT
RSB

FMTZ_TIMEOUT,(R]>
FHTS_ABORT,

;s PRINT TIMEOUT
; PRINT ABORT
s EXIT

FMT3_MACHINE_CHECK,<R6,R7,(RB),R9>

FMTl_RKCS_DECODE,<R3,#BITRKCS)
s EXIT

Diagnostic Conventions
DIAGNOSTIC

15.2.6

SECTIONS

Page 15-8

28-Feb-77 -- Rev 3

Hardware Ptable

+
+

HARDWARE

PARAMETER TABLE FOR PROGRAM

THIS TABLE PROVIDES THE REQUIRED HARDWARE PARAMETERS
FOR TEST EXECUTION. THE ENTRIES ARE OBTAINED FROM EITHER
THE USER VIA GPHRD COMMANDS OR FROM THE SYSTEM
CONFIGURATION TABLE.

HARD UBA:

HARD UBA_BASE:

.LONG

HARD UBA_LEVEL:

.LONG

HARD_ UBA_VECTOR:

15.2.7

.LONG

;BASE ADDRESS OF UBA

;UBA VECTOR ADDRESS
;UBA BR LEVEL

Software Ptable

+
+

SOFTWARE PARAMETER TABLE FOR

PROGRAM

THIS TABLE CONTAINS ALL THE REQUIRED SOFTWARE PARAMETERS.
THESE PARAMETERS ARE OBTAINED VIA GPSFT COMMANDS.

SOFT_UBA:

SOFT_RECORD_LENGTH:

.LONG

; RECORD LENGTH

SOPT_DATA_PATH:

.LONG

;UBA DATA PATH

SOPT_DATA PATTERN:

SOFT_MAP_BASE:

SOFT_MAP_LENGTH:

.LONG

; REQUIRED DATA PATTERN

;BASE MAP REG TO USE

;4# OF MAP REG TO USE

Diagnostic Conventions

28-Feb-77

=--

Rev

Page

15-9

DIAGNOSTIC SECTIONS

15.2.8

Dispatch Table

PROGRAM DISPATCH TABLE

THIS TABLE IS BUILT BY A SUPERVISOR MACRO

“E

;" N " TEST IN TABLE

15.2.9

; ADDRESS OF TEST

;sADDRESS OF TEST

T1S0
T2S0
T3S0

; ADDRESS OF TEST #2

TNSO

Report Code

+
+

STATISTICAL REPORT MODULE

THIS PRINT MODULE PROVIDES REPORTS OF A STATISTICAL NATURE.

THE FIRST ENTRY IS INVOKED BY THE SUPERVISOR COMMAND 'REPORT'.
THE REMAINING ENTRIES ARE PROGRAM INVOKED.

WME

CEXAMPLE>

REP1_PROG_SUMMARY:

PRINT
RSB

REP2_DATA_SUMMARY:

PRINT
PRINT

RSB

FMT6 PROG_SUMMARY,<R6,R5,R7>

;sPRINT SUMMARY.
s EXIT

FMT7_DATA_SUMMARY,<R3,R4,DATA_TABLE>
FMT8 DATA_STAT

+EXIT

DIAGNOSTIC

Page 15-10

28-Feb-77 -- Rev 3

Diagnostic Conventions
SECTI1ONGS

Intialize Code

15.2.10

+
+

FUNCTIONAL DESCRIPTION: INIT
THIS ROUTINE INITIALIZES THE TEST PROGRAM.
IT

PERFORMS:

1.
2.
3.

ALLOCATION OF UNIT(S) UNDER TEST
INITIAL ALLOCATION OF BUFFER SPACE
INITIAL MAPPING OF MEMORY SPACE

CALLING

SEQUENCE:

SUPERVISOR INVOKED

INPUT PARAMETERS:

PTABLE

BGNINT

: START OF CODE

ENDINT

sEND OF

INITIALIZE

Cleanup Code

15.2.11

+
+

FUNCTIONAL DESCRIPTION: CLNUP
THIS ROUTINE PERFORMS THE NECCESSARY CLEANUP BEFORE
THE TEST PROGRAM EXITS BACK TO SUPERVISOR LEVEL.
IT

PERFORMS:

1.
2.
3.

DEALLOCATION OF BUFFER SPACE
RESET OF UNIT UNDER TEST(UUT)
DEALLOCATION OF UNIT UNDER TEST

CALLING

SEQUENCE:

JSB

CLNUP

INPUT

PARAMETERS:

PTABLE

WME

wmg

BGNCLN

; START OF

ENDCLN

;END OF

CLEANUP

Diagnostic Conventions
DIAGNOSTIC

15.2.12

28-Feb-77

Rev 3

Page 15-11

SECTIONS

Program

Subroutines

.SBTTL

PROGRAM

SUBROUTINES

FUNCTIONAL DESCRIPTION:

$RANDOM

THIS ROUTINE GENERATES A RANDOM NUMBER THAT IS RETURNED
IN RO. THE SEED FOR THE NUMBER IS PASSED ON THE STACK.

CALLING

SEQUENCE:

PUSHL
CALLS

SEED
#1,SRAND

; PUT SEED VALUE ON
;CALL ROUTINE

STCK

INPUT PARAMETERS: SEED

%wo

®e

s +4+

SEED

BASE

VALUE

THAT GENERATOR

STARTS

WITH.

®e

S$RANDOM:

.WORD

M<R1l,R2>

MOV

4 (AP) ,R1

MOVL

R1,RO

SRANDOM_EXIT:
RET

;s SAVE REG MASK
;FETCH

SEED

FRM

s RETURN VALUE

sRETURN

STCK

IN RO

CALLER

+
+

SECTIONS

FUNCTIONAL DESCRIPTION:

UBA_SETUP

THIS ROUTINE HANDLES THE SETUP OF THE UBA
TO ALLOW UNIBUS DEVICES TO TRANSFER DATA
BETWEEN SBI MEMORY AND UNIBUS MEMORY OR
UNIBUS

DEVICES

CALLING SEQUENCE:

CALLG

INPUT PARAMETERS:

$UBA_LIST,SUBA_SETUP

UBA_LIST

THIS

LIST

IS A TABLE LIKE:

UBA_LIST:

UBA_MAP_BASE:

.LONG

UBA_BUS_ADR:
UBA_LENGTH:

UBA_DAT_PATH:
UBA_SBI_PHYSICAL:

.LONG
.LONG

0
0

.LONG
.LONG

0
0

;NUMBER OF ARGUMENTS

;BUS ADR AT DEVICE
s RECORD LENGTH
; STARTING MAP REG

;UBA DATA PATH
; STARTING PHYSICAL ADR

u¢

DIAGNOSTIC

Page 15-12

28-Feb-77 -- Rev 3

Diagnostic Conventions

SUBA_SETUP:

.WORD

MOVL

"M<R1,R2,R3,R4>

4 (AP) ,R1

; SAVE R1-R4
;GET ADDR OF ARGUMENT LIST

SUBA_SETUP_EXIT:

RET

; EXIT

Diagnostic Conventions

DIAGNOSTIC

28-Feb-77

SECTIONS

-- Rev 3

Page

15-13

Hardware Test

15.2.13

The actual harware test will go within this section
of
the
program.
All
diagnostics
that
run
with the diagnostic supervisor will, when
neccessary, make supervisor ‘'calls' to provide a function rather
than
code that function into the program.
If a routine is used by more than
one
test,
that
routine
will
be
placed
in
the
program
subroutine section.
Linkage to that routine
will be via °'CALLS' or 'CALLG' instructions.
If these
routines
must
pass data back to the test, the test will specify where this data will
go by supplying the needed argument(s).
This
section
is
sub-divided
by
tests
and
subtests.
The
subdivision
provides
for blocking the diagnostic of into major
areas.
While, the subtest provides a way of further subdividing
test into smalller logic areas.
Therefore

the basic organization will

BGNTST
BGNSUB

<TEST CODE

FOR T1S1l>

ENDSUB

BGNSUB
<TEST CODE

FOR T1S2>

ENDSUR

ENDTST

BGNTST
BGNSUB

<CODE
ENDSUB

ENDTST

FOR T2S1>

look

this.

test
logic
each

Diagnostic Conrventions

CIAGMNSTIC

e
soCCTYy

28-Feb=-77 -- Rev 3

Page 15-14

Fach test and subtest must have a snecific level of documentation.

Each test must specifv a complete test description and any assumptions
that are assumed by this test. Assumptions implies what logic is
assumed to have been successful tested when this test starts.
Each subtest must have
the
test description and
assumptions.
In
addition,
the
subtest must have a complete description of how the
subtest works, what errors the subtest will detect,
procedure is for the subtest failure.

and what the debua

BGNTST

TEST DESCRIPTION:

THIS TEST CHECKS THE MAP REGISTERS IN THE UBA. IT PERFORMS THIS TEST
BY CHECKING THAT ALL REGISTERS HOLD ZEROS AND ONES. THEN THE TEST
WILL FLOAT A ONE THROUGH ALL REGISTERS. FINALLY, THE TEST WILL FLOAT
A ZERO THROUGH ALL REGISTERS

ASSUMPTIONS:

TEST1-TEST2
THIS TEST ASSUMES THAT THE DATA PATH

[

HAS

T3S0:

FROM THE CPU TO THE UBA
REEN CHECKED AND THAT REGISTER ADDRESSING WORKS CORRECTLY.

Diagnostic Conventions
DIAGNOSTIC SECTIONS

28-Feb-77

Rev

Page 15-15

+
+

TEST

DESCRIPTION:

THIS SUBTEST CHECKS THAT UBM000-UBM496 WILL
HOLD AN ALL ZEROS DATA PATTERN AND AN ALL ONES
PATTERN.

DATA

ASSUMPTIONS:

TEST1-TEST2
TEST STEPS:
.

INIT

.
.
.
.
.
.

CLEAR SELECTED MAP REGISTER-MP
(R3)
IF MP(R3) .EQOU O THEN CONTINUE ELS® REPORT ERROR
COMPLEMENT SELECTED REGISTER-MP
(R3)
IF MP(R3) .EQU -1 THEN CONTINUE ELSE REPORT FFKOK
OFRLECT NEXT REGISTER(UPDATE R3)
’
IF R3 .GTR 496 THEN EXIT ELSE GOTO STEP 2

MAP

INDEX

ZERO(R3)

ERRORS:

l.
2.
3.

TIMEOUT- UBA FAILED TO
ZEROS DATA FAILURE
ONES DATA FAILURE

RESPOND

DEBUG:

ERROR

VWO

VWY

BGNSUB

THIS

#1MEAN

POWER

FAILURE.

CHECK

SUPPLIES

CHECK

ERROR #2BIT(S)

THAT

FAILED

STUCK

ONE

ERROR #3CHECK BIT(S)

THAT

FAILED FOR STUCK

ZERO

FOR

STATE

ERROR COULD

T3S1:
<TEST

T3S1X:
ENDSUB

CODE>

STATE

Diagnostic Conventions
DIAGNOSTIC SECTIONS

28-Feb-77 -~ Rev 3

Page 15-16

Hardware Parameter Code

15.2.14

THE HARDWARE PARAMETER TABLE IS BUILT FROM THE INSTRUCTIONS
IN THIS SECTION. THESE INSTRUCTIONS GET EXECUTED IF THE USER
STARTS THE PROGRAM WITHOUT SPECIFYING A CONFIGURATION TABLE.
THE SUPERVISOR WILL RECOGNIZE THIS AN DISPATCH TO THIS SECTION.
THE INPUT TO THESE REQUEST CAN COME FROM EITHER THE USER
OR A SCRIPT FILE.

INPUT IS ELICITED BY GPHRD. THIS COMMAND HAS THE POLLOWING
FORMAT:

GPHRD (TABLE OFFSET,FORMAT STATEMENT,RADIX,BYTE OFFSET,LOWER LIMIT,
UPPER LIMIT)

+
+

; BEGINNING OF HARDWARE CODE

BGNHRD

HPM1:
HPM2:

GPRMD
GPRMD

(BASADR,QST1,0,1,177000,177170)
(VCTADR,QST2,0,1,100,400)

;GET UBA BASE ADR
;GET UBA VECTOR ADR

; RETURN TO SUPERVISOR

ENDHRD

Software Parameter Code

15.2.15
<EXAMPLE>

THE SOFTWARE PARAMETER TABLE IS BUILT FROM THIS CODE IF THE
DIAGNOSTIC SUPERVISOR IS DIRECTED TO ACCEPT SOFTWARE
PARAMETERS FROM EITHER A SCRIPT FILE OR THE USER.
GPSFT COMMANDS ARE USED TO BUILD THE TABLE. THE FOMRAT
OF THE ARGUMENTS 1S THE SAME AS FOR GPHRD(SEE 8.2.14).

®y

WMo

HE & g

; FETCH SO <TYARY PARAMS

RGNSFT

SPM1:

SPM2:

GPRMD

ENDSFT

(RCDLEN,QST4,0,1,20,2000)

(DATPTN,QSTS5,0,1,1,17)

;GET RECOPr, wENGTH

;GET DATA PATTERN

s RETURN TO SUPERVISOR

Diagnostic Conventions

28-Feb-77

-- Rev

Page

15-17

SYMBOL CONVENTIONS

15.3

SYMBOL CONVENTIONS

The following
diagnostics:

symbol

conventions

TnSm

specifies test n

ASCn

specifies ASCII

FMTn

should

used

all

VAX-11

subtest m

specifies format statement n

MSGn
REPn
QSTn
ISRn
SPMn

string n
specifies error message n
specifies statistical report n
specifies question n
specifies interrupt service routine n
software parameter n

HPMn

hardware

The

for

parameter

symbol construction

should

be as

follows:

15.4

MACRO EXPANSION CONVENTIONS

Macros will be expanded or not expanded based on the following
rules.
If a macro generates inline test code it will be expanded but not it's
call.
If a macro makes a call to a subroutine the macro call is shown
but
not it's expansion.
Both the call and expansion can be displayed
it the program is assembled with a debug switch set.

[End

of Chapter

15)

Digital

Equipment

Title:

VAX-11

Corporation

Assembler

Software

Specification

Status:

draft

Architectural

Status:

under

File:

SEAR3.RNO

PDM

not

Date:

COMPANY

ECO

CONFIDENTIAL

Engineering

Page

Sample

Rev

control

used

28-Feb-77

Superseded

Specs:

none

Author:

Conklin

Typist:

Conklin

Reviewer (s):

Abstract:

Brender,

Poulsen,

Appendix
assembly

Revision

D.
D.

Cutler,
Tolman

A contains
language.

copy

Gourd,

sample

Hastings,

module

written

Nassi,

History:

Rev

Description

Rev
Rev
Rev

1
2
3

Author

Original
Revised from Review
After 6 months experience

M.
P.
P.

Spier
Marks
Conklin

Revised

Date
14-Apr-76

21-Jun-76
28-Feb-77

1in

Assembler Sample
Change History

28-Feb-77 -- Rev 3

Rev 2 to Rev 3:
1.

Added example.

[End of SEAR3.RNO]

Page A-990

APPENDIX

ASSEMBLER

28-Feb-77

SAMPLE

=--

Rev

The listing on the next
page
shows
a
routine
from
the
procedure
library.
There
is
no
suggestion that this routine actually works,
only that it follows the conventions set forth in this
document.
In
fact,
its
"facility"
does not even exist.
Note that it consists of
two externally callable routines and a number of internal routines.

28-Feb-77 -- Rev 3

Assembler Sample

.TITLE

.IDENT

(C)

Page A-2

CHFSSIGNAL - Condition Handling Facility SIGNAL and STOIl
/1-3/

1977

DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASSACHUSETTS 01754

WS WP W

WO _wp W

THIS SOFTWARE IS PURNISHED UNDER A LICENSE FOR USE ONLY ON A SINGLE
COPIED ONLY WITH THE INCLUSION OF THE
SYSTEM AND MAY BE
COMPUTER
SOFTWARE, OR ANY OTHER COPIES THEREOF,
THIS
NOTICE.
COPYRIGHT
ABOVE
MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY OTHER PERSON
EXCEPT FOR USE ON SUCH SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE
TITLE TO AND OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES
TERMS.

REMAIN

IN DEC.

THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE
BY DIGITAL EQUIPMENT
NOT BE CONSTRUED AS A COMMITMENT
AND SHOULD

WO WO WS

CORPORATION.

Condition Handling

FACILITY:

ABSTRACT:

“&

DEC ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY OF ITS
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC.

The Condition Handling Facility supports the exception

handling mechanisms needed by each of the common languages.

It provides the programmer with some control over fixup,
It provides
reporting, and flow of control on errors.
to
ability
the
with
writers
subsystem and application
suitable
more
a
give
to
order
override system messages in

application oriented interface.

ENVIRONMENT:

Any access mode--normally user mode

AUTHOR: Peter F. Conklin, CREATION DATE: 12-Nov-76
MODIFIED

«e

To understand CHF more fully, refer to its functional
specification and to the STARLET exception routine (EXCEPTION).

01
02
03

BY:

Peter F. Conklin,

5-Jan-77: VERSION 01

Original, based on CHF Rev 4 spec
(CVC) Updated to Rev 2 coding standards
Correct code in internal handler.

Assembler

Sample

Rev 3

Page

A-3

DECLARATIONS

INCLUDE

FILES:

-e

.SBTTL

28-Feb-77

SPSLDEF
SSSDEF

;PSL

definitions

;System

Status

CANT_MSG_BUF_L=40

CANT_MSG_CTRL_L=40

;length
;length

control string
insert message

CHFS_="X2222016

;***Temp*** CHF

definitions

MACROS:

code

EQUATED SYMBOLS:

NONE

CHF$_CANT_CONT==CHFS$_+4

;Can't

for
for

CHFS$STOP
CHFSSTOP

facility code

continue

CHF$S_NO_HANDLER==CHF$_+8

;:No handler

from CHFS$SSTOP
found

SRMSL_HANDLER=0

;Call

handler

SRM$W_SAVE_PSW=4
SRMSW SAVE MASK=6

SRMSLTM SAVE AP=8
SRMSL_SAVE_FP=12

SRM$L_SAVE_PC=16

;Call

;Call
;Call

frame
frame
frame
frame
frame
frame

PSW

save

mask

save

backward
save

link

CHFSSTOP -

Stop execution via signalling

FUNCTIONAL DESCRIPTION:

We M NG

w
+
+

.SBTTL

Page A-4

28-Feb-77 -- Rev 3

Assembler Sample

NP WY NS

This procedure is called whenever it is impossible
to continue execution and no recovery 1is possible.
It signals the exception. If the handler(s) return
with a continue code, a message "“Can't continue”
is issued and the image is exitted. This procedure
gquaranteed

never

return.

CALLING SEQUENCE:

WME WM

[{parameters.rz.v}])

INPUT PARAMETERS:
NONE

IMPLICIT

INPUTS:

WS e

N "W

"Wy

CALL CHFSSTOP (condition value.rlc.v,

OUTPUT PARAMETERS:

MG WMI

NG Ve

NONE

IMPLICIT OUTPUTS:
NONE

COMPLETION CODES:

WS WP NE

NG NG

NONE

SIDE

EFFECTS:

The process is EXITted if a handler specifies continue.

NONE

$FORMAL

CONDITION VALUE>

; CONDITION VALUE.rlc.v is the condition
;jother

argquments

are parameters

Assembler

Sample

28-Feb-77

Rev

.ENTRY CHF$STOP, "M<R2>
BSBB

SIGNAL

MOVAL

-CANT MSG_CTRL_L(SP),SP

PUSHAB

(SP)
$CANTMSG_CTRL L

PUSHL
MOVL

SP,R2TM

MOVAL

~CANT MSG_ BUF

Page

;Stop

;go do the signaling
;allocate room for control

;set

;make

into

;save

7get

string
it
string descriptor

pointer

$GETERR_S CONDITION VALUE(AP),(RZ),(RZ)
L(SP)SP

copy

error

descriptor

string

MOVL

SP,ROTM

sallocate room for string
;get pointer to it
:
smake into string descriptor
;get pointer to it

PUSHL

;set

$FAOL
S

(R2),(R0O),
(RO) ,CONDITION VALUE (AP)
;format error string
;set "can't continue" code
$CHF$_CANT_CONT
;1ssue message, with the
#2,LIBSOUT MESSAGE
; original SIGNAL's message

PUSHAB
PUSHL

PUSHL
CALLS

BRW

(SP)

#CANT MSGBUF L

SIG_EXIT

A-5

arg

for

later

; as the insert
;stop with original
; as the code

exception

28-Feb-77 -- Rev

Sample

Assembler

.SBTTL

CHFSSIGNAL -

Signal

;++

Exceptional Condition
‘

FUNCTIONAL DESCRIPTION:

Page A-6

This procedure is called whenever it is necessary

to indicate an exceptional condition and the procedure
can not return a status code. If a handler returns
with a continue code, CHFS$SIGNAL returns with
all registers including RO and Rl preserved.
Thus,

CHFSSIGNAL can

also be

used

to plant performance

and

CALLING SEQUENCE:

debugging traps in any code.
If no handler is found,
or all resignal, a catch-all handler is CALLed.

INPUT PARAMETERS:

CALL CHFSSIGNAL (condition value.rlc.v, [{parameters.rz.v}])

IMPLICIT

INPUTS:

NONE

OUTPUT

PARAMETERS:

NONE

IMPLICIT OUTPUTS:

NONE

COMPLETION CODES:

NONE

SIDE

EFFECTS:

If a handler unwinds, then control will not return.
A handler could also modify RO/R1 and change the
If neither is done, then all
flow of control.
registers and condition codes are preserved.

WME

NONE

BSBB
RET

.ENTRY
SIGNAL

CHFSSIGNAL,O

;51gnal
signaling
the
do
;go
caller
;return to

Assembler

Sample

28-Feb-77 -- Rev

SIGNAL

Internal

Page A-7

Routine

Signal

Exceptions

FUNCTIONAL DESCRIPTION:

.SBTTL
EFS

This routine is used by CHFS$SSTOP and CHFS$SIGNAL to do
the actual exception signaling. It sets up the handler
arqument list. It then checks both exception vectors for
a handler. It then searches backward up the stack, frame
by frame looking for a handler. Each handler found is
called. If the handler returns failure (resignal), the
search continues. If no handler is found or if all handlers
resignal a catch-all handler is called. The catch-all
issues the standard message for the condition and then
returns success if condition-value<0> is set. If a
handler returns success (continue) the routine returns
to CHFSSTOP or CHFS$SSIGNAL with RO/R1l intact.

During the stack search, if another signal is found to
be still active, the frames up to and including the
establisher of the handler are skipped. Refer to the
section Multiply Active Signals in the functional
~specification. An active signal is defined as a routine
which is called from the system vector SYSSCALL HANDLR.

CALLING SEQUENCE:

If a memory access violation is found during the stack
search, it is assumed that the stack is finished and
the routine calls the catch-all handler.

INPUT

PARAMETERS:

AP points

to the

IMPLICIT

INPUTS:

NONE

OUTPUT PARAMETERS:
NONE

IMPLICIT OUTPUTS:
NONE

COMPLETION CODES:

JSB

NONE

arg

list

Page A-8

28-Feb-77 -- Rev 3

EFFECTS:

SIDE

Assembler Sample

handler

unwinds,

then control will

not

return.

are

preserved.

We
NP

A handler could also modify RO/R1 and change the flow
of control. If neither is done, then all registers

SIGNAL:

PUSHR
MOVAB

# "M<RO ,R1>
;save RO/R1 in mechanism vector
W'SIGNAL_HANDLER,SRMSL_HANDLER(FP) s;establish a handler
;

MNEGL

#3,-(SP)

catch

access

violations

;initial depth is -3

PUSHL

svector

PUSHL
PUSHAL
PUSHAL

$4
(SP)
(AP)

PUSHL

smechanism has 4 elements
;second arg is mechanism vector
;first ara is signal vector
;two arquments to handler

this point

the

stack

all

set

for

:
:
:

00(SP)
04 (SP)
08 (SP)

= 2
= signal vector address
= mechanism vector address

:
:
:
:

12(SP)
16 (SP)
20(SP)
24 (SP)

=
=
=
=

:
:
:

28 (SP) = mechanism vector Rl
32(SP) = RSB return to CHFSSTOP or
36 (SP)++ RET frame to invoker

to any handler:

vector length (4)
vector frame (FP)
vector depth (-3)
vector RO
CHFSSIGNAL

loop here

looking

for

a handler

to call

mechanism
mechanism
mechanism
mechanism

a call

frame = current

10S:

INCL
BGEQ

EXTZV

;move to next depth
;branch if searching
RO
sget current PSL
$PSLSV_CURMOD, #PSLSS_CURMOD,RO,RO0

MOVQ

8#CTLSAQ EXCVEC[RO]),R0

$-1,20(SP)

;see which vector this time

BEQL
MOVL

408
RO,R1

;sbranch if secondary
;if primary, move to Rl

BRB

408

;

MOVPSL

CMPB

20 (SP)
20$

sget
;get

and

stack

current mode
both exception vectors

branch

28-Feb-77

Sample

Rev

Page

A-9

here

if search ing stack

Assembler

- 20$:

BLBS
MOVL

;1f

loop too

long,

give up

;get last frame examined
SRMSL SAVE FP(RO) ,16(SP) ;get previous frame
sbranch if no more stack
SIGNAL_CATCH

Here with RO containing a frame whose predecessor might be
CHF or EXCEPTION calling to a handler. If so, the return
D
£ \»

wAanld

WAL &4

ha
N

QV SSCALL
wa
r

-t & f Y

HANDL+4

vector to call handlers.

becaun se

Bt me e O

both

JSB

that

If so, we have the situation of

multiply active signals and need to bypass frames until this
handler's establisher is skipped. The depth parameter is
not incremented because a handler and its establisher are
considered part of the same entity.

VWO

MOVL
BEQL

22 (SP) ,SIGNAL_CATCH
l6 (SsP) ,RO

CMPL

BNEQU
BSBB

SRMSL_SAVE_PC
(R0) , #SYSSCALL_HANDL+4
;see if multiply active
sbranch if not
308
OLD_SP
;adjust RO to what SP
;

MOVL

12(RO) ,RO
4(RO),16(SP)

contained before the call
;get mechanism vector
;get establisher's frame

BRB

208

: as last frame
;search again

MOVL
TSTL

@816 (spP) ,R1
R1
108

MOVL

308:
40S:

BEQL
JSB

BLBC
MOVAL

POPR

@#SYSSCALL HANDL

RO,10S$
-12(FP) ,SP

# "M<RO,R1>

Here when no handler is found, or if all handlers resignal.
This is either done when the stack saved FP is 0, meaning end
of the stack, or when an access violation occurs, indicating
that the stack is bad. The catch-all handler is called and
then a no-handler message is issued.

RSB

;get handler if any
;see if handler
;if no handler, loop
;CALL handler via "vector*®
;if resignal, loop
;clean up stack
;restore RO/R1
sreturn to CHFSSTOP or CHFSSIGNAL

SIGNAL CATCH:

~ MOVAB
JSB
PUSHL

CALLS
BRB

B"SIG CATCH ALL,R1

@#sYSSCALL_HANDL
#CHFS_NO_HANDLER

$1,LIBSOUT MESSAGE

SIG_EXIT

;set address of handler
;CALL handler via "“vector”
;get "no handler® code
soutput

message

;go exit with condition
; value as result

SIG_CATCH_ALL -

Internal Catch-all Handler

FUNCTIONAL DESCRIPTION:

This handler is used in SIGNAL to catch
signals when no handler is found or all resignal.
CALLING SEQUENCE:

handled = SIG_CATCH_ALL (condition.rl.ra, mechanism.rl.ra)
INPUT PARAMETERS:
NONE

IMPLICIT INPUTS:
NONE

OUTPUT PARAMETERS:
NONE

IMPLICIT OUTPUTS:
NONE

COMPLETION CODES:
NONE

SIDE

EFFECTS:

If condition_value<0> is clear, SEXIT is done.

-e

e wE Wme e we WP wWe WS WE We WP WE W . WP WP WE WS Mg MO w9 W W .G W9 WO WY WO WE W0 We wo -e

-e

.SBTTL

Page A-10

28-Feb-77 -- Rev 3

Assembler Sample

SIG_CATCH_ALL:

.WORD
MOVAL
CALLG

BLBC

0
@4 (AP) ,AP
(AP) ,LIBSOUT MESSAGE

XIT
,SIG_EN
(AP)IO
IT
VALUE
COND

RET

+if failure,

go exit

; otherwise, return

Here to give up and exit to the system. The condition value
argument is given as the exit status.

:No registers
sget condition args
;issue standard messaqge

SIG_EXIT:

SEXIT_S CONDITION_VALUE(AP)

sexit with condition
s+

value as the result

Assembler

Sample

.SBTTL

28-Feb-77

OLD_SP

Rev

Internal

Routine

CALLING

Calculate 014

to calculate what SP was before
resulted in a specific stack

SEQUENCE:

JSB
INPUT

PARAMETERS:

IMPLICIT

address

stack

frame

question

INPUTS:

NONE

OUTPUT

PARAMETERS:

RO
IMPLICIT

value

before CALL

question

OUTPUTS:

WE WE

NONE

COMPLETION

WO WP WO WY WO B0 WO

Ny B WO WO WE WS WME VP WL W

NG NG

NG WE MY WE Ny WY

WO WO WO WE WE WO W9 Mg "y

;+;UNCTIONAL DESCRIPTION:
This routine is called
a particular CALL that
frame.

Page

NONE

SIDE

OLD

EFFECTS:

SP:

CODES:

clobbered

EXTZV

#14,%#2,SRMSW_SAVE_MASK (R0) ,- (SP)

EXTZV

1get stack
$0,#12,SRM$SW_SAVE_MASK(RO) ,R1

ADDL2
ADDL2

$20,R0
(SP)+,R0

10S$:

BLBC
ADDL?2

20S:

ASHL
BNEQU
RSB

R1,20$
$4 ,RO

$#-1,R]1,R1
10§

offset

;get register mask
;standard frame
;SP correction

;if register bit set,
; count the register

:discard bit
;loop until all
sreturn

done

A-11

Assembler

Sample

Internal

Page A-12

Routine

Handle

Access

+
+

SIGNAL HANDLER

-- Rev

FUNCTIONAL

DESCRIPTION:

NEe

“O

.SBTTL

28-Feb-77

CALLING

SEQUENCE:

This handler is used in SIGNAL to catch
access violations during the stack search.
If it gets an access violation exception from
this procedure it terminates the search.

SIGNAL HANDLER

(condition,

mechanism)

INPUT

PARAMETERS:

handled

IMPLICIT

INPUTS:

NONE

OUTPUT

PARAMETERS:

NONE

IMPLICIT

OUTPUTS:

NONE

COMPLETION

CODES:

success

not

handled
1f

unwound

SIDE

EFFECTS:

|WE

NONE

The

stack

unwound

and

SIGNAL CATCH

branched

to.

Violation

Assembler

Sample

28-Feb-77

Rev

SIGNAL HANDLER:
.WORD
0
MOVQ
4 (AP),RO

here

;NO

registers

;get

both arguments
;verify "this" establisher
;branch if not
;see 1f memory access violation

8 (R1)
10§
4 (RO) , #SS$_ACCVIO
10§

if access violation

A-13

signal

;branch

not

procedure

«-e

TSTL
BNEQU
CMPL
BNEQU

Page

MOVL

CHFSL SIG_ARGS(RO),R1
SIGNAL CATCH,-4(R0O) [R1]

;change

MOVL

$5S$_CONTINUE,RO

;jresume

RET

10$:

CLRL

;

Appendix

signal

args

exception

;MO3

handled

;jreturn

.END

number

execution

;not

RET

[End

iget

MOVAL

+MO3
function

unwind

value

Digital

Equipment

Title:

VAX-11l

Corporation

BLISS

Software

Specification

Status:

draft

Architectural

Status:

under

File:

SEBR3.RNO

PDM

not

Date:

COMPANY

CONFIDENTIAL

Engineering

ECO

Sample

Page

Rev

control

used

27-Feb-77

Superseded

Specs:

none

Author:

Conklin

Typist:

Conklin

Reviewer (s):

Abstract:

R.
D.

Brender,
Tolman

Appendix

Cutler,

contains

BLISS.

Revision

copy

Gourd,

sample

Hastings,

module

written

Nassi,

History:

Rev

Description

Rev

Original

Author

Rev

Revised

from

Rev

After

months

Review
experience

Spier

Marks

Conklin

Revised

Date
14-Apr-76
21-Jun-76

27-Feb-77

BLISS Sample
Change History

Rev

to Rev
l.

27-Feb-77

Added

example.

[End of SEBR3.RNO]

~-- Rev

Page

B-990

APPENDIX

BLISS

SAMPLE

27-Feb-77

The listing on the next
page
shows
library.
There
1is
no
suggestion
only that it follows the conventions

Rev

a
routine
from
the
procedure
that this routine actually works,
set forth in this document.

Page B-2

27-Feb-77 -- Rev 3

BLISS Sample

MODULE LIBSOUT MESSAGE (

!Library routine to output a system messaqge

IDENT='1-4"
)

(C)

1977

DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASSACHUSETTS 01754

THIS SOFTWARE IS FURNISHED UNDER A LICENSE FOR USE ONLY ON A SINGLE
COMPUTER SYSTEM AND MAY BE COPIED ONLY WITH THE INCLUSION OF THE
THIS SOFTWARE, OR ANY OTHER COPIES THEREOF,
ABOVE COPYRIGHT NOTICE.
MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY OTHER PERSON
EXCEPT FOR USE ON SUCH SYSTEM AND TO ONE WHO AGREES TO THESE LICENSE
TITLE TO AND OWNERSHIP OF THE SOFTWARE SHALL AT ALL TIMES
TERMS.
REMAIN IN DEC.

THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE
AND SHOULD

NOT BE CONSTRUED

AS A COMMITMENT

BY DIGITAL

EQUIPMENT

CORPORATION.

RELIABILITY OF ITS
FOR THE USE OR
RESPONSIBILITY
NO
DEC ASSUMES
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DEC.

Gus

gum

Cun

Smn

fun

Can

Saw

¢up

fws

Own

$uwn

Sun

Sem

Oww

bum

BEGIN

L++

Procedure Library

FACILITY:

]
!

ABSTRACT:

]

This routine takes a system message (status) code, gets
it from the system message file and formats it with FAO.

]

!
!

then outputs

ENVIRONMENT:

the message

to OUTPUT.

Any access mode--normally user mode

AUTHOR: Peter F. Conklin, CREATION DATE:

16 Dec 76

]

MODIFIED

BY:

01
02
03

Peter F. Conklin, 29-Dec-76: VERSION 01
Original, using QIO to TT: only.
Update to standard module format
Change to use GETERR FRST and GETERR_NEXT
-

]
|

!
1
1

]
!

and to use PUT_SYSOUT
(CVC)

Correct sense of multi-line loop.

BLISS

Sample

27-Feb-77

Rev

Page B-3

!
!

TABLE

FORWARD

CONTENTS:

ROUTINE

!output message

INCLUDE

FILES:

Sun

LIBSOUT_MESSAGE:NOVALUE;

MACROS:

¢un

Sub

Sum

NONE

EQUATED

SYMBOLS:

Sap

PuB

¢an

NONE

LITERAL

MSG_CTRL

L=132,

!length

of control

!length of message

string

OWN

STORAGE:

Sw»

Punm

Pem

oan

MSG_BUP_L=132;

EXTERNAL

REFERENCES:

Gup

Gum

¢un

NONE

EXTERNAL

ROUTINE

LIBSGETERR_FRST:NOVALUE, !get start of messaqge
LIBSGETERR_NEXT,
lget more of message
SYSSFAOL:NOVALUE,
!format message
LIBSPUT_SYSOUT:NOVALUE; !put message to SYSOUT
:

'A03

ta03

BLISS Sample

Page B-4

27-Feb-77 -- Rev 3

!Output system message
GLOBAL ROUTINE LIBSOUT_MESSAGE (
istandard completion code
MESSAGE_CODE,
Isubstitutable params

LIST)

:NOVALUE

14+

FUNCTIONAL DESCRIPTION:

!
!

This routine takes a system message (status) code, qets
each line of the message from the system message file
via the library routines GETERR_FRST and GETERR_NEXT,

!
!

formats it with PAO, and outputs it via the library

routine PUT_SYSOUT.

FORMAL PARAMETERS:

!
!

MESSAGE_CODE.rlc.v

!
]

!
!
!
!

!
!

[{LIST.rz.v}]

<31:16> facility code

<15:3>
<2:0>

message indicator
severity indicator:
0
1l
2
4

= warning
= success
= error
= severe error

remaining parameters are used in call to FAO

(]

IMPLICIT INPUTS:

NONE

IMPLICIT OUTPUTS:

NONE

]

COMPLETION CODES:

NONE

]

!
!

SIDE EFFECTS:

One or more records are output on device OUTPUT:

BEGIN
LOCAL

Imessage line control cogde
CONTROL,
ON _CTRL Y], 'contrcl string
(MSG
ALLOCATI
TOR[{CHS
MSG CTRL:VEC

MSG_BUF: VECTOR [CHSALLOCATION(MSG_BUF_LY],
MSG_CTRL D:VECTOR(2],
MSG_BUF_D:VECTOR([2];

!text string

tcontrol string descriptor
ltext string descriptor

BLISS

Sample

27-Feb=77

Rev

Page

B-5

]

Initialize

string

descriptors

MSG_CTRL_D[0)

= MSG_CTRL_L;

MSG_CTRL_D[1]) = MSG_CTRL;
MSG_BUF_D([1] = MSG_BUF;

Get

the

message

control

string

for

LIBSGETERR_FRST

(.MESSAGE_CODE,

the

first

MSG_CTRL_D,

line

MSG_CTRL_D,

CONTROL);

Fevd o

1+
!

Loop,

The

processing

loop ends

each

when

line and getting
GETERR_NEXT returns

the

false

'A03

BEGIN

'1A03

!
!
!
!_

If the control code is '
' or 'T', then
format message for output with FAO and then output it.
Note that GETERR returns the control code as uppercase

.CONTROL<0,8>

EQLU

.CONTROL<0,8>

THEN

BEGIN
MSG_BUF_D[0]

SYSJFAOL

EQLU

only.

'T°®

1A03

MSG_BUF_L;

(MSG_CTRLTMD, MSG_BUF_D, MSG_BUF D, MESSAGE CODE)

LIBSPUT_SYSOUT

(MSG_BUF_DJ;

!A03

Reset

control

text

length

Gmp

Sam

END;

MSG_CTRL_D[0]

descriptor

and

aet

MSG_CTRL_L;

END

WHILE

END;

LIBSGETERR_NEXT

(MSG_CTRL_D,

!End

MSG_CTRL
D, CONTROL);

LIBSOUT_MESSAGE

line

103
tA03
IMO4
1A03

BLISS Sample

Paae BR-6

27-Feb-77 -- Rev 3

END

ELUDOM
[End of Appendix B]

'Ené of modulr

“

meauin

Digital

Equipment Corporation

COMPANY CONFIDENTIAL

Title:

COMMON

Engineering

BLISS

Software

Specification

Status:

draft

Architectural

Status:

nunder

File:

SECR3.RNO

PDM

not

Specs:

none

Author:

Murray

Typist:

Murray

Reviewer (s):

Abstract:

R.
D.

$
1
2
3

Rev
Rev

Tolman

Cutler,

contains

copy

Gourd,

sample

Hastings,

1I.

module

written

Nassi,

History:

Description
Original
Revised from Review
After 6 months experience

Author
By

Revision

Brender,

Appendix C
BLISS.

Rev

27-Feb-77

Superseded

Rev

used

Belmont

Marks

Murray

Mamad
NADO
1L

Date:

control

e B

ECO

Sample

Page

Revised

Date
14-Apr-76

21-Jun-76
27-Feb-77

1in

Common BLISS Sample
Change History

Rev 2 to Rev 3:

Added example.

[End of SECR3.RNO]

27-Feb-=77

== Rev

Page C-990

APPENDIX
COMMON

BLISS

27-Feb-=77

The

following

conventions
external

running

discussed

routines for

TTY_GET_CHAR

TTY_PUT CRLF

TTY_PUT_INTEGER

TTY_PUT_ASCIZ

SAMPLE

Rev

program

this manual.

console

TTY_PUT_CHAR

TTY_PUT_MSG

BLISS

1/0.

that

These

illustrates

relies on a

are:

many of

small

the

number of

MODULE LIBSCALC

(

IDENT =
MAIN
)

Page C-2

27-Feb-77 -- Rev 3

Common BLISS Sample

INTEGER ARITHMETIC EXPRESSION EVALUATOR

'03°',

MAINLOOP

DIGITAL EQUIPMENT CORP.,

MAYNARD,

MA 01754

THIS SOFTWARE IS FURNISHED TO THE PURCHASER UNDER
A
LICENSE
FOR
USE
ON A SINGLE COMPUTER SYSTEM AND CAN BE COPIED (WITH
INCLUSION OF DIGITAL'S COPYRIGHT NOTICE) ONLY FOR USE IN SUCH
SYSTEM,
EXCEPT
AS
MAY
OTHERWISE BE PROVIDED IN WRITING BY
DIGITAL.

THE INFORMATION IN THIS DOCUMENT IS SUBJECT TO CHANGE WITHOUT
NOTICE AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL
EQUIPMENT CORPORATION.
DIGITAL ASSUMES NO RESPONSIBILITY FOR
ANY ERRORS THAT MAY APPEAR

IN THIS

DOCUMENT.

DIGITAL EQUIPMENT CORPORATION ASSUMES NO
RESPONSIBILITY
FOR
THE
USE OR RELIABLILTY OF ITS SOFTWARE ON EQUIPMENT WHICH IS
NOT SUPPLIED BY DIGITAL EQUIPMENT CORPORATION.

Peun

Gwn

Gum

fous

Suw

Juw

fus

Smm

Swm

Sem

bem

BEGIN

GENERAL

FACILITY:

]

LIBRARY

]

FUNCTIONAL

]

DESCRIPTION:

THIS PROGRAM PARSES AND EVALUATES ARITHMETIC EXPRESSIONS,
KEEPS 26 VALUES AROUND, AND GENERALLY ACTS LIKE AN "AID"

!
]

WITH

]

DECIMAL

INTEGERS ONLY.

ENVIRONMENT:

USER MODE WITH EXTERNAL ROUTINES

]
'

AUTHOR:

BELMONT

CREATION DATE:

01-JAN-76

]
1

MODIFIED

BY:

PETER C. MARKS, 10-MAY-76
CONFORMATION TO S. E. MANUAL STANDARDS
-

RICHARD M. MURRAY, 21-FEB-77
CONFORM TO REVISED STANDARD
~

ISAAC R. NASSI, 30-APR-77
BUG FIXES, TRANSPORTABILITY CHANGES
-

]

|
!

]
|
!

1
I

1
!

BLISS

EXTENDED

Sample

27-Feb-77

=--

Rev

Page C-3

FUCTIONAL DESCRIPTION:

SYNTAX:

LEXICAL LEVEL: ALL CHARACTERS WITH ASCII VALUE LEO #040
IGNORED.
THUS, BLANKS AND TABS AND <CR> AND <NL>

ARE

IGNORED

UPPER

AND

fuw

SINCE

TYPE

VD gup S

Omm Suw

Suw 0N

uw Sup

Gam

Sam

femw Oum

Common

AFTER

(AND MANY OTHERS).

LOWER CASE
READ

AHEAD

ALPHABETIC
ONE

CHARACTERS

CHARACTER,

MUST

AFTER THE LAST CHARACTER TO GET THE JOB DONE.
PROCESSING, THE REMAINDER OF THE INPUT IS ERASED.

THE

UNARY

OPERATOR

MINUS

(

)

MAY

NOT

$EP
Pun

IMMEDIATELY

fun Pum guw

<T1>

(-1+(-2));
<FULL>

<EXPR>

{ALPHA>=<EXPR>

<T5>

<TS>

<T4>

->
->

!
!

<T2>

<T1>

CED Gum O

USER

IDENTIFIED.

SOMETHING

ANY

EXCEPT

ARE

"(".

THUS

ALL CORRECT

<TO0>

-1+1;

BUT

(-1+1);

-1+-2;

IS NOT.

;

<TO>

<T5>

(SEE

COMMENT

ABOVE

<TO0>

<ALPHA>

<DIGIT>

(

<EXPR>

)

AtB!C!

<ALPHA>
...

<{DECIMAL><DIGIT>

ON USE

UNARY

<DIGIT>

otrl1tr2¢!.,..1718109

SEMANTICS:

THERE
ARE

ARE

VARIABLES

INITIALLY

WITH

<ALPHA>

THE

VARIABLES.

A=B=C=<T5>;

B=1+ (A=B=5+3);

BUT

1+4A=3;

VARIABLE

VALUE

THE

HAS

OPERATOR)

SEB

(THE
AND

A VARIABLE

(R S VU

ASSIGNMENT
THE

NAMES.

THEY

ZERO.

fum

(U (Ul

TR CED

fem

D P

TP fuD eun qun

fan FUED

THE

ARE

WITH

ALLOWED ONLY

EFFECT OF

REPLACING

THE

EVALUATED VALUE OF
ASSIGNMENT OPERATION IS THE

ASSIGNED.

THUS,
THE

A=B=C=1;
EXAMPLES:

VALUE

THE
<T5>.
VALUE

ALL THREE

ARE

CORRECT

A=<T5>;

ARE

NOT.

fem AP

"A;"

jum SUm Sem

THREE

(WD

A+1=3;

ASSIGNS

ALL

VALUES

THE

DERAILING

THE

MAY

STACKS

USED TO
ARE

PRINT THE

MAINTAINED

"MAIN STACK"

VALUE
THIS

MAIN_STK AND

PROGRAM,

ITS

POINTER

MAIN_STK_POINTER.
AND

END

RIGHT

ORDER.

fem IR

fem

OPERATORS

OP_STACK_PTR

STACK

ITS

FOR OPERATORS
POINTER.

OPERATOR_STACK.

MINUS.)

Sample

27-Feb=77

=- Rev

THIS STACK HOLDS LOWER PRECEDENCE
PRECEDENCE OPERATORS ACCUMULATE.
WHEN THE ";" IS PROCESSED.

Page C-4

OPERATORS AS HIGHER
THIS STACK IS EMPTIED

THE
EVAL

EVALUATION
STK

STACK

EVAL _STK.

ITS

POINTER

PTR.

Gum tew

IT HOLDS OPERANDS WHILE THE MAIN STACK IS SCANNED FOR

OPERATORS.

Gaw G

Sap s

Guw

Gms tem S

Common BLISS

GO ON THE EVALUATION STACK.
THIS
BY EVAL_POLISH AND ITS FRIENDS.

THE

RESULTS

OF OPERATIONS

PERFORMED

STACK

MANAGED

27-Feb-77

=--

Page

Sam

MAIN

PROGRAM

SWm

EXPRESSION,

READ,

PARSE,

feam

ROUTINE

MAINLOOP,

$ap

PARSE

Se
fuD

LEXEME

few

GET

fun

STREAM

PUSH_OPERATOR:NOVALUE,

fab

PUSH

POP_OPERATOR,

faB

POP

(AP

PUSH

ERROR;

INCLUDE

ONTO

(up

POP

Sun
San

EXPRESSION

EVALUATE

AN
AN

EVALUATE

PUSH

ONTO

OFF

OPERATOR
ADDRESS

VALUE
EVALUATION

EXPRESSION
CONTENTS

THE

MAIN

STACK

ERROR

EQUIRE

'BLI:COMIOG.REQ';
!
MACROS:

MACRO
LBXEME_TYPE=

LEXEME[O] &,

LEXEMB_VALUE=

LEXEME(1]%,

MAIN TYPE=

MAIN_STK[.MATIN_STK PTR-2]%,
MAIN_STK[.MAIN STK_PTR-1]%,

VALUE=

TOPOP=

STACK

EVALUATION

FILES:

MAIN

STACK

POLISH-TYPE

EVALUATE

POP

STACK

MAIN

INPUT

STACK

OPERATOR
MAIN

EVALUATE

OFF

FROM

OPERATOR

SEm

EVAL ADDRESS,
EVAL VALUE
PUSH_EVAL_STACK:NOVALUE,
POP EVAL STACK,
PRINT STRING:NOVALUE,
PRINT_STACK,

CHARACTER

SED

OPERATOR,

OPERATOR

BUILDING

ONTO

tum

EVAL

EVALUATE
-

EXPRESSION

OFF

Sur

PUSH_MAIN_STACK:NOVALUE,
POP_MAIN_STACK,
EVAL_POLTSH:NOVALUE,

READ_UNTIL_DEL,

LOGIC

AND

EXPRESSION

PROCESS

PROCESS_OPR,

GET_CHARACTER:NOVALUE,

C-5

CONTENTS:

INPUT_CYCLE,

:U = o¢en gom ¢ew

Rev

fam

ORWARD

Sample

fum

TABLE

BLISS

s 'T] ¢ tem s

Common

OPERATOR_STACKT.OP_STACK
PTR-1]%;

MESSAGE

STACK
THE

Common

BLISS

Sample

27-Feb~77

Rev

Page

C-6

SYMBOLS:

EQUATED

!
L
!
!

IS THE

S
P
Caw
¢

Swr

e
%
%

DIVISION

"**"

"+*"
*-"

"“/*

fap

SEMI-COLON ";*"
ASSIGNMENT "="
NEGATION (UNARY

Swn
Sam

PRECEDENCE

PRCDENCE

SUBTRACTION

OPEN

ELEMENT

w»

IS_OPERATOR=
IS_NONE=

STACK

_NAME=

IS _DECIMAL=

O wN -

MAIN
IS

ADDITION

oww

CUTOFF=

PARENTHESIS

MULTIPLICATION

PAREN

AND

MINUS)

PIRST

*-"

FOR NEG

CODES

Jem

NEGATIVE=

VARIABLE

COL=

EQUAL=

OPERATOR

PARENTHESIS

INTEGER VALUE

sum

SEMI

"PIRST"
OPEN

OPERATOR

‘e

DIVIDE=

MINUS=

PLUS=

«-

MULTIPLY=

PAREN=

FIRST=

OPEN_PAREN=

WN -=O
O OV

OPERATOR CODES

NAME

"NOTHING"

(SPECIAL

ELEMENT)

TABLES

PRECEDENCE

THE

CURRENT

OPERATOR

PRCDENCE
2 IS THE PRECEDENCE OF THE OPERATOR ON TOP OF
OP-STACK.
THE TWO ARE COMPARED IN INPUT_CYCLE.
THE TWO LISTS ARE BASICALLY THE SAME,

NOTE:

PRECEDENCE_2

BOUT:

IS THE SAME AS PRECEDENCE

FOR ALL

OPERATORS EXCEPT " (" WHERE IT IS REDUCED TO 1 AND "=" WHERE
IT IS REDUCED TO 2. CLOSE PAREN WILL FORCE "=%" ONTO
STACK AND WILL FORCE ALL OTHER OPERATORS DOWN TC " ("
WHICH, WITH ")", IS REMOVED BY THE ACTION OF ")",

PRCDNCE_1= UPLIT(O0,9,2,7,4,5,6,1,3,8):VECTOR[10}.

*+ -/

PRCDNCE_2= vupPLIT(O,1,2,7,4,5,6,1,2,8):VECTOR[10],
ASCII
OPNAMES=

VALUE

OPERATORS

(
PLIT

PLIT
PLIT
PLIT
PLIT

(%ASCIZ
(8ASCIZ

'FIRST'),
'('),

(%ASCIZ
(%ASCI1Z

*')'),
'*'),

SIZE

(%ASCIZ
(%ASCIZ2

PLIT

(%ASCIZ

PLIT
PLIT

-|!

(SASCIZ

(RASCIZ

PLIT

-«

- %

(%ASCIZ

PL.LIT

C-7

e =

Page

PLIT
-

!
!

Rev

N+

=--

27-Feb-77

G) = = =

Common BLISS Sample

)) :VECTOR([50];

PARAMETERS

132,
400,

STACK_STZE=

INPUT

MAX

AREA

SIZE

SIZE OF

A CONDITION

SIZE

OUTLINE

LENGTH

STACKS

STORAGE

P——r

STOR_LEN=

133,

dem

INPUT_SIZE=

OUT_MSG_MAX=

LITERAL

NOTHING=

.-.-O.-.-.-

CAR_RETURN
CHARMASK =

ICARRIAGE RETURN
! MASK LOW BITS

OWN STORAGE

STACKS

MAIN

STK:

VECTOR [STACK_SIZE],

OPERATOR STACK: VECTOR[STACK_SIZE],
VECTOR
[ STACK_SIZE],
EVAL_STK:
STACK

{
!

MAINSTACK
OPERATOR STACK
EVALUATION STACK

POINTERS

MAIN_STK_PTR,

OP_STACK_PTR,
EVAL_STK_PTR,

VECTOR([STOR_LEN],

SINGLE

CHARACTER

VECTOR([ 2],

LEXEME:

INPUT_POINTER,
INPUT_LENGTH,

ERRORV;

O=0

VECTOR[INPUT_SIZE],

fwp

INPUT:

Smn

PAREN_LEVEL,

Pum

OPERATOR,

ASCII

INPUT
IDENTIFIER VALUE
STORAGE AREA

DECIMAL VALUE
LEXICAL ELEMENT

!
!
Oun

DECVALUE,

¢um

STORAGE:

CHAR,

AREAS

Fap

AND

PARSING VARIABLES

LEXEME[O]
LEXEME([1]

= TYPE
= VALUE

OPERATOR CODE
(SEE ABOVE)
PARENTHESES LEVEL
LINE
INPUT LINE POINTER
LENGTH OF INPUT LINE
INPUT

Common BLISS Sample

EXTERNAL REFERAMCES:
NONE

27-Feb-77

Rev

Page

C-8

Common

BLISS

Sample

27-Feb=-77

=--

Rev

Page

!
]
]

!
]

THIS

]

GROSS

THE

DOING

THE
LOGIC

USER

MAIN ROUTINE OF
OF THE MODULE.
REPEATEDLY

THE

CALL

]

EXECUTION OF

HITTING

TO THE

EXPRESSION

ROUTINE
THIS

CONTROL

THIS

MODULE.

ASKED TO "TYPE
IS PARSED AND
L5 Lo oS

TaaY e

CONTAINS

EXPRESSION".
EVALUATED BY
S &b

FORMAL

(AND

THE

MODULE)

HALTED

PARAMETERS:

NONE

!
!

IMPLICIT

INPUTS:

]
!

NONE

]

IMPLICIT

OUTPUTS:

]

STORAGE,

INPUT,

INPUT_LENGTH,

1
1

ROUTINE

INPUT_POINTER

VALUE:

]

NONE

!
1

!
!
!
]

BEGIN
RESET

INCR

READ

STORAGE

I FROM 0 TO
STORAGE[.I])=

ZERO

VALUES

(STOR_LEN

O0;

LINE

WHILE

BEGIN

TTY_PUT_CRLF
() ;

TTY_PUT_CHAR(

%C'*'

INCR

FROM

BEGIN

UPON

EXPRESSION,

ROUTINE

]
!

THE

);

:NPUT_SIZE-1

PROMPT

C-9

Common BLISS Sample

27-Feb=77 -- Rev 3

INPUT([.I]

= TTY GET CHAR():

IF .INPUT[.I] EQL CAR RETURN
THEN
BEGIN

INPUT[.I]

= %C';

INPUT LENGTH

EXITLOOP;

END;
END;

INPUT_POINTER = -1;
IF EXPRESSION() THEN RETURN
END:;
END;

Page

ICARRIAGE

RETURN

! ONE EXTRA SEMICOLON

Common BLISS Sample

27-Feb-77 -- Rev 3

Page C-11

LOGICALLY,

THIS ROUTINE REPEATEDLY CALLS THE ROUTINE INPUT CYCLE

IN ORDER TO READ AND PARSE THE EXPRESSION, PRINTS THE

EXPRESSION, PRINTS THE CONTENTS OF THE STACK JUST BUILT,
THEN EVALUATES THE EXPRESSION VIA A CALL TO EVAL POLISH.
FORMAL PARAMETERS:
NONE

IMPLICIT

INPUTS:

NONE

IMPLICIT OUTPUTS:
PAREN_LEVEL

COMPLETION CODES:

RETURNED AS ROUTINE VALUE;
0 - NO ERRORS REPORTED
1

- ERROR ENCOUNTERED

SIDE EFFECTS:
NONE

BEGIN

LOCAL

CONDITION;

VALUE RETURNED BY

INPUT_CYCLE

PAREN_LEVEL = 0;
DO

()
CONDITION = INPUT CYCLE

UNTIL .CONDITION NEQ 0;
IF

.CONDITION

PRINT STRING():;

PRINT_STACK();

EVAL_POLISH();
RETURN 0
END;

EQL 1 THEN

RETURN 1;

1ERROR

AND

INPUT CYCLE =

.—.-‘—..o..-o-.-.—.-.-.—..0-0—0—0—.-0—-0-0—0—0—-.—0-.—.—.—o—u-— s Qus Sun g

+
+

ROUTINE

Page C-12

27-Feb-77 -- Rev 3

Common BLISS Sample

FUCTIONAL DESCRIPTION:

THIS ROUTINE MAKES CALLS TO ROUTINE READ UNTIL DELITER

BASED ON THE TYPE

ACCESSING LEXEMES AND DELIMITERS.

THE ROUTINE PERFORMS VARIOUS FUNCTIONS.
NOTE:

THERE IS AN INTERNAL ROUTINE CALLED PROCESS OPR, WHICH

HANDLES OPERATOR DELIMITERS.
FORMAL PARAMETERS:
NONE

IMPLICIT

INPUTS:

LEXEME_TYPE,

LEXEME_VALUE

IMPLICIT OUTPUTS:
NONE

COMPLETION CODES:

RETURNED AS ROUTINE VALUE;
0 - NO ERRORS ENCOUNTERED
1
2
SIDE

- ERROR ENCOUNTERED
- END OF EXPRESSION

EFFECTS:
NONE

BEGIN
LOCAL

! VALUE TO BE RETURNED

VALUE;

IF READ UNTIL_DEL() THEN RETURN 1;

.LEXEME_TYPE NEQ IS_NONE

THEN

BEGIN

PUSH_MAIN_STACK (.LEXEME_TYPE);

PUSH MAIN_STACK (.LEXEME_VALUE)

ELSE

END

IUNARY OPERATOR

(.OPERATOR NEQ MINUS AND
.OPERATOR NEQ OPEN_PAREN)

Common BLISS

Sample

27-Feb-77

.OPERATOR

EQL

Rev

Page

MINUS

THEN

.PRCDNCE_2[.TOPOP]

LSS

THEN
OPERATOR

NEGATIVE

ELSE

RETURN (ERROR(5) ) ;
PROCESS_OPR
END;

CUTOFF

C-13

Common BLISS Sample

ROUTINE

27~-Feb-77 -- Rev 3

Page C-14

PROCESS_OPR =

! ++

FUCTIONAL DESCRIPTION:

!
!

THIS ROUTINE HANDLES OPERATORS (DELIMITERS).
IT
KEEPS TRACK OF THE PARENTHESES COUNT AND THE PROPER

SYNTAX OF

EXPRESSIONS.

FORMAL PARAMETERS:

!
!

NONE

!
!

IMPLICIT

!
!

INPUTS:

OPERATOR, PAREN LEVEL, TOPOP,
1, PRECIDENCE_2
PRECIDENCE

!
!

LEXEME_TYPE,

!
!

IMPLICIT OUTPUTS:

PAREN_LEVEL

!
!

COMPLETION CODES:

RETURNED AS ROUTINE VALUE;

0
1
2

!
!

- NO ERRORS ENCOUNTERED
- ERROR ENCOUNTERED
- END OF EXPRESSION

!
!

SIDE

EFFECTS:

NONE

]
! =

BEGIN

LOCAL

VALUE RETURNED BY PROCESS_OPF

.OPERATOR EQL OPEN_PAREN

THEN

CONDITION;

PAREN LEVEL =

.PAREN_LEVEL+1;

.OPERATOR EQL CLOSE_PAREN

THEN

PAREN LEVEL =

.PAREN_LEVEL-1;

WHILE .PRCDNCE_I[.OPERATOR]

LEQ .PRCDNCE_2[.TOPOP]

BEGIN

PUSH_MAIN-STACK(IS-OPERATOR)7
PUSH_MAIN_STACK(POP_OPERATOR());

Common

BLISS

Sample

27-Feb-77

Rev

Page

END;

.OPERATOR

EQL

SEMI_COL

THEN
IF

.PAREN

THEN

LEVEL

EQL

RETURN

(ERROR(9));

ELSE

.OPERATOR

EQL

CLOSE_PAREN

THEN

BEGIN
IF .TOPOP NEQ OPEN_PAREN
POP_OPERATOR()
;
IF

READ_UNTIL

DEL()

.CONDITION

GTR

THEN

RETURN(ERROR(3)):

RETURN

IF .LEXEME_TYPE NEQ IS _NONE THEN RETURN (ERROR(6));
CONDITION=PROCESS_OPR();
IF

THEN
RETURN

.CONDITION;

END
ELSE

|
PUSH_OPERATOR (.OPERATOR) ;

RETURN 0
END;

C-15

ROUTINE READ_UNTIL_DEL
!

Page C-16

27-Feb=-77 -- Rev 3

Common BLISS Sample

FUCTIONAL DESCRIPTION:

[}
!

THIS ROUTINE DOES THE ACTUAL PARSING OF THE INPUT EXPRESSION
LOOKING FOR SYMBOLS, NUMBERS AND OPERATORS (DELIMITERS).
IT ALWAYS ATTEMPTS TO RECOGNIZE AN OPERATOR AND

1
|

RETURN

]

ITS CODE.

PRIOR TO SEARCHING FOR THE OPERATOR IT LOOKS FOR A SYMBOL
IF NONE OF THESE
(IS_NAME) OR INTEGER(IS_DECIMAL).
IN THE GLOBAL VARIABLE
RETURNED
TS
_NONE
IS
ARE FOUND THEN

LEXEME_TYPE.

!
1

FORMAL PARAMETERS:

|
!

NONE

1
]

IMPLICIT INPUTS:

!
{

CHAR,

OPERATOR

IMPLICIT OUTPUTS:

!
1

OP_STACK_PTR, MAIN_ STK_PTR, ERRORV, LEXEME TYPE,

LEXEME_VALUE, DECVALUE, OPERATOR

1
!
!

ROUTINE

{

VALUE:

OPEN PAREN, CLOSE PAREN, MULTIPLY, PLUS, MINUS

DIVIDE, SEMI_COL, EQUAL, ERROR(1l), ERROR(2)

!
!

SIDE

EFFECTS:

]

NONE

1
!

BEGIN

.INPUT_POINTER EQL -1

THEN

IF FIRST TIME THROUGH PLACE SPECIAL "FIRST" DELIMITER

ON THE

MAIN_STK

BEGIN

;
GET_CHARACTER()

OP_STACK_PTR = 0
MATIN_STK_PTR = 0
ERRORV =

PUSH_OPERATOR(FIRST);

END;

! INITDEL

Common BLISS

Sample

FIRST
N

27-Feb-77

SEARCH
N

LEXEME_TYPE

FOR

SYMBO L

MNAD

(3 ]

NONE;

Rev 3

Page C-17

Tiaim

PR
Y

!FOR

THERE

MAY

NOT

(.CHAR GEQ %CTA' AND .CHAR LEQ %C'Z')
(.CHAR GEQ %C'a'

AND

.CHAR LEQ

THEN

%C'z')

BEGIN

ONE

ICONVERT

LEXEME_TYPE

LEXEME

VALUE

IS_NAME;

(.CHAR

GET CHARACTER()
END

INDEX

AND

CHAR

INTO

TO AN

STORAGE

!ARRAY
CHARMASK)-1;

ELSE

(.CHAR GEQ

%C'0'

AND

.CHAR LEQ

$%C'9')

THEN

BEGIN
DECVALUE

WHILE

(.CHAR

GEQ

%C'0'

AND

.CHAR

LEQ

BEGIN

%C'9')

DECVALUE
GET

END;

= 10* ,DECVALUE+,CHAR-%C'0';
CHARACTER():

LEXEME_TYPE

LEXEME_VALUE

IS _DECIMAL;

,DECVALUE;

!DECIMAL

END;

NOW GET

DELIMITER

(.CHAR

LSS

WHETHER OR NOT WE

%C'('

.CHAR GTR

HAD

%C'="')

RETURN (ERROR(1))
o

LLO | A

BEGIN
OPERATOR=

(CASE

(.CHAR)

FROM

8$C'('

SET

[8C*' ('] :

OPEN_PAREN;

(8C*') ']

CLOSE_PAREN;

[8C'*']):
MULTIPLY;

[8C'+'):
PLUS:;

[8C'-"'):
MINUS:

[sC'/']:
DIVIDE;

[sC';'):

SEMI_COL:

[8C'="]:
EQUAL;

[INRANGE]
:

%C'='

VALUE

IDENTIFIER OR NUMBER

THEN
—r

INTEGER

Common BLISS Sample

27-Feb-77 -- Rev 3

! ALL OTHER VALUES ARE IN ERROR
RETURN (ERROR(2))
;
TES)

;
GET_CHARACTER()

IF TOPERATOR EQL 0 THEN RETURN(ERROR(2))
END;

END;

Page C-18

Common

BLISS

ROUTINE

]

Sample

27-Feb-77

GET_CHARACTER

:NOVALUE

Rev

Page

THIS

ROUTINE

ACCESES

AND

PLACES

ALL

CHARACTERS

THE

WITH

THE

GLOBAL

OCTAL

CHARACTER

VARIABLE

VALUE

LESS

FORMAL PARAMETERS:

NONE

!
IMPLICIT

INPUTS:

!
!

INPUT_POINTER

$
!

IMPLICIT

OUTPUTS:

]
!

INPUT_POINTER,

CHAR

!
!

ROUTINE VALUE:
COMPLETION CODES:

NONE

!
!

SIDE

EFFECTS:

!
!

NONE

]

!
BEGIN

BEGIN
INPUT_POINTER

CHAR =
END
UNTIL

END:

,INPUT

POINTER

_INPUT[.INPUT POINTER];
-

(.CBAR

GTR

$C'

');

FROM

THE

INPUT

STREAM

CHAR.

C-19

FUCTIONAL DESCRIPTIION:

]

THAN

ARE

IGNORED.

Common BLISS Sample

27-Feb-77 -- Rev 3

ROUTINE PUSH_OPERATOR(ELEMENT)

Page C-20

¢:NOVALUE =

1++

!
1

FUCTIONAL DESCRIPTION:

THIS ROUTINE "PUSHES"TM AN ELEMENT ONTO THE OPERATOR_STACK.

!
!
!
!

!
!
!

!
!

!
!
!
!
!

|
'

!
!

FORMAL PARAMETERS:

ELEMENT - OPERATOR TO BE ADDED TO STACK
IMPLICIT

INPUTS:

OP_STACK_PTR

IMPLICIT OUTPUTS:

OP_STACK_PTR, OPERATOR_STACK
ROUTINE VALUE:

COMPLETION CODES:
NONE

SIDE EFFECTS:

NONE

!
!

BEGIN

OPERATOR_STACK[.OP_STACK_PTR] = _ELEMENT;
OP_STACK_PTR = .OP_STACK_PTR+1
END;

Common

ROUTINE

BLISS

Sample

27-Feb-77

POP_OPERATOR

Rev

Page

C-21

!
!

FUCTIONAL DESCRIPTION:

i
THIS ROUTINE "POPS" A DATA ELEMENT OFF OF THE OPERATOR_STACK,
; FORMAL PARAMETERS:
;

NONE

OP_STACK_PTR

;

VALUE OF ELEMENT POPPED FROM STACK

i IMPLICIT INPUTS:
:
OP_STACK_PTR, OPERATOR_STACK
; IMPLICIT OUTPUTS:
g

; ROUTINE VALUE:
' SIDE EFFECTS:

]

!
!

NONE

BEGIN
OP_STACK_PTR

.OP_STACK

PTR-1;

.OPERATOR_STACK[.OP_STACK PTR]

END:;

Common BLISS Sample

27-Feb=77 -- Rev 3

ROUTINE PUSH_MAIN_STACK (ELEMENT)

Page C-22

:NOVALUE =

L++

FUCTIONAL DESCRIPTION:

!
!

THTS ROUTINE WILL "PUSH"TM AN ELEMENT ONTO THE MAIN_STK.

!
!

FORMAL PARAMETERS:

ELEMENT - DATA TO BE PUSHED ON MAIN_STK

!
!

IMPLICIT INPUTS:

MAIN_ STK_PTR

|
!
I

IMPLICIT OUTPUTS:

MAIN STK, MAIN_STK_PTR

ROUTINE VALUE:
COMPLETION CODES:

NONE

SIDE EPFECTS:

NONE

1
! -

BEGIN

MAIN STK([.MAIN_STK_PTR]= .ELEMENT;

MAIN STK_PTR= .MAIN_STK_PTR+l
END;

Common

BLISS

Sample

27-Feb-77

Rev

Page C-23

FUCTIONAL DESCRIPTION:
TAIS

ROUTINE

"POPS"

ELEMENT OFF

FORMAL

OF THE

PARAMETERS:

faw

CEp

Guw

Sab

Qan =

Qup

14+

IMPLICIT

INPUTS:

Gup

PED

Qup

NONE

MAIN STK

IMPLICIT OUTPUTS:

Sup

CEP

(uv

MAIN_STK_PTR,

ROUTINE

VALUE:

VALUE

SIDE

ELEMENT

POPPED

EFFECTS:
NONE

OED

Sup

faB

fep

fan tem

¢am

(WD

Jun

'MAIN_STK

BEGIN

MAIN

STK

PTR=
&

ANV

_MAIN_ST

.MAIN_STR[.MAIN_STK_PTRT

END;

FROM THE

STACK

MAIN

STK

27-Feb-77 -- Rev 3

Common BLISS Sample

ROUTINE EVAL POLISH

Page C-24

+NOVALUE =

14+

FUCTIONAL DESCRIPTIION:

THIS ROUTINE DOES THE ACTUAL EVALUATION OF EXPRESSION
WHICH HAS NOW BEEN PARSED AND RESIDES ON THE MAIN_STK.
OPERANDS (VARIABLES AND INTEGERS) ARE SHUNTED OFF AND PLACED
ONTO THE EVAL_STK.

OPERATORS ARE FVALUATED BY MAKING A CALL TO EVAL_OPERATOR.

FORMAL PARAMETERS:
NONE

IMPLICIT INPUTS:

MAIN_STK_PTR, MAIN_STK, EVAL_STK
IMPLICIT OUTPUTS:

EVAL_STK_PTR, LEXEME_TYPE, LEXEME_VALUE, EVAL_STK
ROUTINE VALUE:
COMPLETION CODES:
NONE

SIDE

EFFECTS:
NONE

BEGIN

EVAL_STK_PTR = 0;

INCR I FROM 0 TO .MAIN_STK_PTR-I BY 2 DO
BEGIN

LEXEME TYPE = .MAIN_STK[.I]:
LEXEME VALUE = .MAIN STK[.I+l];

IF LEXEME TYPE NEQ IS OPERATOR

THEN

BEGIN

PUSH EVAL STACK( LEXEME TYPE),

(.LEXEME VALUE)
TSTACK
PUSH_EVAL

END
ELSE

EVAL_OPERATOR(.LEXEME_VALUB):

END;

IF .MAIN_STK_PTR EQOL 2
THEN

EVAL_STK[l] = BVAL_VALUE(): ! THE CASE "A;"

Common BLISS Sample

TTY_PUT_CRLF();

27-Feb-77 =-- Rev 3

TTY_PUT_QUO('VAL:
)
TTY_PUT_INTEGER(.EVAL_STK[I],10,10);
END:

Page C-25

Common BLISS Sample

Page C-26

27-Feb-77 -- Rev 3

ROUTINE EVAL_OPERATOR(STACK_OPBRATOR) =
!

FUCTIONAL DESCRIPTION:

[}

THIS ROUTINE EVALUATES THE OPERATOR STACK OPERATOR.
THE PROPER NUMBER OF OPERANDS ARE ACCESSED FORM THE MAIN_STK.

AFTER EVALUATION THE VALUE IS PLACED ON THE EVAL_STK.

FORMAL

PARAMETERS:

STACK_OPERATOR - OPERATOR TO BE EVALUATED

IMPLICIT

INPUTS:

NONE

!
|

IMPLICIT OUTPUTS:

t
!

STORAGE

|
1

ROUTINE VALUE:

!
!

ERROR(3)

]
|

SIDE

EFFECTS:

NONE

!
'
!

BEGIN

LOCAL

INTERMEDIATE
SAVE AREAS

VALUE 1,
VALUE_2,
3;
VALUE_

VALUE_3

(SELECT .STACK_OPBRATOR OF
SET

[ALWAYS]
:

!
!

DO THIS FIRST - DETERMINE THE NUMBER OF OPERANDS
o
NEEDED BY THIS PARTICULAR OPERATOR
BEGIN

VALUE 2

VALUE_1

(TF

EVAL VALUE();

.STACK_OPERATOR EQL EQUAL THEN

()
EVAL_ADDRESS

Common

BLISS

Samnle

27-Feb-77

Rev

Page

ELSE

.STACK_OPERATOR

NEQ

EVAL VALUE())

END;

[NEGATIVE])
:
]

NEGATION

(UNARY

MINUS)

- .VALUE
2;

[MULTIPLY]
:
.VALUE_1

_VALUE_2;

.VALUE_2;

.VALUE_1

.VALUE_2;

[PLUS]
:
.VALUE_1

.VALUE_2;

[DIVIDE]
:
.VALUE_1

[MINUS]:

{EQUAL]
:
! STORE THE VALUE
STORAGE[.VALUE
1]

[OTHERWISE]
:
RETURN (ERROR(8) ) ;

TES)
;
PUSH

EVAL STACK(IS
7

DECIMAL);

PUSH TEVAL STAC K{.VALUE

END;:

3);

VALUE_2

.VALUE_2;

NEGATIVE

THEN

C-27

Z27-Feb=717

Common BLiLL HAaAMp.ie

Page C-28

Rev

f:)'\/I'\L_.f\DDi(l.:S Ho00=

SOUTINE

FUCTIONAL DESCRIPTION:

THIS ROUTINE IS CALLED WHEN TOI ASSIGMVFEMT ARRFrATTMARr 1 TN NF

IDENTIFIER

THF VALUC

PETURMNED

IS THE ADDPRESS

(INNEX)

THE

STORAGE,

PARAMETERS:

YOTMATL

see

FVALUATED,

Sew
Y -

T4+

IMPLICIT

INPUTS:

pas

Fwm

Pmm

NONE

IMPLICIT OUTPUTS:

§on

Gem

NONE

ROUTINE

VALUE:

gem

bmw

Geme

NONE

ERROR(7), ADDRESS (INDEX)
TOP OF EVAL_STK

IDENTIFIER

FROM THE

SIDE

EFFECTS:
NONE

tow

Ava

Bus

few

Vnw

see

OF THE

BEGIN
LOCAL
VAL,
TYPE;

!
!

TEMPORARY VALUE
TEMPORARY TYPE

VAL = POP_EVAL_STACK():

TYPE = POP_EVAL_STACK();

IF .TYPE NEQ IS_NAME THEN
.VAL

END;

RETURN (ERROR (7)) ;

Common BLISS

27-Feb=77

Sample

Rev

Paae C-29

FUCTIONAL DESCRIPTION:
THIS

ROUTINE

EVAL

STK

ACESSES THE VALUE OF THE IDENTIFIER. THE
IS USED TO INDEX THE IDENTIFIER VALUE STORAGE

VALUE

AREATM (STORAGE).
FORMAL

PARAMETERS:

NONE
IMPLICIT

INPUTS:

STORAGE
IMPLICIT

OUTPUTS:

NONE

ROUTINE

VALUE:

VALUE

SIDE

THE

IDENTIFIER

THE

TOP

EVAL

STK

EFFECTS:
NONE

BEGIN
LOCAL

TYPE,
VAL;

VAL

POP_EVAL_STACK();

TYPE = POP_EVAL STACK();
IF .TYPE EQL IS NAME THEN
.VAL
END;

VAL

TEMPORARY

TYPE

TEMPORARY

VALUE

_STORAGE([.VAL];

Common BLISS Sample

27-Feb-77 -- Rev 3

ROUTINE PUSH_EVAL_STACK(ELEMENT)

Page C-30

:NOVALUE =

FUCTIONAL DESCRIPTION

!
'

THIS ROUTINE "PUSHES" A DATA ELEMENT ONTO THE EVAL_ STK.

FORMAL PARAMETERS:

]

ELEMENT - DATA TO BE PLACED ON EVAL_ STK

IMPLICIT

INPUTS:

EVAL_STK,

]

EVAL_STK_PTR

IMPLICIT C.TPUTS:

!
]

EVAL_STK_PTR

!
]
!

ROUTINE VALUE:
COMPLETION CODES:

{

NONE

1
|

]
1
'
'

BEGIN

EVAL_STK[.EVAL_STK_PTR]

EVAL_STK_PTR =
END;

,ELEMENT;

.BVAL_STK_PTR+1

Rev

Page

27-Feb=77

>
=

L]
4

Sample

+
+

O-.-0-0—.-.-.-.-0-0-.-.-.-.-.-0—0.-.-.-.-.-Q—.—O—O—O-

Q
<
3

ret

Common BLISS

FUCTIONAL DESCRIPTION:

THIS
FORMAL

ROUTINE

"POPS"

ELEMENT OFF OF THE

PARAMETERS:
NONE

IMPLICIT

INPUTS:

EVAL_STK_PTR,
IMPLICIT

EVAL_STK

OUTPUTS:

EVAL_STK_PTR

ROUTINE

VALUE:

VALUE

SIDE

POPPED

FROM

EVAL_STK

EFFECTS:
NONE

BEGIN
EVAL

STK

PTR

,EVAL

STK

.EVAL_STK[.EVAL_STK_PTR]TM

END:;

PTR-1;

EVAL STK.

C-31

Common BLISS Sample

27-Feb-77 -- Rev 3

ROUTINE PRINT_STRING :NOVALUE =
144

FUCTIONAL DESCRIPTION

THIS ROUTINE PRINTS OUT THE EXPRESSION JUST READ IN.

FORMAL PARAMETERS:

NONE

!
!

IMPLICIT

INPUTS:

INPUT

IMPLICIT OUTPUTS:

NONE

!
!

ROUTINE VALUE:

COMPLETION CODES:
NONE

!
!

SIDE EFFECTS:
NONE

! -

BEGIN

TTY_PUT_CRLF();

INCR I FROM 0 TO .INPUT_LENGTH-1 DO
BEGIN

.INPUT([.I]

EQL CAR_RETURN

THEN

EXITLOOP;

TTY_PUT_CHAR(. INPUT[.I]):
END;
END;

Page C-32

Common

BLISS

27-Feb-77

Rev

Page

C-33

+
+

PRINT_STACK

’

FUCTIONAL

DESCRIPTION:

fup

fow

Sum

ROUTINE

Sample

Swr

THIS

PRINTS

OUT

THE

CONTENTS

MAIN

faw

PARAMETERS:

En S SeB

few $B (e e g fuw Sum pam Sem ¢ 0o fam Sew fan S gus P

fun

FORMAL

STK

gam

faw

ROUTINE
FORMAT.

IMPLICIT

INPUTS:

MAIN_STK_PTR,

MAIN_STK

IMPLICIT OUTPUTS:
NONE

ROUTINE

VALUE:

COMPLETION

CODES:

NONE

SIDE

EFFECTS:
NONE

BEGIN

INCR

FROM

BEGIN

.MAIN_STK

PTR-1

TTY_PUT_CRLF();

SELECT

.MAIN_STK([.I]

SET

[IS_NAME]
:
TTY_PUT_CHAR(.MAIN

STK[.I+l]

%C'A');

[IS_DECIMAL]
:
TTY_PUT_INTEGER(.MAIN STK([.I+1],10,10);

[IS_OPERATOR]
:
TTY_PUT_ASCIZ (.OPNAMES[.MAIN
TES;
END;

END;

STK[.I+1]]);

SYMBOLIC

Page C-34

27-Feb=77 -- Rev 3

Common BLISS Sample

ROUTINE ERROR(ERROR_NUMBER) =
1

FUCTIONAL DESCRIPTION:

1
!

THIS ROUTINE PRINTS OUT ERROR MESSAGES BASED ON THE
IT ALSO DUMPS THE CONTENTS OF THE
ERROR_NUMBER PASSED TO IT.
MAIN STK AND PRINTS THE EXPRESSION IN ERROR.

]
!
]
!

PARAMETERS:

FORMAL

]
!

ERROR_NUMBER - INDEX INTO ERROR MESSAGE PLIT

|
]

IMPLICIT

INPUTS:

]

ERROR_MESSAGE

!
|

IMPLICIT OUTPUTS:

]
]
|

NONE

1
!

ROUTINE VALUE:

]

SIDE EFFECTS:

]
!

NONE

]
1

BEGIN
MACRO

BIND

MESSAGE (ARGUMENT) = PLIT ($ASCIZ ARGUMENT)S%;
ERROR_MESSAGE = PLIT (

MESSAGE ( 'ERR:0

,
NONE')

MESSAGE ('ERR:10

NONE')

MESSAGE ( 'ERR:1
MESSAGE ( 'ERR:
MESSAGE ( 'ERR:3
MESSAGE ('ERR: 4
MESSAGE ('ERR:5
MESSAGE ( 'ERR: 6
MESSAGE ('ERR:7
MESSAGE ( 'ERR:8
MESSAGE ('ERR:9

ILLEGAL CHARACTER ON I:.PUT'},
OPR EXPECTED, NOT FOUND'),
EXCESS CLOSE PARFN'),
ILLEGAL UNARY OP: ATOR'),
ILLEGAL USE OF UNARY MINUS'),
OPERATOR MUST FOLIOW ")*'),
ASSIGNMENT TO NON VAxI{ABLE'),
BAD OPERATOR ON STx(K'),
EXCESS OPEN PAREN';,

;
) :VECTOR([50]

() ;
TTY PUT_CRLF

G_MAX) ;
AGE
,OUT_MS
ESS
ERROR_NUMBER]
[ . R_M
TTY PUT_MSG (.ERRO

BLISS

Sample

STACK
()

PRINT STRING(
RETURN 1
END:;
END

ELUDOM

[End

of Appendix C]}

27-Feb-77

"’ w9

Common

Rev

Page C-35

Paae

Index-1

INDEX

SFORMAL

macro

Rit

field

size

in assembly lanquaqe,

7-15

Bit name,

12-3

in assembly lanquage,

7-33

Block comment,

6-4

Body,

7-22

S LOCAL macro

SOWN macro
in assembly language,

BLISS LIB:,

BLOCK name, REF,
Block statement,

7-14

tascii, 14-8
$blissl6, 14-8

tbpunit, 14-6
tbpval, 14-6, 14-17,
$c, 14-7
fupval, 14-6, 14-19,

14-34

14-28

CASE

7-11

<name> notation, 13-4
<new page> notation, 4-4
{separator> notation, 4-4
<skip> notation, 4-4
{space> notation, 4-4
<tab> notation, 4-4

Abstract, 4-2, 6-2
Abstraction mechanisms, 14-13
Address calculations, 14-18
Address-relational operators,
14-21
Addressing, relative
in assembly language, 7-21
Algorithms
critical, 4-2
Alignment-attribute, 14-17
Allocation-unit attribute, 14-16,

4-2,

instruction

in assembly langquage,

ChSallocation,
ChSptr, 14-32

Character

<access type> notation, 13-5
<arg form> notation, 13-7
<arg mechanism> notation, 13-7
<comment delimiter> notation, 6-1
<data type> notation, 13-6

14-25

12-4
7-28

Call
non-standard, 12-3
CALL instruction
in assembly lanquage, 7-17
Call/return interface, 3-2
Calling sequence, 4-3, 6-2

. PSECT name, 12-4
.SBTTL statement, 7-25

Author,

routine,

12-3

Boolean value, 6-16
Built-in literals, 14-6

tbliss32, 14-8
tbliss36, 14-8
tbpaddr, 14-6

.ENTRY directive,

5-7

name,

14-30

seaquences

14-22
Choice of language,
Code
completion, 6-11
Code PSECT, 7-20
.

7-2

(strings),

3-1

Code

sharing, 3-3
Code, condition, 12-7
Comment, 6-3
block, 6-4
documenting, 6-5
group, 6-6
line, 6-7
maintenance, 6-9
Common PSECT, 7-20
Compiler library, 13-1
Completion code, 6-11, 12-2
Complexity, lanquage, 14-5
Condition handler, 7-4
Condition value, 12-2, 12-7
Conditional assembly, 4-2, 6-12,
7-3
Configuration statement, 6-12
Constant value name, 12-4
Control

6-2

working

set,

3-3

Control expressions, 14-20
Copyright notice, 6-19

Index-2

Page

Critical algorithms, 4-2
Customer version number, 6-29

Data segment module, 6-20

Data type, 12-6
Declaration, 9-2
equated symbol

in assembly language, 7-5

validate

in assembly language, 7-32

variable

in assembly languaqge, 7-14,
7-20,

7-29,

7-33

weak

in assembly language, 7-34

Declaration: format, 5-2 to 9-3

Declaration: forward, 9-2

Declaration: forward routine, 9-3
Declaration: macro, 9-2 to 9-3
Declaration: order, 9-2, 9-4, 9-17
Default value, 13-8

Definition macro name,

structure,

12-4

Descriptor, call by, 7-16, 13-7
Diagnostic conventions, 15-1
Directory, module, 6-21
Documenting comment, 6-5

Expression:

while/until/do,

Extension attribute, 14-17
External csymbol
in assembly language, 7-31

Facility prefix table, 12-7
Facility statement, 4-2, 6-13
Fail return, 6-16
FALSE Boolean value, 6-16
Field offset name, 12-3
Field selectors, 14-22, 14-43
Field support pe “sonnel, 3-2
File generation version, module,
6-21

File name, module, 6-21
File type, module, 6-21
Form,

arg,

13-7

Formal parameter, 6-22
in assembly language, 7-15
Function value, 6-16
Functional description,
4-2 to 4-3, 6-14
Functionality, 3-3

General library, 13-1
Global array name, 12-3
Global entry point, 12-2
label

Edit history, 4-2

Global

Edit number, 6-9, 6-17

Global PSECT, 7-20
Global symbol

Edit in version number, 6-29

Entry point
global, 12-2
Entry, procedure

in assembly language, 7-11

in assembly langquage, 7-31
Global variable name, 12-3
6-6

in assembly language, 7-19
Environment statement, 4-2, 6-13
Equated symbol declaration
in assembly language, 7-5

Group comment,

Error completion code, 6-11

Ident statement,

Equivalencing, 14-21
calling

6-27

sequence,

Expression, 9-3, 9-5

6-2

in assembly language, 7Expression: assignment, 9Expressior: block, 9-5, 9Expression: case, 9-5 to
Evpression: format, 9-5,

Exception,

9-6
9-8

Expression: if/then/else, 9-5, 9-9
Expression: incr/decr, 9-5, 9-10
Expression: select, 9-5, 9-11

9-5,

9-12

Handler, condition,

7-4

History, modification, 6-17
4-1

IDENT statement

in assembly language. 7-8
Implementation langu:~system, 3-1
Implicit input, 6-1b&

Implicit output,
Include

6-18

files

in assembly lanquaqg:.

Inital-attribute, 14-29
Input parameter, 6-23
Interface style, 12--7

Page

Interface type, 13-2 to
Interlocked instruction

assembly

langquage,

13-3

7-31

Interrupt

calling sequence,
Isolation, 14-4
JSB

calling

6-20, 14-4
data segment, 6-20
file name, 6-21
preface, 6-21

6-2

Label
global

assembly

Labels,

language,

7-12

9-13

choice
Language

of,

3-1

switch,

14-9
6-19
notices, 4-1

notice,

13-1
general, 13-1
in assembly language,
math, 13-1

object

time system,
procedure, 13-1
License notice, 6-19
Line comment, 6-7

assembly

LSB,
in

MODULE.BLI,

S5-7

MODULE.MAR,

5-1

Modules,

4-1

Multiple

entry

pattern,

defined

value,

Name,

module,

6-21

7-14

<{access

7-14

14-8

Maintenance

comment,

6-9

Maintenance
Mars, 14-15

number,

6-17

MARS

LIB:,

14-4

Math

library,

Mask name,

12-4

Modifiability,

7-14

13-1

3-3

13-5

form>,

<arg

mechanism>,

<data

13-7
6-1

13-6

13-4

page>,

{separator>,

4-4

<{space>,

4-4

procedure

Notice,
Number

13-7

delimiter>,

type>,

<name>,

argument,

legal,

13-4

6-19

edit, 6-9, 6-17
maintenance, 6-17
modification, 6-9
version, 6-28
Numeric literals, 14-7

Object

5-1

type>,

<arg

{new

Macro

14--15

call,

14-17

<comment

function,

12-2

14-21

Notation

<tab>,

in assembly language,

12-1

12-3
routine, 7-24
Non-transportable attributes,

7-14

14-4,

7-23

Non-standard

.ENABL/.DSABL
assembly language,

Macros,

routine,

Name

<skip>,

Macro-10,

14-9

Name,

7-12

name,

4-1

9-15

language,

Machine-specific

Macro

switches,

Non-standard

13-1

Listing control
in assembly language,
Literal PSECT, 7-20
Local label
:

12-4

private, 12-2
public, 12-1

Legal
Library
compiler,

name,

preface,

Name,

Language

Legal

Module

in assembly language, 7-11
in assembly langquage, 7-10
local

Modification history, 6-17
Modification number, 6-9
Modular programs, 3-3

Module,

6-2

sequence,

Index-3

time system, 13-1
Offset addressing, 14-28
Offset name, 12-3
Optional arqument, 13-8
Order of routine, 7-25

Page

Output parameter, 6-23
Outpuit string, 13-2
Own PSECT, 7-20

Reserved names,
Routine, 9-17
non-standard,

Packed data initalization, 14-33
Parameter

6-22

formal,

in assembly langquage, 7-15

input, 6-23
output, 6-23

Parameterization, 14-2, 14-34
Patch in version number, 6-29
Pattern

Preface, module, 6-21
Preface, routine, 6-25
Prefix table, facility,
Private name, 12-2

12-7

7-17

entry

in assembly langquage, 7-19
Procedure argument notation, 13-4
Procedure library, 13-1
Process synchronization
in assembly language, 7-31

Program,
PSECT

6-24

statement

in assembly language, 7-20

Public

name,

12-1

Quality, 3-3
Queuve instructions

in assembly language, 7-20

Quoted strings,

14-11
7-24

order, 7-25
Routine body, 7-22
Routine entry, multiple,
Routine preface, 6-25
Routine: format, 9-17
Routine: name, 9-17

7-23

Routine: order, 9-17
Routine: preface, 9-17
Routines, 14-13
Service macro name, 12-2
Severe error completion code,

name, 12-1
Plit, 14-25
uplit, 14-25

Procedure,

1Index-4

14-22

used as numeric values,

14-23

Rarnge attribute, 14-17
Read code, 3-2
Readable system code, 3-2
REF BLOCK name, 12-4

Stack local variable
in assembly langquaqe,
Statement, 7-26

7-33

block, 7-28
Status code, 12-2
Status return value, 6-16
String, 12-6
String instruction
in assembly lanquage, 7-28
String literal plits, 14-26
String literals, 14-7
Strings (character sequences),
14-22
Structire: block, 9-18
Structure

in assembly language, 7-29
Structure definition macro name,
12-4

Structure: block, 9-19
Structure: declaration,
9-18 to 9-19
Structures, 14-39
Style of interface, 12-7
Subtitle statement, 7-25

Relative addressing
in assembly language, 7-21
Repeated arqument, 13-8

Success return, 6-16
Support in version number,
Support personnel, 3-2

Reference, call by, 7-16, 13-7

Success completion code,

Relational operators, 14-20

Require files, 9-16,
search

rules,

14-12

14-4,

6-11

Sharing
code, 3-3
Side effect, 6-26
Sign out, 12-7
Signal, 6-27
Simplicity, 14-5

14-12

Symbol
external

6-11
6-28

Page

assembly

language,

7-31

global

in assembly language, 7-31
in assembly langquaqge, 7-30
Symbol declaration, equated
in assembly language, 7-5
Synchronization, process
in assembly lanquage, 7-31

System

code

readable,

System

3-2

Title

statement,
statement

lanquage,

4-1

lanquage,

Transportability,

7-31

3-3

Transportability

quidlines
calculation, 14-19
allocation attribute, 14-16

address

attributes, 14-17
character sequences,
control expressions,

14-24
14-21

declarations, 14-18
field selectors, 14-43
isolation,

14-4

relational

string

operators, 14-21
literals, 14-23

string

literals
strings, 14-24
Transportability,

plits,

tools,

14-28

14-6

Transportable

control

expressions,

data types, 12-6
declarations, 14-16
expressions, 14-19
structures,

TRUE

Boolean

14-20,

value,

14-21

14-39

6-16

Unwind

in assembly language, 7-32
Update in version number, 6-29
Validate

declaration
in assembly lanquage,

Value

function,
Value, call
Variable

7-32

6-16
by,

stack

local

assembly

7-16,

13-7

language,

7-33

declaration

assembly

lanquage,
7-29, 7-33
machine, 14-15

7-20,
Vax-11

7-14,

ersion number, 6-28
Volatile-attribute, 14-17
Warning

implementation

assembly

Weak

TITLE

Variable

Index-5

completion
declaration

assembly

code,

lanquage,

Weak-attribute,

14-17

6-11

7-34