Digital PDFs

AA-H322C-TE

February 1982

260 pages

Original

9.9MB

Document:	VAX-11 BLISS-32 User's Guide
Order Number:	AA-H322C-TE
Revision:	000
Pages:	260
Original Filename:

OCR Text

VAX-11 BLISS-32
User's Guide
Order No. AA-H322C-TE

February 1982
This document describes the VAX-11 BLISS-32 compiler and its use, and
gives basic information about linking, executing, and debugging BLISS-32
programs. It also describes BLISS-32 machine-specific functions, BLISS
tools, and other topics relevant to BLISS-32 programming.

SUPERSESSION/UPOATE INFORMATION: This document supersedes Version 2 of the
BLISS-32 User's Guide, (Order No. AA-H3228-TE),
dated January 1980.

OPERATING SYSTEM AND VERSION:

VAX/VMS V2.5

SOFTWARE VERSION:

BLISS-32 V3.0

digital ·equipment corporation · maynard, massachusetts

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

Rights Reserved.

Printed in U.S.A.
The postpaid READER'S COMMENTS form on the last page of this document
requests the user's critical evaluation to assist in preparing future
documentation.
The following are trademarks of Digital Equipment Corporation:
DEC
DEC/CMS
DECnet
DECsystem-lo
DECSYSTEM-20
DEC US
DECwriter

DIBOL
EduSystem
IAS
MAS SB US
PDP
PDT
RSTS

RSX
UNIBUS
VAX
VMS
VT

mamaama
ZK2203

HOW TO ORDER ADDITIONAL DOCUMENTATION
In Continental USA and Puerto Rico call 800-258-1710

DIRECT MAIL ORDERS (CANADA)

In New Hampshire, Alaska, and Hawaii call 603-884-6660

Digital Equipment of Canada Ltd.
940 Belfast Road
Ottawa, Ontario K1G 4C2
Attn: A&SG Business Manager

In Canada call 613-234-7726 (Ottawa-Hull)
800-267-6146 (all other Canadian)

DIRECT MAIL ORDERS (USA & PUERTO RICO)*
Digital Equipment Corpor~tio~
P.O. Box CS2008
Nashua. New Hampshire 03061

DIRECT MAIL ORDERS (INTERNATIONAL)
Digital Equipment Corporation
A&SG Business Manager
c/o Digital's local subsidiary or
approved distributor

*Any prepaid order .from Puer~o RJco must be placed
with the local Digltat subsidiary (SQ.9-754-75!5)
Internal orders should be placed through the Software Distribution Center (SOC). Digital Equipment
Corporation, Northboro, Massachusetts 01532

CONTENTS

Page
PREFACE

SUMMARY OF TECHNICAL CHANGES

xiii

CHAPTER 1

OPERATING PROCEDURES

1.1
COMPILING A BLISS MODULE •
1.1.1
Command-Line Syntax
1.1.2
Command-Line Semantics •
1.2
FILE SPECIFICATIONS
COMMAND-LINE QUALIFIERS
1.3
1.3.1
Output Qualifiers
1.3.1.l
Syntax •
1.3.1.2
Defaults
1.3.1.3
Semantics
1.3.2
General Qualifiers •
1.3.2.1
Syntax •
1.3.2.2
Defaults •
•,
1.3.2.3
Semantics
1.3.2.4
Discussion •
1.3.3
Terminal Qualifier •
1.3.3.1
Syntax •
1.3.3.2
Defaults •
1.3.3.3
Semantics
1.3.4
Optimize Qualifier •
1.3.4.1
Syntax •
1.3.4.2
Defaults •
1.3.4.3
Semantics
1.3.S
Source-List Qualifier
1.3.S.l
Syntax •
1.3.S.2
Defaults •
1.3.S.3
Semantics
1.3.6
Machine-Code-List Qualifier
1.3.6.1
Syntax •
1.3.6.2
Defaults •
1.3.6.3
Semantics
1.3.7
Qualifier Names vs. Switch Names •
1.3.8
Qualifiers and Default Settings
1.3.9
Positive and Negative Forms of Qualifiers
1. 3.10
Abbreviations of Qualifier and Value Names •

CHAPTER 2

1-1
1-2
1-3
1-3
1-5
1-5
1-6
1-6
1-6
1-7
1-7
1-8
1-8
1-8
1-9
1-9
1-9
1-10
1-10
1-11
1-11
1-11
1-12
1-13
1-13
1-13
1-14
1-14
1-15
1-15
1-16
1-16
1-17
1-17

COMPILER OUTPUT

2.1
TERMINAL OUTPUT
2.2
OUTPUT LISTING •
2.2.1
Listing Header
Source Listing
2.2.2
Object Listing •
2.2.3
2.2.3.l
Default Object Listing •
2.2.3.2
Assembler Input Listing
iii

2-2
2-3
• 2-3
2-4
2-7
2-8
2-12

CONTENTS
Page
Source Part Options • • • • • • • • • • • • •
2.2.4
Default Source Listing • • • • • • • • • • •
2.2.4.1
Listing with LIBRARY and REQUIRE Information
2.2.4.2
Listing with Macro Expansions • • • • •
2.2.4.3
Listing with Macro Tracing •
2.2.4.4
COMPILATION SUMMARY • • • • • •
2.3
ERROR MESSAGES • • • • • • • •
2.4
CHAPTER 3

2-12
2-16
2-17
2-17
2-17
2-17
2-21

LINKING, EXECUTING, AND DEBUGGING

3.1
LINKING • • • • • • • • • • • • • •
• • 3-1
LINK Command Syntax
• • • • • • • • • • • • 3-1
3.1.1
3.1. 2
LINK Command Semantics • •
• • • • • 3-2
3.2
EXECUTING A LINKED PROGRAM •
• • • •
• • • 3-2
DEBUGGING • • • • • • • • •
• • • •
• • • 3-2
3.3
3.3.1
Initialized Modes and Types
• • • 3-3
Debug Commands and Expression Syntax •
3-4
3.3.2
Operators in Arithmetic Expressions • •
• • 3-4
3.3.3
3.3.4
Special Characters in Address Expressions
• 3-5
3.3.4.1
Current Location Symbol (.)
• • • • 3-6
3.3.4.2
Last Value Displayed Symbol (\)
• • • • • • • 3-7
3.3.4.3
Contents Operator·(.)
• • • • • • • • • • • • 3-7
3.3.4.4
Range Operator (:) • • • • • • • • • • • • • • 3-7
Default Next-Location Value
• • • • 3-8
3.3.4.5
3.3.5
Field References • • • • •
• • • •
• • 3-9
3.3.6
Structure References • • •
• • • •
3-10
REF Structure References • • • •
3-12
3.3.7
3.3.8
Scope of Names • • • • • • • •
• • • •
3-13
Source-Line Debugging • • • • • • • •
• • 3-13
3.3.9
Effect of Compilation and Link-Time Qualifiers 3-14
3.3.10
3.3.11
Debugger Command Summary • • • • • • • • • • • 3-15
CHAPTER 4
4.1
4.2
4.3
4.4
4.5
4.6
4.7
4.8
4.9
4.10
4.11
4.12
4.13
4.14
4.15
4.16
4.17
4.18
4.19
4.20
4.21
4.22
4.23
4.24
4.25
4.26
4.27
4.28
4.29

MACHINE-SPECIFIC FUNCTIONS
ADAWI - ADD ALIGNED WORD INTERLOCKED
ADDO - ADD DOUBLE OPERANDS •
ADDF - ADD FLOATING OPERANDS • • • • • •
ADDG - ADD FLOAT-G OPERANDS
• •
ADDH - ADD FLOAT-H OPERANDS
ADDM - ADD MULTIWORD OPERANDS
• • •
ASHQ - ARITHMETIC SHIFT QUAD
• • • •
BICPSW - BIT CLEAR PSW • • • •
BISPSW - BIT SET PSW • • • • •
BPT - BREAK POINT TRAP • • • • •
BUGL - BUGCHECK WITH LONG OPERAND
BUGW - BUGCHECK WITH WORD OPERAND • • •
CALLG - CALL WITH GENERAL PARAMETER LIST
CHMX - CHANGE MODE • • • • • • •
CMPD - COMPARE DOUBLE • • • • • • • • •
CMPF - COMPARE FLOATING • • • •
CMPP - COMPARE PACKED • • • • • • • •
CRC - CYCLIC REDUNDANCY CHECK
CVTDF - CONVERT DOUBLE TO FLOATING • • •
CVTDI - CONVERT DOUBLE TO INTEGER
CVTDL - CONVERT DOUBLE TO LONG • •
CVTFD - CONVERT FLOATING TO DOUBLE • • •
CVTFG - CONVERT FLOATING TO FLOAT-G
CVTFH - CONVERT FLOATING TO FLOAT~H • •
CVTFI - CONVERT FLOATING TO INTEGER
CVTFL - CONVERT FLOATING TO LONG • •
CVTGF - CONVERT FLOAT-G TO FLOATING • •
CVTGL
CONVERT FLOAT-G TO LONG • •
CVTHF - CONVERT FLOAT-H TO FLOATING • •

• • •
•
• • • • •
• •
•
•
•
•
•
• • • •
•
• • • •
• • • •
• • • •
•
• • • •
• • • •
•
•
•
•

• • •
•
• • •
• • •

4-6
4-6
4-6
4-7
4-7
• 4-7
• 4-8
• 4-8
• 4-8
• 4-8
• 4-9
• 4-9
• 4-9
4-10
4-10
4-11
4-11
4-11
4-12
4-12
4-12
4-13
4-13
4-13
4-13
4-14
4-14
4-14
4-15

CONTENTS
Page

4.30
4.31
4.32
4.33
4.34
4.35
4.36
4.37
4.38
4.39
4.40
4.41
4.42
4.43
4.44
4.45
4.46
4.47
4.48
4.49
4.50
4.51
4.52
4.53
4.54
4.55
4.56
4.57
4.58
4.59
4.60
4.61
4.62
4.63
4.64
4.65
4.66
4.67
4.68
4.69
4.70
4.71
4.72
4.73
4.74
4.75
4.76
4. 77
4.78
4.79
4.80
4.81
4.82
4.83
4.84
4.85
4.86
CHAPTER 5
5.1

CVTHL - CONVERT FLOAT-H TO LONG
CVTID - CONVERT INTEGER TO DOUBLE
CVTIF - CONVERT INTEGER TO FLOATING • • • •
CVTLD - CONVERT LONG TO DOUBLE •
CVTLF - CONVERT LONG TO FLOATING
CVTLH - CONVERT LONG TO FLOAT-H • • • • •
CVTLP - CONVERT LONG TO PACKED •
CVTPL - CONVERT PACKED TO LONG •
CVTPS - CONVERT PACKED TO LEADING SEPARATE
NUMERIC
. • • • • • • • • • • • • • • • • •
CVTPT - CONVERT PACKED TO TRAILING NUMERIC •
CVTRDH - CONVERT ROUNDED DOUBLE TO FLOAT-H •
CVTRDL - CONVERT ROUNDED DOUBLE TO LONG • •
CVTRFL - CONVERT ROUNDED FLOATING TO LONG
CVTSP - CONVERT LEADING SEPARATE TO PACKED •
VTTP - CONVERT TRAILING NUMERIC TO PACKED
DIVD - DIVIDE DOUBLE OPERANDS • • • • • • •
DIVF - DIVIDE FLOATING OPERANDS • • • • •
DIVG - DIVIDE FLOAT-G OPERANDS • • •
DIVH - DIVIDE FLOAT-H OPERANDS • •
EDITPC - EDIT PACKED TO CHARACTER
EDIV - EXTENDED-PRECISION DIVIDE •
EMUL - EXTENDED-PRECISION MULTIPLY •
FFC AND FFS - FIND AND MODIFY OPERATIONS •
HALT - HALT PROCESSOR
• • • • • •
INDEX - INDEX CALCULATION
• • • • • •
INSQHI AND INSQTI - INSERT ENTRY IN QUEUE,
INTERLOCKED • • • • • • • • •
• • • • •
INSQUE - INSERT ENTRY IN QUEUE •
LOCC - LOCATE CHARACTER • • • •
MATCHC - MATCH CHARACTERS
MFPR - MOVE FROM PROCESSOR REGISTER • • • •
MOVC3 - MOVE CHARACTER 3 OPERAND • • • • • •
MOVC5 - MOVE CHARACTER 5 OPERAND • • • • • •
MOVP - MOVE PACKED • • • • • • • • • • • • •
MOVPSL - MOVE FROM PSL • • • • • • • • • • •
MOVTC - MOVE TRANSLATED CHARACTERS • •
MOVTUC - MOVE TRANSLATED UNTIL CHARACTER
MTPR - MOVE TO PROCESSOR REGISTER
MULD - MULTIPLY DOUBLE OPERANDS
MULF - MULTIPLY FLOATING OPERANDS
• • • •
MULG - MULTIPLY FLOAT-G OPERANDS •
MULH - MULTIPLY FLOAT-H OPERANDS •
NOP - NO OPERATION • • • • • • • • •
PROBER - PROBE READ ACCESSIBILITY • • • •
PROBEW - PROBE WRITE ACCESSIBILITY •
• •
REMQHI AND REMQTI - REMOVE ENTRY FROM QUEUE,
INTERLOCKED • • • • • • • • • • •
• •
REMQUE - REMOVE ENTRY FROM QUEUE
ROT - ROTATE A VALUE • • •
SCANC - SCAN CHARACTERS • • • • •
SKPC - SKIP CHARACTER • • • •
SPANC - SPAN CHARACTERS
UBD - SUBTRACT DOUBLE OPERANDS • •
SUBF - SUBTRACT FLOATING OPERANDS
• • • •
SUBG - SUBTRACT FLOAT-G OPERANDS • • • • • •
SUBH - SUBTRACT FLOAT-H OPERANDS • • • • • •
SUBM - SUBTRACT MULTIWORD OPERANDS
TESTBITX - TEST AND MODIFY OPERATIONS
XFC - EXTENDED FUNCTION CALL • • • • •

• •

• •
• •

•
•
•
•
•

• •
• •

• •

4-15
4-15
4-15
4-16
4-16
4-16
4-16
4-17
4-17
4-18
4-18
4-18
4-19
4-19
4-19
4-20
4-20
4-20
4-21
4-21
4-21
4-22
4-22
4-23
4-23
4-23
4-24
4-24
4-25
4-25
4-25
4-26
4-26
4-26
4-27
4-27
4-27
4-28
4-28
4-28
4-29
4-29
4-29
4-30
4-30
4-31
4-31
4-31
4-32
4-32
4-32
4-33
4-33
4-33
4-34
4-34
4-35

PROGRAMMING CONSIDERATIONS
LIBRARY AND REQUIRE USAGE DIFFERENCES
v

• • • • • • 5-1

CONTENTS
Page

5.2
5.2.1
5.2.2
5.2.3
5.2.4
5.2.5
5.2.6
5.2.7
5.2.8
5.3
5.4
5.5
CHAPTER 6

FREQUENT BLISS CODING ERRORS • • •
• • • • • • 5-3
Missing Dots • • • • • • • • • •
• • • 5-3
Valued and Nonvalued Routines
• • • • • • • 5-3
Semicolons and Values of Blocks
• • 5-4
Complex Expressions Using AND, OR, and NOT
• 5-4
Computed Routine Calls • • •
• • 5-4
Signed and Unsigned Fields •
• • 5-5
Complex Macros • • • • •
• 5-5
Missing Code • • • • • •
• • 5-5
ERRORS FROM LINKER • • •
• • 5-6
OBSCURE ERROR MESSAGES •
5-6
PIC CODE GENERATION • • • •
• • 5-6
TRANSPORTABILITY GUIDELINES

6.1
INTRODUCTION • • •
• • • •
6.2
GENERAL STRATEGIES • • • • •
•
•
6.2.1
Isolation
•••••••
6.2.2
Simplicity • • • •
6.3
TOOLS • • • • • • • • • • • • •
6.3.1
•
Literals • • • •
• •••••••
Predeclared Literals •
•
6.3.1.l
User-Defined Literals • • • • •
•
6.3.1.2
• •
Macros and Conditional Compilation
6.3.2
Module Switches • • • • •
•
6.3.3
•
6.3.4
Reserved Names • • • • • • •
REQUIRE and LIBRARY Files • • • •
6.3.5
6.3.6
Routines
• • • •
• • • • •
TECHNIQUES FOR WRITING TRANSPORTABLE PROGRAMS
6.4
6.4.1
Data • • • • • • • • • • • • •
6.4.1.1
Problem Origin • • • • • • • • • • • • •
6.4.1.2
Transportable Declarations • • •
6.4.2
Data: Addresses and Address Calculations •
6.4.2.1
Addresses and Address Calculations • •
6.4.2.2
Relational Operators and Control Expressions
6.4.2.3
BLISS-10 Addresses Versus BLISS-36 Addresses
6.4.3
Data: Character Sequences • • • • • • • • • •
Quoted Strings Used as Numeric Values •
6.4.3.1
Quoted Strings Used as Character Strings
6.4.3.2
6.4.4
PLITs and Initialization
6.4.4.1
PLITs in General • • •
6. 4 .• 4. 2
Scalar PLIT Items
6.4.4.3
String Literal PLIT Items
6.4.4.4
An Example of Initialization •
• • • •
6.4.4.5
Initializing Packed Data ••
6.4.5
Structures and Field Selectors •
• • • •
6.4.5.1
Structures • • • • • • • •
6.4.5.2
FLEX VECTOR
• • • •
6.4.5.3
Field Selectors
GEN VECTOR •
6.4.5.4
6.4.5.5
Summary
CHAPTER 7

• 6-1
• 6-2
• 6-2
6-3
• 6-4
• 6-4
• 6-4
• 6-5
• 6-5
• 6-6
• 6-8
6-9
6-11
6-11
6-12
6-12
6-13
6-14
6-14
6-16
6-17
6-18
6-18
6-19
6-19
6-19
6-20
6-20
6-22

6-25
6-29
6-29
6-30
6-32

6-33
6-35

COMPILER OVERVIEW AND OPTIMIZATION SWITCHES

7.1

COMPILER PHASES • • • • • • • •
Lexical and Syntactic Analysis
7 .1. 2
Flow Analysis • • • • • • • •
7.1.2.1
Knowing When a Value Changes
7.1.2.2
Accounting for Changes •
7 .1. 3
Heuristic Phase
7 .1. 4
Temporary Name Binding •
7 .1. 5
Code Generation • • • •
7 .1.6
Code Stream Optimization •
7 .1.1

7-1
•
•
• •

• • • • • • 7-2

7-3
• 7-3
• • 7-5
7-6

7-7
. • • . . • • . • 7-7
• • • • • • • • • 7-8

CONTENTS
Page
7.1.7
7.2
CHAPTER 8

• • 7-8
• • 7-8

Output File Production ••
SUMMARY OF SWITCH EFFECTS • • • •
TOOLS, LIBRARIES, AND SYSTEM INTERFACES

TRANSPORTABLE PROGRAMMING TOOLS (XPORT)
• • 8-1
8.1
8.1. l
XPORT Data Structures • • • • • • • • • • • • • 8-2
XPORT Input/Output • • • • • • •
• • • • • • 8-2
8.1. 2
XPORT Dynamic Memory Management • • • •
• • 8-3
8.1.3
XPORT Host System Services • • •
• • • 8-3
8.1. 4
XPORT String Handling Facilities
• • • • • 8-3
8.1. 5
BLISS CROSS REFERENCES (BLSCRF)
• • • •
• • 8-4
8.2
Command Line Format • • • • • •
• • • • • • 8-4
8.2.l
Command Semantics
• • • • • •
• • 8-5
8.2.2
Command Qualifiers • • • • • • • • • • • • • • • 8-5
8.2.3
8.3
BLISS LANGUAGE FORMATTER (PRETTY)
• • • • • • • • 8-6
Command Line Format
• • 8-6
8.3.l
Command Semantics
• • 8-6
8.3.2
8.3.3
Formatting Options • •
• • 8-7
Hints on Using Pretty
• • • • • • • • • • 8-10
8.3.4
8.3.4.l
Breaking Lines •
• • • • • • • • 8-11
8.3.4.2
Comments • • • • • •
• • • • • • • • 8-11
8.3.4.3
MACROS • • • • • • •
• • • • • • • • • • 8-12
8.3.4.4
PLITs • • • • • • •
• • • • • • • • • • 8-12
8.4
TUTORIAL TERMINAL INPUT/OUTPUT PACKAGE (TUTIO) • 8-12
8.5
VAX/VMS SYSTEM SERVICES INTERFACE
8-13
8.5.l
Sample Program Using VMS System Services
8-14
8.5.2
Common Errors in Using System Services •
8-15
8.6
RECORD MANAGEMENT SERVICES INTERFACE • • • • • • 8-15
Using RMS-32 Macros • • • • • • • • • • • • • 8-15
8.6.l
8.6.2
Sample Routine Using RMS-32 • • • • • • • • • 8-16
OTHER VAX/VMS INTERFACES
• • • • • • • •
8-17
8.7
LIB
• • • • • •
• • • • • • • • 8-17
8.7.l
8.7.2
TPAMAC • • • • •
• • • • • 8-17
APPENDIX A
A. l

SUMMARY OF COMMAND SYNTAX

A.2
A.3
A.4
A.5

COMMAND-LINE SYNTAX • • • •
FILE SPECIFICATION SUMMARY •
QUALIFIER SYNTAX • • • • • •
QUALIFIER DEFAULTS
ABBREVIATIONS

APPENDIX B

SUMMARY OF FORMATTING RULES

APPENDIX C

MODULE TEMPLATE

c.1
C.2
C.3
C.4
APPENDIX D
D.l
D.2

MODULE PREFACE • • • • • • •
DECLARATIVE PART OF MODULE •
EXECUTABLE PART OF MODULE
CLOSING FORMAT • • • •

••
• • • • • • •
• • • • • •
••
••

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

C-2
• • C-3
• • C-4
• • C-4

IMPLEMENTATION LIMITS
BLISS-32 LANGUAGE
SYSTEM INTERFACES

vii

• • • • • • D-1
• • • • • D-1

CONTENTS

Page
APPENDIX E
E.l
APPENDIX F

ERROR MESSAGES
BLISS COMPILER FATAL ERRORS

E-36

SAMPLE OUTPUT LISTING

FIGURES
FIGURE

2-1
2-2
2-3
2-4
2-5
2-6
2-7
2-8

2-9
8-1
F-1

Compiler Output Listing Sequence •
• • • • • • 2-3
Listing Header Format • • • • • •
• • • • •• 2-4
Default Object Listing Example •
• • • • • • • 2-9
Assembler Input Listing Example
• • • •
2-13
Default Source Listing Example •
• • • •
2-16
Output Listing Example Showing Library and
Require File Information • • •
• • • • • • 2-18
Output Listing Example Showing Macro Expansion
Information • • • • • • • • •
• • • • • • 2-19
Output Listing Example Showing Macro Expansion
and Tracing Information • • • •
2-20
2-23
Error Messages in Source Listing Example
Sample TPARSE Program
• • • • • • • •
8-17
• • F-2
Sample Output Listing • • • • • • • • • •

TABLES
TABLE

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

Correspondence Between Qualifier and Switch Names 1-16
Format of Preface String in Source Listing • • •• 2-5
Arithmetic Expression Operators
•• 3-5
Address Representation Characters
• • • 3-6
Machine-Specific Functions • • • • • •
• • • • 4-2

viii

PREFACE

MANUAL OBJECTIVES
This manual is a user's guide for the VAX-11 BLISS-32 compiler running
under the VAX/VMS operating system.
It is intended as a complement to
the BLISS Language Guide.
It provides three kinds of information:
basic operating
instructions, supplementary programming information,
and reference material.

INTENDED AUDIENCE
This guide is intended for users of the BLISS-32 programming language.
It presupposes some familiarity with the VAX/VMS operating system, its
command language, and file-system conventions.

STRUCTURE OF THIS DOCUMENT
Chapters 1 through 3 describe basic operating instructions.
•

Chapter 1 gives procedures for compiling a BLISS
describes the command qualifiers.

program

and

•

Chapter 2 considers output produced by the -compilation.
The
format and meaning of each of the possible compiler outputs
are described and illustrated.

•

Chapter 3 is concerned with linking, executing, and debugging.

Chapters 4 through 8 supply supplementary programming information.
•

Chapter 4 defines the VAX-11 machine-specific functions.

•

Chapter 5 discusses programming considerations,
use of LIBRARY and REQUIRE facilities.

•

Chapter 6 gives guidelines for writing transportable
programs. Chapter 7 discusses the compiler

•

Chapter 7 describes compiler architecture and the
the command qualifiers related to optimization.

•

Chapter 8 describes some tools related to BLISS programming.

usch

the
BLISS

effects

PREFACE
The appendixes contain reference material.
•

Appendix A summarizes the command syntax, including
command qualifiers, their defaults, and abbreviations.

the

• Appendix B provides formatting rules •
• Appendix c provides a module template.

• Appendix D lists current implementation limits.
Appendix E describes the error messages produced by the
• compiler.
• Appendix F is a sample output, listing.
ASSOCIATED DOCUMENTS
The VAX-11 Information Directory lists and describes all the documents
that you may need to refer to in the course of building and executing
a BLISS program.
Additional documentation that is either directly
relevant to BLISS programming includes the following:

indirectly

•

BLISS language usage:

BLISS Language Guide

•

BLISS syntax summary:

BLISS Pocket Guide

•

Program linking and
execution:

VAX-11 Linker Reference Manual
VAX/VMS Command Language
Use,r' s Guide

•

Symbolic debugging:

VAX-11 Symbolic Debugger
Reference Manual

•

System services:

VAX/VMS System Services
Reference Manual
VAX-11 Record Management
Services Reference Manual
VAX-11 Record Management
Services User's Guide

CONVENTIONS USED IN THIS DOCUMENT
Syntax notation and definitions used in BLISS-32 are explained
thoroughly in Chapter 2 of the BLISS Language Guide. The following is
a summary of syntax notation used in this manual:
{ i tem-1

item-2

item-3 }

~ tem-1 }
item-2
{ item-3

Select exactly
one
of
the
i terns
separated by vertical bars within the
braces.
Select exactly one of the items in
braces on separate but contiguous lines.

PREFACE
item •••

11
The item directly preceding the 11
can be repeated zero or more times with
the items separated by spaces.

i tern, •••

The item directly preceding the 11 , • • • 11
can be repeated zero or more times with
the items separated by commas.

i tern+ •••

The item directly preceding the 11 + ••• "
can be repeated zero or more times with
the items separated by plus signs.

In addition, the red portions of a syntax line or
identify information keyed in by the user.

system-user

dialog

SUMMARY OF TECHNICAL CHANGES

This manual describes Version 3.0 of the BLISS-32 compiler.
This
section summarizes the technical changes in the use of the BLISS-32
since Version 2.0.
/ERROR LIMIT has been added as a general-qualifier
command line.

the

BLISS-32

output

for

The following machine-specific functions have been added.
Arithmetic:
ADDO
ADDH
ADDF
ADDM
ADDG
DIVD

DIVF
DIVG
DIVH

Arithmetic Conversion:
CVTDI
CVTGF
CVTHG
CVTFG
CVTGH
CVTHL
CVTFH
CVTLG
CVTGL
CVTFI
CVTHF
CVTLH

MULH
SUBD
SUBF

MULD
MULF
MULG

SUBG
SUBH
SUBM

CVTRGL
CVTRGH

Arithmetic Comparison:
CMPM
CMPH
CMPG
String Functions:
MOVC3
CMPC3
MOVTC
MOVCS
CMPCS
MATCHC

LOCC
SKPC

Additional BUILTIN Functions:
ASHP
XFC
The following
parameters.

machine-specific

CAL LG
CMPC3
CM PCS
CMPP

CVTPT
CVTSP
CVTTP
EDIT PC

CRC
CVTLP
CVTPL
CVTPS

functions

LOCC
MATCHC
MOVC3
MOVCS

MOVP
MOVTC
MOVTUC
SCANC

will
SKPC
SPANC

The following VAX/VMS DEBUG V3 commands are supported.
CANCEL SOURCE
SEARCH
SET MARGIN
SET MAX SOURCE FILES

SET SEARCH
SET SOURCE
SET STEP LINE
SHOW MARGIN

xiii

SHOW SEARCH
SHOW SOURCE
STEP LINE
TYPE

SUMMARY OF TECHNICAL CHANGES
The /DEBUG command line qualifier now generates source-line number
information in the DEBUG symbol table when the compiler executes under
VAX/VMS Version 3.0.
The compilation summary is now generated as part of the statistics.
The BLISS-32 compiler accepts quoted strings up to 1000 characters
length.
Appendix E includes changes in diagnostic messages.
expanded to describe corrective actions.

xiv

It has also

in
been

CHAPTER 1
OPERATING PROCEDURES

This chapter discusses the operating procedures used to compile a
BLISS module.
The form of the command line is considered first.
Next, the file specifications for input to a BLISS-32 compilation are
described and illustrated.
Finally, the command-line qualifiers
relevant to a BLISS-32 compilation are given.
The procedure for compiling, linking, and executing a BLISS-32 program
is uncomplicated.
For example, to compile and execute a program
consisting of a single source module, enter the module in a file,
for
example, ALPHA.B32,
compile it with the BLISS-32 compiler, link it
using the VAX/VMS linker, and execute the linked image.
The command
sequence to do this is:
$ BLISS ALPHA
$LINK ALPHA
$RUN ALPHA

The first command invokes the BLISS compiler to compile the module in
the file ALPHA.B32 . and to produce an object file ALPHA.OBJ. The
second command uses the object module in the file ALPHA.OBJ to produce
an executable image in the file ALPHA.EXE. The third command executes
the image in the file ALPHA.EXE.
However, the more usual case involves the compilation and linking of
several
(and possibly a large number)
of source modules into one
executable image.
You can use command-line qualifiers to control the compiler.
These
qualifiers add a level of complexity to the compilation process.
However, they provide a means by which you can vary the performance of
the compiler, for example, in the production of output, in the
formatting of listings, and in the degree of optimization to be
performed.

1.1

COMPILING A BLISS MODULE

To compile a BLISS module, the programmer issues the BLISS system
command and a BLISS command line. The command line consists of one or
more source file names optionally preceded by command-line qualifiers.
(Refer to "Command Line Syntax" below.)
Some BLISS command line
examples follow.

1-1

OPERATING PROCEDURES
•

To compile a module, give the following command:
$ BLISS MYPROG
The BLISS compiler uses file MYPROG.B32 as input, compiles the
source in that file, and produces an object file, MYPROG.OBJ.

•

To produce a listing file, use the /LIST output qualifier:
$ BLISS/LIST MYPROG
In addition to the object file, the
the listing file, MYPROG.LIS.

•

BLISS

compiler

produces

To produce an object file with a name different from
source file, give the name in tha command as follows:

the

$ BLISS/OBJECT=GAMMA ALPHA
The BLISS compiler produces the object file, GAMMA.OBJ.
•

To produce a BLISS library file instead of an object file, use
the /LIBRARY command qualifier:
$ BLISS/LIBRARY ALPHA
The BLISS compiler compiles the
input
produces the library file, ALPHA.L32.

•

file,

ALPHA.R32,

and

To compile more than one module, include a list of input files
separated by commas:
$BLISS ALPHA,BETA,GAMMA
The compiler compiles ALPHA.B32,
producing the object
ALPHA.OBJ,
then
BETA.B32, producing BETA.OBJ,
and
GAMMA.B32, producing GAMMA.OBJ.

•

file
then

To compile a module that consists of several pieces, each in a
separate file, use the concatenation indicator (+):
$ BLISS ALPHA+BETA+GAMMA
The BLISS compiler compiles the source module
concatenation of ALPHA.B32,
BETA.B32,
and
produces the single object file ALPHA.OBJ.

1.1.1

formed by
GAMMA.B32,

Command-Line Syntax

compilation-request

$ BLISS bliss-command-line

bliss-command-line

{ qualifier, •••

input-spec

file-spec { +. •.} {qualifier, ••• }

space

{ blank

qualifier

I tab }

} space input-spec, •••

...

output qualifier
general qualifier
terminal qualifier
optimization qualifier
source-list qualifier
machine-code-list qualifier

{

1-2

}

the
and

OPERATING PROCEDURES
The dollar sign ($) represents the VMS command-level prompt character.
As indicated in the syntax rule, a space must immediately precede the
first or only input-spec.
Optional spaces may be used before or after
any delimiter character shown in this and subsequent syntax diagrams.
The applicable delimiters are the comma (,),plus sign (+), slash {/),
equal sign (=),and colon (:).

1.1.2

Command-Line Semantics

The BLISS-32 compiler uses command-line qualifiers given in the
bliss-command-line
to
modify
their default settings for each
compilation. Then, each input-spec is compiled separately in the
context of the initial default qualifier settings. Qualifiers and
their initial default settings are described in Section 1.3.
Unless a qualifier to change the compiler's behavior is given,
the
output from a compilation initiated from your terminal is the object
file and the terminal listing, and the output from a compilation given
in a batch file is an object file and listing file.
The compiler uses the contents of a file or of a series of files
joined
(concatenated)
by plus signs
(+) as input to a BLISS
compilation. The compiler begins processing with the first file given
in an input-spec and continues until an end-of-file is reached.
It
continues to read input until all files specified in the input-spec
have been read.
Command-line switches can appear in two places in a
command line:
before the first
input-spec and after individual
input-specs.
Those appearing before the first
input-spec have a
global application to all input-specs in the command-line, for
example:

$ BLISS/LIBRARY ALPHA,BETA+THETA+ZETA,OMEGA
Those appearing at the end of an
input-spec they follow, for example:

input-spec

apply

only

the

$ BLISS/LIBRARY ALPHA,BETA/OBJECT,IOTA
If no command-line switches exist in a command line, default switch
settings are assumed for all input-specs in the command line. All
switches have an assigned default setting or value.
The only required space in the command line separates
input-spec from preceding global command-line switches.

1.2

the

first

FILE SPECIFICATIONS

File specifications are used to name the source of program text to be
compiled and the destination of output from the compilation. More
precisely, file specifications can occur in three contexts:
•

In the input-specs of a bliss-command-line

•

As the values of the qualifiers /OBJECT, /LIBRARY, and /LIST

•

In REQUIRE
compiled

and

LIBRARY

declarations

1-3

the

module

being

OPERATING PROCEDURES
The file-spec is a standard VAX/VMS file specification, as described
in the VAX/VMS Command Language User's Guide.
(See Appendix A.}
A file specification is interpreted as follows:
1.

Logical name translation occurs.

If a file-type is not given, a default file type is used,
described in the next section.

If the file-spec applies to an output file and a filename is
not given,
then the name of the first or only input file in
the input-spec is used.

The compiler uses this same interpretation when it processes the file
specification given in a REQUIRE or LIBRARY declaration.
(Refer to
Chapter 16 of the BLISS Language Manual The compiler has two ordered
lists of default file types to be tried for an input-spec that does
not include a file
type.
The default type the compiler applies
depends on the output to be produced by the compilation, as indicated
in the following list:
Default Type List

Input-spec used to Produce
an object module

.B32,

.BL!

a 1 ibrary file

.R32, .REQ,

.B32,

.BL!

If the program being compiled contains a REQUIRE
or
LIBRARY
declaration,
the compiler uses the following lists to search for the
appropriate file type according to the type of declaration:
File Use

Default Type List

File given in a
REQUIRE declaration

.R32,

File given in a
LIBRARY declaration

.L32

.REQ, .B32, .BL!

For example, suppose you have entered the following source text in the
file ALPHA. BL!:
MODULE MYTEST
BEGIN
REQUIRE 'CBLISS';
LIBRARY 'TBLISS';
END
ELUDOM
and you use the following command line to compile it:

$ BLISS ALPHA
Since the bliss-command-line contains no qualifier requesting that a
library file be produced, the output of the compilation is an object
module.
Therefore, the compiler chooses the list of default types
associated with object module output and searches first for ALPHA.B32,
then, not finding
that file,
for ALPHA.BL!, which it finds and
compiles.

1-4

OPERATING PROCEDURES
In processing the module MYTEST in that file, the compiler encounters
the REQUIRE declaration for the file CBLISS.
Since no file type for
CBLISS is given, the compiler uses the list of default types for files
in a REQUIRE declaration and searches for CBLISS.R32, then CBLISS.REQ,
then CBLISS.B32, then CBLISS.BLI. When the compiler processes the
LIBRARY declaration,
it uses the default type list associated with
library declarations and searches for TBLISS.L32.

1.3

COMMAND-LINE QUALIFIERS

Command-line qualifiers provide control over many aspects of the
compilation. Valid command-line qualifiers and their functions are:
•

output qualifier - defines the types of output to be produced

•

general qualifier - sets a %VARIANT value and
and debug information

•

terminal qualifier - controls output produced on a terminal

•

optimize qualifier - supplies code optimization strategies and
directions

•

source-list qualifier - provides output
concerning the form of the source part

•

machine-code-list
qualifier - provides
output
information concerning the form of the object part

1.3.1

specifies

listing

code

information
listing

Output Qualifiers

Output qualifiers are used to indicate the type of output to be
produced from a BLISS-32 compilation and to give names for the files
to be produced when you do not want to use the default names.
Some
examples of output qualifiers are given in the following list:
•

To suppress the production of an object file,
/NOOBJECT qualifier in the command line, as follows:

use

the

$ BLISS/NOOBJECT ALPHA
The BLISS-32 compiler reads the source in the file ALPHA.B32
and produces no output files.
The only outputs are the error
messages and summary information produced at the terminal.
•

To obtain a list file for a single source file, use the
qualifier, as follows:

/LIST

$ BLISS/LIST ALPHA
The BLISS-32 compiler produces an object file ALPHA.OBJ and a
list file ALPHA.LIS.
(The /LIST qualifier is assumed by
default in a batch command.)
•

To use a different name for the object or list files, use
following qualifiers:

the

$ BLISS/OBJECT=BETA/LIST=GAMMA ALPHA
The compiler reads the input file ALPHA.B32 and produces
object file BETA.OBJ and the list file GAMMA.LIS.

1-5

the

OPERATING PROCEDURES
•

To produce a library file rather than an object file, use
/LIBRARY qualifier, as follows:

the

$ BLISS/LIBRARY ALPHA
The compiler reads the input file ALPHA.B32 and
library file ALPHA.L32.

1.3.1.l

produces

the

Syntax - Output qualifier syntax is defined as follows:

output qualifier

/OBJECT {=file-spec}
I /NOOBJECT }
/LIST {=file-spec}
I /NOLIST
{ /LIBRARY {=file-spec} I /NOLIBRARY

The compiler can produce either a library or an object file, but not
both.
Therefore, the file-designators /OBJECT and /LIBRARY are
mutually exclusive; they must not be given in the same command line.

1.3.1.2 Defaults - In the absence of an explicit choice of output
qualifier,
the following qualifiers are assumed by default in
interactive mode:
/OBJECT

/NOLI ST

/NOLIBRARY

In batch mode, a list file is produced
following qualifiers are assumed:
/OBJECT

/LIST

default;

that

is,

the

/NOLIBRARY

If a file-spec is not given, the file name of the first file
in the
input-spec is combined with the default file type to form the
file-spec.
If a file-spec is given but the file-spec does not include
a file type, the following default file-types are applied, depending
on the file-designator:
File-Designator

Default Type

/OBJECT

OBJ

/LIST

LIS

/LIBRARY

L32

1.3.1.3 Semantics - The
interpretation:

output

qualifiers

the

following

/OBJECT=file-spec

Produce an object file in the file
by file-spec.

specified

/OBJECT

Produce an object file in the file
by 'input-file-name.OBJ'.

specified

/NOOBJECT

Do not produce an object file.

/LIST=file-spec

Produce a list file in the file specified
file-spec.

l...;.6

have

OPERATING PROCEDURES
/LIST

Produce a list file in the file specified
'input-file-name.LIS'.

/NOLI ST

Do not produce a list file.

/LIBRARY=file-spec

Produce a library file in the file
by file-spec.

specified

/LIBRARY

Produce a library file in the file
by 'input-file-name.L32'.

specified

/NOLIBRARY

Do not produce a library file.

1.3.2

General Qualifiers

General qualifiers are used to specify code and debug information and
to set the value for the lexical function %VARIANT.
Some examples of
the use of general qualifiers follow:
•

To conserve object-file storage space, use
qualifier in the command line, as follows:

the

/NOTRACEBACK

$ BLISS/NOTRACEBACK ALPHA
The compiler produces the
ALPHA.OBJ,
by
omitting
information.
•

m1n1mum size object
all
debugging
and

module
in
traceback

To include the necessary debug
information in the object
module so that you can symbolically address declarations other
than routine declarations,
use the /DEBUG qualifier, as
follows:

$ BLISS/DEBUG ALPHA
The compiler reads the source from ALPHA.B32 and creates an
object file ALPHA.OBJ, which includes additional debug tables.
•

To check the syntax of a program you do not intend to execute,
use the /NOCODE qualifier to save compilation time,
as
follows:

$ BLISS/LIST/NOCODE ALPHA
•

To set the value of the lexical function %VARIANT to
example, use the /VARIANT qualifier as follows:

17,

for

$ BLISS/VARIANT=l7 ALPHA

1.3.2.1

Syntax - General qualifier syntax is defined as follows:

general qualifier

/TRACEBACK I /NOTRACEBACK
/DEBUG
I /NODEBUG
/CODE
I /NOCODE
/VARIANT { =value }
/ERROR_LIMIT { =value }

If the qualifier /NOTRACEBACK is given, then the qualifier
meaningless and, therefore, should not be given.

1-7

/DEBUG

OPERATING PROCEDURES
1.3.2.2 Defaults - In the absence of an explicit choice of
qualifier, the following qualifiers are assumed by default:
/TRACEBACK

/NODEBUG

/VARIANT=O

/CODE

general

/ERROR_LIMIT=30

The compiler produces code, does not include the additional debugging
information in the object file, and sets the value of %VARIANT to O.
If the general qualifier /VARIANT is given without a specified
then a value of 1 is assumed.

1.3.2.3 Semantics - The interpretation of the command
given in the following list:

value,

qualifiers

/TRACEBACK

Generate information in the object module that can
be used by the VAX-11 Debugger to locate module,
routine, and program section (PSECT) names.

/NOTRACEBACK

Produce the minimum size object module.
Do not
include any information for debugging or tracing.

/DEBUG

Generate information in the object module that can
be used by the VAX-11 Debugger to reference names
declared within the BLISS module.

/NODE BUG

Do not generate any additional debug
information.
If this switch is applied either explicitly or by
default,
the VAX-11 Debugger can only locate
module, routine, and PSECT names.

/CODE

Generate object code for the BLISS source module.

/NOC ODE

Perform only a syntax check of the program.

/VARIANT

Set %VARIANT to 1.

/VARIANT=n

Set %VARIANT to n, where n is a decimal integer in
the range:
-(2**31)

/ERROR_LIMIT

< n < (2**31)-1

Set limit to 1

/ERROR_LIMIT=n Terminates compilation after
diagnostics are encountered.

error

level

1.3.2.4 Discussion - An object module can be produced with the
following degrees of information for the linker, debugger, and the
operating system.
•

No information (/NOTRACEBACK)

•

Basic
information about
(/TRACEBACK and /NODEBUG)

modules,

1-8

routines,

and

PSECTs

OPERATING PROCEDURES
•

Information about modules, routines, PSECTs, and
names (/TRACEBACK and /DEBUG)

data-segment

The default object module contains the basic
information.
For
example,
if a program fails because of an access violation, VMS can
display the state of the program when the violation occurred through
its traceback facility.
Further, the VAX-11 Debugger can be used to
refer to modules,
routines,
and PSECTs symbolically and to call
routines.
The /NOTRACEBACK qualifier should be used only when object modules for
well-checked-out programs are being generated and when the space to be
occupied by these modules must be kept at a minimum.
Use of the
/NOTRACEBACK qualifier reduces the size of the object module, and to a
lesser degree the size of the executable image, out deprives the
object module of information that could be valuable at execution time.

1.3.3

Terminal Qualifier

The terminal qualifier
the terminal.
You can
on the terminal during
examples of the use of
•

is used to control the output that is sent to
have errors or statistics printed or suppressed
the compilation of a
BLISS program.
Some
the terminal qualifier are as follows:

To see the statistics for each routine as they are produced
during
the compilation, specify the terminal qualifier, as
follows:

$ BLISS/TERMINAL=STATISTICS ALPHA
•

To suppress error messages and
following:

get

statistics,

use

the

$ BLISS/TERMINAL=(NOERRORS,STATISTICS) ALPHA

1.3.3.1

Syntax - Terminal qualifier syntax is defined as follows:

terminal qualifier

/TERMINAL=

terminal-value

{

ERRORS
STATISTICS

{(

terminal-value
terminal-value

I
I

, ... )

}

NOERRORS
}
NOSTATISTICS

1.3.3.2 Defaults - In the absence of
an
explicit
choice
terminal-value, the following values are assumed by default:
ERRORS

NOSTATISTICS

Errors are reported on the
statistics are suppressed.

terminal

1-9

during

the

compilation,

but

OPERATING PROCEDURES
1.3.3.3 Semantics - The /TERMINAL qualifier indicates that one or
more terminal-values follow.
The terminal-values have the following
meanings:
Terminal-Value

Meaning

ERRORS

List each error on the terminal
encountered in the compilation.

NO ERRORS

Do not list errors on the terminal.

STATISTICS

List the name and size of each routine on the
terminal after each routine is compiled.

NOSTATISTICS

Do not list routine names and sizes.

1.3.4

Optimize Qualifier

The optimize qualifier is used to supply directions to the compiler
about the degree and type of optimization wanted and to make
assertions about the program so that the compiler can select the
appropriate optimization strategies.
Some examples of the use of the
optimize qualifier are as follows:
•

To increase the compilation speed by omitting
optimizations,
use the /OPTIMIZE qualifier
QUICK in the command line, as follows:

some standard
with the value

$ BLISS/OPTIMIZE=QUICK ALPHA
Note that use of QUICK turns off
Section 7.1.2.)
•

flow

analysis.

(Refer

To get minimum optimization, use the /OPTIMIZE qualifier
the value LEVEL:O, as follows:

to
with

$ BLISS/OPTIMIZE=LEVEL:O ALPHA
•

To obtain maximum optimization, use
with the value LEVEL:3, as follows:

the

/OPTIMIZE

qualifier

$ BLISS/OPTIMIZE=LEVEL:3 ALPHA
•

To direct the compiler to use techniques that may generate a
larger program in order to increase its operating efficiency,
give the /OPTIMIZE qualifier with the value SPEED, as follows:

$ BLISS/OPTIMIZE=SPEED ALPHA
•

To inform the compiler that the program uses pointers to
manipulate named data,
use the /OPTIMIZE qualifier with the
value NOSAFE, as follows:

$ BLISS/OPTIMIZE=NOSAFE ALPHA
A detailed discussion of the optimizations resulting from the
the /OPTIMIZE qualifier is given in Chapter 7.

1-10

use

OPERATING PROCEDURES
1.3.4.1

Syntax - Optimize qualifier syntax is defined as follows:

optimize qualifier

{ ( optimize-value
optimize-value

/OPTIMIZE=

optimize-value

QUICK
I NOQUICK
SPEED I SPACE
LEVEL : optimize-level
SAFE
I NOSAFE

optimize-level

{

' ... )

}

The optimize-values SPEED and SPACE are mutually exclusive;
not be given in the same command line.

they must

1.3.4.2 Defaults - In the absence of
an
explicit
choice
optimize-value, the following values are assumed by default:

NOQUICK

SPACE

LEVEL:2

SAFE

The compiler is directed:
To perform normal optimization, biasing
trade-off in favor of minimum program size

•

To assume that all variables are addressed by name only

•

To perform optimization
7.1.2.2.)

across

mark

the

speed/space

•

points.

(See

Section

1.3.4.3 Semantics - The /OPTIMIZE qualifier indicates that one or
more optimize-values are given. Optimize-values have the following
meanings.
Optimize-Value

Meaning

QUICK

Omit
some
standard
optimizations
(for
example, turn off flow analysis) in order to
increase compilation speed.

NOQUICK

Perform standard optimizations.

SPEED

Increase the potential execution speed of the
program being compiled (if possible) by using
more space where
necessary.
For
more
information on the effect of this value, see
Section 7.1.4.
(Note: SPEED is equivalent
to the module-switch ZIP.)

SPACE

Keep program size to a minimum at
the
possible expense of operating speed.
For
more information on the effect of this value,
see
Section
7.1.4.
(Note:
SPACE is
equivalent to the module-switch NOZIP.)

1-11

OPERATING PROCEDURES
LEVEL

Optimize the program being compiled according
to the optimize-level given, as follows:
Meaning

Optimize-Level

Minimum optimization
Subnormal optimization
Normal optimization
Maximum optimization

1
2

LEVEL:3 optimizes speed at the expense of
space in the same way as SPEED.
For more
information on the effect of this value, see
Section 7.2.
SAFE

Assume that all named data-segments
are
referenced by name only and not manipulated
indirectly in any way, and use optimization
techniques that exploit this fact.
For more
information on the effect of this value, see
Section 7.1.2.1.

NOSAFE

Assume that sometimes a named data-segment is
referenced by means of a computed expression
and, therefore, some optimization techniques
cannot be used.

1.3.5

Source-List Qualifier

The source-list qualifier is used to supply information about the form
of the source part of the output listing.
Some examples of the use of
the source-list qualifier are as follows:
•

To obtain a paged listing with 44 lines on each page, give the
following source-list qualifier:
$BLISS/LIST/SOURCE_LIST=PAGE SIZE:44 ALPHA

•

To obtain an unpaged listing in which the macro expansions are
given, use the following source-value:

$ BLISS/LIST /SOURCE_LI ST= (NOHEADER, EXPAND MACROS) ALPHA
•

To obtain a listing that contains the contents of the REQUIRE
files
given in REQUIRE declarations, use the following
source-value:
$BLISS/LIST/SOURCE_LIST=REQUIRE ALPHA

1-12

OPERATING PROCEDURES
1.3.5.1

Syntax - Source-list qualifier syntax is defined as follows:

source-list qualifier

source-value

I
I

number-of-lines

{ ( source-value
source-value

/SOURCE_LIST=

... }
)

'II

HEADER
I NOHEADER
PAGE SIZE : number-of-lines
LIBRARY
I NOLIBRARY
REQUIRE
I NOREQUIRE
EXPAND MACROS
I NOEXPAND MACROS
TRACE MACROS
I NOTRACE MACROS
SOURCE
I NOSOURCE

{ 20 I 21 I 22 I

I
)

... }

1.3.5.2 Defaults - In the absence of
an
explicit
choice
source-value, the following values are assumed by default:
HEADER PAGE SIZE:58 NOLIBRARY
NOEXPAND MACROS NOTRACE MACROS

NOREQUIRE
SOURCE

The compiler produces a paged listing with 58 lines on each
which no expansion or tracing is included.

page,

1.3.5.3 Semantics - The /SOURCE LIST qualifier indicates that one or
more source-values are given for the compilation. The source-values
have the following meanings:
Meaning

Source-Value
HEADER

Page the listing produced on the list
and include a heading on each page.

NO HEADER

Do not page the listing, do not include
headings, and do not produce statistics in
the compilation summary. Use this value if
the assembleable listing is to be assembled.

PAGE SIZE:lines

Use the number of lines specified for each
page of the list file.
The number of lines
must be greater than 19.

LIBRARY

Produce a trace
in
the
listing
file
identifying
the library after a LIBRARY
declaration and the first use of each name
whose definition is obtained from a library
file.
For an example of a library trace, see
Section 2.2.4.2.

NO LIBRARY

Do not produce a trace identifying
libraries and their contributions.

REQUIRE

Include source text
files in listing.

1-13

obtained

from

file

any

require

OPERATING PROCEDURES
NORE QUIRE

Do not include require-file text.

EXPAND MACROS

Include the expansion of each macro call
in
the listing file.
For an example of a macro
expansion, see Section 2.2.4.3.

NOEXPAND MACROS

Do not include the expansion of macros.

TRACE MACROS

Include a trace of each macro expansion.
That is,
include the parameter binding and
any intermediate forms of expansion, as well
as the result of the expansion.
For an
example of a macro trace,
see
Section
2.2.4.4.

NOTRACE MACROS

Do not include a trace of macro expansions.

SOURCE

Increment the
listing
control
counter.
Output is listed when the listing control
counter is positive and not listed when the
counter is zero or negative.

NOSOURCE

Decrement the listing control counter.

1.3.6

Machine-Code-List Qualifier

The machine-code-list qualifier
is used to give
the
compiler
instructions about the form of the object part of the output listing.
Some examples of the use of the machine-code-list qualifier are as
follows:
•

To obtain an output listing that can be subsequently edited
and then reassembled by the VAX-11 MACRO assembler, use the
ASSEMBLER code-value, as follows:

$ BLISS/LIST/MACHINE_CODE_LIST=ASSEMBLER ALPHA
•

To obtain a listing that can be assembled and that
contain binary, include the NOBINARY code-value:

does

not

$ BLISS/LIST/MACHINE_CODE_LIST=(ASSEMBLER,NOBINARY) ALPHA
The form of the output listing
is described in Section 2.2.
The
object code part of that listing depends on the machine-code-list
qualifier.

1.3.6.1 Syntax - Machine-code-list qualifier
follows:
machine-code1 ist qualifier

code-value

/MACHINE_CODE_LIST=
OBJECT
ASSEMBLER
SYMBOLIC
BINARY
COMMENTARY
UNIQUE_NAMES

{

1-14

I
I
I
I
I
I

syntax

defined

{ ( code-value , ••• )
code-value
NOOBJECT
NOASSEMBLER
NOSYMBOLIC
NOBINARY
NOCOMMENTARY
NOUNIQUE_NAMES

}

OPERATING PROCEDURES
1.3.6.2 Defaults - In the absence of an explicit
value, the following values are assumed by default:
OBJECT

NOASSEMBLER

SYMBOLIC

BINARY

choice

COMMENTARY

code-

NOUNIQUE_NAMES

The compiler produces a listing that resembles the output
the VAX-11 MACRO assembler.

listing

1.3.6.3 Semantics - The /MACHINE CODE LIST qualifier indicates that
one or more code-values follow~ The code-values have the following
meanings:
Code-Value

Meaning

OBJECT

Produce the
listing.

object

part

the

output

NOOBJECT

Suppress
listing.

object

part

the

output

ASSEMBLER

Produce a listing that can be assembled,
by
listing the assembler instructions produced
as a result of compiling the BLISS program
and
including all other information within
comments. must also be specified,
if this
output is to be assembled.
If this output is
to
be
assembled,
the
qualifiers
/SOURCE LIST:NOHEADER
and
/MACHINE CODE LIST:UNIQUE NAMES must also be
specified.
-

NOASSEMBLER

Do not list the assembler instructions.

SYMBOLIC

Include a machine code listing that
names from the BLISS source program.

uses

NOSYMBOLIC

Do not include a machine code
uses source program names.

that

COMMENTARY

Include a machine-generated commentary in the
object code listing.
At this time,
the
machine-generated commentary is limited to a
cross-reference.x

NOCOMMENTARY

Do not include a commentary
object code listing.

the

BINARY

Include a listing of the binary for
instruction in the object code listing.

each

NOBINARY

Do not include a listing of the binary.

UNIQUE_NAMES

Replace names by machine-generated names so
that all names are unique, independent of
scope so that the resulting listing can be
correctly assembled.
(See ASSEMBLER above.)

NOUNIQUE_NAMES

Do not replace names by unique names.

the

listing

field

Each of the code-values is described and illustrated in Section 2.2.3
in
connection
with the discussion of the output compilation.
Understanding the purpose of these code values requires knowledge of
the format and purpose of the output listing, as discussed in that
section.
1-15

OPERATING PROCEDURES
1.3.7

Qualifier Names vs. Switch Names

Some directions can be given to the compiler either by command line
qualifiers or by switch settings contained in the· module being
compiled.
In some cases, the qualifier name is the same as the switch
name
(module switches and SWITCHES declarations), and in other cases,
it similar but not identical.
The names of the corresponding
qualifiers and switch items are given in Table 1-1.
Table 1-1:

Correspondence Between Qualifier and Switch Names

Qualifier Name

/CODE
/DEBUG
/MACHINE CODE LIST=ASSEMBLER
/MACHINE-CODE-LIST=BINARY
/MACHINE-CODE-LIST=COMMENTARY
/MACHINE-CODE-LIST=OBJECT
/MACHINE-CODE-LIST=SYMBOLIC
/MACHINE-CODE-LIST=UNIQUE NAMES
/OPTIMIZE=LEVEL:n
/OPTIMIZE=SAFE
/OPTIMIZE=SPACE
/OPTIMIZE=SPEED
/SOURCE LIST=EXPAND MACROS
/SOURCE-LIST=LIBRARY
/SOURCE-LIST=REQUIRE
/SOURCE-LIST=SOURCE
/SOURCE-LIST=TRACE MACROS
/TERMINAL=ERRORS n/a (not applicable)

1.3.8

Module-Head
Switch

SWITCHES-Deel.
Switch

CODE
DEBUG
LIST (ASSEMBLY)
LIST (BINARY)
LIST(COMMENTARY)
LIST (OBJECT)
LIST (SYMBOLIC)
UN AMES
OPTLEVEL=n
SAFE
NOZIP
ZIP
LIST(EXPAND)
LIST (LIBRARY)
LIST (REQUIRE)
LIST(SOURCE)
LIST(TRACE)
ERRS

n/a
n/a
LIST (ASSEMBLY)
LIST (BINARY)~
LIST (COMMENTARY)
LIST (OBJECT)
LIST (SYMBOLIC)
UNAMES
n/a
SAFE
NOZIP
ZIP
LIST (EXPAND)
LIST (LIBRARY)
LIST (REQUIRE)
LIST (SOURCE)
LIST (TRACE)
ERRS

indicates that no corresponding switch exists.

Qualifiers and Default Settings

Qualifiers given in the command line alter the default settings
assumed for module-head switches.
A switch setting given in the
module head overrides the corresponding qualifier given in the
command-line;
any switch setting given in a SWITCHES-declaration
overrides the setting given in the module head.
Suppose you are compiling two modules. The first module ALPHA.832 has
a module switch CODE.
The second module BETA.832 has no switches.
The bliss-command-line is as follows:
$BLISS/NOCODE ALPHA,BETA
The qualifier /NOCODE changes the initial default setting from /CODE
to /NOCODE. When the module ALPHA.B32 is compiled, code is produced,
because ALPHA.B32 has the module-head switch CODE, which overrides the
default setting.
When the module BETA.B32 is compiled, no code is
produced because it takes its setting of that switch from the initial
default setting established in the command line.

1-16

OPERATING PROCEDURES
1.3.9

Positive and Negative Forms of Qualifiers

In general, two forms of a qualifier are allowed, namely: a positive
form and a negative form.
For example, /CODE {the positive form)
directs the compiler to generate code, and /NOCODE {the negative form)
directs the compiler to suppress code generation. Generally, positive
and negative forms of a qualifier are mutually exclusive;
however,
exceptions can occur such as in the following example:
$BLISS/LIST ALPHA,BETA/NOLIST,GAMMA
The qualifier /LIST creates ALPHA.LIS and GAMMA.LIS, while the /NOLIST
qualifier prevents the creation of a listing file for BETA.B32

1.3.10

Abbreviations of Qualifier and Value Names

Command qualifier names and value names can be abbreviated.
A valid
abbreviation consists of the minimum number of characters required to
identify a given command keyword without ambiguity.
A list of the
BLISS-32 command abbreviations and values are given in Appendix A.

1-17

CHAPTER 2
COMPILER OUTPUT

This chapter discusses compiler output, specifically as it appears
terminal output, various list file formats, and error messages.

The input to a BLISS compilation is a BLISS module.
As an example,
consider the following module:
it contains two OWN declarations and
three ROUTINE declarations.
The routine IFACT computes the factorial
of its argument by an iterative method.
The routine RFACT computes
the factorial of its argument by a
recursive method.
The routine
MAINPROG provides some test calls on IFACT and RFACT.
Factorial
0
routines are discussed
in Chapter 12,
Routines,"
in the BLISS
Language Guide.
module testfact (main = mainprog)
begin
own

a,
b;
routine ifact (n)
begin
local
result;
result = l;
incr i from 2 to .n do
result = .reult*.i;
.result
end;
routine rfact (n) =
if .n gtr 1 then .n*rfact (.n -

1) else l;

routine mainprog : novalue =
begin
a = ifact (5);
b = rfact (5);
end;
end
eludom
This module is used in the following sections to illustrate various
BLISS compilation output listings.
Two coding errors (missing equal
sign after the module-head and misspelled data-name) are
included to
illustrate the error reporting facility of BLISS.

2-1

COMPILER OUTPUT
2.1

TERMINAL OUTPUT

The compiler produces two kinds of information on the terminal: error
messages and statistics. Each of these can be requested or suppressed
by the use of the terminal qualifier, as described in Section 1.3. By
default,
error
messages
are reported during compilation, but
statistics are suppressed. A final compilation summary is evoked as
part of a statistics request.
Error messages show the source 'program line associated with the error
followed by a description of the error. The statistics show the name
of each routine declaration in the module and the number of bytes
associated with that declaration. The compilation statistics give the
number of warning and error messages, the number of code bytes and
data bytes used by the program, the run time and elapsed time required
for the compilation:, and the number of pages of VAX-11 memory required
for the compilation.
The last line of, the terminal output indicates whether the compilation
produced an object file or a library file.
If an object file is
produced, the last fine is:
; Compilatiori

Co~pl~te

If a library file is produced, the last line is:
; Library Precompilation Complete
Consider the terminal output for the sample module TESTFACT contained
in the file MYPROG.B32.
To obtain both kinds of information, compile
the module by using the following bliss-command-line:
$BLISS/TERMINAL=STATISTICS MYPROG
The qualifier /TERMINAL=STATISTICS is used so that both types of
output are sent to the terminal. The terminal output is as follows:
begin
;
0002
1 Ll:0002
% WARN#048
Syntax error in module head
0014
result= .reult*.I;
% WARN#OOO
•••••••••••••••••• 1 Ll:0014
; Undeclared name: REULT
!FACT 22
RFACT 26
MAINPROG 28
Warnings:
2
Errors:
0
Size:
76 code + 8 data bytes
Run time:
00:01.5
Elapsed time: 00:03.5
Memory used:
10 pages
; Compilation Complete
%BLS32-W-CMPWARN, Compilation with warnings
Terminal output for the ~ompilation of MYPROG includes two warnings,
which are described later. Statistics following the warnings show the
number of bytes required for each routine.
The module TESTFACT
contains
three routine declarations, namely,
IFACT, RFACT, and
MAINPROG, and they use 22,
26, and 28 bytes, respectively.
The
compilation summary shows that the compilation of TESTFACT required
1.5 seconds of processor time and that 3.5 seconds elapsed.
The
compilation required nine pages of memory, excluding memory required
for the compiler itself.

2-2

COMPILER OUTPUT
2.2

OUTPUT LISTING

The output listing produced as a result of a BLISS compilation
consists of source listings, which include any error messages, object
listings, and a compilation summary.
When the compiler completes the processing of a routine declaration,
it produces the source and object listing for that declaration and any
nonroutine declarations that preceded it. In this way, the output
listing is divided into a sequence of segments.
(See Figure 2-1.)

Source
}

Segment 1

}

Segment 2

}

Segment n

Object
Source
Object
Source
Object
Source
Object
Object Summary
Compilation Statistics

Figure 2-1:

Compiler Output Listing Sequence

Both the source and object parts of a routine segment can be
suppressed and the format of the object part can be changed by the
inclusion of switches in the module or qualifiers in the command line.
In the absence of any explicit instruction, both source and object
parts are produced. If the object part of the program is produced, an
object summary is given. The object summary contains a PSECT summary
and, if the compilation included any LIBRARY declarations, a summary
of
library
usage.
The compilation summary contains the same
information as given in the compilation summary at the terminal.
The complete output listing for the module TESTFACT occupies several
pages.
(Refer to "Default Object Listing" later in this chapter.) The
routine segment for the routine !FACT contains the module heading, the
OWN
declaration, and the routine declarations for !FACT.
The
following sections discuss each part of the output listing.
!for that
routine segment in detail.

2.2.1

Listing Header

Listing headers consist of two lines; each line consists of three
fields separated by at least one space. The first field contains
information in print positions 1 through 15; the second extends from
17 through 63; the last extends from 65 through 132. The contents of
each field are left-justified within the
field.
Figure
2-2
illustrates the listing header format.
2-3

COMPILER OUTPUT
Print
1
Position

132

63 65

15 17
name

title

proc.essor identification

ident

subtitle

source identification

Figure 2-2:

Listing Header Format

The name and ident fields contain the same information as that
contained in the object file module headers. Some processors must
generate the first page header before this information is available.
Thus, t
include the information if it appears in the object module.
If the module name exceeds 15 characters, the title field begins eight
columns further to the right.
The title and subtitle fields contain user-supplied information; they
identify the purpose of the module and routine. User title and
subtitle entries that are too long are right-truncated at column 63.
If the language processor makes no provision for the user to supply
this information, the fields are ignored and the processor and source
identifications start in column 17.
If the language processor allows
only one set of title information, the subtitle field is used for
standard identification of the portion of the listing represented.
When the user updates the title or subtitle information in the first
line of the source page, the listing for that page will include the
updated information.
The processor identification field contains the date and time of
compilation
(in the form dy-mon-year hh:mm:ss) and the full product
name of the language processor.
This field includes the release
version number, with the edit number appended to it. The page listing
This number
number appears as the last entry in this field.
increments by one for each listing page produced from a concatenated
source file, that is, in the listing file.
The source identification field contains the data and time of creation
or last modification of the source file bei,,ng read at the start of
this page~
It also contains the resultant file name of this source
file.
It is a fully qualified name, including the actual version
number.
If the name is too
long,
the
leftmost
field
is
right;...truncated.
The source file page number appears last, in
parentheses, and is one greater than the number. of page marks
(form
feeds) read from the source.

2.2.2

Source Listing

The source part of the output listing reproduces the input to the
BLISS compilation with annotation supplied by the compiler. The
compiler annotation includes a 14-character preface string that
precedes each line of input and error message lines that follow each
line on which one or more errors are detected.

2-4

COMPILER OUTPUT
The 14-character preface string consists of a semicolon (;), followed
by either the editor line sequence number for a sequenced file or five
blanks for an unsequenced file, two 1-column codes, a 4-digit line
number generated _by the compiler, and two blanks.
Thus, the preface string has the following general form:
;xxxxxyznnnnbb
Table 2-1 describes preface string components.
Table 2-1:
Item

Format of Preface String in Source Listing

Column

Meaning

The comment character; used to comment out the
source line so that the output listing can be
assembled by the VAX-11 MACRO assembler.

xxxxx

2-6

The line number, if the file contains
line
sequence numbers; otherwise, five blank columns.

A code that indicates the lexical processing level
of the compiler.
The codes that can appear in
this column are described below:
Code
C

Meaning
Embedded

comment,

that

is,

text

within

%( ••• )%.

D
L
M
P
U

Default lexeme stream for a keyword macro
· formal.
Parameter list of a lexical function.
Body of a macro definition.
Parameter list of a macro call.
Source text which is discarded by
an
unsatisfied lexical condition.

If more than one such code applies
(for example,
an embedded comment nested within a macro body),
the "innermost" code is printed.

If the line comes from a
REQUIRE declaration, the
blank.

nnnn

9-12

The BLISS line sequence number, beginning with
0001 and is increased by 1 each time a source line
is read. This line number is referenced by error
messages and by the commentary field of the object
code listing.
It is always incremented for source
lines read from REQUIRE files, even though those
lines may not be listed.

13-14

Blank

2-5

file
code

specified in a
"R"; otherwise,

COMPILER OUTPUT
For example, consider the following line of the source input:
RESULT = l;
If the above expression were the fourteenth line of the
for example, the output listing for that line would be:
0014

compilation,

RESULT = l;

The line number 0014 is the line assigned by the BLISS compiler.
If
the input line had an editor sequence number 2300, the output listing
for that line would be::
;02300

0014

RESULT = l;

If the input line comes from
includes an R, as follows:

the

output

listing

If the input line is part of a macro declaration, the
includes an M, as follows:

output

listing

R0014

M 0004

REQUIRE

file,

RESULT = l;

The y item in the preface string (column 7) is useful for detecting
lexical errors.
For example, if you forget to terminate a macro
declaration, all the following lines in the program are then assumed
to be part of that macro declaration and the error is not detected
until the end of the program. However, you can find the beginning of
the. unterminated macro by finding the point at which the M code first
appears in the y field before the runaway.
An example of the source listing for the first $egment of
TESTFACT appears below:

• (header)
;00100 0001
module testfact (main = mainprog)
;00200 0002
begin
; WARN 048 1 Ll:0002
; Syntax error in module head
;00300 0003
;00400 0004
own
;00500 0005
a,
;00600 0006
b;
;00700 0007
;00800 0008
routine ifact (n) =
;00900 0009
begin
;01000 0010
local
;01100 0011
result;
;01200 0012
result
l;
;01300 0013
incr i from 2 to .n do
;01400 0014
result = .reult*.i;
; WARN 000 ••••••••••••••••••! Ll:0014
; Undeclared name: REULT
;01500 0015
.result
;01600 0016
end;

2-6

the

module

COMPILER OUTPUT
Following three heading line.s, the source of the module TESTFACT is
reproduced.
The preface string begins with a semicolon (;).
If the
input file that contains the module TESTFACT does not have sequence
numbers, columns 2 through 6 of the source listing are blank. Columns
7 and 8 are blank, because the lexical processing level is normal and
the material
is not from a REQUIRE file.
Line numbers generated by
the compiler begin in column 9.
Two error messages are reported as part of the source listing.
Section 2.4 contains a discussion of error messages in general and of
the meaning of these errors in particular.

2.2.3

Object Listing

The object part of the listing has four possible fields,
namely:
assembler
input, assembler output, binary, and commentary. The parts
of the object listing that are produced depend on the choice of
machine-code-list code-values specified
in the command line. Each
part of the object listing has associated with it a machine-code-list·
code-value that allows it to be eithe~ printed or suppressed.
However, although 32 different forms of listing are theoretically
possible,
in practice only a few combinations of code-values are
meaningful. The basic distinction among object listings is whether
the listing replicates assembler input or assembler output.
If the
ASSEMBLER code-value is given, the object part is formatted so that it
can be read by the assembler.
If the NOASSEMBLER code-value is given,
the object part is formatted to resemble assembler output.
The following combinations of the
reasonable:
ASSEMBLER {

NOASSEMBLER

SYMBOLIC

}

machine-code-list

COMMENTARY

{ BINARY

NOSYMBOLIC
SYMBOLIC

BINARY
{

are

} { UNIQUE NAMES

NOBINARY
COMMENTARY

code-values

}

NOUNIQUE_NAMES
}

NOUNIQUE_NAMES

NOBINARY

The commentary field
requires little space and provides useful
information
so that the programmer has no real need for the
NOCOMMENTARY qualifier.
The question of whether or not to have the binary appear on the
listing
is a question of personal preference. However, it may at
times be useful for debugging purposes.
If the binary field
is
omitted, the listing is likely to be more compressed, since additional
operands can then be placed on the same line.
The compiler produces the following information for each field.
ASSEMBLER field

Instructions in assembler form, for example:
MOVL

SYMBOLIC field

#1,RO

Instructions in assembler form,
symbolic source names, for example:
MOVL

U, RESULT

2-7

but

using

COMPILER OUTPUT
BINARY field

Hexadecimal equivalent of instructions and data
to enable easier debugging.
The hexadecimal
instructions appear in the same format as that
produced by the VAX-11 MACRO assembler as far as
possible. The rightmost numeric field
in the
binary listing is the location counter, relative
to the starting
routine's
address.
This
simplifies user interaction with VAX-11 DEBUG
when
setting
breakpoints
or
examining
instructions.
{Refer
to
Section 3.3,
"Debugging.")
The following codes are
included
in
the
hexadecimal
information in the binary field to
provide
information
about
relocation
of
quantities:
Meaning

Code
Blank

Absolute quantity {no linker action)

Forward relocatable.

Complex
Relocated (relative to a program section
other than the code program section)

G
COMMENTARY field

either general
addressing
(Position
Independent) or globally relocatable

A cross-reference to the source program line
If a program line
generating
the
code.
generates more than one
instruction
line,
commentary fields in the lines following the
first generated instruction remain blank.

Some examples of the object part of the routine segment !FACT follow.

2.2.3.1 Default Object Listing - The listing
produced by the following command line:

Figure

2-3

was

the

$BLISS/LIST MYPROG
In the listing, the binary field appears first,
symbolic field, followed by the commentary field.

2-8

followed

TESTFACT

31-0ct-1979 10:34:06
31-0Ct-1979 10:28:35

VAX-11 Blisa-32 T2-619
Page
DBBl:[DIRECTORY]MYPROG.BLI:S (1)

00100 0001
module testfact (main • mainprog)
00200 0002
begin
WARNI048
l Ll:0002
Syntax error in module head
00300 0003
00400 0004
own
00500 0005
a,
00600 0006
b:
00?00 0007
00800 0008
routine ifact (n) •
00900 0009
begin
01000 0010
local
01100 0011
result:
01200 0012
result • l:
01300 0013
incr i from 2 to .n do
01400 0014
result• .reult*.i:
WARNIOOO
•••••••••••••••••• 1 Ll:0014
Undeclared name: REULT
01500 0015
.result
01600 0016
end:

00000 A:
00004 B:

50
51
50
FS

OOOOG

CF
Sl

01
01
06
Sl
AC

0000 00000 IFACT:
DO 00002
DO 00005
11 00008
CS OOOOA 1$:
F3 00010 2$:
04 00015

: Routine Size:

22 bytes,

:01700
:01900

routine rfact (n) =
if .n gtr l then .n*rfact (.n - l) else l:

0017
0018

Routine Base:

01
7E

04
EF

.PSECT

$0WN$,NOEXE,2

.BLKB
.BLKB

4
4

.EXTRN

REULT

.PSECT

$CODE$,NOWRT,2

• l«)RD

MOVL

MOVL
BRB
MULL3
AOBLEQ
RET

TESTFACT

Save nothing
tl, RESULT
U, I

2$
I• REULT • RESULT
N, I, 1$

t"'
L'IJ

t-i

'O'

0008
0012
0013
0014
0013
0008

$CODE$ + 0000

AC
AP

i'O

.TITLE

AC
OE
01
01
AC

0000 00000 RFACT:
Dl 00002
lS 00006
CJ 00008
FB OOOOD
C4 00011
04 OOOlS

Figure 2-3:

• l«>RD

CMPL
BLEQ
SUBL3
CALLS
MULL2
RET

Save nothing
N, tl
1$
U, N, -(SP)
U, RFACT
N, RO

Default Object Listing Example

0017
0018

t-i

TESTFACT

31-0Ct-1979 10:34:06
31-0ct-1979 10:28:35

so
: Routine Size:
02000
02100
02200

0019
0020
0021

02300

0022

02400
02SOO

0023
0024

26 bytes,

Routine Base:

MOVL

Page

tl, RO

RET

0017

$CODE$ + 0016

routine mainprog : novalue a
begin
a • ifact (5):
b • rfact (5):
end:

CB
0000'

AF
CF

D3
0000'

AF
CF

OS
01
SO
OS
01
SO

.....
0

DO 00016 1$:
04 00019

VAX-11 Bliss-32 T2-619
DBBl:[DIRECTORY]MYPROG.BLI:S (1)

: Routine Size:

25 bytes,

Routine Base:

0000 00000 MAINPROG:
.l«>RD
DD 00002
PUSHL
FB 00004
CALLS
DO 00008
MOVL
PUSHL
DD OOOOD
CALLS
FB OOOOF
DO 00013
MOVL
04 00018
R.ET

Save nothing

tl, IFACT

0020
0022

RO, A

0023

tl, RFACT

n
0

..,3
....
t"'

tSJ

RO, B
0020

$CODE$ + 0030

toi

02SSO
02600
02800

002S
0026
0027

.c
toi

end
eludom

PSECT SUMMARY

$OWN$
$CODE$

Warnings:
Errors:

Attributes

Bytes

Name

, WRT,
,NOWRT,

RD ,NOEXE,NOSHR,
RD , EXE,NOSHR,

LCL,
LCL,

REL,
REL,

CON,NOPIC,ALIGN(2)
CON,NOPIC,ALIGN(2)

2
0

COMMAND QUALIFIERS
BLISS /LIST MYPROG

Figure 2-3 (Cont.):

Default Object Listing Example

()

TESTFACT

~
~

31-0ct-1979 10:34:06

VAX-11 Bliss-32 T2-619

Page

..,i
H

Size:
73 code + 8 data bytes
Run Time:
00:01.5
Elapsed Time: 00:03.0
Memory Used: 9 pages
Compilation Complete

t"'
ts.I

:xJ
0

..,c

Figure 2-3 (Cont.):

Default Object Listing Example

COMPILER OUTPUT
2.2.3.2 Assembler Input Listing - The listing
in Figure 2-4
was
produced by compiling module TESTFACT with the following code-options:
$ BLISS/LIST/MACHINE_CODE_LIST: (ASSEMBLER,NOBINARY) MYPROG
In the listing, the assembler field appears first,
followed by the
symbolic field,
followed by the commentary field.
Observe that when
both the assembler and symbolic fields are present, only the operands
are
given
in the symbolic field to conserve space.
Labels,
instruction names, and assembler directives are not repeated.

2.2.4

Source Part Options

The following sections contain more output listings to illustrate
different options for the source part of the list file.
To illustrate
these different forms, the sample program TESTFACT has to be made more
interesting, along the lines given in the following paragraphs.
Suppose the testing of the same program TESTFACT is complete, source
code errors contained in the preceding examples have been corrected,
and the data on the relative performance of the two factorial routines
obtained.
The next step is the production of a new module TEST that
uses the factorial routine to 'take combinations, according to the
following formula for obtaining the number of combinations of m things
taken n at a time:

l: l
where n!

n!
(m-n) ! m!

is the notation for the factorial of n.

First, enter the routine declarations for !FACT and RFACT into
separate REQUIRE files,
named IFACT and RFACT, respectively.
The
module TEST can then use either routine by including the appropriate
REQUIRE declaration.
Next, write
namely:

macro

(COMBN.R32)

for

obtaining

the

combinations,

MACRO
COMBINATIONS(N,M)
(IF N LSS M
THEN ERROR ( )
ELSE COMB(N,M)) %,
COMB(N,M) =
FACT(N)/(FACT(N-M)*FACT(M)) %;
Then, precompile the macro declaration into a LIBRARY file as
(include a LIBRARY declaration in the module TEST):

follows

$BLISS/LIBRARY COMBN
Finally, include some test combinations.
The following
sections illustrate the different output
obtained for that module by varying the command qualifiers.

2-12

listings

TESTFACT

31-0ct-1979 10:45:47
31-0ct-1979 10:28:35

VAX-11 Bliss-32 T2-619
DBBl:[DIRECTORY]MYPROG.BLI;S (1)

Page

;00100 0001
module testfact (main = mainprog)
;00200 0002
begin
; WARN#048
1 Ll:0002
: Syntax error in module head
;00300 0003
;00400 0004
own
;00500 0005
a,
;00600 0006
b;
;00700 0007
;00800 0008
routine ifact (n)
;00900 0009
begin
;01000 0010
local
;01100 0011
result;
;01200 0012
result = l;
;01300 0013
incr i from 2 to .n do
;01400 0014
result= .reult*.i;
: WARNlfOOO
••••.•• , •••••••••• 1 Ll :0014
; Undeclared name: REULT
;01500 0015
.result
;01600 0016
end;

(\.)

I
~

A:
B:

!FACT:

1$:
2$:

.TITLE

TESTFACT

.PSECT

$OWN$,NOEXE,2

.bKB
.bKB

n
~

t-t

t'"'

tzJ

"c:

4
4

.EXTRN

REULT

t-i
"O

.PSECT

$CODE$,NOWRT,2

t-i

.WORD
MOVL
MOVL
BRB
MULL3
AOBLEQ
RET

AM<>
#1, RO
#1, Rl
2$
Rl, WAREULT, RO
4(AP), Rl, 1$

Save nothing
#1, RESULT
#1, I
2$
I I REULT , RESULT
N, I, 1$

0014
0013
0008

$CODE$ + 0000

: Routine Size:

22 bytes,

;01700
;01900

0017
0018

routine rfact (n) =
if .n gtr 1 then .n*rfact (.n - 1) else l;

RFACT:

.WORD
CMPL
BLEQ
SUBL3
CALLS
MULL2
RET

AM<>
4(AP), U
1$
#1, 4(AP), -(SP)
u, BARFACT
4(AP), RO

Routine Base:

0008
0012
0013

;Save nothing
#1
;1$
;U, N, -(SP)
;#1, RFACT
;N, RO
;N,

Figure 2-4:

Assembler Input Listing Example

0017
0018

31-0ct-1979 10:4S:47
31-0ct-1979 10:28:3S

TESTFACT
1$:

MOVL
RET

:11, RO

U, RO

Routine Size:

26 bytes,

02000
02100
02200
02300
02400
02SOO

routine mainprog : novalue
begin
a= ifact (5):
b
rfact (S):
end:

0019
0020
0021
0022
0023
0024

VAX-11 Bliss-32 T2-619
DBBl:[DIRECTORY]MYPROG.BLI:S (1)

Routine Base:

Page

0017

$CODE$ + 0016

MAINPROG:
.~RD

PUSHL
CALLS
MOVL
PUSHL
CALLS
MOVL
RET

IV
I
fo-1

AM<>
ts
fl, BAIFACT
RO, W"'A
ts
n, sARFAcT
RO, W"B

0020
0022

Save nothing
IS
tl, IFACT
RO, A
ts
U, RFACT
RO, B

0023
0020

2S, bytes,

Routine Size:
02SSO
02600
02800

002S
0026
0027

Routine Base:

....
"'
tot
tsJ
~

$CODE$ + 0030

"'
c

end
eludom

PSECT SUMMARY
Name

Attributes

Bytes

$OWN$
$CODE$

Warnings:
Errors:

8
73

, WRT,
,NOWRT,

RD ,NOEXE,NOSHR,
RD , EXE,NOSHR,

LCL,
LCL,

REL,
REL,

CON,NOPIC,ALIGN(2)
CON,NOPIC,ALIGN(2)

o
COMMAND QUALIFIERS

BLISS /LI-ST/MACHINE_CODE_LIST:(ASSEMBLER,JIOBilllARY) MYPROG

Figure 2-4 (Cont.):

Assembler Input Listing Example

TESTFACT

"'I
~

(Ji

31-0ct-1979 10:45:47

VAX-11 Bliss-32 T2-619

ita

....

Size:
73 code + 8 data bytes
Run Time:
00 :01. 6
Elapsed Time: 00 :.04. 0
Memory Used: 10 pa9es
Compilation Complete

.END

Page

,,
t""

·ts,i

MAINPROG

;g
Figure 2-4 (Cont.):

Assembler Input Li-sting Example

t-i

COMPILER OUTPUT
2.2.4.1 Default Source Listing - The following command line generated
the output listing in Figure 2-5 for the module TEST:

$ BLISS/LIST/NOCODE TEST
Observe that, although the contents of the REQUIRE file are not
printed, the lines within the file are numbered by the compiler. The
output listing shows that lines 0011 through 0016 are used for this
purpose.

• (header)
0001
0002
0003
0004
0005
0006
0007
0008
0009
0010
0017
0018
0019
0020
0021
0022
0023
0024
0025

module test (main
begin

mainprog)

own

a,
b;
external routine
error;
library 'combn'
require 'rfact'
routine mainprog =
begin
a= combinations (3, 2);
b =combinations (6, 4);
end;
end
eludom

LIBRARY STATISTICS
-------- Symbols -------Total
Loaded
Percent

File
DBBl: [DIRECTORY]COMBN.L32;3

100

COMMAND QUALIFIERS
BLISS /LIST/NOCODE TEST
Run Time:
00:00.7
Elapsed Time: 00:03.6
Memory Used:
8 pages
Compilation Complete
Figure 2-5:

Default Source Listing Example

Blocks
Read
4

COMPILER OUTPUT
2.2.4.2
line:

Listing with LIBRARY and REQUIRE Information - The

command

$ BLISS/NOCODE/LIST/SOURCE_LIST: (LIBRARY,REQUIRE) TEST
generated the output listing in Figure 2-6, which contains information
from LIBRARY and REQUIRE files.
The LIBRARY file is identified
following line 0009 and the first use of a name from that library is
noted following line 0020. The contents of the REQUIRE file are given
in lines 0011 through 0016.

2.2.4.3

Listing with Macro Expansions - The command line:

$ BLISS/NOCODE/LIST/SOURCE_LIST:EXPAND_MACROS TEST
generated the output listing in Figure 2-7 to illustrate macro
expansions, which follow lines 0020 and 0021.
Observe that expansions
are listed in the order in which they occur. The innermost expansion
is printed first, followed by the outer expansion, which includes the
expanded form of the inner macro. Therefore, the last line of the
macro expansion is the fully expanded form.

2.2.4.4

Listing with Macro Tracing - The command line:

$ BLISS/NOCODE/LIST/SOURCE_LIST:TRACE_MACROS TEST
produced the output listing in Figure 2-8, which contains macro
tracing and macro expansion information.
The macro trace gives
information about parameter binding in addition to the expansion
information.

2.3

COMPILATION SUMMARY

The compilation summary appears at the end of
listing and consists of six kinds of information:

every

compilation

starting

psect-relative

address

•

The routine size
and
(following each routine)

•

A program section summary (at the end of the module)

•

Library usage statistics indicating the libraries used and the
number of names loaded from each library {omitted if no
libraries are used)

•

The command line used to compile the module

•

Number of warnings and
errors exist)

•

Summary of statistics for the module, consisting of: size of
code and data {in bytes), run time, elapsed time, memory used,
and a statement that the compilation is complete.

errors

(omitted

warnings

31-0ct-1979 15:32:08
31-0ct-1979 12:37:24

TEST

VAX-11 Bliss-32 T2-619
DBBl:(DIRECTORY]TEST.BLI:5 (1)

Page

0001 module test (main
mainprog)
0002 begin
0003
0004 own
0005
a,
0006
b:
0007 external routine
0008
error:
0009 library 'combn' :
,, Library file DBBl:[DIRECTORY]COMBN.L32;3 produced by VAX-11 Bliss-32 T2-619 on 31-0ct-1979 15:13:25
0010 require 'rfact' :
ROOll
R0012
R0013
R0014
R0015
R0016

routine fact (n) =
if .n gtr 1
then
.n*fact ( .n - 1)
else
1:

0017
0018 routine mainprog
0019
begin
0020
a= combinations (3, 2):
, , Loaded symbol COMBINATIONS from library DBBl:(DIRECTORY]COMBN.L32:3
: : Loaded symbol COMB from library DBBl:[DIRECTORY]COMBN.L32:3
0021
b =combinations (6, 4):
0022
end:

()

.,,3:
t-1

,,
c-e
tSl

I
I-'
00

0023
0024
0025

end
eludom

.,,c:
~
~

LIBRARY STATISTICS
-------- Symbols -------Total
Loaded
Percent

File
DBBl:(DIRECTORY]COMBN.L32;3

100

Blocks
Read
4

COMMAND QUALIFIERS
BLISS /NOCODE/LIST/SOURCE_LIST:(LIBRARY,REQUIRE) TEST
Run Time:
00:00.6
Elapsed Time: 00:02.5
Memory Used: 8 pages
Compilation Complete

Figure 2-6:

Output Listing Example Showing Library and Require File Information

TEST

31-0ct-1979 15:41:30
31-0ct-1979 12:37:24
0001
0002
0003
0004
0005
0006
0007
0008
0009
0010

VAX-11 Bliss-32 T2-619
DBBl:[DIRECTORY]TEST.bI:S (1)

Page

module test (main • mainprog)
begin
own
··· a,
b:
external routine
error:
library 'combn'
require 'rfact'

0017
0018 routine mainprog
begin
0019
0020
a= combinations (3, 2):
[COMB]= FACT ( 3 ) / ( FACT ( 3 - 2
[COMBINATIONS]= ( IF 3 LSS 2 THEN ERROR
b
combinations (6, 4):
0021
[COMB]= FACT ( 6 ) / ( FACT ( 6 - 4
[COMBINATIONS]= ( IF 6 LSS 4 THEN ERROR
0022
end:

:
:
:

I
1--'

0023
0024
0025

) * FACT ( 2 ) )
( ) ELSE FACT ( 3 ) / ( FACT ( 3 - 2 )

* FACT ( 2

) * FACT ( 4 ) )
( ) ELSE FACT ( 6 ) /

* FACT ( 4 )

( FACT ( 6 - 4 )

i"O

....
t1

end
eludom

tsJ

\.0

c:
~

LIBRARY STATISTICS
File
DBBl:[DIRECTORY]COMBN.L32:3

-------- Symbols -------Total
Loaded
Percent

Blocks
Read

100

COMMAND QUALIFIERS
BLISS /NOCODE/LIST/SOURCE_LIST:EXPAND_MACROS TEST
Run Time:
00:00.6
Elapsed Time: 00:03.l
Memory Used: 8 pages
Compilation Complete

Figure 2-7:

Output Listing Example Showing Macro Expansion Information

31-0ct-1979 15:59:16
31-0ct-1979 12:37:24

TEST

I
N
0

0001 module test (main = mainprog)
0002 begin
0003
0004 own
0005
a,
0006
b:
0007 external routine
0008
error:
0009 library 'combn' :
0010 require 'rfact' :
0017
0018 routine mainprog =
0019
begin
0020
a= combinations (3, 2):
[COMBINATIONS]: Parameter binding
[COMBINATIONS](l)= 3
[COMBINATIONS](2)= 2
[COMBINATIONS]: Expansion
[COMB]: Parameter binding
[COMBJ(l)= 3
[COMB](2)= 2
[COMB]: Expansion
[COMB]= FACT ( 3 ) f ( FACT ( 3 - 2
[COMBINATIONS]= ( IF 3 LSS 2 THEN ER]:lOR
0021
b = combinations (6, 4):
[COMBINATIONS]: Parameter binding
[COMBINATIONS](l)= 6
[COMBINATIONS](2)= 4
[COMBINATIONS]: Expansion
[COMB]: Parameter binding
[COMB](l)= 6
[COMBJ(2)= 4
[COMB]: Expansion
[COMB]= FACT ( 6 ) f ( FACT ( 6 - 4
[COMBINATIONS]= ( IF 6 LSS 4 THEN ERROR
0022
end:
0023
0024 end
0025 eludom

) * FACT ( 2 ) )
( ) ELSE FACT ( 3 )

VAX-11 Bliss-32 T2-619
DBBl:[DIRECTORY]TEST.BLI:5 (1)

Page

f ( FACT ( 3 - 2 ) * FACT ( 2 ) ) )

,,
t""

) * FACT ( 4 ) )
( ) ELSE FACT ( 6 )

'ti

c:·

f ( FACT ( 6 - 4 ) * FACT ( 4 ) ) )

-------- Symbols -------Total
Loaded
Percent

DBBl:[DIRECTORY]COMBN.L32:3

100

Blocks
Read
4

Run Time:
00:00.7
Elapsed Time: 00:01.8
Memory Used: 8 pages

Compilation Complete

Figure 2-8:

'ti
....

LIBRARY STATISTICS
File

0
0

Output Listing Example Showing Macro Expansion and Tracing Information

COMPILER OUTPUT
2.4

ERROR MESSAGES

The BLISS compiler detects two types of errors, namely:
fatal and
warning. A fatal error is one that the compiler cannot handle without
potentially skipping some source. A warning error is one for which
the compiler has an effective recovery technique that permits it to
generate an executable object module. Both the warning and the fatal
errors messages are listed separately in Appendix E. The warnings are
listed by number, and each warning includes an explanation of the
error and a recommended user action.
If a fatal error is detected, the compiler continues to check syntax
of the remainder of the program;
any subsequent errors can be
detected, but neither an object module nor the object part of the
output listing is produced following the detection of the fatal error.
A warning error message begins with the identification WARN.
For
example, the routine declaration for IFACT includes a coding mistake,
as follows:
RESULT = .REULT*.I;
The BLISS compiler
warning message:

detects

this

error

and

reports

the

following

0014
RESULT = .REULT*.I;
WARN #000
•••••••••• 1 Ll:0014
Undeclared name: REULT
The message is not fatal, because the compiler can declare the
undeclared name REULT as EXTERNAL and continue processing without
omitting the compilation of any source.
Consider a different kind of coding error, as follows:
!NCR I FROM 2 TO .NDO
RESULT = .REULT*.I;
The BLISS compiler detects this error and reports the
in the following segment from the output listing:

messages

given

0013
!NCR I FROM 2 TO .NDO
WARN #000
•••••••••••••••••l
Ll:0013
Undeclared name: NDO
0014
RESULT = .REULT*.I;
ERR #066 •••••••••••••! Ll:0014 L2:0014 L3:0014
Two consecutive operands with no intervening operator
Omitting the blank between the name N and the keyword DO caused one
warning and one fatal error. Because in the absence of a separator
the compiler sees NDO as a single name, it first identifies it as an
undefined name.
When it fails to find the keyword DO, the compiler
cannot make syntactic sense out of the lines;
therefore, it must
report a fatal error message and suppress the production of any object
output.
Observe that although the compiler continues to check the syntax of
the remainder of the module, it misses the error REULT, because some
text must be left unscanned to recover from the fatal error.
The
recovery process sometimes causes genuine errors to be missed and
spurious errors to be reported. A module cannot be assumed to be
fully checked by the compiler until all error messages are eliminated.

2-21

COMPILER OUTPUT
THE BLISS compiler supplies a great deal of information in its error
messages.
Each error message occupies two lines. The first line
classifies and pinpoints the error and the second line gives a short
description of the error. For example, consider the following error
message from the above example:
0013
INCR I FROM 2 TO .NDO
WARN #000
•••••••••••••••••l Ll:0013
Undeclared name: NDO
The first line classifies the error as a nonfatal by the string WARN
and gives the error number 000 followed by a pointer to the place in
the input line at which the error was detected and a line indicator.
The second line describes the error.
The first line of an error message lines up with the input column at
which the compiler detected the error. Under the preface for the
input line, the error message has a preface part that gives the type
of error
(warning or fatal)
and the error number.
(Refer to
Appendix E.) Under the text part of the input line, the error message
can have up to three pointers and three line indicators. The pointers
are numbered from 1 to 3 and the meaning associated with each of the
pointers is given in the following list:
Pointer

Meaning

Indicates the point in the input text
the error was detected.

Indicates the beginning of the
scope.

Indicates the end of the last control scope that
was successfully closed prior to the detection
of the error.

current

which
control

The line indicators are closely related to the pointers in meaning,
but whereas the pointers indicate a position within a line, the line
indicators indicate a line within the program, as follows:
Line Indicator

Meaning

Ll:nnnn

Indicates the line nnnn in the
the error was detected.

L2:nnnn

Indicates the line nnnn
control scope begins.

L3:nnnn

Indicates the line nnnn at which the
control scope was successfully closed.

input

which

the

which
current
last

Line indicators are usually not too informative when the error is
confined within a program line, as in the examples given above, but
they are very useful for errors that span several lines. For example,
consider the full source listing for the module TESTFACT given in
Figure 2-9. This version of TESTFACT includes the coding error
illustrated in the ccove examples. The error message at the end of
the program identifies with line indicators the point at which tHe
errorwas detected
(line 0032), the line at which the control scope
began (line 0013), and the line at which the control scope was closed
(line 0032).
With the information provided by the line indicators for error message
#012,
the source of the error is identified as the typing error in
line 0013.
2-22

COMPILER OUTPUT

• (header)
0001
MODULE TESTFACT (MAIN = MAINPROG)
0002
BEGIN
WARN#048
1 Ll:0002
Syntax error in module head
0003
0004
OWN
0005
A,
0006
B;
0007
0008
ROUTINE !FACT (N) =
0009
BEGIN
0010
LOCAL
0011
RESULT;
0012
RESULT = l;
0013
!NCR I FROM 2 TO .NDO
WARN#OOO
•••••••••••••••••••••l Ll:0013
Undeclared name: NDO
0014
RESULT = .REULT*.I;
ERR #066
••••••••• 1 Ll:0014 L2:0014 L3:0014
Two consecutive operands with no intervening operator
0015
.RESULT
0016
END;
0017
0018
ROUTINE RFACT (N} =
0019
IF .N GTR 1
0020
THEN
0021
.N*RFACT (.N - 1)
0022
ELSE
0023
l;
0024
0025
ROUTINE MAINPROG =
0026
BEGIN
0027
A= !FACT (5);
0028
B = RFACT (5);
0029
END;
0030
0031
END
0032
ELUDOM
ERR #012
1 ••• 2 Ll:0032 L2:0013 L3:0032
Missing DO following !NCR or DECR
Warnings:
2
Errors:
2
Size:
0 code + 8 data bytes
Run Time:
00:02
; Elapsed Time:
00:03
Memory Used:
3K
Compilation Complete

Figure 2-9:

Error Messages in Source Listing Example

2-23

CHAPTER 3
LINKING, EXECUTING, AND DEBUGGING

This chapter describes the
debugging a BLISS program.

3.1

process

linking,

executing,

and

LINKING

Before you can execute your program, you must link the various pieces
together to form an executable image. The linking process makes the
connection between external variables referenced in one module and
global variables defined in another module.
Some examples of linking are:
•

To link a single module, use the following command:

$ LINK ALPHA
In response to this command,
module
in
ALPHA.OBJ
and
ALPHA.EXE.
•

the linker reads the object
creates the executable image

To link the modules ALPHA, BETA, and GAMMA, use the
command:

following

$ LINK ALPHA,BETA,GAMMA
In response to this command, the linker combines the object
module in the file ALPHA.OBJ with the object module in the
file BETA.OBJ and the object module in the file GAMMA.OBJ to
produce a single executable image ALPHA.EXE, which can then be
executed.
The link operation
Reference Manual.

3.1.1

described

detail

the

VAX-11

Linker

LINK Command Syntax

Syntax of the LINK command is defined as follows:
{/DEBUG }
nothing

link-command

LINK

object-file

file-spec

3-1

space

object-file

' ...

LINKING, EXECUTING, AND DEBUGGING
3.1.2

LINK Command Semantics

The linker reads the object modules contained in each file named
in
the link command to create a linked, executable image. The name of
the eX'ecutable image is taken from the name of the first object-file,
and the file type EXE is used.
If no file type is included in the
file-spec, file type OBJ is assumed.
If the /DEBUG qualifier
is used
in the link-command,
Debugger is linked with the specified object-files.

the

VAX-11

The linker has many qualifiers, but only the /DEBUG qualifier
is
discussed here.
Other qualifiers are described in the VAX-11 Linker
Reference Manual.
Appearance of the following error message during the link operation:
%LINKER-W-TRUNC, Trunc. error in module <name>, P-section
<name>, offset %X <address>
generally implies that the program is larger
the module qualifier:

than

32KB.

Specifying

ADDRESSING_MODE(EXTERNAL=LONG_RELATIVE, NONEXTERNAL=LONG_RELATIVE)
causes the compiler
instruction operands.

3.2

generate

long

displacement

values

for

EXECUTING A LINKED PROGRAM

To run your program, use the executable image produced as a result
the link operation, as follows:

$ RUN ALPHA
Your program, ALPHA, then executes.
Any input or output in your
program
takes place, and control then returns to the command
processor. The command processor then prompts for another command.

3.3

DEBUGGING

The VAX-11 Symbolic Debugger can be used to debug or test BLISS
programs.
The following discussion of BLISS debugging assumes that
you are familiar with the use of the debugger for VAX-11 MACRO
programs,
as described
in the VAX-11 Symbolic Debu~ger Reference
Manual.
This section describes BLISS debugging facil1t1es pr1mar1ly
in terms of differences from MACRO-level debugger usage.
The debugger recognizes BLISS as one of its "known" languages
(as it
does MACRO and FORTRAN,
for example),
and provides a number of
features specifically designed for more convenient debugging of BLISS
programs. These BLISS-specific features are:
•

Debug expression syntax that is consistent with BLISS language
syntax:
radix
control
operators,
arithmeticand
address-expression operators, field selectors, and so on.

3-2

LINKING, EXECUTING, AND DEBUGGING
•

Support of fetch operator in arithmetic expressions.

•

Expression evaluation according to BLISS
precedence and use of parentheses.

•

BLISS-style references to elements and components of standard
(predeclared)
data structures: VECTOR, BLOCK, BLOCKVECTOR,
and BITVECTOR; and support of REF data segments.

•

Support of field-names in structure references.

•

Support of BLISS field-references, as in:

rules

for

operator

EXAMINE X<lS,3,0>.

In combination, the features just described provide a high-level,
BLISS-like facility for examining and modifying program data segments,
both scalar and structured.
Many of the procedural aspects of BLISS debugging, however, such as
setting breakpoints and program stepping, must necessarily be handled
at object-code level, that is, with reference to the assembly listing,
as in MACRO-level debugging.
This is a consequence of two related
characteristics of BLISS:
It is not a statement language
(as is
FORTRAN, for example), and symbolic names for procedure addresses do
not exist in BLISS below the routine level.
In general, the same
procedure-related debugging facilities are provided for BLISS usage as
for MACRO usage, and these facilities are exercised in very much the
same way.

3.3.1

Initialized Modes and Types

When you initiate a debugging session for
debugger provides the information message:

BLISS

program,

the

%DEBUG-I-INITIAL, language is BLISS, module set to 'ABC'
where ABC represents your main module name.
entry/display modes are set to:

For

BLISS,

the

initial

SYMBOLIC, HEXADECIMAL
These mode settings can be changed with the SET MODE command, and can
be restored to the initial settings with the CANCEL MODE or SET
LANGUAGE BLISS commands. The initialized modes are the same as for
MACRO.
The initial setting for default type is:
LONG INTEGER
(Refer to the SET TYPE command.)
The initial scope is PC scope.

3-3

LINKING, EXECUTING, AND DEBUGGING
3.3.2

Debug Commands and Expression Syntax

Debugger commands are used for BLISS debugging exactly as they are for
MACRO programs except for the syntax within expressions. The debugger
expression syntax is extended to allow use of a wide range of
BLISS-style expressions,
including most BLISS arithmetic and Boolean
operators and the fetch operator, ordinary-structure-references
(for
predeclared structures), and BLISS field-references for specification
of bit fields.
(Debug commands are summarized at the end of this
chapter for convenient reference.)
Experienced VAX-11 Symbolic Debugger users should note in particular
that,
in expressions, the BLISS dot symbol (.) is recognized instead
of the "@" character as the debugger "contents" or indirect operator,
and that the previous location symbol (A) is not recognized in BLISS
mode.
The next two subsections describe special characters and keywords
recognized by the debugger as operators and address symbols (or
"address representation characters") in BLISS mode debugging.
In some
cases the characters are different from those recognized in MACRO mode
with the same meaning, and in other cases the characters or keywords
are additional to those recognized in MACRO mode.
(The differences
are noted.) In all cases the operator usage is BLISS-like in that the
meanings assigned to special characters and symbols in debug commands
are consistent with BLISS operator semantics.
Note that the significance of special characters as delimiters in
debug commands is the same for both BLISS and MACRO debugging. Also
in order to maintain a reasonable correspondence with the VAX-11
Symbolic
Debugger
Reference . Manual,
the
informal categories
"arithmetic expression" and "address expression" are used below (on a
best-fit basis)
rather than the more formal BLISS language-syntax
categories.

3.3.3

Operators in Arithmetic Expressions

Table 3-1 lists special characters and keyword symbols used in
arithmetic expressions. The semantics, priority, and relationship of
the operators listed in the Table are as defined in BLISS.
That is,
the debugger evaluates expressions according to the language context.
In particular, the intermediate and final
results of an expression
evaluation are calculated as longword (32-bit) values.
Restrictions:
The following
restrictions,
relative to full
expression syntax, apply to expressions in debug commands:
function

calls

invalid

part

Routine or
expression.

•

The assignment operator {=) is invalid within an expression.
(The equal-sign character may be used only as a separator in
DEPOSIT and DEFINE commands.)

•

The BLISS relational operators (for example,
are not supported.

•

BLISS executable functions are not supported.

•

Control expressions are not supported.

•

Declarations are not supported.

EQL,

•

3-4

are

BLISS

NEQ,

LSS)

LINKING, EXECUTING, AND DEBUGGING
Table 3-1:

Arithmetic Expression Operators

Character

Interpretation
Fetch (pref ix) operator
Arithmetic addition
plus sign

(infix)

operator

(prefix)

Arithmetic subtraction (infix) operator, or (prefix)
minus sign

Arithmetic multiplication operator

Arithmetic division operator
Arithmetic shift operator (unlike MACRO syntax)

MOD

Arithmetic modulus operator

NOT

Boolean negation operator

AND

Boolean 'and' operator

Boolean 'inclusive or' operator

XOR

Boolean 'exclusive or' operator

EQV

Boolean equivalence operator

(

... )

Precedence operators;
MACRO syntax)

do (enclosed)

first

(unlike

%DECIMAL

Decimal radix operator (either %DEC or %DECIMAL)

%0 'string'

Octal radix operator

%X 'string'

Hexadecimal radix operator

%E 'string'

Single-precision floating-point operator

3.3.4

Special Characters in Address Expressions

Table 3-2 lists special characters that can be used to represent
locations in a debugger expression.
(Later subsections describe
BLISS-style syntax extensions for structure references and field
references.)

3-5

LINKING, EXE.CUTING, AND DEBUGGING
Table 3-2:
Character

Address Representation Characters
Interpretation

When used alone or immediately before a delimiter,
represents the last location addressed by an EXAMINE,
DEPOSIT, SET BREAK, SET TRACE, or SET WATCH command.
This is called the current location.

Represents the last value displayed by EXAMINE or
EVALUATE.
(The backslash is also used in forming
pathnames, as in MACRO syntax.)
"Contents of" or indirect operator, when
prefix operator (unlike MACRO syntax)•
Range operator (low
EXAMINE command.

address:high

used

address)

for

a
the

3.3.4.1 Current Location Symbol (.) - Used either by itself or as an
operand in an expression, the dot represents the location most
recently referred to in an EXAMINE, DEPOSIT, SET BREAK, SET TRACE, or
SET WATCH command.
The value represented by the current location
symbol remains unchanged until one of the above mentioned commands is
used to refer to another location.
The dot symbol is assigned different meanings depending upon the
context
in
which it occurs.
In addition to its meaning as
current-location symbol, it is the debugger "contents" or indirect
operator
(as described below)
and, analogously, the BLISS fetch
operator in expressions. Thus, the sequence " •• " itself constitutes a
valid expression, meaning "contents of the current location." As a
simple example, suppose that, at a given step in the execution of a
program, the data-segment PTR contains the address of a longword
vector named INBUF, and that the location last referred to by a
debugger command is PTR. At this point the command:
EXAMINE •

I Examine current location I

will display the address of INBUF (that is, the contents
PTR), and the command:
EXAMINE

location

I Examine current location indirect I

will display the contents of location INBUF. Subsequently (since the
last command altered the current-location value to location INBUF),
the command:
EXAMINE .+4

/ Examine current location plus 4 I

will display the contents of location INBUF+4.
In contrast, note
particularly that the expression .(+4} would be interpreted (as in
BLISS)
as
"contents
of
location
00004"
rather
than
as
"current-location value plus four bytes."
The previous-location symbol, A' recognized in MACRO debugging,
is
invalid when 'language is BLISS'. The address expression .-1 or .-4
can be used, for example, to represent the location of the "previous"
byte or longword, respectively.

3-6

LINKING, EXECUTING, AND DEBUGGING
3.3.4.2 Last Value Displayed Symbol (\) - The backslash character (\)
can be used to represent the value most recently displayed. The value
remains unchanged until the debugger displays a new value.
For example (again assuming the data segments PTR and INBUF previously
described):
DBG>EXAMINE/DEC PTR
LISTER\LSTR\PTR:
1024
DBG>EXAMINE/ASCII \
LISTER\INBUF<0,32>: ABCD
The first EXAMINE command displays the contents of location PTR as the
value 1024.
The display shows the scope of the symbol PTR to be
module LISTER and routine LSTR. The second EXAMINE command displays
the contents of location 1024, that is, at the last value displayed.
The display shows the location symbolized as INBUF with scope LISTER,
and shows the contents of INBUF<0,32> to be "ABCD", interpreted as an
ASCII string.

3.3.4.3 Contents Operator (.) - The 'dot' character (.)
used as an
operator is the debugger "contents of" or indirect operator. It
requests that the debugger evaluate the expression following
it and
then use the contents of the location addressed by the expression
value rather than use the expression value itself.
(The contents
operator in MACRO debugging mode is the 'at' sign, @.)
Examples of the use of the dot as both the current-location symbol and
the contents operator, depending on its context, are given in the two
preceding subsections.
A further example, based on
the
same
assumptions, is:
DBG>EXAMINE/ASCII .PTR
LISTER\INBUF: ABCD
Observe that this one EXAMINE command is equivalent to the sequence
EXAMINE PTR followed by either EXAMINE\ or EXAMINE •• {in terms of
the final location displayed) •.
Other examples, modified from those given in Chapter 4 of
Symbolic Debugger Reference Manual, follow. The command
DBG>DEPOSIT MASK

the

VAX-11

= .MASKA4

shifts the current contents of the location MASK four bit positions to
the left.
The command
DBG>EXAMINE .R7 : .R7+%DEC'20'
displays the current contents of the 21
location addressed by general register 7.

bytes

beginning

with

the

3.3.4.4 Range Operator (:) - A colon is used to separate elements in
an address range in an EXAMINE command (see the previous example) ,
just as in MACRO debugging.
Unlike MACRO usage, however, the colon is not used in the EVALUATE
command to express a bit-field specification.
(In BLISS usage, the
standard BLISS field-selector notation is used instead, as described
in Section 3.3.5.)
3-7

LINKING, EXECUTING, AND DEBUGGING
Several examples of range-operator usage, modified from those given in
Chapter 4 of the VAX-11 Symbolic Debugger Reference Manual, follow:
DBG>EXAMINE/ASCII:l INBUF : INBUF+6
DBG>EXAMINE • : • + %DEC'200'
DBG>EXAMINE/INSTRUCTION .PC : .PC+lO
In the first command example, the address expression INBUF is
interpreted as a nonstructured data reference, since no access actuals
are specified, although INBUF is assumed to name a structured {vector)
data segment for the purposes of this discussion.
This command simply
displays the contents of the sequence of locations requested
in
storage units determined by the current length type, without reference
to declared structure.
In this case, since the specified type
is
ASCII:l,
the first seven bytes beginning at location INBUF are
displayed as follows:
LISTER\INBUF<0,8>:
A
LISTER\INBUF+l<0,8>:
B

LISTER\INBUF+6<0,8>:

If the type were ASCII:4, the first two longwords beginning
would be displayed, as follows:

INBUF

LISTER\INBUF<0,32>: ABCD
LISTER\INBUF+4<0,32>:
EFGH
The use of structure references in EXAMINE commands and the format
structured displays are described in Section 3.3.6.

3.3.4.5 Default Next-Location Value - The default next-location value
is the address implied by the "shorthand" form of the EXAMINE command,
that is,
the EXAMINE verb
{and possibly a type specification)
immediately followed by a carriage return.
The next-location value is
always the address of the byte following the last byte of the previous
display item.
Continuing with the previous example involving INBUF, if subsequent to
the command
DBG>EXAMINE/ASCII:l

INBUF : INBUF+6

and its resultant display, the "shorthand" command
DBG>EXAMINE/ASCII:l
is given, the display
LISTER\INBUF+7:

would be produced, or the display
LISTER\INBUF+8:

if type ASCII:2 was specified, or
LISTER\INBUF+OA:

KLMN

if type ASCII:4 was specified.

3-8

LINKING, EXECUTING, AND DEBUGGING
3.3.5

Field References

A BLISS field reference, that is, an expression followed by a field
selector, is used to specify a field of storage in EXAMINE, EVALUATE,
and DEPOSIT commands. The form of a field reference (as in BLISS) is:
address<position,size,ext>
where ext is O for unsigned extension and 1 for signed extension;

address<position,size>
where unsigned extension is assumed by default. The position and size
values are interpreted as decimal integers, regardless of current
radix mode, unless a radix operator is used (for example, %X'F'). The
size value may not exceed 32 in any case.
In the EXAMINE command, a field-selector has the same meaning as in
the BLISS fetch context, since indirection (that is, contents of) is
implied. That is, the EXAMINE command displays the contents of the
field of storage specified by position and size, relative to the
address given.
(The field value is first extended to a longword, with
signed or unsigned extension as requested). There is no syntactic
restriction on the range of the position value except that it must be
a positive integer. As an example,
DBG>EXAMINE/ASCII INBUF+8
LISTER\INBUF+S<0,32>:
IJKL
DBG>EXAMINE/ASCII:l INBUF<72,8>
LISTER\INBUF+9<0,8>: J
Note that the address expression INBUF+8 is equivalent
reference INBUF<64,32>.

the

field

In an EVALUATE command, the meaning of a field selector depends upon
whether or not a contents operator is specified, that is, whether or
not indirection is requested.
If the contents operator is specified,
a field selector has the same meaning (and lack of restriction on
position) as in the BLISS fetch context. For example:
DBG>EVALUATE/DEC .INBUF<72,8>
74
Observe that the effect of this field reference
(with the contents
operator specified)
is the same as that produced by an equivalent
EXAMINE command: the decimal value 74 is the ASCII code for the
character "J".
If indirection is not specified in an EVALUATE command, a field
selector has the same meaning and restrictions as in the BLISS
nonfetch, nonassignment content; that is, the expression
addr<p,s>
simply calculates the value addr+(p/8), where p must be a multiple of
8 and s
is ignored. The effect of a field selector in this case is
simply that of an address pffset, with the position value
(p)
interpreted as p/8. For example, assuming (as above) that the symbol
INBUF has the value 1024:
DBG>EVALUATE/DEC
1024

INBUF<80,8>

3-9

LINKING, EXECUTING, AND DEB,UGGING

Observe that the field reference INBUF<80,8> in the "nonfetch" context
is equivalent to the expression INBUF+lO (as also is INBUF<B0,16> or
INBUF<B0,23> or INBUF<B0,32>, for example).
In the DEPOSIT command, a field selector in the address expression on
the left side of the equal sign has the same meaning and effect as in
the BLISS assignment context.
That is, it specifies a field of
storage, relative to the given address, into which a value is to be
stored. The stored value is truncated if necessary to fit the
receiving field.
If a field selector appears in a "data"
(righthand)
operand of a
DEPOSIT command, it has the same meaning and effect as described above
for the EVALUATE command, depending upon whether or not a contents
operator is specified.

3.3.6

Structure References

A BLISS-style structure reference may be used as
a
debugger
address-expression if the data-segment referred to has a standard
BLISS predeclared structure, that is, either VECTOR, BITVECTOR, BLOCK,
or BLOCKVECTOR.
The debugger recognizes the following forms of
structure reference:
•

For VECTOR-structured segments segname[actual_l]

•

For BITVECTOR-structured segments segname[actual_l]

•

or segname[field-name]

For BLOCK-structured segments segname[actual l,actual 2,actual_3,actual_4]
segname[field-name]

•

For BLOCKVECTOR-structured segments segname[actual l,actual 2,---,actual 5]
segname[actual-1,field-name]
-

where
segname
is
a
name
declared
with
the
appropriate
structure-attribute or appropriate REF structure-attribute.
actual i is an expression evaluated as a
representing
a
valid access-actual for
structure.

decimal integer
the given data

field-name is a name
(declared in a source-program FIELD
declaration)
that represents a valid field-definition for the
given data structure.
Note that access-actual values are interpreted in decimal unless
radix operator is used, regardless of the current radix mode.

3-10

LINKING, EXECUTING, AND DEBUGGING
The following EXAMINE commands provide a simple example
references and structured display format:

structure

DBG>EXAMINE/ASCII
INBUF[l]
LISTER\INBUF[ll:
EFGH
DBG>EXAMINE/ASCII:l6 INBUF[O]
LISTER\INBUF[O]:
ABCDEFGHIJKLMNOP
DBG>EXAMINE/ASCII INBUF[O]:INBUF[3]
LISTER\INBUF[O]:
ABCD
LISTER\INBUF[l]:
EFGH
LISTER\INBUF[2]:
IJKL
LISTER\INBUF[3]:
MNOP
DBG>EXAMINE INBUF[l]:INBUF[2]
LISTER\INBUF[l]:
48474645
LISTER\INBUF[2]:
4C4B4A49
DBG>EXAMINE
LISTER\INBUF+OC<0,32>:
504F4E4D
In response to a structure reference,
the debugger
ignores default
type and displays data in accordance with the allocation-unit declared
for the structure. For example, if you specify a range of data within
a
BLOCKVECTOR
segment
in
an
EXAMINE command,
in terms of
colon-separated structure references, and the segment is declared with
allocation-unit WORD, the debugger responds as follows:
1.

Displays the content of the component specified by the
structure reference.

first

Skips any remaining bits (up to seven)
not end on a byte boundary.

does

Displays any remaining data within the range in 2-byte units
beginning with the next location, and ending with the last
location occupied by any part of the component specified in
the second structure reference (plus an additional byte if
required to round up to a word-size display unit).

if the component

An appropriately defined field-name can be used in place of explicit
access-actual values as shown in the structure-reference formats given
above.
No symbolic expression other than a field-name is valid in a
debugger structure reference.
In an EVALUATE command that specifies indirection, a structure
reference results in an evaluation of the content of the requested
element or component, in current radix mode. The display differs as
usual
from EXAMINE in that the location of the evaluated item is not
reported, and context type is ignored.
For example:
DBG>EVALUATE
4C4B4A49

.INBUF[2]

In an EVALUATE command without indirection
(no contents operator
specified), a structure reference results in an evaluation of the
address corresponding to the requested element or component. That is,
the address of the byte in which the data item begins.
(In the case
of a BLOCK or BLOCKVECTOR structure, the access actuals representing
size and extension are ignored.)
For a simple example, assume (as
above) that the symbol INBUF names a longword vector segment at
decimal location 1024:
DBG>EVALUATE
1024
DBG>EVALUATE
1036

INBUF
INBUF[3]

3-11

LINKING, EXECUTING, AND DEBUGGING
(This example assumes the current radix mode to be DECIMAL.)
For a somewhat more complex example, assume a block-structured segment
named BLK2 begins at location 648
(decimal)
and is allocated in
longwords.
Further, assume a set of declared field names Fl, F2,
F3,
and F4. Also, for simplicity assume DECIMAL radix mode:
DBG>EVALUATE BLK2
648
DBG>EVALUATE F4
2, 4, 12, 0
DBG>EVALUATE BLK2[F4]
656
This example illustrates two facts:
•

That the EVALUATE command evaluates a field name by reporting
the
access-actual
values
defined
for
that
name.
(Access-actual values, like field-selector parameters, are
always displayed in decimal regardless of current radix
mode.) The last-value-displayed (represented by \)
following
this type of command is the last access-actual shown in the
list:
in this case, the value O.

•

That evaluation of the structure-reference BLK2[2,4,12,0]
results in the address value BLK2+8, since the component
identified by the reference begins in the first byte of the
third longword in segment BLK2.
(More specifically, field F2
is defined as the 12 bits beginning with bit 4 of the third
allocation
unit.)
As stated previously, the size and
extension values are not involved in the evaluation.

In the DEPOSIT command, a structure reference used as the address
expression on the left side of the equal sign has the same meaning and
effect as in the BLISS assignment context. That is, it specifies an
element or component of a data structure into which a value is to be
stored. The stored value is truncated if necessary to fit the
receiving element or component.
If a structure reference appears in a "data" (righthand) operand of a
DEPOSIT command,
it has the same meaning as described above for the
EVALUATE command, depending on whether or not a contents operator
is
specified.
That
is, with indirection specified the structure
reference results in a fetch of the element or component indicated,
with or without sign extension as requested. Without indirection, a
structure reference results in the same kind of address evaluation as
is performed by the EVALUATE command.

3.3.7

REF Structure References

The debugger recognizes and treats REF data-segments in a manner
consistent with the BLISS language.
(A REF data-segment is a longword
segment declared with the attribute "REF structure-name".) When a REF
segment
name
is used in a structure reference, the debugger
automatically supplies an extra level of indirection, treating the
name as the location of a pointer to a segment that has the same
structure as that declared for the REF segment.
As in BLISS, when a REF segment name is given in a debugger command
without access actuals, the extra level of indirection is not
provided.
In this case, the name is interpreted as an ordinary
address reference.

3-12

LINKING, EXECUTING, AND DEBUGGING
Note that the debugger recognizes and supports REF segments as just
described only if they are declared with one of the predefined
structure-names, that is, VECTOR, BITVECTOR, BLOCK, or BLOCKVECTOR.
(User-defined structures are not supported as such by the debugger.)

3.3.8

Scope of Names

Whereas BLISS determines the scope of a data-segment name on a block
basis, the debugger's smallest unit of scope is the routine. This
causes no problems if a given name is declared only once within a
routine.
Ambiguities can arise, however,
if a name declared at a
given level (for example, at the outer routine level)
is redeclared
one or more times in contained blocks.
This includes the obscure case of redeclaring a routine formal-name in
a MAP declaration
(in order to give it certain attributes, for
example), since a formal-name is effectively declared as a LOCAL
scalar, with default attributes LONG and UNSIGNED, in the implicit
block that surrounds every routine body. Redeclaration also includes,
of course, the common, more obvious case where a name explicitly
declared as a permanent data segment in a containing block is
redeclared as (for example, LOCAL, STACKLOCAL, or REGISTER) in one or
more contained blocks.
In all such cases, the debugger knows only of the
(physically)
last
declaration of a given name that occurs in the source code for a
routine, that is to say, the last declaration of the name encountered
by the compiler when processing the source code for a particular
routine. This means that the attributes of, and storage address
corresponding to, a given name as known by the debugger are determined
by that last declaration.
An entirely different and more subtle kind of problem can arise in
connection with references to temporary data segments by name; a
problem that is inherent in the compiler's optimization techniques.
As described in Section 7.1.4, the compiler may allocate two or more
temporary values to the same storage location or register at different
points within a routine, if their "useful lifetimes" do not overlap.
(The compiler does this for a number of reasons involving both space
and time optimization.)
The possible implication of this for debugging is that, at a given
point in the execution of a routine, a name declared as LOCAL,
STACKLOCAL, or REGISTER can point to a location occupied either by a
value corresponding to a different temporary data segment or by a
compiler-defined temporary value.
The only way to resolve the
resultant ambiguity (if examination of such a value is in fact
necessary) is by careful interpretation of the object code and
examination of the program counter when stepping through the routine
in question.

3.3.9

Source-Line Debugging

When the BLISS-32 compiler is executed under VAX/VMS Version 3
(or
later versions), additional information is entered into the DEBUG
Symbol Table, which permits a limited form of source-line number
debugging
(where the source-line numbers are defined as the numbers
printed in the leftmost margin of a listing).

3-13

LINKING, EXECUTING, AND DEBUGGING
For example, it is possible to set a break on the first instruction of
a source-line using a %LINE syntax:
DBG>SET BREAK %LINE 42
Note, however, that since BLISS-32 is an optimizing compiler for an
expression language,all source lines cannot be accessed with the %LINE
syntax.
However, using the TYPE command it is possible to display
text for any line, including comments.
DBG>TYPE 17:19
Module TESTER
17: J= .J+l;
18: T= IFACT(5);
19: RETURN .T+J

!Check out 5!

the

source

120

Note that the TYPE command shown displays source lines ranging from 17
through 19 using the module designated by the current scope setting.
It is also possible to examine the
current PC location, as follows:

source

code

associated

with

DBG>EXAMINE/SOURCE .PC
18: T= IFACT(5);

3.3.10

Effect of Compilation and Link-Time Qualifiers

The use of the qualifier /DEBUG in the link operation tells the linker
to replace the user program's starting address with the debugger's
starting address. The executable image formed as a result causes the
debugger to be mapped into the user program's address space. When it
is executed, control first goes to the debug program instead of the
user program.
The debugger is a shareable image. When a shareable image is linked
into an executable image, it is unnecessary to copy the physical
content of the shareable image. When a program that uses a shareable
image is run, the copy from the shareable image file is run.
In
reality, debugger modules are mapped into memory;
they are not
physically there.
(Refer to the VAX-11 Linker Reference Manual.)
The type of data you can access symbolically depends on the settings
for the /TRACEBACK and /DEBUG qualifiers for the compilation.
If the
/NOTRACEBACK qualifier was given, no symbolic access is possible.
If
the /TRACEBACK and /NODEBUG qualifiers are given, only the names of
globals, routines, modules and PSECTs are available to the DEBUG
program.
If the /TRACEBACK and /DEBUG qualifiers are given, you can
examine BIND, GLOBAL, EXTERNAL, OWN, LOCAL, STACKLOCAL, and REGISTER
data names in addition to names already mentioned; moreover, you can
use field-names in structure accesses, reference literal names in
expressions, and use listing source line-numbers to set breaks and
examine BLISS source code.

3-14

LINKING, EXECUTING, AND DEBUGGING
Recall that, as described in Section 1.3.2.2, the qualifier /TRACEBACK
is compilation default, while /DEBUG is not.

3.3.11

Debugger Command Summary

This section summarizes commands that can be used to debug BLISS
programs. The summary presents the commands in alphabetical order.
As in BLISS notation, braces
({---})
enclose optional
command
elements;
they are not part of the syntax. The optional-repetition
symbols "···" and ", ••• " also have the same meaning as in BLISS syntax
definitions.
See SET MODE for entry/display mode keywords;
type keywords.

see SET TYPE

for

data

With the exception of
ASCII
character
input,
the
debugger
automatically converts lowercase input to uppercase.
(That is, the
debugger is not sensitive to the case of an input character.)
"Address-expression" in the command syntax representations can be the
pathname (see SET SCOPE) of a symbol in your program, a numeric value,
a symbol that you defined during this debugging session, a debugger
special character, or an expression that combines any of these
elements.
"Address-expression" also includes
BLISS-style
field
references and structure references.
The debugger supports command line continuation. A command line can
contain up to approximately 500 characters, including nonprinting
characters. You indicate continuation with the hyphen {-) as the last
character prior to the carriage return. The debugger indicates a
continued line by displaying an underline character as the first
character on the line rather than the DBG> prompt.
CTRL/"x" refers to the simultaneous typing of the CTRL key and the
respective character key, that is, C, Y, or Z {refer to the VAX/VMS
Command Language User's Guide for information on the complete list of
CTRL functions).
CTRL/"x" echoes at the terminal as Ax.
All commands preceded by an
VAX/VMS Version 3.
All command lines except CTRL
return.

asterisk

(*)

functions

are
must

only
end

available
with

with

carriage

@f ilespec
In debug mode, the @filespec denotes an indirect command file.
It causes the debugger to begin taking debug commands from the
indicated file. An indirect command file can be invoked wherever
any other debug command can be given. An indirect command file
can contain any valid debug command, including another indirect
command. An EXIT command within an indirect command file cancels
one level of indirection; an EXIT command given at terminal
input level terminates the debug process.
CALL name {{argument , ••• )}
Call routine by its symbolic name or by its virtual address
(address expression is invalid) with optional argument list. An
argument list must be enclosed by parentheses.

3-15

LINKING, EXECUTING, AND DEBUGGING
CANCEL ALL
Cancel all breakpoints, tracepoints, watchpoints, and user-set
entry/display modes.
Type is set to its default value {long
integer), and scope is set to its default value, O. The initial
entry/display modes are restored. This command does not change
the current contents of the debugger's symbol table
(that is,
those
symbols
acquired
from program modules at debugger
initialization or through use of the SET MODULE command, or any
symbols that you defined during this debugging session). The
current language is not changed.
CANCEL BREAK address-expression
CANCEL BREAK/ALL
Cancel breakpoint
breakpoints.

set

specified

address,

cancel

all

breakpoint,

CANCEL EXCEPTION BREAK
Cancel the request that your program stop, as
for any exception condition.

CANCEL MODE
Restore initial entry/display modes.
SCOPE or current language.

Command

does

not

change

CANCEL MODULE module-name-list
CANCEL MODULE/ALL
Purge symbolic information associated with the named modules from
the
debugger's
symbol table, or purge all module-related
information from the symbol table. The typical use is to make
space available for symbols associated with another module or
modules {see SET MODULE). Global symbols and any symbols defined
during this debugging session are not affected.
CANCEL SCOPE
Set scope to 0.
*CANCEL SOURCE{/module=modnam}
Cancels the current source directory search list established by
previous SET SOURCE commands.
When the qualifier is used
(/module=modname), the command cancels the affect of any previous
command in which the same module name was specified; but does
not affect commands in which other module names are specified or
commands where the qualifier is not used.
CANCEL TRACE address-expression
CANCEL TRACE/CALL
CANCEL TRACE/BRANCH
CANCEL TRACE/ALL
Cancel tracepoint set at specified address, cancel all opcode
tracing at call-type instructions, cancel all opcode tracing at
branch-type instructions, or cancel all tracepoints and opcode
tracing.
CANCEL WATCH address-expression
CANCEL WATCH/ALL
Cancel watchpoint
watchpoints.

set

specified
3-16

address,

cancel

all

LINKING, EXECUTING, AND DEBUGGING
CTRL/C
Has same effect, and echoes at terminal, as CTRL/Y (see below) if
your program does not include an exception condition handler for
CTRL/C.
CTRL/Y
Interrupt the debugger or executing program and transfer control
to the VAX/VMS command interpreter (signaled by the system prompt
$). Type DEBUG after the system prompt to return control to the
debugger.
Type CONTINUE after the system prompt to return
control to the interrupted program. Typing any VAX/VMS command
other than DEBUG or CONTINUE will probably force the premature
exit of your program.
You can use CTRL/Y to interrupt a looping
program.
To determine the point at which you interrupted you'r
program, type
DBG>EXAMINE/INSTRUCTION .PC
CTRL/Z
Same result as EXIT; that is, terminate the debugging
and transfer control to the VAX/VMS command interpreter.

session

DEFINE symbol-name=value {,symbol-name=value , ••• }
Equate name{s) of name=value list with associated value(s)
for
use during this debugging session. The debugger searches these
symbols first whenever it requires a definition for a symbolic
entry, and whenever
it requires a symbolic name to report a
location.
DEPOSIT{/modifier ••• }

address-expression=data{,data , ••• }

Enter data specified in data list in sequence of locations
beginning with the specified address. Modifier can be any mode·
or type keyword.
{Mode and type keywords can be mixed in any
meaningful way).
EVALUATE{/mode ••• }

expression

' ...

Transform input (which can be field name, arithmetic expression,
ASCII string, VAX-11 MACRO instruction, symbol, structure- or
field-reference, or numeric value)
to associated value{s)
and
display result{s).
Can be used as desk calculator,
radix
converter, symbol verifier, and so on.
The debugger displays
result(s)
in the order in which you specified the input. The
displayed decimal value of the field name is a comma list of
field components.
EXAMINE{/modifier ••• }

address{:address} {,address{:address} , ••• }

Display current contents of specified address(es).
The colon
signifies range; that is, display contents of addresses from low
address through high address. Modifier can be any mode or type
keyword.
(Mode and type keywords can be mixed in any meaningful
way).
EXIT
Terminate debugging session and transfer control to the VAX/VMS
command interpreter. An EXIT command within an indirect command
file cancels one level of indirection; an EXIT command given at
terminal input level terminates the debug process.

3-17

LINKING, EXECUTING, AND DEBUGGING
GO {address-expression}
Start or continue program execution.
The first GO command
(without an address) starts the program at its transfer address.
GO commands thereafter continue execution from a stopped point
(as at a breakpoint or watchpoint, or because of an exception
condition).
An address entry replaces the current program counter
(PC)
contents; execution starts or continues from the new location.
Once you have started a program, you should not try to attempt a
restart at the transfer address or any other address. Program
behavior is unpredictable when restarted.
*HELP topic {subtopic ••• }
Displays a description, format, qualifiers, and parameters of a
debugger command as specified by the topic parameter; and
describes qualifiers and/or parameters as specified by the
subtopic parameter.
*SEARCH{/qualifier{/qualifier} } range string
Limits the debugger's search (of a source file)
program regions for occurrences of the string.
are:

to specified
The qualifiers

occurrences of
every line, in

the
the

/ALL

Specifies search for all
string,
and
display of
specified range.

/NEXT

Specifies search, and display, of only the first
occurrence of the string in the specified range.
(This is the default.)

/IDENTIFIER

Specifies search for an occurrence of the string
in the specified range. but the string is only
displayed if it is bounded (on either side)
by a
character that is not part of an identifier in the
current language.

/STRING

Specifies a search and display of an occurrence of
the string specified.
(This is the default.)

The range parameter limits the
region as follows:

specified

program

MODNAME

Search the specified module from line
number 0 to end of module.

MODNAME\LINE-NUM

Search the specified module from the
specified line number to the end of
the module.

MODNAME\LINE-NUM:LINE-NUM

Search the specified module from the
first line number given to the last.

LINE-NUM

Search the module designated by the
current
scope
setting
from the
specified line number to the end of
the module.

3-18

LINKING, EXECUTING, AND DEBUGGING
LINE-NUM:LINE-NUM

Search the module designated by the
current scope setting beginning at
the first line number and ending at
the last.

Search the same module from which a
source line was recently displayed
(via
a
TYPE
or
EXAMINE/SOURCE
command), beginning at the first line
following the line displayed
and
continuing to the end of the module.

The string parameter specifies the string in the source code for which
the search is initiated.
SET BREAK address-expression {DO {command list)}
Establish breakpoint at specified address (the
your
program
before
the
instruction
"address-expression" is executed).

breakpoint
beginning

stops
with

The debugger executes commands in DO sequence command format
whenever your program stops because of the specified breakpoint.
Parentheses are required as command list delimiters.
Multiple
commands must be separated by se.micolons. Any complete debugger
command can be used in this context, including GO, STEP, or CALL.
If GO, STEP, or CALL is specified, it must be the last command in
the sequence.
You can specify the aafter" option to defer a breakpoint:
SET BREAK/AFTER:decimal-integer address-expression {DO ---}
Your program does not stop because of the breakpoint
(that is,
the breakpoint is ignored)
until the "n"th pass through the
specified location, as in an iteration, where n is within the
range 1 through 32767. Thereafter, the breakpoint takes effect
each time the debugger encounters it.
You can specify a
temporary (or one time) breakpoint by:
SET BREAK/AFTER:O address-expression
The debugger automatically cancels the breakpoint after it
your program the first time the breakpoint is encountered.

stops

SET EXCEPTION BREAK
Stop the program and report the current program counter contents
if an exception condition occurs that was not initiated by a
debugger command.
SET LANGUAGE language-name
Let the debugger interpret input and display output in the syntax
defined
for the specified language.
The debugger rejects
commands that are invalid in the specified syntax. The debugger
initially recognizes the language of the first module in your
program that contains symbol information.
SET LOG file-name
Specify a name other than the default name
(DEBUG.LOG)
for the
debug log file.
Can be used to generate multiple log files
during a single debug session.

3-19

LINKING, EXECUTING, AND DEBUGGING
*SET MARGIN rm
*SET MARGIN lm:rm
*SET MARGIN lm:
*SET MARGIN
:rm
Specify the leftmost and/or rightmost source line character
position at which to begin and end a line of source code. The
default value for the left margin is l; while the default value
for the right margin is 255.
*SET MAX SOURCE FILES n
Specifies the maximum number of source files
can keep open at any one time.

that

the

debugger

data

specified

SET MODE mode-keyword{,mode-keyword , ••• }
Allow or inhibit the entry
formats.

and

display

The following list describes the function of each keyword:
DECIMAL

Interpret/display data in decimal radix.

HEXADECIMAL

Interpret/display data in hexadecimal radix.

NOSYMBOLIC

Inhibit display of symbolic addresses.

OCTAL

Interpret/display data in octal radix.

SYMBOLIC

Display symbolic addresses.

The debugger's initial modes are:

SYMBOLIC and HEXADECIMAL.

You can also enter the mode keywords with the commands DEPOSIT,
EVALUATE, and EXAMINE to override the current associated mode
{radix and symbolic/nosymbolic). A slash must precede each mode
keyword entered after these command verbs.
command-verb/keyword/keyword
SET MODULE module-name-list
SET MODULE/ALL
Enter nonglobal symbols and program section names associated with
the program-module list into the debugger's symbol table, or
enter information from all modules into the symbol table.
The
debugger
cannot
interpret
nonglobal symbols unless their
associated module names appear in the status report produced by
the SHOW MODULE command with a "yes" indication.
SET OUTPUT keyword{,keyword, ••• }
Turn the logging function on/off, display or inhibit the display
of DEBUG commands executed from indirect command files or
breakpoint actions, and permit or suppress DEBUG output, except
error messages, to the terminal. Valid keywords are:
LOG

(verbatim)
and
DEBUG
Copy all command input
output, including error messages, to the current
log file;
copy verified lines if VERIFY is
specified.

3-20

LINKING, EXECUTING, AND DEBUGGING
NO LOG

Inhibit the creation of a debug log file.

TERMINAL

Print all debug output on the terminal,
including
command input, debug responses, comment lines, and
warning and error messages.

NOTERMINAL

Print only error messages;
suppress
output, including verified lines.

VERIFY

Echo command lines on the terminal as they are
executed from a breakpoint action or indirect
command file.

NOVERIFY

Do not echo command lines
file on the terminal.

from

all

indirect

debug

command

The initial keyword settings are NOLOG, NOVERIFY,
and TERMINAL.
If default settings are used,
no log file is produced, the
printing of any command taken from an indirect command file and
breakpoint action is inhibited, and all DEBUG output is printed
on the terminal.
Specifying NOLOG and NOTERMINAL causes a warning
printed; output is printed on the terminal.

message

The following symbols may appear on the log file and/or terminal:
Indicates a DEBUG response
Indicates a comment line

! !

To log all DEBUG command I/O on the log file, use the command:
SET OUTPUT LOG
SET SCOPE module-name{\routine-name ••• }
Establish an ordered list of pathnames for use with
debugger's symbol search rules.
A pathname completely
unambiguously identifies a symbol.
For BLISS, a pathname is
of the following:

the
and
one

symbol-name
module-name{\routine-name ••• }\symbol-name
The debugger evaluates an expression in which a
symbolic entry
If it
appears only if a definition was located for the entry.
fails to locate a match for a pathname, the debugger reports the
search failure and the symbol name.
NOTE
Special pathnames are available for use in
pathnames of a SET SCOPE command:

the

list

•

0 - Indicates the pathname of the lexical entity,
for
example,
routine or block, that contains the current
program counter.

•

1, 2, 3, ••• - The pathname "l" indicates the caller of
the
lexical
entity
containing the current PC;
pathname "2" indicates the caller of pathname "l", and
so on.
3-21

LINKING, EXECUTING, AND DEBUGGING
- The pathname "\" preceding a
symbolic
name
• \indicates
a global symbol of that name; for example:
EXAM \GLOBAL
causes a search for a
'GLOBAL';
nonglobal
ignored.

global symbol whose name is
symbols of the same name are

{Refer to the VAX;...11 Symbolic Debugger Reference Manual.)
*SET SEARCH parameter{,parameter}
Establishes search parameters whenever a SEARCH command qualifier
is not specified.
The parameters determine the search for
occurrences of a string as follows:
find all occurrences {ALL);
find only the next occurrence {NEXT); display all occurrences
found {STRING); display only the occurrences unbounded by a
current language identifier {IDENTIFIER).
*SET SOURCE{/module=modname} dirname{,dirname ••• }
Directs the search of specified directories for source files.
The command is used to locate source files that have been removed
from compile-time directories.
SET STEP keyword {,keyword , ••• }
Establish default
keywords are:
INSTRUCTION -

conditions

for

the

STEP

command.

Valid

Step increment in VAX-11 MACRO instructions.

INTO - Allow stepping through called routine.
LINE - Step increment by listing line numbers.
OVER - Step over called routine (make call transparent).
*SOURCE - Display the line of source code that corresponds to the
instruction{s) being executed.
*NOSOURCE - Inhibit the display of the line of
corresponding to the instruction being executed.

source

code

SYSTEM - Allow stepping in system space.
NOSYSTEM - Inhibit stepping
therein transparent).

system

The initialized conditions for BLISS are:
and OVER.

space

(make

execution

INSTRUCTION, NOSYSTEM,

SET TRACE address-expression
SET TRACE/CALL
SET TRACE/BRANCH
Set tracepoint at specified address, or specify tracing of all
call-type instructions, or all branch-type instructions. At a
tracepoint, the debugger reports the current program counter
contents and then continues program execution automatically.

3-22

LINKINGr EXECUTING, AND DEBUGGING
SET TYPE
Specify a data type to be associated to data
infer a type from its input.

when

DEBUG

cannot

The following list describes the function of each keyword:
ASCII :n

Interpret/display data as a string
characters, where n is an integer.

BYTE

Interpret/display data in byte units.

INSTRUCTION

Interpret/display VAX-11 MACRO instructions.

LONG

Interpret/display data in longword units.

WORD

Interpret/display data in word units.

ASCII

The debugger's initial type setting is: LONG INTEGER.
You can
also enter the type keywords with the commands DEPOSIT and
EXAMINE to override the current associated type.
A slash must
precede each type entered after these command verbs.
command-verb/keyword/keyword
SET WATCH address-expression
Report if the contents of the specified location(s} are modified.
The locations watched can be individual addresses (including the
number of bytes specified by the length type in effect when the
watchpoint was set), or the number of bytes associated with the
symbol's data type (for example, double precision: eight bytes).
When the contents of a watched location changes, the debugger
stops the program (as at a breakpoint) and reports both the
previous contents and the current contents of the location.
SHOW BREAK
Report the locations of
information associated
and "after" options.

current breakpoints and any relevant
with them, such as DO command sequences

SHOW CALLS {n}
Report current call level and the hierarchy of call levels that
preceded it (that is, trace your program's call history). If "n"
(a decimal integer) is expressed, the debugger reports n call
levels back from the current level (n has the range O through
32767). If "n" is omitted, all preceding call levels are
reported.
SHOW LOG
Display the name and status of the log file (see
display appears as follows:

SET

LOG.)

The

[not] logging to 'filename'
*SHOW MARGIN
Displays the current source line margin settings that are being
used for the display of sou~ce code. The margin settings are
established by the SET MARGIN command.
The default margin
settings are: left margin 1 and right margin 255.
3-23

LINKING, EXECUTING, AND DEBUGGING
*SHOW MAX SOURCE FILES
Display the maximum number of source files the debugger can
open at one time.

keep

SHOW MODE
Report the current entry/display modes (see SET MODE).
SHOW MODULE
List program modules by name,
indicate whether or not their
associated symbol data exists in the debugger's symbol table (by
yes or no) , and indicate the approximate space required for the
entry of each module's symbol data. List also the amount of
space currently unused. The debugger has no knowledge of any
program module not reported in this status report.
SHOW OUTPUT
Display the current output attributes and the name and status of
the current log file.
(See SET OUTPUT and SET LOG.) This command
generates the following status report:
output: [no]verify, [no]terminal, and [not] logging to 'filename'
*SHOW SEARCH
Displays the current search parameters established by
SEARCH command or the default values of ALL and STRING.

the

SET

SHOW SCOPE
Report the current contents of SCOPE.
*SHOW SOURCE
Displays the current source directory search list(s)
established
by the SET SOURCE or SET SOURCE/module=modname command.
SHOW STEP
Report current default conditions for STEP (see SET STEP).
SHOW TRACE
Report the locations of
tracing is in effect.

current

tracepoints,

that

opcode

SHOW TYPE
Report the current type setting.
SHOW WATCH
Report the locations of current watchpoints
bytes monitored by each watchpoint.

and

the

number

STEP{/keyword} {decimal-integer}
Begin program execution and then stop after executing the
specified number of instructions or listing-lines.
(If you do
not specify a count, the value 1 is assumed;
that is, single
stepping is the default.) The count is a decimal integer between
O through 32767.
3-24

LINKING, EXECUTING, AND DEBUGGING
The following keywords can either be used after the STEP command
verb
(STEP/keyword)
or be set with the SET STEP command to
establish the default conditions for STEP. The SHOW STEP command
displays the current defaults.
The keywords have the following relationships:
SYSTEM/NOSYSTEM - Count/do not count steps in system space.
INTO/OVER - Count/do not count steps within a called routine.
INSTRUCTION - Step by instructions.
LINE - Step by listing line numbers.
*SOURCE/NOSOURCE - Display/do not display line(s) of source code.
The initialized defaults for BLISS are:
INSTRUCTION, NOSYSTEM, OVER.
*TYPE { {modname\}line-number{:line-number} {,{modname\}line-number{:line-number} ••• } }
Displays the source language statement(s)
line number(s) specified.

corresponding

the

In effect, all the source language statements in the program can
be read by specifying a starting line number of 1 and an ending
line number that is equal to or greater than the largest line
number in the program listing.
If a module name and line number(s), either a single number or a
range of numbers (separated by a colon), are not specified, the
default scope setting is used to determine which module to use.
The default scope is either the module designated by a SET SCOPE
command or the module containing the current PC.

3-25

CHAPTER 4
MACHINE-SPECIFIC FUNCTIONS

Machine-specific functions (also referenced as builtin functions)
allow you to perform specialized VAX-11 operations within the BLISS
language. A machine-specific function call is similar to a BLISS
routine call.
It requires parameters and, in some cases, returns a
value. If a machine-specific function that does not return a value is
used in a context that requires a value, an error is reported, as in a
BLISS routine.
Compilation of a machine-specific function generates inline code,
often a single instruction, rather than a call to an external routine.
The compiler attempts to optimize the code it produces for a
machine-specific
function
call by choosing the most efficient
instruction sequence.
In some cases, the optimization procedure
r~sults
in a different machine instruction being generated than the
one specified in the call.
Machine-specific functions in BLISS-32 are divided into categories, as
illustrated in Table 4-1. A separate description of each function is
given in the following sections. For a detailed discussion, consult
the VAX-11/780 Architecture Handbook.·
The definitions of these functions consistently require addresses as
parameters, even where values could have been specified for what
VAX-11 terms "source operands" that are a longword or less in size.
For example, where a length is required as the second parameter of the
PROBER function, the call is written as in:
PROBER( ••• ,UPLIT(S), ••• )
or
PROBER( ••• ,%REF(.A+2), ••• )
{The %REF is preferred, as the compiler is free to create immediate or
short-literal addressing modes.)
Most functions also allow the name of a register to be used as the
parameter, even though register names do not have values in BLISS-32.
For example, the following code fragment:
REGISTER R;
IF PROBER {••• ,R, ••• ) THEN •••
is equivalent to:
REGISTER R;
IF PROBER{ ••• ,%REF{.R), ••• ) THEN •••

4-1

MACHINE-SPECIFIC FUNCTIONS
The following provides general rules for the use of %REF and
register names with the parameters:
Rule 1

- A %REF value
address.

Rule 2

- An undotted register can only be used
that
are:
BYTE,
WORD,
Single-precision-floating-point.

Rule 3

- A register name cannot be used as the address
character string or packed decimal string.
Table 4-1:

cannot

used

with

undotted

DESTINATION
for operands
LONG,
or
of

Machine-Specific Functions

Processor Register Operations
MFPR
MTPR

Move From Processor Register
Move to Processor Register
Parameter Validation Operations

PROBER
PROBEW

Probe Read Accessibility
Probe Write Accessibility
Program Status Operations

BICPSW
BISPSW
MOVPSL

Bit Clear PSW
Bit Set PSW
Move From PSL
Queue Operations

INS QUE.
INSQxI
REM QUE
REMQxI

Insert Entry Into Queue
Insert Entry Into Queue Interlocked
Remove Entry From Queue
Remove Entry From Queue Interlocked
Bit Operations

FFC
FFS
TESTBITCC
TESTBITCCI
TESTBITCS
TESTBITSC
TESTBITSS
TESTBITSSI

Find First Clear Bit
Find First Set Bit
Test for Bit Clear; Clear Bit
Test for Bit Clear; Clear Bit Interlocked
Test for Bit Clear; Set Bit
Test for Bit Set; Clear Bit
Test for Bit Set; Set Bit
Test for Bit .Set; Set Bit Interlocked
(continued on next page)

4-2

MACHINE-SPECIFIC FUNCTIONS
Table 4-1 (Cont.):

Machine-Specific Functions

Arithmetic Operations
ADAWI
ADDO
ADDF
ADDG
ADDH
ADDM
ASHQ
DIVD
DIVF
DIVG
DIVH
EDIV
EMUL
MULD
MULF
MULG
MULH
SUBD
SUBF
SUBG
SUBH
SUBM

Add Aligned Word Interlocked
Add Double Operands
Add Float operands
Add Float-G Operands
Add Float-H Operands
Add Multiword Operands
Arithmetic Shift Quad
Divide Double Operands
Divide Float Operands
Divide Float-G Operands
Divide Float-H Operands
Extended-Precision Divide
Extended-Precision Multiply
Multiply Double Operands
Multiply Floating Operands
Multiply Float-G Operands
Multiply Float-H Operands
Subtract Double Operands
Subtract Floating Operands
Subtract Float-G Operands
Subtract Float-H Operands
Subtract Multiword Operands
Arithmetic Comparison Operations

CMPD
CMPF
CMPG
CMPH
CMPM

Compare
Compare
Compare
Compare
Compare

Double Operands
Float Operands
Float-G Operands
Float-H Operands
Multiword Operands

Arithmetic Conversion Operations
CVTDF
CVTDI
CVTDL
CVTFD
CVTFG
CVTFH
CVTFI
CVTFL
CVTGF
CVTGL
CVTHF
CVTHL
CVTID
CVTIF
CVTLD
CVTLF
CVTLH
CVTRDH
CVTRDL
CVTRFL
CVTRGH
CVTRGL
CVTRHL

Convert Double to Float
Convert Double to Integer
Convert Double to Long
Convert Float to Double
Convert Float to Float-G
Convert Float to Float-H
Convert Float to Integer
Convert Float to Long
Convert Float-G to Float
Convert Float-G to Long
Convert Float-H to Float
Convert Float-H to Long
Convert Integer to Double
Convert Integer to Float
Convert Long to Double
Convert Long to Floating
Convert Long to Float-H
Convert Rounded Double to Float-H
Convert Rounded Double to Long
Convert Rounded Float to Long
Convert Rounded Float-G to Float-H
Convert Rounded Float-G to Long
Convert Rounded Float-H to long
(continued on next page)

4-3

MACHINE-SPECIFIC FUNCTIONS
Table 4-1

(Cont~):

Machine-Specific Functions

Character String Operations
CMPC3
CMPCS
CRC
LOCC
MATCHC
MOVC3
MOVCS
MOVTC
MOVTUC
SCANC
SKPC
SPANC

Compare Characters 3 Operand
Compare Characters 5 Operand
Cyclic Redundancy Calculation
Locate Character
Match Characters
Move Character 3 Operand
Move Character 5 Operand
Move Translated Characters
Move Translated Until Character
Scan Characters
Skip Character
Span Characters
Decimal String Operations

ASHP
CMPP
CVTLP
CVTPL
CVTPS
CVTPT
CVTSP
CVTTP
EDIT PC
MOVP

Arithmetic Shift and Round Packed
Compare Packed
Convert Long to Packed
Convert Packed to Long
Convert Packed to Leading Separate Numeric
Convert Packed to Trailing Numeric
Convert Leading Separate Numeric to Packed
Convert Trailing Numeric to Packed
Edit Packed to Character
Move Packed
Miscellaneous Operations

BPT
BUGL
BUGW
CAL LG
CHMx
HALT
INDEX
NOP
ROT
XFC

Breakpoint
Bugcheck With Long Operand
Bugcheck With Word Operand
Call With General Argument List
Change Mode
Halt Processor
Index (Subscript) Calculation
No Operation
Rotate a Value
Extended Function Call

The compiler attempts to optimize the code which corresponds to a
machine-specific function call.
It chooses instruction sequences
based on the type of result required of the function and the context
in which it is used. This is illustrated in the following examples:
BLISS Source
IF TESTBITSS( X<3,l> )
THEN
BEGIN
CONSEQUENCE
END

4-4

MACHINE-SPECIFIC· FUNCTIONS
Generated Code
BBCS

#3,X,1$
;

. CONSEQUENCE

1$:
Note that the compiler has chosen an instruction with the opposite
sense to the machine-specific function.
If 1$ could not be reached by
a byte displacement, the coding would be:
BBSS
BRW

#3,X,1$
2$

1$:
CONSEQUENCE
;

2$:

In the above example, the TESTBITSS routine is used in a situation
where it is required to generate only a control flow result. If a
real result actually was needed, it might be generated as in this
example.
BLISS Source
Y = TESTBITSS( X<3,l> )
Generated Code
CLRL
BBCS
INCL

#3,X,1$

1$:
A machine-specific function differs from a routine call in that the
compiler can determine exactly how the parameters of the routine call
are going to be used, and so there are cases where %REF does not
really need to allocate a temporary. For example, the call:
BISPSW( %REF (%X'80'));

ENABLE DECIMAL OVERFLOW

would be coded as:
BISPSW

rxso

ENABLE DECIMAL OVERFLOW

witho~t any temporary being allocated.

The compiler can make similar decisions when you use the undotted name
of a local as a parameter in a machine-specific function call. You
are syntactically specifying an address, but depending on
the
parameter, that local might still be allocated in a register. For
example,
MOVPSL(ALOCAL)
might result in
MOVPSL

4-5

MACHINE-SPECIFIC FUNCTIONS
4.1

ADAWI - ADD ALIGNED WORD INTERLOCKED
ADAWI (SRCADDR, DSTADDR)

Parameters:
SRCADDR

- Address of a word whose contents are
destination

DSTADDR

- Address of a word to which the,source is to be added
The address must be word-aligned (that is, the low
bit must be zero).

added

the

Result:
Contents of the PSL

4.2

ADDD - ADD DOUBLE OPERANDS
ADDO (SRClA, SRC2A, DSTA)

Parameters:
SRClA

a
- Address
double-precision
of
quadword used as the addend

floating-point

SRC2A

double-precision
- Address
a
of
quadword used as the augend

floating-point

DSTA

- Address of a quadword where the sum is stored

Result:

NOVA LUE

4.3

ADDF - ADD FLOATING OPERANDS
ADDF (SRClA, SRC2A, DSTA)

Parameters:
SRClA

- Address
a
single-precision
of
longword used as the addend

floating-point

SRC2A

a
- Address
single-precision
of
longword used as the augend

floating-point

DSTA

- Address of a longword where the sum is stored

Result:

NOVALUE

4-6

MACHI'NE-SPECIF'IC FUNCTIONS
4.4

ADDG - ADD FLOAT-G OPERANDS
ADDG (SRClA, SRC2A, DSTA)

Parameters:
SRClA

- Address
of
an
extended
double-precision
floating-point quadword used as the addend

SRC2A

- Address
of
an
extended
double-precision
floating-point quadword used as the augend

DSTA

- Address of a quadword where the sum is stored

Result:
NOVA LUE

4.5

ADDH - ADD FLOAT-H OPERANDS
ADDH (SRClA, SRC2A, DSTA)

Parameters:
SRClA

- Address of an extended-exponent double-precision
floating-point octaword used as the addend

SRC2A

- Address of an extended-exponent double-precision
floating-point octaword used as the augend

DSTA

Address of an octaword where the sum is stored

Results:
NOVA LUE

4.6

ADDM - ADD MULTIWORD OPERANDS
ADDM (SIZE, SRClA, SRC2A, DSTA)

Parameters:
SIZE

Compile-time-constant expression indicating the size
of the operands in words (BLISS value units)

SRClA

- Address of extended multi-precision integer used
the addend

SRC2A

- Address of extended multi-precision integer used
the augend

DSTA

- Address of the sum of source one and source two

Result:
NOVA LUE

4-7

MACHINE-SPECIFIC FUNCTI.ONS
4.7

ASHQ - ARITHMETIC SHIFT QUAD
ASHQ (SHIFT, SRCADDR, DSTADDR)

Parameters:
SHIFT

- Address of a byte whose contents specify
count

SRCADDR

- Address of a quadword containing the quantity to
shifted

DSTADDR

- Address of-a quadword where the shifted result is to
be stored

the

shift
be

Result:
Contents of the PSL

4.8

BICPSW - BIT CLEAR PSW
BICPSW (MASKADDR) ·

Parameter:
MASKADDR

- Address of a word whose contents are
complemented and AND'ed into the PSW

ones

OR'ed

Result:
NOVALUE

4.9

BISPSW - BIT SET PSW
BISPSW (MASKADDR)

Parameter:
MASKADDR

- Address of a word whose contents
into the PSW

Result:
NOVA LUE

4.10

BPT - BREAK POINT TRAP
BPT

()

Parameters:
None
Result:
NOVA LUE

4-8

are

MACHINE-SPECIFIC FUNCTIONS
4.11

BUGL - BUGCHECK WITH LONG OPERAND
BUGL (ARG)

Parameters:
ARG

- Link-time
constant
expression
(LTCE)
to
be
interpreted by the bugcheck exception handling code

Result:
NOVA LUE
The following example based on the DISPAT module in the FllACP:
buil tin
BUGW
external literal
BUG$_UNXSIGNAL;
BUGW( BUG$_UNXSIGNAL or 4 );
generates the code sequence:
.EXTRN BUG$_UNXSIGNAL
BUGW
.WORD BUG$_UNXSIGNAL!4
The in-line generation of this code eliminates the need
PLIT containing hand-assembled code.

4.12

create

BUGW - BUGCHECK WITH WORD OPERAND
BUGW (ARG)

Parameters:
ARG

Link-time constant expression (LTCE) word value to
be interpreted by the bugcheck exception handling
code

Result:
NOVALUE

4.13

CALLG - CALL WITH GENERAL PARAMETER LIST
CALLG (ARGLIST, RTN)

Parameters:
ARGLIST

- Address {of the parameter list) to be placed in the
parameter pointer (AP) register must not be a
register name or a %REF vlaue)

RTN

- Address of the routine to be called

4-9

MACHINE-SPECIFIC FUNCTIONS
Result:
Same as result of the routine that is called
Note:
This function does not interact with any linkage attribute information
that may be associated with the second parameter. It must be used
only to call a routine with a standard VAX/VMS linkage
(BLISS and
FORTRAN in BLISS-32).
To pass a routine's
following sequence:

argument

list

another

routine,

use

the

BUILT IN
AP,
CALLG;
CALLG(.AP,OTHERRTN);

4.14

CHMX - CHANGE MODE
CHME
CHMK
CHMS
CHMU

(ARG)
(ARG)
(ARG)
(ARG)

Parameters:
ARG

- Address of a word
parameter code

whose

contents

are

used

Result:
NOVALUE

4.15

CMPD - COMPARE DOUBLE
CMPD (SRClA, SRC2A)

Parameters:
SRClA

- Address of a quadword containing a double-precision
floating-point value be the name of a register nor a
%REF value)

SRC2A

- Address of a quadword containing a
floating-point value

Result:
-1
0
l

- SRClA less than SRC2A
- SRClA equal to SRC2A
- SRClA greater than SRC2A

4-10

double-precision

MACHINE-SPECIFIC FUNCTIONS
4.16

CMPF - COMPARE FLOATING
CMPF (SRClA, SRC2A)

Parameters:
SRClA

- Address of a longword containing a
floating-point value

single-precision

SRC2A

- Address of a longword containing a
floating-point value

single-precision

Result:
-1
0
1

4.17

- SRClA less than SRC2A
- SRClA equal to SRC2A
- SRClA greater than SRC2A

CMPP - COMPARE PACKED
CMPP (SRClLENA, SRClADDR, SRC2LENA, SRC2ADDR)

Parameters:
SRClLENA

- Address of a word containing
decimal string SRCl

SRClADDR

- Address of the base of packed decimal string SRCl

SRC2LENA

- Address of a word containing the length
string SRC2

SRC2ADDR

- Address of the base of packed decimal string SRC2

the

length

the

decimal

Result:
-1

0
1

- SRCl less than SRC2
- SRCl equal to SRC2
- SRCl greater than SRC2

Note: CMPP3 or CMPP4 is generated depending on the operands provided.

4.18

CRC - CYCLIC REDUNDANCY CHECK
CRC (TABLEADDR, INICRCADDR, STRLENADDR, STREAMADDR, DSTADDR)

Parameters:
TABLEADDR

- Address of a 16-longword table

INICRCADDR - Address of a longword which contains the initial CRC
STRLENADDR - Address of a word containing the unsigned length
the data stream in bytes

STREAMADDR - Address of the first byte of the data stream
DSTADDR

- Address of a longword where the resulting 32-bi t CRC
is to be stored

4-11

MACHINE~SPECIFIC

FUNCTIONS

Result:
NOVA LUE

4.19

CVTDF - CONVERT DOUBLE TO FLOATING
CVTDF (SRCA, DSTA)

Parameters:
SRCA

- Address of a quadword containing a
floating-point value

DSTA

- Address of a longword where the single-precision
floating-point conversion is stored

double-precision

Result:

4.20

- No floating-point overflow

- Floating-point overflow

CVTDI - CONVERT DOUBLE TO INTEGER
CVTDI (SRCA, DSTA)

Parameters:
SRCA

- Address of a quadword containing a
floating-point value

DSTA

- Address where the integer conversion is stored

double-precision

Result:

4.21

- No integer overflow

- integer overflow

CVTDL - CONVERT DOUBLE TO LONG
CVTDL (SRCA, DSTA)

Parameters:
SRCA

- Address of a quadword containing a
floating-point value

DSTA

- Address of a longword where the
is stored

Result:
1

- No integer overflow

- Integer overflow

4-12

double-precision

integer

conversion

MACHINE-SPECIFIC FUNCTIONS
4.22

CVTFD - CONVERT FLOATING TO DOUBLE
CVTFD (SRCA, DSTA)

Parameters:
SRCA

- Address of a longword containing a
floating-point value

DSTA

- Address of a quadword where the double-precision
floating-point conversion is stored

single-precision

Result:
NOVA LUE

4.23

CVTFG - CONVERT FLOATING TO FLOAT-G
CVTFG (SRCA, DSTA)
Parameters:
SRCA

- Address of a longword containing a
floating-point value

single-precision

DSTA

- Address
of
a
quadword
where
the
extended
double-precision floating-point conversion is stored

Result:
NOVALUE

4.24

CVTFH - CONVERT FLOATING TO FLOAT-ff
CVTFH (SRCA, DSTA)
Parameters:
SRCA

- Address of a longword containing a
floating-point value

single-precision

DSTA

- Address of an octaword where the extended-exponent
double-precision floating-point conversion is stored

Result:
NOVA LUE

4.25

CVTFI - CONVERT FLOATING TO INTEGER
CVTFI (SRCA, DSTA)

Parameters:
SRCA

- Address of a longword containing a
floating-point value

DSTA

- Address of a longword where the
is stored
4-13

single-precision

integer

conversion

MACHINE-SPECIFIC FUNCTIONS
Result:

4.26

- No integer overflow

- Integer overflow

CVTFL - CONVERT FLOATING TO LONG
CVTFL (SRCA, DSTA)

Parameters:
SRCA

- Address of a longword containing a
floating-point value

DSTA

- Address of a longword where the
is stored

single-precision

integer

conversion

Result:

4.27

- No integer overflow

- Integer overflow

CVTGF - CONVERT FLOAT-G TO FLOATING
CVTGF (SRCA, DSTA)

Parameters:
SRCA

- Address of a quadword containing
double-precision floating-point value

DSTA

- Address of a longword where the single-precision
floating-point conversion is stored

extended

Result:
NOVALUE·

4.28

CVTGL - CONVERT FLOAT-G TO LONG
CVTGL (SRCA, DSTA)

Parameters:
SRCA

- Address of a quadword containing
double-precision floating-point value

DSTA

- Address of a longword where the
is stored

Result:
NOVALUE

4-14

extended

integer

conversion

MACHINE~SPECIFIC

4.29

FUNCTIONS

CVTHF - CONVERT FLOAT-ft TO FLOATING
CVTHF (SRCA,DSTA)
SRCA

- Address
of
an
octaword
containing
an
extended-exponent
double-precision floating-point
value

DSTA

- Address of a longword where the single-precision
floating-point conversion is stored

Result:
NOVA LUE

4.30

CVTHL - CONVERT FLOAT-B TO LONG
CVTHL (SRCA, DSTA)

Parameters:
SRCA

- Address
of
an
octaword
containing
an
double-precision floating-point
extended-exponent
value

DSTA

- Address of a longword where the
is stored

integer

conversion

Result:
NOVA LUE

4.31

CVTID - CONVERT INTEGER TO DOUBLE
CVTID (SRCA, DSTA)

Parameters:
SRCA

- Address of a longword containing an integer value

DSTA

- Address of a quadword where the double-precision
floating-point conversion is stored

Result:
NOVA LUE

4.32

CVTIF - CONVERT INTEGER TO FLOATING
CVTIF (SRCA, DSTA)

Parameters:
SRCA

- Address of a longword containing an integer value

DSTA

- Address of a longword where the single-precision
floating point conversion is stored

4-15

MACHINE-SPECIFIC FUNCTIONS
Result:
NOVALUE

4.33

CVTLD - CONVERT LONG TO DOUBLE
CVTLD (SRCA, DSTA)

Parameters:
SRCA

- Address of a longword containing an integer value

DSTA

- Address of quadword where the
double-precision
floating-point conversion is stored

Result:
NOVA LUE

4.34

- No overflow can occur

CVTLF - CONVERT LONG TO FLOATING
CVTLF {SRCA, DSTA)

Parameters:
SRCA

- Address of a longword containing an integer value

DSTA

- Address of a longword where the single-precision
floating-point conversion is stored

Result:
NOVA LUE

4.35

- No overflow can occur

CVTLH - CONVERT LONG TO FLOAT-ff
CVTLH {SRCA, DSTA)

Parameters:
SRCA

- Address of a longword containing an integer value

DSTA

- Address of an octaword where the extended-exponent
double-precision floating point conversion is stored

Result:
NOVALUE

4.36

CVTLP - CONVERT LONG TO PACKED
CVTLP (SRCA, DSTLENA, DSTADDR)

4-16

MACHINE-SPECIFIC FUNCTIONS
Parameters:
SRCA

- Address of a longword containing an integer value

DST LENA

- Address of a word
destination string

DSTADDR

- Address of the base of the destination string

containing

the

length

the

Result:
l

- No decimal overflow

- Decimal overflow

4.37

CVTPL - CONVERT PACKED TO LONG
CVTPL (SRCLENA, SRCADDR, DSTA)

Parameters:
SRCLENA

- Address of a word
source string

SRCADDR

- Address of the base of the source string

DSTA

- Address of a longword where the
is stored

containing

the

length

integer

conversion

Result:
1

- No integer overflow

- Integer overflow

4.38

CVTPS - CONVERT PACKED TO LEADING SEPARATE NUMERIC
CVTPS (SRCLENA, SRCADDR, DSTLENA, DSTADDR)

Parameters:
SRCLENA

- Address of a word
source string

SRCADDR

- Address of the base of the source string

·DSTLENA·

- Address of a word
destination string

DSTADDR

- Address of the base of the destination string

Result:
1

- No decimal overflow

- Decimal overflow

4-17

containing

the

length

the

MACHINE-SPECIFIC FUNCTIONS
4.39

CVTPT - CONVERT PACKED TO TRAILING NUMERIC
CVTPT (SRCLENA, SRCADDR, TBLADDR, DSTLENA, DSTADDR)

Parameters:
SRCLENA

- Address of a word
source string

SRCAD DR

- Address of the base of the source string

TBLADDR

- Address of the table used to convert the sign

DST LENA

- Address of a word
destination string

DSTADDR

- Address of the base of the destination string

containing

the

length

the

Result:

4.40

- No decimal overflow

- Decimal overflow

CVTRDH - CONVERT ROUNDED DOUBLE TO FLOAT-ff
CVTRDH (SRCA, DSTA)

Parameters:
SRCA

- Address of a quadword containing a
floating-point value

double-precision

DSTA

- Address of an octaword where the extended-exponent
double-precision floating-point conversion is stored

Result:
NOVALUE

4.41

CVTRDL - CONVERT ROUNDED DOUBLE TO LONG
CVTRDL (SRCA, DSTA)

Parameters:
SRCA

- Address of a quadword containing a
floating-point value

DSTA

- Address of a longword where the
is stored

Result:
1

- No integer overflow

- Integer overflow

4-18

double-precision

integer

conversion

MACHINE-SPECIFIC-' FUNCTIONS
4.42

CVTRFL - CONVERT ROUNDED FLOATING TO LONG
CVTRFL (SRCA, DSTA)

Parameters:
SRCA

- Address of a longword containing a
floating-point value

DSTA

Address of a longword where the
is stored

single-precision

integer

conversion

Result:

4.43

- No iriteger overflow

- Integer overflow

CVTSP - CONVERT LEADING SEPARATE TO PACKED
CVTSP (SRCLENA, SRCADDR, DSTLENA, DSTADDR)

Parameters:
SRCLENA

- Address of a word
source string

SRCAD DR

- Address of the base of the source string

DSTLENA

- Address of a word
destinatiOn string

DSTADDR

- Address of the base of the destination string

containing

the

length

the

Result:

4.44

- No decimal overflow

- Decimal overflow

VTTP - CONVERT TRAILING NUMERIC TO PACKED
CVTTP (SRCLENA, SRCADDR, TBLADDR, DSTLENA, DSTADDR)

Parameters:
SRCLENA

- Address of a word
source string

SRCAD DR

- Address of the base of the source string

TBLADDR

- Address of the table used to convert the sign

DST LENA

- Address of a word
destination string

DSTADDR

- Address of the base of the destination string

4-19

containing

the

length

MACHINE-SPECIFIC FUNCTIONS.
Result:

4.45

- No decimal overflow

- Decimal overflow

DIVD - DIVIDE DOUBLE OPERANDS
DIVD {DIVSR, DIVID, QUOT)

Parameters:
DIVSR

- Address
of
a
double-precision
quadward used as the divisor

floating-point

DIVID

- Address
of
a
double-precision
quadword used as the dividend

floating-point

QUOT

- Address of a quadword where the quotient is stored

Result:
NOVA LUE

4.46

DIVF - DIVIDE FLOATING OPERANDS
DIVF {DVISR DIVID, QUOT)
DVISR

- Address
of
a
single-precision
longword used as the divisor

floating-point

DIVID

a
- Address
of
single-precision
longword used as the dividend

floating-point

QUOT

- Address of a longword where the quotient is stored

Result:
NOVALUE

4.47

DIVG - DIVIDE FLOAT-G OPERANDS
DIVG {DIVSR, DIVID, QUOT)

Parameters:
DIVSR

- Address of an extended double-precision
point quadword used as the divisor

floating

DIVID

- Address of an extended double-precision
point quadword used as the dividend

floating

QUOT

- Address of a quadword where the quotient is stored

Result:
NOVA LUE

4-20

MACHINE-SPECIFIC FUNCTIONS
4.48

DIVH - DIVIDE FLOAT-H OPERANDS
DIVH (DIVSR, DIVID, QUOT)

Parameters:
DIVSR

- Address of an extended-exponent double-precision
floating-point octaword that is used as the divisor

DIVID

- Address -0f an extended-exponent doublw-precision
floating-point octaword that is used as the dividend

QUOT

- Address of an octaword where the quotient is stored

Result:
NOVA LUE

4.49

EDITPC - EDIT PACKED TO CHARACTER
EDITPC (SRCLENA, SRCADDR, PATTERN, DSTADDR)

Parameters:
SRCLENA

- Address of a word
source string

SR CAD DR

- Address of the base of the source string

PATTERN

- Address of the pattern-operator string

DSTADDR

- Address of the base of the destination string

containing

the

length

the

Result:

4.50

- No decimal overflow

- Decimal overflow

EDIV - EXTENDED-PRECISION DIVIDE
EDIV (DIVISOR, DIVIDEND, QUOTIENT, REMAINDER)

Parameters:
DIVISOR

- Address of a longword whose contents are used as the
divisor

DIVIDEND

- Address of a quadword whose contents are used as the
dividend

QUOTIENT

- Address of a longword where the quotient
stored

REMAINDER

- Address of a longword where the remainder is
stored

Result:
Contents of the PSL

4-21

MACHINE,...SPECIFIC FUNCTIONS
4.51

EMUL - EXTENDED-PRECISION MULTIPLY
EMUL (MULR, MULD, ADD, PROD)

Parameters:
MULR

- Address of a longword whose contents are used as the
multiplier

MULD

- Address of a longword whose contents are used as the
multiplicand

ADD

- Address
of
a
longword
whose
contents
are
sign-extended to a quadword and added to the product
quadword

PROD

- Address of a quadword where
stored a %REF value)

the

result

Result:
Contents of the PSL

4.52

FFC AND FFS - FIND AND MODIFY OPERATIONS
FFC (POSADDR, SIZADDR, BASEADDR, DSTADDR) Find first clear bit
FFS (POSADDR, SIZADDR, BASEADDR, DSTADDR)
Find first set bit

Parameters:
POSADDR

- Address of a longword whose contents specify a bit
position relative to the low bit of the byte
addressed by BASEADDR. The low bit of that byte is
bit position zero.

SI ZADOR

- Address of a byte whose contents, when zero extended
to 32 bits, have a value less than or equal to 32.
This value specifies the size of the field to be
searched. The size of the field is measured in bits
and begins at the bit position specified by POSADDR
and extends toward increasing bit numbers.

BASEADDR

- Address of a byte whose low bit
position zero

DSTADDR

- Address of a longword
first bit found in
stored

interpreted

where the position of the
the specified state is to be

Result:
1

No bit in the specified state is found in the
searched.
- Otherwise

4-22

field

MACHINE-SPECIFIC FUNCTIONS
4.53

HALT - HALT PROCESSOR
HALT ()

Parameters:
NONE
Result:
NOVA LUE
Description:
This routine generates a HALT instruction.

4.54

INDEX - INDEX CALCULATION
INDEX (SUBSCRIPT, LOW, HIGH, SIZE, INDEXIN, INDEXOUT)

Parameters:
SUBSCRIPT

- Address of a longword containing the subscript

LOW

- Address of a longword containing the lower bound
the subscript range

HIGH

- Address of a longword containing the upper bound
the subscript range

SIZE

- Address of a longword containing the scale factor

INDEXIN

- Address of a longword containing the
value

INDEXOUT

- Address of a longword where
stored

the

initial

result

index
to

Result:
NOVALUE

4.55

INSQHI AND INSQTI - INSERT ENTRY IN QUEUE, INTERLOCKED
INSQHI(ENTRY, HEADER)
INSQTI(ENTRY, HEADER)

Insert entry in queue at head, interlocked
Insert entry in queue at tail, interlocked

Parameters:
ENTRY

- Address of an entry
following the header

HEADER

- Address of the queue header

4-23

inserted

queue

MACHINE-SPECIFIC ·FUNCTIONS
Result:
0

- If ENTRY was not the first entry to be
the queue

- If the secondary interlock could not be acquired

- If ENTRY was the first entry to be inserted into the
queue

Note that, if a real result is
generated for these functions is:

1$:
2$:

CLRL
INSQxI
BCS
BNEQ
INCL
INCL

needed,

the

inserted

instruction

sequence

tmp
ENTRY,HEADER
1$
2$
tmp
tmp

If only a flow result is requested, the instruction sequence is:
INSQxI
BCC

ENTRY,HEADER
1$

Success
Failure actions

Thus, the BLISS expression to set a software interlock realized with a
queue is:
WHILE INSQHI(ENTRY, HEADER) DO WAIT();

4.56

INSQUE - INSERT ENTRY IN QUEUE
INSQUE (ENTRY, PRED)

Parameters:
ENTRY

- Address of an entry to be inserted
after the entry specified by PRED

PRED

- Address of an entry in a queue

the

queue

Result:

4.57

- ENTRY was the first entry to be
queue

- Otherwise

inserted

.into

the

LOCC - LOCATE CHARACTER
LOCC (CHARA, LENA, ADDR)

Parameters:
CHARA

- Address of a byte containing
located

4-24

the

character

MACHINE-SPECIFIC FUNCTIONS
LENA

- Address of
length

ADDR

- Address of the string to be searched

word

containing

the

string

Result:

4.58

TRUE

- A byte was located which was the same as .CHARA<0,8>
(the Z condition code is clear)

FALSE

- No byte was located (the Z condition code is set)

MATCHC - MATCH CHARACTERS
MATCHC (OBJLENA, OBJADDR, SRCLENA, SRCADDR)

Parameters:
OBJLENA

- Address of word containing the length of the pattern
string

OBJAD DR

- Address of the pattern string

SRCLENA

- Address of a word containing
string to be searched

SRCAD DR

- Address of the string to be searched

the

length

the

Result:

4.59

TRUE

- A match was found (the Z condition code is set)

FALSE

- No match was found

(the Z condition code is clear)

MFPR - MOVE FROM PROCESSOR REGISTER
MFPR (PROCREG, DSTADDR)

Parameters:
PROCREG

- Processor register number

DSTADDR

- Address of a longword where the contents
processor register is to be stored

the

Result:
NOVALUE

4.60

MOVC3 - MOVE CHARACTER 3 OPERAND
MOVC3 (LENA, SRCADDR, DSTADDR)

Parameters:
LENA

- Address of a word
source string

4-25

containing

the

length

MACHINE-SPECIFIC FUNCTIONS
SRCADDR

- Address of the base of the source string

DSTADDR

- Address of the destination string

Result:
NOVALUE

4.61

MOVCS ..;.MOVE CHARACTER 5 OPERAND
MOVCS (SRCLENA, SRCADDR, FILL,TBLADDR, DSTLENA, DSTADDR)

Parameters:
source

SRCLENA

- Address of word containing the length of the
string

SRCADDR

- Address of the base of the source string

FILL

- Address of a byte containing the fill character

TBLADDR

- Address of the translation table

DST LENA

- Address of word
length

DSTADDR

- Address of the destination string

containing

the

destination-string

Result:
NOVA LUE

4.62

MOVP - MOVE PACKED
MOVP {LENA, SRCADDR, DSTADDR)

Parameters:
LENA

- Address of a word
source string

containing

the

length

SRCAD DR

- Address of the base of the source decimal string

DSTADDR

- Address of the base of the destination

the

Result:
NOVA LUE

4.63

MOVPSL - MOVE FROM PSL
MOVPSL (DSTADDR)

Parameter:
DSTADDR

- Address of a longword where the contents of the
is to be stored

4-26

PSL

MACHINE-SPECIFIC FUNCTIONS
Result:
NOVA LUE

4.64

MOVTC - MOVE TRANSLATED CHARACTERS
MOVTC (SRCLENA, SRCADDR, FILL, TBLADDR, DSTLENA, DSTADDR)

Parameters:
SRCLENA

- Address of a word containing the source length

SRCADDR

- Address of source string

FILL

- Address of a byte containing the fill character

TBLADDR

- Address of the translation table

DST LENA

- Address of a word containing the destination length

DSTADDR

- Address of the destination string

Result:
NOVA LUE

4.65

MOVTUC - MOVE TRANSLATED UNTIL CHARACTER
MOVTUC (SRCLENA, SRCADDR, ESCA, TBLADDR, DSTLENA, DSTADDR)

Parameters:
SRCLENA

- Address of a word
source string

SRCADDR

- Addiess of the base of the source string

ESCA

- Address of a byte containing the escape character

TBLADDR

- Address of the translation
using CH$TRANSTABLE)

DST LENA

- Address of a word
destination string

DSTADDR

- Address of the base of the destination string

containing

the

table

containing

the

length

(may

length

the

created
of

the

Result:
If the string was successfully translated without escape, the
result is 0. Otherwise, the result is the address of the byte in
the source string which caused the escape.

4.66

MTPR - MOVE TO PROCESSOR REGISTER
MTPR (SRCADDR, PROCREG)

4-27

MACHINE-SPECIFIC FUNCTIONS
Parameters:
SRCADDR

- Address of a longword whose contents are to
loaded into the designated processor register

PROCREG

- Processor register number

Result:
NOVA LUE

4.67

MULD - MULTIPLY DOUBLE OPERANDS
MULD (SRClA, SRC2A, DSTA)

Parameters:
SRClA

a
double-precision
- Address
of
quadword used as the multi plier

floating-point

SRC2A

double-precision
of
a
- Address
quadword used as the multiplicand

floating-point

DSTA

- Address of a quadword where the product is stored

Result:
NOVA LUE

4.68

MULF - MULTIPLY FLOATING OPERANDS
MULF (SRClA, SRC2A, DSTA)

Parameters:
SRClA

a
- Address
of
single-precision
longword used as the multi plier

floating-po int

SRC2A

- Address
of
a
single-precision
longword used as the multiplicand

floating-point

DSTA

- Address of a longword where the product is stored

Result:
NOVA LUE

4.69

MULG - MULTIPLY FLOAT-G OPERANDS
MULG (SRClA, SRC2A, DSTA)

Parameters:
SRClA

- Address
of
an
extended
double-precision
floating-point quadword used as the multiplier

SRC2A

- Address
of
an
extended
double-precision
floating-point quadword used as the multiplicand

DSTA

- Address of a quadword where the product is stored
4-28

MACHINE-SPECIFIC FUNCTIONS
Result:
NOVALUE

4.70

MULH - MULTIPLY FLOAT-R OPERANDS
MULH (SRClA, SRC2A, DSTA)

Parameters:
SRClA

- Address of an extended-exponent double-precision
floating-point octaword used as a multiplier

SRC2A

- Address of an extended-exponent double-precision
floating-point octaword used as a multiplicand

DSTA

- Address of an octaword where the product is stored

Result:
NOVALUE

4.71

NOP - NO OPERATION
NOP ()

Parameters:
None
Result:
NOVA LUE

4.72

PROBER - PROBE READ ACCESSIBILITY
PROBER (MODEADDR, LENGTHADDR, BASEADDR)

Parameters:
MODEADDR

- Address of a byte
protection mode

whose

contents

specify

LENGTHADDR - Address of a word whose contents are zero-extended
and added to BASEADDR to specify the last byte of an
area in memory
BASEADDR

- Address of the first byte of an area in memory (must
not be the name of a register nor a %REF value)

Result:
1

- Both first and last bytes are read-accessible

- Otherwise

4-29

MACHINE-SPECIFIC FUNCTIONS
4.73

PROBEW - PROBE WRITE ACCESSIBILITY
PROBEW (MODEADDR, LENGTHADDR, BASEADDR)

Parameters:
MODEADDR

- Address of a byte
protection mode

whose

contents

specify

LENGTHADDR - Address of a word whose contents are zero-extended
and added to BASEADDR to specify the last byte of an
area in memory
BASEADDR

- Address of the first byte of an area in memory (must
not be the name of a register nor a %REF value)

Result:

4.74

- Both first and last bytes are write-accessible

- Otherwise

REMQHI AND REMQTI - REMOVE ENTRY FROM QUEUE, INTERLOCKED
REMQHI (HEADER, ADDR)
REMQTI (HEADER, ADDR)

Remove from queue at head, interlocked
Remove from queue at tail, interlocked

Parameters:
HEADER

- Address of the queue header

ADDR

- Address of a longword where the address of the entry
removed is to be stored

Result:
0

- The queue is not empty;

an entry was removed.

- The secondary interlock could not be acquired.

- The queue is now empty;

- The queue was already empty;

the last entry was removed.
no entry was removed.

The result of REMQxI is TRUE if no entry was removed, either because
the queue was empty or because the secondary interlock was not
acquired.
The instruction sequence generated in real-context is:

1$:
2$:

CLRL
REMQxI
BCS
BVS
BEQL
DECL
ADDL
INCL

tmp
HEADER,ADDR
Interlock failed
Remove failed
Removed an entry
Removed last entry

1$
3$

tmp
#2,tmp
tmp

The instruction sequence generated in flow-context is:
REMQxI
BVC

HEADER,ADDR
1$
4-30

Entry removed
Remove failed

MACHINE-SPECIFIC FUNCTIONS
4.75

REMQUE - REMOVE ENTRY FROM QUEUE
REMQUE (ENTRY, ADDR)

Parameters:
ENTRY

- Address of an entry in a queue

ADDR

- Address of a longword where the address of the entry
removed is to be stored

Result:
Value

Initial
State

Final
State

Entry
Removed

not empty

yes

not empty

empty

yes

empty

Note that the value of REMQUE is true only if no entry was removed.
The value is computed from the condition codes as:
(Z-bit)Al OR (V-bit)

4.76

ROT - ROTATE A VALUE
ROT (VALUE, SHIFT)

Parameters:
VALUE

- Value to be rotated

SHIFT

- Number of bits to rotate

Result:
VALUE rotated the specified number of bits

4.77

SCANC - SCAN CHARACTERS
SCANC (LENA, ADDR, TBLADDR, MASKA)

Parameters:
LENA

- Address of a word containing
string to be scanned

ADDR

- Address of the base of the string

TBLADDR

- Address of the translation table

MAS KA

- Address of a byte containing
scanning

4-31

the

length

mask

the

use

MACHINE~SPEClPIC

FUNCTIONS

Result:
If the SCANC fails to find a match, the result is O.
Otherwise,
the result is the address of the byte that produced a nonzero AND
with the MASK.

4.78

SKPC - SKI.P CHARACTER
SKPC (CHARA, LENA, ADDR)

Parameters:
CHARA

- Address of a byte containing
skipped

.LENA

- Address of
length

ADDR

- Address of the string to be searched

word

the

containing

character
the

string

Result:

4.79

TRUE

- A byte was located which was not the same
.CHARA<0,8> (the Z condition code is clear)

FALSE

- No byte was located (the Z condition code is set)

SPANC - SPAN CHARACTERS
SPANC (LENA, ADDR, TBLADDR, MASKA)

Parameters:
LENA

- Address of a word containing
string to be spanned

ADDR

- Address of the base of the string

TBLADDR

- Address of the translation table

MAS KA

- Address of a byte containing
spanning

the

length

mask

the

use

Result:
If the SPANC fails to find a match, the result is O.
Otherwise,
the result is the address of the byte that produced a zero AND
with the MASK.

4.80

UBD - SUBTRACT DOUBLE·OPERANDS
SUBD (SRClA, SRC2A, DSTA)

Parameters:
SRClA

- Address
of
a
double-precision
quadword used as the subtrahend

4-32

floating-point

MACHINE-SPECIFIC FUNCTIONS
SRC2A

- Address
of
a
double-precision
quadword used as the minuend

floating-point

DSTA

- Address of the
stored

difference

quadword

where

the

Result:
NOVALUE

4.81

SUBF - SUBTRACT FLOATING OPERANDS
SUBF {SRClA, SRC2A, DSTA)

Parameters:
SRClA

- Address
a
of
single-precision
longword used as the subtrahend

floating-point

SRC2A

- Address
of
a
single-precision
longword used as the minuend

floating-point

DSTA

- Address of a longword where the difference is stored

Result:
NOVA LUE

4.82

SUBG - SUBTRACT FLOAT-G OPERANDS
SUBG {SRClA, SRC2A, DSTA)

Parameters:
SRClA

- Address
of
an
extended
double-precision
floating-point quadword used as the subtrahend

SRC2A

- Address
of
an
extended
double-precision
floating-point quadword used as the minuend

DSTA

- Address of a quadword where the difference is stored

Result
NOVA LUE

4.83

SUBH - SUBTRACT FLOAT-H OPERANDS
SUBH (SRClA, SRC2A, DSTA)

Parameters:
SRClA

- Address of an extended-exponent double-precision
floating-point ocatword used as the subtrahend

SRC2A

- Address of an extended-exponent double-precision
floating-point octaword used as the minuend

DSTA

- Address of
stored

octaword
4-33

where

the

difference

MACHINE-SPECIFIC FUNCTIONS·
Result:
NOVA LUE

4.84

SUBM - SUBTRACT MULTIWORD OPERANDS
SUBM {SIZE, SRClA, SRC2A, DSTA)

Parameters:
SIZE

Compile-time-constant-expression indicating the size
of the operands in fullwords {BLISS value units)

SRClA

- Address of an extended multi-precision integer
as the subtrahend

used

.SRC2A

- Address of an extended multi-precision integer
as the minuend

used

DSTA

- Address of the difference

Result:
NOVA LUE

4.85

TESTBITX - TEST AND MODIFY OPERATIONS
TESTBITSS {FIELD)
TESTBITSC {FIELD)
TESTBITCS {FIELD)
TESTBITCC {FIELD)
TESTBITSSI {FIELD)
TESTBITCCI {FIELD)

Test for bit set, then set bit
Test for bit set, then clear bit
Test for bit clear, then set bit
Test for bit clear, then clear bit
Test for bit
set,
then
set
{interlocked)
Test for bit clear, then clear
(interlocked)

bit
bit

Parameter:
FIELD

- Address with optional field selector which specifies
a
field whose low bit will be tested for a
particular state. That bit will be set to the
specified state.
The size parameter of the field
selector is ignored and a literal value one is
substituted
Note that these are the only routines in the
machine-specific set which accept an address with
field selector that cannot be evaluated to an
address.

Result:
1

Bit tested was in the specified state
- Otherwise

4-34

MACHINE-SPECIFIC FUNCTIONS
4.86

XFC - EXTENDED FUNCTION CALL
XFC (OPCODE)

Parameters:
OPCODE

- Link-time-constant-expression to be deposited in the
byte which follows the XFC opcode in the instruction
stream

Result:
NOVA LUE

4-35

CHAPTER 5
PROGRAMMING CONSIDERATIONS

This chapter provides practical help on writing BLISS programs.
First, usage differences between LIBRARY and REQUIRE files are
considered. Then, some common BLISS programming errors are discussed.

5.1

LIBRARY AND REQUIRE USAGE DIFFERENCES

BLISS library files are used like required files:
declarations that
are common to more than one module are centralized in a single file,
which is automatically incorporated into other
modules
during
compilation by means of REQUIRE or LIBRARY declarations.
Library files are more efficient for doing this than required files
for two reasons. First, with files invoked by REQUIRE declarations,
the cost of processing the source occurs every time the file is used
in a compilation. However, with library files, the major compilation
cost occurs once when the library is compiled, and a much smaller cost
occurs each time the library file is used in a compilation. A library
file closely approximates the internal symbol table representation
used by the compiler; hence, costs of lexical processing (including
scanning, lexical conditionals,
lexical
functions,
and
macro
expansions) and declaration parsing and checking occur only during the
library compilation.
Second, with files invoked by REQUIRE declarations, all declarations
contained in the file are incorporated into the compiler symbol table.
With library files, the compiler does not incorporate declarations
into
the normal symbol table until they are actually needed.
Declarations of names that are not used do not fill up the symbol
table.
The difference in cost depends on many factors, including the size of
the library, the size of the module being compiled, and the percentage
and kind of declarations used from a library.
Experimental results
indicate that compiler time and space requirements can typically be
improved by a factor of four by using library files instead of source
files.

5-1

PROGRAMMING CONSIDERATIONS
Library files and the same declarations used from source files using
the REQUIRE declarations are similar. However, the differences are:
•

Files invoked by REQUIRE declarations are source (text) files;
files invoked by LIBRARY declarations must be special files
created by the compiler in a previous library compilation.

•

Files invoked by REQUIRE declarations can contain any source
text that is valid when that source text is substituted for
the
REQUIRE
declaration.
Files
invoked
by
LIBRARY
declarations must be compiled from sources that consist of a
sequence of (only} the following declarations:
COMPILETIME
EXTERNAL
EXTERNAL LITERAL
EXTERNAL ROUTINE
FIELD
KEYWORDMACRO
LIBRARY
LINKAGE
LITERAL
MACRO
REQUIRE
STRUCTURE
SWITCHES
UNDECLARE

•

SWITCHES. declarations contained in files invoked by the
REQUIRE decla.ration can affect the module being compiled;
those contained in files used to produce library files affect
only
the library compilation.
Switch settings are not
incorporated into the compilation that uses the library file.
(The only switches that are useful in a library compilation
are LIST, LANGUAGE, and ERRS. The remaining switches may be
given, but are effectively ignored since none of them has any
effect on the declarations that are valid in a library
compilation.}

•

Files invoked by REQUIRE declarations. can have effects that
depend on previous declarations or switch settings in the
module being compiled.
This can occur
in
a
lexical
conditional (%IF-%THEN-%ELSE-%FI) or macro expansion that
depends either on the lexical functions %SWITCHES, %DECLARED,
or %VARIANT, or on values of predeclared literals, such as
%BPVAL.
(Refer to "Predeclared Literals" in Section 6. 3.1.1.}
Files invoked by LIBRARY declarations do not have effects that
depend on previous declarations or switch settings, because
SWITCijES
declarations,
REQUIRE
declarations,
lexical
conditionals or macro calls contained in sources used to
produce a library file are processed during the library
compilation.

•

Appropriately written source files can be invoked by REQUIRE
declarations in BLISS compilers other than BLISS-32. Library
files can be invoked only in compilations by the same compiler
that created the library file.

5-2

PROGRAMMING CONSIDERATIONS
In most normal cases, the source files used to create a library can be
invoked by a REQUIRE declaration or the library can be invoked by a
LIBRARY declaration with identical effects in the module being
compiled.
However, the differences presented above can lead to
problems that are difficult to identify. Therefore, one or the other
form should be used consistently for each set of declarations.

5.2

FREQUENT BLISS CODING ERRORS

Certain coding errors occur frequently, especially when new BLISS
users compile and debug a new module. The following check list may be
useful when you cannot seem to find the source of a problem.

S.2.1

Missing Dots

The most frequent error is to forget a dot. Except for the left side
of an assignment expression, the appearance of a data segment name
without a preceding fetch operator is the exception, ,and usually a
mistake. For example:
IF A THEN •••
should almost certainly be:
IF .A THEN •••

5.2.2

Valued and Nonvalued Routines

The BLISS compiler does not diagnose useless value expressions in
contexts that do not use a value. For example, in the following
routine:
ROUTINE R(A): NOVALUE
BEGIN

RETURN 5;
END;
the apparent return value 5 is discarded, since the
NOVALUE attribute.

routine

has

the

However, in the following case:
ROUTINE S(B)
BEGIN

RETURN;
END;
an informational message is issued indicating that a value expression
is missing in a context that implies a value.
(The compiler assumes a
value of zero for missing expressions.)

5-3

PROGRAMMING CONSIDERATIONS
S.2.3

Semicolons and Values of Blocks

It is common to think of a semicolon as a terminator of an expression,
but this is not true and can lead to errors. In the following
example:
IF .A
THEN
X=.Y;
ELSE
X=-5;
the first semicolon terminates the initial IF-THEN and the
ELSE is in error.

subsequent

A more subtle error is to place a semicolon after the last expression
of a block when that expression is supposed to be the value of the
block.
(This is very similar to Section 5.2.2 above concerning valued
and nonvalued routines.)

5.2.4

Complex Expressions Using AND, OR, and NOT

When writing complex tests involving the AND, OR, and NOT operators,
it is easy to confuse the relative precedence of the operators. Use
parentheses to make your intent explicit to the compiler, to. other
readers, and to yourself. For example, instead of:
IF .X EQL 0 AND .Y OR NOT .J THEN •••
use:
IF ((.X EQL 0) AND .Y) OR (NOT .J) THEN •••

5.2.5

Computed Routine Calls

When computing the address of a routine to be called, enclose the
expression that computes the address in parentheses followed by the
parameters. For example:
BEGIN
EXTERNAL ROUTINE
R;
LOCAL
L;
L = R;
{.L) (0)

END
calls the routine at address R with a parameter of zero.

However:

• L {0)

calls the routine at address L (most likely an address on the stack)
and uses the returned value as the operand of the fetch. Since there
is no code at address L, an illegal instruction exception is likely at
execution.

5-4

PROGRAMMING CONSIDERATIONS
An alternative is to use a general routine call. Assuming the desired
linkage is the default calling convention, you could write the
computed call as:
BLISS (. L, 0)

5.2.6

Signed and Unsigned Fields

Be careful when using signed and unsigned fields that are smaller than
a fullword.
Consistent use of the sign extension rules and signed
versus unsigned operations is important.
For example, in
the
following:
BEGIN
FIELD LOW9 = [0,0,9,0];
OWN
X : BLOCK[!] FIELD(LOW9);
IF .X[LOW9] EQL -5
THEN
END
the expression .X[LOW9] EQL -5 is always false because the
value fetched from X is necessarily in the range 0 to 511.

5.2.7

(unsigned)

Complex Macros

The BLISS macro facility has many capabilities, but also has some very
subtle properties.
Most problems arise when features that have
side-effects on the compilation are used, such as:
•

Macro expansions that produce declarations
particularly other macro declarations

•

Use of compile-time names to control
%ASSIGN

•

Use of %QUOTE, %UNQUOTE, and %EXPAND

macro

Be particularly careful when trying to use these
you may not really need them in the first place.

5.2.8

any

kind,

expansions

using

features;

indeed,

Missing Code

Many coding errors tend to tesult in code that can be optimized.
If
you discover that some of your program seems to be missing from the
compiled code, you may possibly have made a coding error.
Check the
compiled code carefully to ensure that the code is indeed missing,
rather than cleverly optimized.
For example, consider the following:
BEGIN
OWN
X: BYTE;
IF .X EQL -5 THEN X = O;
END
5-5

PROGRAMMING CONSIDERATIONS
In the above example, the value of the test expression, .index EQL -5,
is
always
false.
(Refer to "Signed and Unsigned Fields" in
Section 5.2.6.) As a result, the compiler
•

produces no code for the test expression, and

•

produces no code for the alternative, X=O
executed).

(it

can

never

Consequently, the entire IF expression disappears from the compiled
code.
The problem is not erroneous compiler optimization, but a
missing SIGNED attribute in the declaration of x.
A similar error occurs if the fact is overlooked that TRUE/FALSE is
based on the value of the low bit of an expression. Thus the
following fragment:
IF .x and 2
THEN
Y=O
ELSE
Y=l
will always assign the value "l" to Y, because the low bit of
and 2" must, always be zero (false).

5.3

".index

ERRORS FROM LINKER

The TRUNC or TRUNCDAT error message is typically caused
compiled with the default addressing mode

module

ADDRESSING_MODE(WORD_RELATIVE)
being linked in an image that is larger than 32K.
resolved by any of the following procedures:

5.4

The problem can
to

be
use

•

Edit
the
offending
source
module
ADDRESSING_MODE(LONG_RELATIVE) and recompile.

•

Rearrange the placement of the object modules in such a manner
that EXTERNAL or inter-PSECT references are within 32k bytes
of their target.·

OBSCURE ERROR MESSAGES

Obscure error messages that appear after a program has been run are
typically caused by a program whose main routine fails to return a
valid VMS completion code.

5.5

PIC CODE GENERATION

The BLISS-32 compiler always generates position-independent code (PIC)
for expressions that involve relocatable quantities. This may cause
surprisingly complex code to be generated.
However, it is the
programmer's responsibility to ensure that he/she has generated PIC
data, when necessary.

5-6

CHAPTER 6
TRANSPORTABILITY GUIDELINES

This chapter addresses the task of writing transportable programs. It
shows why writing such transportable code is much easier if considered
from the beginning of the project, explores properties that cause a
program to lose its transportability, and discusses techniques by
which a programmer can avoid these pitfalls.
After an introduction to the concept of transportability,
the
transportability guidelines presented in this chapter are organized
into three sections. The section "General Strategies" discusses some
high-level approaches to writing transportable software in BLISS. The
section "Tools" describes various features of the BLISS language that
can be used in solving transportability problems.
The section
"Techniques for Writing Transportable Programs" analyzes various
transportability problems and suggests solutions to them.
The dialects discussed in this chapter are the
the following BLISS compilers:

languages

defined

BLISS-16 Vl
BLISS-32 V2
BLISS-36 V2
BLISS-36 and BLISS-16 are intended as generic names for language that
have BLISS compilers generating code for DEC-10/20's and PDP-ll's,
respectively.

6.1

INTRODUCTION

A transportable BLISS program is one that can be compiled to execute
on at least two, and preferably all, of the three major architectures:
PDP-10, PDP-11, and VAX-11.
Various solutions to the problem of
transportability exist, each requiring different levels of effort.
Various kinds of solutions are recommended.
For example, in some
cases, program text should be rewritten. However, large portions of
programs can be written in such a way that they will require no
modification
and
yet
be functionally equivalent in differing
architectures.
The levels of solutions in order of decreasing
desirability, are:
•

No change is needed to
completely transportable.

6-1

program

text

The

program

TRANSPORTABILITY GUIDELINES
•

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 the program makes
use of features of an architecture that do not have analogs
across all other architectures, or different, separately
transportable
aspects
of
the
program
interact
in
nontransportable ways.

The goal is to make transportability as simple as possible, which
means that the effort needed in transporting programs should be
minimized. Central to the ideas presented here is the notion that
transportability is more easily accomplished if considered from the
beginning. Transporting programs after they are running becomes a
much more complex task.
It is advantageous to run parallel compilations frequently.
It is
fortunate therefore, that with the right tools and techniques,
transportability is not difficult to achieve. The first transportable
program is the hardest.
Before undertaking a large programming
project, it may be useful to write and transport a less ambitious
program.
These guidelines are the result of a concentrated study of the
problems associated with transportability.
No claim is made that
these guidelines are complete. Some of what is contained here will
not be obvious to programmers. An attempt is made to identify those
areas that can cause problems, if the programmer is not forewarned.
Solutions to all identified problems are suggested.

6.2

GENERAL STRATEGIES

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

Isolation, and

•

Simplicity

6.2.1

are

Isolation

Remember the following rule when you are designing or coding a program
that is to be transported:
•

If a construct is NOT transportable, isolate it.

You will probably encounter situations for which it is desirable to
use machine-specific constructs in your BLISS program. In these
cases, simply isolating the constructs will facilitate any future
movement of the program to a different machine. In most cases, only a
small percentage of the program or system will be sensitive to the
machine on which it is running. By isolating those sections of a

6-2

TRANSPORTABILITY GUIDELINES
program or a system, the effort involved in transporting the program
will be confined mainly to these easily identifiable, machine-specific
sections. Specifically, follow these rules1
•

If machine-specific data are to be allocated, place
allocation in a separate module or in a REQUIRE file.

•

If machine-specific data are to be accessed, place the
accessing code in a routine or in a macro and then place the
routine or macro in a separate module or in a REQUIRE file.

•

If a machine-specific function or instruction is to
isolate it by placing it in a REQUIRE file.

•

If it is impossible or impractical to isolate this part of
your program from its module, comment it heavily. Make it
obvious to the reader that this code is nontransportable.

the

used,

The above rules are applicable in the local context of a routine or
module.
In a larger or more global context (for instance, in the
design of an entire system), isolation is implemented by the technique
of modularization•
By separating those parts of the system that are
machine- or operating-system dependent from the rest of the system,
the task of transporting the entire system is simplified.
It becomes
a matter of recoding a small section of the total system.
The major
portion of the code (if written in a transportable manner) should be
easy to move to a new machine with a minimum of recoding.
The BLISS
language facilitates both the design and programming of programs and
systems in a modular fashion.
This feature should be used to
advantage when writing a transportable system.

6.2.2

Simplicity

A basic concept in writing transportable BLISS software is simplicity
in the use of the language. BLISS was originally developed for the
implementation of systems software. As a result of this, BLISS is one
of few high-level programming languages that allow ready access to the
machine on which the program will be running.
The programmer is
allowed to have complete control over the allocation of data, for
example. Unfortunately, the same language features that allow access
to underlying features of the hardware are the very features that lead
to nontransportable code. In a system intended to be transportable,
these features should be used only where necessary to meet a specific
functional, performance, or economy objective.
It is often the case that BLISS language features that make a program
nontransportable also make the program more complex. Reducing the
complexity of data allocation, for example, results in a transportable
subset of the BLISS language. This reduction of complexity is one of
the basic themes that runs through these guidelines.
In effect, the
coding of transportable programs is a simpler task because the number
of options available has been reduced.
Simplicity in the coding
effort is one of the reasons for the development of higher-level
languages like BLISS. The use of the defaults in BLISS will result in
programs that are much more easily transported.

6-3

TRANSPORTABILITY GUIDELINES
6.3

TOOLS

This section on tools presents various language features that provide
a means for writing transportable programs. These features are either
normal features of BLISS or have been designed for transportability or
software engineering uses.
The tools described here will be used
throughout the next section on techniques.

6.3.1

Literals

Literals provide a means for associating a name with a compile-time
constant expression.
This section considers some built-in literals
that aid in writing transportable programs. In addition, it discusses
restrictions on user-defined literals.

6.3.1.1 Predeclared Literals - One of the key techniques in writing
transportable programs is parameterization. Literals are a primary
parameterization tool. The BLISS language has a set of predeclared,
machine-specific
literals
that can be useful.
These literals
parameterize certain architectural values of the three machines.
The
values of the literals are dependent on the machine for which the
program is currently being compiled. Here are their names and values:
Description

Literal
Name

10/20

VAX-11

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 literal names that can be used
without declaration.
These literal names are used throughout these
guidelines.
Bits per value is the maximum number of bits in a BLISS value.
Bits
per unit is the number of bits in the smallest unit of storage that
can have an address. Bits per ad0ress refers to the maximum number of
bits an address value can have.
Units per value is the quotient
%BPVAL/%BPUNIT.
It is the maximum number of addressable units
associated with a value.
We can derive other useful values from these built-in
example:

literals.

For

LITERAL
HALF VALUE = %BPVAL / 2;
defines the number of bits in half a word (half a longword on VAX-11).

6-4

TRANSPORTABILITY GUIDELINES
6.3.1.2 User-Defined Literals - Strictly speaking, a literal is not a
self-defining term.
The value and restrictions associated with a
literal are arrived at by assigning certain semantics to its source
program representation.
It is convenient to define the value of a
literal as a function of the characteristics of a
particular
architecture,
which means that there are certain architectural
dependencies inherent in the use of literals. Because the size of a
BLISS value determines the value and/or the representation of a
literal, there are some transportability considerations.
BLISS value {machine word) sizes are different on each of the three
machines.
On VAX-11, the size is 32 bits; on the 10/20 systems, it
is 36; and the 11 value is 16.
There are two types of BLISS literals: numeric literals and string
literals.
The values of numeric literals are constrained by the
machine word size. The ranges of values for a signed number, i , are:
VAX-11:

-(2**31)

< i < {2**31) - 1

10/20:

-(2**35)

< i < (2**35)

11:

-(2**15)

< i < {2**15) - 1

ALL:

- (2 ** {%BPVAL-l))

< i < {2**{%BPVAL-l))-l

- 1

A numeric literal, %C'single-character', has been implemented.
Its
value is the ASCII code corresponding to the character in quotes and
when stored,
it is right-justified in a BLISS value
{word or
longword).
A more thorough discussion of its usage can be found in
the section "Data: Character Sequences." There are two ways of using
string literals:
as integer values and as character strings. When
string literals are used as values, they are not transportable.
This
arises out of the representational differences and from differing word
sizes. The following table illustrates these potential differences
for an %ASCII type string literal:
VAX-11
Maximum number of
characters

Character placement

right to
left

This type of string-Ii teral usage and also
string are discussed in the section "Data:

6.3.2

10/20

left to
right

right to
left

its use as a character
Character Sequences. II

Macros and Conditional Compilation

of
BLISS macros can be an essential tool in the development
(expand)
during
transportable
programs.
Because they evaluate
compilation, it is possible to use macros to tailor a program to a
specific machine.

6-5

TRANSPORTABILITY GUIDELINES
A good example can be found in the section "Structures." There, two
macros are developed whose functions are completely transportable.
The macros can determine the number of addressable units needed for a
vector of elements, ·where the element size is specified in terms of
bits. There are also predefined machine conditionalization macros
available. These macros can be used to select for compilation certaln
declarations or expressions depending on which compiler is being run.
There are three sets of definitions, each containing three macro
definitions.
The definitions for the BLISS-32 set are:
MACRO
%BLISS16[] = % ,
%BLISS36 []
% ,
%BLISS32 [] = %REMAINING % ;
There are analogous definitions for the other machines.
The net
effect is that in the BLISS-32 compiler, the arguments to %BLISS16 and
%BLISS36 will disappear, while arguments to %BLISS32 will be replaced
by the text given in the parameter list.
A very explicit way of tailoring a program to a specific architecture
uses the %BLISS lexical function in conjunction with the conditional
compilation facility in BLISS.
The %BLISS lexical function takes
either BLISS36, BLISS32 or BLISS16 as a parameter, and returns 1 if
the parameter corresponds to the compiler currently executing, and O
otherwise. In the following example, INSQUE is an executable function
in BLISS-32, but is a routine for BLISS-36:
%IF %BLISS(BLISS32}
%THEN
BUILTIN
INSQUE;
%ELSE
%IF %BLISS(BLISS36}
%THEN
FORWARD ROUTINE
INSQUE;
%FI
%FI

6.3.3

Module Switches

A module switch and a corresponding special switch are provided to aid
in the writing of transportable programs. This switch, LANGUAGE, is
provided for two reasons:
•

To indicate the intended transportability goals
and

•

To provide diagnostic checking of the use of certain
features.

module
language

Using this switch, you can therefore indicate the target architectures
(environments} for which a program is intended.

6-6

TRANSPORTABILITY GUIDELINES
Transportability checking consists of the
compiler
determining
whether, in the module being compiled, certain language features
appear that fall into either of two categories:
•

Features that are not commonly supported across
target environments.

the

intended

•

Features that most often prove to
be
troublesome
in
transporting a program from any one environment to another.

The syntax is:
LANGUAGE (language-name , ••• )
where language-name
BLISS32.

any

combination

BLISS36,

BLISS16,

Two other forms are possible:
LANGUAGE( COMMON
LANGUAGE()
If no LANGUAGE switch is specified, the default is the single language
name corresponding to the compiler used for the compilation, and no
transportability checking
is
performed.
If
more
than
one
language-name is specified, the compiler will assume that the program
is intended to run under each corresponding architecture.
If no language name is specified, no transportability checking will be
performed.
A specification of COMMON is the equivalent of the
specification of all three.
Each compiler will give a warning diagnostic if its own
is not included in the list of language-names.

language-name

Within the scope of a language switch, each compiler will give a
warning diagnostic for any nontransportable or problematic language
construct relative to the specified set of languages.
This chapter
discusses most of the constructs that will be checked for.
NOTE
The precise set of language constructs
that are subject to transportability
checking is specified in Appendix C of
the BLISS Language Guide.

6-7

TRANSPORTABILITY GUIDELINES
Here is· an example of how ·the LANGUAGE switch can be used:
MODULE FOO( ••• ,LANGUAGE(COMMON) , ••• )
BEGIN
!+
! Full Transportability Checking is in effect.
!-

...
...
BEGIN
!+
! BLISS36 no longer in effect:
BLISS-16/32 Subset checking
! to be performed in this block.
!-

SWITCHES
LANGUAGE(BLISS16, BLISS32);

Within this block (that is, within the .scope
of the SWITCHES declaration) , a relaxed
form of full transportability checking
is performed. (This takes advantage of
the greater degree of commonality that
exists between the BLISS-16 and BLISS-32
target architectures.)
The compilation of this section
of code by a BLISS-36 compiler will
result in a diagnostic warning.

END;
!+
Full transportability checking is restored.
!-

6.3.4

Reserved Names

The following is a list of the BLISS reserved names.
These names
cannot be declared by the user. While the same names are reserved in
all three BLISS dialects, some of them do not have a predefined
meaning in each dialect.
For example, LONG is an allocation-unit
keyword in BLISS-32 and is a reserved but otherwise unsupported name
in BLISS-16 and BLISS-36 (due to basic architectural differences in
the target systems) • Any attempted use of this name in the latter two
dialects will result in a compiler diagnostic. As another example,
the name IOPAGE has no defined meaning in any BLISS dialect but is

6-8

TRANSPORTABILITY GUIDELINES
reserved for possible future use in all dialects. The reserved names
that are not supported in some or all dialects are marked with an
asterisk.
See Appendix A of the BLISS Language Guide for a more
complete description.
*ADDRESSING MODE
*ALIGN
ALWAYS
AND
BEGIN
BIND
*BIT
BUILTIN
BY
*BYTE
CASE
CODECOMMENT
COMPILETIME
DECR
DEC RA
DECRU
DO
ELSE
ELUDOM
ENABLE
END
EQL
EQLA
EQLU
EQV
EXITLOOP
EXTERNAL
FIELD
FORWARD
FROM
GEQ
GEQA
GEQU
GLOBAL
GTR
GTRA

6.3.5

GTRU
IF
INCR
INC RA
INC RU
INITIAL
INRANGE
*IO PAGE
KEYWORDMACRO
LABEL
LEAVE
LEQ
LEQA
LEQU
LIBRARY
LINKAGE
LITERAL
LOCAL
*LONG
LSS
LSSA
LSSU
MACRO
MAP
MOD
MODULE
NEQ
NEQA
NEQU
NOT
NOVA LUE
OF
OR
OTHERWISE
OUTRAN GE
OWN

PLIT
PRESET
PSECT
*RECORD
REF
REGISTER
REP
REQUIRE
RETURN
ROUTINE
SELECT
SELECTA
SELECTONE
SELECTONEA
SELECTONEU
SELECTU
SET
*SHOW
*SIGNED
STACKLOCAL
STRUCTURE
SWITCHES
TES
THEN
TO
UN DECLARE
*UNSIGNED
UNTIL
UPLIT
VOLATILE
*WEAK
WHILE
WITH
*WORD
XOR

REQUIRE and LIBRARY Files

REQUIRE files are a way of gathering machine-specific declarations
and/or expressions together in one place. LIBRARY files are a form of
precompiled REQUIRE files.
In many cases, it will be either impossible or unnecessary to code a
particular
BLISS
construct
(for
example,
routines and data
declarations) in a transportable manner.
Developing parallel REQUIRE
files,
one for each machine, can often provide a 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.

6-9

TRANSPORTABILITY GUIDELINES
Each BLISS compiler has a predefined 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 search rules for each compiler are:
Compiler

lST

2ND

3RD

4TH

BLISS-36

.R36

.REQ

.B36

.BL!

BLISS-16

.Rl6

.REQ

.Bl6

.BL!

BLISS-32

.R32

.REQ

.B32

.BL!

Hence, the following REQUIRE declaration:
REQUIRE
I IOPACK';

! I/O Package

will search for IOPACK.R36, IOPACK.Rl6 or IOPACK.R32, depending on
which
compiler is being run.
Failing that it will look for
IOPACK.REQ, and so on.
Inherent in these search rules is a naming convention for REQUIRE
files.
If the file is transportable, give it the file type '.REQ' or
'.BLI'.
If it is specific to a particular dialect, give it the
corresponding file type (for example, '.R36' or '.B36').
Each BLISS compiler, by the use of the /LIBRARY switch, is capable of
precompiling
files
containing
declarations.
However, not all
declarations can be processed in a library run;
those that are
allowed are described elsewhere.
The output of a library run is
called a 1 ibrary file;
1 ibrary files are processed by a compiler when
it encounters a LIBRARY declaration, for example:
LIBRARY
I IOPACK';
Each compiler checks to see that the library file it is using was
produced by itself in a previous run. Thus, to build a transportable
library from a single transportable source, you must build unique
LIBRARY files for each architecture of interest, using the appropriate
compilers of interest.
For example, let us assume that the file SYSDCL.BLI contains a set of
transportable declarations common to an application that is to run on
a DECSYSTEM-20 and a VAX. To precompile it requires that it be run on
the BLISS-32 compiler using the /LIBRARY switch, and the BLISS-36
compiler using the /LIBRARY switch. The object file produced by the
compiler is the library file, and if no extension is given for it in
the command line, a default extension is used (for example,
.L32 and
.L36 respectively).

6-10

TRANSPORTABILITY GUIDELINES
6.3.6

Routines

The key to transportability is the ability to identify an abstraction
that can exist in several environments. This is done by naming the
abstraction and describing its external characteristics in a way that
permits implementation in any of the environments. The abstraction
may then be implemented separately in each environment.
The closed
subroutine has long been regarded as the principal abstraction
mechanism in programming languages.
With BLISS, other abstraction
mechanisms are also available, like structures, macros, literals,
require files, and so on, 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.
If the floating-point arithmetic resides
entirely in a well-defined set of routines, and no knowledge of the
various representations of floating-point numbers is used except
through these well defined interface routines, then it becomes
possible to perform "cross-arithmetic", which is important when
writing cross-compilers, for instance. Even if the ability to perform
cross-arithmetic is not desired, isolating floating-point operations
in routines may be 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
(since the system under
construction is transportable), but need not be transportable if
cross-arithmetic is not a goal.
The principal objection to using routines as an abstraction mechanism
is that the cost of calling a procedure is significant, and that cost
is strictly program overhead. Composing this sort of abstraction in
the limit will produce serious performance degradation. For this
reason, a programmer should probably try not to use the routine as a
transportability mechanism if a small amount of forethought will be
sufficient to enable the writing of a single transportable module.

6.4

TECHNIQUES FOR WRITING TRANSPORTABLE PROGRAMS

This section on techniques shows you how to write
programs.
The section is organized in dictionary
construct or concept. Each subsection contains:

transportable
form by BLISS

•

A discussion of the construct or concept.

•

Transportability problems that its use may engender.

•

Specific guidelines and
construct or concept.

•

Examples - both transportable and nontransportable.

restrictions

the

use

In all cases, the examples attempt to use the tbols described
previous section.

6-11

the

TRANSPORTABILITY GUIDELINES
6.4.1

Data

This section deals with the allocation of data in a BLISS program.
In
this section we do not deal with character sequence (string) data or
the formation of address data. These types of data are discussed in
their own sections (See:
"Data: Addresses and Address Calculation"
and "Data:
Character Sequences").
Primarily, we
discuss
~he
allocation of scalar data (for example, counters, integers, pointers,
addresses, and so on.) A presentation of more complex forms of data
can be found in the sections "Structures and Field-Selectors" and
"PLITs and Initialization." First there
is
a
discussion
of
transportability
problems
encountered due to differing machine
architectures.
Next a discussion of the BLISS
allocation-unit
attribute is presented.
Finally, a discussion of other ·BLISS data
attributes that must be considered when writing transportable programs
is discussed.

6.4.1.1 Problem Origin - The allocation of data (via the OWN,
LOCAL,
GLOBAL, and other declarations) tends to be one of the most sensitive
areas of a BLISS program in terms of transportability.
This problem
of transporting data arises chiefly from two sources:
•

The machine architectures and

•

The flexibility of the BLISS language.

When we are considering writing a BLISS program that will be
transported to another machine, we are confronted with the problem of
allocating data on (at least two) architecturally different machines.
Although we have already discussed differing word sizes, there are
further
differences.
On the VAX-11 architecture, data may be
typically 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
18-bit halfwords and 36-bit words on the 10/20 systems may be fetched
without a byte pointer.
If we were writing our program in an assembly language we would not
consider these differences to be important - clearly, our assembly
language program was not intended to be transportable.
What decisions, however, must the BLISS programmer make in the
transportable allocation of data? Need he or she be concerned with
how many bits are going to be allocated?
These questions (and their answers) can be complicated by the other
chief source of data transportability problems, namely the BLISS
language itself.
BLISS is unlike many other higher-level languages in that it allows
ready access to machine-specific control, particularly in storage
allocation. This is fortunate for the programmer who is trying to
write efficient machine-specific software. This programmer needs much
more control over exactly how many bits of data will be used.
This
feature of BLISS, however, can complicate the decisions that need to
be made by the BLISS programmer who is writing a transportable
program. Does he or she allocate scalars by bytes, or by words, or by
longwords?

6-12

TRANSPORTABILITY GUIDELINES
6.4.1.2 Transportable Declarations - Consider
example of a data declaration in BLISS-32:
LOCAL
PAGE COUNTER:

BYTE;

the

following

simple

Page counter

The programmer has allocated one byte (8 bits) for a variable named
PAGE COUNTER. No matter what his or her intentions were in requesting
only-one byte of storage, this declaration is nontransportable.
The
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 in an error
message.
In fact, since this storage is allocated on the stack or in
a register, there is even less motivation to make it a byte due to the
frequent use of these locations.
If this declaration had been originally coded as:
LOCAL
PAGE_COUNTER;

Page counter

then this could have been transported to any of the three machines.
The functionality (in this case, storing the number of pages) has not
been lost. We allowed the BLISS compiler to allocate storage by
default
by
not
specifying any allocation unit in the LOCAL
declaration.
In all BLISS dialects the default size for allocation
unit consists of %BPVAL bits. Thus our first transportable guideline
is:
•

Do not use the allocation-unit
declaration.

attribute

scalar

data

In the case of scalar data, the use of 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, is 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 BLISS language, the default size of %BPVAL bits was chosen
(among other reasons)
because this is the largest, most efficiently
accessed unit of data for a particular machine.
In other words, the
saving of bits does not necessarily mean a more efficient program.
Besides the allocation unit there
present transportability problems
allocating data:
•

are other
if used.

attributes that may
In particular, when

Do not use the following attributes:
Extension (SIGNED and UNSIGNED),
Alignment,
Weak
which is to say: think twice before you write a declaration.
Do you really need to specify any data attributes other than
structure attributes?

The extension attribute specifies whether the sign bit is to be
extended in a fetch of a scalar (or equivalently, whether or not the
left most bit is to be interpreted as a sign bit). In any case, no
sign extension can be performed if the allocation unit is not
specified.

6-13

TRANSPORTABILITY GUIDELINES
The alignment attribute tells the compiler at what kind of address
boundary a data segment is to start. It is not supported in BLISS-36
or BLISS-16;
h~nce,
it is nontransportable.
Suitable
default
alignments are available dependent on the size of the scalar.
The weak attribute is a VAX/VMS-specific attribute and is not
supported by BLISS-36 or BLISS-16.
It therefore can not be used in a
transportable program.
These guidelines are relatively simple, yet they should relieve the
BLISS programmer of needing to worry about how the program data will
actually be allocated by the compiler. There is often very little
reason to specify an allocation unit or any attributes. The default
values are almost always sufficient.
There will undoubtedly be cases where it is impossible to avoid the
use of one or more of the above attributes.
In fact, it may be
desirable to take advantage of a specific machine feature.
In these
cases follow this guideline:
•

Conditionalize or heavily comment
which may be nontransportable.

the

use

declarations

This guideline is the "escape-hatch" in this set of guidelines.
It
should only be used sparingly and where justified. To use it often
will only result in more code that will need to be rewritten when the
program has to be transported to another machine - and rewriting code
is not a goal.

6.4.2

Data: Addresses and Address Calculations

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 in the interpretation of address values
between BLISS-10 and BLISS-36 are discussed.

6.4.2.1 Addresses and Address Calculations - The value of an undotted
variable name in BLISS is 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.
The term
"address calculation" means any arithmetic operations performed on
address values.
The primary reason for this 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 values have been parameterized and are now
predeclared literals. A table of their values can be found in the
section "Literals."

6-14

TRANSPORTABILITY GUIDELINES
To see how these size differences can have an effect on writing
transportable programs, consider a common type of address expression;
namely an expression that computes an address value from a base
{a
pointer or an address) and an offset. That is, some expression of the
form:
base + index
Now consider the following BLISS assignment expression using this form
of address calculation:
OWN
ELEMENT_2;

ELEMENT_2 = .{INPUT_RECORD + l);
The intent {most likely) was to access the contents of the second
value in the data segment named INPUT RECORD and to place that value
in an area pointed to by ELEMENT 2. The effect, however, is different
on each machine as will be shown:By adding 1 to an address (in this case, INPUT RECORD) the address of
the next addressable unit on the machine- is being computed.
In
BLISS-32 and BLISS-16 this would be the address of the next byte
{8
bits), 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
different sizes of the addressable units and the resultant values.
Based on the above example, follow this guideline:
•

When a complex address calculation is not an intrinsic part of
the algorithm being coded, do not write it outside of a
structure declaration.

There is a way, however, of making such an address calculation
transportable.
It involves the use of the values of the predeclared
literals. In the last example, if the index had been 4 in BLISS-32 or
2 in BLISS-16 then in each case the next word would have been
accessed.
A multiplier that will have a value of 4 in BLISS-32,
2 in BLISS-16
and 1 in BLISS-36 is needed. Such a multiplier already exists as
another predeclared literal. Its definition is %BPVAL/%BPUNIT, and it
is called %UPVAL.
Using this literal in the example yields:
ELEMENT 2 =
.(INPUT_RECORD + 1

* %UPVAL);

The address expression is now tranportable.

6-15

TRANSPORTABILITY GU!oDELINES
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_2;
-

ELEMENT_2

= .INPUT_RECORD[l];

The transportable structure FLEX VECTOR and a more thorough discussion
of structures can be found Tn the section "Structures and Field
Selectors."

6.4.2.2 Relational Operators and Control Expressions - The
previous
example illustrated the use of address values in the context of
computations. Other common uses of addresses are in comparisons
(for
example~
testing for equality)
and as indices in loop and select
expressions. The use of address values in these contexts points to
another set of differences found among the three machines.
In BLISS-32 and BLISS-16, addresses occupy a full word (%BPADDR equals
%BPVAL)
and unsigned integer comparisons must be performed. However,
in BLISS-36, addresses are smaller than the machine word (18 versus 36
bits)
and signed integer operations are performed for efficiency
reasons.
It can be seen that to perform a simple
values:
ADDRESS l

relational

test

address

LSS ADDRESS 2 •••

requires two different interpretations.
This
expression
would
evaluate correctly on the 10/20 systems.
But, on VAX-11 and 11
machines, the following would have had to have been coded for the
comparison to have been made correctly:
••• ADDRESS 1 LSSU ADDRESS 2 •• ~
Another type of relational operator, designed specifically for address
values,
is needed.
Such operators exist and are referred to as
address-relational-operators. BLISS-36, BLISS-16, and BLISS-32 have a
full set
(for example, LSSA, EQLA, and so on) which support address
comparisons.
In BLISS-16 and BLISS-32, the address-relationals are equivalent to
the unsigned-relationals.
In BLISS-36, 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

6-16

TRANSPORTABILITY GUIDELINES
address comparisons to be performed correctly across architectures.
In addition,
there are address forms of the SELECT
{SELECTA),
SELECTONE
{SELECTONEA),
!NCR {INCRA)
and DECR
{DECRA)
control
expressions.
The following guidelines establish a usage for these
operators and contol expressions:
•

If address values are to be compared, use the address form
the relational operators.

•

If an address is used as an index in a SELECT, SELECTONE, !NCR
or DECR expression, use the address form of these control
expressions.

A violation of either
results.

these

guidelines

can

have

unpredictable

6.4.2.3 BLISS-10 Addresses Versus BLISS-36 Addresses - There
is
a
fundamental conceptual change from BLISS-10 to BLISS-36 in the defined
value of a name.
BLISS-10 defines the value of a data segment name to
be a byte pointer consisting of the address value in the low half of a
word, and position and size values of 0 and 36 in the high half of the
word.
BLISS-36, however, defines the value as simply the address in
the low half and zeros in the high half. This change was made solely
for
reasons of transportability,
since it allows BLISS to assign
uniform semantics to an address.
The fetch and assignment operators are redefined
address part of a value.
Thus the expressions:

.X;

F(.Y) + 2;

use

only

the

are the same in both BLISS-10 and BLISS-36, but
y = X;
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
operands to the fetch and assignment operators, instead of as value
producing operators applied to a name.
Thus the meaning of:
Y<0,18> = .X<3,7>;
is unchanged, but
Y = X<3,7>;
is invalid. Moreover, it is highly recommended that field selectors
never appear outside of a structure declaration, since position and
A more thorough
size are apt to be highly machine dependent.
discussion
can be found
in the section "Structures and Field
Selectors."

6-17

TRANSPORTABILITY GUIDELINES'
6.4.3

Data: Character Sequences

This section will discuss the use of character sequences (strings}
in
BLISS programs. Historically, there has been no consistent method for
transportably dealing with strings and the functions operating· upon
them.
Ad hoc string functions have been the rule, having been
implemented by individuals or projects to suit their particular needs.
This section will begin by looking at quoted strings in two different
contexts. Transportability problems associated with quoted string,
and guidelines for their use will be discussed.
Quoted strings are used in two different contexts:
•

as values (integers} and

•

as character strings

6.4.3.1 Quoted Strings Used as Numeric Values - 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_l;

To hold a literal

CHAR_l = 'ONE';
A natural interpretation for BLISS-32 to use is that one longword
would be allocated and the three characters would be assigned to
increasing byte addresses within the longword.
In memory, the value
of CHAR 1 would have the following representation:
CHAR 1:

00 E N 0 /

(32)

BLISS-16 would not allow this assignment because only two ASCII
characters are allowed per string literal. This restriction arises
from the fact that BLISS-16 works with a maximum of 16-bit values and
three 8-bit ASCII characters require 24 bits.
On 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 1:

/ 0 N E 00 00 0 /

(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 value
in BLISS-36, and the value 4276803 in BLISS-32.

-33543847936

Based on these problems with representation our first guideline is:
•

Do not use string literals as numeric values.

6-18

TRANSPORTABILITY GUIDELINES
In those cases where it is necessary to perform a numeric operation
(for example, a comparison) with a character as an argument, you must
use the %C form of numeric 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'

= %X'42' = 66

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

6.4.3.2 Quoted Strings Used as Character Strings - The necessity of
using more than one character in a literal leads 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 handling package has been constructed
as part of the BLISS language. It has been implemented in BLISS-32,
BLISS-36, and BLISS-16.
These built-in functions provide a very complete and powerful
operations on characters. The next guideline is:
•

set

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

A more detailed description of these functions can be found in the
"Character Handling Functions" chapter of the BLISS Language Guide.

6.4.4

PLITs and Initialization

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 in 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.

6.4.4.1 PLITs in General - Because BLISS values are a maximum of a
machine word in length, 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
constants longer than one word. PLITs are often used to initialize
data segments (for example, tables)
and are used to define the
arguments for routine calls.
PLITs themselves are
elements
and
their
transportable.

transportable;
however,
machine
representation

6-19

their
are

constituent
not
always

TRANSPORTABILITY GUIDELINES
A PLIT consi~ts 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.

6.4.4.2 Scalar PLIT Items - The first transportability problem that
might be encountered with the use of PLITs is in the specification of
scalar PLIT items. As with any other declaration of scalar items
(pointers, integers, addresses, and so on) it is possible to define
them with an allocation-unit attribute.
For example, in BLISS-32,
machine-specific sizes as BYTE and LONG can be specified. Thus the
following example is nontransportable and, in fact, will not compile
on BLISS-36 or BLISS-16:
BIND
Ql

= PLIT BYTE(l, 2, 3, LONG (-4));

This last example provides the first PLIT guideline:
•

Do not use allocation units in the specification of a PLIT
PLIT item.

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

PLIT{l, 2, 3, -4);

This last guideline is necessary because of the differences in the
sizes of words on the three machines, a feature of the architectures.
A discussion of the role
of
machine
architectures
in
the
transportability of data can be found in the section "Data." Further
guidelines are presented in the section "Initializing Packed Data."

6.4.4.3 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
representation can be found in the section
"Data:
Character
Sequences""
Care must be exercised when strings are to be used as items in PLITs.
For example, it may be necessary to specify a PLIT that consists of
two elements: a 5-character string and an address of a routine.
If
it is specified as:

CONABC:

I D c B AI

(32)

I address I

(32)

6-20

TRANSPORTABILITY GUIDELINES
on the 11, it is:
CONABC:

I B A I

(16)

I D c I

(16)

( 16)

I address

I (16)

and the 10/20 representation is:
CONABC:

I A B C D E I
I address

(36)

I (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.
There is a
problem if the second element of this PLIT is to be accessed by the
use of an address offset.
For example, the second element
(the
address) is accessed by the expression:
CONABC + 1
in the BLISS-36 version, but not in the BLISS-32 or BLISS-16 versions.
For the BLISS-32 version, the access expression is:
CONABC + 8
and for BLISS-16, it would have to be:
CONABC + 6
Taking a data segment's base address and adding to it an offset (as in
this
case)
is
particularly sensitive to transportability.
A
discussion on the use of addresses can be found in the section "Data:
Addresses and Address Calculations."
This section on addresses suggests the use of the literal, %UPVAL, to
ensure some degree of transportability. Its value is the number of
addressable units per BLISS value or machine word.
As already
discussed,
in BLISS-32, the literal equals 4;
in BLISS-16, it is 2;
and in BLISS-36, its value is 1.
Multiplying an offset by this value can, in some cases, ensure an
address calculation that will be transportable. So to access the
second element in the above PLIT, one would write:
CONABC + 1*%UPVAL
But this will not work for the VAX-11 representation. An offset value
of 8 is needed because the string occupies two 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.
The problem with this particular example
(and,
in general, with
strings in PLITs)
is not in the use of a string literal but in its
position within the PLIT.
Because the number of characters that will
fit in a BLISS value differs on all three machines, the placement of a
string in a PLIT will very often result in different displacements for
the remaining PLIT items.

6-21

TRANSPORTABILITY GUIDELINES
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.

literal,

Following this guideline, the example should have been coded:
BIND
CONABC = PLIT(ABC_ROUT, 'ABCDE');
and this expression:
CONABC + 1*%UPVAL
would have resulted in the address of the second element in
(in this case the string).

the

PLIT

6.4.4.4 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 is 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 length,
5-character field.
For example,
information:

345

201

line

the

table

would

contain

the

following

SMITH

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

conform

this

(345, 201, 'SMITH')
Notice that no allocation units were specified and that the character
string was specified last. This line will now be used 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[l,3]
INITIAL(
345,
201,
'SMITH'
) i

6-22

TRANSPORTABILITY GUIDELINES
However, a problem has developed. This definition would work well in
BLISS-36.
That is, 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.
However, the declaration would be incorrect in BLISS-32 or BLISS-16,
simply because not enough storage would have been allocated for all
the initial values. BLISS-32 would have required four longwords, and
BLISS-16, five words.
The problem arises as a result of the way in which strings are
represented and allocated on the three machines. The solution is
simple. We only need to determine the number of BLISS values that
will be needed for the character string on each machine. There is a
function that will give this value. It is named CH$ALLOCATION and it
is part of the character handling 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
value as an allocation actual in the table definition, as follows:
OWN
TABLE:

BLOCKVECTOR[l,2 + CH$ALLOCATION(5)]
INITIAL(
345,
201,
'SMITH'
);

The declaration is now transportable.
By using the CH$ALLOCATION
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 lines to the table and not be concerned with
the representation or allocation of the data~
Here is a l~rger
example of the same kind of table. We will not develop it step by
step, but point out and explain some of the highlights •

...
!+

Table Parameters
I-

LITERAL
NO EMPLOYEES = 2,
EMP NAME SIZE = 25,
EMP-REC SIZE = 2 +
-CH$ALLOCATION(EMP_NAME_SIZE);
!+

Employee Name Padding Macro
!-

MACRO
NAME PAD(NAME) =
%EXACTSTRING (EMP_NAME_SIZE, 0, NAME)%;
!+

Employee Information Table
Size: NO EMPLOYEES

* EMP REC SIZE

6-23

TRANSPORTABILITY GUIDELINES
.OWN.
EMP TABLE:
-BLOCKVECTOR[NO EMPLOYEES,. EMP_REC_SIZE]
INITIAL (
345,
201,
NAME_PAD('SMITH PETER'),
207,
345,
NAME_PAD('JONES PENNY')
);

The literals serve to parameterize certain values that are subject to
change. The literal EMP REC SIZE has as its value the number of words
needed for a table entry~
The
character
sequence
function,
CH$ALLOCATION, returns the number of words needed for EMP NAME SIZE
characters.
The macro will, based on the length of the employee name argument
(NAME), generate zero-filled words to pad out the name field.
Thus,
we are assured of the same number of words being initialized for each
employee name, no matter what its size might be. This is important
because storage is allocated according to the fixed length of a
character field
(employee name).
The actual string length may, of
course, be less than that value.
This last example was developed with the specification that the
empl·oyee name field was fixed in length (EMP NAME SIZE). What if,
however, we wished to have the table hold variable length names? That
is, for certain reasons, we wished to allocate only enough storage to
hold the table data, not the maximum amount.
The table structure developed above won't work because it
is
predicated upon the constant size of the name field.
If we were to
use variable length character strings, either too much or not enough
storage would be allocated. And there would be no consistent way of
accessing the employee name (where would the next one start?).
We
could, if we knew the length of every employee name, determine in
advance the number of words needed. But this is not a very practical
solution.
One transportable solution is to remove the character string from the
table and replace it with a pointer 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 argument to the functions in the character package.
The cost of
this technique is the addition of an extra word (the character
sequence pointer) for each table entry. The length of the name may
also be stored in the table. Here is a typical example, again based
on the employee table:

Table Parameters
!-

6-24

TRANSPORTABILITY GUIDELINES
LITERAL
NO EMPLOYEES = 2,
EMP REC SIZE = 4;

!+
Macro to construct a CS-pointer to employee name
!-

MACRO
NAME PTR(NAME) =
CH$PTR(UPLIT( NAME)), %CHARCOUNT (NAME) %;

!+
Employee Information Table
Size: NO EMPLOYEES * EMP REC SIZE
!-

OWN
EMP TABLE:
-BLOCKVECTOR[NO EMPLOYEES, EMP_REC_SIZE]
INITIAL(
345,
201,
NAME_PTR('SMITH PETER'),
207,
345,
NAME_PTR('JONES PENNY')
) ;

6.4.4.5 Initializing Packed Data - In this section we will discuss
some transportability considerations involved in the initialization of
packed data. By packed data, we 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 the PLIT item would be represented
by the following expression:

where
max (pl, p2,

••• , pn)

sl + s2 +

< %BPVAL

+ sn < %BPVAL

and for all i
-2**si

<vi~

2**(si - 1)

The OR operator could be replaced by 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.

6-25

TRANSPORTABILITY GUIDELINES
The following is an illustration of the initialization of packed data
obtained by modifying the employee table example that was developed
above. When a field within a block is accessed,
it is a common
practice to associate each field reference (that is, offset, position
and size) with a field name. So, for example, the field names for the
original employee table would look like:
FIELD EMP =
SET
EMP ID= [O,O,%BPVAL,O],
EMP-COST CEN
[l,O,%BPVAL,O],
EMP-NAME-PTR = [2,0,%BPVAL,O];
TES;
These field names can be used in developing an initialization macro,
by
using
parameiric values.
This is another example of how
writing
parameterization can be used as a key
technique
in
transportable code.
If the number of bits needed to represent the values of EMP ID and
EMP COST CEN were each known not to exceed 16, we could pack these two
fields into one BLISS value in BLISS-32 and BLISS-36.
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.
In BLISS-36, an
18-bit size for these two fields would be chosen, since we know that
both DECsystem-10 and DECSYSTEM-20 hardware have instructions that
operate efficiently on halfwords.
If the interest is only in transporting
field declaration would look like:

BLISS-36

and

BLISS-32,

the

FIELD EMP =
SET
EMP ID= [O,O,%BPVAL/2,0],
EMP-COST CEN = [O,%BPVAL/2,%BPVAL/2,0],
EMP-NAME-PTR = [l,O,%BPVAL,O];
TES;
Based on these declarations, a macro can be designed that will take as
arguments the initial values and then do the proper packing:
MACRO
EMP INITIAL(ID,CC,NAME) [] =
-IDA%FIELDEXPAND(EMP ID,2) OR
CCA%FIELDEXPAND(EMP-COST CEN,2) ,
NAME_PTR ( NAMEA%FIELDEXPAND(EMP_NAME_PTR, 2)) %;
The lexical function %FIELDEXPAND simply extracts the
position
parameter of the field name. The initialization macro, EMP INITIAL,
makes use of this shift value in packing the words. The goal here is
to require the user to specify as arguments only the information
needed to initialize the table, and not to specify information that is
part of its representation.
An example of using these macros to
initialize packed data follows:
!+

Employee Field Reference macros
!-

6-26

TRANSPORTABILITY GUIDELINES
FIELD EMP =
SET
EMP ID = [O,O,%BPVAL/2,0],
EMP-COST CEN = [O,%BPVAL/2,%BPVAL/2,0],
EMP-NAME-PTR = [l10,%BPVAL,O];
TES;
MACRO
!+

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

SHIFT(X)

= %FIELDEXPAND(X,2) %,

!+
Employee table initializing macro
Three values are required
!-

EMP INITIAL(ID,CC,NAME)[] =
IDASHIFT(EMP ID) OR
CCASHIFT(EMP=COST_CEN), ! First value
NAMEASHIFT(EMP_NAME_PTR) %; ! Second value

!+
Employee table definition and initialization
!-

OWN
EMP TABLE:
-BLOCKVECTOR[NO EMPLOYEES, EMP_LINE_SIZE]
INITIAL( EMP INITIAL(
345,201,
'SMITH PETER',
207,
345,
'JONES PENNY'
) );

What has been illustrated in
the
previous
example
is
the
parameterization
of
certain
values such as field sizes.
In
transporting this program, benefits can be
derived
from
the
localization of certain machine values as in the field definitions.
This code is transportable between BLISS-32 and BLISS-36. To compile
this program with the BLISS-16 compiler, a change to the field
definitions is needed. The packing macros would no longer be needed,
though they could be used for consistency purposes. In that case,
they would also need to be changed.
As a final example of initializing packed data, consider the DCB (data
control block) BLOCK structure.
(Details as to what DCB is and how it
accesses data are discussed under "FIELD Declarations" and "BLOCK
Structures" in the BLISS Language Guide. Here, we are concerned only
with initializing this type of structure.)

6-27

TRANSPORTABILITY GUIDELINES
The DCB BLOCK consists of five fields.
Four 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 case it is possible to transport the DCB initialization very
easily between BLISS-32 and BLISS-36.
The reason is that the total
number of bits required for each word does not exceed the value 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. One method of
doing this is by placing its definition in a REQUIRE file. We prefer,
however,
to again use the technique of parameterization. We will
again make use of the field reference macros as we did in the previous
example.
The next page contains the example describing a method in which it
could be initialized.
Making it a BLOCKVECTOR has extended the
structure. Note that this structure could be transported to BLISS-16
by making suitable changes to the field definitions and the packing
macro.
The only consideration might be whether the last field, DCB_E,
did require a full 32 bits.

!+
DCB size parameters
!-

LITERAL

DCB NO BLOCKS = total number of blocks,
DCB-SIZE = size of a block;

!+
DCB Field Reference macros
!-

FIELD DCB =
SET
DCB A
DCB-B =
DCB-C
DCB-D =
DCB-E =
TES7
MACRO

[0,0,8,0]'
[0,8,3,0]'
[0,11,5,0]'
[O,%BPVAL/2,%BPVAL/2,0],
(1, 0, %BPVAL, 0];

!+
! Macro to create the shift value from the
1 position parameter of a field reference macro
!-

SHIFT{X) = %FIELDEXPAND{X, 2) %,

!+
! DCB initializing macro.
!
Five values are required.
!-

6-28

TRANSPORTABILITY GUIDELINES
DCB INITIALIZE(A,B,C,D,E) [] =
AASHIFT(DCB A) OR
BASHIFT(DCB-B) OR
CASHIFT(DCB-C) OR
DASHIFT(DCB=D) '
EASHIFT(DCB_E) %;

first word
second word

!+
DCB Blockvector definition and initialization
!-

OWN
DCB AREA:
-BLOCKVECTOR[DCB NO BLOCKS, DCB_SIZE]
INITIAL(
DCB INITIALIZE
1,2;3,4,
first word
5,
second word
6 , 7, 8 , 9,
10,

6.4.5

f i rs t word
second word

Structures and Field Selectors

Two BLISS constructs will be discussed in 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 usage 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 is 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. At this point field selectors will be discussed.
Finally, a more general structure, GEN_VECTOR, will be developed.

6.4.5.1 Structures - Structure
declarations
are
sensitive
to
transportability in that one can 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 O respectively when used as structure actual
parameters.
The ability to specify architecture-dependent information can be an
advantage in developing transportable structure declarations.
Later
in this section, a structure will be developed which will use the UNIT
parameter to gain a degree of transportability. The UNIT parameter
specifies the number of addressable allocation units in one element of
a homogeneous structure. This number will be used in determining the
amount of storage that is to be allocated for each element of the
structure.

6-29

TRANSPORTABILITY GUIDELINES
As
mentioned
repeatedly
in
these
guidelines,
the
prime
transportability problem is differing machirie architectures. The key
to dealing with these differences is the parameterization by the size
of the machine word
(%BPVAL)
the number of bits needed to hold an
address (%BPADDR) and the number of bits occupied by the smallest
addressable unit (%BPUNIT).

6.4.5.2 FLEX VECTOR - An application of this is illustrated
by
developing FLEX VECTOR, a structure that will, by default, allocate
and access a vector consisting of only the smallest addressable units.
If the default value given in the structure declaration is not used,
the vector element size will be specified in terms of the number of
bits. The existing VECTOR mechanism will not do this.
An example of its use would be to create a vector of 9-bit elements.
The first decision that has to be made in its design is whether or not
each element is to be exactly nine bits, or at least nine bits.
For
this example, we chose the smallest natural unit whose size is greater
than or equal to nine bits. Since there are no 9-bit conveniently
addressable units on any of the machines, we have a choice of 8-, 16-,
32-, or 36-bit units.
We can see that 9 bits will fit in the only addressable unit on the
10/20 systems
the word.
On the 11 we will need two bytes or a
16-bit word and on the VAX-11 we will again need two bytes.
How then can a structure be developed 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.
The predeclared literals have all the information we need.
In
only one set of values is needed:
bits per addressable
{%BPUNIT) •

fact
unit

The minimum necessary size of a vector element will be one of the
allocation formals {UNIT). Other formals that will be needed are the
number of elements {N), the index parameter
{I)
for accessing the
vector, and an indication of whether or not the leftmost bit of an
element is to be interpreted as a sign bit {EXT).
The access and allocation formal list for FLEX VECTOR is:
STRUCTURE
FLEX_VECTOR[ I;

N, UNIT = %BPUNIT, EXT

=1 ] =

Notice that by setting UNIT equal to %BPUNIT the default {if
not specified) will be %BPUNIT.

UNIT

The next step is to develop the formula for the structure-size
expression.
The expression will make use of the allocation formals
UNIT and N, and in addition, the value of %BPUNIT.
If UNIT were allowed to assume only values of integer multiples of
%BPUNIT
{that
is,
1*%BPUNIT,
2*%BPUNIT, and so on), only a
structure-size expression of the following form would be needed:
[ N * (UNIT) I %BPUNIT ]

6-30

TRANSPORTABILITY GUIDELINES
Dividing the element size (UNIT) by %BPUNIT would give the size of
each element in the vector in terms of an integer multiple. This
value would then be multiplied by the number of elements to give the
total size of the data to be allocated.
Suppose the structure needs to be more flexible in that it should be
possible to specify any size element (within certain limits). The
structure size must be slightly more complex:
[ N * ((UNIT+ %BPUNIT - 1)) I %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 howthls expression evaluates.
This subexpression:
(UNIT + %BPUNrT - 1) / %BPUNIT
that we will call NO OF UNITS is very important in effecting the
transportability and flexibility of this particular structure. The
key to transporting this structure is the knowledge that it has of the
value
of a certain machine architectural parameter:
bits per
addressable unit~
This particular expression makes use of this
knowledge;
hence, it can adapt to any machine. This subexpression
will be used twice more in the structure-body expression.
The structure body is an address expression. This expression consists
of the name of the structure (the base address) plus an offset based
on the index I.
In additiorir a field s~lector is needed to access the
proper number of bits at the calculated address.
The offset is simply the expression NO OF UNITS multiplied by the
index I.
(Remember that indices start-at-0). The size parameter of
the field selector is the expression NO OF UNITS multiplied by the
size of an addressable unit, %BPUNIT. The structure body will look
like:
(FLEX VECTOR +
I-* ((UNIT+ %BPUNIT -·1} I %BPUNIT))
<O, ((UNIT + %BPUNIT - l) /%BPUNIT) *%BPUNIT, EXT>;
The value of the position parameter in the field selector
constant 0 since it always starts at an addressable boundary.
The following table shows the structure
different values of UNIT:

the

three

machines

VAX-11
UNIT = 0

no storage
FLEX_VECTOR<O,O,l>

UNIT = 1 to 8

[N * l] Bytes
(FLEX_VECTOR + I)<0,8,1>

UNIT = 9 to 16

[N * 2] Bytes

(FLEX_VECTOR + I * 2)<0,16,1>
UNIT

17 to 32

[N * 4] Bytes
(FLEX_VECTOR + I * 4)<0,32,l>

6-:-31

a
for

TRANSPORTABILITY GUIDELINES
11

UNIT

0 to 16

same as VAX-11 . ·

10/20
UNIT = 0

no storage
(FLEX_VECTOR)<010,l>

UNIT = 1 to 36

[ N ] Words
(FLEX_VECTOR + I)<0,36,1>

The above table illustrates that if the default value for UNIT were
set to %BPVAL, this structure would be equivalent to a VECTOR of
longwords on VAX-11, and a VECTOR of words on the 10/20 and 11
systems.
Elements in a data segment that 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.
If this structure were to access elements of exactly the size
specified, then only change needed would be the size parameter of the
field selector. This expression then becomes:
FLEX_VECTOR<O, UNIT>;
This is a less efficient means of accessing data (when UNIT is not a
multiple of %BPUNIT)
because the compiler needs to generate field
selecting instructions in the case of the VAX-11 and 10/20 machines
and a series of masks and shifts for the 11.

6.4.~.3
Field Selectors - In the last structure declaration, it was
necessary to make use of a field selector. Now, the use of field
selectors in a more general context will be discussed.

The use of field selectors can be nontransportable 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 + s

< 36
0 < s < 36

0 < p
p + s < 16
0 < s
16

VAX-11

0 < s

< 32

From the table we can see that:
•

The most restrictive is the 11.

•

The moderate restrictions are those of the 10/20.

•

The least restrictive is VAX-11.

6-32

TRANSPORTABILITY GUIDELINES
In order to ensure the transportable use of field selectors, we would
have to abide by the set of restrictions imposed in BLISS-16. These
are restrictions imposed by the values of p and s. There is also a
contextual restriction on the use of field selectors. The following
guideline should be followed:
•

Field selectors can appear
user-defined structures.

only

the

definition

Restricting the domain of field selectors to structures isolates their
use.
Field selectors should be isolated so that:
•

Changes in data structure design are easier.

•

Machine dependencies can easily be placed in REQUIRE files.

•

Complex coding making heavy use of the predeclared literals is
limited to declarations.

Another transportable structure will be developed and will be affected
by the table of field selector value restrictions.

6.4.5.4 GEN VECTOR - Notice that FLEX VECTOR does not attempt to pack
data.
Using the example of 9-bit elements, it is evident that there
will be some wasting of bits - from seven bits on the 11 and VAX-11 to
27 on the 10/20 systems.
A variation of FLEX VECTOR can be developed to provide a certain
degree of packing:
For example, in the case of 9-bit elements it
would be possible to pack at least four of them into a 10/20 word and
three into a VAX-11 longword.
This structure, which will be named GEN VECTOR, will pack as many
elements as possible into a BLISS value and so will make use of the
machine-specific literal %BPVAL.
However, since allocation is in
terms of %BPUNIT, a literal will be needed that has as a value the
number of allocation units in a BLISS value. This literal has been
predeclared for transportability reasons and has the name %UPVAL, and
is defined as %BPVAL/%BPUNIT.
Elements will not cross word boundaries. This constraint is because
of the restrictions placed on the value of the position parameter of a
10/20 and 11 field selector. For the same reason elements cannot be
longer
than %BPVAL, as given in the table of field selector
restrictions above.
As in FLEX VECTOR, the allocation expression of GEN VECTOR will need
to calculate the number of allocation units needed by the entire
vector. This will again be based on the number of elements
(N)
and
the size of each element
(S).
But because the elements will be
packed, the expression will be slightly more complicated.
The first value is the number of elements that will
value. The expression:
(%BPVAL/S)

6-33

fit

BLISS

TRANSPORTABILITY GUIDELINES
will compute this value. Given this, to obtain the number of BLISS
values or words needed for the entire vector, divide this value into
N:
(N/(%BPVAL/S))
This is the total number of values needed.
However, data are not
allocated by words on both of the machines. Multiplying this value by
%UPVAL 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 again,
will be expressed as a macro with N and S as parameters:
MACRO
WHOLE_VAL(N,S)

((N/(%BPVAL/S))*%UPVAL)%;
The name of the macro suggests that it calculates the number of whole
words needed.
If, 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 this is not known in advance,· another expression to calculate
the number of allocation units needed for any remaining elements is
needed. The number of elements left over is the remainder of the last
division in this expression:
(N/ (%BPVAL/S))
The MOD function will calculate this value, as follows:
(N MOD (%BPVAL/S))
Multiplying this value by the size of each element
number of bits that remain to be allocated:

gives

the

total

(N MOD (%BPVAL/S)) * S
This value will always be strictly less than %BPVAL.
For the same
reasons outlined above this expression will be expressed as a macro
with N and S as parameters:
MACRO
PART_VAL(N,S)

((N MOD (%BPVAL/S)) * S)%;
PART VAL computes the number of bits allocated in the
word:-

last

(partial)

Taking this value, adding a "fudge factor~ and then dividing by
%BPUNIT gives us the number of allocation units needed for the
remaining bits:
(PART_VAL(N,S) + %BPUNIT -l)/%BPUNIT

6-34

TRANSPORTABILITY GUIDELINES
The total number of allocation units
structure allocation expression is:

has

been ·calculated

and

the

[WHOLE VAL(N,S} +
(PART_VAL{N,S) + %BPUNIT - l)/%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 an address
offset be computed which is then added to the name of the structure.
This offset is some number of addressable units and is a function of
the value of the index I. The expression which will calculate this
number of addressable units is the macro WHOLE VAL. Thus, the first
part of the accessing expression is:
GEN_VECTOR + WHOLE_VAL(I,S}
Note that the macro was called with the index parameter I.
This expression will result in the structure being aligned on some
addressable boundary.
But since the element may not begin at this
point (that is, the element may be located somewhere within a unit
%BPVAL bits in length}, one more value is needed. That value is the
position parameter of a field selector.
The macro PART VAL will
calculate this value based on the index I:
<PART_VAL(I,S},S,EXT>
The size parameter is the value s. The position parameter
calculated at runtime, based on the value of the index I.
This completes the definition of GEN VECTOR.
is:

The

entire

will

declaration

STRUCTURE
GEN_VECTOR[I;N,S,EXT=l] =
[WHOLE VAL(N,S} +
(PART_VAL(N,S) + %BPUNIT - l}/%BPUNIT]
(GEN_VECTOR + WHOLE_VAL(I,S}}
<PART_VAL(I,S),S,EXT>;
The reader should compile this structure
BLISS-16, BLISS-32, and BLISS-36.

and

see

how

works

6.4.S.S Summary - No claim is made that either of
these
two
structures will solve all the problems associated with transporting
vectors.
Many such problems will have interesting and
unique
solutions.
BLOCKS or BLOCKVECTORS have not been discussed, but it is
hoped that the reader will get from the examples a feeling for the
techniques involved in transporting structures.
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.

6-35

TRANSPORTABILITY. GUIDELINES
This exercise .in the development
illustrated two points:
•

parameterization and

•

field selector usage.

transportable

structures

has

By parameterizing certain machine~specific values and by taking full
advantage of the powerful STRUCTURE mechanism, two transportable
structures have been developed.
The accessing of odd (not addressable) units of data is accomplished
by the use of field selectors. The field selector should be used only
in structure declarations.

6-36

CHAPTER 7
COMPILER OVERVIEW AND OPTIMIZATION SWITCHES

This chapter provides an overview of the BLISS compiler organization
and processing.
The material presented here assumes that the reader
has a general understanding of compiler theory and practice. It need
not be understood for normal use of the BLISS language and compiler.
Some of the switches described in
connection
with
"SWITCHES
declaration" in the BLISS Langua~e Guide provide specialized control
over the processing of the compiler, especially in the area of
optimization.
This section provides the basis for a more detailed
understanding of these switches. The switches that are described are:
CODE and NOCODE
OPTIMIZE and NOOPTIMIZE
OPTLEVEL
SAFE and NOSAFE
ZIP and NOZIP
Table 1-1 shows command qualifier relationships to these switches.

7.1

COMPILER PHASES

The compiler is organized conceptually into seven major phases:
LEXSYN
FLOW
DELAY
TNBIND
CODE
FINAL
OUTPUT

Lexical and syntactic analysis
Flow analysis
Heuristics
Temporary name binding (register allocation)
Code generation
Code stream optimization
Object and listing file production

This division of the compiler into conceptual phases corresponds only
approximately to the actual compiler. In some cases, a phase actually
consists of two or more subphases.
In other cases, phases are
combined in the implementation. This level of detail is not important
in the following discussion of the phases. The term "phase" should
not be taken literally.

7-1

COMPILER OVERVIEW AND OPTIMIZATION SWITCHES
7.1.1

Lexical and Syntactic Analysis

The lexical
functions:

and

syntactic

phase,

LEXSYN,

performs

the

following

•

Reads the input files

•

Divides the source character text into lexemes

•

Identifies and performs lexical functions and macro expansions

•

Parses the resulting
input lexeme sequence and
creates
appropriate symbol table entries for declarations and tree
representations for expressions

The BLISS compiler reads the source text once and uses it to create an
internal representation of the module.
In this sense, the BLISS
compiler is a one-pass compiler. On the other hand, at the end of
each
(ordinary or global) routine definition, the remaining phases of
the compiler are performed in turn to analyze and completely produce
and output code for that entire routine.
In this sense, the BLISS
compiler is a multi-pass compiler.
If the NOCODE switch is specified, the compiler operates in a
"syntax-only" mode,
in which the LEXSYN phase does not produce the
tree representations for expressions and the later ~hases are not
performed.
If an error (as contrasted with a warning) is detected and
reported by the compiler,
the
compiler
automatically
enters
syntax-only mode as if NOCODE had been specified.
Syntax-only mode is useful for initial checking of a newly created
module. However, there are two important limitations to such use:
1.

Some errors are detected and reported by later phases of the
compiler.
Since the later phases are not performed in this
mode, some errors will not be detected.

Because the tree representation of expressions is not being
produced, the values of compile-time constant expressions
cannot be determined. The compiler assumes a value of 0 for
any expression that is not a simple literal.
If the correct
parsing of the module depends on the correct values of
constant expressions, spurious error diagnostics can result.
Examples where this might be the case are lexical functions,
conditional compilation, and macro expansion.

The difference between an error and a warning diagnostic is based on
the seriousness of the effect of the. error ·upon the internal
representation of the program used by the compiler.
(It is not a
value judgment upon the nature of the programmer's mistake.)
In most cases, the compiler can recover and proceed
compilation. This permits further errors, if any, to be
in some cases, may permit the resulting object module to
execution time debugging before the source module is
recompiled.
Errors from which the compiler can continue
reported as warning diagnostics.

with normal
detected and,
be used for
corrected and
normally are

In some cases, the effect of a user error is to make the compiler's
internal
representation of the module inconsistent or otherwise
unreliable for continued use.
Such errors are reported as error
diagnostics.

7-2

COMPILER OVERVIEW AND OPTIMIZATION SWITCHES
Depending on the circumstances, the same apparent user error
(same
diagnostic
information)
may be reported as a warning in one case but
as an error in another.

7.1.2

Flow Analysis

the
internal
tree
The flow analysis phase,
FLOW,
examines
representation of a complete routine and performs the following
functions:
Identifies expressions that appear more than once
• source,
but
that will produce the same value

in the
(common
subexpressions) • Such expressions need be evaluated only once
during execution and the result used several times, thereby
saving execution time and code space.

•

Identifies expressions contained in loops whose values will be
the same on each iteration of the loop. Such expressions can
be evaluated once before starting the loop and the result used
during each iteration, thereby saving execution time.

•

Identifies expressions that occur on all alternatives of the
IF, CASE, and SELECTONE expressions. Such expressions may be
evaluated once before or after the multiple alternatives,
thereby saving code space.

More generally, the FLOW phase identifies possible alternative ways of
evaluating a routine, which might be more efficient in time or space
or both. Note that the next phase determines which alternative is
actually used;
the FLOW phase only identifies the possible choices.
If OPTLEVEL is specified with a value of 0 or 1, the flow analysis
phase is totally skipped. A consequence of skipping flow analysis is
that the OPTIMIZE and SAFE switches have no effect, because OPTIMIZE
and SAFE control aspects of how flow analysis is done. However, if
OPTLEVEL is specified with a value of 2 (the default) or 3, the flow
analysis phase is performed and the OPTIMIZE and SAFE switches have
the effects described below.
To understand the effects of the OPTIMIZE and
first necessary to understand more about
performed.

SAFE switches,
it
how flow analysis

is
is

7.1.2.1 Knowing When a Value Changes - One operator in BLISS, the
assignment operator, can change the contents of a data segment.
However, routine calls can also change the contents of data segments
because they can contain assignments.
For each assignment, the compiler examines the left operand expression
and attempts to determine the name of the data segment whose contents
will be changed by the assignment.
(The case where no name can be
determined is considered below.) The same analysis is performed for
each actual parameter that appears in a routine call.
In effect, the
compiler treats each actual parameter as though it did appear as the
left operand of an assignment.
In addition to this, for each routine
call the compiler determines the names of all OWN and GLOBAL data
segments that the called routine might change and assumes that all of
them are changed.

7-3

COMPILER OVERVIEW AND OP,TIMIZATION SWITCHES

Machine-specific functions are treated as normal routine calls, except
that the compiler has more detailed infqrmation about which parameters
can cause changes and which cannot.
Several aspects of this analysis process are illustrated using
examples. In these examples the following declarations are assumed:.
OWN

X: VECTOR[lO],
Y,
Z;

EXTERNAL ROUTINE
F;

First, consider the following sequence of assignments:
I = 3;

Y = .X[.I];
X [ 7]

= • X [. Y] ;

Z = .X[.I]+l;
In the third line, the assignment to X[7] is assumed to change all of
the data segment identified by X. As a consequence, the possible
common subexpression .X[.I] is not recognized by the compiler.
(However, note that the common subexpression X[.I], which computes the
address of the I'th element of X, is recognized since the assignment
to X cannot affect this value.)
In the above example, it may seem apparent exactly what part of X is
changed, but in most cases it is difficult or impossible for the
compiler to determine what part of a named data segment changes and
what part does not change.
Another aspect is illustrated with this example:
X[ll] = 11;
y = • z;

In the first line, the assignment to X[ll] actually modifies the
contents of z.
(Recall that X was declared as a vector of 10 elements
numbered 0 through 9). The compiler analysis does not determine that
storage other than the storage for X is being changed because the
analysis is based completely on the names that occur in
the
expression.
As a consequence, the compiler may inappropriately use
the previous contents of Z in the assignment to Y. This would happen,
for example, if the expression .z were a common subexpression used
frequently enough to result in the contents of Z being copied into a
register for more efficient access.
Both of these examples emphasize the importance of the
reference storage in the analysis performed by FLOW.

name

used

Now consider the case where a name cannot be identified for the
storage being changed. This is the case in the following example:
Z

= F();

• z = 3;

7-4

COMPILER OVERVIEW AND OPTIMIZATION SWITCHES
In the second line, no name of a data segment can be determined.
In
such a case, the compiler assumes (by default) that no named storage
has changed. This assumption is justified because it is always the
case that such indirect assignments are used to change the contents of
•

dynamically created data structures that do not have names, or

•

data segments passed as parameters of routine calls and that
cannot be referenced in the called routine by the name used to
allocate the storage

The NOSAFE value of the /OPTIMIZE qualifier can be used to override
the default assumption described above.
(SAFE is the default).
If
NOSAFE is specified, the compiler assumes that indirect assignments do
change
some named data segment.
Because it is nearly always
impossible to identify the data segment that is changed, this
assumption is guaranteed by making the even stronger assumption that
all named data segments are changed.

7.1.2.2 Accounting for Changes - The
BLISS
language
definition
intentionally leaves unspecified the order of operand evaluation in
operator expressions in order to permit maximum optimization by the
BLISS compiler. For example, the expression
F(X) + .X
can be evaluated first, by calling F with the address X as a
parameter, second, by fetching the contents of X, and finally, by
performing the addition.
It might also be evaluated first, by
fetching
the contents of X,
second, by calling F, and so on. The
compiler uses information about the entire routine in which the
expression is contained to choose alternatives. Since the routine
call F(X) may change the contents of X, the question becomes:
When
does the compiler take the (potential) change into effect? It does
not make sense to take this into account within the expression without
also specifying precisely the order of evaluation.
It makes sense to
account for changes only at points in the language where the order of
evaluation is specified.
Points at which changes are taken into
account are called mark points. Mark points in BLISS are summarized
in the following diagram, where "!" is used to point to the mark point
within the language syntax on the subsequent line.
BEGIN exp

, ... END

IF exp THEN exp ELSE exp
WHILE exp DO exp
DO exp WHILE exp
!NCR name FROM exp TO exp BY exp DO exp
CASE exp FROM ctce TO ctce OF SET [ ••• ]: exp, ••• TES
SELECT exp OF SET [exp TO exp r••• ]: exp; ••• TES

7-5

COMPILER OVERVIEW AND OPTIMIZATION SWITCHES
The most common mark point in most programs is the semicolon, which
separates expressions in a block or compound expression, for example:
BEGIN
Y = .X+2;
Z = .X+2+F(X);
W = .X+2
END
In the second line, the content of Y is changed. This change is taken
into account by the compiler when the semicolon is encountered. In
the third line, .X+2 computes the same value as .X+2 in the second
line;
thus, .X+2 is a common subexpression of the second and third
lines. Also in the third line, the content of Z is changed and the
call F(X)
is considered to change the content of X. As discussed
above, these changes are not taken into account until the semicolon is
encountered.
In the fourth line, .X+2 must be recomputed because of
the change of the content of X in the third line - it is not a common
subexpression with the previous occurrences.
The effect of the OPTIMIZE switch is now easily stated.
If OPTIMIZE
is specified (the default) full flow analysis is performed. If
NOOPTIMIZE is specified, at every mark point all data segments are
assumed to change.
As a consequence, common subexpression values
computed by one expression are not reused in later expressions - the
value is computed again.
Expressions that have a constant value
within a loop are not computed once before the loop is started;
the
value is recomputed during each iteration of the loop. And similarly,
other kinds of "code motion" optimizations are not performed.
However, specifying NOOPTIMIZE is not equivalent to specifying that no
flow analysis is performed, since common subexpressions that occur
between mark points are still detected.
For example, in
the
expression
Y = (.X*2)+F(.X*2)
the subexpression .X*2 is computed once and the resulting
twice, even when NOOPTIMIZE is specified.

7.1.3

value

used

Heuristic Phase

The heuristic phase, DELAY, further analyzes the routine to obtain
general information about the routine. Some of this information is
used by DELAY itself to make optimization decisions, and some is made
available for use by later phases.
DELAY performs the following
functions:
•

Evaluates the effectiveness of the alternatives identified by
FLOW
and
chooses the best alternative.
This analysis
considers, for example, the number of occurrences of a common
subexpression
and
the
potential for using specialized
operations available in the address parts of instructions (for
example, indirection and indexing).

•

Identifies sets of subexpressions that occur only once (that
is, are not common subexpressions) that should be computed in
the same temporary location (whether a register or memory),
thereby maximizing the use of 2-operand (as contrasted with
3-operand) instructions.

None of the switches affect the operation of the DELAY phase.

7-6

COMPILER OVERVIEW AND OPTIMIZATION SWITCHES
7.1.4

Temporary Name Binding

The temporary name binding phase, TNBIND, determines where each value
computed during the execution of a routine should be allocated. This
phase corresponds to what is sometimes called register allocation in
other compilers. It is somewhat more general in that it considers and
allocates user declared local variables together with compiler-needed
temporary locations in an integrated way.
TNBIND performs the following functions:
•

Determines the lifetime (that is, the first and last uses)
each temporary value in the routine.

•

Estimates the difference in compiled code cost of allocating
each temporary value in a register versus in memory (on the
stack) •

•

Uses cost information to rank temporary values to determine
the most important ones to be allocated in a register.

•

Proceeding from most important to least important, allocates
the temporary values.
More than one temporary value may be
allocated in the same location, provided their lifetimes do
not overlap.
(Thus, it is possible for a less important
temporary to be allocated in a register even though a more
important one is not - its shorter lifetime could permit it to
"fit.")

The measure of importance used
(normally)
by TNBIND is
based
completely on minimizing the overall size of the code generated for
the entire routine.
The ZIP switch modifies the importance measure. If ZIP is specified,
temporary values used within loops are given increased importance.
The greater the degree of loop nesting, the greater the importance.
Thus, temporary values used in loops become more likely to be
allocated in registers~ As a consequence, code within loops tends to
execute faster, even though the overall size of the routine can become
larger.

7.1.5

Code Generation

The code generator phase, CODE, processes the tree and generates
instructions. Since the allocation for each operand of a node and the
result location of each node have already been determined by TNBIND,
CODE selects the locally best code sequence consistent with those
requirements.
None of the compilation switches affect
phase.

7-7

the

operation

the

CODE

COMPILEROVERVIEW AND OPTIMIZATION SWITCHES
7.1.6

Code Stream Optimization

The code stream optimization phase, FINAL, processes the code stream
produced by CODE and makes further optimizations at the machine code
level. The optimizations performed include:
•

Peephole optimization.
One sequence of instructions
replaced with an equivalent shorter sequence.

•

Test elimination.
TST instructions used for conditional
branching may be deleted if the condition codes needed by the
branch instruction are appropriately set by the instruction(s)
that precede the TST. ·

•

Jump/Branch resolution. Branch instructions are reduced to
their shortest size consistent with the actual range of the
needed branch displacement.

•

Branch chaining.
If a short branch instruction is not able to
reach the desired location but can reach another branch
instruction that goes to the desired location, a chain of
branches is used to minimize code size.

•

Cross-jumping.
Identical sequences of code that flow
common instruction are merged into a single sequence.

into

The OPTLEVEL switch may be used to eliminate some
of
these
optimizations.
The result is code that more clearly follows the
organization of the source program.
This may be helpful during
debugging or when the generated code must be understood in detail.

7.1.7

Output File Production

The output file production phase, OUTPUT, transforms the code stream
into object module format and outputs it to the object file.
It also
formats and outputs the listing file information.
If the DEBUG switch is specified, symbol table information for use by
the DEBUG system utility is included in the object module.
If NODEBUG
is specified (the default), no symbol table information is produced.

7.2

SUMMARY OF SWITCH EFFECTS

The previous sections have described the phases of the compiler and
the
switches that affect each of those phases.
This section
summarizes the effects of each switch throughout the compiler.
Switch Name

Phase

Effect

CODE

LEXSYN

NOCODE
specifies
syntax-only
processing; the other phases are
not invoked.

OPTIMIZE

FLOW

If flow analysis is performed,
NOOPTIMIZE
specifies
do
not
optimize across mark points.

7-8

COMPILER OVERVIEW AND OPTIMIZATION SWITCHES
Switch Name

Phase

Effect

OPTLEVEL

FLOW

At levels O and 1, flow
is not performed.

FINAL

At levels 0 and 1, cross-jumping
and
branch
chaining are not
performed. At level O, peephole
optimizations
that
are
not
adjacent are not performed.

SAFE

FLOW

If flow analysis is performed,
SAFE
specifies
that indirect
changes are to assume all storage
is changed.

ZIP

TNBIND

ZIP specifies that data segments
used in loops are to be given
increased
importance
in
determining register allocation.

analysis

The OPTLEVEL switch is a composite switch that includes appropriate
settings of the other switches in an ordered way.
It can be specified
in either the command line or module head or both. The rule applied
to determine which switch setting has effect is that the most recent
switch setting specified has effect allowing the other switches (SAFE,
OPTIMIZE, and so on)
to override OPTLEVEL at any time.
In a
compilation of more than one module, each module begins with the
setting defined in the command line and OPTLEVEL=2 if OPTLEVEL has not
been specified in the command line.
Optimizations performed at each setting of the OPTLEVEL switch are:
Optimization
* 1.
* 2.
3.
4.
5.

6.
7.
8.

9.
10.
11.
*12.
*13.
*14.

OPT LEVEL

Common subexpression detection
Code motion out of loops, and so on
Targetting/preferencing to
temporaries
Cross jumping
Multiple RETs (instead of only one
return point)
Peepholes
TSTx elimination
Scans for ()+, -() forms
Scans for PUSHR, and so on
Scans for cheaper form of addressing
Branch chaining
"SAFE" optimizations
"OPTIMIZE" over mark points (for example, ;)
"ZIP" speed/space tradeoff
(faster but possibly larger)

x
x
x
x

x
x
x
x
x
x

Key:
* - Another switch can control this optimization separately
X - Allowable optimization
+ - Allowed
with increased freedom
Allowed -- with certain restrictions

7-9

x
x
x
x
x
x
x
x
x
x
x
x
x

x
x
+

x
x
x
x
x
x
x
x
x
x
x

CHAPTER 8
TOOLS, LIBRARIES, AND SYSTEM INTERFACES

A number of programming tools, libraries, and system interfaces are
available
for use by BLISS programmers.
This chapter briefly
describes what is available for use with BLISS-32 V3. Note that the
BLISS tools
(utility programs) and system interfaces described here
are not supported products at the time of writing.
The residence locations specified for the various BLISS-related
program and information files assume that these files have been
installed on your system in their standard, as-released locations.

8.1

TRANSPORTABLE PROGRAMMING TOOLS (XPORT)

XPORT is a collection of transportable source-level programming tools
for
use with the BLISS langua~e. XPORT tools may be commonly applied
across all BLISS target systems to provide such thing~ as:
extensive
input/output facilities; a uniform interface for obtaining operating
system services
(such as dynamic memory);
and aids
to
data
structuring and string handling.
The XPORT package consists of five components:
XPORT Data Structures
XPORT Input/Output Facilities
XPORT Dynamic Memory Management
XPORT Host System Services
XPORT String Handling Facilities
Each component provides tools which ease the task of interfacing a
BLISS program with the operating system under which it will run.
Therefore, the primary purpose of the XPORT package is to provide
tools and interfaces which behave exactly alike in all system
environments, and thus provide
transportable
operating
system
interfaces.
Programs written in Common BLISS (which use XPORT services in the
manner prescribed) can be developed and debugged on one system and run
on any other BLISS-s~pported system without change.
An additional benefit of using the XPORT package for BLISS programs,
even if they do not require transportability, is the advantage in
using the simplified XPORT interface as opposed to more powerful and
complicated host system inter£aces.
A description of each XPORT component follows; however,
for a more
detailed explanation of XPORT and its services refer to the XPORT
Programmer's Guide.

8-1

TOOLS, LIBRARIES, AND SYSTEM INTERFACES
8.1.1

XPORT Data Structures

The XPORT structure-definition facility is a collection of macros that
allow a programmer to define efficient BLOCK structures in a manner
that is both convenient and primarily system-independent.
The
facility primarily consists of a replacement for the standard BLISS
FIELD declaration, using the keyword $FIELD.
The structure-definition facility allows a programmer to name the kind
of field required for each block component, instead of specifying its
position and size. A field-type
(such as, SHORT INTEGER, ADDRESS,
BYTE)
implies not only the size but also the alignment and required
sign extension mode.
The XPORT data structure facility also provides the following
features:

support

FIELD SET SIZE

calculates the size of
$FIELD.

ALIGN

forces a specified mode of
subsequent field.

OVERLAY

allows for overlayed field definitions.

CONTINUE

terminates field overlaying.

LITERAL/DISTINCT

creates a set of distinct integer literals.

SHOW

controls the display of XPORT generated field
definitions, values, and messages.

SUB FIELD

provides a means of referencin9
within a substructure of a block.

8.1.2

block

defined

alignment

for

field

XPORT Input/Output

XPORT input/output is a general-purpose, system-independent service
that supports sequential I/O operations in record, character stream,
and binary mode, and provides basic file functions.
This facility
actually consists of several separate I/O packages, each being written
for a specific operating system and file system. However, the program
interface to each package is identical. Thus, a transportable I/O
interface is provided for programs written in common BLISS or any
other transportable language.
The XPORT I/O facility
manipulation functions:

performs

the

following

I/O

and

file

OPEN

prepares a file for reading
(input)
or writing
(output). An output file may .be optionally created.

terminates the processing of an input or output
file, including the flushing of any I/O buffers.

DELETE

deletes an existing file.

RENAME

changes the name of an existing file.

8-2

TOOLS,. LIBRARIES, AND SYSTEM INTERFACES
BACKUP

provides a mechanism for preserving a copy of an
input file when a program creates a new version of
that file.
This capability is typically used by
editor-type applications.

PARSE

parses a host system
component parts.

GET

returns the length and address
of
the
next
sequential logical record read from an input file.
Logical concatenation of several input files can be
automatically
performed
when
an
intermediate
end-of-file is reached.

PUT

writes a single logical record into an opened
file.

8.1.3

file

into

its

outpu~

XPORT Dynamic Memory Management

The XPORT dynamic memory management facility
functions:

8.1.4

specification

provides

the

following

GET MEM

allocates a specified amount of dynamic memory.

FREE MEM

releases an allocated element of dynamic memory

XPORT Host System Services

The XPORT host system services are a set of routines that perform
commonly needed host system functions in a transportable manner. The
functions provided are as follows:

8.1.S

PUT ·MSG

routes a message sequence to the standard output
and/or error devices, based on a message severity
code.

TERMINATE

terminates program execution after sending the
a termination message.

user

XPORT String Handling Facilities

The XPORT string handling facility provides a programmer with the
ability to transportably manipulate character strings. Small control
structures {modeled after the VAX/VMS descriptor convention) are used
to facilitate the exchange of character data between procedures.
The following descriptor classes are provided:
FIXED

describes a string with a
location.

BOUNDED

describes a buffer that contains
length string.

DYNAMIC

describes a moveable string, the
which is subject to variance.

length

DYNAMIC BOUNDED

describes a moveable buffer that
variable length string.

contains

8-3

fixed

length
a

and

variable

TOOLS, LIBRARIES 1 AN.D SYSTEM INTERFACES
The following functions· are used to manipulate a
associated string:

descriptor

and

its

DESCRIPTOR

creates and initializes a descriptor in OWN
storage, or creates a descriptor in LOCAL
storage.

DESC INIT

dynamically initializes a descriptor
or LOCAL storage.

COPY

copies a source string to a target string
with appropriate truncation and padding.

APPEND

appends a source string to a target string.

EQL,NEQ,LSS,
LEQ,GEQ,GTR

compares the values of two strings according
to the ASCII collating sequence.

SCAN

locates a specific sequence of characters
(FIND mode), matches a stream of characters
(SPAN mode) , or searches for one character of
a set (STOP mode) •

CONCAT

concatenates two or more strings as a
logical string.

FORMAT

centers, left justifies, right justifies,
converts a string to upper case.

ASCII

produces an ASCII string representation of
binary field value.

BINARY

converts an ASCII string value
value.

OWN

single

binary

The XPORT string handling facility also extends the descriptor concept
to include binary data; whereby, the four descriptor classes (FIXED,
BOUNDED, DYNAMIC, and DYNAMIC BOUNDED) are used to describe a data
item instead of a string,-while two of the descriptor manipulation
functions (DESCRIPTOR, DESC !NIT) are used to create and intitialize
the binary data descriptors~

8.2

BLISS CROSS REFERENCES (BLSCRF)

The utility program BLSCRF cross-references BLISS source files and
provides a means of merging the cross-references of multiple files.

8.2.1

Command Line Format

BLSCRF is invoked by defining the string-symbol:
BLSCRF:==$BLSCRF
BLSCRF in-spec{/OUTPUT:outspec}{/MERGE:merge-spec}{qualifier ••• }
Wildcards are permitted in the directory, file name, file type, and
file version fields.
A comma-list is not accepted by the current
implementation.

8-4

TOOLS, LIBRARIES, AND SYSTEM INTERFACES
The default file types are:
in-spec
out-spec
merge-spec

8.2.2

B32 (BLI)
XRF
MRG

Command Semantics

BLSCRF accepts as input BLISS
source
text
and
produces
a
cross-reference listing file (out-spec) and/or merge file (merge-spec)
suitable for combining with similar files to produce a master
cross-reference of multiple modules.
The cross-reference listing is a numbered listing of the input text,
followed by an alphabetical listing of symbols and line numbers on
which the symbols occur. This file
is suitable for listing on a
132-column line printer.
The merge file contains cross-references by symbol and file name.
This can be appended to other merge files and sorted to create a
master cross-reference.

8.2.3

Command Qualifiers

A number of command-line qualifiers can be specified to permit some
flexibility in what is cross-referenced and how it is formatted
(*=default).
/FLAG: (ASSIGN,REQUIRE,ROUTINE)
Certain characters can be used to flag
including:

various

symbol

uses,

ASSIGN*
NOASSIGN

"#" indicates that symbol appeared on left side of
an equals sign
and
represents
a
probable
assignment

REQUIRE*
NOREQUIRE

"+" indicates that symbol appeared in REQUIRE file

ROUTINE*
NOROUTINE

"*" indicates that symbol appeared as a routinename in a ROUTINE declaration
(also
FORWARD
ROUTINE, BIND ROUTINE, or EXTERNAL ROUTINE)

/KEYWORD
/NOKEYWORDS*

The use of BLISS
referenced.

/MERGE:file-spec

Create a merge file.

/ONCE
/NOONCE*

Cross reference only those symbols
exactly once in the input file.

language

keywords

is cross

that appear

/OUTPUT:file-spec Specifies output file.
/REQUIRE
/NOREQUIRE*

List

/SOURCE*
/NOSOURCE

Include a line numbered listing of the source
with the cross-reference in the output file.

source

8-5

lines

REQUIRE

files.

TOOLS, LIBRARIES, AND SYSTEM INTERFACES
8.3

BLISS LANGUAGE FORMATTER (PRETTY)

PRETTY is a utility program that reformats BLISS source files and
require files so that they correspond to the formatting standards
described in the VAX-11 Software Engineering Manual.
PRETTY is a
valuable tool
in standardizing the appearance of BLISS code, for it
promotes readability while
permitting
flexibility
in
program
structure.
PRETTY is more than a reformatter.
It also performs a cursory syntax
check of your program and reports obvious errors that should be fixed
prior to compilation, such as mismatched BEGIN and END statements.

8.3.1

Command Line Format

PRETTY is invoked by defining the string symbol:
PRETTY:==$PRETTY
PRETTY in-spec{/OUTPUT: out-spec}{/LISTING: list-spec}, •••

8.3.2

Command Semantics

The output file contains the reformatted source program
file.
Some of the operations performed by PRETTY are:

•

To force routines to the top of a new page (if
nested within other routines)

•

To align BEGIN-END pairs

•

To indent blocks

•

Where possible, to align end-of-line comments (remarks)
standard column

•

To align block comments with the enclosing blocks

•

To realign control structures
standard way

one

they

REQUIRE

are

lines

not

Several options are available to enable a user to specify different
kinds of formatting;
defaults for all options are described.
The listing file differs from the output file in three ways:
Each line is appended with a slash (/), the SOS page number,
• and
the SOS line number, as in:

200

logical tab is preceded by a colon
• Each
indentation level is obvious, as in:
IF .A
THEN

I
I
I
I
I

IF .B
THEN

8-6

(:)

1.
1.
1.
1.
1.

1200
1300
1400
1500
1600

that

the

TOOLS, LIBRARIES, AND SYSTEM INTERFACES

I
I
I
I
I

IF .C
THEN
D=S;
•

1700
1800
1900
2000
2100

1.
1.
1.
1.
1.

There is a three line heading on each page:
%TITLE information (which starts a new page)
%SBTTL information
Module and routine names and page number

The listing file cannot be used as input to the BLISS compiler.
On VAX, if no output or listing files are specified, only terminal
error messages are produced. Otherwise, an output file is created, if
specified, and a listing file is created, if specified.
If no input
file extension is specified the extension defaults to .BLI.
Producing both an output file and listing file doubles the execution
time of PRETTY.
However, PRETTY's typical execution time is only a
fraction of the BLISS compiler's.

Formatting Options

8.3.3

You can specify in the source input a number of options, which give
you flexibility in deciding how to format your code. You supply
formatting options by inserting directives as full-line comments in
the input source text. The format of the formatting option directive
is:
!<BLF/option>
The exclamation point that starts the command must begin in column 1.
Options may be typed in uppercase or lowercase characters. Commands
are passed to PRETTY in this fashion without modification to either
the output or the listing files.
Since the directives begin with an
exclamation point, they are interpreted as comments by the BLISS
compiler.
Formatting option directives are described
identifies the default.

below.

asterisk

( *)

ERROR*
This enables the insertion of error messages
(that is, lines
beginning with "!!ERROR!!") into the output file.
Error messages
are automatically deleted from source files on subsequent runs.
Example:

!<BLF/ERROR>

NO ERROR
This disables the insertion of error messages into the
file.
Error messages are always output to the terminal.
Example:

!<BLF/NOERROR>

8-7

output

TOOLS, LIBRARIES, AND SYSTEM INTERFACES
FORMAT*
This causes resumption of formatting by PRETTY.
Example:

!<BLF/FORMAT>

NOFORMAT
This inhibits formatting by PRETTY until the next !<BLF/PAGE>
!<BLF/FORMAT> is encountered.
Example:

!<BLF/NOFORMAT>

LOWERCASE
This causes all identifiers
lowercase.

converted

This causes BLISS keywords, builtins, and predefined names to
converted to lowercase.

Example:

and

keywords

!<BLF/LOWERCASE>

LOWERCASE KEY

Example:

!<BLF/LOWERCASE_KEY>

LOWERCASE USER
This causes user identifiers to be converted to lowercase.
Example:

!<BLF/LOWERCASE_USER>

MACRO
This causes macros to be formatted. Use of this option may cause
error messages that do not appear when formatting with macros is
disabled.
Example:

!<BLF/MACRO>

NOMACRO*
This disables formatting of macros.
Example:

! <BLF /NOMACRO>

NOCASE*
This causes all identifiers and keywords to remain unchanged.
Example:

!<BLF/NOCASE>

NOCASE KEY
This causes all BLISS keywords, builtins, and predefined names to
remain unchanged.
Example:

!<BLF/NOCASE_KEY>

NOCASE USER
This causes all user identifiers to remain unchanged.
Example:

!<BLF/NOCASE_USER>
8-8

TOOLS, LIBRARIES, AND SYSTEM INTERFACES
PAGE
A page break (formfeed)
Example:

is generated.

!<BLF/PAGE>

PLIT
This causes formatting of PLIT bodies to occur.
Since the
content of PLITs is difficult to analyze, PRETTY may format the
PLIT differently than you had intended.
Example:

!<BLF/PLIT>

NOPLIT*
This inhibits formatting of PLIT bodies.
Only the first line of
a PLIT body is formatted;
the remaining lines remain unchanged.
Example:

!<BLF/NOPLIT>

REMARK:n (Default = 6)
This causes subsequent comments to begin at column 8*n+l,
2 < n < 16. The default comment starts at column 49•
Example:

where

!<BLF/REMARK:S>

REQUIRE'file-spec'
The specified file
is read
for
further
formatting
option
directives.
Everything
in the REQUIRE file other than legal
directives is ignored.
Directives in the REQUIRE file are not
reproduced in the output or listing files.
The REQUIRE file must
not contain another REQUIRE directive.
Example:

!<BLF/REQUIRE'COMMAND.REQ'>

SYNONYM name = lexeme •••
This option describes to PRETTY macros that you have
substitute for
keywords.
SYNONYM causes subsequent
of "name" to be treated as a sequence of other
formatting purposes.
The special token "*" can
indicate where to position "name" with regard to
position of the tokens that it replaces.
Example:

defined to
occurrences
tokens for
be used to
the normal

!<BLF/SYNONYM ELIF = ELSE IF *>

permits the sequence:
IF expr THEN expr ELIF expr THEN expr;
to be formatted without error.
Only the name ELIF is output, but
it is indented as though ELSE IF had occurred in the text.
In the above example, formatting would occur as follows:
IF expr
THEN
ex pr
ELIF expr
THEN
expr;

8-9

TOOLS, LIBRARIES, AND SYSTEM INTERFACES
If !<BLF/SYNONYM ELIF = ELSE * IF> had been specified, formatting
would occur as:
IF expr
THEN
ex pr
ELIF
ex pr
THEN

expr;
UPPERCASE
This causes all identifiers
uppercase.
Example:

and

keywords

converted

!<BLF/UPPERCASE>

UPPERCASE KEY
This causes all BLISS keywords, builtins, and predefined names to
be converted to uppercase.
Example:

!<BLF/UPPERCASE_KEY>

UPPERCASE USER
This causes all user identifiers to be converted to uppercase.
Example:

!<BLF/UPPERCASE_USER>

WIDTH:n (Default = 110)
This causes subsequent output
columns, where 71 < n <141.
Example:

8.3.4

lines

have

width

"n"

!<BLF/WIDTH:80>

Hints on Using PRETTY

Because of the great flexibility possible in the use of the BLISS
language, specification of fixed formatting rules for the language is
difficult. In order to construct a formatting tool like PRETTY, an
idealized model of a BLISS program must be used. This model may be
quite different from your particular style of manual formatting.
Several features of the language can be used in such a way as to make
formatting difficult without very extensive semantic analysis. In
order to meet its goals of executing many times faster than the
compiler, PRETTY does not perform this kind of extensive analysis, but
rather relies on hints from the programmer.

8-10

TOOLS, LIBRARIES, AND SYSTEM. INTERFACES
8.3.4.1 Breaking Lines - PRETTY attempts to break lines by certain
general rules.
In a begin-block, every semicolon terminating a main
line expression causes a line break except if a remark follows.
Therefore, a remark can be used to force a line break.
Operator-expressions that are too long to fit on a single line will be
broken around an operator. A programmer can specify an alternate line
break strategy by using the exclamation point as a break character.
Consider a (visually) long expression of the form:
El OR ••• ANO EN
where Ei denotes an expression.
If the programmer wishes to control
following can be written:
El
E2

OR
OR
AND

how

this

line

broken,

the

comment

EN
PRETTY attempts to place an if-expression on a single line if it fits.
If it does not, PRETTY will automatically place the 'THEN' under the
'IF', and the 'ELSE' if present, under the 'THEN'.

8.3.4.2 Comments - While BLISS recognizes only two kinds of comments,
embedded comments
( %( ••• )% ) and trailing comments ( ! ••• ) ,
PRETTY distinguishes several subtypes of trailing comments:
•

Remarks:
••• ! comment

These are lined up in the remark column,
analyzed. They cause a line break.
•

but

not

passed

the

Full line comment:
!

rest of line

This occurs in column 1. The entire line is
output file without further processing.
•

otherwise

Offset BLOCK comments:

...
!+
! comment
!-

These are preceded and followed by a blank line, and indented
to the current indentation level.

8-11

TOOLS, LIBRARIES, AND SYSTEM INTERFACES
•

Non-offset BLOCK comments:

! comment

These are similar to offset block comments in that they are
similarly indented, but are not offset from the surrounding
text by blank lines. They are recognized as block comments
rather than remarks only if they appear more than one tab to
the left of the remark column.

8.3.4.3 MACROS - Because it is possible to write macros in BLISS that
are not expressions or lists of expressions, PRETTY conservatively
makes no attempt to format macro bodies, and treats macro invocations
in the same way as routine calls. Thus, the macro body appears in the
output file the same way it appeared in the input file, and thus, may
be formatted quite differently from surrounding text in the output
file.
Experience has shown, however, that the great majority of macro bodies
can be successfully formatted by PRETTY. Because of this, you may
want to change the default to:
!<BLF/MACRO>
for your programs by preceding each source file with the above
command.
Macro formatting can be turned off before any offending
macro declaration, and turned on after it, should there be any.
The SYNONYM facility allows users a limited way of telling PRETTY to
interpret certain macro invocations as other than routine calls, as in
the ELIF macro given above.

8.3.4.4 PLITs - PLITs are used to construct initialized tables in
BLISS, and in practice, the programmer-specified formatting of a table
gives a good indication to the reader of the structure and meaning of
the table.
Rather than try to guess the structure of a PLIT, PLIT
turned off by default.

formatting

The initial-attribute of a declaration is handled exactly as a PLIT.

8.4

TUTORIAL TERMINAL INPUT/OUTPUT PACKAGE (TUTIO)

TUTIO.R32 is a BLISS REQUIRE file that contains some simple terminal
I/O primitives. This package is normally used in conjuction with the
BLISS self-paced study course as outlined in the BLISS Primer, but can
be useful in writing quick and dirty programs, also. To gain access
to the elements of this package, insert the following line in your
BLISS program:
REQUIRE 'SYS$LIBRARY:TUTIO';

8-12

TOOLS, LIBRARIES, AND SYSTEM INTERFACES
A list of these primitives and their functions 'appears
following conventions are used in the descriptions:
char

- a character

len

- a length (in characters)

addr

- a memory address

value

- an integer

radix

- an integer

The

•

TTY_PUT_CHAR(char); - Writes a character to the terminal.

•

char=TTY_GET_CHAR(): - Reads a character from the terminal.

•

TTY PUT QUO('quoted string'); - Writes a quoted string to
terminal.

•

TTY PUT CRLF(); - Writes a carriage return/line feed
to the terminal.

•

TTY_PUT_ASCIZ(addr); - Writes an ASCIZ string to the terminal.

•

TTY PUT MSG(addr,len); - Writes a string of
to the terminal.

•

TTY PUT INTEGER(value,radix,len); - Writes an integer
terminal.

•

n =TTY GET LINE{~ddr,len): - Reads a line from the terminal
into a Euff~r and returns the number of characters r~ad.

ASCII

The TUTIO package will function only with a terminal.
work from a batch job or command-procedure file.

8.5

below.

the

sequence

characters
to

wi 11

the

not

VAX/VMS SYSTEM SERVICES INTERFACE

System services are procedures used by the operating system to control
resources available to processes, to provide for communication among
processes, and to perform basic operating system functions, such as
the coordination of input/output operations. Although most system
services are used primarily by the operating system itself on behalf
of logged-on users, many are available for general use and provide
techniques that can be used in application programs.
The BLISS interface to the VAX/VMS System Services routines is in
SYS$LIBRARY:STARLET.REQ
or
SYS$LIBRARY:STARLET.L32.
The primary
function of the interface is to guarantee the proper number and
sequence of arguments required for the System Service calls.
Using the BLISS interface macros, the syntax for
invoking system
services in BLISS is almost identical to the VAX-11 MACRO keyword
syntax.
The major difference
(aside from the fact that BLISS
expressions appear in the parameter list) is that BLISS requires the
macro parameter list to be enclosed in parentheses.
(See the example
of the BLISS-style usage below.)

8-13

TOOLS, LIBRARIES, AND SYSTEM INTERFACES
To use the interface, include the declaration:
LIBRARY 'SYS$LIBRARY:STARLET'
System services act like routine calls and return a condition-value as
their result.
The following code fragment checks for successful
completion of the system service:
IF STATUS=$WAITFR(EFN=l)
THEN
!successful wait
ELSE
!invalid event flag
SIGNAL (.STATUS);
!pass back failure
For detailed information on available services, see the VAX/VMS System
Services Reference Manual.

8.5.1

Sample Program Using VMS System Services

The program shown below prints the time of day at the user's terminal.
Although not very interesting as a practical program, it does show the
use of two system services, $GETTIM and $FAO, and of the common
run-time library routine LIB$PUT_OUTPUT.
MODULE SHOWTIME(IDENT='l-1' %TITLE'Print time', MAIN=TIMEOUT)=
BEGIN
LIBRARY 'SYS$LIBRARY:STARLET';
Defines System Services
OWN
TIMEBUF: VECTOR[2],
1 64-bit system time
MSGBUF: VECTOR[SO,BYTE],
! Output message buffer
MSGDESC: BLOCK[S,BYTE] PRESET( [DSC$W LENGTH]=SO,
[DSC$A_POINTER]=M36BUF)
BIND
FMTDESC=%ASCID %STRING('At the tone, the time will be '
%CHAR ( 7) , I !l 5%T I ) ;
EXTERNAL ROUTINE
LIB$PUT OUTPUT: ADDRESSING_MODE(GENERAL);
ROUTINE TIMEOUT=
BEGIN
LOCAL
RSLT: WORD;

Resultant string length

$GETTIM( TIMADR=TIMEBUF );

Get time as 64-bit integer

$FAOL( CTRSTR=FMTDESC,
OUTLEN=RSLT,
OUTBUF=MSGDESC,
PRMLST= %REF(TIMEBUF));
MSGDESC[O] = .RSLT;
LIB$PUT OUTPUT( MSGDESC )
END;
END ELUDOM

Format Descriptor
Resultant length (only a word!)
Output buffer descriptor
Addr of 64-bit time block
Modify output descriptor
Return status

In the SHOWTIME example, LIB$PUT OUTPUT is part of the VMSRTL
shareable-image, as such it is referenced via GENERAL addressing. The
call on $FAOL uses %REF to make the PRMLST value the address of a
pointer to the TIMEBUF.

8-14

TOOLS, LIBRARIES, AND SYSTEM INTERFACES
8.5.2

Common Errors in Using System Services

When the user invokes system services, he can encounter a number of
errors.
Two of the more common errors occur when the $HIBER and $FAQ
services are invoked.
The $HIBER system service keyword macro has no arguments.
invoked as:

Thus, it· is

$HI BER
Notice the absence of any parenthesized argument list.
The OUTLEN keyword parameter of the $FAQ and $FAOL system service is
the address of a WORD (16-bit) value. A common error is to provide
that parameter with the address of a fullword (32-bit)
value, rather
than a WORD value.
Thus, the 16 high-order bits always contain a
variable, indeterminate value. Consequently, when the full 32-bit
value is used rather than just the 16 low-order bits, unpredictable
results occur.
Users should guard against this
services.

8.6

problem

calls

other

system

RECORD MANAGEMENT SERVICES INTERFACE

VAX-11 Record Management Services (RMS-32) is a collection of fileand record-level I/O routines that enable user programs to process and
manage data files. Also included as a part of RMS-32 is a set of
BLISS macro definitions that facilitate control-block initialization
and the calling of RMS control routines.
RMS
definitions
appear
in
SYS$LIBRARY:STARLET.REQ
or
SYS$LIBRARY:STARLET.L32.
For
a
general description of RMS-32
programming, see the VAX-11 Record Management Services User's Guide
and VAX-11 Record Management Services Reference Manual.

8.6.l

Using RMS-32 Macros

STARLET.REQ provides three types of RMS definitions:
a.

Field definitions and constants used in RMS control blocks

Static and dynamic control-block initialization macros

RMS routine-call keyword macros.

The best way to understand
STARLET.REQ and study it.

these

macros

8-15

copy

TOOLS, LIBRARIES, AND SYSTEM INTERFACES
Macros for defining FAB, RAB, and XAB blocks are provided.
Each
control block has macros for static or dynamic initialization and for
uninitialized structures; for example:
$FAB

A keyword macro for static definition.

$FAB INIT A keyword macro for run-time dynamic initialization.
$FAB DECL A simple macro for FABs that require no initialization.
Typically, this is used to map attributes onto a
routine's formal parameter.
Keywords for these macros are identical to those used by the VAX-11
RMS-32 interface, except for those keywords that expect a 64-bit
value. These keywords are handled as "keyO" and "keyl", each of which
has a 32-bit value.
M~CRO

8.6.2

Sample Routine Using RMS-32

The following sample program illustrates the use.of the RMS macros.
The program opens a file named MYFILE.SRC and copies it to a file
named MYFILE.LIS.
MODULE RMSTEST(IDENT='l-1' %TITLE'BLISS-RMS Example' ,MAIN=COPYIT)=
BEGIN
!++
! Sample program showing use of BLISS/RMS-32 Inter.face Macros
!--

LIBRARY 'SYS$LIBRARY:STARLET';

! All definitions are here

OWN
MYBUF:
INFAB:

VECTOR[CH$ALLOCATION(l32)],
$FAB(FNM='MYFILE.SRC',
FAC=GET),

Input record buff er
Source FAB

OUTFAB: $FAB(FNM='MYFILE.LIS', RFM=VAR,
RAT=CR, FAC=PUT),

Destination FAB

INRAB:

RAB def'n: Locate Read,
and Multibuffer I/O
on input and output.

$RAB(UBF=MYBUF, USZ=l32,
ROP=<LOC,RAH>, FAB=INFAB),
OUTRAB: $RAB(ROP=WBH, FAB=OUTFAB);
ROUTINE COPYIT=
BEGIN
LOCAL
STS;

! RMS service-completion code

$OPEN( FAB=INFAB );
Open input file
$CONNECT( RAB=INRAB );
and associate RAB.
$CREATE( FAB=OUTFAB );
Create a new output file
$CONNECT( RAB=OUTRAB );
and associate a RAB.
!+
! Copy loop. Read records from input until
! EOF or error encountered. Write each record as it is read.
!-

WHILE ( STS=$GET( RAB=INRAB ) ) DO
BEGIN
OUTRAB[RAB$L RBF] = .INRAB[RAB$L RBF];
OUTRAB[RAB$W-RSZ] = .INRAB[RAB$W=RSZ];
$PUT( RAB=OUTRAB )
END;

8-16

Copy record descr.
to output RAB and
write the record.

TOOLS, LIBRARIES, AND SYSTEM INTERFACES
$CLOSE( FAB=INFAB );
$CLOSE( FAB=OUTFAB );
IF .STS EQL RMS$_EOF
THEN
SS$ NORMAL
ELSE
• STS
END;
END ELUDOM

8.7
8.7.1

Close the input
and output files.
Check for EOF on input
Tell System everything is OK, or
Return the RMS error status •

OTHER VAX/VMS INTERFACES
LIB

LIB.L32 contains internal interfaces between BLISS-32 and the VAX/VMS
Operating System as well as everything in STARLET.L32. Much of LIB is
normally useful only to an operating-system programmer.
Most users
should use SYS$LIBRARY:STARLET.L32, the user relevant subset of LIB.

8.7.2

TPAMAC

TPAMAC.REQ provides BLISS macros for LIB$TPARSE, a finite-state
transition parser. The sample program presented in Figure 8-1 closely
parallels the example in Chapter 8 of the VAX-11 Runtime Library
Reference Manual.

MODULE CREATE DIR(%TITLE 'Create Directory File' !DENT
MAIN=CREATE_DIR)
BEGIN

•xoooo•,

This is a sample program that accepts and parses the command line
of the CREATE/DIRECTORY command.
This program contains the operating system
call to acquire the command line from the command interpreter
and parse it with TPARSE, leaving the necessary information
in its global data base. The command line has the following format:
CREATE/DIR DEVICE: [MARANTZ.ACCOUNT.OLD]
/OWNER UIC=[2437,25]
/ENTRIES=lOO
/PROTECTION=(SYSTEM:R,OWNER:RWED,GROUP:R,WORLD:R)
The three qualifiers are optional. Alternatively,_ the command
may take the form
CREATE/DIR DEVICE:J202,31]
using any of the optional qualifiers.
!-

Figure 8-1:

Sample TPARSE Program

8-17

TOOLS, LIBRARIES, AND SYSTEM INTERFACES

LIBRARY 'SYS$LIBRARY STARLET';
LIBRARY 'SYS$LIBRARY CLIMAC';
LIBRARY 'SYS$LIBRARY TPAMAC';

Define CLI off sets
and request blocks,
and TPARSE stuff too.

FORWARD ROUTINE
BLANKS OFF,
CHECK UIC,
STORE-NAME,
MAKE UIC,
CREATE_DIR;
I
I
I

Define parser flag bits for flags longword

LITERAL
UIC FLAG=
ENTRIES FLAG=
PROT FLAG=
I
I
I

/UIC seen
/ENTRIES seen
/PROTECTION seen

1,
2,

CLI request descriptor block to get the command line

OWN
REQ_COMMAND: $CLIREQDESC( RQTYPE=GETCMD );
I
I
I

TPARSE parameter block

OWN
TPARSE BLOCK: BLOCK[TPA$C LENGTHO,BYTE]
PRESET ( [TPA$L COUNT] =TPA$K COUNTO,
[TPA$L-OPTIONS]= TPA$M ABBREV
OR TPA$M_BLANKS)J
I
I
I

Longword count
Allow abbreviation
Process spaces explicitly

Parser Data Base

OWN
PARSER FLAGS,
DEVICE-STRING:
VECTOR[2],
ENTRY COUNT,
FILE PROTECT,
UIC GROUP,
UIC-MEMBER,
UIC-OWNER,
NAME COUNT,
DIRNAME:
BLOCKVECTOR[S,2,LONG];

Keyword flags
device string descriptor
space to preallocate
directory file protection
temp for UIC group
temp for UIC member
actual file owner UIC
number of directory names
name descriptors 0-7

EXTERNAL ROUTINE
SYS$CLI:
ADDRESSING MODE(GENERAL),
LIB$TPARSE: ADDRESSING=MODE(GENERAL);

Figure 8-1 (Cont.):

Sample TPARSE Program

8-18

TOOLS, LIBRARIES, AND SYSTEM INTERFACES

%SBTTL 'Parser State Table'
$INIT_STATE( UFD_STATE, UFO KEY );
Read over the command line to the first blank in the command.
$STATE( START,
(TPA$ BLANK,
(TPA$=ANY,

START) ) ;

,BLANKS OFF),
-

Read device name string and trailing colon
$STATE (,
(TPA$ SYMBOL,
$STATE(;

,DEVICE_STRING));

(':'));

Read directory string, which is either a UIC string or a general
directory -string.
$STATE (,
( (UIC) ,
( (NAME)));

,MAKE_UIC),

Scan for options until end of line is reached
$STATE(OPTIONS,
(

'/'

)

( TPA$ EOS,
TPA$_EXIT) );
$STATE (, ('OWNER UIC', PARSE_UIC,
('ENTRIES',
PARSE ENTRIES,
('PROTECTION',PARSE=PROT,

, UIC FLAG,
PARSER FLAGS),
, ENTRIES FLAG, PARSER-FLAGS),
, PROT_FLAG,
PARSER=FLAGS) );

Get file owner UIC
$STATE( PARSE UIC,
(':'),
('='));

$STATE(,
( (UIC) ,

OPTIONS ) ) ;

Get number of directory entries
$STATE( PARSE ENTRIES,
(':'),
('='));

$STATE (,
(TPA$_DECIMAL,OPTIONS,

Figure 8-1 (Cont.):

ENTRY_COUNT));

Sample TPARSE Program

8-19

TOOLS,

L~BRARIES,

AND SYSTEM INTERFACES

Get directory file protection. Note that the bit masks generate the
protection in complement form. It will be uncomplemented by the main
program
$STATE( PARSE PROT,

(' : ')
('='));

$STATE (,
('('));

$STATE( NEXT PRO,
( 'SYSTEM' , SYPR ) ,
('OWNER',
OWPR ),
('GROUP',
GRPR ),
('WORLD',
WOPR ) ) ;
$STATE( SYPR,
(': ')
('=')

);

$STATE(SYPRO,
( 'R''
( 'W''
( 'E''
( 'D''
(TPA$_LAMBDA,

SYPRO,
SYPRO,
SYPRO,
SYPRO,
ENDPRO)

, %X'l',

FILE PROTECT),
FILE-PROTECT),
FILE-PROTECT),
FILE:PROTECT),

, %X'2',
, %X'4',
, %X'8',
);

$STATE(OWPR,

( : ')
('='));

$STATE(OWPRO,
( 'R''
( 'W''
( 'E''
( 'D''
(TPA$_LAMBDA,

OWPRO,
OWPRO,
OWPRO,
OWPRO,
ENDPRO)

, %X'0010',
, %X'0020',
, %X'0040',
, %X'0080',

FILE PROTECT),
FILE-PROTECT),
FILE-PROTECT),
FILE:PROTECT),

);

$STATE (GRPR,

( : ')
('='));

$STATE(GRPRO,
GRPRO,
( 'R''
GRPRO,
( 'W''
GRPRO,
( 'E''
GRPRO,
( 'D''
(TPA$_LAMBDA, ENDPRO)

, %X'0100',
, %X'0200',
%X'0400',
,' %X'0800',

FILE PROTECT),
FILE-PROTECT),
FILE-PROTECT),
FILE:PROTECT),

);

$STATE(WOPR,

' ,

(': )
('='));

Figure 8-1 (Cont.):

Sample TPARSE Program

8-20

TOOLS, LIBRARIES, AND SYSTEM INTERFACES
$STATE(WOPRO,

WOPRO,
WOPRO,
(IE I'
WOPRO,
WOPRO,
(ID I '
(TPA$_LAMBDA, ENDPRO)
(IR I'

( 'W''

$STATE(ENDPRO,
(',',
( I )

, \X'lOOO',
, \X'2000',
, \X'4000',
, \X'8000',
);

FILE PROTECT),
FILE-PROTECT),
FILE-PROTECT),
FILE=PROTECT),

NEXT PRO),
0 PT I ON s )

);

Subexpressions to parse a UIC string.
$STATE( UIC,
('[')

);

$STATE(,
(TPA$ OCTAL,
$STATE(-;

UIC_GROUP) ) 1

(','));

$STATE (I
(TPA$ OCTAL,
$STATE(-;
{']',

UIC_MEMBER) ) ;
TPA$_EXIT, CHECK_UIC) );

Subexpressions to parse a general directory string
$STATE( NAME,
('[')

);

$STATE( NAMEO,
(TPA$ STRING,
$STATE(-;

NAMEO ),
TPA$_EXIT) ) ;

( I • I I
( I ]

, STORE_NAME) );

I I

Note absence of $END_STATE macro.
\SBTTL

'Parser Action Routines'

ROUTINE BLANKS OFF=
1

1 Shut off explicit blank processing after passing the command name.
1

BEGIN
BUILT IN
AP;
MAP
AP:

REF BLOCK[,BYTE];

AP[TPA$V BLANKS] = O;
1

1 Success always.

END;

Figure 8-1 (Cont.):

Sample TPARSE Program

8-21

TOOLS, LIBRARIES, AND SYSTEM INTERFACES
ROUTINE CHECK UIC =
l

l Check the UIC for legal value range.
l

BEGIN
BUILTIN
AP;
MAP
AP:

REF BLOCK[,BYTE];
UIC components are 16 bits only

IF .UIC GROUP<l6,16> NEQ 0 OR
.UIC-MEMBER<l6,16> NEQ 0
THEN
RETURN O;
UIC OWNER<0,16> = .UIC MEMBER<0,16>;
UIC-OWNER<l6,16>
.UIC GROUP<0,16>;
1

ENO;
ROUTINE STORE NAME=
l
l

Store a directory name component
BEGIN
BUILT IN
AP;
MAP
AP:

REF BLOCK[,BYTE];

IF .NAME_COUNT GEQ 3 THEN RETURN O;
OIRNAME[.NAME COUNT,0,0,32,0]

OIRNAME[.NAME-COUNT,l,0~32,0]

NAME_COUNT = 7NAME_COUNT + l;

l Maximum of 3 components

.AP[TPA$L TOKENCNT];
.AP[TPA$L=TOKENPTR];

Store the
descriptor
Set to next
free slot

IF .AP[TPA$L_TOKENCNT] GTR 9 THEN RETURN 0; ! Name too long
1

ENO;
ROUTINE MAKE UIC=
BEGIN
BUILT IN
AP;
MAP
AP:
REF BLOCK[,BYTE];
OWN
UIC STRING:
VECTOR[CH$ALLOCATION(6)];
IF

.UIC GROUP<8,8> NEQ 0 OR
.UIC-MEMBER<8,8> NEQ 0
THEN
RETURN O;

Check UIC for byte values,
since UIC type directories
are restricted to this form

DIRNAME[O,l,0,32,0] = UIC STRING;
$FAOL( CTRSTR=UPLIT(6,'lOB!OB'),
OUTBUF=DIRNAME,
PRMLST=UIC_GROUP)
END;

Point to string buffer
Convert UIC to octal string

Figure 8-1 (Cont.):

Sample TPARSE Program

8-22

TOOLS, LIBRARIES, AND SYSTEM INTERFACES
tSBTTL

'Main Program'

ROUTINE CREATE DIR=
1+
1

1 This is the main program of the CREATE/DIRECTORY utility. It gets
1 the command line from the command interpreter and parses it with TPARSE.
1
1-

BEGIN
1
l Call the command interpreter to obtain the command line
1

SYS$CLI( REQ_COMMAND, O, 0 );
1

1 Copy the input string descriptor into the TPARSE control block
! and call LIB$~PARSE. Note that impure storage is assumed to be zero.
1

TPARSE BLOCK[TPA$L STRINGCNT] = .REQ COMMAND[CLI$W RQSIZE];
TPARSE:BLOCK[TPA$L:STRINGPTR] = .REQ:coMMAND[CLI$A=RQADDR];
IF NOT LI8$TPARSE( TPARSE BLOCK, UFD_STATE, UFD_KEY
THEN
RETURN SS$_ABORT;
Parsing is complete
Process the command to create
the appropriate directory.
RETURN SS$_NORMAL
END1
END ELUDOM

! Return Success to command interpreter

Figure 8-1 (Cont.):

Sample TPARSE Program

8-23

APPENDIX A
SUMMARY OF COMMAND SYNTAX

This appendix summarizes the command syntax, the
and their abbreviations.

A.l

qualifier

defaults,

COMMAND-LINE SYNTAX

compilation-request

$ BLISS bliss-command-line

bliss-command-line

{ qualifier, ••• } space input-spec, •••

{ output qualifier
general qualifier
terminal qualifier
optimization qualifier
source-list qualifier
machine-code-list qualifier

qualifier

...

space

{ blank

input-spec

file-spec+ ••• {qualifier, ••• }

A.2

I tab }

}

FILE SPECIFICATION SUMMARY

file-spec

{ node::

node

1- to 6-character alphanumeric network node name and
optionally a 1- to 42-character access control string

dev

any logical or physical device name; includes device
type, controller designation, and unit number

dir

any valid directory or subdirectory name

file

type

1 to 3 alphanumeric characters

ver

version number from 1 to 32767

} { dev: } { [di r]

} file { .type } { ;ver }

to 9 alphanumeric characters

A-1

SUMMARY OF COMMAND SYNTAX
A.3

QUALIFIER SYNTAX

output qualifier

/OBJECT {=file-spec}
/LIST {=file-spec}
{ /LIBRARY {=file-spec}

general qualifier

/TRACEBACK I /NOTRACEBACK
/DEBUG
I /NODEBUG
{ /CODE
I /NOCODE
/VARIANT {:value} }

/NOOBJECT }
/NO LIST
/NO LIBRARY

/TERMINAL=

terminal-value

ERRORS
{ STATISTICS

optimize qualifier

/OPTIMIZE=

NOERRORS
NOSTATISTICS

I
I

{ ( optimize-value
optimize-value

optimize-value

{

QUICK I NOQUICK
SPEED I SPACE
LEVEL : optimize-level
SAFE
I NOSAFE

optimize-level

{

source-list qualifier

/SOURCE_LIST=

source-value
\

}
I • • •

)

}

PAGE SIZE : number-of-lines
HEADER
I NOHEADER
LIBRARY
I NOLIBRARY
REQUIRE
I NOREQUIRE
EXPAND MACROS
I NOEXPAND MACROS
TRACE MACROS
I NOTRACE MACROS
SOURCE
I NOSOURCE

... }

{ 20

machine-code1 ist qualifier

/MACHINE_CODE_LIST=

I 21 I 22 I

OBJECT
ASSEMBLER
SYMBOLIC
BINARY
COMMENTARY
UNIQUE_NAMES

{

A-2

}

( source-value ' ... )
}
{ source-value

number-of-lines

code-value

( terminal-value , ... )
{ terminal-value
}

terminal qualifier

).
(
'

I
I
I
I
I
I

( code-value , ... ) }
{ code-value
NOOBJECT
NOASSEMBLER
NOSYMBOLIC
NOBINARY
NOCOMMENTARY
NOUNIQUE_NAMES

}

SUMMARY OF.COMMAND SYNTAX
A.4

QUALIFIER DEFAULTS

The following qualifiers are assumed by default:
/OBJECT=input-file-name.OBJ
/NOLIST (in interactive mode)
/LIST
(in batch mode)
/NOLIBRARY
/TRACEBACK
/ERROR LIMIT=30
/NODEBUG
/CODE
/VARIANT:O
/TERMINAL={ERRORS,NOSTATISTICS)
/OPTIMIZE=(NOQUICK,SPACE,LEVEL:2,SAFE)
/SOURCE LIST={HEADER,PAGE SIZE:58,NOLIBRARY,NOREQUIRE,
NOEXPAND_MACROS,NOTRACE_MACROS,SOURCE)
/MACHINE CODE LIST=(NOASSEMBLER,SYMBOLIC,BINARY,OBJECT
COMMENTARY,NOUNIQUE_NAMES)

A.5

ABBREVIATIONS

The abbreviations for the positive
qualifier values are given below:
Qualifier

forms

the

qualifiers

Abbreviation

Value

/OBJECT
/LIST
/LIBRARY
/ERROR_LIMIT

/OB
/LIS
/LIB
/E

/TRACEBACK
/VARIANT
/CODE
/DEBUG
/TERMINAL

/TR
/V
/C
/D
/TE
E

ERRORS
STATISTICS
/OPTIMIZE

/OP
Q
SPA
SPE
L
SA

QUICK
SPACE
SPEED
LEVEL
SAFE

A-3

and

SUMMARY OF COMMAND SYNTAX
Qualifier

Value

Abbreviation

/SOURCE_LIST
HEADER
PAGE SIZE
LIBRARY
REQUIRE
EXPAND MACROS
TRACE MACROS
SOURCE
/MACHINE_CODE_LIST
OBJECT
ASSEMBLER
SYMBOLIC
BINARY
COMMENTARY
UNIQUE_NAMES

/S
H
p
L

R
E

/M
0
A

c
u

For the negative form of a qualifier or value (where applicable),
positive-form abbreviation can be prefixed by "NO".

A-4

its

APPENDIX B
SUMMARY OF FORMATTING RULES

The basic rule of indentation is that a block is indented one logical
tab deeper than the current indentation level (one logical tab equals
four spaces;
two logical tabs equal one physical tab}.
·The
declarations and expressions of a block are indented to the same level
as the BEGIN-END delimiters.
The format for a declaration is:
declaration-keyword
declaration-item,

!comment

declaration-item;

!comment

where the declaration-keyword starts at the current indentation
and each declaration-item is further indented one logical tab.

level

Expressions generally have two formats: one for expressions that fit
on one line and one for expressions that are longer.
If the
expression does not fit on one line, then keywords appear on separate
lines from subparts and subparts are indented one tab. For example,
IF expressions are written in either of two formats:
IF test THEN consequence ELSE alternative;
or
IF test
THEN
consequence
ELSE
alternative;
The examples used in Chapter 2 are indented correctly,
comments have been omitted in order to save space.

although

all

For further information, see the VAX-11 Software Engineering Manual.

B-1

APPENDIX C
MODULE TEMPLATE

This appendix contains a listing of the file MODULE.BL!, which is the
standard template for BLISS modules and routines. A module has four
parts: a preface, a declarative part, an executable part, and a
closing part.
The module's preface (Page C-2)
appears
first.
It
provides
documentation explaining the module's function, use, and history.
The module's declarative part appears next (Page C-3).
This section
provides
a table of contents for the module (FORWARD ROUTINE
declarations) and declarations of macros, equated symbols,
OWN
storage, externals, and so on.
The module's executable part, consisting of zero or more routines,
comes next. The template for a routine is on Page C-4. A routine has
three parts: a preface, a declarative part, and code.
Finally, every module has a closing part (Page C-4),
the syntax of a module.

which

completes

The module template may be used either as a checklist for module
organization and content or as the starting point in creating a new
module. The template and its use are described in detail in the
VAX-11 Software Engineering Manual.
The file MODULE.BL! is supplied as part of the BLISS support
on logical device SYS$LIBRARY.

C-1

package,

MODULE TEMPLATE
C.1

MODULE PREFACE

MODULE TEMPLATE (
!DENT

) =

BEGIN
COPYRIGHT (C) 1978, 1979, 1980 BY
DIGITAL EQUIPMENT CORPORATION, MAYNARD, MASS.
THIS SOFTWARE IS FURNISHED UNDER A LICENSE AND MAY BE USED AND COPIED
ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE
INCLUSION OF THE ABOVE COPYRIGHT NOTICE. THIS SOFTWARE OR ANY OTHER
COPIES THEREOF MAY NOT BE PROVIDED OR OTHERWISE MADE AVAILABLE TO ANY
OTHER PERSON. NO TITLE TO AND OWNERSHIP OF THE SOFTWARE IS HEREBY
TRANSFERRED.
THE INFORMATION IN THIS SOFTWARE IS SUBJECT TO CHANGE WITHOUT NOTICE
AND SHOULD NOT BE CONSTRUED AS A COMMITMENT BY DIGITAL EQUIPMENT
CORPORATION.
DIGITAL ASSUMES NO RESPONSIBILITY FOR THE USE OR RELIABILITY
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL.

!++
FACILITY:
ABSTRACT:
ENVIRONMENT:
AUTHOR:

, CREATION DATE:

MODIFIED BY:
, : VERSION
01
!--

C-2

ITS

MODULE TEMPLATE
C.2

DECLARATIVE PART OF MODULE

TABLE OF CONTENTS:
FORWARD ROUTINE

INCLUDE FILES:

MACROS:

EQUATED SYMBOLS:

OWN STORAGE:

EXTERNAL REFERENCES:
EXTERNAL ROUTINE

C-3

MO.DOLE TEMPLATE
C.3

EXECUTABLE PART OP MODULE

ROUTINE TEMP EXAMPLE

()

:NOVALUE =

!++
! FUNCTIONAL DESCRIPTION:
!
!
I

FORMAL PARAMETERS:
NONE
IMPLICIT INPUTS:
NONE
IMPLICIT OUTPUTS:
NONE
ROUTINE VALUE:
COMPLETION CODES:
NONE
SIDE EFFECTS:
NONE

!--

BEGIN
LOCAL
END;

C.4

! END

or· TEMP EXAMPLE

CLOSING FORMAT

END
ELUDOM

!END OF MODULE

C-4

APPENDIX D
IMPLEMENTATION LIMITS

Each BLISS-32 compiler implementation has limitations on the use of
certain language constructs or system interfaces. These values are
subject to change if experience indicates they are unsuitable.

D.l

D.2

BLISS-32 LANGUAGE
The maximum number of

•

Nested blocks containing declarations

•

Characters in a quoted-string

•

Actual parameters in a routine call

•

Structure formal parameters

•

Field components

•

Parameters of a FIELD attribute

128

•

Bytes initialized by a single PLIT
(i.e., the maximum byte count of a single PLIT)

1000

65,535

SYSTEM INTERFACES
The maximum number of

•

Characters in an input source line

132

•

Simultaneously active (depth of nested)
REQUIRE files

D-1

APPENDIX E
ERROR MESSAGES

Whether an error is fatal to the creation of an object module {ERR) or
a warning {WARN) is context-dependent. Informational messages {INFO)
have no effect on compilation. BLISS-32 creates an object module for
a program that has warnings,but no errors. However, such a program
may fail to link or may fail to execute in the intended manner.
In
some
of
these error messages, the compiler provides variable
information that points to the possible source of error.
{See the
example in Section 2.1 for an illustration.) In this appendix any
information enclosed in angle brackets {< >) describes the type of
such variable information given. Fatal error messages appear at the
end of the appendix.
000 Undeclared name:

<name>

Explanation:

The name shown has not previously been declared.

User Action:

Declare the name.

001 Declaration following an expression in a block
Explanation:
block.

Declarations

must

precede

expressions

within

User Action:
block.

Reinsert the declaration properly or create

new

Explanation: An excess or unnecessary left-operand precedes
operator named.

the

002 Superfluous operand preceding "<operator-name>"

User Action:

Remove the extra or unnecessary left-operand.

003 BEGIN paired with right parenthesis
Explanation: A closed parenthesis has been encountered when
compiler expected an END.
User Action:
END keyword.

the

Provide the appropriate pairing or insert a missing

E-1

ERROR MESSAGES
004 Missing operand preceding "<operator-name>"
Explanation: Required
infix-operator named.
User Action:

left-operand

missing

from

Insert missing left-operand.

005 Control expression must be parenthesized
Explanation:

Parerithesis is required to achieve intended result.

User Action:

Insert missing parenthesis.

006 Superfluous operand following "<operator-name>"
Explanation: An extra or unecessary
operator named.
User Action:

right-operand

follows

the

Remove the excess or unecessary right-operand.

007 Missing operand following "<operator-name>"
Explanation:
named.

Required right-operand

missing

User Action:

Insert missing right-operand.

from

operator

008 Missing THEN following IF
Explanation:

Conditional-expression is incomplete.

User Action:

Insert required keyword THEN.

009 Missing DO following WHILE or UNTIL
Explanation:

Pre-tested-loop-expression is incomplete.

User Action:

Insert required keyword DO.

010 Missing WHILE or UNTIL following DO·
Explanation:

Post-tested-loop-expression is incomplete.

User Action:

Insert required keyword WHILE or UNTIL.

011 Name longer than 31 characters
Explanation:

Maximum name length has been exceeded.

User Action:

Reduce name length to 31 characters or less.

E-2

ERROR MESSAGES
012 Missing DO following INCR or DECR
Explanation:

Indexed-loop-expression is incomplete.

User Action:

Insert required keyword DO.

013 Missing comma or right parenthesis
list

routine

actual

parameter

Explanation: Each actual-parameter in a list must be separated
by a comma and the list must be ended by a close parenthesis.
User Action:
parenthesis.

Insert

comma(s),

necessary,

and/or

014 Missing FROM following CASE
Explanation:

Case-expression is incomplete.

User Action:

Inse-rt required keyword FROM.

015 Missing TO following FROM in CASE expression
Explanation:

Case~expression

User Action:

Insert required keyword TO.

is incomplete.

016 Missing OF following TO in CASE expression
Explanation:

Case-expression is incomplete.

User Action:

Insert required keyword OF.

017 Missing OF following SELECT
Explanation:

Select-expression is incomplete.

User Action:

Insert required keyword OF.

018 Missing SET following OF in SELECT expression
Explanation:

Select-expression is incomplete.

User Action:

Insert required keyword SET.

019 Missing colon following right bracket in SELECT expression
Explanation:

Select-line of select-expression is incomplete.

User Action:
Insert colon between select-label
close bracket and select-action expression.

E-3

expression's

ERROR MESSAGES
020 Missing semicolon or TES following a
Explanation:

action

SELEC~

Select-line of select-expression is incomplete.

User Action: Insert required semicolon or keyword TES
select-action expression.

following

021 Address arithmetic involving REGISTER variable <variable-name>
Explanation: An attempt has·been made to
register name in an expression.
User Action:
022

use

the

value

Correct the expression.

Field reference used as an expression has no value
Explanation: The reference is invalid as a fetch
expression and cannot produce a value.
User Action:

assignment

Evaluate and validate the expression.

023 Missing comma or right angle bracket in a field selector
Explanation:

Field selector is incomplete.

User Action:

Insert missing comma{s) or close bracket.

024 Value in field selector outside permitted range
Explanation: The value has exceeded
machine-word boundaries of the dialect.

the

field

size

sign

legal

range

User Action: Correct the address, position~ size,
expression value according to dialect restrictions.
025 Value of attribute outside permitted range
Explanation: The value used is
permits, such as UNSIGNED{37).
User Action:

larger

than

the

Correct the attribute value.

026 ALIGN request negative or exceeds that of PSECT {or stack)
Explanation: The alignment-attribute boundary must be a positive
integer that does not exceed the psect-alignment-boundary.
User Action:

Correct the boundary value.

027 Illegal character in source text
Explanation: One of the 30 illegal non-printing ASCII characters
has been used (as other than data) in a BLISS module.
User Action: Only four non-printing characters (blank,
vertical-tab, and form-feed) may be used in coding.

E-4

tab,

ERROR MESSAGES
028 Illegal
parameter
in
<lexical-function-name>
Explanation:
invalid.

call

lexical

function

A parameter used with the named lexical-function is

User Action: Check and correct parameter usage according to
definition of the function.

the

029 Attribute illegal in this declaration
Explanation: Attributes
declarations.
User Action:

are

restricted

use

certain

Remove the illegal attribute from the declaration.

030 Access formals must not appear in structure size-expression
Explanation: An access-formal provides variable
access
to
elements of a structure and should not be included with the
expression defining structure size.
User Action:
expression.

Remove the access-formal

from

the

structure-size

031 Conflicting or multiple specified attributes
Expla·nation:
used.

Contradictory or superfluous attributes

User Action:
definitions.

Check

attribute

usage

regard

have

been

specific

032 Two consecutive field selectors
Explanation: Irrational
field-reference.

use

f ield..:.selector

portion

User Action: Remove extra field-selector or insert parenthesis
to create a complete field-reference, such as:
.(.x<0,16>)<0,8>.
033 Syntax error in ~ttribute
Explanation:
attribute.

error

has

occurred

the

coding

User Action:

Correct the error using the appropriate syntax.

034 INITIAL value <integer> too large for field
Explanation: The integer
designated field.
User Action:

value

shown

too

large

for

the

Decrease the value or increase the allocation-unit.

E-5

ERROR MESSAGES
035 The <attribute-name> attribute contradicts
declaration

corresponding

FORWARD

Explanation: The attributes of a name in an own- or global- or
routine-declaration must be identical to those used in the
associated forward-declaration.
User Action:

Correct the syntax of the attribute named.

036 Literal value cannot be represented in the declared number of bits
Explanation: The literal-value of a literal-declaration
larger than the field specified by the storage attribute.
User Actiort:

Check sign or bit-count of range-attribute.

037 Lower bound of a range exceeds upper bound
Explanation: The
value
case-expression must not
range.
User Action:

of
the
low-bound
range
of
a
exceed the value of the high-bound

Correct the low-bound value.

038 Number of routine actual parameters exceeds
of 64

implementation

for

value

has

Explanation: The number of
input-actual-parameters
routine-declaration must not exceed 64.
User Action:

Decrease the number of parameters to 64.

039 Name used in an expression has no value:

<name>

Explanation: A name that cannot denote an arithmetic
been used in an expression.
User Action:

limit

Correct the expression.

040 LEAVE not within the block labelled by <label-name>
Explanation:
label named.

The leave-expression is not within the block of the

User Action:

Insert the expression in the appropriate block.

041 Missing comma or right parenthesis in parameter
function <lexical-function-name>

list

lexical

Explanation: Each lexical-actual-parameter in a list must be
separated by a comma and the list must be ended by a close
parenthesis.
User Action:

Insert the missing comma(s) or close parenthesis.

E-6

ERROR MESSAGES
042 Missing label name following LEAVE
Explanation:

The leave-expression is incomplete.

User Action:
Insert the appropriate
keyword LEAVE.

label

name

following

the

043 Label <label-name> already labels another block
Explanation: The label name shown has been declared for
labeled-block.
User Action:

another

Change the name of one block or the other.

044 EXITLOOP not within a loop
Explanation:

exitloop-expression has been incorrectly used.

User Action:
Insert the expression, within the
to be exited.

(innermost)

loop

045 Missing structure name following REF,
structure~attribute

Explanation:
incomplete.

The

User Action:
keyword.

Insert the

missing

using

REF

following

the

shown

not

missing

open

keyword

structure-name

046 Register <register-number> cannot be reserved
Explanation: The register defined by the
locally usable.
User Action:

number

Specify another register.

047 Module prematurely ended by extra close bracket
bracket

Explanation: The number of close brackets in a module must equal
the number of open brackets.
User Action: Remove the extra right bracket (s)
11
> 11 ) or add the missing left bracket(s) (BEGIN,

(END,

(

)
,

,
11

]

048 Syntax error in module head
Explanation:

The module-head is incorrectly ~oded.

User Action: Correct
module-switch list.

the

module-name

E-7

the

syntax

the

ERROR MESSAGES
049 Invalid switch specified
switches~declaration

Explanation:
the dialect.

An invalid

User Action:

Correct the use of the switches-declaration.

050 Name already declared in this block:

has been used

with

<name>

Explanation: The name shown has been declared more than once
the same block.

User Action:
block.

the

Remove all but one of the declarations

within

051 Syntax error in switch specification

Explanation: An error has occurred in
module-switches or switches-declaration.
User Action:

the

coding

the

Correct the coding of the switches.

052 Expression must be a compile-time constant
Explanation: The
compiler
requires
a
compile-time-constant-expression and the expression used does not
meet the criteria.
User Action:

Evaluate and correct the expression.

053 Invalid attribute in declaration

Explanation:
declaration.

illegal

attribute

has

User Action: Check the legality of the
the declaration.
054 Name in attribute list not declared

name:

been

used

attribute{s)

structure

the

used

with

linkage

<name>

Explanation: The name shown has not been used as a structure- or
linkage-name in a structure- or linkage-declaration.
User Action:

Correct or declare the name appropriately.

055 Missing equal sign in BIND or LITERAL. dec.laration
Explanation: The name and value of a literal-, bind-data-,
bind-routine-item must be separated by an equal sign.
User Action:

Insert the missing equal sign.

E-8

ERROR MESSAGES
056 Missing comma or semicolon following a declaration
Explanation: Each decl~ration in a list must be separated
comma and the last must be followed by a semicolon.
User Action:

Insert the missing comma(s) or semicolon.

057 Value of structure size-expression for REGISTER must not exceed 4
Explanation:
value.

Structure~size

User Action:
expression.

Correct the value of

expression exceeds
the

maximum

allowed

structure-size

058 Left parenthesis paired with END
Explanation:
-END pair.

A pair of parenthesis must be used to replace a"("

User Action: Provide the appropriate pairing or insert a missing
BEGIN keyword.
059 Register <register-number> cannot be specifically declared
Explanation: Register number shown is beyond the allowable range
of the dialect or is illegally declared, such as REGISTER R = 50.
User Action:

Insert a valid register-number.

060 Missing SET following OF in CASE expression
Explanation:

Cas~-expression

User Action:

Insert required keyword SET.

is incomplete.

061 Missing left bracket preceding a CASE- or

SELECT~label

Explanation:

Case- or select-expression is incomplete.

User Action:

Insert missing open bracket.

062 MODULE declaration inside module body
Explanation:

A module-body cannot contain a module-declaration.

User Action:

Correct the declaration coding.

063 More than one CASE-label matching the same CASE-index
Explanation: Only
case-index value.
User Action:

one

case-label

value

can

match

Correct either the label or index value.

E-9

given

ERROR MESSAGES
064 Value in CASE--label outside the range given by FROM and TO

Explanation:
specified.

Value

case-label

not

within

User Action:

Correct the case-label or range values.

the

range

065 Missing equal sign in ROUTINE declaration

Explanation: An equal sign must precede the
routine-declaration.
User Action:

routine-body

Insert the missing equal sign.

066 Two consecutive operands with no intervening operator

Explanation:

Operator-expression is incomplete or illegal.

User Action: The compiler will
operator and continue.

usually

insert

appropriate

067 Missing comma or right bracket following a CASE- or SELECT-label

Explanation: Each label
in
a
list,
select-expression, must be separated by
ended with a close bracket.
User Action:

for
a
caseor
a comma and the list

Insert missing comma(s) or close bracket.

068 Name to be declared is a reserved word:

<name>

Explanation:

Reserved words cannot be declared by the user.

User Action:

Select another name for the declaration.

069 Size-expression required in STRUCTURE declaration when storage

to be allocated
Explanation: When a structure is associated with a name in a
data-declaration an expression must be used to specify the amount
of storage allocated.
User Action:

Insert structure-size expression.

070 Number of structure formal parameters exceeds implementation limit

of 31
Explanation:
allowed.

Number of access-formal parameters exceeds

User Action:

Reduce the number of parameters.

E-10

maximum

ERROR MESSAGES
071 Missing comma or closing bracket
<routine-or-macro-name>

formal

parameter

list

Explanation: Each formal parameter in a list must be
by a comma and the list ended with a right bracket.
User Action:

for

separated

Insert missing comma(s) or right bracket.

072 Missing control variable name in INCR or DECR expression
Explanation:

Indexed-loop-expression is incomplete.

User Action:

Insert missing loop-index name.

073 Missing equal sign in STRUCTURE or MACRO declaration
Explanation: An equal sign must precede the
expression or structure-body or the macro-body.
User Action:

structure-size

Insert the missing equal sign.

074 Missing actual parameter list for macro <macro-name>
Explanation: The actual-parameters
are
macro-call associated with the macro named.

missing

User Action:
Insert actual-parameters to correspond
formal-name parameters from the declaration.

from

the

with

the

075 Missing closing bracket or unbalanced brackets in actual parameter
list for macro <macro-name>
Explanation: There must be a right bracket
bracket used in the actual-parameter list.
User Action:

for

every

left

Correct the pairing of the open and close brackets.

076 Extra actual parameters
segment <name>

referencing

data

Explanation: Superfluous
access-actual
parameters
structure-reference for structure and data-segment named.

User Action:

for

structure

<name>

Correct coding of structure-reference.

077 Missing colon following right bracket in CASE expression
Explanation:

Case-expression is incomplete.

User Action:

Insert colon following close bracket.

E-11

ERROR MESSAGES
078 Name to be mapped is undeclared or not mappable:

<name>

Explanation: Name shown is undeclared or does not lie within the
scope of a data- or data-bind-declaration of the same name.
User Action: Declare
appropriate manner.

name

correct

declaration

079 Missing comma or right bracket in structure actual parameter list
Explanation: A comma must separate each access-actual parameter
in a list and the list must be ended with a close bracket.
User Action:
080

Insert missing comma(s) or close bracket.

Illegal
characters
in
<lexical-function-name>

quoted

string

parameter

Explanation: The only valid ASCII characters for a quoted string
are:
blanks, tabs, paired single quotes, and any printing
character except an apostrophe.
User Action: Remove illegal characters, or use %STRING
characters with %CHAR inserted before illegal ones.

for

all

081 Quoted string not terminated before end of line
Explanation:
line.

A quoted-string character sequence extends

over

User Action: Using %STRING and open parenthesis, quote first
character sequence and before end-of-line conclude with a comma;
do the same with subsequent sequences and then conclude the last
line with a close parenthesis.
082 Missing comma or right parenthesis following a
PRESET item

PLIT,

INITIAL

Explanation: Each item in the list must be separated by a
and the list must be ended with close parenthesis.
User Action:

comma

Insert missing comma(s) or close parenthesis.

083 Actual parameter list for macro <macro-name> not terminated before
end of program
Explanation: The actual-parameter list in the call for the macro
named must be ended by a close parenthesis or close bracket
(right square or right angle) even if the list is empty.
User Action:

Insert the missing close parenthesis or bracket.

E-12

ERROR MESSAGES
084 Expression must be a link-time constant
Explanation: The
compiler
requires
a
link-time-constantexpression and the expression used does not meet the criteria.
User Action:

Evaluate and correct the expression.

085 String literal too long for use outside a PLIT
Explanation: The numeric value of a string-literal
word length for the dialect.

exceeds

the

User Action: Reduce
pl it-declaration.

use

the

length

086 Name declared FORWARD is not defined:

the

string

<name>

Explanation:
be declared
block.

A name declared in a forward-declaration must also
by an own- or global-declaration within the same

User Action:

Make the proper declarations.

087 Size of initial value
{<integer-value>)

(<integer-value>)

exceeds

declared

Explanation: The initial value shown is greater than the
space reserved for it.
User Action: Decrease the
declared size value.

initial

value

and/or

size
memory

increase

the

088 Missing quoted string following <lexical-function-name>
Explanation: The
quoted-string.
User Action:

lexical-function

shown

requires

Insert the required quoted-string.

089 Syntax error in PSECT declaration
Explanation:

The psect-declaration is improparly coded.

User Action:

Check and correct the coding of the declaration.

090 Missing semicolon or TES following a CASE action
Explanation: Each case-action expression in a list must be
followed by a semicolon and the list must be concluded by TES.
User Action:

Insert the missing semicolon(s) or the keyword TES.

E-13

ERROR MESSAGES
091 No CASE-label matches the CASE-index
Explanation: Based on its evaluations of the low- to high-bound
and case-label values, the compiler has determined that for the
values of the case-index no selector element will be matched.
User Action: Evaluate the case-index and its bounds relative to
the values of the case-labels, or include INRANGE and OUTRANGE
labels.
092 Some values in the range given by FROM and
CASE-label

have

Explanation: The compiler cannot match all of the
high-bound values with the case-label values given.

matching
low-

User Action: Evaluate the case-label values relative to those of
the low- to high-bound values.
093 No structure attribute for variable <name> in structure reference
Explanation: The variable name shown has been declared
structure-attribute is missing.

but

the

structure-attribute
User
Action:
Insert
the
appropriate
for the declaration of
(structure-name and allocation-actuals)
the data-segment named.
094 Routine specified as MAIN is not defined
Explanation: The routine-name specified in the MAIN switch also
must be defined by a routine- or global-routine-declaration in
the same module.
User
Action:
declaration.

Define

the

routine

095 %REF built-in function must be
parameter

used

only

with

the

appropriate

routine

Explanation:

Builtin function has been used improperly.

User Action:

Correct the use of the function.

096 Module body contains
constant declaration

executable

expression

actual

non-link-time

Explanation: An executable expression (such as .x) or a non-ltce
declaration should not appear within the outer most level of the
module-body.
User Action: Correct the use of expressions and
within the outer most level of the module-body.

E-14

declarations

ERROR MESSAGES
097 Length of quoted string parameter of <lexical-function>
exceed <integer-value>

must

not

Explanation: The quoted-string of the function
contain more characters than the value shown.

must

not

User Action:

shown

Correct the length of the parameter.

098 Cannot satisfy REGISTER declarations
Explanation: Too many registers (in linkage, globals,
or predeclared functions) simultaneously active.

built-in

User Action: Redistribute explicit
overlaps as regards time.

prevent

usage

quantities

Explanation: Two conflicting data segments have
at the same time for the register shown.

been

allocated

099 Simultaneously
<integer-value>

User Action:

allocated

two

Correct the data segment allocations.

100 Division by zero
Explanation:

An illegal arithmetic operation has been performed.

User Action:

Correct the operation.

101 Name to be declared is missing
Explanation:

A name has not been specified in the declaration.

User Action:

Specify a name in the declaration.

102 Null structure actual parameter <name> has no default value
Explanation: A null
reference
has
been
made
with
access-actual expression for which no default value exists.
User Action:

Specify a value in the access-actual expression.

103 Illegal up-level reference to <name>
Explanation: Reference has been illegally made from a nested
routine-declaration
to
a
name in a higher level block.
References are not permitted to LOCAL, REGISTER, or STACKLOCAL
storage that is declared in a routine-declaration which contains
the routine-declaration currently being compiled.
User Action: Delete and relocate the reference or the name to an
appropriate block.

E-15

ERROR MESSAGES
104 Missing ELUDOM following module
Explanation:

The end module keyword is missing.

User Action:

Insert the ELUDOM keyword at the end of the module.

105 Language
feature
not
<feature-keyword-name>

yet

implemented

<language>:

Explanation:
dialect.

Language feature shown is not yet supported in this

User Action:

Remove the language feature named from the program.

106 REQUIRE file nesting depth exceeds implementation limit of 9
Explanation: Require declarations or lexical functions have been
nested beyond allowable limit.
User Action:

Reconfigure nesting within allowable limits.

107 Structure and allocation-unit or extension are mutually exclusive
Explanation: An
allocation-unit
attribute
or
an
extension-attribute cannot appear with a structure-attribute in
an allocation declaration.
User Action:

Remove the contradictory attribute(s).

108 Allocation-unit must not follow INITIAL attribute
Explanation: The allocation-unit attribute
initial-attribute in a declaration.
User Action:

must

precede

the

require-

Rearrange the order of the attributes.

109 Missing quoted string following REQUIRE or LIBRARY
Explanation: Quoted
library-declaration.
User Action:

file-name

not

found

Insert and/or quote file name in declaration.

110 Open failure for REQUIRE or LIBRARY file
Explanation:

The

library~declaration

User Action:
to compiler.

file
specified
in
a
requirecannot be accessed by the compiler.

Check validity of file name or make file

E-16

available

ERROR MESSAGES
111 Comment not terminated before end of <source-file-name>
Explanation: An imbedded comment must end
with
a
close
parenthesis and a percent sign; and the comment must end in the
same source file in which it began.
User Action:

Correct the insertion of the imbedded comment.

112 Definition of macro <macro-name>
program

not

terminated

before

end

Explanation: A macro-declaration must be terminated by a percent
sign followed by a semicolon.
User Action:

Terminate the macro-name shown.

113 Missing semicolon, right
subexpression of a block

parenthesis

END

following

be
concluded
by
a
Explanation: Each subexpression must
semi-colon
and the block must be concluded with a close
parenthesis or an END.
User Action:

Insert the appropriate terminator(s).

114 Invalid REQUIRE or LIBRARY file specification
Explanation: The specified require file must be a valid name to
the compiler and the system, and the library file must be a
binary file produced by the correct compiler dialect.
User Action:

Check and correct the validity of the file.

115 Expression identified by a label must be a block
Explanation: A labelled expression must be
BEGIN-END or parenthesis pair.
User Action:

contained

within

Enclose the expression(s) within a block.

116 Value of structure size-expression must be a compile-time constant
Explanation: The size-expression must meet the
compile-time-constant expression.
User Action:

criteria

for

indicate

Evaluate and correct the size-expression.

117 Value of structure size-expression must not be negative
Explanation: A structure size-expression
neg'at i ve value.
User Action:

must

not

Evaluate and correct the size-expression value.

E-17

ERROR MESSAGES
118 Missing left parenthesis in PLIT or INITIAL attribute
Explanation1 A plit-item
enclosed in parenthesis.
User Action:

initial-attribute

must

Insert the missing open parenthesis.

119 ALWAYS illegal in a SELECTONE expression
Explanation: The select-label ALWAYS cannot be
SELECTONE, SELECTONU, or SELECTONEA expression.

with

120 Case range spanned by FROM and TO exceeds implementation limit
512

User Action:

Correct the select-expression.

Explanation: Range of
high-bound limit of 512.
User Action:

used

case-expression

exceed

cannot

the

Evaluate and correct the range values.

121 Percent sign outside macro declaration
Explanation: An
improperly quoted
(%QUOTE)
percent sign is
contained in a nested macro-declaration, or an extra percent sign
has been found in the source file.
User Action: Evaluate and correct the use of
for the macro-declaration.

the

percent

sign

122 Recursive invocation of non-recursive macro <macro-name>
Explanation: Only a conditional-macro
formal-names can be used recursively.
User Action:

with

one

directly

Correct the definition of the macro named.

123 Recursive invocation of structure <structure-name>
Explanation:
indirectly.

structure

cannot

invoke

itself

User Action:

Correct the declaration of the structure named.

124 Expression nesting or size of a block exceeds implementation limit
of 300
Explanation: More expressions have
contains more lines than are allowed.

been

User Action:
Decrease the number of nested
number of lines in the block.

E-18

nested

expressions

block
or

the

ERROR MESSAGES
125 Operand preceding left bracket in structure
variable name
Explanation: The operand preceding
must be a variable-name.
User Action:

the

reference

not

access-actual-parameter

Evaluate and correct the operand.

126 Value of PLIT replicator must not be negative
Explanation: The
REP
replicator
compile-time-constant-expression
that
negative value.
User Action:

does

be
indicate

must
not

a
a

Evaluate and correct the replicator value.

127 RETURN not within a routine
Explanation: To properly return control to the caller, the
return-expression must be enclosed within the BEGIN-END pair of
the called routine.
User Action: Correct the placement of the return-expression
within the outer most level of the routine, or check for the
exclusion of the END keyword from the routine.
128 BIND or LITERAL name <name> used in its own definition
Explanation: The data-name-value for a bind-declaration or the
literal-value for a literal-declaration must not contain a name
already declared bind or literal.
User Action:

Evaluate name shown and correct coding.

129 Missing comma or right parenthesis in actual
<routine-or-macro-name>

parameter

list

for

Explanation: Each actual-parameter in a call list must be
separated by a comma and the list must be ended by a close
parenthesis.
User Action:
Insert the missing comma(s) or close parenthesis in
the call to the routine or macro named.
130 Omitted actual parameter in call to
default value

<keyword-macro-name>

has

Explanation:
In reference call to keyword-macro named,
default value exists for the omitted actual-parameter.
User Action: Provide
actual-parameter.

appropriate

E-19

value

for

the

no
no

omitted

ERROR MESSAGES
131 Extra actual parameters in call to <builtin-function-name>
Explanation: The number of actual-parameters used in call to a
builtin-function must not exceed the number of formal-parameters
used in the builtin-routine.
User Action: Correct actual-parameter
builtin-function named.

usage

call

must

Explanation: The translation-items do not meet the criteria
compile-time-constant-expressions.

for

User Action:
call.

the

table

are

132 Translation table entries
compile-time constants

call

CH$TRANSTABLE

Evaluate and correct the translation-items

133 Allocation unit (other than BYTE) in call to CH$TRANSTABLE
Explanation: Character-positions in
restricted to the length of a byte.

User Action:
If an allocation-unit
insert the keyword BYTE.

translation
attribute

necessary,

134 Length of table produced by CH$TRANSTABLE (<integer-value>) not an
even number between 0 and 256
Explanation: The number of translation-items used
must be even.

the

call

User Action: Reduce or increase the length of the table by an
even number that is closest to the number of character positions
desired.
135 Length of destination
CH$COPY

shorter

Explanation: The
sum
of
(snl+sn2+ ••• )
must not be
destination-parameter (dn) •
User Action:
136 Character-size
equal to 8

than

sum

source

lengths

the
source-length
parameters
greater than the value of the

Increase the value of the destination-parameter.
parameter

<character-function-name>

must

Explanation: The
character-function
named
has
illegally
specified a character-size other than eight bits in length; only
BLISS-36 supports character sizes other then eight.
User Action:

Insert a character-size value of eight.

E-20

ERROR MESSAGES
137 Built-in routine has no value
Explanation: A machine-specific-function that cannot produce
value has been used in a context where a value is required.
User Action:
Evaluate the required use of
and correct the coding.

the

builtin-function

138 Missing equal sign in GLOBAL REGISTER declaration
Explanation:

The global-register-declaration is incomplete.

User Action:
Insert
register-name.

the

missing

equal

139 Illegal use of %REF built-in function
<integer-value> of call to <routine-name>

sign

following

the

parameter

actual

Explanation: The value of a %REF function is the address of a
temporary data segment which stores a copy of the value of the
actual-parameter; thus its use is often incompatible with the
storage requirements of a builtin-function.
User Action:
Delete ~REF and provide a call to the routine named
that will provide permanent storage for the value returned.
140 Illegal use of register name as actual parameter <number> of
to routine <routine-name>
Explanation: An undotted register name has
actual-parameter for the routine-call shown
User Action:

been

used

call
as

Provide a legal register-name.

141 Routine <routine-name> has no value
Explanation:

The mechanism for returning a value is suppressed.

User Action:
named.

Remove

the

novalue-attribute

from

the

routine

142 Missing quoted string following CODECOMMENT
Explanation:

A quoted string is required for each comment.

User Action:

Enclose the affected comment(s)

in quotes.

143 Missing comma or colon following CODECOMMENT
Explanation:
Each quoted-string in the list must be separated by
a comma and the list must be ended with a colon.
User Action:

Insert the missing comma(s) and/or the colon.

E-21

ERROR MESSAGES
144 Expression following CODECOMMENT must be a block
Explanation: The-expression following the colon must be enclosed
with a parenthesis or BEGIN-END pair.
User Action:

Enclose the expression appropriately.

145 Illegal OPTLEVEL value <value>
Explanation: The only valid optimization-level values are:
through three.
User Action:
value.

Replace the switch value shown with an

zero

appropriate

146 ENABLE declaration must be in outermost block of a routine
Explanation: The enable-declaration must
most level of the establisher routine.
User Action:

reside

the

outer

Correct the placement of the enable-declaration.

147 More than one ENABLE declaration in a routine
Explanation: An establisher routine must not
one handler routine.
User Action:

enable

than

Remove all but one of the enable-declarations.

148 Handler specified by ENABLE must be a routine name
Explanation: The name specified by an enable-declaration must be
the name of a routine.
User Action:
declaration.

Provide

appropriate

routine-name

for

the

149 Illegal actual parameter in ENABLE declaration
Explanation: Actual-parameters
for
enable-declarations
are
restricted in use to names declared as own-, global-, forward-,
or local-names.
User Action:

Provide an

appropriately

declared

name

for

the

actual-parameter~

150 Name used as ENABLE actual parameter must be VOLATILE:

<name>

Explanation: A volatile-attribute must be used to warn the
compiler
that the declared actual-parameter is subject to
unexpected change.
User
Action:
Provide
actual-parameter named.

E-22

volatile-attribute

for

the

ERROR MESSAGES
151 Missing comma or right parenthesis in ENABLE actual parameter list
Explanation: Each actual-parameter in a list must be separated
by a comma and the list must be ended with a close parenthesis.
User Action:
parenthesis.

Insert

missing

the

and/or

comma{s)

152 LANGUAGE switch specification excludes <language-name>
Explanation: The language-name shown
language-list in a switch-declaration.
User Action:

missing

from

the

Insert the missing language-name.

153 Missing OF following REP
Explanation:
incomplete.

The replicator

User Action:
replicator.

Insert

the

construct
missing

154 Incorrect number of parameters
<lexical-function-name>
Explanation:
definition.

for

the

expression

keyword

following

the

call

A lexical-function must conform

lexical

function

syntactic

its

usage

for

155 Number of parameters of ENTRY switch exceeds implementation
of 128

limit

User Action: Evaluate
lexical-function named.

and

parameter

correct

Explanation:

The module-switch has been illegally coded.

User Action:
switch.

Reduce the number of parameters used in

156 Unknown name in BUILTIN declaration:
Explanation:
builtin.

the

ENTRY

<name>

Only a name predefined for BLISS can be declared as

User Action: Correct the name shown or delete it or use
form of declaration for it.
157 Conditional out of sequence:

another

<name>

Explanation: The keyword named is improperly
lexical-conditional.
User Action: Evaluate and correct
keywords are coded in the expression.

E-23

the

sequenced

order

the

which

the

ERROR MESSAGES
158 <%PRINT, %INFORM, %WARN, %ERROR, or %ERRORMACRO>:

<advisory-text>

Explanation: This is the form of the message number and text
that appears when one of the lexical-functions shown is used.
User Action: Example:
INFO il58,%INFORM:'user text specified by function'
159 Conditional
not
source-file-name>

terminated

before

end

Explanation: Lexical-conditional is not properly
the file named.
User Action:

<macro

terminated

Insert the missing termination keyword %FI.

160 Missing formal parameter or equal sign in call
<macro-name>

keyword

macro

Explanation: Each macro-actual-parameter in a keyword-macro-call
must be connected by an equal sign to a keyword-formal-name
previously declared in a keyword-macro.
User Action:
sign.

Insert the missing formal-name or the missing equal

161 Formal parameter <parameter-name> multiply specified
keyword macro <macro-name>

call

Explanation: In a keyword-macro-call to the macro named the
multiplication
of
the
keyword-formal-name shown has been
illegally specified.
User Action:

Evaluate and correct the coding of the call.

162 Missing %THEN following %IF
Explanation:

The coding of a lexical-conditional is incomplete.

User Action:

Insert the missing required keyword %THEN.

163 Actual
parameter
<parameter-name>
<routine-name> is illegal

call

routine

Explanation: An invalid actual-parameter has been used in a call
to the routine named.
User Action: Evaluate and correct the
named in the call.
164 Language feature to be removed:

use

actual-parameter

Explanation: Compiler reports that the use of feature
discontinued.
User Action:

Evaluate and correct module.

E-24

named

ERROR MESSAGES
165 Language feature not present in <language>:

Explanation: The compiler reports that the feature named is
available to the dialect named.

not

User Action: Remove the feature from the module-switch
dialect named.

for

the

Explanation:
declared.

The name used as a stack data-segment has not

been

User Action:

Correct or define name with stacklocal-declaration.

166 Name declared STACK is not properly defined

167 Name declared ENTRY is not globally defined:

<name>

Explanation: In BLISS-36, name shown has been designated for
entry in global-object-module-record and has not been declared as
global.
User Action:

Define name shown with global-declaration.

169 Fetch or store applied to field of zero size
Explanation: Attempted fetchinvalid data-segment.
User
Action: Correct
structure-declaration.

assignment-expression

range-attribute

for

data-

an
or

170 Missing equal sign in FIELD declaration
Explanation: An
equal
sign
must
appear
between
the
field-set-name and the keyword SET and between each field-name
and the left-bracket of the field-component.
User Action:

Insert missing equal sign(s).

171 Missing comma on right bracket in FIELD declaration
Explanation: Comma must appear after right-bracket
field-definition (except the last) in list.
User Action:

Insert missing comma(s).

E-25

each

ERROR MESSAGES
172 Missing· left bracket in FIELD declaration
Explanation: A left bracket must appear before
field-components in a list of field-definitions.
User Action:

each

list

Insert missing left bracket(s).

173 Missing comma or TES in FIELD declaration
Explanation: A comma must appear between each field-component in
a list and the list must be ended with a TES.
User Action:

Insert missing comma(s) or keyword TES.

174 Missing left bracket or SET in FIELD declaration
Explanation: The equal sign following the field-set-name must be
followed by a SET and each equal sign following a field-name must
be followed by a left bracket.
User Action:

Insert keyword SET or left bracket(s).

175 Number of field components exceeds implementation limit of 32
Explanation: The number of components in
exceeds the limits allowed for a structure.
User Action: Decrease
separate structures.
176 Field name <name>
<variable-name>

the

invalid

number

field-definition

components

create

structure

reference

variable

Explanation: The field-name shown as an access-actual-parameter
does
not
agree
with
the
variable-name
shown
as
a
field-declaration.
User Action:

Evaluate and correct the uses of name.

177 Parameter of FIELD attribute must be a field or field-set name
Explanation: Invalid
parameter
has
been
used
for
field-attribute;
the
name used must be identified by
field-declaration as a field- or field-set-name.

a
a

User Action: Replace
field-set-name.

parameter

178 Number of parameters of ,FIELD
limit of 128

with

attribute

declared

exceeds

field-

implementation

Explanation: Excessive number of field-names have been specified
in field-attribute.
User Action: Decrease the number of
field-set for the number in excess.

E-26

field-names

declare

ERROR MESSAGES
179 Missing equal sign in LINKAGE declaration
Explanation: An equal sign must appear
and a linkage-type.
User Action:

between

linkage-name

the

dialect

Insert the missing equal sign.

180 Invalid linkage type specified
Explanation:
illegal.

The

linkage-type

specified

for

User Action:

Evaluate and correct the linkage-type word.

181 Illegal register number <integer> in LINKAGE declaration
Explanation:

The register number shown is invalid.

User Action:

Evaluate and correct the register number.

182 Multiple specification of register
declaration

<register-number>

Explanation: The register shown has
once in the declaration.
User Action:

been

specified

LINKAGE

than

Evaluate and correct register specifications.

183 Invalid parameter location specified
Explanation:

The parameter-location specified is illegal.

User Action: Check the legal
correct the specifications.

uses

parameter-locations

and

184 Missing comma or right parenthesis in LINKAGE declaration
Explanation:
Each parameter-location in a list must be separated
by a comma and the list must be ended by a close parenthesis.
User Action:
parenthesis.

Insert

the

missing

comma(s)

and/or

the

185 Invalid linkage attribute in LINKAGE declaration
Explanation: A
linkage-option
has
linkage-declaration that is invalid.
User Action:

been

used

Use a valid modifier in the linkage-declaration.

185 Invalid linkage modifier in LINKAGE declaration
Explanation: An
linkage-option.

illegal

modifier

User Action: Check and correct
modifiers for the dialect.

E-27

has
the

use

been

used

linkage-option

ERROR MESSAGES
186 Missing left parenthesis in LINKAGE declaration
Explanation: A parameter-location list must be
open parenthesis.
User Action:

preceded

Insert the missing open parenthesis.

187 Missing global register name in LINKAGE declaration
Explanation: A global linkage-option has been
global-register-name has not been specified.
User Action:

used

and

the

Insert the missing global-register-name.

188 No match in linkage <name> for EXTERNAL REGISTER variable <name>
Explanation: The register named in the global
must be the same as the register named in

linkage-option
the associated

external-register~declaration.

User Action: Use the same register name in both the routine
its linkage-declaration.
189 Global register <name> specified
declared at call

linkage

<linkage-name>

and

not

Explanation: The register named in the global linkage-option has
not been declared in a call to the routine.
User Action: Declare the register-name within
routine via an external-register-declaration.
190 WORD or Radix-SO item
boundary
Explanation:

number

allocated

the

calling

odd

byte

Data structure is improperly allocated.

User Action: Correct data allocation to place WORD
value shown at a word boundary.
191 Multiple GLOBAL declaration of name:

RADSO 11

<name>

Explanation: The global name shown has been declared
once in the same module.

than

appearances

the

User Action: Delete
global-declaration.

all

the

extra

192 Multiple declaration of name in assembly source:

<name>

Explanation: The name shown has been declared more than once in
a module that was compiled with the assembleable-listing option.
User Action: If the intent is to run the listing through an
assembler, delete all extra appearances of the declared name;
or, use the switch-item UNAMES in a switches-declaration -to
obtain unique names.

E-28

ERROR MESSAGES
193 <declaration-name> declaration not available when OBJECT(ABSOLUTE)
in effect
Explanation:
expansion.

This

message

reserved

User Action:

No action is required.

for

future

BLISS-16

194 Library source module must contain only declarations
Explanation:
source file.

Executable expressions must not appear in a library

User Action:
source file.

Remove all but declaration coding from the

library

195 LIBRARY file has invalid format
Explanation:

The internal formatting of the file is incorrect.
not a precompiled
recompile.
If the

User Action: The specified file is probably
library file;
change the file-spec and
problem persists submit an SPR.

196 LIBRARY file must be regenerated using current compiler release
Explanation: A library source file must
using the latest version of the compiler.

precompiled

User Action:
Use the latest
regenerate the library file.

the

version

again

compiler

197 LIBRARY file must be generated using <language>
Explanation: The library file must be precompiled
compiler associated with the dialect named.

User Action: Generate the library
associated with the dialect named.

the

compiler

that

has

file

with

the

198 LIBRARY file contains internal consistency error
Explanation: A library file has been referenced
precompiled with errors.

User Action: Recompile the library source file with a
qualifier, and if the problem persists submit an SPR.

been

/LIBRARY

199 Warnings issued during LIBRARY precompilation: <number>
Explanation: The number shown is the number of
during the precompilation of the file.
User Action:

warnings

issued

Evaluate and correct all warnings and recompile.

E-29

ERROR MESSAGES
200 Illegal declaration type in library source module
Explanation: Only certain types of declarations may be used in a
library source file.
User Action: Remove the invalid declaration(s) from the
source file and regenerate the file.

library

201 Illegal occurrence of bound name <name> in library source module
Explanation:
file.

Bound names cannot be inserted

library

source

User Action: Remove the declaration for the name shown from
file and regenerate the file.

the

202 Number of parameters of ARGTYPE linkage attribute modifier exceeds
implementation limit of 128
Explanation: Excessive number of parameters
linkage-function ARGTYPE.
User Action:

used

with

builtin

Reduce the parameters to an acceptable number.

203 <name> linkage modifier not available with this linkage type
Explanation: The linkage-option named cannot be
linkage-type specified.
User Action:

used

with

the

Evaluate and use an appropriate linkage-option.

204 Length of SYSLOCAL specification not in range 1 to 15
Explanation:

This message reflects a future enhancement.

User Action:

No action is required.

205 BUILTIN declaration of <name> invalid in this context
Explanation: Each name used in a builtin-declaration must be
predefined (but not predeclared); however, if a register-name or
linkage-function is used it must also be contained in
a
routine-declaration.
User Action:

Evaluate and correct the use of the name shown.

206 BUILTIN operation needs a register declared as NOTUSED
Explanation: A register required by a builtin-function
unavailable for use due to a NOTUSED linkage modifier.
User Action: Delete or change the modifier in the
linkage-declaration to allow the register to be used.

E-30

associated

ERROR MESSAGES
207 NOTUSED linkage modifier of caller is not
called routine

subset

that

Explanation: The linkage-type and linkage-option of the
routine is incompatible with that of the called routine.
User Action:

caller

Evaluate and correct the linkage-declarations.

208 Called routine does not
caller

preserve

declared

NOTUSED

Explanation: To preserve all the necessary registers, all of the
locally usable registers of the called routine must be declared
as locally usable registers in the caller routine.
User Action:

Evaluate and correct the linkage-declarations.

209 Illegal character or field too large in VERSION
Explanation: The quoted-string in the VERSION switch
must
conform to the TOPS-10/20 version-number format, which is:
oooa(oooooo)-o; where "o" is an octal digit .and "a" is an
alphabetic.
User Action:
format.

Correct the string in regard to the

version-number

210 Stack pointers in different registers
Explanation: The number of the stack pointer register
is
assigned by default and depends on the dialect used; however,
the default number of the register can be altered by a change in
the declared linkage-type
(such as FlO) while neglecting to
specify the LINKAGE_REGS option.
User Action: Specify the desired stack pointer register number
by using a LINKAGE_REGS modifier for the altered linkage-type.
211 Use of uninitialized data-segment <name>
Explanation: An attempt has been made to
named without first initializing it.
User Action:
declaration,
from it.

use

the

data-segment

Insert an initial-attribute in the data-segment
or assign a value to the segment before fetching

212 Null expression appears in value-required context
Explanation:
required.

A null expression has been used where

User Action:

Evaluate and provide a value for the expression.

E-31

value

ERROR MESSAGES
213 Expression (s) eliminated following RETURN, LEAVE or EXITLOOP
Explanation: These expressions end
the
evaluation
of
a
routine-body (return), a block
(leave), or an innermost loop
(exitloop);
. therefore, they must be the last
expressions
inserted
before the affected block is ENDed,
if not all
subsequent expressions will not be compiled.
User Action: Evaluate and correct the insertion of
or exit-expression.

the

return-

214 Language feature not transportable
Explanation: The feature specified for the dialect(s) defined by
the language-switch is not transportable.
User Action:

Evaluate the feature and take appropriate action.

215 Language feature not transportable:

<name>

Explanation: The feature specified by the name shown is not
transportable to the dialect(s) defined by the language switch.
User Action:
action.

Evaluate the feature

216 Language feature not transportable:

named

and

take

appropriate

Explanation: The feature specified by the keyword shown is not
transportable to the dialect(s) defined by the language switch.
User Action:
action.

Evaluate the feature

shown

and

take

217 GLOBAL or EXTERNAL name not unique in 6 characters:
Explanation: In BLISS-16 and BLISS-36, at least
in a global- or external-name must be unique.
User Action:

appropriate

<name>
six

characters

Evaluate and correct the global- or external-name.

218 Implicit declaration of BUILTIN <linkage-name> to be withdrawn
Explanation: The compiler implicitly declares the function named
as builtin when a FORTRAN linkage-routine is being compiled.
User Action: Add
proper scope.

explicit

builtin-declaration

within

the

219 Empty compound expression is illegal
Explanation: A compound-expression block does not contain any
declarations, but it must contain at least one expression to be
legal.
User Action: Insert an expression in the
entire block form.

E-32

block

delete

the

ERROR MESSAGES
220 PRESET items have overlapping initialization
Explanation: A preset-value must not occupy more storage than is
allocated for the data segment, and the field-names described in
the preset-items must not overlap.
User Action:
Evaluate
preset-attribute.

and

coding

the

correct

the

must

221 Missing left square-bracket in PRESET attribute
Explanation: Each preset-item
preceded by an open bracket.
User Action:
preset-item.

Insert

222 Source line too long.

the

missing

preset-attribute
open

before

the

exceeds

the

Truncated to 132 characters.

Explanation: A
line
in
the
source
implementation limit of 132 characters.
User Action:

bracket

file

Decrease the size of the source line.

223 Name used in routine-call not declared as ROUTINE: <routine-name>
Explanation: The routine-designator used in a routine-call must
yield
a
value
declared
as
a
routine-name
in
a
routine-declaration.
User Action: Assure that the name used in the
declared in a routine-declaration.

routine-call

224 INTERRUPT general routine call is invalid
Explanation: A linkage-name defined by an INTERRUPT linkage-type
must not be used with this dialect in a general-routine-call.
User Action: With this dialect, use an ordinary-routine-call
invoke the interupt routine.

225 Invalid linkage attribute specified <attribute-name> is assumed
Explanation: A linkage-attribute must be either a predeclared
linkage-name or one specified in a linkage-declaration.
User Action:
Evaluate and correct the use of the linkage-name in
the linkage-attribute.
226 Value of a linkage name <name> is outside permitted range
Explanation: The value of the linkage-name shown
compatible and transportable range of the dialect.

exceeds

the

User Action: Provide a linkage-name that
is
compatible and transportable range of the dialect.

within

the

E-33

ERROR MESSAGES
227 Effective position and size outside of permitted range
.Explanation: The values of the field-reference parameters have
exceeded the structure-allocation specified for the data-segment.
User Action: Evaluate and correct the value of
field size parameters.

the

offset

and

Explanation: The instruction named did not produce a value
executed by the machine~specific-function MACHOP.

when

228 Builtin machop <name> has no value

User Action: Select a machine instruction that
value when executed.

will

produce

229 Parameter <parameter-name> of builtin <name> has value outside the
range
Explanation: The parameter named for the builtin-function
indicates a value that exceeds the specified range.
User Action: Decrease the value of the parameter
conform with the specifications of the function named.
230 Parameter <parameter-name> of builtin <name> must be
constant expression

named

link-time

Explanation: The parameter named for the builtin-function
is an invalid expression.

named

User Action: Replace the parameter named with an expression that
meets the criteria for a link-time-constant.
231 Invalid linkage attribute specified CLEARSTACK is added
Explanation:
dialect.

The CLEARSTACK linkage-option is illegal with

this

CLEARSTACK

the

User
Action: Delete
linkage-declaration.

the

modifier

from

232 OTS linkage specified twice
Explanation: The ots-option of the ENVIRONMENT switch specifies
the use of a standard OTS file and linkage; therefore the switch
must not appear in the same module with an OTS switch and an
OTS LINKAGE switch which specifies the use of a nonstandard file
and-linkage.
User Action:

Evaluate and correct the coding for OTS.

E-34

ERROR MESSAGES
233 OTS linkage <name> not declared before first routine declaration
Explanation: The linkage-name specified by the
OTS LINKAGE
switch must be predeclared or appear in a linkage~declaration
that precedes the first routine-declaration in the module.
User
Action: Define
the
linkage-name
shown
in
a
linkage-declaration that precedes the first routine-declaration
in the module.
234 OTS linkage <name> may not use global registers or pass parameters
by register
specified
register

Explanation: The linkage-name
switch
must
not
specify
parameter-locations.

by the
OTS LINKAGE
or
global-register
of

the

Explanation: The linkage-name shown has not been declared
to its use in an OTS LINKAGE switch.

prior

User
Action: Evaluate
and
correct
the
use
paramete-locations in the linkage-declaration named.
235 OTS linkage <name> not defined before it's used

User
Action: Declare
linkage-declaration.

the

linkage-name

shown

with

236 First PSECT declaration appears after a declaration that allocates
storage
Explanation:
In BLISS-36, the first psect-declaration in a
module must appear before the first declaration that causes
storage to be allocated or object code to be generated.
User Action: Reinsert the first psect-declaration before the
first data- or routine-declaration (external and forward types
excepted) and/or the first plit-expression in the module.
237 Exponent for floating or double floating literal out of range
Explanation:

Exponent value is too large for floating literal.

User Action:

Evaluate and correct the value of the

239 String exceeding implementation limits (<number>
truncated

exponent~

characters)

was

Explanation: The string-function (such as %EXACTSTRING)
exceeds
the implementation limit of 1000 characters for the length of a
sequence.
User Action:

Decrease the size of the string.

E-35

ERROR MESSAGES
240 <reserved-word> declaration is illegal in STRUCTURE declaration
Explanation: The declaration defined by the reserved-word
(such as OWN) is illegal in a structure-declaration.
User Action:

shown

Remove the illegal declaration.

242 Output formal parameter <name>
described in linkage

routine

declaration

was

not

Explanation: An output-parameter-location has not been specified
in
the
corresponding
linkage-declaration
for
the
output-formal-parameter shown.
User Action: Specify the output-parameter-location for
output-formal-parameter named in the routine-declaration.

the

243 Output actual parameter was not described in linkage
Explanation: An output-parameter-location has not been specified
in
the
corresponding
linkage-declaration
for
an
output-actual-parameter specified in the caller routine.
User Action: Specify an output-parameter-location
for
output-actual-parameter specified in the caller routine.

the

244 Name declared UNDECLARE is not defined:<name>
Explanation: An undeclare-declaration has been used with a
that has not been declared.
User Action:

E.l

name

Declare the name shown.

BLISS COMPILER FATAL ERRORS

The following fatal error messages indicate serious problems with the
environment and/or compiler.
When such a condition is detected,
compilation terminates immediately.
INTERNAL COMPILER ERROR
The compiler has failed an internal consistency check.
This
message may be followed by an error number. BLISS-32 then issues
a traceback printout. BLISS-36 is unable to issue a traceback.
Please submit an SPR and include a copy of the program that
generated this message.
INSUFFICIENT DYNAMIC MEMORY AVAILABLE
On the VAX, this error may indicate a bug in the compiler.
On
the DECsystem-IO and -20, the user's program may be too large to
compile.

E-36

ERROR MESSAGES
I/O ERROR ON INPUT FILE
An error occurred while accessing an input file.
This may be
preceded by other error messages which provide more specific
information about the error.
I/O ERROR ON OBJECT FILE
An error occurred while accessing the output object file.
This
may be preceded by other error messages which provide more
specific information about the error.
I/O ERROR ON LISTING FILE
An error occurred while accessing the output listing file.
This
may be preceded by other error messages which provide more
specific information about the error.
I/O ERROR ON LIBRARY FILE
An error occurred while accessing a BLISS precompiled library
file. This may be preceded by other error messages which provide
more specific information about the error.
LIBRARY PRE-COMPILATION EXCEEDS COMPILER LIMIT
A pre-compiled BLISS library cannot be larger than approximately
1024 (VAX) or 2048 (10/20) disk blocks; the library file will be
deleted.
MACRO OR STRUCTURE DECLARATION WITHIN STRUCTURE BODY
This is a
language.

permanent

implementation

restriction

the

BLISS

restriction

the

BLISS

REQUIRE DECLARATION WITHIN MACRO BODY
This is a
language.

permanent

implementation

FATAL ERROR IN COMMAND LINE
This message appears on VAX-VMS only, for BLISS-32 or BLISS-16.
The user's command line was improperly formed. A previous error
message provided additional information to describe what was
wrong.

E-37

ERROR MESSAGES
I/O ERROR DURING COMMAND LINE SCANNING
This message appears on TOPS-10 or TOPS-20 when a severe error is
encountered in parsing the command line.
NESTED EXPRESSION TOO DEEP.

SIMPLIFY AND RECOMPILE

The source program contains more than 64 levels of nested blocks,
each containing declarations.
UNRECOVERABLE SOURCE ERRORS.

CORRECT AND RECOMPILE

This message appears on VAX-VMS only, for BLISS-32 or BLISS-16.
Errors previously encountered by the compiler have confused it to
the point at which it cannot continue the compilation.

E-38

APPENDIX F
SAMPLE OUTPUT LISTING

The following pages contain the complete output listing for the module
TESTFACT. Chapter 2 examples use excerpts from this listing.

F-1

TESTFACT

5-0ct-1979 10:37:06
5-0ct-1979 10:37:00
0001
0002
0003
0004
0005
0006
0007
0008
0009
0010

VAX-11 Bliss-32 T2-617
Page
1
DBBl:[LEHOTSKY.DOC.UGUIDE]TESTFACT.BLI;2 (1)

MODULE TESTFACT (MAIN = MAINPROG)=
BEGIN
OWN
A,
B,
C;
ROUTINE !FACT (N)
BEGIN

OOll

0012
0013
0014
0015
0016

LOCAL
RESULT;
RESULT = l;
!NCR I FROM 2 TO .N DO
RESULT = .REULT*.I;
WARN#OOO
.................. 1 Ll: 0016
Undeclared name: REULT
0017
.RESULT
0018
END;

~
"ti

t"'
tr.J

.TITLE

TESTFACT

.PSECT

$OWN$,NOEXE,2

1-'rj

I
N

"ti

00000 A:
00004 B:
00008 C:

50
51
50
FS
Routine Size:

22 bytes,

OOOOG

CF
51

Routine Base:

01
01
06
51
AC

0000 00000 !FACT:
DO 00002
DO 00005
11 00008
CS OOOOA 1$:
F3 00010 2$:
04 00015

.BLKB
.BLKB
.BLKB

4
4
4

.EXTRN

REULT

.PSECT

$CODE$,NOWRT,2

.w:>RD
MOVL
MOVL
BRB
MULL3
AOBLEQ
RET

Save nothing
#1, RESULT
#1, I
2$
I, REULT, RESULT
N, I, 1$

$CODE$ + 0000

0019

Figure F-1: Sample Output Listing

t"'

H
00

zCi)
0009
0014
0015
0016
0015
0009

TESTFACT

5-0ct-1979 10:37:06
5-0ct-1979 10:37:00
0020
0021
0022
0023
0024
0025
0026

VAX-11 Bliss-32 T2-617
Page
2
DBBl:[LEHOTSKY.DOC.UGUIDE]TESTFACT.BLI;2 (2)

ROUTINE RFACT (N) =
IF .N GTR 1
THEN
.N * RFACT(.N - 1)
ELSE
l;

(/)

ttj

t-t

l:rj

c::

01
7E

04
EF

AC
AF
50
50

Routine Size:

26 bytes,

Routine Base:

0000 00000 RFACT:
Dl 00002
15 00006
C3 00008
FB OOOOD
C4 00011
04 00015

.WORD
CMPL
BLEQ
SUBL3
CALLS
MULL2
RET

Save nothing
N, #1
1$
#1, N, -(SP)
:fl:l, RF ACT
N, RO

AC
OE
01
01
AC
01

DO 00016 1$:

MOVL

#1, RO

;
i

04 00019

RET

$CODE$ + 0016

Figure F-1 (Cont.)

Sample Output Listing

0021
0022

i
i
i
i

0024

1-3
"ti

c::
t-3

t-t
H

(/)

t-3

0022
0021

TESTFACT

5-0ct-1979 10:37:06
5-0ct-1979 10:37:00
0027
0028
0029
0030
0031
0032
0033

VAX-11 Bliss-32 T2-617
Page
3
DBBl:[LEHOTSKY.DOC.UGUIDE]TESTFACT.BLI:2 (3}

ROUTINE MAINPROG =
BEGIN
A = IF ACT ( 5} :
B = RFACT(5}:
VMS wants a success return

l'.J)

END:

~
"'O
t-t

t;rj

0
t'Xj

I
..i::.

Routine Size:

28 bytes,

0034

END ELUDOM

CB
0000'

AF
CF

D3
0000'

AF
CF
50

Routine Base:

0000 00000 MAINPROG:
.WORD
PUSHL
05 DD 00002
01 FB 00004
CALLS
so DO 00008
MOVL
PUSHL
05 DD OOOOD
CALLS
01 FB OOOOF
MOVL
50 DO 00013
MOVL
01 DO 00018
RET
04 OOOlB

c:::

Save nothing
#5
#1, IFACT
RO, A
#5
#1, RFACT
RO, B
#1, RO

$CODE$ + 0030

Figure F-1 (Cont.):

Sample Output Listing

0027
0029
0030

1-3

"'O

c:::

1-3
t-t
H

l'.J)

1-3
0027

PSECT SUMMARY
Name

Attributes

Bytes

$OWN$
$CODE$

12
76

WRT,
NOWRT,

RD ,NOEXE,NOSHR,
RD , EXE,NOSHR,

LCL,
LCL,

REL,
REL,

CON,NOPIC,ALIGN(2)
CON,NOPIC,ALIGN(2)
00

Warnings:
Errors:

t'I

1
0

l:rj

t'rj

c::

COMMAND QUALIFIERS

t'I

BLISS /LIS/NOOB TESTFACT
Size:

76 code + 12 data bytes

Run Time:

00:01.2

H
00

Elapsed Time: 00:04.1
Memory Used: 10 pages
Compilation Complete

Figure F-1 (Cont.)

Sample Output Listing

INDEX

-A-

Abbreviations, summary, A-3
Abstraction mechanisms, 6-11
ADAWI, 4-6
ADDD, 4-6
ADDF, 4-6
ADDG, 4-7
ADDH, 4-7
ADDM, 4-7
Address calculations, 6-14
Address representation characters,
3-6
Address-relational operators,
6-16
Addresses, 6-16
Alignment attribute, 6-14
Allocation of scalar data, 6-12
Allocation-unit attribute, 6-13,
6-20
%ASCII, 6-5
ASHQ, 4-8
ASSEMBLER, 1-15
At sign (@), 3-4, 3-7
Attributes, nontransportable,
6-13

-BBICPSW, 4-8
BINARY, 1-15
Binding of names, 7-7
BISPSW, 4-8
Bit functions, 4-34
%BLISS 16, 6-6
%BLISS32, 6-6
%BLISS 36, 6-6
BLSCRF, 8-4
%BPADDR, 6-4
BPT, 4-8
%BPUNIT, 6-4
%BPVAL, 5-2, 6-4, 6-13, 6-25
BUGL, 4-9
BUGW, 4-9

-c%C, 6-5
CALLG, 4-9
CH$ALLOCATION, 6-23
CH$PTR, 6-24
Character sequence functions,
6-19
Character sequences (strings),
6-18
Characters, address
representation, 3-6
Characters, delimiters, 1-3

CHME, 4-10
CHMK, 4-10
CHMS, 4-10
CHMU, 4-10
CMPD, 4-10
CMPF, 4-11
CMPP, 4-11
/CODE, 1-8
CODE, 7-7
Code generation, 7-7
Coding errors, 5-3
computed routine calls, 5-4
in complex tests, 5-4
missing dots, 5-3
missing expression, 5-4
missing/disappearing code, 5-5
parentheses, 5-4
semicolon, 5-4
signed/unsigned fields, 5-5
use of complex macros, 5-5
useless value expressions, 5-3
valued/nonvalued routines, 5-3
Command syntax, summary, A-1
Command-line semantics, 1-3
Command-line syntax, 1-2
COMMENTARY, 1-15
Compilation
conditional, 6-5
costs, 5-1
summary, 2-2, 2-17
use of debug qualifiers, 3-14
Compile-time constant expressions,
6-4
Compiler
organization and processing,
7-1
output, 2-1
overview, 7-1
phases, 7-1
CODE, 7-7
DELAY, 7-6
FINAL, 7-8
FLOW, 7-3
LEXSYN, 7-2
OUTPUT, 7-8
TNBIND, 7-7
Complexity, language, 6-3
Concatenation, 1-3
Conditional compilation, 6-5
Control expressions, 6-16
CRC, 4-11
Cross-referencer, BLSCRF, 8-4
CVTDF, 4-12
CVTDI, 4-12
CVTDL, 4-12
CVTFD, 4-13
CVTFG, 4-13
CVTFH, 4-13

Index-1

INDEX
CVTFI, 4-13
CVTFL, 4-14
CVTGF, 4-14
CVTGL, 4-14
CVTHF, 4-15
CVTHL, 4-15
CVTID, 4-15
CVTIF, 4-15
CVTLD, 4-16
CVTLF, 4-16
CVTLH, 4-16
CVTLP, 4-16
CVTPL, 4-17
CVTPS, 4-17
CVTPT, 4-18
CVTRDH, 4-18
CVTRDL, 4-18
CVTRFL, 4-19
CVTSP, 4-19
CVTTP, 4-19
-D-

Data segments
changing contents of, 7-3
scope of names, 3-13
Data-name examination, 3-14
DCB BLOCK structure, 6-27
/DEBUG, 1-8
Debugger
command-line continuation, 3-15
commands, 3-4
commands, summary of, 3-15
contents operator symbol, 3-7
current location symbol, 3-6
default next-location value,
3-8
expression syntax, 3-4
last value displayed symbol,
3-7
range operator, 3-7
symbolic access, 3-14
Debugging, 3-2
Declarations, common, 5-1
Defaults
file type, 1-4
qualifiers, 1-16
DELAY, 7-6
Delimiters, 1-3
DIVD, 4-20
DIVF, 4-20
DIVG, 4-20
DIVH, 4-21
Dots, missing, 5-3
-E-

EDITPC, 4-21
EDIV, 4-21
EMUL, 4-22
Equivalencing, 6-17

Error messages, E-1
form of, 2-22
line indicator, 2-22
pointer, 2-22
ERRORS, 1-10
Errors
detected in LEXSYN phase, 7-2
discussion of, 5-3
from linker, 5-6
obscure messages, 5-6
terminal output, 2-2
user coding, 5-3
Examples
EXPAND MACROS, 2-17
LIBRARY, 2-1 7
machine-specific functions, 4-4
output listing, 2-16
object part, 2-8, 2-12
source part, 2-6
REQUIRE, 2-17
TRACE MACROS, 2-17
EXPAND MACROS, 1-13
example, 2-17
Expression operators, arithmetic,
3-5
Expressions
missing, 5-4
tree representations, 7-2
Extended arithmetic functions,
4-8
Extension attribute, 6-13
-FFFC, 4-22
FFS, 4-22
Field references, 3-9
Field selectors, 6-17, 6-32
Fields, (un)signed, 5-5
Figures
assembler input listing, F-8
compiler O/P listing sequence,
2-3
default object listing, F-5
default source listing, 2-16
error messages in source
listing, 2-23
listing header format, 2-4
output listing example showing
library/require file, 2-18
sample output listing, F-2
sample TPARSE program, 8-17
File type, defaults, 1-4
File-designator, 1-6
FINAL, 7-8
FLEX VECTOR, 6-16, 6-30, 6-33
FLow-; 7-3
Flow analysis, 7-3
Format
error messages, 2-22
listing header, 2-3
preface string, 2-5

Index-2

INDEX
Formatting
automated formatter, 8-6
PRETTY, 8-6

LOCC, 4-24
-M-

-G-

GEN VECTOR, 6-33
General qualifier, 1-7
Guidelines, transportability, 6-1
-HHALT, 4-23
HEADER, 1-13
Header format, 2-3
Heuristic phase of compiler, 7-6
-I-

Implementation limits
summary, D-1
INDEX, 4-23
Initial attribute, 6-22
Initial debug modes/types, 3-3
Initialization, 6-22
Input-spec, 1-2
Input/output support facility,
8-1
INSQHI, 4-23
INSQTI, 4-23
INS QUE, 4-24
Interface macros, 8-13
Isolation, 6-2
-L-

Language switch, 6-7
LEVEL, 1-11
Lexical analysis, 7-2
Lexical function
%BLISS, 6-6
LEXSYN, 7-2
Libraries
discussion of, 5-1
usage, 5-2
/LIBRARY, 1-6
LIBRARY, 1-13
example listing, 2-17
vs. REQUIRE, 5-2
Line indicator
in error message, 2-22
Link-command, 3-1
Linking, 3-1
errors from linker, 5-6
/LIST, 1-6
Listing header, 2-3
Literals, 6-4
numeric, 6-5
predeclared, 5-2, 6-4
string, 6-5
user-defined, 6-5
value definition, 6-5

Machine-code-list qualifier, 1-14,
2-7
Machine-specific functions, 6-3
conventions, 4-1
examples, 4-4
names
ADAWI, 4-6
ADDO, 4-6
ADDF, 4-6
ADDG, 4-7
ADDH, 4-7
ADDM, 4-7
ASHQ, 4-8
BICPSW, 4-8
BISPSW, 4-8
BPT, 4-8
BUGL, 4-9
BUGW, 4-9
CALLG, 4-9
CHME, 4-10
CHMK, 4-10
CHMS, 4-10
CHMU, 4-10
CMPD, 4-10
CMPF, 4-11
CMPP, 4-11
CRC, 4-11
CVTDF, 4-12
CVTDI, 4-12
CVTDL, 4-12
CVTFD, 4-13
CVTFG, 4-13
CVTFH, 4-13
CVTFI, 4-13
CVTFL, 4-14
CVTGF, 4-14
CVTGL, 4-14
CVTHF, 4-15
CVTHL, 4-15
CVTID, 4-15
CVTIF, 4-15
CVTLD, 4-16
CVTLF, 4-16
CVTLH, 4-16
CVTLP, 4-16
CVTPL, 4-17
CVTPS, 4-17
CVTPT, 4-18
CVTRDH, 4-18
CVTRDL, 4-18
CVTRFL, 4-19
CVTSP, 4-19
CVTTP, 4-19
DIVD, 4-20
DIVF, 4-20
DIVG, 4-20
DIVH, 4-21
EDITPC, 4-21

Index-3

INDEX
Machine-specific functions
names (Cont.)
EDIV, 4-21
EMUL, 4-22
FFC, 4-22
FFS, 4-22
HALT, 4-23
INDEX, 4-23
INSQHI, 4-23
INSQTI, 4-23
INS QUE, 4-24
LOCC, 4-24
MATCHC, 4-25
MFPR, 4-25
MOVC3, 4-25
MOVC5, 4-26
MOVP, 4-26
MOVPSL, 4-26
MOVTC, 4-27
MOVTUC, 4-27
MTPR, 4-27
MULD, 4-28
MULF, 4-28
MULG, 4-28
MULH, 4-29
NOP, 4-29
PROBER, 4-29
PROBEW, 4-30
REMQHI, 4-30
REMQTI, 4-30
REMQUE, 4-31
ROT, 4-31
SCANC, 4-31
SKPC, 4-32
SPANC, 4-32
SUBD, 4-32
SUBF, 4-33
SUBG, 4-33
SUBH, 4-33
SUBM, 4-34
TESTBITCC, 4-34
TESTBITCCI, 4-34
TESTBITCS, 4-34
TESTBITSC, 4-34
TESTBITSS, 4-34
TESTBITSSI, 4-34
XFC, 4-35
optimization, 4-4
register name parameters, 4-1
table of, 4-2
treatment during FLOW analysis,
7-4
use of registers, 4-5
/MACHINE CODE LIST, 1-14
Macros, 5-5, 6-3
conditional compilation, 6-5
Mark points, 7-5
MATCHC, 4-25
MFPR, 4-25
Miscellaneous functions, 4-23
Missing code, 5-5
Modularization, 6-3

Module, 6-3
Module switches, 6-6
Module template, C-1
MODULE.BL!, C-1
MOVC3, 4-25
MOVC5, 4-26
MOVP, 4-26
MOVPSL, 4-26
MOVTC, 4-27
MOVTUC, 4-27
MTPR, 4-27
MULD, 4-28
MULF, 4-28
MULG I 4-28
MULH, 4-29
-N-

Name binding, 7-7
Name, defined value, 6-17
Nontransportable attributes, 6-13
NOP, 4-29
NOSAFE, effect of, 7-5
Number-of-lines, 1-13
Numeric literals, 6-5
-0-

/OBJECT, 1-6
Object part of output, 2-7
Object-file, 3-1
Offset addressing, 6-21
Operating procedures
compiling, 1-1
debugging, 3-2
linking, 3-1
program execution, 3-2
Operators, arithmetic expression,
3-4
Optimization
missing code, 5-5
of code stream, 7-8
of machine-specific functions,
4-4
switches, 7-1
/OPTIMIZE I 1-11
effect of, 7-6
effect of /OPTLEVEL value, 7-8
effect of NOSAFE value, 7-5
Optimize qualifier, 1-11
/OPTLEVEL, effect of, 7-8
OUTPUT, 7-8
Output file production, 7-8
Output listing
complete listing, F-1
examples, 2-16
object part, 2-8
source part, 2-6
fields, 2-7
listing header format, 2-4
object part, 2-7
preface format (table), 2-5

Index-4

INDEX
Qualifiers (Cont.)
used for debugging, 3-14
/VARIANT, 1.:...8
Queue functions, 4-24
QUICK, 1-11
Quoted strings,·6~18
used as character strings, 6-19
used as numeric values, 6-18

Output listing (Cont.)
segments, 2-3
source part, 2-4
Output qualifier, 1-6
Output, on terminal, 2-2

-PPacked data initialization, 6-25
PAGE SIZE:lines, 1-13
Parameter validation functions,
4-29
Parameterization, 6-1, 6-26
Parentheses, 5-4
PIC code generation, 5-6
PLIT, 6-19
Pointer in error message, 2-22
Predeclared literals, 5-2, 6-4
Preface string, 2-5
Preface string format, 2-5
PRETTY, 8-6
breaking lines, 8-10
command line format, 8-6
command semantics, 8-6
comments, 8-10
formatting options, 8-7
hints on use, 8-10
macros, 8-12
PLITs, 8-12
PROBER, 4-29
PROBEW, 4-30
Processor register functions,
4-27
Program execution, 3-2
Program status functions, 4-26
Programming considerations, 5-1
centralized common declarations,
5-1
compilation costs, 5-1, 5-2
efficiency of library files,
5-1
symbol tables, 5-1

-QQualifiers, 1-5
abb~eviations,

A-3
/CODE, 1-8
correspondence to switch names,
1-16
/DEBUG, 1-8
default summary, A-3
defaults, 1-16
/LIBRARY, 1-6
/LIST, 1-6
/MACHINE CODE LIST, 1-14
/OBJECT,-1-6 /OPTIMIZE, 1-11
positive and negative, 1-17
/SOURCE LIST, 1-13
/TERMINAL, 1-9
/TRACEBACK, 1-8

-RRecord Management Services, 8-lS
Register names
as mach-spec-func parameters,
4-1
Relational ~pera~ors, 6-16
REMQHI, 4-30
REMQTI, 4-30
REMQUE, 4-31
REQUIRE
example listing, 2~17
vs. LIBRARY, 5-2
REQUIRE declaration
files invoked by, 5-2
REQUIRE files, 6-3, 6-9
search rules, 6-10
Reserved names, 6-8
RMS-32, 8-15
ROT, 4-31
Routines, 6-11
computed calls, 5~4

-sSAFE, 1-11
Sample program, 8-14
Scalar PLIT ite~s~ 6~20·
SCANC, 4-31
Scope of names, 3-13
Search rules, 6-10
Segments of output listing, 2~3
Semicolon
used as expression terminator,
5-4
used as ~ark point, 7-6
Sign extension rules
consistent us~ of, 5-5
Simplicity, 6-3
SKPC, 4-32
SOURCE, 1-13
Source part of output, 2-4
Source reformatte~, a.:...6
Source-line debugglng~ 3-13
Source-list qualifier~ 1-13
/SOURCE LIST, 1-13
SPACE, T-11
SPANC, 4-32
Special characters
in address expressions, 3-5
SPEED, 1-11
STATISTICS, 1-10
String functions, 4-27

Index-5

INDEX
String literal in PLITs, 6-20
String literals~ 6-5
Strings (character sequences) ,
6-18
Structure references, 3-10
for REF data segments, 3~12
Structures, 6-29
SUBD, 4-32
SUBF, 4-33
SUBG, 4-33
SUBH, 4-33
SUBM, 4-34
Summaries
abbreviations, A-3
command syntax, A-1
compilation, 2-2, 2-17
debugger commands, 3-15
implementation limits, D-1
machine-specific functions, 4-2
qualifier defaults, A-3
qualifier vs. switch names,
1-16
switch effects, 7-8
user coding errors, 5-3
Switches
LANGUAGE, 6-6
module, 6-6
NOSAFE, effect of, 7-5
/OPTIMIZE, effect of, 7-6
/OPTLEVEL, effect of, 7-8
/ZIP 1 effect of, 7-7
SWITCHES declaration, 5-2, 7-1
Symbol table, 5-1
entries for declarations, 7-2
SYMBOLIC, 1-15
Symbols
command-line continuation (-),
3-15
contents operator, 3-6
contents operator {.), 3-4, 3-7
current location (.), 3-6
current location contents ( •• ),
3-6
debug indirect command file (@),
3-15
fetch operator (.), 3-6
indirect operator, 3-6
indirect operator (not@), 3-4
last value displayed (\), 3-7
previous location (A), 3-4, 3-6
range operator (:), 3-7
Symbols, as delimiters, 1-3
Syntactic analysis, 7-2
Syntax, command-line, 1-2
System services, 8-13
-T-

Tables
address representation
characters, 3-6

Tables (Cont.)
arithmetic expression operators,
3-5
correspondence between
qualifier
and switch names, 1-16
machine-specific functions, 4-2
source listing preface format,
2-5
/TERMINAL, 1-9
Terminal output, 2-2
Terminal qualifier, 1-9
TESTBITCC, 4-34
TESTBITCCI, 4-34
TESTBITCS, 4-34
TESTBITSC, 4-34
TESTBITSS, 4-34
TESTBITSSI, 4-34
TNBIND, 7-7
Tools
BLSCRF, 8-4
PRETTY, 8-6
transportability, 6-4
TUTIO, 8-12
XPORT, 8-1
TRACE MACROS, 1-13
example, 2-17
/TRACEBACK, 1-8
Transportability
key to, 6-11
techniques, 6-11
tools, 6-4
Transportability guidelines, 6-1
address calculation, 6-15
allocation attribute, 6-13
attributes, 6-13
character sequences, 6-19
checking, 6-7
control'~xpressions, 6-17
declarations, 6-14
field selectors, 6-33
isolation, 6-2
literals, 6-4
modularization, 6-3
module switches, 6-6
relational operators, 6-17
REQUIRE and LIBRARY files, 6-9
reserved names, 6-8
simplicity, 6-3
string literals, 6-18
string literals in PLITs, 6-22
strings, 6-19
Transportable
control expressions, 6-17
declarations, 6-13
expressions, 6-15
structures, 6-16, 6-29
Transportable tools, 8-1
TUTIO, 8-12
Tutorial terminal I/O package,
8-12

Index-6

INDEX

-uUNIQUE NAMES, 1-15
UPLIT,-6-19
%UPVAL, 6-4, 6-15, 6-21

-vValues
abbreviations, A-3
changing of, 7-3
code
ASSEMBLER, 1-15, 2-7
BINARY, 1-15, 2-7
COMMENTARY, 1-15
NOASSEMBLER, 2-7
NOCOMMENTARY, 2-7
SYMBOLIC, 1-15
UNIQUE NAMES, 1-15
optimize_
LEVEL, 1-11
QUICK, 1-11
SAFE, 1-11
SPACE, 1-11
SPEED, 1-11
source

Values (Cont.)
EXPAND MACROS, 1-13
HEADER-; 1-13
LIBRARY, 1-13
PAGE SIZE:lines, 1-13
SOURCE, 1-13
TRACE MACROS, 1-13
terminal
ERRORS, 1-10
STATISTICS, 1-10
/VARIANT, 1-8
VAX/VMS interfaces, 8-17
VAX/VMS System Services, 8-13

-wWeak attribute, 6-14

-xXFC, 4-35
XPORT, 8-1

-z/ZIP, effect of, 7-7

Index-7

VAX-11 BLISS-32
User's Guide
AA-H322C-TE
READER'S COMMENTS
NOTE: This form is for document comments only. DIGITAL will use comments submitted on this form at the
company's discretion. If you require a written reply and are eligible to receive one under Software
Performance Report (SPR) service, submit your comments on an SPR form.

Did youfind this manual understandable, usable, and well organized? Please make suggestions for improvement.

Did you find errors in this manual? If so, specify the error and the page number.

Please indicate the type of user/reader that you most nearly represent.

D Assembly language programmer
D
D
D
D

Higher-level language programmer
Occasional programmer (experienced)
User with little programming experience
Student programmer
D Other (please specify)

Organization
Street
State _ _ _ _ _ _ Zip Code - - - - - or Country

Do Not Tear- Fold Here and Tape -

mnmnomn

111111

BUSINESS REPLY MAIL
FIRST CLASS PERMIT N0.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

BSSG PUBLICATIONS ZK1-3/J35
DIGITAL EQUIPMENT CORPORATION
110 SPIT BROOK ROAD
NASHUA, NEW HAMPSHIRE 03061

·. ·"·
-

Do Not Tear - Fold Here

No Postage
Necessary
if Mailed in the
United States