Digital PDFs

AA-H322E-TE

May 1987

408 pages

Original

10MB

Document:	BLISS-32 User Manual
Order Number:	AA-H322E-TE
Revision:	000
Pages:	408
Original Filename:

OCR Text

BLISS-32 User Manual
Order Number: AA-H322E-TE

May 1987
This document describes the BLISS-32 compiler and provides basic information about linking, executing, and debugging BLISS-32 programs. It also
describes BLISS-32 machine-specific functions, BLISS tools, and other topics
related to BLISS-32 programming.

Revision/Update Information:

This book supersedes the BLISS-32 User's
Guide (Order No. AA-H322D-TE).

Operating System and Version: VMS Version 4.2 or higher
Software Version:

digital equipment corporation
maynard, massachusetts

BLISS-32 Version 4.3

First Printing, January 1980
Revised, February 1982
Revised, November 1983
Revised, May 1987
The information in this document is subject to change without notice and
should not be construed as a commitment by Digital Equipment Corporatior
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 m
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 ©1980, 1982, 1983, 1987 by Digital Equipment Corporation
All 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
DEC/MMS
DECnet
DECsystern-10
DECSYSTEM-20
DECUS
DEC writer

DIBOL
EduSystern
IAS
MASS BUS
PDP
PDT
RSTS
RSX

UNIBUS
VAX
VAXcluster
VMS
VT

tDDrnDD~D
ZK4:

This document was prepared using an in-house documentation production
system. All page composition and make-up was performed by TEX, the
typesetting system developed by Donald E. Knuth at Stanford University. ·
is a trademark of the American Mathematical Society.

Contents
PREFACE

xix

SUMMARY OF TECHNICAL CHANGES

xxiii

CHAPTER 1

OPERATING PROCEDURES

1-1

1.1

COMPILING A BLISS MODULE
1.1.1
Command-Line Syntax
1.1.2
Command-Line Semantics

1-2
1-3
1-3

1.2

FILE SPECIFICATIONS

1-4

1.3

COMMAND-LINE QUALIFIERS
1.3.1
/CHECK Qualifier
1.3. 1. 1
Syntax• 1-7
1.3.1.2
Defaults • 1-7
1.3.1.3
Semantics • 1-8
1.3.2
/CROSS-REFERENCE Qualifier
1.3.2.1
Syntax• 1-9
1.3.2.2
Defaults • 1-9
1.3.2.3
Semantics • 1-10
1.3.3
General Qualifiers
1.3.3.1
Syntax • 1-11
1.3.3.2
Defaults • 1-11
1.3.3.3
Semantics • 1-11
1.3.3.4
Discussion • 1-12
1.3.4
/MACHINE_CODE_LIST Qualifier
1.3.4.1
Syntax • 1- 13
1.3.4.2
Defaults • 1-14
1.3.4.3
Semantics • 1-14
1.3.5
/OPTIMIZE Qualifier
1.3.5.1
Syntax • 1- 16
1.3.5.2
Defaults • 1-16
1.3.5.3
Semantics • 1-17

1-6
1-7

1-8

1-10

1-13

1-15

iii

1.3.6

1.3.7

1.3.8

1.3.9
1.3.10
1.3.11
1.3.12

1-18

1-20

1-23

1-24
1-25
1-26
1-26

COMPILER OUTPUT

2-1

2.1

TERMINAL OUTPUT

2-2

2.2

OUTPUT LISTING
2-3
2.2.1
Listing Header
2-5
2.2.2
Source Listing
2-6
2.2.3
Object Listing
2-10
2.2.3.1
Default Object Listing • 2-12
2.2.3.2
Assembler Input Listing • 2-12
2.2.4
Source Part Options
2-19
2.2.4.1
Default Source Listing • 2-20
2.2.4.2
Listing with LIBRARY and REQUIRE Information • 2-20
2.2.4.3
Listing with Macro Expansions• 2-20
2.2.4.4
Listing with Macro Tracing • 2-20

2.3

CROSS-REFERENCE LISTING
2.3.1
Cross-Reference Header
2.3.2
Cross-Reference Entries
2.3.3
Output Listing with Cross-Reference Listing

2-27
2-27
2-27
2-34

2.4

COMPILATION SUMMARY

2-39

CHAPTER 2

Output Qualifiers
1.3.6.1
Syntax • 1-19
1.3.6.2
Defaults • 1-1 9
Semantics• 1-20
1.3.6.3
/SOURCE_LIST Qualifier
1.3.7.1
Syntax• 1-21
1.3.7.2
Defaults • 1-21
Semantics• 1-22
1.3.7.3
/TERMINAL Qualifier
1.3.8.1
Syntax• 1-23
1.3.8.2
Defaults • 1-23
Semantics• 1-24
1.3.8.3
Qualifier Names Versus Switch Names
Qualifiers and Default Settings
Positive and Negative Forms of Qualifiers
Abbreviations of Qualifier and Value Names

2.5

CHAPTER 3
3.1

ERROR MESSAGES

2-39

LINKING, EXECUTING, AND DEBUGGING

3-1

LINKING

3-1
3-2
3-2

3.1.1
3.1.2

LINK Command Syntax
LINK Command Semantics

3.2

EXECUTING A LINKED PROGRAM

3-2

3.3

DEBUGGING
Initialized Modes and Types
Debugger Commands and Expression Syntax
Operators in Arithmetic Expressions
Special Characters in Address Expressions
3.3.4. 1
Current Location Symbol (.) • 3-7
3.3.4.2
Last Value Displayed Symbol(\)• 3-8
3.3.4.3
Contents Operator (.) • 3-9
3.3.4.4
Range Operator (:) • 3-9
3.3.4.5
Default Next Location Value• 3-10
3.3.5
Field References
3.3.6
Structure References
3.3.7
REF Strµcture References
3.3.8
Scope of Names
3.3.9
Source-Line Debugging
3.3.10
Effect of Compilation and Link-Time Qualifiers
3.3.11
Debugger Command Summary

3-3

3.3.1
3.3.2
3.3.3
3.3.4

3-4
3-4
3-5
3-6

3-11

3-13
3-16
3-17
3-18
3-18

3-19

MACHINE-SPECIFIC FUNCTIONS

4-1

4.1

ADAWl-ADD ALIGNED WORD INTERLOCKED

4-9

4.2

ADDO-ADD D-FLOATING OPERANDS

4-9

4.3

ADDF-ADD F-FLOATING OPERANDS

4-10

4.4

ADDG-ADD G-FLOATING OPERANDS

4-10

4.5

ADDH-ADD H-FLOATING OPERANDS

4-11

4.6

ADDM-ADD MULTIWORD OPERANDS

4-11

4.7

ASHP-ARITHMETIC SHIFT AND ROUND PACKED

4-12

4.8

ASHQ-ARITHMETIC SHIFT QUAD

4-13

4.9

BICPSW-BIT CLEAR PSW

4-14

4.10

BISPSW-BIT SET PSW

4-14

4.11

BPT-BREAK POINT TRAP

4-14

4.12

BUGL-BUGCHECK WITH LONG OPERAND

4-15

4.13

BUGW-BUGCHECK WITH WORD OPERAND

4-15

4.14

CALLG-CALL WITH GENERAL PARAMETER LIST

4-16

4.15

CHMX-CHANGE MODE

4-17

4.16

CMPC3-COMPARE CHARACTERS 3 OPERAND

4-17

CHAPTER 4

4.17

CMPC5-COMPARE CHARACTERS 5 OPERAND

4-18

4.18

CMPD-COMPARE D-FLOATING OPERANDS

4-19

4.19

CMPF-COMPARE F-FLOATING OPERANDS

4-20

4.20

CMPG-COMPARE G-FLOATING OPERANDS

4-21

4.21

CMPH-COMPARE H-FLOATING OPERANDS

4-21

4.22

CMPM-COMPARE MULTIWORD OPERANDS

4-22

4.23

CMPP-COMPARE PACKED

4-23

4.24

CRC-CYCLIC REDUNDANCY CHECK

4-24

4.25

CVTDF-CONVERT D-FLOATING TO F-FLOATING

4-24

4.26

CVTDl-CONVERT D-FLOATING TO INTEGER

4-25

4.27

CVTDL-CONVERT D-FLOATING TO LONG

4-25

4.28

CVTFD-CONVERT F-FLOATING TO D-FLOATING

4-26

4.29

CVTFG-CONVERT F-FLOATING TO G-FLOATING

4-26

4.30

CVTFH-CONVERT F-FLOATING TO H-FLOATING

4-27

4.31

CVTFl-CONVERT F-FLOATING TO INTEGER

4-27

4.32

CVTFL-CONVERT F-FLOATING TO LONG

4-28

4.33

CVTGF-CONVERT G-FLOATING TO F-FLOATING

4-28

4.34

CVTGH-CONVERT G-FLOATING TO H-FLOATING

4-29

vii

viii

4.35

CVTGL-CONVERT G-FLOATING TO LONG

4-29

4.36

CVTHF-CONVERT H-FLOATING TO F-FLOATING

4-30

4.37

CVTHG-CONVERT H-FLOATING TOG-FLOATING

4-30

4.38

CVTHL-CONVERT H-FLOATING TO LONG

4-30

4.39

CVTID-CONVERT INTEGER TO D-FLOATING

4-31

4.40

CVTIF-CONVERT INTEGER TO F-FLOATING

4-31

4.41

CVTLD-CONVERT LONG TOD-FLOATING

4-32

4.42

CVTLF-CONVERT LONG TO F-FLOATING

4-32

4.43

CVTLH-CONVERT LONG TO H-FLOATING

4-33

4.44

CVTLP-CONVERT LONG TO PACKED

4-33

4.45

CVTPL-CONVERT PACKED TO LONG

4-34

4.46

CVTPS-CONVERT PACKED TO LEADING SEPARATE
NUMERIC

4-34

4.47

CVTPT-CONVERT PACKED TO TRAILING NUMERIC

4-35

4.48

CVTRDL-CONVERT ROUNDED D-FLOATING TO LONG

4-37

4.49

CVTRFL-CONVERT ROUNDED F-FLOATING TO LONG

4-37

4.50

CVTRGL-CONVERT ROUNDED G-FLOATING TO LONG

4-38

4.51

CVTRHL-CONVERT ROUNDED H-FLOATING TO LONG

4-38

4.52

CVTSP-CONVERT LEADING SEPARATE TO PACKED

4-39

4.53

CVTIP-CONVERT TRAILING NUMERIC TO PACKED

4-40

4.54

DIVD-DIVIDE D-FLOATING OPERANDS

4-41

4.55

DIVF-DIVIDE F-FLOATING OPERANDS

4-41

4.56

DIVG-DIVIDE G-FLOATING OPERANDS

4-42

4.57

DIVH-DIVIDE H-FLOATING OPERANDS

4-42

4.58

EDITPC-EDIT PACKED TO CHARACTER

4-43

4.59

EDIV-EXTENDED-PRECISION DIVIDE

4-44

4.60

EMUL-EXTENDED-PRECISION MULTIPLY

4-45

4.61

FFC AND FFS-FIND AND MODIFY OPERATIONS

4-45

4.62

HALT-HALT PROCESSOR

4-46

4.63

INDEX-INDEX CALCULATION

4-46

4.64

INSQHI AND INSQTl-INSERT ENTRY IN QUEUE.
INTERLOCKED

4-47

4.65

INSQUE-INSERT ENTRY IN QUEUE

4-48

4.66

LOCC-LOCATE CHARACTER

4-49

4.67

MATCHC-MATCH CHARACTERS

4-49

4.68

MFPR-MOVE FROM PROCESSOR REGISTER

4-51

4.69

MOVC3-MOVE CHARACTER 3 OPERAND

4-51

4.70

MOVC5-MOVE CHARACTER 5 OPERAND

4-52

4.71

MOVP-MOVE PACKED

4-53

4.72

MOVPSL-MOVE FROM PSL

4-54

4.73

MOVTC-MOVE TRANSLATED CHARACTERS

4-54

4.74

MOVTUC-MOVE TRANSLATED UNTIL CHARACTER

4-56

4.75

MTPR-MOVE TO PROCESSOR REGISTER

4-57

4.76

MULD-MULTIPLY D-FLOATING OPERANDS

4-57

4.77

MULF-MULTIPLY F-FLOATING OPERANDS

4-58

4.78

MULG-MULTIPLY G-FLOATING OPERANDS

4-59

4.79

MULH-MULTIPLY H-FLOATING OPERANDS

4-59

4.80

NOP-NO OPERATION

4-60

4.81

PROBER-PROBE READ ACCESSIBILITY

4-60

4.82

PROBEW-PROBE WRITE ACCESSIBILITY

4-61

4.83

REMQHI AND REMQTl-REMOVE ENTRY FROM QUEUE,
INTERLOCKED

4-61

4.84

REMQUE-REMOVE ENTRY FROM QUEUE

4-62

4.85

ROT-ROTATE A VALUE

4-63

4.86

SCANC-SCAN CHARACTERS

4-63

4.87

SKPC-SKIP CHARACTER

4-64

4.88

SPANC-SPAN CHARACTERS

4-65

4.89

SUBD-SUBTRACT D-FLOATING OPERANDS

4-66

4.90

SUBF-SUBTRACT F-FLOATING OPERANDS

4-67

4.91

SUBG-SUBTRACT G-FLOATING OPERANDS

4-67

4.92

SUBH-SUBTRACT H-FLOATING OPERANDS

4-68

4.93

SUBM-SUBTRACT MULTIWORD OPERANDS

4-68

4.94

TESTBITX-TEST AND MODIFY OPERATIONS

4-69

4.95

XFC-EXTENDED FUNCTION CALL

4-70

PROGRAMMING CONSIDERATIONS

5-1

LIBRARY AND REQUIRE FILE DIFFERENCES

5-1

FREQUENT BLISS CODING ERRORS
Missing Dots
Valued and Nonvalued Routines
Semicolons and Values of Blocks
Complex Expressions Using AND, OR, and NOT
Computed Routine Calls
Signed and Unsigned Fields
Complex Macros
Missing Code
Using the Built-In PC
Indexed Loop Coding Error

5-3
5-4
5-4
5-5
5-5
5-5
5-6
5-7
5-7
5-8
5-9

CHAPTER 5
5.1
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.2.9
5.2.10

5.3

LINKER ERROR MESSAGES

5-10

5.4

OBSCURE ERROR MESSAGES

5-10

5.5

POSITION-INDEPENDENT CODE GENERATION

5-10

5.6

ADVANCED USE OF BLISS MACROS
5.6.1
Advantageous Use of Machine Dependencies
5.6.2
Using String Instructions
5.6.3
Dealing with Enumeration Types
5.6.3. 1
The SET Data Type • 5-13
5.6.3.2
Creating a Set • 5-14
5.6.3.3
Placing Elements in Sets • 5-16
5.6.3.4
Membership in a Set • 5-17

5-10
5-11
5-11
5-13

CHAPTER 6 TRANSPORTABILITY GUIDELINES
6.1

INTRODUCTION

6-2

6.2

GENERAL STRATEGIES
6.2.1
Isolation
6.2.2
Simplicity

6-3
6-3
6-4

6.3

TOOLS
6.3.1

6-4
6-4

6.3.2
6.3.3
6.3.4
6.3.5
6.3.6
6.4

xii

6-1

Literals
6.3. 1.1
Predeclared Literals • 6-5
6.3. 1.2
User-Defined Literals • 6-6
Macros and Conditional Compilation
Module Switches
Reserved Names
REQUIRE and Library Files
Routines

TECHNIQUES FOR WRITING TRANSPORTABLE PROGRAMS
6.4.1
Allocation of Data
6.4. 1. 1
Problem Origin • 6-14
6.4. 1.2
Transportable Declarations • 6-15

6-7
6-8
6-10
6-11
6-13
6-14
6-14

6.4.2

6.4.3

6.4.4

6.4.5

CHAPTER 7
7.1

7.2

Data Addresses
6-17
6.4.2.1
Addresses and Address Calculations • 6-17
6.4.2.2
Relational Operators and Control Expressions • 6-19
6.4.2.3
BUSS-10 Addresses Versus BUSS-36
Addresses• 6-20
6-21
Data Character Sequences
6.4.3.1
Quoted Strings Used as Numeric Values • 6-21
6.4.3.2
Quoted Strings Used as Character Strings • 6-23
PLITs and Initialization
6-23
6.4.4.1
PUTs in General• 6-23
6.4.4.2
Scalar PUT Items • 6-24
6.4.4.3
String Literal PUT Items • 6-24
6.4.4.4
Initialization Example • 6-26
6.4.4.5
Initializing Packed Data • 6-30
Structures and Field Selectors
6-34
6.4.5.1
Structures • 6-35
6.4.5.2
FLEX_VECTOR• 6-35
6.4.5.3
Field Selectors• 6-38
6.4.5.4
GEN_VECTOR • 6-39
6.4.5.5
Summary of Structures and Field Selectors • 6-42

COMPILER OVERVIEW AND OPTIMIZATION SWITCHES

7-1

COMPILER PHASES·
7 .1.1
Lexical and Syntactic Analysis Phase
7. 1 .2
Flow Analysis Phase
7.1.2.1
Knowing When a Value Changes• 7-4
7 .1.2.2
Accounting for Changes• 7-6
7.1.3
Heuristic Phase
7.1.4
Temporary Name Binding Phase
7.1.5
Code Generation Phase
7.1.6
Code Stream Optimization Phase
7.1.7
Output File Production Phase

7-2
7-2
7-3

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

SUMMARY OF SWITCH EFFECTS

7-10

xiii

CHAPTER 8 TOOLS, LIBRARIES, AND SYSTEM INTERFACES

8-1

8.1

VAX SOURCE CODE ANALYZER (SCA)

8-1

8.2

TUTORIAL TERMINAL INPUT/OUTPUT PACKAGE (TUTIO)

8-2

8.3

VMS SYSTEM SERVICES INTERFACE
8.3.1
Sample Program Using VMS System Services
8.3.2
Common Errors in Using System Services

8-3
8-4
8-5

8.4

RECORD MANAGEMENT SERVICES INTERFACE
8.4.1
Using VAX RMS Macros
8.4.2
Sample Routine Using VAX RMS

8-5
8-6
8-6

8.5

OTHER VMS INTERFACES
8.5.1
LIB Interface
8.5.2
TPAMAC Interface

8-7
8-7
8-8

CHAPTER 9 BLISS-32 CODE EXAMPLES

xiv

9-1

9.1

EXAMPLE 1: THE ALPHA PROGRAM
Module ALPHA
9.1.1
Routine SORT_CHARS
9.1.2
Routine ALPHA_SORT
9.1.3
Cell-Handling Package
9.1.4
Macro REL_CELL
9.1.5
Macro I NS_CELL
9.1.6
Macro GET_CELL
9.1.7
Macro REM_CELL
9.1.8

9-1
9-2
9-4
9-6
9-8
9-10
9-11
9-12
9-13

9.2

EXAMPLE 2: THE CALC PROGRAM
9.2.1
Module CALCULATE
Routine CALC_DRIVER
9.2.2
Routine MAIN
9.2.3
Routine READEXPRESSION
9.2.4
Routine READTERM
9.2.5

9-13
9-15
9-16
9-18
9-19
9-20

9.2.6
9.2.7
9.2.8

9.2.9

APPENDIX A

Routine READFACTOR
Routine READNUMBER
Routine READCHAR
Routine CATCH_ERRORS

9-21
9-23

9-24
9-25

SUMMARY OF COMMAND SYNTAX

A-1

A.1

COMMAND-LINE SYNTAX

A-1

A.2

FILE SPECIFICATION SUMMARY

A-2

A.3

QUALIFIER SYNTAX

A-2

A.4

QUALIFIER DEFAULTS

A-4

A.5

ABBREVIATIONS

A-5

APPENDIX B SUMMARY OF FORMATTING RULES

B-1

APPENDIX C MODULE TEMPLATE

C-1

C.1

MODULE PREFACE

C-2

C.2

DECLARATIVE PART OF MODULE

C-3

C.3

EXECUTABLE PART OF MODULE

C-4

C.4

CLOSING FORMAT

C-5

APPENDIX D IMPLEMENTATION LIMITS

D-1

D.1

BLISS-32 CONSTRUCTS

D-1

D.2

SYSTEM INTERFACES

D-2

APPENDIX E ERROR MESSAGES

E-1

E.1

BLISS COMPILER FATAL ERRORS

E-45

APPENDIX F SAMPLE OUTPUT LISTING

F-1

APPENDIX G OPTIONAL PROGRAMMING PRODUCTIVITY TOOLS

G-1

G.1

G.2

xvi

USING LSE WITH BLISS-32
G.1.1
Entering Source Code Using Tokens and
Placeholders
G.1.2
Compiling Source Code
G.1.3
Examples
G.1 .4
Module Declaration
G.1.4. 1
Routine Declaration • G-7
G. 1.4.2
IF Statement • G-9
G. 1.4.3
Select Expression • G-10
G.1.4.4
CH$COMPARE Function• G-12

G-1
G-2
G-4
G-5
G-6

USING THE VAX SOURCE CODE ANALYZER
G-14
G.2.1
Setting Up an SCA Environment
G-15
G.2.1.1
Creating an SCA Library• G-17
G.2. 1.2
Generating Data Analysis Files • G-17
G.2. 1.3
Loading Data Analysis Files into a Local Library • G-17
G.2. 1.4
Selecting an SCA Library • G-18
G.2.2
Using SCA for Cross-Referencing
G-18

INDEX

EXAMPLES
2-1

Example of Error Messages in Source Listing

2-43

8-1

Sample TPARSE Program

8-9

Compiler Output Listing Sequence

2-4

FIGURES
2-1
2-2

Listing Header Format

2-5

2-3

Default Object Listing Example

2-13

2-4

Assembler Input Listing Example

2-16

2-5

Default Source Listing Example

2-21

2-6

Output Listing with LIBRARY and REQUIRE File Data

2-22

2-7

Output Listing with Macro Expansion Data

2-24

2-8

Output Listing with Macro Expansion and Tracing Data

2-25

2-9
F-1

Output Listing with-Cross-Reference Listing Included
Sample Output Listing

2-35
F-2

G-1

Use of LSE and SCA for Multimodular Development

G-16

Correspondence Between Qualifier and Switch Names

1-25

TABLES
1-1
2-1

Format of Preface String in Source Listing

2-7

2-2

Symbol Type Abbreviatipns

2-28

3-1

Arithmetic Expression Operators
Address Representation Characters

3-6

3-2
4-1

Machine-Specific Functions

4-3

3-7

xvii

Preface

Manual Objectives
This manual is a user's guide for the VAX BLISS-32 compiler running
under the 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 VMS operating system, its
command language, and its file system conventions.

Structure of This Document
Chapters 1 through 3 describe basic operating instructions.
•
•

•

Chapter 1 gives procedures for compiling a BLISS-32 program and
describes the command qualifiers.
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 9 supply supplementary programming information.
•
•
•

Chapter 4 defines the VAX machine-specific functions.
Chapter 5 discusses programming considerations, such as using
LIBRARY and REQUIRE facilities.
Chapter 6 gives guidelines for writing transportable BLISS-32 programs.
xix

•
•
•

Chapter 7 describes compiler architecture and the effects of the
command qualifiers related to optimization.
Chapter 8 describes some tools related to BLISS-32 programming.
Chapter 9 provides coding examples in the form of two complete and
annotated programs.

The appendixes contain reference material.
•
•
•
•
•
•
•

Appendix A summarizes the command syntax, including the command
qualifiers and their defaults and abbreviations.
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.
Appendix G describes how to use related development tools.

Associated Documents
The VAX Information Directory lists and describes all of the documents
you may need to refer to in the course of building and executing a BLISS
program.
Additional documentation that is either directly or indirectly relevant to
BLISS programming includes the following:

BLISS language usage:

BLISS Language Reference Manual
(AA-H275D-TK)

BLISS syntax summary:

BLISS Pocket Guide (AV-H289D-TK)

Program linking and execution:

VAX/VMS Linker Reference Manual
(AA-Z420A-TE)

VAX/VMS DCL Dictionary (AA-Z200C-TE)
Symbolic debugging:

VAX/VMS Debugger Reference Manual
(AA-Z411C-TE)

System services:

VAX/VMS System Services Reference Manual
(AA-ZSOlC-TE)

VAX Record Management Services Reference
Manual (AA-Z503B-TE)

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 notations used in this manual:
{ item-1 I item-2 I item-3 }

~tem-1 }

{

item-2
item-3

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

item ...

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

item, ...

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

item+ ...

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

•••

In addition, the red portions of a syntax line or system-user dialogue
identify information entered in by the user.

xxi

Summary of Technical Changes
This manual provides BLISS-32 user information for Version 4.3 of the
BLISS-32 compiler. This list summarizes technical changes, additions, and
deletions to the guide since Version 4.0.
•
•
•

/ANAL YSIS_DATA has been added as an output-qualifier for the
BLISS-32 command line.
The VAX Source Code Analyzer (SCA) programming tool makes the
/MASTER_CROSS-REFERENCE qualifier and BCREF obsolete.
XPORT material has been removed; this information is available from
the DECUS library.

xxiii

Chapter 1

Operating Procedures
This chapter describes 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
VMS Linker, and execute the linked image. The command sequence tq do
this is as follows:
$ 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 compiling and linking 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.

Operating Procedures

1-1

1.1 Compiling a BLISS Module
To compile a BLISS module, issue the DCL command BLISS, followed
by a BLISS command line. The command line consists of one or more
source file names optionally preceded by command-line qualifiers. (Refer
to Section 1.1.1.) Some BLISS command line examples follow:
•

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 BLISS compiler produces the listing
file MYPROG.LIS.
To produce an object file with a name different from that of the source
file, give the· name in the command as follows:
$ 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 file ALPHA.R32 and produces
the library file ALPHA.L32.
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 file
ALPHA.OBJ; then BETA.B32, producing BETA.OBJ; and then
GAMMA.B32, producing GAMMA.OBJ.
To compile a module that consists of several pieces, each in a separate
file, use the concatenation indicator ( + ):
$ BLISS ALPHA+BETA+GAMMA

1-2

Operating Procedures

The BLISS compiler compiles the source module formed by the
concatenation of ALPHA.B32, BETA.B32, and GAMMA.B32, and
produces the single object file ALPHA.OBJ.

1.1.1

Command-Line Syntax
compilation-request

$ BLISS [/qualifier ... ] input-spec, ...

input-spec

file-spec[+ ... ] [/qualifier ... ]

qualifiers

check qualifier
general qualifiers
machine-code-list qualifier
optimize qualifier
output qualifiers
reference qualifier
source-list qualifier
terminal qualifier

The dollar sign ( $ ) represents the DCL prompt. 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 blisscommand-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 you use a qualifier to change the compiler's behavior, the output
from an interactive compilation is an object file and a terminal listing, and
the output from a batch compilation is an object file and a listing file.
The compiler uses the contents of a file or of a series of files joined'-by plus
signs (+)as input to a ~JJSS compilation. The compiler begins processing
with the first file given in an input-spec and continues until an end-offile is reached. It continues to read input until all files specified in the
input-spec have been read. Command-line qualifiers can appear in two
Operating Procedures

1-3

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 apply only to the input-spec
they follow. For example:
$BLISS/LIBRARY ALPHA,BETA/OBJECT,IOTA

If no command-line qualifiers exist in a command line, default qualifier
settings are assumed for all input-specs in the command line. All qualifiers
have an assigned default setting or value.

The only required space in the command line separates the first input-spec
from preceding global command-line qualifiers.

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

In the input-specs of a bliss-command-line
As the values of the qualifiers /OBJECT, /LIBRARY, /LIST, and
/ANALYSIS-DATA
In REQUIRE and LIBRARY declarations in the module being compiled

The file-spec is a standard VMS file specification, as described in the
VAX/VMS DCL Dictionary. (See Appendix A.)
A file specification is interpreted as follows:
1. Logical names are translated.
2. If a file type is not given, a default file type is used, as described in
the next section.
3. If the file-spec applies to an output file and a file name is not given,
then the name of the first or only input file in the input-spec is used.

1-4 Operating Procedures

The compiler uses this same interpretation when it processes the file
specification given in a REQUIRE or LIBRARY declaration. (Refer to the
BLISS Language Reference 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 that the compiler applies depends on the output to
be produced by the compilation, as indicated in the following list:
Input-spec Used to Produce

Default Type List

An object module

.B32, .BLI

A library file

.R32, .REQ, .B32, .BLI

If the program being compiled contains a REQUIRE or LIBRARY declara-

tion, 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, .REQ, .B32, .BLI

File given in a LIBRARY declaration

.L32

The default file-types for output files that the compiler generates are as
follows:
File-Designator

Default Type

/OBJECT

.OBJ

/LIST

.LIS

/LIBRARY

.L32

/ANALYSIS-DATA

.ANA

Suppose you have entered the following source text in the file ALPHA.BU:
MODULE MYTEST =
BEGIN
REQUIRE 'CBLISS';
LIBRARY 'TBLISS';
END
ELUDOM

And you use the following command line to compile it:
$ BLISS ALPHA

Operating Procedures

1-5

Because 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, the compiler searches for ALPHA.BU, which it finds and
compiles.
In processing the module MYTEST in that file, the compiler encounters
the REQUIRE declaration for the file CBLISS. Because 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, and then CBLISS.BLI. When the compiler processes the
LIBRARY declaration, it uses the default type list associated with library
declarations and searches first 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 as follows:
•
•
•
•
•
•
•
•

1-6 Operating Procedures

/CHECK qualifier-controls the level of semantic checking done
during compilation
/CROSS_REFERENCE qualifier-includes cross-reference information
in output listing
General qualifiers-sets a variant value and specifies code and debugging information
/MACHINE-CODE-LIST qualifier-provides output listing information concerning the form of the object part
/OPTIMIZE qualifier-supplies code optimization strategies and
directions
Output qualifiers-defines the types of output to be produced
/SOURCE_LIST qualifier-provides output listing information concerning the form of the source part
/TERMINAL qualifier-controls output produced on a terminal

1.3.1

/CHECK Qualifier
The /CHECK qualifier controls the level of semantic checking done during
compilation. The qualifier allows all legal BLISS syntax to be examined for
semantic irregularities. Some examples of the use of the /CHECK qualifier
are as follows:
•

To suppress field name checking on structure accesses if the data
segment declaration has no field-attribute, use the /CHECK qualifier
as follows:
$ BLISS/CHECK=NOFIELD ALPHA

•

To check for the use of uninitialized storage, use the /CHECK qualifier
as follows:
$ BLISS/CHECK=INITIAL ALPHA

1.3. 1. 1

Syntax

/CHECK qualifier syntax is as follows:
check qualifier

check-value

1.3. 1.2

/CHECK= { (check-value , ... ) }
check-value

{

FIELD
INITIAL
OPTIMIZE
REDECLARE

I NOFIELD
I NOINITIAL
I NOOPTIMIZE
I NOREDECLARE

}

Defaults

In the absence of a specific choice of check-value, the following values are
assumed by default:
FIELD
INITIAL
OPTIMIZE
NOREDECLARE

Operating Procedures

1-7

1.3. 1.3

Semantics

The /CHECK qualifier indicates that one or more check-values follow.
The check-values have. the following meanings:
Check-Value

Meaning

FIELD

Do not suppress field name checking.

NO FIELD

If the data segment declaration has no field-attribute,
suppress field name checking on the structure accesses.

INITIAL

Check for the use of uninitialized LOCAL, STACKLOCAL,
and REGISTER data storage.

NOINITIAL

Do not check for the use of uninitialized storage.

OPTIMIZE

Check for suspicious optimizations-for example, constant
folding expressions of a form that is always false, such as:
.X < 0,8,1 > EQL

1.3.2

NOOPTIMIZE

Do not check for suspicious optimizations.

REDECLARE

Check for the redeclaration of a name within a nested
scope.

NO REDECLARE

Do not check for the redeclaration of a name.

/CROSS-REFERENCE Qualifier
The /CROSS_REFERENCE qualifier allows a cross-reference listing to
be included with the compiler listing or a cross-reference data file to be
created, or both (refer to Section 1.3.5). Some examples of using the
/CROSS_REFERENCE qualifier are as follows:
•

To have a cross-reference listing included with the normal source
compiler listing, use the /CROSS_REFERENCE qualifier in the
command line as follows:
$ BLISS/LIST/CROSS_REFERENCE ALPHA

In addition to the object file, the compiler produces list file
ALPHA.LIS, to which a cross-reference listing is appended.

1-8

Operating Procedures

•

To have only a cross-reference listing produced (without the normal
source compiler listing), use the following:
$ BLISS/LIST/CROSS_REFERENCE/SOURCE=NOSOURCE $_/MACH=NOOBJECT ALPHA

•

In addition to the object file, the compiler produces list file
ALPHA.LIS, which contains only cross-reference information.
To produce a compiler listing with a cross-reference listing, use the
following:
$ BLISS/LIST/CROSS_REFERENCE ALPHA

•

In addition to the object file, the compiler produces list file ALPHA.
US, to which a cross reference listing is appended.
To produce a listing with cross-references that include multiple references to the same type symbol occurring on the same source line, use
the following:
$ BLISS/LIST/CROSS_REFERENCE=(MULTIPLE) ALPHA

In addition to the object file, the compiler produces list file
ALPHA.LIS, to which a cross-reference listing is appended that
includes multiple references to the same symbol.

1.3.2. 1

Syntax
/CROSS_REFERENCE qualifier syntax is as follows:

1.3.2.2

reference-qualifier

{ /CROSS_REFERENCE { = reference-value } }

reference-value

{ MULTIPLE I NOMULTIPLE }

Defaults
In the absence of an explicit choice of reference value, the value
NOMULTIPLE is assumed by default.

Operating Procedures

1-9

1.3.2.3

Semantics
The /CROSS_REFERENCE qualifier indicates that a reference-value
can be given for the compilation. The reference-value has the following
meanings:

1.3.3

Reference-Value

Meaning

MULTIPLE

Allow all multiple references (of the same reference type) to
a symbol, occurring on the same source line, to be included
in the cross-reference listing.

NOMULTIPLE

Exclude from the cross-reference listing all multiple references to a symbol occurring on the same source line.

General Qualifiers
General qualifiers are used to specify code and debugging 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 the /NOTRACEBACK
qualifier in the command line, as follows:
$ BLISS/NOTRACEBACK ALPHA

•

The compiler produces the minimum size object module in
ALPHA.OBJ by omitting all debugging and traceback information.
To include the necessary debugging 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 17, for example,
use the /VARIANT qualifier as follows:
$ BLISS/VARIANT=17 ALPHA

1-1 0 Operating Procedures

1 .3.3. 1

Syntax

General qualifier syntax is as follows:

general qualifier
(

/TRACEBACK
/DEBUG
/CODE
/VARIANT { =value }
/ERROR_LIMIT { =value }

I /NOTRACEBACK
I /NODEBUG

)

l/NOCODE
I
I

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

1.3.3.2

Defaults

In the absence of an explicit choice of general qualifier, the following
qualifiers are assumed by default:
/TRACEBACK
/NODEBUG
/CODE
/VARIANT=O
/ERRQR_LIMIT=30
The compiler produces code, does not include the additional debugging
information in the object file, and sets the value of %VARIANT to zero.
If the general qualifier /VARIANT is given without a specified value, then
a value of 1 is assumed.

1.3.3.3

Semantics

The command qualifiers have the following meanings:
/TRACEBACK

Generates information in the objec;t module that can be
used by the VMS Debugger to locate module, routine,
and program section names.

/NOTRACEBACK

Produces the minimum size object module. Does not
include any information for debugging or tracing.

Operating Procedures

1-11

/DEBUG

Generates information in the object module that can be
used by the VMS Debugger to reference names declared
within the BLISS module.

/NODEBUG

Does not generate any additional debugging information.
If this qualifier is applied either explicitly or by default,
the VMS Debugger can only locate module, routine, and
PSECT names.

/CODE

Generates object code for the BLISS source module.

/NOCODE

Performs only a syntax check of the program.

/VARIANT

Sets %VARIANT to 1.

/VARIANT=n

Sets %VARIANT to n, where n is a decimal integer in
the range:

-(2* *31) :s; n :s; (2* *31) - 1

1.3.3.4

/ERROR_LIMIT

Sets limit to 1.

/ERROR_LIMIT=n

Terminates compilation after n error level diagnostics are
encountered.

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 modules, routines, and program sections
(/TRACEBACK and /NODEBUG)
Information about modules, routines, program sections, and data
segment names (/TRACEBACK and /DEBUG)

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, you can use the VMS Debugger 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. Using the
/NOTRACEBACK qualifier reduces the size of the object module and, to

1-12

Operating Procedures

a lesser degree, the size of the executable image, but deprives the object
module of information that could be valuable at execution time.

1.3.4 /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 using the /MACHINE_CODE_LIST qualifier are as follows:
•

To obtain an output listing that can be subsequently edited and then
reassembled by the VAX 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 does not contain
binary, include the NOBINARY code-value:
$ 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.4. 1

Syntax

/MACHINE_CODE_LIST qualifier syntax is as follows:
qualifier /MACHINE_CODE_LIST= { ( code-value / · · · ) }
code-value

code-value

OBJECT
ASSEMBLER
SYMBOLIC
BINARY
COMMENTARY
UNIQUE_NAMES

I NOOBJECT
I NOASSEMBLER
I NOSYMBOLIC
I NOBINARY
I NOCOMMENTARY
I NOUNIQUE_NAMES

Operating Procedures

1-13

1.3.4.2

Defaults

In the absence of an explicit choice of code-value, the following values are
assumed by default:
OBJECT
NO ASSEMBLER
SYMBOLIC
BINARY
COMMENTARY
NOUNIQUE_NAMES
The compiler produces a listing that resembles the output listing of the
VAX MACRO assembler.
1.3.4.3

Semantics

The /MACHINE_CODE_LIST qualifier indicate that one or more codevalues follow. The code-values have the following meanings:
Code-Value

Meaning

OBJECT

Produce the object part of the output listing.

NOOBJECT

Suppress the object part of the output listing.

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. If this output
is to be assembled, the qualifiers /SOURCE_
LIST=NOHEADER and /MACHINE_CODE_
LIST=UNIQUE_NAMES must also be spedfied.

NO ASSEMBLER

Do not list the assembler instructions.

SYMBOLIC

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

NOSYMBOLIC

Do not include a machine code listing that uses
source program names.

COMMENTARY

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

1-14 Operating Procedures

Code-Value

Meaning

NOCOMMENTARY

Do not include a commentary field in the object code
listing.

BINARY

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

NO BINARY

Do not include a listing of the binary

UNIQUE_NAMES

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

NOUNIQUE_NAMES

Do not replace names by unique names.

Each of the code-values is described and illustrated in Section 2.2.3 in
connection with the discussion of the output compilation.

1.3.5

/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 some .standard optimizations, use either the /QUICK qualifier or the /OPTIMIZE qualifier
with the value QUICK in the command line, as follows:
$ BLISS/OPTIMIZE=QUICK ALPHA

•

Note that the use of either the QUICK value or the /QUICK qualifier
turns off flow analysis. (Refer to Section 7.1.2.)
To get minimum optimization, use the /OPTIMIZE qualifier with the
value LEVEL:O, as follows:
$ BLISS/OPTIMIZE=LEVEL:O ALPHA

•

To obtain maximum optimization, use the /OPTIMIZE qualifier with
the value LEVEL:3, as follows:
$ BLISS/OPTIMIZE=LEVEL:3 ALPHA

Operating Procedures

1-15

•

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 using the
/OPTIMIZE qualifier is given in Chapter 7.
1.3.5. 1

Syntax

/OPTIMIZE qualifier syntax is as follows:
optimize qualifier

/OPTIMIZE= { ( o~tir:'ize-value , ... ) }
optimize-value

optimize-value
{
optimize-level

QUICK
SPEED
LEVEL : optimize-level
SAFE

I NOQUICK
I SPACE
I NOSAFE

}

{0 I 1 I 2 I3}

The optimize-values SPEED and SP ACE are mutually exclusive; they must
not be given in the same command line.
1.3.5.2

Defaults

In the absence of an explicit choice of optimize-value, the following values
are assumed by default:
NOQUICK
SPACE
LEVEL:2
SAFE
The compiler is directed to do the following:
•

1-16

Perform normal optimization, biasing the speed/space trade-off in
favor of minimum program size

Operating Procedures

•
•
1.3.5.3

Assume that all variables are addressed by name only
Perform optimization across mark points (see Section 7.1.2.2)

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 that 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 that
SP ACE is equivalent to the module-switch NO ZIP.

LEVEL

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

Optimize-Level

Meaning

Minimum optimization

Subnormal optimization

Normal optimization

Maximum optimization

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.

DECLIT AA VAX H322E
BLI SS-:32 use . . . manual
1

Operating Procedures

1-17

1.3.8

Optimize-Value

Meaning

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.

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. The following are
examples of output qualifiers:
•

To suppress the.production of an object file, use the /NOOBJECT
qualifier in the command line, as follows:
$ 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 /LIST qualifier, as
follows:
$ 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 the following
qualifiers:
$ BLISS/OBJECT=BETA/LIST=GAMMA ALPHA

The compiler reads the input file ALPHA.B32 and produces the object
file BETA.OBJ and the list file GAMMA.LIS.

1-18 Operating Procedures

•

To produce an analysis data file for a VAX Source Code Analyzer
(SCA) library, use the following qualifier:
$ BLISS/ANALYSIS_DATA=SCALIB ALPHA

•

The compiler reads the input file ALPHA.B32 and produces the
analysis data file SCALIB.ANA.
To produce a library file rather than an object file, use the /LIBRARY
qualifier, as follows:
$ BLISS/LIBRARY ALPHA

The compiler reads the input file ALPHA.B32 and produces the library
file ALPHA.L32.

1.3.6. 1

Syntax
Output qualifier syntax is as follows:
output
qualifier

{

/OBJECT {=file-spec}
/LIST {=file-spec}
/LIBRARY {=file-spec}
/ ANALYSIS_DATA {=file-spec}

I /NOOBJECT
I /NOLIST
I /NOLIBRARY
I /NO ANAL YSIS_DATA

}

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

Defaults
In interactive mode, in the absence of an explicit choice of output qualifier,
the following qualifiers are assumed by default:
/OBJECT
/NO LIST
/NO LIBRARY
/NOANAL YSIS_DATA
In batch mode, a list file is produced by default; thus, the following
qu~lifiers are assumed:
/OBJECT
/LIST
/NO LIBRARY
/NOANALYSIS_DATA

Operating Procedures

1-19

1.3.6.3

Semantics
The output qualifiers have the following meanings:
/OBJECT=file-spec

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

/OBJECT

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

/NOOBJECT

Do not produce an object file.

/LIST=file-spec

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

/LIST

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

/NO LIST

Do not produce a list file.

/LIBRARY=file-spec

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

/LIBRARY

Produce a library file in the file specified
by 1input-file-name. L32 1 •

/NO LIBRARY

Do not produce a library file.

/ ANALYSIS_DATA=file-spec

Produce an analysis data file in the file
specified by file-spec.

/ ANALYSIS_DATA

Produce an analysis data file in the file
specified by 'input-file-name.ANN.

./NOANALYSIS_DATA

Do not produce an analysis data file .

1.3.7 /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 using 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_LIST=(NOHEADER,EXPAND MACROS) ALPHA

1-20

Operating Procedures

•

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.3. 7. 1

Syntax
/SOURCE_LIST qualifier syntax is as follows:
source-list qualifier

source-value

number-of-lines

1.3.7 .2

/SOURCE_LIST= { ( source-value , ... ) }
source-value
HEADER
PAGE_SJZE:
LIBRARY
REQUIRE
EXPAND_MACROS
TRACE_MACROS
SOURCE

I NOHEADER
number-of-lines
I NOLIBRARY
I NOREQUIRE
I NO EXP AND_MACROS
I NOTRACE_MACROS
I NOSOURCE

{ 20 I 21 I 22 I . . . }

Defaults
In the absence of an explicit choice of source-value, the following values
are assumed by default:
HEADER
P AGE_SIZE:58
NO LIBRARY
NOREQUIRE
NO EXP AND_MACROS
NOTRACE_MACROS
SOURCE
The compiler produces a paged listing with 58 lines on each page, in
which no expansion or tracing is included.

Operating Procedures

1-21

1.3. 7 .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:
Source-Value

Meaning

HEADER

Page the listing produced on the list file 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 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 any libraries and
their contributions.

REQUIRE

Include source text obtained from require files in
listing.

NO REQUIRE

No not include require-file text.

EXP AND_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.

1-22 Operating Procedures

1.3.8

Source-Value

Meaning

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.

/TERMINAL Qualifier
The /TERMINAL qualifier is used to control the output that is sent to the
terminal. You can have errors or statistics printed or suppressed on the
terminal during the compilation of a BLISS program. Some examples of
the use of 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 obtain statistics, use the following:
$ BLISS/TERMINAL=(NOERRORS,STATISTICS) ALPHA

1.3.8. 1

Syntax
/TERMINAL qualifier syntax is as follows:
terminal qualifier
terminal-value

1.3.8.2

/TERMINAL= { ( terminal-value, ... ) }
terminal-value
{

ERRORS
STATISTICS

I NOERRORS
I NOSTATISTICS

}

Defaults
In the absence of an explicit choice of terminal-value, the following values
are assumed by default:
ERRORS
NOSTATISTICS
Errors are reported on the terminal during the compilation, but statistics
are suppressed.

Operating Procedures

1-23

1.3.8.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 as it is encountered in the
compilation.

NOERR ORS

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.9 Qualifier Names Versus 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), while in other cases it is similar
but not identical. The names of the corresponding qualifiers and switch
items are given in Table 1-1.

1-24 Operating Procedures

Table 1-1:

Correspondence Between Qualifier and Switch Names

Qualifier Name

Module-Head Switch

SWITCHESDeclaration Switch

/CODE

CODE

n/a

/DEBUG

DEBUG

n/a

/MACHINE_CODE_LIST=ASSEMBLER

LIST(ASSEMBLY)

LIST (ASSEMBLY)

/MACHINE_CODE_LIST=BINARY

LIST(BINARY)

LIST( BINARY)

/MACHINE_CODE_LIST=COMMENTARY

LIST(COMMENTARY)

LIST (COMMENTARY)

/MACHINE _CODE _LIST=OBJECT

LIST( OBJECT)

/MACHINE_CODE_LIST=SYMBOLIC

LIST(SYMBOLIC)

LIST (SYMBOLIC)

/MACHINE_CODE_LIST=UNIQUE_NAMES

UN AMES

/OPTIMIZE=LEVEL:n

OPLEVEL=n

n/a

/OPTIMIZE=SAFE

SAFE

/OPTIMIZE=SPACE

NO ZIP

/OPTIMIZE=SPEED

ZIP

/SOURCE_LIST=EXPAND_MACROS

LIST(EXP AND)

LIST( EXP AND)

/SOURCE _LIST=LIBRARY

LIST(LIBRARY)

LIST( LIBRARY)

/SOURCE_LIST=REQUIRE

LIST(REQUIRE)

LIST( REQUIRE)

/SOURCE_LIST=SOURCE

LIST(SOURCE)

LIST( SOURCE)

/SOURCE_LIST=TRACE_MACROS

LIST(TRACE)

LIST( TRACE)

/TERMINAL=ERRORS

ERRS

1.3.10

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.B32
has a module switch CODE. The second module BETA.B32 has no
switches. The BLISS command line is as follows:
$ BLISS/NOCODE ALPHA.BETA

Operating Procedures

1-25

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

Positive and Negative Forms of Qualifiers
In general, two forms of a qualifier are allowed: 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, whereas the
/NOLIST qualifier prevents the creation of a listing file for BETA.B32.

1.3.12

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 is given in Appendix A.

1-26

Operating Procedures

Chapter 2

Compiler Output
This chapter describes compiler output as it appears in 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 routines are
described in the BLISS Language Reference Manual.
module testfact (main = mainprog)
begin
own
a,
b;

routine if act (n)
begin
local
result;
result = 1;
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 1;
routine mainprog : novalue =

Compiler Output

2-1

begin
a= ifact (5);
b = rfact (5);
1

VMS wants a success return

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 Terminal Output
The compiler produces two kinds of information on the terminal: error
messages and statistics. You can request or suppress each of these by
using 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 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 line is as follows:
;Compilation Complete

If a library file is produced, the last line is as follows:
;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

2-2

Compiler Output

The qualifier /TERMINAL=STATISTICS is used so that both types of
output are sent to the terminal. The terminal output is as follows:
;
0002 0
begin
1 L1:0002
Y. WARN#048
Syntax error in module head
;
0014
2
result = .reult*.I;
Y. WARN_#OOO
.................. 1 L1:0014
Undeclared name: REULT
!FACT 22
RFACT 26
MAINPROG 28
Information: 0
Warnings:
2
Errors:
0
Size:
76 code + 8 data bytes
Run time:
00: 01. 5
Elapsed time:
00:03.5
Lines/CPU Min:
1663
Lexemes/CPU-Min: 6252
; Memory used: 15 pages
; Compilation Complete
Y.BLS32-W-ENDDIAGS, Compilation with 2 diagnostics

Terminal output for compiling 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, !FACT, RFACT, and MAINPROG, and they
use 22, 26, and 28 bytes, respectively. The compilation summary shows
that the compiling of TESTFACT required 1.2 seconds of processor time
and that 3.0 seconds elapsed; moreover, 1663 source lines comprising
6252 lexemes were processed per CPU minute. The compilation required
15 pages of memory, excluding memory required by the compiler itself.

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.

Compiler Output

2-3

Figure 2-1 : Compiler Output Listing Sequence

SOURCE
} SEGMENT 1
OBJECT
SOURCE
} SEGMENT 2
OBJECT
SOURCE

•••
OBJECT
SOURCE
} SEGMENT n
OBJECT
CROSS-REFERENCE
OBJECT SUMMARY
COMPILATION STATISTICS
ZK-1368-83

Both the source and object parts of a routine segment can be suppressed
and the format of the object part can be changed by including 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.

2-4 Compiler Output

The complete output listing for the module TESTFACT occupies several
pages (refer to Section 2.2.3.1). The routine segment for the routine
IFACT contains the module heading, the OWN declaration, and the
routine declarations for IFACT. The following sections discuss each part of
the output listing.

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.
Figure 2-2:
PRINT
POSITION

Listing Header Format

132

63 65

15 17
NAME

TITLE

PROCESSOR IDENTIFICATION

IDENT

SUBTITLE

SOURCE IDENTIFICATION
ZK-1369-83

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 avallable. Thus, the first page of a
module may be blank; subsequent pages must include the information if it
appears in the object module. If the module name exceeds 15 characters,
the title field begins 8 columns further to the right.
The title and subtitle fields contain user-supplied information; they identify the purpose of the module and routine. User-defined title and subtitle
entries that are too long are right truncated at column 63. If the language
processor makes no provision for you 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 you update the title or subtitle information in the first

Compiler Output

2-5

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 number appears as the
last entry in this field. This number increments by 1 for each listing page
produced from a concatenated source file, that is, in the listing file.
The source identification field contains the date and time of creation or last
modification of the source file being 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 1 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 16- or 24-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.
The basic difference in preface string length is due to the fact that the
24-character preface contains the editor's line sequence numbers, whereas
the 16-character string does not.
The 16-character preface string has the following general form:
;byznnnnbnnbbbbb

The 24-character preface string has the following general form:
;xxxxxbbyznnnnbnnbbbbbbb

Table 2-1 describes preface string components of each string. (Asterisks
denote the components and columns of the 24-character preface string.)

2-6

Compiler Output

Table 2-1: Format of Preface String in Source Listing
Item
Column Meaning
1

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
or
b

2-6t
or
2

The line number, if the file contains line sequence numbers; otherwise, one blank column.

bbt

7-St

Blanks.

9t
or
3

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

Code

Meaning

Embedded comment, that is, text within %( ... )%

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

IOt
or
4

nnnn

ll-14t
or

5-8

If the line comes from a file specified in a REQUIRE
declaration, the code "R"; otherwise, a blank.

The BLISS line sequence number, beginning with 0001;
it 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.

tcomponents of the 24-character preface string

Compiler Output

2-7

Table 2-1 (Cont.): Format of Preface String in Source Listing
Item
Column Meaning
b

lSt
or

Blank.

The begin-end block level number reflecting the depth of
the code within each block structure.

16-17t
or
10-11

bbbbbbbt 18-24t

Blanks.

12-16

Blanks.

bbbbb

tcomponents of the 24-character preface string

For example, consider the following line of the source input:
RESULT

= 1;

If the above expression were the fourteenth line of the compilation, for
example, the output listing for that line would be as follows:
0014

RESULT = 1;

The line number 0014 is the line assigned by the BLISS compiler, and
the begin-end block depth number 2 indicates that the line of code occurs
in the second block level. If the input line had an editor line sequence
number 2300, the output listing for the line would be as follows:
;02300

0014

RESULT = 1;

If the input line comes from a REQUIRE file, the output listing includes an
R, as follows:
;

R0014

RESULT

= 1;

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

RESULT = 1;

They item in the preface string column 3 (9 for a 24-character preface) 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. You can find the beginning of the unterminated

2-8

Compiler Output

macro, however, by finding the point at which the M code first appears in
they field.
The following is an example of the source listing (the first segment of the
module TESTFACT) that uses the 24-character preface string:
. (header)
module testf act (main = mainprog)
begin
; WARN#048
1 11:0002
; Syntax error in module head
;00300
0003 1
;00400
0004 1
own
a,
;00500
0005 1
b;
;00600
0006 1
;00700
0007
routine if act (n)
;00800
0008 1
;00900
0009 2
begin
;01000
0010 2
local
result;
;01100
0011 2
;01200
0012 2
result = 1;
incr i from 2 to .n do
;01300
0013 2
result = .reult*.i;
;01400
0014 2
; WARN#OOO
.................. 1 11:0014
; Undeclared name: REULT
;01500
0015 2
.result
;01600
0016 1
end;
;00100
;00200

0001
0002

0
0

Following three heading lines, the source of the module TESTFACT is
reproduced. The 24-character preface string begins with a semicolon (; ).
Columns 7 and 8 are always blank, and columns 9 and 10 are blank
because the lexical processing level is normal and the material is not from
a REQUIRE file. Line numbers generated by the compiler occupy columns
11 through 14. Column 15 is always blank, and in columns 16 and 17 the
begin-end block level count appears.
Two error messages are reported as part of the source listing. Section 2.5
discusses error messages and their meaning.

Compiler Output

2-9

2.2.3

Object Listing
The object part of the listing has four possible fields: assembler input,
assembler output, binary, and commentary. The parts of the object
listing that are produced depend on the choice of machine-code-list codevalues 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 either
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 machine-code-list code-values are
acceptable:
ASSEMBLER { SYMBOLIC
} COMMENTARY { BINARY
} { UNIOUE_NAMES
}
NOSYMBOLIC
NOBINARY
NOUNIOUE_NAMES
NOASSEMBLER SYMBOLIC COMMENTARY { BINARY
} NOUNIOUE_NAMES
NOBINARY

The commentary field requires little space and provides useful information
so that you have no real need for the NOCOMMENTARY qualifier.
The question of whether to have the binary field 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:

2-1 0

Compiler Output

Field

Contents

ASSEMBLER field

Instructions in assembler form, for example:
MOVL

SYMBOLIC field

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

BINARY field

#1,RO

#1,RESULT

Hexadecimal equivalent of instructions and data to
enable easier debugging. The hexadecimal instructions appear in the same format as that produced
by the VAX 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 interaction with the
VMS Debugger when you are setting breakpoints or
examining instructions (refer to Section 3.3).
The following codes are included in the hexadecimal
information in the binary field to provide information
about relocation of quantities:

Code

Meaning

Blank

Absolute quantity (no linker
action}.

Forward relocatable.

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

Compiler Output

2-11

Field

Contents
Code

Meaning

Either general addressing (position independent) or globally
relocatable.

COMMENTARY A cross-reference to the source

field

program line generating the
code. If a program line 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 IFACT follow.
2.2.3. 1

Default Object Listing

The listing in Figure 2-3 was produced by the following command line:
$ BLISS/LIST MYPROG

In the listing, the binary field appears first, followed by the symbolic field,
and then by the commentary field.
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, and then 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-12

Compiler Output

Figure 2-3:

Default Object Listing Example

TESTFACT

2-Mar-1987 14:11:48
22-Jul-1983 16:06:56

0001
0002
WARN#048
Syntax
0003
0004
l
0005
1
0006
1
0007
0008
0009
0010
0011
0012
0013
0014
WARN#OOO
Undeclared
0015
2
0016

A,
B;
ROUTINE IFACT (N)
BEGIN
LOCAL
RESULT;
RESULT= l;
INCR I FROM 2 TO .N DO
RESULT= .REULT*.I;
.................. 1
Ll:0014
RE ULT
.RESULT
END;

so
Sl

OOOOG

("".)

"E.

1
l
l

( l)

OWN

.TITLE

TESTFACT

.PSECT

$OWN$,NOEXE,2

. BLKB
.BLKB
.EXTRN

0017
0018
0019
0020
0021
0022
0023

Page

MODULE TESTFACT (MAIN= MAINPROGI
BEGIN
l
Ll:0002
in module head

00000 A:
00004 B:

Routine Size:

VAX Bliss-32 V4.3
DISK$: [DIRECTORY J MYPROG. B3 2; 13

22 bytes,

CF
S1

Routine Base:

ROUTINE RFACT (N) =
IF .N GTR 1
THEN
.N * RFACT(.N ELSE

RE ULT

.PSECT

$CODE$,NOWRT,2

00000 IFACT:
00002
OOOOS
00008
OOOOA 1$:
00010 2$:
OOOlS

.WORD
MOVL
MOVL
BRB
MULL3
AOBLEQ
RET

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

0000 00000 RFACT:

.WORD

Save nothing

0000
DO
01
01
DO
06
11
S1
CS
AC
F3
04

0008
0 0 12
0013
0014
0016

$CODE$ + 0000

s
s.

-0

.!..
w

0018
ZK·5990/1·HC

(Continued on next page)

....I

Figure 2-3 (Cont.):

Default Object Listing Example

C")

TESTFACT

2-Mar-1987 14:11:48
22-Jul-1983 16:06:56

VAX Bliss-32 V4. 3
DISK$:[DIRECTORY]MYPROG.B32;13

s
s

04
EF

-c

AC
AF
50

AC
OE
01
01
AC

50
Routine Size:
0024
0025
0026
0027
0028
0029
0030
0031

1
2
2
2

26 bytes,

Routine Base:

01
15
C3
FB
C4
04
DO
04

00002
00006
00008
00000
00011
00015
00016 1$:
00019

CMPL
BLEQ
SUBL3
CALLS
MULL2
RET
MOVL
RET

Page

2
( 1)

N' #1
1$
#1, N, -(SP)
#1, RFACT
N, RO

0019

#1, RO

0019
0023

Save nothing
#5
U, !FACT
RO, A
#5
*1, RF ACT
RO, B
# 1, RO

0025
0027

0021

$CODE$ + 0016

ROUTINE MAINPROG =
BEGIN
A= IFACT(5);
B = RFACT(5);
VMS wants a success return
END;

Routine Size:

0032
0033

1
0

28 bytes,

C8
0000'

AF
CF

03
0000'

AF
CF
50

Routine Base:

05
01
50
05
01
50
01

0000 00000 MAINPROG:
.WORD
OD 00002
PUSHL
FB 00004
CALLS
DO 00008
:-!OVL
DD 00000
PUSHL
FB OOOOF
CALLS
DO 00013
MOVL
DO 00018
MOVL
04 OOOlB
RET

0028

0 0 31

$CODE$ + 0030

END
ELUDOM

PSECT SUMMARY
Name

$OWN$
$CODE$

Bytes

Attributes

NOVEC,
WRT,
NOVEC,NOWRT,

RD ,NOEXE,NOSHR,
RD
EXE,NOSHR,

LCL,
LCL,

REL,
REL,

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

ZK-5990/2-HC

(Continued on next page)

Figure 2-3 (Cont.):

Default Object Listing Example
2-Mar-1987 14:11:48
22-Jul-1983 16:06:56

TESTFACT

VAX Bliss-32 V4.3

DISK$:(DIRECTORY)MYPROG.B32;13

Page

3
(l)

Information:
Warnings:
Errors:·

COMMAND QUALIFIERS
BLISS/LIST MYPROG
Size:
76 code + 8 data bytes
Run Time:
00:01.4
Elapsed Time:
00:02.9
Lines/CPU Min:
1455
Lexemes/CPU-Min:
5470
Memory Used:
19 pages
Compilation Complete

ZK·5990/3·HC

C"')

c
3
"'52.

N
I

U 'I

Figure 2-4:

Assembler Input Listing Example

n
3

TESTFACT

2-Mar-1987 13:54:04
22-Jul-1983 16:06:56

"'E.

0001
0002
0
WARN#048
Syntax
0003
0004
0005
0006
0007
0008
0009
0010
0011
0012
0013
0014
WARN#OOO
Undeclared
0015
2
0016
1

s.
s.

A:
B:

VAX Bliss-32 V4.3

DISK$:[DIRECTORY]MYPROG.B32;13

Page

1
( 1)

MODULE TESTFACT (MAIN = MAINPROG)
BEGIN
1
Ll:0002
in module head
OWN

A,
B;

ROUTINE IFACT (N)
BEGIN
LOCAL
RESULT;
RESULT = 1;
INCR I FROM 2 TO .N DO
RESULT= .REULT*.I;
. . . . . . . . . . . . . . . . . . 1 Ll: 0014
RE ULT
.RESULT
END;

.TITLE

TESTFACT

.PSECT

$OWN$,NOEXE,2

.BLKB
.BLKB

I FACT:

1 $:

2$:

.EXTRN

RE ULT

.PSECT

$CODE$,NOWRT,2

.WORD
MOVL
MOVL
BRB
MULL3
AOBLEQ
RET

•M<>
#1, RO
# 1, Rl
2$
Rl, w·REULT, RO
4(AP), Rl, 1$

Routine Size:
0017
0018
0019
0020
0021
0022
0023

RF ACT:

1
1
1
1
1
1

. WORD

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

0008
0012
0013
0014
0016

22 bytes,

Routine Base:

ROUTINE RFACT (N) =
IF .N GTR 1
THEN
. N * RF ACT ( . N ELSE
l;

·Mo

$CODE$ + 0000

; Save nothing

; 0018

ZK-5989/1-HC

(Continued on next page)

Figure 2-4 (Cont.):

Assembler Input Listing Example

TESTFACT

2-Mar-1987 13:54:04
22-Jul-1983 16:06:56
CMPL
BLEQ
SUBL3
CALLS
MULL2
RET
MOVL
RET

1 $:

Routine Size:
0024
0025
0026
0027
0028
0029
0030
0031

1
2
2
2

0032
0033

N, !11
1$
!11, N, -(SP)
!11, RFACT
N, RO

0019

!11, RO

Ill , RO

0019
0023

26 bytes,

Routine Base:

0021

$CODE$ + 0016

ROUTINE MAINPROG =
BEGIN
A= IFACT(5);
B = RFACT(S);

1
0

.M<>
!15
!11, B.IFACT
RO, w·A
!IS
Ill, B.RFACT
RO, w·B
!11, RO
28 bytes,

Save nothing
!IS
111, IFACT
RO, A
!IS
Ill, RFACT
RO, B
111, RO
Routine Base:

0025
0027
0028
0031

$CODE$+ 0030

END
ELUDOM

PSECT SUMMARY

s.
s.

( 1)

4 (AP), Ill
1$
Ill , 4 ( AP ) , - ( SP )
!11, B .RF ACT
4 (AP), RO

VMS wants a success return

Routine Size:

Page

END;

MAINPROG:
.WORD
PUSHL
CALLS
MOVL
PUSHL
CALLS
MOVL
MOVL
RET

3
"'5!.
~

VAX Bliss-32 V4.3
DISK$:[DIRECTORY]MYPROG.B32;13

Name
$OWN$
$CODE$

Bytes

Attributes
8
76

NOVEC,
WRT,
NOVEC,NOWRT,

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

LCL,
LCL,

REL,
REL,

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

"'C

ZK·5989/2-HC

-.....
I

(Continued on next page)

=
C")

Figure 2-4 (Cont.):

Assembler Input Listing Example

TESTFACT

2-Mar-1987 13:54:04
22-Jul-1983 16:06:56

s
s

VAX Bliss-32 V4.3
DISK$:[DIRECTORY]MYPROG.B32;13

Page

3
( l)

Information:
Warnings:
; Errors:

COMMAND QUALIFIERS
BLISS/LIST/MACHINE_CODE_LIST:(ASSEMBLER,NOBINARY) MYPROG
Size:
76 code + 8 data bytes
Run Time:
00:01.3
Elapsed Time:
00:01.7
Lines/CPU Min:
1571
Lexemes/CPU-Min:
5904
Memory Used:
18 pages
Compilation Complete
.END

MAINPROG

ZK·5989/3·HC

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 complex.
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 has been
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:

ml
(m)
n -(m-n)!n!

First, enter the routine declarations for !FACT and RFACT into separate
REQUIRE files, named !FACT and RFACT, respectively. The module
TEST can then use either routine by including the appropriate REQUIRE
declaration.
Next, write a macro (COMBN.R32) for obtaining the combinations:
MACRO

COMBINATIONS(N,M) =
(IF N LSS M
THEN ERROR()
ELSE COMB(N,M)) Y..
COMB(M,N) =
FACT(N)/(FACT(N-M)_*FACT(M)) Y.;

Then, precompile the macro declaration into a LIBRARY file as follows
(include a LIBRARY declaration in the module TEST):
$

BLISS/LIBRARY COMBN

Finally, include some test combinations.
The following sections illustrate the different output listings obtained for
that module by varying the command qualifiers.

Compiler Output

2-19

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

Listing with LIBRARY and REQUIRE Information

The following command line generated the output listing in Figure 2-6,
which contains information from LIBRARY and REQUIRE files:
$

BLISS/NOCODE/LIST/SOURCE_LIST:(LIBRARY,REQUIRE) TEST

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 following command line generated the output listing in Figure 2-7 to
illustrate macro expansions, which follow lines 0020 and 0021:
$ BLISS/NOCODE/LIST/SOURCE_LIST:EXPAND_MACROS TEST

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 following command line produced the output listing in Figure 2-8,
which contains macro tracing and macro expansion information:
$ BLISS/NOCODE/LIST/SOURCE_LIST:TRACE_MACROS TEST

The macro trace gives information about parameter binding in addition to
the expansion information.

2-20

Compiler Output

Figure 2-5:

Default Source Listing Example
2-Mar-1987 13:59:39
16-Apr-1983 20:02:35

TEST
0001
0002
0003
0004
0005
0006
0007
0008
0009
0010
0017
0018
0019
0020
0021
0022
0023
0024
0025
0026
0027

module test
begin

(main

VAX Bliss-32 V4. 3
DISK$:[DIRECTORY]TEST.BLI;l

Page

1
( 1)

mainprog)

1
1·
a'
b;

external routine
error;
library 'combn'
require 'rfact'

;

routine mainprog =
begin
a= combinations
b=combinations

(3,
(6,

2);
4);
VMS wants a success return

end;
end
eludom

Library Statistics

Total

File

Symbols
Loaded

DISK$: [DIRECTORY]COMBN.L32;1

Percent
100

Pages
Mapped

Processing
Time
00:00.1

COMMAND QUALIFIERS
BLISS/LIST/NOCODE TEST
Run Time;

00:00.6

Elapsed Time:
00:00.9
Lines/CPU Min:
2842
Lexemes/CPU-Min: 21894
Memory Used:
10 pages
Compilation Complete
C")
0

"E.
~
0

s.
N

ZK 5991-HC

'I"'
N

Figure 2-6:

Output Listing with LIBRARY and REQUIRE File Data

N
C"')

TEST

2-Mar-1987 14:02:41
16-Apr-1983 20:02:35

0
c::

s.
,,

0001
0
0002
l
0003
l
0004
l
0005
l
0006
l
0007
l
0008
l
0009
l
Library file
0010
l

module test (main
begin

VAX Bliss-32 V4.3
DISK$:[DIRECTORY]TEST.BLI;l

Page
( l)

= mainprog)

own
a,
b;
external routine
error;
library 'combn' ;
DISK$:[DIRECTORY]COMBN.L32;1 produced by VAX Bliss-32 V4.3
require 'rfact' ;

2-Mar-1987 13:58:38

ZK·5992/1·HC

2-Mar-1987 14:02:41
13-Apr-1983 10:27:34

TEST
ROOll
R0012
R0013
R0014
R0015
R0016

ROUTINE FACT (N) =
IF .N GTR l
THEN
.N * FACT(.N ELSE

VAX Bliss-32 V4.3
DISK$:[DIRECTORY]RFACT.REQ;2

Page

2
( 1)

ZK·5992/2·HC

(Continued on next page)

Figure 2-6 (Cont.):

Output Listing with LIBRARY and REQUIRE File Data

TEST

2-Mar-1987 14:02:41
16-Apr-1983 20:02:35

VAX Bliss-32 V4.3
DISK$:[DIRECTORY]TEST.BLI;l

Page
( 1)

0017
0018
routine mainprog =
0019
begin
0020
a= comb nations (3, 2);
, , Loaded symbol COMBINATION
from library DISK$:[DIRECTORY]COMBN.L32;1
;; Loaded symbol COMB from l brary DISK$:[DIRECTORY]COMBN.L32;1
0021
2
b=combnations (6, 4);
0022
0023
VMS wants a success return
0024
end;
0025
0026
end
0027
eludom
Library Statistics
File

Total

Sy111bols
Loaded

DISK$:[DIRECTORY]COMBN.L32;1

Percent
100

Pages
Mapped

Processing

Ti111e

00:00.1

COMMAND QUALIFIERS
BLISS/NOCODE/LIST/SOURCE_LIST:(LIBRARY,REQUIRE) TEST
Run Time:
00:00.7
Elapsed Time:
00:01.4
Lines/CPU Min:
2417
Lexemes/CPU-Min: 18626
Memory Used:
10 pages
Compilation Complete

ZK-5992/3-HC

C"')

"5!.

s
s

"'C

"'
w
"'
I

Figure 2-7:

C"')

TEST

N
.;i.

Output Listing with Macro Expansion Data
2-Mar-1987 14:14:51
16-Apr-1983 20:02:35

~
~
0

s
s

VA:Z. Bliss-32 V4. 3
Disg$:[DIRECTORY)TEST.BLI;l

Page

l
( l)

aodule test (aain = aainprog)
begin

0001
0002
0003
0004
0005
0006
0007
0008
0009
0010
0017
0018
0019
0020

a'
b;

external routine
error;
library 'coabn' ;
require 'rfact' ;

routine aainprog =
begin
a= coabinations (3,
[COMB)= FACT ( 3 ) / ( FACT (
[COMBINATIONS]=
( IF 3 LSS 2 THEN
0021
2
b = coabinations (6,
[COMB)= FACT ( 6 ) / ( FACT (
[COMBINATIONS)=
( IF 6 LSS 4 THEN
0022
2
0023
2
end;
0024
0025
end
0026
0027
0
eludoa

2);
3 - 2
ERROR
4);
6 - 4
ERROR

* FACT· ( 2 ) )
ELSE FACT ( 3 ) I

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

VMS

FACT

3 -

( FACT ( 6 -

* FACT

2 )

) * FACT ( 4 ) )

)

wants a success return

Library Statistics

File

Total

Symbols -------Loaded
Percent
100

OISK$:[DIRECTORY)COMBN.L32;1

Pages
Mapped

Processing
Tiae
00:00.l

COMMAND QUALIFIERS
BLISS/NOCOOE/LIST/SOURCE_LIST:EXPAND_MACROS TEST
00:00.7
Run Time:
00:01.5
Elapsed Time:
Lines/CPU Min:
2492
Lexemes/CPU-Min: 19200
Memory Used:
10 pages
Compilation Coaplete

ZK 5993-HC

Figure 2-8:

Output Listing with Macro Expansion and Tracing Data
2-Mar-1987 14:15:39
16-Apr-1983 20:02:35

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

VAX Bliss-32 V4.3
DISK$:[DIRECTORY]TEST.BLI;l

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

( FACT ( 3 -

2 ) * FACT ( 2 )
·

)

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

( FACT ( 6 -

4 ) * FACT ( 4 )

)

Page

1
( 1)

VMS wants a success return

Library Statistics

File

Total

Symbols
Loaded

Percent

Pages
Mapped

Processing
Time

("')

100

DISK$:[DIRECTORY]COMBN.L32;1

00:00.1

=:!.

s
s

N
U'1

COMMAND QUALIFIERS
ZK-5994/1 ·HC

(Continued on next page)

Figure 2-8 (Cont.):

Output Listing with Macro Expansion and Tracing Data

en
C"')

TEST

2-Mar-1987 14:15:39
16-Apr-1983 20:02:35

VAX Bliss-32 V4.3
DISK$:[DIRECTORY)TEST.BLI;l

Page

2
( 1)

BLISS/NOCODE/LIST/SOURCE_LIST:TRACE_MACROS TEST

s
s

Run Time:
00:00.7
Elapsed Time:
00:01.1
Lines/CPU Min:
2 250
Lexemes/CPU-Min: 17333
Memory Used:
10 pages
Compilation Complete
ZK·5994/2·HC

2.3 Cross-Reference Listing
The cross-reference listing is an optional part of the output listing that is
produced by the compiler on request. Cross-reference data are generated
on a module basis; therefore, the reference information associated with a
given module will appear as the last module-specific item in the listing
file, before the compilation summary and before any subsequent module
data.

2.3.1

Cross-Reference Header
The cross-reference header is separated from the output listing header by
a blank line and subsequently appears on the first two lines of each page
of the reference listing. The cross-reference header is as follows:
Symbol

2.3.2

Type

Defined

Referenced ...

Cross-Reference Entries
The reference entries listed under each header name are fixed-length fields
that are separated by a single space.
Symbol Field

The symbol field is used to list the names of the different symbols.
The length of the field is fixed at the length of the longest name in the
module. A name appears just once in the symbol field, defining its initial
recognition by the compiler as a declared symbol. If multiple symbols are
declared with the same name, lines directly following the first appearance
of the name are used; however, for each subsequent recognition the field
is left blank. For example:
ALPHA
GAMMA

Compiler Output 2-27

Type Field

The type field describes the condition (such as LOCAL, BIND, or
BUILTIN) under which the symbol-name was used when it was declared.
The field is eight characters long; therefore, symbol type abbreviations are
used. The symbol type abbreviations are listed in Table 2-2.
Table 2-2:

Symbol Type Abbreviations

Symbol Type

2-28

Abbreviation

Bind

Bind routine

BindRout

Builtin

Compiletime

Comptime

Enable

External

External literal

ExtLit

External register

ExtReg

External routine

ExtRout

Field

Fieldset

Forward

Forward routine

ForwRout

Global

Glo}1al

Global bind

Glob Bind

Global bind routine

GlBiRout

Global literal

Glob Lit

Global register

Glob Reg

Global routine

Glob Rout

Keyword macro

KeyWMacr

Keyword macro formal

KeyWForm

Label

Linkage

Literal

Compiler Output

Table 2-2 (Cont.):

Symbol Type Abbreviations

Symbol Type

Abbreviation

Local

Macro

Map

Macro formal

MacrForm

Symbol without a declaration

NotDecl

Own

Psect

Routine

Routine formal

RoutForm

Structure

Structur

Stacklocal

Stackloc

Structure formal

StruForm

Name which is not bound

Unbound

Undeclare

Undeclar

The NotDecl abbreviation indicates the use of a symbol that has not been
declared. Thus, the appearance of NotDecl in the type field indicates an
error.
The Enable, Forward, ForwRout, Map, or Undeclar abbreviation refers to
symbols that are declared elsewhere as routine or data-segment names.
Thus, the appearance of any of these abbreviations in the type field
usually indicates an error.
The Unbound abbreviation indicates that the compiler made no attempt
to find a declaration for the symbol name because the name is not bound
to a symbol. For example, a symbol in a macro actual-list, or in the
false branch of a %IF compile-time conditional-function, is declared as
Unbound.

Compiler Output

2-29

As an example of using the symbol name and type fields, consider the
following code segment:
00050
00051
00052
00053

BEGIN
LOCAL

00080
00081
00082
00083
00084

END;

BEGIN
LOCAL
ALPHA;

00095

END;

ALPHA,

GAMMA;

The appearance of the symbols in the cross-referencing listing would be as
follows:
ALPHA

Local
Local
Local

GAMMA

52
84
53

Defined Field

The defined field identifies the compiler listing line number of the declaration or the library (Lib) file number and has a fixed length of five
characters. Exceptions occur with the NotDecl and Unbound symbol
types. Because the symbol name in these cases cannot be associated with
a declaration, no line number can appear, and the field is blank. The
following example depicts the appearance of line numbers and a library
file number in the defined field:
A
B

COMB

Own
Own
Macro

5
6
Lib01

20=
20=
20=

Note that a cross-reference map appears at the bottom of the listing which
locates and identifies each compiled file (source, require, or library) by
its initial line number and its system location (device, directory, and file
specification).

2-30 Compiler Output

Referenced Field

The referenced field lists additional references and uses of the symbol.
Each entry consists of a 5-character line number (or a library file number)
and a 2-character usage field. If the references require more than one line,
the additional entries appear on subsequent lines.
The 2-character usage-fields describe the way in which the symbols are
used. A usage-field may consist of none, one, or two of the following
characters:
Flag

Meaning

Declaration -Usage
e

EXTERNAL, EXTERNAL ROUTINE, or EXTERNAL
LITERAL declaration

FORWARD or FORWARD ROUTINE declaration

MAP declaration

Condition handler enabling

UNDECLARE declaration

Data-Usage
Fetch
Store
c

Routine call

Address use

Indirect use

A blank usage field indicates that usage is implied by the type of symbol,
for example, a macro name used within a macro expansion or a structure
name used as a structure-attribute in a declaration.
An ( e ), ( f ), ( m ), ( h ), or ( u) flag appearing in the usage field indicates a
reference to the symbol name within an EXTERNAL, FORWARD, MAP,
ENABLE, or UNDECLARE type declaration.
The fetch flag (.) indicates that a data segment has been "fetched from"
a location defined by the symbol name, while the store flag ( =) indicates
that a value has been "stored into" a location defined by the symbol name.

Compiler Output 2-31

The address-use flag (a) indicates that the address of a data segment,
defined by the symbol name, has been stored into another data segment.
For example, A = B indicates that the address of the data segment defined
by B is stored in data segment A. Thus, symbol B would be flagged (a)
for its use as an address, and symbol A would be flagged ( =) for its use as
storage.
The indirect-use flag (@)never appears alone. This flag is always combined with the remaining data-usage flags to indicate that a data segment
has been used indirectly, such as fetched from (@.) or stored into (@=);
however, note that all multiple levels of indirection are flagged the same
as a single level of indirection.
The following list provides samples of the 2-character data-usage codes.
The examples reflect direct and indirect data uses of symbol B as a BLOCK
structure and then as a REF BLOCK structure.
Code

B;BLOCK[n]

B:REF BLOCK[n]

A= .. B

A= ... B

A= B[C]

A= .B

A= .B[C]

B =.A
(.B) =.A

B[C] =.A

@=
@=

B() =A

(.B) ()=A

Thus, in relation to direct and indirect addressing, the utility recognizes
ordinary structures and FIELD references. For example, consider the
following code segment where explicit FIELD references are made to data
segments:

2-32

Compiler Output

00030
00031
00032
00033
00034
00035
00036
00037
00038
00039

FIELD
My_fields =
SET
This_field = [0,0,8,0],
That_field = [0,1,8,0]
TES;
OWN
B : REF BLOCK[] FIELD (My_fields);
B[This_field] = .B[That_field] + 1;

The cross-reference listings for B are as follows:
_B

Own

390=

THAT_FIELD
THIS_FIELD

Field
Field

34
33

39.
39=

390.

Note that because Bis declared as a REF structure, the structure references
to Bare indirect references.
The next code example reflects an indirect address usage of B:
00030
00031
00032
00033
00034
00035
00036
00037
00038

FIELD
My_fields =
SET
This_field = [0,0,8,0],
That_field = [0,1,8,0]
TES;
OWN
B : REF BLOCK[] FIELD (My_fields);

00108

C = B[That_field]

The listing for B is now as follows:
B

Own

1080a

THAT_FIELD

Field

108

In this example, B points to a BLOCK in memory. Through B, an address
within the BLOCK is indirectly stored in C; thus, an indirect address use is
flagged for B.

Compiler Output 2-33

2.3.3

Output Listing with Cross-Reference Listing
The listing in Figure 2-9 includes a cross-reference listing that was produced by compiling module TEST with the following options:
$ BLISS/SOURCE_LIST:(REQUIRE)/LIST/CROSS_REFERENCE TEST

Note that the listing includes cross-referenced information for the
LIBRARY and REQUIRE files. The reference list is followed by a crossreference map, which specifies the first and last lines of the files used, and
a flags legend, which describes the codes used in the referenced field.

2-34 Compiler Output

Figure 2-9:

Output Listing with Cross-Reference Listing Included

TEST

VAX Bliss-32 V4.3
DISK$:[DIRECTORY]TEST.BLI;l

2-Mar-1987 14:17:29
16-Apr-1983 20:02:35
0001
0002
0003
0004
0005
0006
0007
0008
0009
0010

module test (main
begin

Page

1
( 1)

rnainprog)

own
a'

1
1
1
1

external routine
error;
library 'combn'
require 'rfact'

ZK-5995/1 ·HC

ROOll
R0012
R0013
R0014
R0015
R0016

ROUTINE FACT (N) =
IF .N GTR 1
THEN
.N * FACT(.N ELSE

04
EF

AC
AF
50

so
Routine Size:

2
( 1)

s
s

Page

00000 A:
00004 B:

n
0
3
"'5!.
~

VAX Bliss-32 V4.3
DISK$:[DIRECTORY]RFACT.REQ;2

2-Mar-1987 14:17:29
13-Apr-1983 10:27:34

TEST

26 bytes,

Routine Base:

0000
AC Dl
OE 15
C3
01
FB
01
AC C4
04
DO
01
04

00000 FACT:
00002
00006
00008
00000
00011
00015
00016 1 $:
00019

.TITLE

TEST

. PSECT

$OWN$, NO EXE, 2

.BLKB
.BLKB
.EXTRN

ERROR

.PSECT

$CODE$,NOWRT,2

.WORD

save nothing
If, 11

CMPL
BLEQ
SUBL3
CALLS
MULL2
RET
MOVL
RET

0011
0012

11, N, -(SP)
t1,
If,

0014

FACT
RO

11, RO

0012
0016

$CODE$ + 0000

ZK·5995/2·HC

w
c.n

(Continued on next page)

N
I

Figure 2-9 (Cont.):

n
3

TEST

w
c:n

Output Listing with Cross-Reference Listing Included
2-Mar-1987 14:17:29
16-Apr-1983 20:02:35

"E.

s
s

0017
0018
0019
0020
0021
0022
0023
0024

VAX Bliss-32 V4.3
DISK$:[DIRECTORY)TEST.BLI;l

Page

3
( 1)

routine mainprog =
begin
a= combinations (3, 2);
b =combinations (6, 4);
VMS wants a success return
end;

64
53
64
52

0000'

64
50
53

64
53
64
52

0000'

Routine Size:
0025
0026
0027

1
0

64
50
53
50

70 bytes,

Routine Base:

OOlC 00000 MAINPROG:
.WORD
MOVAB
AF 9E 00002
OD 00006
PUSHL
03
FB 00008
CALLS
01
50
DO OOOOB
MOVL
00 OOOOE
PUSHL
01
01
FB 00010
CALLS
50
DO 00013
MOVL
02
DO 00016
PUSHL
01
FB 00018
CALLS
C4 00018
MULL2
52
50
C7 OOOlE
DIVL3
06
OD 00024
PUSHL
FB 00026
CALLS
01
50
DO 00029
MOVL
02
DD 0002C
PUSHL
01
FB 0002E
CALLS
50
DO 00031
MOVL
DD 00034
PUSHL
04
CALLS
01
FB 00036
C4 00039
MULL2
52
50
C7 0003C
DIVL3
MOVL
01
DO 00042
04 00045
RET

Save R2,R3,R4
FACT, R4
#3
#1, FACT
RO, R3

0018
0020

u
U,
RO,
#2
#1,
R2,
RO,

FACT
R2
FACT
RO
R3, A
0021

#1,
RO,
#2
#1,
RO,
#4
#1,
R2,
RO,
# 1,

FACT
R3
FACT
R2
FACT
RO
R3, B
RO

0024

$CODE$ + OOlA

end
eludom

PSECT SUMMARY
Name
$OWN$
$CODE$

Attributes

Bytes

NOVEC,
WRT,
NOVEC,NOWRT,

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

LCL,
LCL,

REL,
REL,

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

ZK-5995/3-HC

(Continued on next page)

Figure 2-9 (Cont.):

Output Listing with Cross-Reference Listing Included
2-Mar-1987 14:17:29
16-Apr-1983 20:02:35

TEST

Type

Symbol

Defined

VAX Bliss-32 V4.3
DISK$:[DIRECTORY]TEST.BLI;l

Page

4
( 1)

Referenced ...

------------ Own
-------- ----- ---------------5
20=

A
B
COMB
COMBINATIONS
ERROR
FACT
MAINPROG
N

Own
6
Macro
LibOl
Macro
LibOl
ExtRout
8
Routine
11
Routine
18
RoutForm
11

Line #

Event

11
16
27

Source (start)
Module TEST
Library #1
Require (start)
Require (end)
Eludom TEST

21=
20
20
20
14c
12.

21
21
21

20c

2lc

14.

CROSS REFERENCE MAP
File ...
DISK$:[DIRECTORY]TEST.BLI;l
DISK$:[DIR&CTORY]COMBN.L32;1
DISK$:[DIRECTORY]RFACT.REQ;2

KEY TO REFERENCE TYPE FLAGS

Fetch
Store
Routine call
Address use
Indirect use
External, external routine, or external literal declaration
Forward or forward routine declaration
Condition handler enabling
Map declaration
Undeclare declaration

Library Statistics
C")

3
"5!.
~

File
DISK$:[DIRECTORY]COMBN.L32;1

Total

Symbols
Loaded

Percent
100

Pages
Mapped

Processing
Time
00:00.l

s.
s.

N
I

.....

ZK-5995/4-HC

(Continued on next page)

'I"

Figure 2-9 (Cont.):

Output Listing with Cross-Reference Listing Included

CCI
C")

TEST

2-Mar-1987 14:17:29
16-Apr-1983 20:02:35

3
"S!.

s
s

"'C

Page

5
( 1)

COMMAND QUALIFIERS

VAX Bliss-32 V4.3
DISK$: (DIRECTORY] TEST. BLI; 1

BLISS/SOURCE_LIST:(REQUIRE)/LIST/CROSS_REFERENCE TEST
Size:
96 code + 8 data bytes
Run Time:
00:01.7
Elapsed Time:
00:20.3
Lines/CPU Min:
947
Lexemes/CPU-Min:
7298
Memory Used:
28 pages
Compilation Complete
ZK-5995/5-HC

2.4 Compilation Summary
The compilation summary appears at the end of every compilation listing
and consists of the following information:
•
•
•
•

•
•
•
•
•

2.5

The routine size and program section relative starting address (following each routine)
A program section summary (at the end of the module)
If a cross-reference listing is added, a cross-reference map of the files
used and the line number where each file is first referenced
If a cross-reference listing is added, a key to the meaning of the
usage-field characters
Library usage statistics indicating the libraries used and the number of
names loaded from each library (omitted if no libraries are used)
The number of memory pages mapped and the processing time
The command line used to compile the module
The number of warnings and errors (omitted if no warnings or errors
exist)
A summary of statistics for the module, consisting of size of code and
data (in bytes); run time; elapsed time; number of lines and lexemes
processed per CPU minute; memory used; and a statement that the
compilation is complete

Error Messages
The BLISS compiler detects two types of errors: 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. The warning and fatal error 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 the 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.

Compiler Output 2-39

A warning error message begins with the indentification WARN. For
example, the routine declaration for IFACT includes a coding mistake, as
follows:
RESULT = .REULT*.I;

The BLISS compiler detects this error and reports the warning message
shown in the following segment from the output listing:
0014 2
RESULT= .REULT*.I;
; WARN#OOO
.......... 1 11 :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:
ROUTINE RFACT (N =

The BLISS compiler detects this error and reports the message given in the
following segment from the output listing:
0013 2
!NCR I FROM 2 TO .NDO
WARN#OOO
..................... 1 11 :0013
Undeclared name: NDO
0014 2
RESULT= .REULT*.I;
WARN#066
......... 1 11:0014
Two consecutive operands with no intervening operator.
A "DO" has been inserted
WARN#OOO
................. 1 11:0014
Undeclared name: REULT
0015 2
.RESULT
0016 1
end
0017 1
0018 1
ROUTINE RFACT (n =
ERR #071
2 ...... 3 ......... 1 11:0018 13:0016
Missing comma or closing bracket in formal parameter list for RFACT
The incorrect delimiter was "="

Omitting the blank between the name N and the keyword DO caused
another warning, while omitting the close parenthesis, that is (N =),
caused one fatal error. With the absence of a blank seperator, the compiler
sees NDO and RESULT as two consecutive operands with no intervening
operator and inserts a DO. However, when the compiler fails to find the
close parenthesis, it cannot make syntactic sense of the line; therefore, it
reports a fatal error message and suppresses the production of an object
file.

2-40

Compiler Output

Note that, although the compiler continues to check the syntax of the
remainder of the module, some text may be left unscanned. Also, the scan
process can sometimes cause 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.
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:
!NCR I FROM 2 TO .NDO
0013 2
..................... 1
11 :0013
; WARN#OOO
; Undeclared name: NDO

The first error message line indicates a warning (WARN) and provides the
error message 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 at which the error was
detected

Indicates the beginning of the current control scope

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

Compiler Output 2-41

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 input at which the error was
detected

L2:nnnn

Indicates the line nnnn at which the current control scope
begins

L3:nnnn

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

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-10. This
version of TESTFACT includes the coding error illustrated in the above
examples. The error message at the end of the program identifies with
line indicators the point at which the error was 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.
For example:

2-42

Compiler Output

Example 2-1:

Example of Error Messages in Source Listing

(header)
0001 0 MODULE TESTFACT (MAIN = MAINPROG)
0002 0 BEGIN
WARN#048 1 L1:0002
Syntax error in module head
0003 1
0004 1 OWN
0005 1
A,
0006 1
B;
0007 1
0008 1 ROUTINE !FACT (N)
0009 2
BEGIN
0010 2
LOCAL
0011 2 RESULT;
0012 2
RESULT = 1;
0013 2
!NCR I FROM 2 TO .NDO
WARN#OOO ..................... 1 L1:0013
Undeclared name: NDO
0014 2 RESULT = .REULT*.I;
WARN#066 ........ 1 L1:0014
Two consecutive operands with no intervening operator. A "DO" has been inserted
WARN#OOO ................. 1 L1:0014
Undeclared name: REUL!
0015 2
.RESULT
0016 1
END;
0017 1
0018 1 ROUTINE RFACT (N =
ERR #071
2 ...... 3 ......... 1 L1:0018 L2:0018 L3:0016
Missing comma or closing bracket in formal parameter list for RFACT
The incorrect delimiter was 11 =11
0019 1
IF .N GTR 1
0020 1
THEN
0021 1 .N * RFACT(.N - 1)
0022 1
ELSE
0023 1 1;
0024 1
0025 1 ROUTINE MAINPROG =
0026 2
BEGIN
0027 2
A= IFACT(5);
0028 2
B = RFACT(5);
0029 2
0030 2
1 ! VMS wants a success return
0031 1
END;
0032 1 END
0033 0 ELUDOM

(Continued on next page)

Compiler Output

2-43

Example 2-1

Information:
Warnings:
Errors:

2-44

Compiler Output

0
4
1

(Cont.):

Example of Error Messages in Source
Listing

Chapter 3

Linking, Executing, and Debugging
This chapter describes the process of linking, executing, and debugging a
BLISS program.

3.1

Linking
Before you can execute your program, you must use the VMS Linker to
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 as follows:
•

To link a single module, use the following command:
$

•

LINK ALPHA

In response to this command, the linker reads the object module in
ALPHA.OBJ and creates the executable image ALPHA.EXE.
To link the modules ALPHA, BETA and GAMMA, use the following
command:
$

LINK ALPHA.BETA.GAMMA

In response to this command, the linker combines the object module in the file ALPHA.OBJ with the object modules BETA.OBJ and
GAMMA.OBJ to produce the single executable image ALPHA.EXE,
which can then be executed.
The link operation is described in detail in the VAX/VMS Linker Reference

Manual.
Linking, Executing, and Debugging

3-1

3.1.1

LINK Command Syntax
The syntax of the LINK command is as follows:
LINK [/qualifier ... ] object-file, ...

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
executable 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, the VMS Debugger
is linked with the specified object-files.

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

generally implies that the program is larger than 32KB.
Specifying the following module qualifier causes the compiler to generate
long displacement values for instruction operands:
ADDRESSING_MODE(EXTERNAL=LONG_RELATIVE, NONEXTERNAL=LONG_RELATIVE)

3.2 Executing a Linked Program
To run your program, use the executable image produced as a result of 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 DCL, which then prompts
for another command.

3-2

Linking, Executing, and Debugging

3.3 Debugging
The VMS Debugger is used to debug or test BLISS programs. The following discussion of BLISS debugging assumes that you are familiar
with using the debugger for VAX MACRO programs, as described in the
VAX/VMS Debugger Reference Manual. This section describes BLISS debugging facilities primarily in terms of how such usage differs from that of
the MACRO-level debugger.
The debugger provides a number of features specifically designed for more
convenient debugging of BLISS programs. These BLISS-specific features
are as follows:
•

•
•
•

•
•

Debug expression syntax that is consistent with BLISS language
syntax: radix control operators, arithmetic- and address-expression
operators, field selectors, and so on
Support of the fetch operator in arithmetic expressions
Expression evaluation according to BLISS rules for operator 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 EXAMINE X <15,3,0>

In combination, these features 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.

Linking, Executing, and Debugging

3-3

3.3. 1 Initialized Modes and Types
When you initiate a debugging session for a BLISS program, the debugger
provides the information message:
1.DEBUG-1-INITIAL, language is BLISS, module set to 1 ABC 1

ABC represents your main module name. For BLISS, the initial entry/ display modes are set to the following:
SYMBOLIC, HEXADECIMAL

You can change these mode settings with the SET MODE command and
can restore them to the initial settings with the CANCEL MODE or SET
LANGUAGE BLISS commands. The initialized modes are the same as
those for MACRO.
The initial setting for the default type is as follows (refer to the SET TYPE
command in Section 3.3.11.):
LONG INTEGER

The initial scope is PC scope.

3.3.2

Debugger 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 pre-declared structures), and BLISS field-references for specifying bit fields.
(Debugger commands are summarized at the end of this chapter.)
Experienced VMS Debugger users should note in particular that, in
expressions, the BLISS dot symbol ( . ) is recognized instead of the at sign
(@) character as the debugger "contents" or indirect operator, and that the
previous location symbol ( ") 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 an addition to those recognized in MACRO mode. These differences are noted.
In all cases the operator usage is BLISS-like in that the meanings assigned

3-4

Linking, Executing, and Debugging

to special characters and symbols in debugger commands are consistent
with BLISS operator semantics.
Note that the significance of special characters as delimiters in debugger
commands is the same for both BLISS and MACRO debugging. Also
in order to maintain a reasonable correspondence with the VAX/VMS
Debugger Reference Manual, the informal categories "arithmetic expression"
and "address expression" are used below 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.
The following restrictions, relative to full BLISS expression syntax, apply
to expressions in debug commands:
•
•

•
•
•
•

Routine or function calls are invalid as part of an expression.
The assignment operator ( =) is invalid within an expression. (The
equal sign character can be used only as a separator in DEPOSIT and
DEFINE commands.)
The BLISS relational operators (for example, EQL, NEQ, and LSS) are
not supported.
BLISS executable functions are not supported.
Control expressions are not supported.
Declarations are not supported.

Linking, Executing, and Debugging

3-5

Table 3-1 : Arithmetic Expression Operators
Character

Interpretation
Fetch (prefix) operator

Arithmetic addition (infix) operator or (prefix) plus sign
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

%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

Precedence operators; do (enclosed) first (unlike MACRO syntax)

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-6

Linking, Executing, 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 path names, as in MACRO
syntax.)

"Contents of" or indirect operator, when used as a prefix operator
(unlike MACRO syntax).
Range operator (low address:high address) for the EXAMINE
command.·

3.3.4. 1

Current Location Symbol ( . )

Used either by itself or as an operand in an expression, the current
location symbol (.) 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 symbol is assigned different meanings depending on 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 an 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 following command will display the
address of INBUF (that is, the contents of location PTR):
EXAMINE .

I Examine current location I

The following command will display the contents of location INBUF:
EXAMINE ..

I Examine current location indirect I

Linking, Executing, and Debugging

3-7

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

I Examine current location plus 4 I

In contrast, note 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 (") 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.3.4.2

Last Value Displayed Symbol(\)

You can use the backslash character ( \) 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, 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-8

Linking, Executing, and Debugging

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 as
follows:
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 the VAX/VMS Debugger

Reference Manual, follow:
DBG>DEPOSIT MASK = .MASKA4

This command shifts the current contents of the location MASK four bit
positions to the left:
DBG>EXAMINE .R7 : .R7+Y.DEC'20'

This command displays the current contents of the 21 bytes beginning
with the location addressed by general register 7.

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 its MACRO usage, however, the colon is not used in the
EVALUATE command to express a bit-field specification. (In BLISS use,
the standard BLISS field-selector notation is used instead, as described in
Section 3 .3 .5.)

Linking, Executing, and Debugging

3-9

Several examples of range-operator usage, modified from those given in
the VAX/VMS Debugger Reference Manual, follow:
DBG>EXAMINE/ASCII:1 INBUF : INBUF+6
DBG>EXAMINE . : . + 1.DEC'200'
DBG>EXAMINE/INSTRUCTION .PC : .PC+10

In the first command example, the address expression INBUF is interpreted
as a nonstructured data reference because 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+1<0,8>: B

LISTER\INBUF+6<0,8>: G

If the type were ASCII:4, the first two longwords beginning at INBUF
would be displayed, as follows:
LISTER\INBUF<0,32>: ABCD
LISTER\INBUF+4<0,32>: EFGH

The use of structure references in EXAMINE commands and the format of
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. For example, suppose the following EXAMINE
commands are given, with the second command in "shorthand" form:
DBG>EXAMINE/ASCII:1 INBUF : INBUF+6
DBG>EXAMINE/ASCII:1

The following display would be produced:
LISTER\INBUF+7: H

3-1 0

Linking, Executing, and Debugging

If type ASCII:2 had been specified, the display would be as follows:
LISTER\>INBUF+8: IJ

If type ASCII:4 had been specified, the display would be as follows:
LISTER\INBUF+OA: KLMN

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. As in BLISS, the form of a field reference is as
follows:
address<position,size,ext>

where ext is 0 for unsigned extension and 1 for signed extension; or
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
must not exceed 32 in any case.
In the EXAMINE command, a field selector has the same meaning as
in the BLISS fetch context, because 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. For
example:
DBG>EXAMINE/ASCII INBUF+8
LISTER\INBUF+8<0,32>: IJKL
DBG>EXAMINE/ASCII:1 INBUF<72,8>
LISTER\INBUF+9<0,8>: J

Note that the address expression INBUF+8 is equivalent to the field
reference INBUF <64,32> .

linking, Executing, and Debugging

3-11

In an EVALUATE command, the meaning of a field selector depends on
whether a contents operator is specified (that is, whether 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 filed selector
has the same meaning and restrictions as in the BLISS nonfetch, nonassignment content. That is, the expression addr <p,s> 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 offset, with the
position value p interpreted as p/8. For example, assume (as above) that
the symbol INBUF has the value 1024:
DBG>EVALUATE/DEC INBUF<80,8>
1024

Note that the field reference INBUF <80,8> in the "nonfetch" context
is equivalent to the expression INBUF+lO (as also is INBUF <80,16> ,
INBUF <80,23> , or INBUF <80,32> , for example).
In the DEPOSIT command, a field selector in the address expression OJ.l
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 a contents operator is
specified.

3-12

Linking, Executing, and Debugging

3.3.8

Structure References
A BLISS-style structure reference can be used as a debugger addressexpression if the data segment referred to has a standard BLISS predeclared structure (VECTOR, BITVECTOR, BLOCK, or BLOCKVECTOR).
The debugger recognizes the following forms of structure reference:
•

For VECTOR-structured segments:
segname[actual_1]
segname[field-name]

•

For BITVECTOR-structured segments:
segname[actual_1]
segname[field-name]

•

For BLOCK-structured segmentsi
segname[actual_1,actual_2,actual_3,actual_4]
segname[field-name]

•

For BLOCKVECTOR-structured segments:
segname[actual_1,actual_2,---,actual_5)
segname[actual_1,field-name]

segname
Is a name declared with the appropriate structure-attribute or appropriate
REF structure-attribute.
actuaLi
Is an expression evaluated as a decimal integer representing a valid
access-actual for the given data structure.
field-name
Is a name declared in a source-program FIELD declaration that represents
a valid field-definition for the given data structure.

Linking, Executing, and Debugging

3-13

Note that access-actual values are interpreted in decimal unless a radix
operator is used, regardless of the current radix mode.
The following EXAMINE commands provide a simple example of structure
references and structured display format:
DBG>EXAMINE/ASCII INBUF[1]
LISTER\INBUF[1]: EFGH
DBG>EXAMINE/ASCII:16 INBUF[O]
LISTER\INBUF[O]: ABCDEFGHIJKLMNOP
DBG>EXAMINE/ASCII INBUF[O]:INBUF[3]
LISTER\INBUF[O]: ABCD
LISTER\INBUF[1]: EFGH
LISTER\INBUF[2]: IJKL
LISTER\INBUF[3]: MNOP
DBG>EXAMINE INBUF[1]:INBUF[2]
LISTER\INBUF[1]: 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 first structure
reference
2. Skips any remaining bits (up to seven) if the component does not end
on a byte boundary
3. 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)
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:
3-14

Linking, Executing, and Debugging

DBG>EVALUATE .INBUF[2]
4C4B4A49

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 INBUF
1024
DBG>EVALUATE INBUF[3]
1036

(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 a
backslash) following this type of command is the last access-actual
shown in the list: in this case, the value 0.
That evaluating the structure-reference BLK2[2,4,12,0] results in the
address value BLK2+8, because 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.

Linking, Executing, and Debugging

3-15

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 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.
Note that the debugger recognizes and supports REF segments 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-16

Linking, Executing, and Debugging

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),
because 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 the common
case where a name, explicitly declared as a permanent data segment in a
containing block, is redeclared (for example, LOCAL, STACKLOCAL, or
REGISTER) in one or more contained blocks.
In all such cases, the debugger knows only of the last declaration of a
given name that occurs in the source code for a routine; that is, 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 to optimize
the use of time and space.)
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 by either a value corresponding to a different temporary data segment or a compiler-defined temporary
value. The only way to resolve the resultant ambiguity (if examination
of such a value is necessary) is by carefully interpreting the object code
and examining the program counter when stepping through the routine in
question.

Linking, Executing, and Debugging 3-17

3.3.9

Saurce-Line Debugging
When the BLISS-32 compiler is executed under VMS Version 4 (or higher
versions), additional information is entered into the debugger 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).
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 because BLISS-32 is an optimizing compiler for an
expression language, you cannot access all source lines with the %LINE
syntax.
However, using the TYPE command, you can display the source text for
any line, including comments.
DBG>TYPE 17:19
Module TESTER
17: J= .J+1;
18: T= IFACT(5);
19: RETURN .T+J

!Check out 5! = 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 source code associated with a current PC
location as follows:
DBG>EXAMINE/SOURCE .PC
18: T= IFACT(5;)

3.3.10

Effect of Compilation and Link-Time Qualifiers
Using the qualifier /DEBUG in the link operation instructs 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 debugger instead of the user program.

3-18

Linking, Executing, and Debugging

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 also run. In reality, debugger
modules are mapped into memory; they are not physically there. (Refer to
the VAX/VMS 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 program sections are available to the
debugger. If the /TRACEBACK and /DEBUG qualifiers are given, you can
examine BIND, GLOBAL, EXTERNAL, OWN, LOCAL, STACKLOCAL,
and REGISTER data names in addition to the other names. Moreover,
you can use field names in structure accesses, reference literal names in
expressions, and listing source line-numbers to set breaks and examine
BLISS source code.
Recall that the /TRACEBACK qualifier is a compilation default, while the
/DEBUG qualifier is not.

3.3.11

Debugger Command Summary
This section summarizes commands that you can use 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; see SET TYPE for data
type keywords.
With the exception of ASCII character input, the debugger automatically
converts lowercase input to uppercase.
11

Address-expression" in the command syntax representations can be the
path name (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.
/1

Linking, Executing, and Debugging

3-19

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 before 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 DCL
Dictionary for information on the complete list of CTRL functions).
CTRL/X echoes at the terminal as "X.
All commands preceded by an astefisk ( * ) are available only with VMS
Version 3.
With the exception of CTRL functions, you terminate all command lines
by pressing the RETURN key.
@filespec
In debug mode, denotes an indirect command file that causes the debugger
to begin taking debugger commands from the indicated file. An indirect
command file can be invoked wherever any other debugger command
can be given. An indirect command file can contain any valid debugger
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 debugging process.
CALL name {(argument, ... J}
Calls a routine by its symbolic name or by its virtual address (an address
expression is invalid) with optional argument list. An argument list must
be enclosed by parentheses.
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 of zero. 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

Cancels breakpoint set at specified address, or cancels all breakpoints.
3-20

Linking, Executing, and Debugging

CANCEL EXCEPTION BREAK
Cancels the request that your program stop at an exception condition
(such as at a breakpoint).
CANCEL MODE
Restores initial entry/ display modes. This command does not change the
scope or the current language.
CANCEL MODULE module-name-list
CANCEL MODULE/ALL
Purges symbolic information associated with the named modules 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
Sets the scope to zero.
*CANCEL SOURCE{/module=modnam}
Cancels the current source directory search list established by previous
SET SOURCE commands. When the qualifier (/module=modname) is
used, the command cancels the effect 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
Cancels a tracepoint set at the specified address, cancels all opcode
tracing at call-type instructions, cancels all opcode tracing at branch-type
instructions, or cancels all tracepoints and opcode tracing.
CANCEL WATCH address-expression
CANCEL WATCH/ALL
~ancels a watchpoint set at the specified address, or cancels all watchpoints.
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.
Linking, Executing, and Debugging 3-21

CTRL/Y
Interrupts the debugger or executing program and transfers control to
DCL, as 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 DCL 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 your
program, type the following:
DBG>EXAMINE/INSTRUCTION .PC

CTRL/Z
Same result as EXIT; that is, terminates the debugging session and transfers control to DCL.
DEFINE symbol-name=value {,symbol-name=value, ... }
Equates the names on the name=value list with associated values for use
during the debugging session. The debugger searches these symbols first
when it requires either a definition for a symbolic entry or a symbolic
name to report a location.
DEPOSIT{/modifier ... } address-expressioTFdata{,data, ... }
Enters the data specified in the data list in the sequence of locations that
begins with the specified address. The modifier can be any mode or type
keyword. (Mode and type keywords can be mixed.)
EVALUA TE{/mode ... } expression , ...
Transforms input (which can be a field name, arithmetic expression,
ASCII string, VAX MACRO instruction, symbol, structure-reference, fieldreference, or numeric value) to associated values and displays the results.
This command can also be used for such things as a desk calculator, radix
converter, or symbol verifier. The debugger displays results in the order
in which you specify the input. The displayed decimal value of the field
name is a comma list of field components.
EXAMINE{/modifier ... } address{:addressj{,address{:address}
,

... }

Displays the current contents of the specified addresses. The colon signifies the range; that is, it displays the contents of the addresses from the
low adddress through the high address. The modifier can be any mode or
type keyword. (Mode and type keywords can be mixed.)

3-22

Linking, Executing, and Debugging

EXIT
Terminates the debugging session and transfers control to DCL. An EXIT
command within an indirect command file cancels one level of indirection;
an EXIT command given at terminal input level terminates the debugging
process.
GO {address-expression}
Starts or continues 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 attempt to restart at the
transfer address or any other address. Program behavior is unpredictable
when restarted.
*HELP topic {subtopic ... J
Displays a description, format, qualifiers, and parameters of a debugger
command as specified by the topic parameter; and displays qualifiers
and/ or parameters as specified by the subtopic parameter.
*SEARCH {/qualifier {/qualifier} J range string
Limits the debugger's search (of a source file) to specified program regions
for occurrences of the string. The qualifiers are as follows:
/ALL
Specifies a search for all occurrences of the string and a display of
every line in the specified range.
/NEXT
Specifies a search and display of only the first occurrence of the string
in the specified range. (This is the default.)
/IDENTIFIER
Specifies a search for an occurrence of a string in the range specified.
The string is displayed only if it is delimited 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 specified string.
(This is the default.)

Linking, Executing, and Debugging

3-23

The range parameter limits the search to a specified program region as
follows:
modname

Search the specified module from
line number zero to the end of the
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.

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 (by 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)}
Establishes a breakpoint at specified address (the breakpoint stops your
program before the instructi~n beginning with "address-expression" is
executed).

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

3-24 Linking, Executing, and Debugging

You can specify the /AFTER qualifier to defer a breakpoint as follows:
SET BREAK/AFTER:decimal-integer address-express {DO - - -}

The breakpoint is ignored until the nth 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 with the
following:
SET BREAK/AFTER:O address-expression

The first time the breakpoint is encountered, the debugger stops your
program and cancels the breakpoint.
SET EXCEPTION BREAK
Stops the program and reports the current program counter contents if an
exception condition occurs that was not initiated by a debugger command.
SET LANGUAGE language-name
Lets 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
Specifies a name other than the default name (DEBUG.LOG) for the
debugger log file. The command can also be used to generate multiple log
files during a single debugging session.
*SET MARGIN rm
*SET MARGIN lm:rm
*SET MARGIN Im:
*SET MARGIN :rm
Specifies the leftmost and rightmost source line character positions at
which to begin and end a line of source code. The default value for the
left margin is l, and the default value for the right margin is 255.
*SET MAJLSOURCE_F/LES n
Specifies the maximum number of source files that the debugger can keep
open at any one time.
SET MODE mode-keyword{,mode-keyword , ... J
Allows or inhibits the entry and display of data in specified formats.
Linking, Executing, and Debugging

3-25

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
Enters nonglobal symbols and program section names associated with
the program-module list into the debugger's symbol table, or enters
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, ... }
Turns the logging function on or off, displays or inhibits the display of
debugger commands executed from indirect command files or breakpoint
actions, and permits or suppresses debugger output, except error messages,
to the screen. Valid keywords are as follows:
LOG

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

NO LOG

Inhibit the creation of a debugger log file.

3-26 Linking, Executing, and Debugging

TERMINAL

Print all debugger output on the screen, including command
input, debugger responses, comment lines, and warning and
error messages.
Print only error messages; suppress all debugger output, including verified lines.

VERIFY

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

NO VERIFY

Do not echo command lines from indirect command file on the
screen.

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 message to be
printed; output is printed on the terminal.
The following symbols may appear in the log file and the screen:
Indicates a debugger response
!!

Indicates a comment line

To log all debugger command I/O in the log file, use the following
command:
SET OUTPUT LOG

SET SCOPE module-name{\routine-name ... J
Establishes an ordered list of path names for use with the debugger's symbol search rules. A path name completely and unambiguously identifies a
symbol. For BLISS, a path name is one of the following:
symbol-name
module-name{\routine-name ... }\symbol-name

The debugger evaluates an expression in which a symbolic entry appears
only if a definition was located for the entry. If it fails to locate a match
for a path name, the debugger reports the search failure and the symbol
name.

Linking, Executing, and Debugging

3-27

Special path names are available for use in the list of path names of a SET
SCOPE command:
Path Name

Meaning

Indicates the path name of the lexical entity. For example,
routine or block that contains the current program c.ounter.

1, 2, 3, ...

Path name 1 indicates the caller of the lexical entity containing
the current PC; path name 2 indicates the caller of path name 1,
and so on.
The path name\ preceding a symbolic name indicates a global
symbol of that name. For example:
EXAM \GLOBAL

This causes a search for a global symbol whose name is
GLOBAL; nonglobal symbols of the same name are ignored.

*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 the source files. The
command is used to locate source files that have been removed from
compile-time directories.
SET STEP keyword {,keyword, ... }
Establishes default conditions for the STEP command. Valid keywords are
as follows:

3-28

INSTRUCTION

Steps increment in VAX MACRO instructions.

INTO

Allows stepping through called routine.

LINE

Steps increment by listing line numbers.

Linking, Executing, and Debugging

OVER

Steps over called routine (make call transparent).

*SOURCE

Displays the line of source code that corresponds to the
instructions being executed.

*NOSOURCE

Inhibits the display of the line of source code corresponding to the instruction being executed.

SYSTEM

Allows stepping in system space.

NOSYSTEM

Inhibits stepping in system space (make execution transparent).

The initialized conditions for BLISS are INSTRUCTION, NOSYSTEM, and
OVER.
SET TR~CE address-expression
SET TRACE/CALL
SET TRACE/BRANCH
Sets a tracepoint at the specified address, or specifies tracing of all calltype or branch-type instructions. At a tracepoint, the debugger reports the
current program counter contents and then continues program execution
automatically.
SET TYPE
Specifies a data type to be associated to data when the debugger cannot
infer a type from its input.

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

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

BYTE

Interpret/display data in byte units.

INSTRUCTION

Interpret/display VAX MACRO instructions.

LONG

Interpret/display data in longword units.

WORD

Interpret/display data in word units.

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

Linking, Executing, and Debugging

3-29

SET WATCH address-expression
Reports if the contents of the specified locations 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
Reports the locations of current breakpoints and any relevant information
associated with them, such as DO command sequences and "after" options.
SHOW CALLS {n}
Reports current call level and the hierarchy of call levels that preceded
it (that is, traces 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 0 through 32767). If n is omitted, all preceding call levels
are reported.
SHOW LOG
Displays the name and status of the log file (see SET LOG.) The display
appears as follows:
[not] logging to 'filename'

*SHOW MARGIN
Displays the current source line margin settings that are being used for the
display of source code. The margin settings are established by the SET
MARGIN command. The default margin settings are left margin 1 and
right margin 255.
*SHOW MAJLSOURCE_F/LES
Displays the maximum number of source files that the debugger can keep
open at one time.
SHOW MODE
Reports the current entry/ display modes (see SET MODE).

3-30

Linking, Executing, and Debugging

SHOW MODULE
Lists program modules by name, indicates (by yes or no) whether their
associated symbol data exists in the debugger's symbol table and indicates
the approximate space required for the entry of each module's symbol
data. Lists also the amount of space currently unused. The debugger has
no knowledge of any program module not reported in this status report.
SHOW OUTPUT
Displays 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 the SET SEARCH
command or the default values of ALL and STRING.
SHOW SCOPE
Reports the current contents of SCOPE.
*SHOW SOURCE
Displays the current source directory search lists established by the SET
SOURCE or SET SOURCE/module=modname command.
SHOW STEP
Reports current default conditions for STEP (see SET STEP).
SHOW TRACE
Reports the locations of current tracepoints or that opcode tracing is in
effect.
SHOW TYPE
Reports the current type setting.
SHOW WATCH
Reports the locations of current watchpoints and the number of bytes
monitored by each watchpoint.
STEP{/keyword} {decimal-integer}
Begins program execution and then stops after executiilg the specified
number of instructions or listing lines. (If you do not specify a count,
single stepping is the default.) The count is a decimal integer between 0
through 32767.
Linking, Executing, and Debugging

3-31

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 lines of source code.

The initialized defaults for BLISS are INSTRUCTION, NOSYSTEM, and
OVER.
*TYPE { {modname\}line-number{:line-number} f,{modname\}line-number}:line-number} . .. } }

Displays the source language statements corresponding to the line numbers specified.
In effect, you can read all the source language statements in the program
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 either a single line 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-32 Linking, Executing, and Debugging

Chapter 4

Machine-Specific Functions
Machine-specific functions (also called built-in functions) allow you
to perform specialized VAX 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.
Compiling 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 results in a machine· instruction being generated
that is different from 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

Architecture Handbook.
Input Parameter Usage

The definitions of these functions require addresses as input parameters,
even where values could have been specified for what VAX terms "source
operands", which are a longword or less in size. For example, where a
length is required as the second input-parameter of the PROBER function,
the call is written as follows:
PROBER( ... ,UPLIT(5), ... )

or
PROBER( ... , Y.REF( .A+2), ... )

Machine-Specific Functions

4- 1

(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:
REGISTER R;
IF PROBER ( ... , R, ... ) THEN

is equivalent to:
REGISTER R;
IF PROBER( ... , Y.REF( .R), ... ) THEN

The following are general rules for the use of %REF and undotted register
names with the input parameters:
•
•

•

A %REF value cannot be used with a DESTINATION address.
With the exception of their use with TESTBITxx built-in functions,
an undotted register can only be used for operands that are BYTE,
WORD, LONG, or single-precision floating-point.
A register· name cannot be used as the address of a character string or
packed decimal string.

Output Parameter Usage

Output parameters allow the return of register contents that result from
executing certain machine-specific functions (such as CALLG).
For example:
BUILTIN
CALLG;
BIND
ARGLIST= UPLIT(1, PI);
CALLG( ARGLIST, MTH$DSIN; SINX[O], SINX[1] );

This code expands to the following:
CALLG ARGLIST, MTH$DSIN
MOVQ RO, SINX

4-2 Machine-Specific Functions

Notice in the syntax of the machine-specific function that output parameters are separated from input parameters by a semicolon.
Table 4-1:
Function
Processor
Register
Operations

Machine-Specific Functions
Description

MFPR

Move from processor register

MTPR

Move to processor register

Parameter
Validation
Operations
PROBER

Probe read accessibility

PRO BEW

Probe write accessibility

Program Status
Operations
BICPSW

Bit clear PSW

BISPSW

Bit set PSW

MOVPSL

Move from PSL

Queue
Operations
INSQUE

Insert entry into queue

INSQxl

Insert entry into queue interlocked

REM QUE

Remove entry from queue

REMQxl

Remove entry from queue interlocked

Machine-Specific Functions

4-3

Table 4-1 (Cont.):
Function

Machine-Specific Functions

Description

Bit Operations
FFC

Find first clear bit

FFS

Find first set bit

TESTBITCC

Test for bit clear; clear bit

TESTBITCCI

Test for bit clear; clear bit interlocked

TESTBITCS

Test for bit clear; set bit

TESTBITSC

Test for bit set; clear bit

TESTBITSS

Test for bit set; set bit

TESTBITSSI

Test for bit set; set bit interlocked

Arithmetic
Operations
ADAWI

Add aligned word interlocked

ADDD

Add D-floating operands

ADDF

Add F-floating operands

ADDG

Add G-floating operands

ADDH

Add H-floating operands

ADDM

Add multiword operands

ASHQ

Arithmetic shift quad

DIVD

Divide D-floating operands

DIVF

Divide F-floating operands

'1JIVG

Divide G-floating operands

DIVH

Divide H-floating operands

EDIV

Extended-Precision divide

EMUL

Extended-Pr~cision multiply

MULD

Multiply D-floating operands

MULF

Multiply F-floating operands

MULG

Multiply G-floating operands

4-4 Machine-Specific Functions

Table 4-1 (Cont.):
Function

Machine-Specific Functions

Description

Arithmetic
Operations
MULH

Multiply H-floating operands

SUBD

Subtract D-floating operands

SUBF

Subtract F-floating operands

SUBG

Subtract G-floating operands

SUBH

Subtract H-floating operands

SUBM

Subtract multiword operands

Arithmetic
Comparison
Operations
CMPD

Compare D-floating operands

CMPF

Compare F-floating operands

CMPG

Compare G-floating operands

CMPH

Compare H-floating operands

CMPM

Compare multiword operands

Arithmetic
Conversion
Operations
CVTDF

Convert D-floating to F-floating

CVTDI

Convert D-floating to integer

CVTDL

Convert D-floating to long

CVTFD

Convert F-floating to D-floating

CVTFG

Convert F-floating to G-floating

CVTFH

Convert F-floating to H-floating

CVTFI

Convert F-floating to integer

CVTFL

Convert F-floating to long

CVTGF

Convert G-floating to F-floating

CVTGH

Convert G-floating to H-floating

Machine-Specific Functions 4-5

Table 4-1 (Cont.):
Function

Machine-Specific Functions

Description

Arithmetic
Conversion
Operations

CVTGL

Convert G-floating to long

CVTHF

Convert H-floating to F-floating

CVTHL

Convert H-floating to long

CVTID

Convert integer to D-floating

CVTIF

Convert integer to F-floating

CVTLD

Convert long to D-floating

CVTLF

Convert long to F-floating

CVTLH

Convert long to H-floating

CVTRDL

Convert rounded D-floating to long

CVTRFL

Convert rounded F-floating to long

CVTRGL

Convert rounded G-floating to long

CVTRHL

Convert rounded H-floating to long

Character String
Operations

CMPC3

Compare characters 3 operand

CMPCS

Compare characters 5 operand

CRC

Cyclic redundancy calculation

LOCC

Locate character

MATCHC

Match characters

MOVC3

Move character 3 operand

MOVCS

Move character 5 operand

MOVTC

Move translated characters

MOVTUC

Move translated until character

SCANC

Scan characters

SKPC

Skip character

SPANC

Span characters

4-6 Machine-Specific Functions

Table 4-1 (Cont.):
Function

Machine-Specific Functions

Description

Decimal String
Operations
ASHP

Arithmetic shift and round packed

CMPP

Compare packed

CVTLP

Convert long to packed

CVTPL

Convert packed to long

CVTPS

Convert packed to leading separate numeric

CVTPT

Convert packed to trailing numeric

CVTSP

Convert leading separate numeric to packed

CVTTP

Convert trailing numeric to packed

EDITPC

Edit packed to character

MOVP

Move packed

Miscellaneous
Operations
BPT

Breakpoint

BUGL

Bugcheck with long operand

BUGW

Bugcheck with word operand

CAL LG

Call with general argument list

CHMx

Change mode

HALT

Halt processor

INDEX

Index (subscript) calculation

NOP

No operation

ROT

Rotate a value

XFC

Extended function call

The compiler attempts to optimize the code that corresponds to a machinespecific 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.

Machine-Specific Functions

4- 7

BLISS Source:
IF TESTBITSS( X<3,1> )
THEN
BEGIN
! CONSEQUENCE
END
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 expansion would be as follows:
BBSS 3,X,1$
BRW 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 the following example.
BLISS Source:
Y = TESTBITSS( X<1> )

Generated Code:
CLRL
BBCS
INCL

Y
#3,X,1$
Y

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 need to allocate a
temporary storage. For example:
BISPSW( Y.REF (Y.X'80'));

! ENABLE DECIMAL OVERFLOW

This call would be coded without any temporary being allocated, as
follows:
BISPSW rXSO

4-8 Machine-Specific Functions

; ENABLE DECIMAL OVERFLOW

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)

This might result in the following code:
MOVPSL R2

4.1

ADAWl-Add Aligned Word Interlocked
ADAWI

(SRCADOR, OSTADDR)

Parameters:

SRCADDR
Address of a word whose contents are added to the 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).
Result:

Contents of the PSL

4.2 ADDO-Add D-Floating Operands
ADDO (SRCTA, SRC2A, OSTA)

Parameters:

SRC1A
Address of a double-precision floating-point quadword used as the addend.
SRC2A
Address of a double-precision floating-point quadword used as the augend.

Machine-Specific Functions

4-9

DSTA
Address of a quadword where the sum is stored.
Result:

NOVALUE

4.3 ADDF-Add F-Floating Operands
ADDF

(SRC1A, SRC2A, DSTA)

Parameters:

SRC1A
Address of a single-precision floating-point longword used as the addend.

SRC2A
Address of a single-precision floating-point longword used as the augend.

DSTA
Address of a longword where the sum is stored.
Result:

NOVALUE

4.4 ADDG-Add G-Floating Operands
ADDG

(SRC1A, SRC2A, DSTA)

Parameters:

SRC1A
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.
4-1 0 Machine-Specific Functions

Result:
NOVALUE

4.5 ADDH-Add H-Floating Operands
AODH

(SRCTA, SRC2A, OSTA)

Parameters:

SRC1A
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.
Result:
NOVALUE

4.6 ADDM-Add Multiword Operands
ADDM

(SIZE, SRCTA, SRC2A, OSTA)

Parameters:

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

SRC1A
Address of extended multiprecision integer used as the addend.

SRC2A
Address of extended multiprecision integer used as the augend.

Machine-Specific Functions

4-11

DSTA
Address of the sum of source 1 and source 2.

Result:

NOVALUE

4.7 ASHP-Arithmetic Shift and Round Packed
ASHP

(SCALE, SRCLEN, SRCAOOR, ROUND, OSTLEN, OSTAOOR l·OUTO, OUT1, OUT2, OUT3])

Input Parameters:
SCALE
Address of a byte whose contents specify the scale count by a power of
10 (a positive count effectively multiplies while a negative count divides, a
zero count moves and affects condition codes).
SRCLEN
Address of a byte whose contents specify the length of the source string to
be scaled.
SRCADDR
Address of a quadword containing the quantity to be scaled.
ROUND
Address of a byte whose contents specify the decimal round operand (only
used when a negative count is specified).
DSTLEN
Address of a byte whose contents specify the length of the destination
string where the result is to be stored.
DSTADDR
Address of a quadword where the scaled result is to be stored.

4-12 Machine-Specific Functions

Output Parameters:

OUTO
Value returned in RO is zero.
OUT1
Value returned in Rl is the address of the byte containing the most
significant bit of the source string.
OUT2
Value returned in R2 is zero.
OUT3
Value returned in R3 is the address of the byte containing the most
sugnificant digit of the destination string.
Result:

NOVALUE

4.8 ASHO-Arithmetic Shift Ouad
ASHO

(SHIFT, SRCADOR, DSTADDR)

Parameters:

SHIFT
Address of a byte whose contents specify the shift count.
SRCADDR
Address of a quadword containing the quantity to be shifted.
DSTADDR
Address of a quadword where the shifted result is to be stored.
Result:

Contents of the PSL

Machine-Specific Functions 4-13

4.9 BICPSW-Bit Clear PSW
BICPSW

(MASKAOORJ

Parameters:
MASKADDR
Address of a word whose contents are to be ones complemented and
ANDed into the processor status word (PSW).
Result:

NOVALUE

4.10 BISPSW-Bit Set PSW
BISPSW

(MASKAOORJ

Parameters:
MASKADDR
Address of a word whose contents are to be ORed into the PSW.
Result:

NOVALUE

4.11 BPT-Break Point Trap
BPT ()

Parameters:
None
Result:

NOVALUE

4-14 Machine-Specific Functions

4.12 BUGL-Bugcheck with Long Operand
BUGL (ARG)

Parameters:
ARG
Link-time constant expression (LTCE) to be interpreted by the bugcheck
exception-handling code.
Result:

NOVALUE
The following example is based on the DISPAT module in the Fl lACP:
builtin

BUGW
external literal

BUG$_UNXSIGNAL;
BUGW( BUG$_UNXSIGNAL or 4 );

generates the code sequence:
.EXTRN BUG$_UNXSIGNAL
BUGW
.WORD BUG$_UNXSIGNAL!4

The inline generation of this code eliminates the need to create a PUT
containing hand-assembled code.

4.13 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
Machine-Specific Functions

4-15

4. 14 CALLG-Call with General Parameter List
CALLG

(ARGL/ST, RTN [; OUTO, OUT1])

Input Parameters:

ARGLIST
Address of the parameter list to be placed in the address pointer (AP)
register (must not be a register name or a %REF value).

RTN
Address of the routine to be called.
Output Parameters:

OUTO
Value returned in RO.
OUT1
Value returned in Rl.
Result:

Same as result of the routine that is called.
Note that 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 VMS linkage (BLISS and FORTRAN
in BLISS-32).
To pass a routine's argument list to another routine, use the following
sequence:
BUILTIN
AP,

CALLG;
CALLG(.AP,OTHERRTN);

4-16 Machine-Specific Functions

4.15 CHMx-Change Mode
CHME (ARG)
CHMK (ARG)
CHMS (ARG)
CHMU

(ARG)

Parameters:

ARG
Address of a word whose contents are used as a parameter code.
Result:

NOVALUE

4.16 CMPC3-Compare Characters 3 Operand
CMP3 (LENA, SRCTA, SRC2A [; OUTO, OUTT, OUT2, OUT3]) )

Input Parameters:

LENA
Address of a word containing the byte comparison lengths for string 1 and
string 2.

SRC1A
Address of the base of string 1.

SRC2A
Address of the base of string 2.
Output Parameters:

OUTO
Value returned in RO is the number of bytes remaining in string 1 (including the byte that terminated the comparison); RO is zero only if the strings
are equal.

Machine-Specific Functions

4-17

OUT1
Value returned in Rl is the address of the byte in string 1 that terminated
the comparison; if the strings are equal, RO contains an address equal to
one byte beyond string 1.
OUT2
Value returned in R2 equals RO.
OUT3
Value returned in R3 is the address of the byte in string 2 that terminated
the comparison; if the strings are equal, R3 contains an address equal to
one byte beyond string 2.
Result:

-1
SRClA less than SRC2A.

0
SRClA equal to SRC2A.
1
SRClA greater than SRC2A.

4.17 CMPCS-Compare Characters 5 Operand
CMPC5 (SRC1LENA, SRC1A, FILLA, SRC2LENA, SRC2A [;OUTO, OUT1, OUT2, OUT3])

Input Parameters:
SRC1LENA
Address of a word containing the length of string 1.
SRC1A
Address of the base of string 1.
FILLA

Address of a word containing a byte fill value, which extends the shorter
string to the length of the longer.
SRC2LENA
Address of a word containing the length of string 2.
4-18

Machine-Specific Functions

SRC2A
Address of the base of string 2.
Output Parameters:

OUTO
Value returned in RO is the number of bytes remaining in string 1 (including the byte which terminated the comparison); RO is zero if the strings
are of equal value and length or if string 1 was exhausted before the
comparison terminated.
OUT1
Value returned in Rl is the address of the byte that terminated the
comparison; if the comparison did not terminate before string 1 was
exhausted, Rl contains an address equal to one byte beyond string 1.
OUT2
Value returned in R2 is the number of bytes remaining in string 2 (including the byte that terminated the comparison); RO is zero if the strings
are of equal value and length or if string 2 was exhausted before the
comparison terminated.
OUT3
Value returned in R3 is the address of the byte in string 2 that terminated
the comparision; if the comparison did not terminate before string 2 was
exhausted, R3 contains an address equal to one byte beyond string 2.
Result:

-1
SRClA less than SRC2A.

0
SRClA equal to SRC2A.
1

SRClA greater than SRC2A.

4. 18 CMPD-Compare D-Floating Operands
CMPD

(SRCTA, SRC2A)

Machine-Specific Functions

4-19

Parameters:

SRC1A
Address of a quadword containing a double-precision floating-point value
(must not be the name of a register nor a %REF value).

SRC2A
Address of a quadword containing a double-precision floating-point value.
Result:

-1
SRClA less than SRC2A.

0
SRClA equal to SRC2A.
1

SRClA greater than SRC2A.

4.19 CMPF-Compare F-Floating Operands
CMPF (SRC1A, SRC2A)

Parameters:

SRC1A
Address of a longword containing a single-precision floating-point value.

SRC2A
Address of a longword containing a single-precision floating-point value.
Result:

-1
SRClA less than SRC2A.

0
SRClA equal to SRC2A.

1
SRClA greater than SRC2A.

4-20 Machine-Specific Functions

4.20 CMPG-Compare G-Floating Operands
CMPG (SRC1A, SRC2A)

Parameters:

SRC1A
Address of a quadword containing an extended double-precision floatingpoint value.

SRC2A
Address of a quadword containing an extended double-precision floatingpoint value.
Result:

-1
SRClA less than SRC2A.

0
SRClA equal to SRC2A.
1

SRClA greater than SRC2A.

4.21

CMPH-Compare ff-Floating Operands
CMPH (SRC1A, SRC2A)

Parameters:

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

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

Machine-Specific Functions 4-21

Result:

-1
SRClA less than SRC2A.

0
SRClA equal to SRC2A.

1
SRClA greater than SRC2A.

4.22 CMPM-Compare Multiword Operands
CMPP (SIZE, SRC1A, SRC2A)

Parameters:

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

SRC1A
Address of a longword containing an extended multiprecision value.

SRC2A
Address of a longword containing an extended multiprecision value.
Result:

-1
SRClA less than SRC2A.

0
SRClA equal to SRC2A.

1
SRClA greater than SRC2A.

4-22

Machine-Specific Functions

4.23 CMPP-Compare Packed
CMPP (SRC1LENA, SRCTAOOR, SRC2LENA, SRC2AOOR [; OUTO, OUTT, OUT2, OUT3])

Input Parameters:

SRC1LENA
Address of a word containing the length of the decimal string SRCl.
SRC1ADDR
Address of the base of packed decimal string SRCl.
SRC2LENA
Address of a word containing the l~ngth of decimal string SRC2.
SRC2ADDR
Address of the base of packed decimal string SRC2.
Output Parameters:

OUTO
Value returned in RO is zero.
OUT1
Value returned in Rl is the address of the byte containing the most
significant digit of string SRCl.
OUT2
Value returned in R2 is zero.
OUT3
Value returned in R3 is the address of the byte containing the most
significant digit of string SRC2.
Result:

-1
SRCl less than SRC2.

0
SRCl equal to SRC2.

Machine-Specific Functions 4-23

1
SRCl greater than SRC2.
Note that CMPP3 or CMPP4 is generated depending on the operands
provided.

4.24 CRC-Cyclic Redundancy Check
CRC

(TABLEADDR, INICRCADOR, STRLENADDR, STREAMADOR, 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 of the data stream in
bytes.
STREAMADDR
Address of the first byte of the data stream.
DSTADDR
Address of a longword where the resulting 32-bit CRC is to be stored.
Result:

NOVALUE

4.25 CVTDF-Convert D-Floating to F-Floating
CVTDF

(SRCA, DSTA)

4-24 Machine-Specific Functions

Parameters:
SRCA
Address of a quadword containing a double-precision floating-point value.
DSTA
Address of a longword where the single-precision floating-point conversion is stored.
Result:
1
No floating-point overflow.

0
Floating-point overflow.

4.26 CVTDl-Convert D-Floating to Integer
CVTOI

(SRCA, OSTA)

Parameters:
SRCA
Address of a quadword containing a double-precision floating-point value.
DSTA
Address where the integer conversion is stored.
Result:
1
No integer overflow.

0
Integer overflow.

4.27 CVTDL-Convert D-Floating to Long
CVTDL

(SRCA, OSTA)

Machine-Specific Functions

4-25

Parameters:

SRCA
Address of a quadword containing a double-precision floating-point value.
DSTA
Address of a longword where the integer conversion is stored.
Result:

1
No integer overflow.

0
Integer overflow.

4.28 CVTFD-Convert F-Floating to D-Floating
CVTFD

(SRCA, DSTA)

Parameters:

SRCA
Address of a longword containing a single-precision floating-point value.
DSTA
Address of a quadword where the double-precision floating-point conversion is stored.
Result:

NOVALUE

4.29 CVTFG-Convert F-Floating to G-Floating
CVTFG

4-26

(SRCA, DSTA)

Machine-Specific Functions

Parameters:

SRCA
Address of a longword containing a single-precision floating-point value.
DSTA
Address of a quadword where the extended double-precision floating-point
conversion is stored.
Result:

NOVALUE

4.30 CVTFH-Convert F-Floating to H-Floating
CVTFH

(SRCA, OSTA)

Parameters:

SRCA
Address of a longword containing a single-precision floating-point value.
DSTA
Address of an octaword where the extended-exponent double-precision
floating-point conversion is stored.
Result:

NOVALUE

4.31 CVTFl-Convert F-Floating to Integer
CVTFI (SRCA, OSTA)

Parameters:

SRCA
Address of a longword containing a single-precision floating-point value.
DSTA
Address of a longword where the integer conversion is stored.

Machine-Specific Functions

4-27

Result:
1
No integer overflow.

0
Integer overflow.

4.32 CVTFL-Convert F-Floating to Long
CVTFL

(SRCA, DSTA)

Parameters:

SRCA
Address of a longword containing a single-precision floating-point value.
DSTA
Address of a longword where the integer conversion is stored.
Result:

1
No integer overflow.

0
Integer overflow.

4.33 CVTGF-Convert G-Floating to F-Floating
CVTGF

(SRCA, DSTA)

Parameters:

SRCA
Address of a quadword containing an extended double-precision floatingpoint value.
DSTA
Address of a longword where the single-precision floating-point conversion is stored.
4-28 Machine-Specific Functions

Result:
NOVALUE

4.34 CVTGH-Convert G-Floating to H-Floating
CVTGH

(SRCA, OSTA)

Parameters:

SRCA
Address of a quadword containing an extended double-precision floatingpoint value.
DSTA
Address of an octaword where the extended-exponent double-precision
floating-point conversion is stored.
Result:
NOVALUE

4.35 CVTGL-Convert G-Floating to Long
CVTGL

(SRCA, OSTA)

Parameters:

SRCA
Address of a quadword containing an extended double-precision floatingpoint value.
DSTA
Address of a longword where the integer conversion is stored.
Result:
NOVALUE

Machine-Specific Functions

4-29

4.36 CVTHF-Convert H-Floating to F-Floating
CVTHF

(SRCA,DSTA)

Parameters:

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:

NOVALUE

4.37 CVTHG-Convert H-Floating to G-Floating
CVTHG

(SRCA, DSTA)

Parameters:

SRCA
Address of an octaword containing an extended-exponent double-precision
floating-point value.
DSTA
Address of a quadword where the extended double-precision floating-point
conversion is stored.

4.38 CVTHL-Convert H-Floating to Long
CVTHG

(SRCA, DSTA)

4-30 Machine-Specific Functions

Parameters:

SRCA
Address of an octaword containing an extended-exponent double-precision
floating-point value.
DSTA
Address of a longword where the integer conversion is stored.
Result:
NOVALUE

4.39 CVTID-Convert Integer to D-Floating
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:
NOVALUE

4.40 CVTIF-Convert Integer to F-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.
Machine-Specific Functions

4-31

Result:

NOVALUE

4.41 CVTLD-Convert Long to D-Floating
CVTLD

(SRCA, OSTA)

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:

NOVALUE
No overflow can occur.

4.42 CVTLF-Convert Long to F-Floating
CVTLF

(SRCA, OSTA)

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:

NOVALUE
No overflow can occur.
4-32

Machine-Specific Functions

4.43 CVTLH-Convert Long to H-Floating
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.44 CVTLP-Convert Long to Packed
CVTLP

(SRCA, DSTLENA, DSTADDR)

Parameters:

SRCA
Address of a longword containing an integer value.
DSTLENA
Address of a word containing the length of the destination string.
DSTADDR
Address of the base of the destination string.

Machine-Specific Functions

4-33

Result:
1
No decimal overflow.

0
Decimal overflow.

4.45 CVTPL-Convert Packed to Long
CVTPL

(SRCLENA, SRCADOR, OSTA)

Parameters:

SRCLENA
Address of a word containing the length of the source string.
SRCADDR
Address of the base of the source string.
DSTA
Address of a longword where the integer conversion is stored.
Result:
1
No integer overflow.

0
Integer overflow.

4.46 CVTPS-Convert Packed to Leading Separate Numeric
CVTPS

(SRCLENA, SRCADOR, DSTLENA, OSTADDR [; OUTO, OUT1, OUT2, OUT3])

Input Parameters:

SRCLENA
Address of a word containing the length of the source string.

4-34 Machine-Specific Functions

SRCADDR
Address of the base of the source string.
DSTLENA
Address of a word containing the length of the destination string.
DSTADDR
Address of the base of the destination string.
Output Para.meters:

OUTO
Value returned in RO is zero.
OUT1
Value returned in Rl is the address of the byte containing the most
significant digit of the source string.
OUT2
Value returned in R2 is zero.
OUT3
Value returned in R3 is the address of the sign byte of the destination
string.
Result:

1
No decimal overflow.

0
Decimal overflow.

4.47 CVTPT-Convert Packed to Trailing Numeric
CVTPS

(SRCLENA, SRCAOOR, TBLAODR, OSTLENA, OSTAOOR [; OUTO, OUT1, OUT2, OUT3])

Machine-Specific Functions 4-35

Input Parameters:
SRCLENA
Address of a word containing the length of the source string.
SRCADDR
Address of the base of the source string.
TBLADDR
Address of the table used to convert the sign.
DSTLENA
Address of a word containing the length of the destination string.
DSTADDR
Address of the base of the destination string.

Output Parameters:
OUTO
Value returned in RO is zero.
OUT1
Value returned in Rl is the address of the byte containing the most
significant digit of the source string.
·
OUT2
Value returned in R2 is zero.
OUT3
Value returned in R3 is the address of the sign byte of the destination
string.

Result:

1
No decimal overflow.
0
Decimal overflow.

4-36

Machine-Specific Functions

4.48 CVTRDL-Convert Rounded D-Floating to Long
CVTRDL

(SRCA, OSTA)

Parameters:

SRCA
Address of a quadword containing a double-precision floating-point value.
DSTA
Address of a longword where the integer conversion is stored.
Result:
1
No integer overflow.

0
Integer overflow.

4.49 CVTRFL-Convert Rounded F-Floating to Long
CVTRFL

(SRCA, OSTA)

Parameters:

SRCA
Address of a longword containing a single-precision floating-point value.
DSTA
Address of a longword where the integer conversion is stored.
Result:

1
No integer overflow.
0
Integer overflow.

Machine-Specific Functions

4-37

4.50 CVTRGL-Convert Rounded G-Floating to Long
CVTRGL

(SRCA, OSTA)

Parameters:

SRCA
Address of a quadword containing an extended double-precision floatingpoint value.
DSTA
Address of a longword where the integer conversion is stored.
Result:

1
No integer overflow.

0
Integer overflow.

4.51

CVTRHL-Convert Rounded H-Floating to Long
CVTRHL

(SRCA, OSTA)

Parameters:

SRCA
Address of an octaword containing an extended-exponent double-precision
floating-point value.
DSTA
Address of a longword where the integer conversion is stored.

4-38

Machine-Specific Functions

Results:
1

No integer overflow.

0
Integer overflow.

4.52 CVTSP-Convert Leading Separate to Packed
CVTSP

(SRCLENA, SRCADDR, DSTLENA, DSTADDR [;OUTO, DUTT, OUT2, OUT3])

Input Parameters:
SRCLENA

Address of a word containing the length of the source string.
SRCADDR

Address of the base of the source string.
DSTLENA

Address of a word containing the length of the destination string.
DSTADDR

Address of the base of the destination string.
Output Parameters:
OUTO

Value returned in RO is zero.
OUT1

Value returned in Rl is the address of the sign byte of the source string.
OUT2

Value returned in R2 is zero.
OUT3

Value returned in R3 is the address of the byte containing the most
significant digit of the destination string.

Machine-Specific Functions

4-39

Result:
1

No decimal overflow.

0
Decimal overflow.

4.53 CVTTP-Convert Trailing Numeric to Packed
CVTTP

(SRCLENA, SRCADDR, TBLADDR, DSTLENA, DSTADDR [; OUTO, OUTT, OUT2, OUT3])

Input Parameters:
SRCLENA

Address of a word containing the length of the source string.
SRCADDR

Address of the base of the source string.
TBLADDR

Address of the table used to convert the sign.
DSTLENA

Address of a word containing the length of the destination string.
DSTADDR

Address of the base of the destination string.
Output Parameters:
OUTO

Value returned in RO is zero.
OUT1

Value returned in Rl is the address of the most significant digit of the
source string.
OUT2

Value returned in R2 is zero.

4-40 Machine-Specific Functions

OUT3
Value returned in R3 is the address of the byte containing the most
significant digit of the destination string.
Result:
1
No decimal overflow.

0
Decimal overflow.

4.54 DIVD-Divide D-Floating Operands
DIVD (0/VSR, OIVIO, QUOT)

Parameters:

DIVSR
Address of a double-precision floating-point quadword used as the divisor.
DIVID
Address of a double-precision floating-point quadword used as the dividend.
QUOT
Address of a quadword where the quotient is stored.
Result:

NOVALUE

4.55 DIVF-Divide F-Floating Operands
DIVF (OVISR, OIVIO, QUOT)

Machine-Specific Functions

4-41

Parameters:

DVISR
Address of a single-precision floating-point longword used as the divisor.
DIVID
Address of a single-precision floating-point longword used as the dividend.
QUOT
Address of a longword where the quotient is stored.
Result:

NOVALUE

4.56 DIVG-Divide G-Floating Operands
OIVG

(OVISR, OIV/O, QUOT)

Parameters:

DIVSR
Address of an extended double-precision floating-point quadword used as
the divisor.
DIVID
·Address of an extended double-precision floating-point quadword used as
the dividend.
QUOT
Address of a quadword where the quotient is stored.
Result:

NOVALUE

4.57 DIVH-Divide H-Floating Operands
DIVH (0/VSR, OIV/O, QUOT)

4-42 Machine-Specific Functions

Parameters:

DIVSR
Address of an extended-exponent double-precision floating-point octaword
that is used as the divisor.
DIVID
Address of an extended-exponent double-precision floating-point octaword
that is used as the dividend.
QUOT
Address of an octaword where the quotient is stored.
Result:

NOVALUE

4.58 EDITPC-Edit Packed to Character
EDITPC

(SRCLENA, SRCADDR, PATTERN, DSTADDR [; OUTO, OUT1, OUT2, OUT3, OUT4, OUT5])

Input Parameters:

SRCLENA
Address of a word containing the length of the source string.
SRCADDR
Address of the base of the source string.
PATTERN
Address of the pattern-operator string.
DSTADDR
Address of the base of the destination string.
Output Parameters:

OUTO
Value returned in RO is the length of the source string.
OUT1
Value returned in Rl is the address of the byte containing the most
significant digit of the source string.
Machine-Specific Functions

4-43

OUT2
Value returned in R2 is zero.
OUT3
Value returned in R3 is the address of the byte containing the EO$END
pattern operator.
OUT4
Value returned in R4 is zero.
OUT5
Value returned in RS is the address of one byte beyond the last byte of
the destination string.
Result:
1

No decimal overflow.

0
Decimal overflow.

4.59 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 is to be stored.
REMAINDER
Address of a longword where the remainder is to be stored.
Result:

Contents of the PSL
4-44 Machine-Specific Functions

4.60 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 that is sign-extended to a quadword and added to
the product quadword.
PROD
Address of a quadword where the result is to be stored.
Result:

Contents of the PSL

4.61

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.
SIZADDR
Address of a byte whose content, when zero extended to 32 bits, has 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, begins at the
bit position specified by POSADDR, and extends toward increasing bit
numbers.
Machine-Specific Functions 4-45

BASEADDR
Address of a byte whose low bit is interpreted as position zero.
DSTADDR
Address of a longword where the position of the first bit found in the
specified state is to be stored.
Result:

1
No bit in the specified state is found in the field searched.

0
Otherwise.

4.62 HALT-Halt Processor
HALT

Parameters:

None
Result:

NOVALUE
Description:

This routine generates a HALT instruction.

4.63 INDEX-Index Calculation
INDEX (SUBSCRIPT, LOW, HIGH, SIZE, INOEXIN, INOEXOUT)

Parameters:

SUBSCRIPT
Address of a longword containing the subscript.
LOW
Address of a longword containing the lower bound of the subscript range.
4-46 Machine-Specific Functions

HIGH
Address of a longword containing the upper bound of the subscript range.
SIZE
Address of a longword containing the scale factor.
INDEXIN
Address of a longword containing the initial index value.
INDEXOUT
Address of a longword where the result is to be stored.

Result:

NOVALUE

4.64 INSOHI and INSOTl-lnsert Entry in Oueue, Interlocked
INSQHl(ENTRY, HEADER)

Insert entry in queue at head, interlocked

INSOTl(ENTRY, HEADER)

Insert entry in queue at tail, interlocked

Parameters:
ENTRY
Address of an entry to be inserted in a queue following the header.
HEADER
Address of the queue header.

Result:

0
If ENTRY was not the first entry to be inserted in the queue.
1
If the secondary interlock could not be acquired.

2
If ENTRY was the first entry to be inserted into the queue.

Machine-Specific Functions 4-4 7

Note that if a real result is needed, the instruction sequence generated for
these functions is as follows:
CLRL
INSQxI
BCS
BNEQ
INCL
INCL

1$:
2$:

tmp

ENTRY.HEADER
1$
2$
tmp
tmp

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

ENTRY.HEADER
1$
; Success
; Failure actions

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

4.65 INSOUE-lnsert Entry in Oueue
INSOUE

(ENTRY, PRED)

Parameters:
ENTRY

Address of an entry to be inserted in the queue after the entry specified by
PRED.
PRED

Address of an entry in a queue.
Result:

1
ENTRY was the first entry to be inserted into the queue.
0
Otherwise.

4-48 Machine-Specific Functions

4.66 LOCC-Locate Character
LOCC

(CHARA, LENA, AOOR [; OUTO, OUT1])

Input Parameters:

CHARA
Address of a byte containing the character to be located.

LENA
Address of a word containing the search string length.

ADDR
Address of the string to be searched.
Output Parameters:
OUTO
Value returned in RO is the number of bytes remaining in the string
(including the located one) if the byte is located; otherwise, RO is a zero.
OUT1
Value returned in Rl is the address of the byte located if the byte is
located; otherwise, Rl is the address of one byte beyond the string.
Result:
1

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

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

4.67 MATCHC-Match Characters
MATCHC

(OBJLENA, OBJAOOR, SRCLENA, SRCAOOR [; OUTO, OUT1, OUT2, OUT3])

Machine-Specific Functions

4-49

Input Parameters:
OBJLENA
Address of word containing the length of the pattern string.
OBJADDR
Address of the pattern string.
SRCLENA
Address of a word containing the length of the string to be searched.
SRCADDR
Address of the string to be searched.

Output Parameters:

OUTO
Value returned in RO is zero (if a match occurred); otherwise, RO is the
number of bytes in the object string.
OUT1
Value returned in Rl is the address .~f one byte beyond the object string
(if a match occurred); otherwise, it is the address of the object string.
OUT2
Value returned in R2 is the number of bytes remaining in the source string
after the match (if a match occurred); otherwise, R2 is zero.
OUT3
Value returned in R3 is the address of one byte beyond the last byte
matched (if a match occurred); otherwise, R3 is the address of one byte
beyond the source string.
Result:

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

0
No match was found (the Z condition code is dear).

4-50

Machine-Specific Functions

4.68 MFPR-Move from Processor Register
MFPR

(PROCREG, DSTADOR)

Parameters:

PROCREG
Processor register number.
DSTADDR
Address of a longword where the contents of the processor register is to
be stored.
Result:

NOVALUE

4.69 MOVC3-Move Character 3 Operand
MOVC3

(LENA, SRCADOR, OSTADOR [; OUTO, DUTT, OUT2, OUT3, OUT4, OUT5])

Input Parameters:

LENA
Address of a word containing the length of the source string.
SRCADDR
Address of the base of the source string.
DSTADDR
Address of the destination string.
Output Parameters:

OUTO
Value returned in RO is zero.
OUT1
Value returned in Rl is the address of one byte beyond the source string.
OUT2
Value returned in R2 is zero.
Machine-Specific Functions

4-51

OUT3
Value returned in R3 is the address of one byte beyond the destination
string.
OUT4
Value returned in R4 is zero.
OUT5
Value returned in RS is zero.

Result:

NOVALUE

4. 70 MOVC5-Move Character 5 Operand
MOVC5 (SRCLENA, SRCAOOR, FILL, OSTLENA, OSTAOOR [; OUTO, DUTT, OUT2, OUT3, OUT4, OUT5])

Input Parameters:
SRCLENA
Address of word containing the length of the source string.
SRCADDR
Address of the base of the source string.
FILL
Address of a byte containing the fill character.
DSTLENA
Address of word containing the destination-string length.
DSTADDR
Address of the destination string.

Output Parameters:
OUTO
Value returned in RO is the number of unmoved bytes remaining in the
source string; RO is nonzero only if the source string is longer than the
destination string.

4-52 Machine-Specific Functions

OUT1
Value returned in R1 is the address of one byte beyond the last byte in the
source string that was moved.
OUT2
Value returned in R2 is zero.
OUT3
Value returned in R3 is the address of one byte beyond the destination
string.
OUT4
Value returned in R4 is zero.
OUT5
Value returned in RS is zero.
Result:

NOVALUE

4.71 MOVP-Move Packed
MOVP (LENA, SRCAOOR, OSTAOOR [; OUTO, OUT1, OUT2, OUT3])

Input Parameters:
LENA

Address of a word containing the length of the source string.
SRCADDR
Address of the base of the source decimal string.
DSTADDR
Address of the base of the destination.

Machine-Specific Functions 4-53

Output Parameters:
OUTO
Value returned in RO is zero.
OUT1
Value returned in Rl is the address of the byte containing the most
significant digit of the source string.
OUT2
Value returned in R2 is zero.
OUT3
Value returned in R3 is the address of the byte containing the most
significant digit of the destination string.
Result:

NOVALUE

4. 72 MOVPSL-Move front PSL
MOVPSL (DSTADDR)

Parameters:
DSTADDR
Address of a longword where the contents of the PSL are to be stored.
Result:

NOVALUE

4.73 MOVTC-Move Translated Characters
MOVTC (SRCLENA, SRCADDR, FILL, TBLADDR, DSTLENA, DSTADDR [; OUTO, OUT1, OUT2, OUT3, OUT4,
OUT5])

4-54 Machine-Specific Functions

Input 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.
DSTLENA
Address of a word containing the destination length.
DSTADDR
Address of the destination string.
Output Parameters:
OUTO
Value returned in RO is the number of translated bytes remaining in the
source string; RO is nonzero only if the source string is longer than the
destination string.
OUT1
Value returned in Rl is the address of one byte beyond the last byte in the
source string that was translated.
OUT2
Value returned in R2 is zero.
OUT3
Value returned in R3 is the address of the translation table.
OUT4
Value returned in R4 is zero.
OUT5
Value returned in RS is the address of one byte beyond the destination
string.

Machine-Specific Functions

4-55

Result:

NOVALUE

4.74 MOVTUC-Move Translated Until Character
MOVTUC (SRCLENA, SRCAOOR, ESCAOOR, TBLAOOR, OSTLENA, OSTAOOR [; OUTO, OUT1, OUT2, OUT3,
OUT4, OUT5])

Input Parameters:
SRCLENA
Address of a word containing the length of the source string.
SRCADDR
Address of the base of the source string.
ESCADDR
Address of a byte containing the escape character.
TBLADDR
Address of the translation table (can be created with CH$TRANSTABLE).
DSTLENA
Address of a word containing the length of the destination string.
DSTADDR
Address of the base of the destination string.
Output Parameters:

OUTO
Value returned in RO is the number of bytes remaining in the source string
(including the byte that caused the escape); RO is zero only if the entire
source string was translated and moved without escape.
OUT1
Value returned in Rl is the address of the byte that resulted in destination
string exhaustion or escape; if no exhaustion or escape, Rl is the address
of one byte beyond the end of the source string.
OUT2
Value returned irt R2 is zero.
4-56 Machine-Specific Functions

OUT3
Value returned in R3 is the address of the table.
OUT4
Value returned in R4 is the number of bytes remaining in the destination
string.
OUT5
Value returned in RS is the address of the byte in the destination string
that would have received the translated byte that caused the escape,
or would have received a translated byte if the source string was not
exhausted; if no exhaustion or escape, RS is the address of one byte
beyond the end of the destination string.
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.75 MTPR-Move to Processor Register
MTPR (SRCAOOR, PROCREG)

Parameters:
SRCADDR
Address of a longword whose contents are to be loaded into the designated processor register.
PROCREG
Processor register number.

Result:

NOVALUE

4.76 MULD-Multiply D-Floating Operands
MULD (SRCTA, SRC2A, OSTA)

. Machine-Specific Functions 4-5 7

Parameters:

SRC1A
Address of a double-precision floating-point quadword used as the multiplier.

SRC2A
Address of a double-precision floating-point quadword used as the multiplicand.

DSTA
Address of a quadword where the product is stored.
Result:
NOVALUE

4.77 MULF-Multiply F-Floating Operands
MULF (SRCTA, SRC2A, DSTA)

Parameters:

SRC1A
Address of a single-precision floating-point longword used as the multiplier.

SRC2A
Address of a single-precision floating-point longword used as the multiplicand.

DSTA
Address of a longword where the product is stored.
Result:
NOVALUE

4-58

Machine-Specific Functions

4.78 MULG-Multiply G-Floating Operands
MULG (SRCTA, SRC2A, OSTA)

Parameters:

SRC1A
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.
Result:

NOVALUE

4.79 MULH-Multiply H-Floating Operands
MULH (SRCTA, SRC2A, OSTA)

Parameters:

SRC1A
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

Machine-Specific Functions 4-59

4.80 NOP-No Operation
NOP

()

Parameters:

None
Result:

NOVALUE

4.81

PROBER-Probe Read Accessibility
PROBER

(MOOEAOOR, LENGTHAOOR, BASEAOOR)

Parameters:
MODEADDR
Address of a byte whose contents specify a protection mode.
LENGTHADDR
Address of a word whose contents are zero extended decremented by 1
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.

0
Otherwise.

4-60 Machine-Specific Functions

4.82 PROBEW-Probe Write Accessibility
PROBEW (MOOEADOR, LENGTHAOOR, BASEAOOR)

Parameters:

MODEADDR
Address of a byte whose contents specify a processor mode.
LENGTHADDR
Address of a word whose contents are zero extended decremented by 1
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 write accessible.

0
Otherwise.

4.83 REMQHI and REMQTl-Remove Entry From Oueue,
Interlocked
REMQHI (HEADER, ADDR)

Remove from queue at head, interlocked

REMOTI (HEADER, ADDR)

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.

Machine-Specific Functions

4-61

Result:

0
The queue is not empty; an entry was removed.
1

The secondary interlock could not be acquired.

2
The queue is now empty; the last entry was removed.

3
The queue was already empty; no entry was removed.
The result of REMQxl 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 as follows:
CLRL
REMQxI
BCS
BVS
BEQL
DECL
1$: ADDL
2$: INCL

tmp
HEADER,ADDR
2$
1$
3$

tmp
#2,tmp
tmp

; Interlock failed
; Remove failed
; Removed an entry
; Removed last entry

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

HEADER,ADDR
1$

Entry removed
Remove failed

4.84 REMQUE-Remove Entry from Queue
REMQUE (ENTRY, AOOR)

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.
4-62 Machine-Specific Functions

Result:
Initial
State

Final
State

Entry
Removed

Not
empty

Yes

Not
empty

Empty

Yes

Empty

Value

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

4.85 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.86 SCANC-Sca" Characters
SCANC

(LENA, ADDR, TBLADDR, MASKA [; OUTO, OUT1, OUT2, OUT3])

Machine-Specific Functions

4-63

Input Parameters:
LENA

Address of a word containing the length of the 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 the mask to use in scanning.
Output Parameters:

OUTO
Value returned in RO is the number of bytes remaining in the string
(including the byte that produced a nonzero AND result); RO is zero only
if there was a zero AND result.
OUT1
Value returned in Rl is the address of the byte that produced a nonzero
AND result or (if no nonzero AND result) the address of one byte beyond
the string.
OUT2
Value returned in R2 is zero.
OUT3
Value returned in R3 is the address of the table.
Result:
If the SCANC fails to find a match, the result is 0. Otherwise, the result is
the address of the byte that produced a nonzero AND with the MASK.

4.87 SKPC-Skip Character
SKPC

(CHARA, LENA, AOOR [; OUTO, OUT1]) )

4-64 Machine-Specific Functions

Input Parameters:

CHARA
Address of a byte containing the character to be skipped.
LENA

Address of a word containing the search string length.

ADDR
Address of the string to be searched.
Output Parameters:

OUTO
Value returned in RO is the number of bytes remaining in the string
(including the located or unequal one) if the (unequal) byte is located;
otherwise, RO is zero.
OUT1
Value returned in Rl is the address of the byte located (if byte is located);
otherwise, Rl is the address of one byte beyond the string.
Result:
1

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

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

4.88 SPANC-Span Characters
SPANC

(LENA, ADDR, TBLADDR, MASKA [; OUTO, OUT1, OUT2, OUT3])

Input Parameters:
LENA

Address of a word containing the length of the string to be spanned.

ADDR
Address of the base of the string.

Machine-Specific Functions 4-65

TBLADDR
Address of the translation table.

MAS KA
Address of a byte containing the mask to use in spanning.
Output Parameters:

OUTO
Value returned in RO is the number of bytes remaining in the string
(including the byte that produced a zero AND result); RO is a zero only if
there was a nonzero AND result.
OUT1
Value returned in Rl is the address of the byte that produced a zero AND
result; otherwise, Rl is the address of one byte beyond the string.
OUT2
Value returned in R2 is zero.
OUT3
Value returned in R3 is the address of the table.
Result:

If the SP ANC fails to find a match, the result is zero. Otherwise, the result
is the address of the byte that produced a zero AND with the MASK.

4.89 SUBD-Subtract D-Floating Operands
SUBO

(SRC1A, SRC2A, OSTA)

Parameters:

SRC1A
Address of a double-precision floating-point quadword used as the subtrahend.

SRC2A
Address of a double-precision floating-point quadword used as the minuend.

4-66 Machine-Specific Functions

DSTA
Address of the quadword where the difference is stored.
Result:

NOVALUE

4.90 SUBF-Subtract F-Floating Operands
SUBF

(SRC1A, SRC2A, OSTA)

Parameters:

SRC1A
Address of a single-precision floating-point longword used as the subtrahend.

SRC2A
Address of a single-precision floating-point longword used as the minuend.

DSTA
Address of a longword where the difference is stored.
Result:

NOVALUE

4.91 SUBG-Subtract G-Floating Operands
SUBG

(SRC1A, SRC2A, OSTA)

Parameters:

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

Machine-Specific Functions

4-67

DSTA
Address of a quadword where the difference is stored.
Result:

NOVALUE

4.92 SUBH-Subtract H-Floating Operands
SUBH

(SRC1A, SRC2A, OSTA)

Parameters:

SRC1A
Address of an extended-exponent double-precision floating-point octaword
used as the subtrahend.

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

DSTA
Address of an octaword where the difference is stored.
Result:

NOVALUE

4.93 SUBM-Subtract Multiword Operands
SUBM

(SIZE, SRC1A, SRC2A, OSTA)

Parameters:

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

SRC1A
Address of an extended multiprecision integer used as the subtrahend.

4-68

Machine-Specific Functions

SRC2A
Address of an extended multiprecision integer used as the minuend.

DSTA
Address of the difference.
Result:

NOVALUE

4.94 TESTBITx-Test and Modify Operations
TESTBITSS (FIELD)

Test for bit set, then set bit

TESTBITSC (FIELD)

Test for bit set, then clear bit

TESTBITCS (FIELD)

Test for bit clear, then set bit

TESTBITCC (FIELD)

Test for bit clear, then clear bit

TESTBITSSI (FIELD)

Test for bit set, then set bit (interlocked)

TESTBITCCI (FIELD)

Test for bit clear, then clear bit (interlocked)

Parameters:
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 a field selector that cannot be evaluated to an
address.

Machine-Specific Functions

4-69

Result:
1
Bit tested was in the specified state.

0
Otherwise.

4.95 XFC-Extended Function Call
XFC

(OPCOOE)

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

Result:

NOVALUE

4-70 Machine-Specific Functions

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 File 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, the
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.

Programming Considerations

5-1

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 4 by using library files instead of source files.
Library files and declarations and REQUIRE files and declarations are
similar; however, the differences are:
•

•

Files invoked by REQUIRE declarations are source (text) files, while
files invoked by LIBRARY declarations are special files, previously
created by the compiler through a 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:
BIND 1
BIND ROUTINE 1
BUILTIN 1
COMPILETIME
EXTERNAL
EXTERNAL LITERAL
EXTERNAL ROUTINE
FIELD
KEYWORD MACRO
LIBRARY
LINKAGE
LITERAL
MACRO
REQUIRE
STRUCTURE
SWITCHES
UNDECLARE
SWITCHES declarations contained in files invoked by the REQUIRE
declaration 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.

1 Some restrictions apply to these declarations.

5-2

Programming Considerations

•

(The only switches that are useful in a library compilation are LIST,
LANGUAGE, and ERRS. The remaining switches can be given, but
are effectively ignored because 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 Section 6.3.1.1). Files
invoked by LIBRARY declarations do not have effects that depend
on previous declarations or switch settings, because SWITCHES
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.

In most 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, achieving identical effects in the module being compiled.
However, the differences presented above can lead to problems that are
difficult to identify. Therefore, you should use one consistent form 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.

Programming Considerations

5-3

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

This should almost certainly be the following:
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:
ROUTINE R(A): NOVALUE =
BEGIN
RETURN 6;
END;

In this routine, the apparent return value 5 is discarded, because the
routine has the NOVALUE attribute.
However, notice the following case:
ROUTINE S(B) =
BEGIN
RETURN;
END;

Here 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-4

Programming Considerations

5.2.3

Semicolons and Values of Blocks
It is common to think of the semicolon as a terminator for an expression,

but this is not always true and can lead to errors. For example:
IF .A
THEN
X=.Y;
ELSE

X=-5;

Here the first semicolon terminates the initial IF-THEN and the subsequent
ELSE is in error.
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.)

5.2.4

Complex Expressions Using AND, OR, and NOT
When you are 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, the following construction is
difficult to read and may not reflect the intention:
IF .X EQL 0 AND .Y OR NOT .J THEN ...

The following clearly reflects the intent:
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:

Programming Considerations

5-5

BEGIN
EXTERNAL ROUTINE
R;
LOCAL
L;

L = R;
( .L)(O)
END

This code calls the routine at address R with a parameter of zero.
However, notice the following call:
.L(O)

This expression calls the routine at address L (most likely an address
on the stack) and uses the returned value as the operand of the fetch.
Because there is no code at address L, an illegal instruction exception is
likely at execution.
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 follows:
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:
BEGIN
FIELD LOW9 = [0,0,9,0];
OWN
X: BLOCK[1] FIELD(LOW9);
THEN
END

Here the expression .X[LOW9] EQL-5 is always false because the (unsigned) value fetched from X is necessarily in the range 0 to 511.

5-6

Programming Considerations

5.2.7

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

Macro expansions that produce declarations of any kind, particularly
other macro declarations
Use of compile-time names to control macro expansions using
%ASSIGN
Use of %QUOTE, %UNQUOTE, and %EXPAND

Be careful when using these features; indeed, you may not really need
them. (Refer to Section 5.6 for examples of advanced macro usage.)

5.2.8

Missing Code
Many coding errors tend to result 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 missing from the source,
rather than removed by optimization.
For example, consider the following:
BEGIN
OWN
X: BYTE;
IF .X EQL -5 THEN X = O;
END

In this example, the value of the test expression, .X EQL-5, is always false
(refer to Section 5.2.6). As a result, the compiler produces no code for the
test expression or the alternative (X=O), which can never be executed.
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.

Programming Considerations

5-7

A similar error occurs if the fact is overlooked that TRUE-/FALSE is
based on the value of the low bit of an expression. For example:
IF .X and 2
THEN
Y=O
ELSE

Y=1

This code will always assign the value 1 to Y, because the low bit of .X
AND 2 must always be zero or false.

5.2.9

Using the Buih-ln PC
The VAX Architecture Handbook asserts that the PC cannot be used in
REGISTER or REGISTER indirect addressing modes. The BLISS-32
compiler generates an internal compiler error if the following kinds of
expressions are encountered:
BUILTIN PC;
OWN
X;
X = .PC;
! produces a MOVL PC,X which is unpredictable
X = .. PC;
! produces a MOVL (PC),X which is unpredictable

If it is necessary for you to obtain an approximate value for the PC, the
technique to use is as follows:
BUILTIN PC;
EXTERNAL ZERO:WEAK;
X = .PC + ZERO;

default to zero if no corresponding
GLOBAL BIND ZERO = 0 appears

This will produce the following:
MOVAB ZERO(PC),X

This instruction is defined in the VAX Architecture Handbook.

5-8

Programming Considerations

5.2.10

Indexed Loop Coding Error
A common coding error occurs in the use of unsigned indexed loop
expressions of the following form:
DECRU I FROM HIGH TO 0 DO

This results in an infinite loop because the programmer is inadvertently
attempting to decrement through zero. The rules of unsigned arithmetic
state that zero is the smallest integer; thus, .I is never less than zero and
the loop cannot terminate.
The proper interpretation of these expressions is as follows:
BEGIN
LOCAL I;
I = HIGH;
IF .I GTRU 0 DO ( I = .I - 1) UNTIL .I LSSU O;
END;

Thus, when .I is zero and is decremented to -1, it becomes the largest
unsigned number. The expression .I LSSU 0 is always false because -1
LSSU 0 is always false. Therefore, the unsigned indexed loop expression
must be coded as either one of the following:
DECRU I FROM HIGH_ + 1 TO 1 DO

or
DECRU I FROM HIGH TO 0 DO
BEGIN
IF .I EQL 0 THEN EXITLOOP
END;

The semantics of the DECRA expression are the same, except GTRU and
LSSU would be GTRA and LSSA.

Programming Considerations

5-9

5.3 Linker Error Messages
The TRUNC or TRUNCDAT error message is typically caused by a
module compiled with the following default addressing mode being linked
in an image that is larger than 32K:
ADDRESSING_MODE(WORD_RELATIVE)

The problem can be resolved with one of the following procedures:
•
•

Edit the source module to use ADDRESSING_MODE(LONG_
RELATIVE) and recompile.
Rearrange the placement of the object modules so that EXTERNAL
references or references between program sections are within 32KB of
their target.

5.4 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 Position-Independent Cade 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 PIC data has been generated when necessary.

5.6 Advanced Use af BLISS Macros
This section provides some examples of the advanced use of BLISS
macros. In particular, the examples demonstrate the use of the following:
•
•
•

5-10

Conditional compilations
Iterative macros
Lexical functions (such as %QUOTE and %EXP AND)

Programming Considerations

5.6.1

Advantageous Use of Machine Dependencies
The following examples show how machine-independent constructs can
be modified to take advantage of machine dependencies.
Assume a high-level construct is needed to move a fullword sequence
from a source to a destination; the simplest transportable implementation
of this might be as follows:
MACRO
MOVECORE( SRC, DST, LENTH ) =
BEGIN
BIND
$S=(SRC) : VECTOR,
$D=(DST) : VECTOR;
INCR I FROM 0 TO (LENTH)-1 DO $D[.I] = .$S[.I]
END X;

Notice that the BIND of SRC and DST guards against their producing any
extraneous side-effects. For example, if the assignment-expression in the
INCR loop used a general structure reference of the following form, and
the DST or SRC expressions were routine calls, a call would be executed
every time a pass was made through the loop:
VECTOR[ DST, .I ] = .VECTOR[ SRC, .I ] ;

Thus, the BIND to $D and $5 ensures that this side effect occurs only
once.

5.6.2

Using String Instructions
The macro shown in the previous example is, however, inefficient for use
in the moving of large blocks of memory due to excessive execution time
and instruction size; more efficient coding would take advantage of string
instructions supported by the VAX and DECsystem 10/20 hardware.
As an example, the transportable CH$MOVE function can be used, with
appropriate adjustments, to deal with 8-bit bytes on the VAX and 36-bit
bytes on the 10 /20 as follows:
MACRO
WORD_PTR(A) = CH$PTR( A Y.BLISS36(. 0, 36) ) X.
MOVECORE(SRC,DST,LENTH) = CH$MOVE(
(LENTH)•XUPVAL,
WORD_PTR(SRC),
WORD_PTR(DST) ) X;

Programming Considerations

5-11

This method produces fairly efficient code; but for DECsystem 10 /20
an even more efficient implementation is possible using the BLT (Block
Transfer) instruction as follows:
MACRO
MOVECORE(SRC,DST,LENTH)=
Y.IF Y.BLISS(BLISS36)
Y.THEN
BEGIN
BIND
$D =(DST);
BUILTIN MACHOP;
LITERAL BLT=Y.0'261';
REGISTER
RQQQ,
SQQQ=1;
RQQQ<18,18> = (SRC);
RQQQ<0,18> = ($D);

! BLT opcode

! Must not be ACO
! Source-ptr in LH
! Destination in RH

Y.IF Y.LTCE( LENTH )
! Effective address
Y.THEN
! tells where to stop
SQQQ = .RQQQ<0,18>;
MACHOP( BLT, RQQQ, (LENTH)-1, SQQQ)
Y.ELSE
SQQQ = ($D) + (LENTH);
MACHOP(BLT, RQQQ, -1, SQQQ)
Y.FI
END
Y.ELSE
CH$MOVE((LENTH)•Y.UPVAL, SRC, DST)
Y.FI Y.,

The BLISS-36 version of MOVECORE is now heavily conditionalized to
generate the best possible code when the length of the memory block is
known at compile or link time.
For example, the %LTCE lexical function is used to determine if advantage
can be taken of the PDP-10 effective-address calculation to completely
evaluate the expression:
.SQQQ + (LENTH) - 1

However, if the expression is not a link-time constant, it is necessary to
compute the ending address by a combination of run-time addition and
effective-address computation.
Further, it should be noted that there is some risk involved with this
implementation, in that the BLT always moves at least one word. Thus, if
the LENTH parameter is zero, the BLT method will incorrectly move one
word to the destination.

5-12

Programming Considerations

5.8.3

Dealing with Enumeration Types
One of the more powerful features of languages such as Pascal is the
ability to define a finite set of elements. This is known as an "enumerated
type", because you define the set by exhaustively naming each possible
element in the set.
While BLISS is unaware of such types, it is possible to provide an adequate
simulation.

5.6.3. 1

The SET Data Type

Sets are implemented in BLISS through a system of macros. An element
of the set is given a small integer value between zero and %BPVAL-1.
Thus, sets are limited (in this implementation) to contain no more than
%BPVAL elements in their domain.
You store a subset by setting bits in a fullword. For reasons to be discussed later, the bits in the fullword are numbered in reverse order from
the normal BLISS conventions. Thus for the VAX a set looks as follows:
31

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

IOI 11 21 31 41 51 6171 ........ 1291301311
+--+--+--+--+--+--+--+--+--------+--+--+--+

The digits inside the box refer to element-numbers, while the digits
outside the box refer to the most-significant (31) and least-significant bits
( 0) of a VAX longword.
The following table shows some simple sets and the elements they
contain:
Set(Hexadecimal)

Contents

80000000
80000001
00000002
FFOOOOOO

0,31
30
0,l,2,3,4,5,6,7

Programming Considerations

5-13

5.6.3.2

Creating a Set
The following macro defines an enumeration type.
MACRO
ENUMERATION(NAME)=
!+
! Creates a PASCAL-like ENUMERATION type. The parameter
! NAME will be defined as a macro expanding to the
! comma-list of the %REMAINING parameters.
!-

COMPILTIME
NAME = O;
LITERAL
ENUM_ (NAME,lREMAINING);
UNDECLARE NAME;
MACRO NAME = Y.QUOTE %EXPAND %REMAINING Y.QUOTE Y.

%.
ENUM_(V)[N] = N = V %ASSIGN(V,V+1) Y.;

Note that the ENUMERATION macro is particularly interesting due to the
use of the %QUOTE lexical function. As an example, consider the use of
the ENUMERATION macro to define the type TREES:
ENUMERATION( TREES, OAK, MAPLE, PINE, ELM);

The intended result is that the names OAK, MAPLE, PINE, and ELM
should be defined as follows:
LITERAL
OAK = 0,
MAPLE= 1,
PINE = 2,
ELM = 3;

And the name TREES should be defined by the following macro:
MACRO TREES = OAK, MAPLE, PINE, ELM %;

You must use %QUOTE with %EXPAND to keep it from occurring until
you expand the ENUMERATION macro. At this time, the %REMAINING
will be bound to the list of names: OAK, MAPLE, PINE, ELM.
Because the macro NAME is inside another macro, you are scanning its
body at macro-quote level when you expand the ENUMERATION macro.
Thus, suppose the body of the ENUMERATION macro was defined as
follows:

5-14 Programming Considerations

MACRO NAME = YJlEMAINING %QUOTE Y.;

The result of expanding ENUMERATION would be as follows:
MACRO TREES = XREM!INING %;

Because TREES is defined as not having a macro-parameter list, the value
of the %REMAINING would always be empty. Therefore, you must force
the expansion of %REMAINING when the ENUMERATION macro is
expanded, not when the TREES macro is expanded.
Suppose you have defined the ENUMERATION macro as follows:
MACRO NAME = %EXPAND XREM!INING %QUOTE Y.;

This would cause %REMAINING to be expanded too soon (when the
ENUMERATION macro is declared), and again %REMAINING would be
an empty lexeme sequence.
The macro, which expands to the entire domain of the enumeration type,
can be used as follows:
1.

To iterate over a set, write the following:
INCR SPECIES FROM MIN(TREES) TO MAX(TREES) do ...

Using the CASE control expression, write the following:
CASE .WOOD FROM MIN(TREES) TO MAX(TREES) OF
SET
[OAK]:
[MAPLE]:

[PINE,ELM]:
[OUTRANGE] :
TES;

3. A successor function can be defined as follows:
MACRO SUCCESSOR(T) = ( (T)+1 ) MOD MAX(TREES) Y.;

The MOD is used to cause SUCCESSOR(MAX(TREES)) to be the same as
MIN(TREES).
A more general implementation would pass the SET as a parameter, as
follows:
MACRO SUCCESSOR(T) = ((T)+1) MOD MAXCY.REMAINING) Y.;

Programming Considerations

5-15

This would be invoked as SUCCESSOR( MAPLE, TREES) to return the
value 2 (the literal associated with PINE).
5.6.3.3

Placing Elements in Sets

Given elements of an enumeration type, you can produce a subset containing those elements. The SUBSET macro shows another useful example of
an iterative macro. Its purpose is to OR together the single sets produced
by BITS. Notice how the sequence "O OR BITS( ... )"is used to force the
default separator to be OR. BITS is notable for the inclusion of defensive
code to detect attempts to produce sets that exceed the implementation
limits.
MACRO
BITS[A]=
l!F %CTCE(A)
Y.THEN
Y.IF A GTRU Y.BPVAL-1
Y.THEN
Y.WARN('Value (', Y.NUMBER(A),
•) in BITS Mask exceeds Y.BPVAL-1')
Y.FI
Y.FI
( 1A( CY.BPVAL-1)-(A) ) ) Y..
SUBSET[] = ( 0 OR BITS(Y.REMAINING) ) Y.;

Typical use of the SUBSET macro would be to initialize a set or to test for
intersections, as follows:
OWN FOREST : INITIAL( SUBSET<OAK, MAPLE>);
IF (.FOREST AND SUBSET<PINE,ELM>) EQL 0
THEN
! No trees in common between two sets

5-16 Programming Considerations

5.6.3~4

Membership in a Set

The ONEOF macro efficiently determines if an element is a member of a
given subset by doing a left,..shift and examining the sign bit of the result
value. For this reason, sets are stored in reverse,..numbered bit fields.
This example also deals with machine dependencies, as the BLISS-36
arithmetic shift operator (") must choose either an ASH or a LSH
instruction. An ASH instruction leaves the sign bit unchanged. This is
the behavior wanted when right-shifting any value, but when left-shifting,
the BLISS semantics demand that a LSH be generated. If the shift count
is unknown at compile time, BLISS-36 must generate a run-time test and
conditionally execute either the ASH or the LSH. Because the shifts wHl
always be to the left, the generated code is optimized by forcing a LSH to
be emitted as shown below.
MACRO
ONEOF(ELEMENT,SUBSET)=
XIF XBLISS(B~ISS36)
XTHEN
BEGIN
BUILTIN LSH;
LSH(SUBSET, ELEMENT) LSS 0
END

XELSE
(((SUBSET) • (ELEMENT)) LSS 0)
UI X;

For example, on the VAX, consider the following:
LOCAL TREE : INITIAL( ELM);

! An element

IF ONEOF( .TREE, SUBSET<~t-!. P;t»E> )
THEN

This code fragment would expap.d t9 the following:
IF ( c1 • (31-3)) OR o ·-(31-2)) ) • (.TREE) LSS 0
THEN

This is eqµivalent to the following:
IF (1.X I 30000000 I

•

( •

TREE) )

LSS 0

THEN

Programming Considerations

5-17

Assuming that TREE still contains its initial value of 3 (for ELM), this is
equivalent to the following:
IF (1.X'80000000') LSS 0
THEN

This evaluates to TRUE and indicates that ELM is a member of the subset
{ELM, PINE}.

5-18

Programming Considerations

Chapter 6

Transportability Guidelines
This chapter provides guidelines for writing transportable programs
and demonstrates why the writing of transportable code is easier if it
is considered at the beginning of a project. Also described are ways in
which a program can become untransportable, and techniques whereby
such occurrences can be avoided.
Following an introduction to the concepts of transportability, the guidelines are presented in three sections: Section 6.2 describes high-level
approaches to writing transportable software in BLISS. Section 6.3 describes various BLISS features that can be used in solving transportability
problems. Section 6.4 analyzes various transportability problems and
provides suggested solutions.
The dialects referenced in this chapter are the languages defined by the
following BLISS compilers:
BLISS-16 Version 4.3
BLISS-32 Version 4.3
BLISS-36 Version 4.0
BLISS-36 and BLISS-16 are generic names for languages that have BLISS
compilers that generate code for DECsystem-10 /20s and PDP-lls, respectively.

Transportability Guidelines

6-1

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. 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 as follows:
•
•

•

No change to program text is needed-the program is completely
transportable.
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, you may find it 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; however, an attempt has been made to identify less obvious
problem areas and provide solutions.

6-2

Transportability Guidelines

&.2 General Strategies
Two global strategies are important to the writing of transportable BLISS
programs: isolation and simplicity.

8.2.1

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 such cases, isolating the constructs will facilitate any future movement of the program to
a different machine. Generally, only a small percentage of the program
or system will be sensitive to the machine on which it is running. By
isolating those sections, you can mainly confine the effort involved in
transporting the program to these easily identifiable, machine-specific
sections. Specifically, follow these rules:
•
•

•
•

If machine-specific data are to be allocated, place the 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 a macro and then place the routine or macro in a separate
module or a REQUIRE file.
If a machine-specific function or instruction is to be used, 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 the code is nontransportable.

These 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 operatingsystem dependent from the rest of the system, the task of transporting
the entire system is simplified. It becomes a matter of rewriting 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 rewriting. The BLISS language facilitates both the design and
programming of programs and systems in a modular fashion. You should
use this feature to advantage when writing a transportable system.

Transportability Guidelines

6-3

8.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. You are 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 writing of
transportable programs is a simpler task because the number of options
available has been reduced. Simplicity in the writing 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 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 Section 6.4 as well.

8.3.1

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

6-4 Transportability Guidelines

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:
Literal
Name

Description

%BPUNIT

Bits per addressable unit

%BPADDR

Bits per address value

%BPVAL

Bits per BLISS value

%UPVAL

Units per BLISS value

DEC
10/20

36
18
36
1

VAX

PDP-11

8
32
32

8
16
16
2

The names beginning with a percent sign ( % ) are literal names that can
be used without declaration. These literal names are used throughout this
chapter.
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 address 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.
You can derive other useful values from these built-in literals. For example:
LITERAL

HALF_VALUE = Y.BPVAL / 2;

This defines the number of bits in a half word (half a longword on the
VAX).

Transportability Guidelines 6-5

6.3.1.2

User-Defined Literals

Strictly speaking, a literal is not a self-defining term. You arrive at the
value and restrictions associated with a literal 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 ate certain architectural dependencies inherent in the use of literals. Because the size of a BLISS value
determines the value and the representation of a literal, there are som.e
transportability considerations.
BLISS value (machine word) sizes are different on each of the three
machines. On VAX, the size is 32 bits; on the DECsystem 10 /20 systems,
it is 36; and on the PDP-11, the 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 numbet ( i) are as follows:
VAX

-(2••31)

:::; i :::; (2••31)-1

DECsystem-10/20

-(2••35)

:::; i:::; (2••35)-1

PDP-11

-(2••15)

:::; i :::; (2••15)-1

All

-(2••(%BPVAL-1))

:::; i :::; (2**(%BPVAL-1))-1

A numeric literal (%C'single-character') has been implemented. Its stored
value is the ASCII code corresponding to the character in quotes. It is
right-justified in a BLISS value (word or longword). A more thorough
discussion of its usage can be found in Section 6.4.3. There are two ways
of using string literals: as integer values and as character strings. When
strirtg 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:
DECsystemVAX

10/20

PDP-11

Maximum number of
characters

Character placement

right to left

left to right

right to left

This type of string-literal usage and also its use as a character string are
discussed in Section 6.4.3.

6-6 Transportability Guidelines

8.3.2 Macros and Conditional Compilation
BLISS macros can be an essential tool in the development of transportable programs. Because they evaluate (expand) during compilation, it
is possible to use macros to tailor a program to a specific machine.
A good example can be found in the Section 6.4.5.1, where 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. Depending
on which compiler is being run, you can use these macros to select declarations or expressions for compilation. There are three sets of definitions,
each containing three macro definitions.
The definitions for the BLISS-32 set are as follows:
MACRO
Y.BLISS16 [] = Y. ,
Y.BLISS36 [] = Y. ,
Y.BLISS32[] = Y.REMAINING Y. ;

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 0 otherwise. In the
following example, INSQUE is an executable function in BLISS-32, but is
a routine for BLISS-36:
Y.IF Y.BLISS(BLISS32)
Y.THEN
BUILTIN
INSQUE;
Y.ELSE
Y.IF Y.BLISS(BLISS36)
Y.THEN
FORWARD ROUTINE
INSQUE;
Y.FI
Y.FI

Transportability Guidelines 6-7

8.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 of a module
To provide diagnostic checking of the use of certain language features

Using this switch, you can therefore indicate the target architectures
(environments) for which a program is intended.
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 the intended target
environments
Features that most often prove to be troublesome in transporting a
program from any one environment to another

The syntax is as follows:
LANGUAGE (language-name, ... )

where language-name is any combination of BLISS36, BLISS16, or
BLISS32.
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 assumes that the program is intended to run under
each corresponding architecture.
If no language name is specified, no transportability checking will be per-

formed. A specification of COMMON is the equivalent of the specification
of all three.
Each compiler will give a warning diagnostic if its own language-name is
not included in the list of language-names.

6-8

Transportability Guidelines

Within the scope of a language switch, each compiler gives 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.
The precise set of language constructs that are subject to transportability
checking is specified in the BLISS Language Reference Manual.
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 BLISS-16
and BLISS-32 target architectures.)
The compilation of this section of code by a
BLISS-36 compiler will result in a disgnostic
warning.

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

Transportability Guidelines

6-9

1.3.4 Reserved Names
The following is a list of BLISS reserved names that cannot be declared
by the user. Although 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 IOP AGE has no defined meaning in any
BLISS dialect but is 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 the BLISS Language Reference Manual for a more
complete description.
•ADDRESSING-MODE

GTRU

PUT

•ALIGN

PRESET

ALWAYS

INCR

PSECT

AND

INCRA

•RECORD

BEGIN

INCRU

REF

BIND

INITIAL

•BIT

INRANGE

REP

BUILTIN

•IOPAGE

REQUIRE

KEYWORDMACRO

RETURN

•BYTE

LABEL

ROUTINE

CASE

LEAVE

SELECT

CODECOMMENT

LEQ

SELECTA

COMPILETIME

LEQA

SELECTONE

DECR

LEQU

SELECTONEA

DECRA

LIBRARY

SELECTONEU

DECRU

LINKAGE

SELECTU

LITERAL

SET

ELSE

LOCAL

•SHOW

ELUDOM

•LONG

•SIGNED

ENABLE

LSS

STACKLOCAL

6-1 0 Transportability Guidelines

END

LSSA

STRUCTURE

EQL

LSSU

SWITCHES

EQLA

MACRO

TES

EQLU

MAP

THEN

EQV

MOD

EXITLOOP

MODULE

UNDECLARE

EXTERNAL

NEQ

•UNSIGNED

FIELD

NEQA

UNTIL

FORWARD

NEQU

UPLIT

FROM

NOT

VOLATILE

GEQ

NO VALUE

•WEAK

GEQA

WHILE

GEQU

WITH

GLOBAL

OTHERWISE

•WORD

GTR

OUTRANGE

XOR

GTRA

OWN

6.3.5 REQUIRE and Library Files
REQUIRE files are a way of gathering machine-specific declarations and
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 write 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 is very machine specific, then the
solution may be to write two or three functionally equivalent routines, one
for each machine type, and segregate them each in their own REQUIRE
file.
Each BLISS compiler has a 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.

Transportability Guidelines 6-11

The search rules for each compiler are as follows:
Compiler

1ST

2ND

3RD

4TH

BLISS-36

.R36

.REQ

.B36

.BLI

BLISS-16

.R16

.REQ

.B16

.BLI

BLISS-32

.R32

.REQ

.B32

.BLI

Hence, the following REQUIRE declaration searches for IOP ACK.R36,
IOPACK.Rl6, or IOPACK.R32, depending on which compiler is run.
REQUIRE
'IOPACK';

! I/O Package

If these searches fail, it then looks for IOP ACK.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 in
the BLISS Language Reference Manual. The output of a library run is called
a library file; library files are processed by a compiler when it encounters a
LIBRARY declaration. For example:
LIBRARY
'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 'V_AX. To precompile it requires that it be run
on the BLISS-32 compiler with the /LIBRARY switch and the BLISS36 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-12 Transportability Guidelines

8.3.6

Routines
The key to transportability is the ability to identify an abstraction that can
exist in several environments. You do this by naming the abstraction and
describing its external characteristics in a way that permits implementation
in any of the environments. The abstraction can 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, such as
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, you
will 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, for
instance, when writing cross-compilers. Even if the ability to perform
cross-arithmetic is not desired, isolating floating-point operations in
routines may be a good idea because 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 (because 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 routine abstractions produces serious
performance degradations. For this reason, you should not attempt to use
a routine as a transportability mechanism when a small amount of effort is
sufficient for the writing of a single transportable module.

Transportability Guidelines 6-13

6.4 Techniques for Writing Transportable Programs
This section on techniques shows you how to write transportable programs. The section is organized in dictionary form by BLISS construct or
concept. Each subsection contains the following:
•
•
•
•

A discussion of the construct or concept
Transportability problems that its use may engender
Specific guidelines and restrictions on the use of the construct or
concept
Examples-both transportable and nontransportable

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

6.4.1 Allocation of Data
This section deals with the allocation of data in a BLISS program. In this
section, character sequence (string) data or the formation of address data
is not discussed. These types of data are discussed in Sections 6.4.2 and
6.4.3. This section describes the 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 Sections 6.4.4 and 6.4.5.
The first discussion concerns transportability problems encountered due to
differing machine architectures. This is followed by a presentation on the
BLISS allocation-unit attribute, and then a discussion of other BLISS data
attributes you must consider when writing transportable programs.
6.4.1.1

Problem Origin

The allocation of data (through 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
The flexibility of the BLISS language

6-14 Transportability Guidelines

In considering writing a BLISS program for transporting to another machine, you will be confronted with the problem of allocating data on at
least two different architectures.
Although differing word sizes have already been discussed, there are
further differences to be considered. On VAX architecture, for example,
data may be typically fetched in longwords (32 bits), in words (16 bits),
and in bytes (8 bits); while on the PDP-11, both words and bytes may be
fetched; and on the DECsystem-10/20 only 18-bit halfwords and 36-bit
words can be fetched without a byte pointer.
What decisions must you make in the transportable allocation of data?
Need you be concerned with how many bits are going to be allocated?
These questions can be further 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
helps you write efficient machine-specific software. You have much more
control over exactly how many bits of data you will use. This feature of
BLISS can, however, complicate the decisions you must make regarding
transportability. For example, do you allocate scalars by bytes, words, or
longwords?
6.4. 1.2

Transportable Declarations

Consider the following simple example of a data declaration in BLISS-32:
LOCAL
PAGE_COUNTER: BYTE;

! Page counter

One byte (eight bits) is allocated for a variable named PAGE_COUNTER.
No matter what the intention was in requesting only one byte of storage,
this declaration is nontransportable. The concept of BYTE (in this context)
does not exist on the DECsystem-10 /20. In fact, in BLISS-36 the use of
the word BYTE results in an error message. Moreover, because the 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.
Suppose this declaration had been originally written as follows:
LOCAL
PAGE_COUNTER;

! Page counter

Transportability Guidelines

6-15

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.
By not specifying any allocation unit in the LOCAL declaration, the BLISS
compiler is allowed to allocate storage by default. In all BLISS dialects the
default size for an allocation unit consists of %BPVAL bits. Thus, the first
transportable guideline is as follows:
•

Do not use the allocation-unit attribute in a scalar data declaration.

In the case of scalar data, using the default allocation unit sometimes
results in the allocation of more storage than is strictly necessary. This
gain in program data size (which is small in most instances) must be
weighed against the decrease in fetching time for particular scalar values,
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 and most efficiently
accessed unit of data for a particular machine. In other words, saving bits
does not necessarily mean a more efficient program has been written.
There are other attributes besides the allocation unit that, if used, may
present transportability problems. In particular, when allocating data,
adhere to the following guidelines:
•

Do not use the following attributes:
SIGNED
UNSIGNED
ALIGN
WEAK

In other words, before writing a declaration, consider whether you need to
specify any data attributes other than structure attributes.
The extension attribute (SIGNED and UNSIGNED) specifies whether the
sign bit is to be extended in a fetch of a scalar (or equivalently, whether or
not the leftmost 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.
The alignment attribute (ALIGN) specifies the kind of address boundary
at which a data segment is to start. It is not supported in BLISS-36 or
BLISS-16; hence, it is nontransportable. Suitable default alignments are
available dependent on the size of the scalar.

6-16 Transportability Guidelines

The weak attribute (WEAK) is a VMS-specific attribute and is not supported by BLISS-36 or BLISS-16; therefore, it cannot be used in a
transportable program.
These guidelines are relatively simple and can relieve your concerns as
to how the compiler will actually allocate the program's data. 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 using
one or more of the above attributes. In fact, it may be desirable to take
advantage of a specific machine feature. In such cases, adhere to the
following guideline:
•

Conditionalize or heavily comment the use of declarations that are
nontransportable.

This is an "escape-hatch" guideline that must be used sparingly and only
where justified; frequent use will merely produce more code, which will
have to be rewritten when the progam is transported to another machine.

8.4.2

Data Addresses
This section discusses address values and address value calculations. The
section first presents problems resulting from using an address or an
address calculation as a value, and then offers transportable solutions to
some of these problems. This is followed by a discussion of the need
for address forms of BLISS relational operators and control expressions
and how and when to use them. Finally, some important differences in
interpreting BLISS-10 and BLISS-36 address values 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. 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

Transportability Guidelines

6-1 7

values have been parameterized and are now predeclared literals. A table
of their values can be found in Section 6.3.1.
To see how these size differences can have an effect on writing transportable programs, consider a common type of address expression that
computes an address value from a base (a pointer or an address) and an
offset. For example:
. . . base + index ...

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

ELEMENT_2 = .(INPUT_RECORD + 1);

The intent of the code is 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. However, as will be shown, the effect of this
code differs on each machine.
Adding 1 to an address (in this case, INPUT_RECORD) computes the
address of the next addressable unit on the machine. For BLISS-32 and
BLISS-16, the next addressable unit is the address of the next byte (8 bits),
while for BLISS-36 the next addressable unit is the address of the next
word (36 bits). Because the addressable units and the resultant values
differ, the code segment does not reflect a transportable expression.
Therefore, adhere to the following 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 exists as a predeclared literal. Its
definition is %BPVAL/%BPUNIT, and it is called %UPVAL.

6-18 Transportability Guidelines

Using this literal in the example yields the following:
ELEMENT_2 =
.(INPUT_RECORD + 1 * Y.UPVAL);

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 written as follows:
OWN
INPUT_RECORD:
FLEX_VECTOR[RECORD_SIZE,Y.BPVAL],
ELEMENT_2;

ELEMENT_2 = .INPUT_RECORD[1];

The transportable structure FLEX_VECTOR and a more thorough discussion of structures can be found in Section 6.4.5.
6.4.2.2

Relational Operators and Control Expressions

The previous example illustrated using 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.
Using 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.
For example, consider this relational test of address values:
... ADDRESS_! LSS ADDRESS_2 ...

This test requires two different interpretations. This expression would
evaluate correctly on DECsystem-10 /20 systems. But on VAX and PDP-11
machines, the test would have to have been written as follows:
... ADDRESS_! LSSU ADDRESS_2 ...

Transportability Guidelines 6-19

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, address relational operators are equivalent to
unsigned relational operators. In BLISS-36, address relational operators
are equivalent to signed relational operators. However, for all practical
purposes, you need not be concerned with this, because "equivalencing"
permits address comparisons to be performed correctly across architectures. In addition, there are address forms of the SELECT (SELECTA),
SELECTONE (SELECTONEA), INCR (INCRA), and DECR (DECRA)
control expressions. The following guidelines establish a usage for these
operators and control expressions:
•
•

If address values are to be compared, use the address form of the
relational operators.
If an address is used as an index in a SELECT, SELECTONE, INCR, or
DECR expression, use the address form of these control expressions.

Violating either of these guidelines can have unpredictable results.
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, because it allows BLISS to assign uniform
semantics to an address.
The fetch and assignment operators are redefined to use only the address
part of a value. For example:
y = .X;
Y = F(. Y) + 2;

These expressions are the same in both BLISS-10 and BLISS-36, but the
following expression assigns a different value to Yin BLISS-36 and in
BLISS-10.
y = X;

6-20 Transportability Guidelines

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. For example:
Y<0,18> = .X<3,7>;

The meaning of this expression is unchanged, but the following expression
is invalid:
Y = X<3,7>;

Moreover, it is strongly recommended that field selectors never appear
outside of a structure declaration, because position and size are apt to be
highly machine dependent. A more thorough discussion can be found in
Section 6.4.5.

8.4.3

Data Character Sequences
This section discusses 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 begins
by looking at quoted strings in two different contexts. Transportability
problems associated with quoted strings and guidelines for their use are
also described.
Quoted strings are used in two different contexts:
•
•

6.4.3. 1

As values (integers)
As character strings

Quoted Strings Used as Numeric Values

Using quoted strings as values (in assignments and comparisons) illustrates
the problem of differing representations on differing architectures. For
example, consider the following code sequence:
OWN
CHAR_1;
CHAR_1 = I ONE I ;

To hold a literal

Transportability Guidelines 6-21

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_l would
have the following representation:
CHAR_1:

I 00 E N O I (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 DECsystem-10 /20 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:

I 0 N E 00 00 0 I (36)

Even if the DECsystem-10/20 string literal had been right justified in the
word, it still would not equal the VAX representation numerically. So, in
fact, the following would not be transportable:
WRITE_INTEGER( 1 ABC 1 ) ;

This is because 'ABC' is invalid syntax in BLISS-16, has the value 33543847936 in BLISS-36, and the value 4276803 in BLISS-32.
Based on these problems with representation, the first guideline is as
follows:
•

Do not use string literals as numeric values.

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 the following is true:
Y.C'B' = Y.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-22 Transportability Guidelines

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 complete and powerful set of operations
on characters. The next guideline is as follows:
•

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

A more detailed description of these functions can be found in the BLISS

Language Reference Manual.

8.4.4 PLITs and Initialization
This section is primarily concerned with the uses of the PUT (Pointer
to Literal) and the UPLIT (Uncounted Pointer to Literal). First, there
is general discussion of PLITs and the contexts in which they often
appear. A presentation of how scalar PUT 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 is 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 PUT. Hence, PLITs are a means
for defining references to constants that are longer than one word. PLITs
are often used to initialize data segments (such as tables) and are used to
define the arguments for routine calls.
PLITs themselves are transportable; however, their constituent elements
and their machine representation are not always transportable.

Transportability Guidelines 6-23

A PUT consists of one or more values (PUT items). PUT items can be
strings, numeric constants, address constants, or any combination of these
last three, providing that the value of each is known before execution
time.
6.4.4.2

Scalar PLIT Items

The first transportability problem that might be encountered with the use
of PUTs is in specifying scalar PUT 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 BUSS-32,
machine-specific sizes (such as BYTE and LONG) can be specified. Thus,
the following example is nontransportable and, in fact, will not compile
on BUSS-36 or BUSS-16:
BIND
Q1 = PLIT BYTE(1, 2, 3, LONG (-4));

This last example provides the first PUT guideline:
•

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

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 Section 6.4.1. Further guidelines are presented in Section 6.4.4.5.
6.4.4.3

String Literal PLIT Items

The next guideline is based on the representation of PUTs in memory.
Specifically the problem is encountered when scalar and string PUT items
appear in the same PUT.
The difficulty arises primarily from the representation of characters on the
different machines. A more thorough discussion of character representation can be found in Section 6.4.3.
Use caution when you use strings as items in PUTs. For example, it may
be necessary to specify a PUT that consists of two elements: a 5-character
string and an address of a routine. Suppose it is specified as follows:
BIND

CONABC = PLIT('ABCDE', ABC_ROUT);

6-24 Transportability Guidelines

Then the VAX representation is as follows:
CONABC:

I DCBAI
I
EI
I address I

(32)
(32)
(32)

On the PDP-11, it is as follows:
CONABC:

I BAI

(16)

I DCI

(16)

E I

I address

I (16)

The DECsystem-10/20 representation is as follows:
CONABC:

I AB CDE I

(36)

I address

(36)

The three PLITs are not equivalent. Three longwords· are required for the
BLISS-32 representation, four words are needed for BLISS-16, and two
words are needed for the BLISS-36 representation. 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
following expression in the BLISS-36 version, but not in the BLISS-32 or
BLISS-16 versions:
••. CONABC + 1 ..•

For the BLISS-32 version, the access expression is as follows:
••• CONABC + 8 .••

For BLISS-16, it would have to be as follows:
.•• 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 Section 6.4.2.
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.

Transportability Guidelines

6-25

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 PUT, you would write the following:
. . . CONABC + 1•1.UPVAL ...

But this will not work for the VAX 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 using a string literal but in its position within the PUT.
Because the number of characters that will fit in a BLISS value differs on
all three machines, the placement of a string in a PUT will very often
result in different displacements for the remaining PUT items.
There is a relatively simple solution to this problem:
•

In a PUT there can only be a maximum of one string literal, and that
literal must be the last item in a PUT.

Following this guideline, the example should have been written as follows:
BIND
CONABC = PLIT(ABC_ROUT, 'ABCDE');

Thus, the following expression would have resulted in the address of the
second element in the PUT (in this case the string) .
. . . CONABC + 1•1.UPVAL ...

6.4.4.4

Initialization Example

As mentioned in the beginning of this section, PLITs are often used to
initialize data segments such as tables. You can initialize a data segment
allocated by an OWN or GLOBAL declaration by using the INITIAL
attribute. The INITIAL attribute specifies the initial values and consists of
a list of PUT items.
The following example uses a table of employee data to show how to
initialize data in a transportable way. Information on each employee
consists of three elements: an employee number, a cost center number
and the employee's name. (The employee's name is a fixed length,
5-character field.)

6-26 Transportability Guidelines

For example, a line of the table contains the following information:
345

201

SMITH

Converting this line into a list of PUT items that conform to this section's
guidelines results in the following:
(345, 201, 'SMITH')

Notice that no allocation units were specified and that the character string
was specified last. This line is now used to initialize a small table of only
one line. The table has the built-in BLOCKVECTOR structure attribute.
The table declaration is as follows:
OWN
TABLE:
BLOCKVECTOR[1,3]
INITIAL(
345,
201,
'SMITH'
);

This definition works well in BLISS-36. That is, three words are allocated
for TABLE. The first word is initialized with the employee number; the
second word with the cost center; and the third with the name. However,
the declaration is incorrect for BLISS-32 or BLISS-16 because not enough
storage is allocated for all of the initial values. BLISS-32 requires four
longwords and BLISS-16, five words.
To solve this problem, you determine the number of BLISS values that
are needed for the character string on each machine. You then use the
CH$ALLOCATION function from the character handling package to
return this value. The CH$ALLOCATION function 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. You can use this value as an
allocation actual in the table definition, as follows:
OWN
TABLE:
INITIAL(
345,
201,
'SMITH'

BLOCKVECTOR[1,2 + CH$ALLOCATION(5)]

) ;

The declaration is now transportable. By using the CH$ALLOCATION
function you can ensure that enough words will be allocated on each
machine. No rewriting is necessary.

Transportability Guidelines

6-27

You are free to add other lines to the table and not be concerned with the
representation or allocation of the data. Here is a larger example of the
same kind of table.

!+
!
!--

Table Parameters

LITERAL
NO_EMPLOYEES = 2,
EMP_NAME_SIZE = 26,
EMP_REC_SIZE = 2 +
CH$ALLOCATION(EMP_NAME_SIZE);
!+
!
!--

Employee Name Padding Macro

MACRO
NAME_PAD(NAME)
%EXACTSTRING (EMP_NAME_SIZE, 0, NAME)l;
!+

Employee Information Table
Size: NO_EMPLOYEES * EMP_REC_SIZE

!
!--

OWN
EMP_TABLE:
BLOCKVECTOR[NO_EMPLOYEES, EMP_REC_SIZE]
INITIAL(
346,
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.

6-28 Transportability Guidelines

The macro will, based on the length of the employee name argument
(NAME), generate zero-filled words to pad out the name field. Thus,
you 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 employee
name field was fixed in length (EMP_NAME_SIZE). However, if you
want the table to hold variable length names (that is, you want to allocate
only enough storage to hold the table data, not the maximum amount),
the table structure developed above will not work because it is predicated
upon the constant size of the name field. If you were to use variable
length character strings, either too much or not enough storage would be
allocated. There would be no consistent way of accessing the employee
name because you would not know where each name would start. You
could, if you knew the length of every employee name, determine in
advance the number of words needed, but this is not a 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) that constructs 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

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 )), lCHARCOUNT (NAME) %;
!+

Employee Information Table
!
!--

Size: NO_EMPLOYEES * EMP_REC_SIZE

Transportability Guidelines 6-29

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 initializing of packed data. Packed data means 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 PUT item will be represented by
the following expression:
v1Ap1 OR v2Ap2 OR ... OR vnApn

where
for all i

max(pl,p2, ... ,pn) < sl + s2 + ... + sn ~

-2 **Bi ~ 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.
Note that the packing of data in a transportable manner is dependent on
the value of %BPVAL.
The following is an illustration of the initialization of packed data obtained
by modifying the employee table example 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
the following:

6-30 Transportability Guidelines

FIELD EMP =
SET
EMP_ID = [0,0,Y.BPVAL,0],
EMP_COST_CEN = [1,0,Y.BPVAL,0],
EMP_NAME_PTR = [2,0,Y.BPVAL,O];
TES;

You can use these field names in developing an initialization macro, by
using parametric values. This is another example of how you can use
parameterization as a key technique in writing 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, you 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, because you know
that DECsystem- to /20 systems have instructions that operate efficiently
on halfwords.
If the interest is only in transporting BLISS-36 and BLISS-32, the field
declaration would look like the following:
FIELD EMP =
SET
EMP_ID = [0,0,YJ3PVAL/2,0],
EMP_COST_CEN = [O,Y.BPVAL/2,Y.BPVAL/2,0],
EMP_NAME_PTR = [1,0,Y.BPVAL,O];
TES;

Based on these declarations, you can design a macro that will take as
arguments the initial values and then do the proper packing:
MACRO
EMP_INITIAL(ID,CC,NAME)[]
rn·Y.FIELDEXPAND(EMP_ID,2) OR
cc·Y.FIELDEXPAND(EMP_COST_CEN,2) •
NAME_PTR (NAME.Y.FIELDEXPAND(EMP_NAME_PTR, 2)) Y.;

The lexical function %FIELDEXP AND simply extracts the position parameter of the field name. The initialization macro, EMP...JNITIAL, 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.

Transportability Guidelines 6-31

Employee Field Reference macros
FIELD EMP·=
SET
EMP_ID = [0,0,Y.BPVAL/2,0],
EMP_COST_CEN
[0,1.BPVAL/2,1.BPVAL/2,0],
EMP_NAME_PTR = [1,0,Y.BPVAL,0];
TES;
MACRO
!+
! Macro to create the shift value from the
! position parameter of a field reference macro
!--

SHIFT(X) = 1.FIELDEXPAND(X,2) 1..
!+
! Employee table initializing macro
! Three values are required
!--

EMP_INITIAL(ID,CC,NAME)[]
ID-SHIFT(EMP_ID) OR
cc-sHIFT(EMP_COST_CEN).

First value

NAME-SHIFT(EMP_NAME_PTR) 1.; ! Second value
!+
!

Employee table definition and initialization

OWN
EMP_TABLE:
BLOCKVECTOR[NO_EMPLOYEES, EMP_LINE_SIZE]
INITIAL(EMP_INITIAL(
346,
I

201,
SMITH PETER I •
207,
346,

'JONES PENNY'
)) ;

Illustrated in the previous example is the parameterization of certain
values such as field sizes. In transporting this program, you can derive
benefits from localizing 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. In that case, they would also need to be
changed.

6-32 Transportability Guidelines

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 in the BLISS Language Reference Manual. Here,
we are concerned only with initializing this type of structure.)
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, you do not have to modify the
design of the BLOCK in any way. Typically, however, you would design
the structure for each target machine. One method of doing this is by
placing its definition in a REQUIRE file. It is preferable, however, to again
use the parameterization technique, making use of the field reference
macros as in the previous example.
The next example describes a method by which the DCB can be initialized.
Using BLOCKVECTOR the structure is extended. Note that you can also
transport the structure 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 = [0,0,8,0),
DCB_B = [0,8,3,0),
DCB_C = [0,11,5,0),
DCB_D = [O,Y.BPVAL/2,Y.BPVAL/2,0),
DCB_E = [1,0,Y.BPVAL,O];
TES;
MACRO
!+
! Macro to create the shift value from the
! position parameter of a field reference macro
!--

Transportability Guidelines

6-33

SHIFT(X) = Y.FIELDEXPAND(X, 2) Y..
!+
! DCB initializing macro.
! Five values are required.
!--

DCB_INITIALIZE(A,B,C,D,E)[]
A.SHIFT(DCB_A) OR
B.SHIFT(DCB_B) OR
c·sHIFT(DCB_C) OR
n·sHIFT(DCB_D)
E.SHIFT(DCB_E) Y.;

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

first word
second word

Structures and Field Selectors
Two BLISS constructs are discussed in this section: structures and field
selectors. While using one does not necessarily imply using the other,
for transportability reasons, field selector usage is confined to structure
declarations. Hence, these two constructs are discussed together.
In the following general discussion of structures, it will be shown that a
certain machine-specific feature of structures can be used in a transportable
manner. The development of a transportable structure called FLEX_
VECTOR is presented; field selectors are discussed next, followed by a
description of a more general structure called GEN_VECTOR.

6-34 Transportability Guidelines

6.4.5. 1

Structures

Structure declarations are sensitive to transportability in that you 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 l, 2, 4, l, and 0, 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 that 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.
As mentioned repeatedly in these guidelines, the prime transportability problem is differing machine architectures. The key to dealing
with these differences is the parameterization, by the size of the machine word (%BPVAL), of 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 parametization is illustrated by 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,
you must choose the smallest natural unit whose size is greater than or
equal to nine bits. Because there are no 9-bit conveniently addressable
units on any of the machines, you have a choice of 8-, 16-, 32-, or 36-bit
units.
Nine bits will fit in the only addressable unit on the DECsystem-10 /20
systems: the word. On the PDP-11 you will need two bytes or a 16-bit
word and on the VAX you will again need two bytes.

Transportability Guidelines

6-35

For a structure to do the allocation and also be transportable to the three
systems requires some knowledge of machine architecture. This is where
parameterization finds a key usage.
The predeclared literals have all the information you need. In fact, only
one set of values is needed: bits per addressable unit (%BPUNIT).
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 as follows:
STRUCTURE
FLEX_VECTOR[ I; N, UNIT= Y.BPUNIT, EXT= 1 ] =

Note that if you set UNIT equal to %BPUNIT, the default (if UNIT is not
specified) is %BPUNIT.
The next step is to develop the formula for the structure-size expression.
The expression makes use of the allocation formals UNIT and N and the
value of %BPUNIT.
If UNIT were allowed to assume only values of integer multiples of

%BPUNIT (that is, l_•%BPUNIT, 2_•%BPUNIT, and so on), only a
structure-size expression of the following form would be needed:
[ N * (UNIT) I Y.BPUNIT ]

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 + Y.BPUNIT - 1)) I Y.BPUNIT ]

The structure-size expression now computes enough %BPUNITs to hold
the entire vector. You should try some values of UNIT, in order to see
how the %BPUNIT expression evaluates.
The following NO_QF_UNITS subexpression is important to this particular structure in relation to transportability and flexibility:
(UNIT + Y.BPUNIT - 1) I Y.BPUNIT

6-36 Transportability Guidelines

The key to transporting the structure is in its knowledge of the value
of a certain machine architectural parameter: bits per addressable unit.
Because this particular expression makes use of this knowledge, it can
adapt to any machine. The subexpression is used twice more in the
structure-body expression.
The structure body is an address expression, which consists of the name
of the structure (the base address) plus an offset based on the index I. In
addition, a field selector is needed to access the proper number of bits at
the calculated address.
The offset is simply the expression: NO_OF_UNITS multiplied by index
I (remember that indices start at zero). 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 looks like the following:
(FLEX_VECTOR +
I * ((UNIT + Y.BPUNIT - 1) I Y.BPUNIT))
<0,((UNIT + Y.BPUNIT - 1)/Y.BPUNIT)*Y.BPUNIT,EXT>;

The value of the position parameter in the field selector is a constant 0
since it always starts at an addressable boundary.
The following table shows the structure on the three machines for different
values of UNIT:
Machine

Structure

VAX
UNIT= 0

No storage FLEX_VECTOR <0,0,1>

UNIT= 1 to 8

[N * 1] Bytes (FLEX_VECTOR+ I) <0,8,1>

UNIT= 9 to 16

[N * 2] Bytes (FLEX_VECTOR+ I* 2) <0,16,l>

UNIT= 17 to 32

[N * 4] Bytes (FLEX_VECTOR+ I* 4) <0,32,l>

PDP-11
UNIT= 0 to 16

Same as VAX

DECsystem-10/20
UNIT= 0

No storage (FLEX_VECTOR) <O,O,l>

UNIT= 1 to 36

[ N] Words (FLEX_VECTOR+ I) <0,36,1>

The table illustrates that if the default value for UNIT was set to %BPVAL
this structure would be equivalent to a VECTOR of longwords on the VAX
and a VECTOR of words on both DECsystem-10/20 and PDP-11 systems.
Transportability Guidelines

6-37

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, the
only change needed would be the size parameter of the field selector. This
expression then becomes the following:
... 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 and DECsystem-10/20
machines and a series of masks and shifts for the PDP-11.
6.4.5.3

Field Selectors

In the last structure declaration, it was necessary to make use of a field
selector. Using field selectors in a more general context are discussed in
this section.
Using field selectors can be nontransportable because they use the value
of the machine word size. The unrestricted use of field selectors can 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:
DECsytem-

10/20
0 :::; p

PDP-11

p + s:::; 36

p + s:::; 16

0:::; s:::; 36

0 ~ s ~ 16

VAX

O~p

0:::; s:::; 32

From the table, you can see that the PDP-11 is the most restrictive; the
DECsystem- IO /20 is moderately restrictive; and the VAX is the least
restrictive.
To ensure the transportable use of field selectors, you 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:
•

6-38

Field selectors can appear only in the definition of user-defined
structures.

Transportability Guidelines

Restricting the domain of field selectors to structures isolates their use.
Field selectors should be isolated so that:
•
•
•

6.4.5.4

Changes in data structure design are easier.
Machine dependencies can easily be placed in REQUIRE files.
Complex code making heavy use of the predeclared literals is limited
to declarations.

GEN-VECTOR

GEN_VECTOR is a transportable structure that is also affected by the
table of field selector value restrictions. 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
PDP-11 and VAX to 27 on the DECsystem-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 DECsystem-10 /20 word and
three into a VAX longword.
The GEN_VECTOR structure packs as many elements as possible into a
BLISS value and so makes use of the machine-specific literal %BPVAL.
However, since allocation is in terms of %BPUNIT, a literal is 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 do not cross word boundaries. This constraint exists because
of the restrictions placed on the value of the position parameter of a
DECsystem-10/20 and PDP-11 field selector. For the same reason elements cannot be longer than %BPVAL, as given in the table of field
selector restrictions.
As in FLEX_VECTOR, the allocation expression of GEN_VECTOR needs
to calculate the number of allocation units needed by the entire vector.
This is again based on the number of elements ( N) and the size of each
and the size of each element ( S ); however, because the elements are
packed, the expression is slightly more complicated.
The first value is the number of elements that will fit in a BLISS value.
The following expression computes this value:
(Y.BPVAL/S)

Transportability Guidelines

6-39

Given this, to obtain the number of BLISS values or words needed for the
entire vector, divide this value into N:
(N/(1.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
results in the number of allocation units needed by the vector:
((N/(Y.BPVAL/S))•Y.UPVAL)

For clarity's sake and because this expression is again used, it is expressed
as a macro with N and S as parameters:
MACRO
WHOLE_VAL(N,S) =
((N/(Y.BPVAL/S))_*Y.UPVAL)Y.;

The name of the macro suggests that it calculates the number of whole
words needed. If N were an integral multiple of the number of elements
in a word, then this macro would be sufficient for allocation purposes.
Because 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/(Y.BPVAL/S))

The MOD function calculates this value, as follows:
(N MOD (Y.BPVAL/S))

Multiplying this value by the size of each element gives the total number
of bits that remain to be allocated:
(N MOD CY.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 (Y.BPVAL/S)) * S)Y.;

PART_VAL computes the number of bits allocated in the last (partial)
word.

6-40 Transportability Guidelines

Taking this value, adding an arbitrary factor, and then dividing by
%BPUNIT gives us the number of allocation units needed for the remaining bits:
(PART_VAL(N,S) + Y.BPUNIT -1)/Y.BPUNIT

The total number of allocation units has been calculated and the structure
allocation expression is as follows:
[WHOLE_VAL(N,S) +
(PART_VAL(N,S) + Y.BPUNIT - 1)/Y.BPUNIT]

As it works out, the structure-body expression for GEN_VECTOR is
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.
The offset is some number of addressable units and is a function of the
value of the index I. The expression calculating this number of units is the
macro WHOLE_VAL. Thus, the first part of the accessing expression is as
follows:
GEN_VECTOR + WHOLE_VAL(l,S)

Note that the macro was called with the index parameter I.
This expression results in the structure being aligned on some addressable
boundary, but because the element may not begin at this point (that is, the
element can 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 calculates this value based on the index I:
<PART_VAL(l,S),S,EXT>

The size parameter is the value S. The position parameter will be calculated at runtime, based on the value of the index I.
This completes the definition of GEN_VECTOR. The entire declaration is
as follows:
STRUCTURE
GEN_VECTOR[I;N,S,EXT=1]
[WHOLE_VAL(N,S) +
(PART_VAL(N,S) + 1.BPUNIT - 1)/Y.BPUNIT]
(GEN_VECTOR + WHOLE_VAL(l,S))
<PART_VAL(l,S),S,EXT>;

You can compile this structure to see how it works in BLISS-16, BLISS-32,
and BLISS-36.
Transportability Guidelines 6-41

6.4.5.5

Summary of Structures and Field Selectors

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 and BLOCKVECTORS
have not been discussed, but it is hoped that you will get from the
examples a feeling for the techniques involved in transporting structures.
There is no easy solution to transporting data structures. When developing
data structures, you should consider the machines for which the program
or system is targeted and make full use of predeclared literals, such as
%BPUNIT.
This exercise in developing transportable structures has demonstrated the
following two points:
•
•

Parameterization
Field selector usage

By parameterizing certain machine-specific values, and by taking full
advantage of the powerful STRUCTURE mechanism, two transportable
structures have been developed.
Although you can access odd (nonaddressable) units of data using field
selectors, they should only be used in structure declarations.

6-42 Transportability Guidelines

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 you have 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 the BLISS Language Reference Manual
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 as follows:
•
•
•
•
•

CODE and NOCODE
OPTIMIZE and NOOPTIMIZE
OPTLEVEL
SAFE and NOSAFE
ZIP and NOZIP

Compiler Overview and Optimization Switches 7-1

7.1 Compiler Phases
The compiler is organized conceptually into seven major phases:
LEXSYN

Lexical and syntactic analysis

FLOW

Flow analysis

DELAY

Heuristics

TNBIND

Temporary name binding (register allocation)

CODE

· Code generation

FINAL

Code stream optimization

OUTPUT

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; however, this level of detail is not important in the
following discussion of the phases. The term "phase" should not be taken
literally.

7.1.1

Lexical and Syntactic Analysis Phase
The lexical and syntactic phase (LEXSYN) performs the following functions:
•
•
•
•

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 tum to analyze and completely produce and output code
for that entire routine. In this sense, the BLISS compiler is a multi-pass
compiler.

7-2

Compiler Overview and Optimization Switches

If the NOCODE switch is specified, the compiler operates in "syntax-only"
mode, in which the LEXSYN phase does not produce the tree representations for expressions and the later phases are not performed. If an error
(as opposed to 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.
There is an important limitation in this mode, however, in that some
errors cannot be detected because certain error detection and reporting can
occur only in later phases of the compiler that are not performed.
The difference between an error and a warning diagnostic is based on the
seriousness of the effect of the error on the internal representation of the
program used by the compiler.
In most cases, the compiler can recover and proceed with normal compilation. This permits further errors, if any, to be detected and, in some cases,
may permit the resulting object module to be used for execution time
debugging before the source module is corrected and recompiled. Errors
from which the compiler can continue normally are reported as warning
diagnostics.
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.
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 Phase
The flow analysis phase (FLOW) examines the internal tree representation
of a complete routine and performs the following functions:
•

•

Identifies expressions that appear more than once in the source but
produce the same value (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.

Compiler Overview and Optimization Switches 7-3

•

Identifies expressions that occur on all alternatives of the IF, CASE,
and SELECTONE expressions. Such expressions can 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 that might be more efficient in time or space, or both.
Note that the next phase (DELAY) determines which alternative is actually
used; the FLOW phase only identifies the possible choices.
If OPTLEVEL is specified with a value of 0 or l, the flow analysis phase
is 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 effects that will be described.

To understand the effects of the OPTIMIZE and SAFE switches, it is first
necessary to understand more about how flow analysis is performed.
7 .1.2.1

Knowing When a Value Changes

One operator in BLISS, the assignment operator, can change the contents
of a data segment. Routine calls can 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 compiler performs the same analysis
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.
Machine-specific functions are treated as normal routine calls, except that
the compiler has more detailed information about which parameters can
cause changes and which cannot.
Several aspects of this analysis process are illustrated in the following
examples. In the examples these declarations are assumed:

7-4

Compiler Overview and Optimization Switches

OWN
X: VECTOR[10],
Y,
Z;
EXTERNAL ROUTINE
F;

First, consider the following sequence of assignments:
I = 3;
Y = .X[. I];

X [7] = .X [ . Y] ;
Z = .X[.!]+1;

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 compiler does not
recognize the possible common subexpression .X[.I]. (However, note that
the common subexpression X[.I], which computes the address of the Ith
element of X, is recognized because 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[11] = 11;
y = .Z;

In the first line, the assignment to X[l 1] 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 Xis 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 Zin 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 name used to
reference storage in the analysis performed by FLOW.
Now consider the case where a name cannot be identified for the storage
being changed. This is the case in the following example:
Z = FO;
3;

.z =

Compiler Overview and Optimization Switches 7-5

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 the following:
•
•

Dynamically created data structures that do not have names
Data segments passed as parameters of routine calls that cannot be
referenced in the called routine by the name used to allocate the
storage

You can use the NOSAFE value of the /OPTIMIZE qualifier to override
the default assumption described above (SAFE is the default). If NOSAFE
is specified, the compiler assumes that indirect assignments change some
named data segment. Because it is nearly impossible to identify the data
segment that is changed, this assumption is guaranteed by the compiler
by making the 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:
F(X) + .X

This expression 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. Because the routine call F(X) may change the
contents of X, the question becomes: When does the compiler account for
the (potential) change? It does not make sense to account for this within
·the expression without precisely specifying the order of evaluation. It
makes sense to account for (:hanges 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 an exclamation point ( ! ) is used to point to
the mark point within the language syntax on the subsequent line.

7-6

Compiler Overview and Optimization Switches

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, ... ]: exp; ... TES

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. The compiler takes this
change into account 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.

Compiler Overview and Optimization Switches 7-7

However, specifying NOOPTIMIZE is not equivalent to specifying that no
flow analysis is performed, because common subexpressions that occur
between mark points are still detected. For example:
Y = ( .X•2)+F( .X•2)

In this expression, subexpression .X•2 is computed once and the resulting
value used twice, even when NOOPTIMIZE is specified.

7.1.3

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 uncommon subexpressions that occur only once.
These subexpressions should be computed in the same temporary
register or memory location to maximize the use of 2-operand as
opposed to 3-operand instructions.

None of the switches affect the operation of the DELAY phase.

7.1.4 Temporary Name Binding Phase
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:
•
•

7-8

Determines the lifetime (the first and last uses) of 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).

Compiler Overview and Optimization Switches

•
•

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 a loop tends to execute faster,
even though the overall size of the routine can become larger.

7.1.5

Code Generation Phase
The code generator phase (CODE) processes the tree and generates instructions. Because 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 the operation of the CODE phase.

7.1.6

Code Stream Optimization Phase
The code stream optimization phase (FINAL) processes the code stream
produced by CODE and makes further optimizations at the machine code
level. The following optimizations are performed:
•
•

Peephole optimization. One sequence of instructions is 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 instructions that precede the TST.

Compiler Overview and Optimization Switches 7-9

•

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 into a common
instruction are merged into a single sequence.

You can use the OPTLEVEL switch 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 Phase
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.

7-1 0

Compiler Overview and Optimization Switches
J

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 prevents optimization across mark points.

OPTLEVEL

FLOW

At levels 0 and l, flow analysis is not performed.

FINAL

At levels 0 and l, cross-jumping and branch
chaining are not performed. At level 0, peephole optimizations that are not adjacent are not
performed.

SAFE

FLOW

If flow analysis is performed, NOSAFE specifies that
indirect changes are assumed to change all storage.

ZIP

TN BIND

ZIP specifies that data segments used in loops are
to be given increased importance in determining
register allocation.
·

The OPTLEVEL switch is a composite switch that includes appropriate
settings of the other switches in an ordered way. It can be specified in 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.
The optimizations performed at each setting of the OPTLEVEL switch are
as follows:
1.
2.
3.
4.
5.
6.
7.
8.
9.

•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

Compiler Overview and Optimization Switches 7-11

10. Scans for cheaper form of addressing
11. Branch chaining
12. *SAFE optimizations
13. *OPTIMIZE over mark points (for example,;)
14. *ZIP speed/space trade off (faster but possibly larger)
The following table relates the optimizations to the OPTLEVEL settings:
OPTLEVEL
0

2
x
x
x

l*
2*
3
4
5

11
12*

13*
14*

x
x

Legend:

*: Another switch can control this optimization separately
x: Allowable optimization
+: Allowed (with increased freedom)
r: Allowed (with certain restrictions)

7-12

Compiler Overview and Optimization Switches

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 Version 4.3. Note that with
the exception of the VAX Source Code Analyzer, the BLISS tools (utility
programs) and system interfaces described here are not supported products
at the time of this 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 VAX Source Code Analyzer (SCA}
The VAX Source Code Analyzer (SCA) is a source code cross-reference
and static analysis tool that is used to aid you in understanding large-scale
software systems. SCA is integrated with the VAX Language-Sensitive
Editor (LSE), but can also be used, in a reduced capacity, at the DCL level
as a standalone tool. In either case, SCA libraries are created and analysis
data files loaded, using SCA commands.
For details about LSE and SCA refer to Appendix G.

Tools, Libraries, and System Interfaces

8-1

8.2 Tutorial Terminal Input/Output Package (TUTIO)
TUTIO.R32 is a BLISS REQUIRE file that contains some simple terminal
1/0 primitives. This package is normally used in conjunction with the
BLISS self-paced study course, as outlined in the BLISS Primer, but can
also be useful for writing short miscellaneous programs. To gain access
to the elements of this package, insert the following line in your BLISS
program:
REQUIRE 'SYS$LIBRARY:TUTl0';

A list of these primitives and their functions appears below. The following
conventions are used in the descriptions:
char (character)
len (length in characters)
addr (memory address)
value (integer)
radix (integer)
•
•
•
•
•
•
•
•

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 the
terminal.
TTY_pUT_CRLF ();-writes a carriage return/line feed sequence to
the terminal.
TTY_pUT_ASCIZ (addr);-writes an ASCIZ string to the terminal.
TTY_pUT_MSG (addr,len);-writes a string of ASCII characters to the
terminal.
TTY_pUT-1NTEGER (value,radix,len);-writes an integer to the
terminal.
n = TTY_GET_LINE (addr,len);-reads a line from the terminal into a
buffer and returns the number of characters read.

The TUTIO package functions only with a terminal; it does not work from
a batch job or command procedure file.

8-2

Tools, Libraries, and System Interfaces

8.3 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-in
users, many are available for general use and provide techniques that can
be used in application programs.
The BLISS interface to the VMS system service 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.
With the BLISS interface macros, the syntax for invoking system services
in BLISS is almost identical to the VAX 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. (Following is an example of the BLISS-style
usage.)
To use the interface, include the following 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=1)
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.

Tools, Libraries, and System Interfaces

8-3

8.3.1

Sa•ple Program Using VMS System Services
The program shown below prints the time of day at the user's terminal. It
shows the use of system services $GETTIM and $FAO and of the common
run-time library routine LIB$PUT_OUTPUT.
MODULE SHOWTIME(IDENT= 1 1-1 1 Y.TITLE'Print time•, MAIN=TIMEOUT)=
BEGIN
LIBRARY 1 SYS$LIBRARY:STARLET 1 ;
Defines System Services
OWN
TIMEBUF: VECTOR[2],
! 64-bit system time
MSGBUF: VECTOR[80,BYTE],
! Output message buffer
MSGDESC: BLOCK[8,BYTE] PRESET( [DSC$W_LENGTH]=80,
[DSC$A_POINTER]=MSGBUF)
BIND
FMTDESC=Y.ASCID Y.STRING('At the tone, the time will be '
Y.CHAR(7), '!151.T' );
EXTERNAL ROUTINE
LIB$PUT_OUTPUT: ADDRESSING_MODE(GENERAL);
ROUTINE TIMEOUT=
BEGIN
LOCAL
RSLT: WORD;
$GETTIM( TIMADR=TIMEBUF );
$FAOL( CTRSTR=FMTDESC,
OUTLEN=RSLT,
OUTBUF=MSGDESC,
PRMLST= Y.REF(TIMEBUF));
MSGDESC[O] = .RSLT;
LIB$PUT_OUTPUT( MSGDESC )
END;
END ELUDOM

Resultant string length
Get time as 64-bit integer
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_QUTPUT is part of the VMSRTL
shareable image; as such it is referenced by GENERAL addressing. The
call on $FAOL uses %REF to make the PRMLST value the address of a
pointer to the TIMEBUF buffer.

8-4

Tools, Libraries, and System Interfaces

8.3.2

Common Errors in Using System Services
When you invoke system services, you may encounter a number of errors.
Two of the more common errors occur when the $HIBER and $FAO
services are invoked.
The $HIBER system service keyword macro has no arguments. Thus, it is
invoked as follows:
$HIBER

Note the absence of any parenthesized argument list.
The OUTLEN keyword parameter of the $FAO 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.
You should guard against this problem in calls to other system services.

8.4 Record Management Services Interface
VAX Record Management Services (VAX RMS) is a collection of file
and record-level 1/0 routines that enable user programs to process and
manage data files. Also included as a part of VAX RMS is a set of BLISS
macro definitions that facilitate control block initialization and the calling
of VAX RMS control routines.
RMS definitions appear in SYS$LIBRARY:STARLET.REQ or
SYS$LIBRARY:STARLET.L32. For a general description of VAX RMS
programming, see the VAX Record Management Services Reference Manual.

Tools, Libraries, and System Interfaces

8-5

8.4.1

Using VAX RMS Macros
STARLET .REQ provides three types of VAX RMS definitions:
1. Field definitions and constants used in VAX RMS control blocks
2. Static and dynamic control block initialization macros
3. VAX RMS routine-call keyword macros
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 RMS
MACRO 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.

8.4.2

Sample Routine Using VAX RMS
The following sample program illustrates the use of the VAX RMS macros.
The program opens a file named MYFILE.SRC and copies it to a file
named MYFILE.LIS.
MODULE RMSTEST(IDENT='1-1' 1.TITLE'BLISS-RMS Example',MAIN=COPYIT)=
BEGIN
!++
! Sample program showing use of BLISS/RMS-32 Interface Macros
!--

LIBRARY 'SYS$LIBRARY:STARLET';

All definitions are here

OWN
MYBUF:
INFAB:

VECTOR[CH$ALLOCATION(132)],
$FAB(FNM='MYFILE.SRC',
FAC=GET),

OUTFAB: $FAB(FNM='MYFILE.LIS', RFM=VAR,
RAT=CR, FAC=PUT),

8-6

Tools, Libraries, and System Interfaces

Input record buffer
Source FAB
Destination FAB

INRAB:

$RAB(UBF=MYBUF, USZ=132,
ROP=<LOC,RAH>, FAB=INFAB),
OUTRAB: $RAB(ROP=WBH, FAB=OUTFAB);
ROUTINE COPYIT=
BEGIN
LOCAL
STS;

RAB def'n: Locate Read,
and Multibuffer I/0
on input and output.

! RMS service-completion code

$OPEN( FAB=INFAB );
$CONNECT( RAB=INRAB );
$CREATE( FAB=OUTFAB );
$CONNECT( RAB=OUTRAB );

Open input file
and associate RAB.
Create a new output file
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;
$CLOSE( FAB=INFAB );
$CLOSE( FAB=OUTFAB );
IF .STS EQL RMS$_EOF
THEN
SS$_NORMAL
ELSE
.STS
END;
END ELUDOM

Copy record descr.
to output RAB and
write the record.

Close the input
and output files.
Check for EOF on input
Tell System everything is OK, or
Return the RMS error status.

8.5 Other VMS Interfaces
Two other VMS interfaces (LIB and TP AMAC) are available.

8.5.1

LIB Interface
LIB.L32 contains internal interfaces between BLISS-32 and the 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, a subset of LIB.

Tools, Libraries, and System Interfaces

8-7

8.5.2 TPAMAC Interface
TP AMAC.REQ provides BLISS macros for LIB$TPARSE, a finite-state
transition parser. The sample program presented in Example 8-1 closely
parallels the example in the VAX/VMS Run-Time Library Routines Reference

Manual.

8-8

Tools, Libraries, and System Interfaces

Example 8-1:

Sample TPARSE Program

MODULE CREATE_DIR(XTITLE 'Create Directory File' !DENT= 'XOOOO',
MAIN=CREATE_DIR) =
BEGIN
!+
!

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=100
/PROTECTION=(SYSTEM:R,OWNER:RWED,GROUP:R,WORLD:R)
The three qualifiers are optional. Alternatively, the command
may take the form
CREATE/DIR DEVICE:[202,31]
using any of the optional qualifiers.
!---

LIBRARY 'SYS$LIBRARY:STARLET';
LIBRARY 1 SYS$LIBRARY:CLIMAC 1 ;
LIBRARY 1 SYS$LIBRARY:TPAMAC 1 ;

Define CL! offsets
and request blocks,
and TPARSE stuff too.

FORWARD ROUTINE
BLANKS_OFF,
CHECK_UIC,
STORE_NAME,
MAKE_UIC,
CREATE_DIR;
Define parser flag bits for flags longword
LITERAL
UIC_FLAG=
ENTRIES_FLAG=
PROT_FLAG=

1,
2,
4;

/UIC seen
/ENTRIES seen
/PROTECTION seen

(Continued on next page)

Tools, Libraries, and System Interfaces

8-9

Example 8-1 (Cont.):

Sample TPARSE Program

CLI request descriptor block to get the command line
OWN
REQ_COMMAND: $CLIREQDESC( RQTYPE=GETCMD );
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);

Longword count
Allow abbreviation
Process spaces explicit!

Parser Data Base
OWN
PARSER_FLAGS,
DEVICE_STRING:
VECTOR[2],
ENTRY_COUNT,
FILE_PROTECT,
UIC_GROUP,
UIC_MEMBER,
UIC_OWNER,
NAME_COUNT,
DIRNAME:
BLOCKVECTOR[8,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);
%SBTTL 'Parser State Table'
$INIT_STATE( UFD_STATE, UFD_KEY );
Read over the command line to the first blank in the command.
$STATE( START,.
(TPA$_BLANK,
(TPA$_ANY,

,BLANKS_OFF),
START));

(Continued on next page)

8-10 Tools, Libraries, and System Interfaces

Example 8-1 (Cont.):

Sample TPARSE Program

Read device name string and trailing colon
$STATE(,
(TPA$_SYMBOL,
$STATE(,

,DEVICE_STRING));

(I; t));

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,
( I/' ) I
( TPA$_EOS,
TPA$_EXIT) );
$STATE(,
( 'OWNER_UIC' , PARSE_UIC,
, UIC_FLAG,
PARSER_FLAGS) ,
('ENTRIES',
PilRSE_ENTRIES, , ENTRIES_FLAG, PARSER_FLAGS),
('PROTECTION' ,PARSE_PROT,, PROT_FLAG,
PARSER_FLAGS) );
Get file owner UIC
$STATE( PARSE_UIC,
( t; I).

('='));

$STATE(,
( (UIC),

OPTIONS));

Get number of directory entries
$STATE( PARSE_ENTRIES,
(I; I).

('='));

$STATE(,
(TPA$_DECIMAL,OPTIONS,

ENTRY_COUNT));

(Continued on next page)

Tools, Libraries, and System Interfaces

8-11

Example 8-1

(Cont.):

Sample TPARSE Program

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,
(I : I) 1

( '='));

$STATE(,
(I (I));

$STATE( NEXT_PRO,
('SYSTEM',
SYPR ),
('OWNER',
OWPR ) ,
( I GROUP I •
GRPR ) •
('WORLD',
WOPR) );
$STATE( SYPR,
(I ; I) 0
( '=') ) ;

$STATE(SYPRO,
SYPRO, , Y.X'1',
SYPRO,
Y.X'2',
SYPRO, , Y.X'4',
('E' •
SYPRO, , Y.X 1 8 1 ,
( 'D' •
(TPA$_LAMBDA, ENDPRO) ) ;

('R' •
('W' •

FILE_PROTECT),
FILE_PROTECT),
FILE_PROTECT),
FILE_PROTECT),

$STATE(OWPR,
(I ; I) 1

( ·=·));

$STATE(OWPRO,
OWPRO, , Y.X'0010',
( 'R' •
OWPRO, , Y.X'0020',
('W''
OWPRO, , Y.X'0040',
('E' •
OWPRO, , Y.X'0080',
( 'D' •
(TPA$_LAMBDA, ENDPRO) ) ;

FILE_PROTECT),
FILE_PROTECT),
FILE_PROTECT),
FILE_PROTECT),

$STATE(GRPR,
(I; I).

( '='));

$STATE(GRPRO,
GRPRO, , Y.X'0100',
('R' •
GRPRO, , Y.X'0200',
('W' •
GRPRO, , Y.X'0400',
( 'E' •
GRPRO, , Y.X'0800',
( 'D''
(TPA$_LAMBDA, ENDPRO) ) ;

FILE_PROTECT),
FILE_PROTECT),
FILE_PROTECT),
FILE_PROTECT),

(Continued on next page)

8-12: Tools, Libraries, and System Interfaces

Example 8-1 (Cont.):

Sample TPARSE Program

$STATE(WOPR,
(I: I).
(I: I));

$STATE(WOPRO,
FILE_PROTECT),
FILE_PROTECT),
FILE_PROTECT),
FILE_PROTECT),

WOPRO, • Y.1'1000'.
WOPRO, , Y.X 1 2000 1 ,
WOPRO, , Y.X'4000',
WOPRO, , Y.X'8000',
(TPA$_LAMBDA, ENDPRO) ) ;

('R' •
('W' •
('E' •
('D' •

$STATE(ENDPRO,
('

(')',

NEXT_PRO),
OPTIONS) );

Subexpressions to parse a UIC string.
$STATE( UIC,
(I [I) ) ;

$STATE(,
(TPA$_0CTAL,
$STATE(,

UIC_GROUP) );

(I ' I));

$STATE(.
(TPA$_0CTAL,
$STATE(.
(']',

UIC_MEMBER) );
TPA$_EXIT, CHECK_UIC) );

Subexpressions to parse a general directory string
$STATE( NAME,
(I [I) ) ;

$STATE( NAMEO,
(TPA$_STRING,
, STORE_NAME) );
$STATE(,
('.',
NAMED),
(']',
TPA$_EXIT) );
Note absence of $END_STATE macro.
Y.SBTTL 'Parser Action Routines'
ROUTINE BLANKS_OFF=

(Continued on next page)

Tools, Libraries, and System Interfaces

8-13

Example 8-1 (Cont.):

Sample TPARSE Program

Shut off explicit blank processing after passing the command name.
BEGIN
BUILTIN
AP;
MAP

AP:

REF BLOCK[,BYTE];
AP[TPA$V_BLANKS] = O;
1 ! Success always.
END;

ROUTINE CHECK_UIC =
Check the UIC for legal value range.
BEGIN
BUILTIN
AP;
MAP

AP:

REF BLOCK[,BYTE];

IF .UIC_GROUP<16,16> NEQ 0 OR
.UIC_MEMBER<16,16> NEQ 0
THEN
RETURN O;

UIC components are 16 bits only

UIC_OWNER<0,16> = .UIC_MEMBER<0,16>;
UIC_OWNER<16,16> = .UIC_GROUP<0,16>;
1

END;
ROUTINE STORE_NAME=
Store a directory name component
BEGIN
BUILTIN
AP;
MAP
AP:

REF BLOCK[,BYTE];

IF .NAME_COUNT GEQ 3 THEN RETURN O;

Maximum of 3 components

(Continued on next page)

8-14 Tools, Libraries, and System Interfaces

Example 8-1

(Cont.):

Sample TPARSE Program

DIRNAME[.NAME_COUNT,0,0,32,0]
DIRNAME[.NAME_COUNT,1,0,32,0]
NAME_COUNT = .NAME_COUNT + 1;

.AP[TPA$L_TOKENCNT];
.AP[TPA$L_TOKENPTR];

IF .AP[TPA$L_TOKENCNT] GTR 9 THEN RETURN O;

Store the
descriptor
Set to next
free slot

Name too long

END;
ROUTINE MAKE_UIC=
BEGIN
BUILTIN
AP;
MAP
AP :
REF BLOCK[, BYTE] ;
OWN
UIC_STRING:
VECTOR[CH$ALLOCATION(6)];
IF .UIC_GROUP<S,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[0,1,0,32,0] = UIC_STRING;
$FAOL( CTRSTR=UPLIT(6, 1 !0B!OB 1 ) ,
OUTBUF=DIRNAME,
PRMLST=UIC_GROUP)
END;

Point to string buffer
Convert UIC to octal string

Y.SBTTL

'Main Program'

ROUTINE CREATE_DIR=
!+

! This is the main program of the CREATE/DIRECTORY utility. It gets
! the command line from the command interpreter and parses it with TPARSE.
!
!---

BEGIN
! Call the command interpreter to obtain the command line
!

SYS$CLI( REQ_COMMAND, 0, 0 );

(Continued on next page)

Tools, Libraries, and System Interfaces

8-15

Example 8-1

(Cont.):

Sample TPARSE Program

Copy the input string descriptor into the TPARSE control block
and call LIB$TPARSE. Note that impure storage is assumed to be zero.
TPARSE_BLOCK[TPA$L_STRINGCNT] = .REQ_COMMAND[CLI$W_RQSIZE];
TPARSE_BLOCK[TPA$L_STRINGPTR] = .REQ_COMMAND[CLI$A_RQADDR];
IF NOT LIB$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
END;
END ELUDOM

8-16

Tools, Libraries, and System Interfaces

Return Success to command interpreter

Chapter 9

BLISS-32 Code Examples
This chapter provides useful examples of BLISS-32 coding techniques.
These examples demonstrate the use of many BLISS language features.

9.1

Example 1: The ALPHA Program
This program prompts the user for a line of text, removes all but the uppercase characters from the line, then rearranges and prints the uppercase
characters in alphabetical order. The algorithms chosen are not optimal,
but they serve to demonstrate recommended style. The program consists
of two routines (SORT_CHARS and ALPHA_SORT) and three included
files.
The ALPHA program uses the following facilities:
•
•
•

TUTIO-Tutorial Terminal Input/Output Package
CELPKG-Cell Manipulation Primitives
VMS RTL-Memory Management Routines (called within CELPKG)

Note that the ALPHA module is transportable but the TUTIO and
CELPKG packages are not. TUTIO exists for target systems other than
the VAX, while CELPKG can be written for other systems.
The following steps are used to run the ALPHA program:
1. Produce a library file for the CELPKG program:
$ BLISS /LIB CELPKG

BLISS-32 Code Examples

9-1

2. Compile the ALPHA program:
$ BLISS ALPHA

3. Link the ALPHA program:
$ LINK ALPHA

4. Run the ALPHA program:
$ RUN ALPHA

5. As an example, respond to the input prompt as follows:
INPUT: 12P4E6IQOY-='asFgjkW; '{ZXCBNM<>?ASDVRGHJKLTUIRETI
OUTPUT:ABCDEFGHIJKLMNOPQRSTUVWXYZ
INPUT: ICTRL/C I
$

The following sections contain the annotated ALPHA module and the
cell-handling package (CELPKG).

9.1.1

Module ALPHA
MODULE ALPHA

!DENT= 'x1-1', Y.TITLE'Sample Program'
MAIN=ALPHA_SORT ) =

BEGIN
!++

FACILITY:

Sample Program

ABSTRACT:
This sample program prompts you for a line of text,
removes all but uppercase characters from the line,
and prints the uppercase characters in alphabetical
order. The program is terminated by a blank line or
a Control-C c-c).
ENVIRONMENT:

.+
! TABLE OF CONTENTS:
!-

FORWARD ROUTINE
SORT_CHARS,
ALPHA_SORT;

9-2

BLISS-32 ·Code Examples

Does sorting
Main routine

INCLUDE FILES:
LIBRARY I CELPKG I ; 0

! Interface to cell
! package

%BLISS32( LIBRARY 'SYS$LIBRARY:STARLET' ;) 49
REQUIRE I SYS$LIBRARY: TUTIO I ; . •
!+
! EQUATED SYMBOLS:
!-

LITERAL
TRUE=
1,
FALSE=
0,
LINE_BUFF_SIZE=

133; 9

!+
! OWN STORAGE:
!-

OWN
HEADER:
HEADER_STR
PRESET( [FLINK] = HEADER,
[BLINK] = HEADER,
[SIZEF] = HEADER_SIZE ), 0
LINE_BUFF:

VECTOR[CH$ALLOCATION(LINE_BUFF_SIZE)]; 0

Use a LIBRARY declaration to include GET_CELL, REL _CELL, INS_
CELL, REM_CELL, and the CELL data structure.
49 If BLISS-32, use a LIBRARY declaration to include the definition of
SS$_NORMAL. This is used by the main routine as the return value.
0 Use a REQUIRE declaration to include the terminal 1/0 functions.
e Limit the input line length to 132 and set the buffer size one character
longer to detect longer lines.
0 Allocate and initialize a list header in static storage.
0 Allocate the line buffer.
NOTE

In all three declarations, the file type is allowed to have a
default. This simplifies the writing of portable software, because
the compiler searches for language-dependent extensions (such
as .R32) before searching for .REQ.

BLISS-32 Code Examples

9-3

9.1.2

Routine SORT-CHARS
ROUTINE SORT_CHARS (LEN, CH_PTR)
!++
! FUNCTIONAL DESCRIPTION:

The input to this routine is a character sequence,
identified by LEN and CH_PTR. All non-uppercase
alphabetic characters are removed from the sequence
and the remaining characters are put in alphabetical
order. The resulting sequence is placed in the character
data segment originally occupied by the input character
sequence.
FORMAL PARAMETERS:
LEN
CH_PTR

- Length of character sequence.
- Character pointer to the first
character in sequence.

IMPLICIT INPUTS:
NONE
ROUTINE VALUE:
Length of the resulting character sequence.
SIDE EFFECTS:
The storage pointed to by CH_PTR is modified.

BEGIN
LOCAL
CHAR_PTR,
CURRENT_CELL:

REF CELL_STR;

A character pointer
A cell pointer

CHAR_PTR = .CH_PTR; 0
INCR I FROM 1 TO .LEN DO fJ
BEGIN
LOCAL
CHAR;
CHAR= CH$RCHAR_A(CHAR_PTR);

A character
Read character and
advance pointer

IF .CHAR GEQ 1.C'A' AND .CHAR LEQ Y.C'Z' f)
THEN

BEGIN
LOCAL
CELL:

9-4

BLISS-32 Code· Examples

REF CELL_STR;

A cell pointer.

CURRENT_CELL = .HEADER[FLINK]; 8
UNTIL .CURRENT_CELL EQLA HEADER DO 0
BEGIN
IF .CURRENT_CELL[VALUEF] GEQ .CHAR
THEN
EXITLOOP; 0
CURRENT_CELL = .CURRENT_CELL[FLINK]
END;
CELL= GET_CELL(CELL_SIZE); f)
CELL[VALUEF] = .CHAR;
INS_CELL( .CELL, .CURRENT_CELL[BLINK]
END
END;
CHAR_PTR = .CH_PTR; 0
UNTIL
REM_CELL (CURRENT_CELL = .HEADER[FLINK]) EQL EMPTYK
DO f>
BEGIN
CH$WCHAR_A( .CURRENT_CELL[VALUEF], CHAR_PTR ); 4D
REL_CELL(.CURRENT_CELL)
END;
CH$DIFF(.CHAR_PTR, .CH_PTR)
END;

a.
!End of SORT_CHARS

0
8

Initialize CHAR_pTR to point to first character in sequence.
In this loop, get a cell for each uppercase character in the sequence
and insert the cell in a doubly linked list sorted by character values.
8 Test for uppercase characters.
G Initialize CURRENT_CELL to the address of the list header.
0 Move forward through the list of cells until you reach the last. The
last cell is recognized by its forward pointer, which points back to the
list header.

Note that the EQLA operator (although synonymous with EQL) is
used to remind the programmer that addresses are being compared.
If the character value stored in this cell is greater than or equal to the
last character value read, exit the loop. (You want to insert the new
character before this one.)
Note that if the loop runs to completion, and the EXITLOOP is never
executed, CURRENT_CELL is left pointing to the list header. Inserting
before the list header is equivalent to inserting at the end of the list
(desired behavior).
BLISS-32 Code Examples

9-5

Get a cell from heap storage store the character value there and insert
the cell before the one pointed to by CURRENT_CELL.
0 Reset CHAR_pTR to point to the first character in the sequence.
0 For each cell in the doubly-linked list, write the character into the
character sequence and delete the cell.
4D Write the character and advance the pointer.
4D Compute the length of the resulting character sequence by the difference between the pointer to the first character position and the next
one to be written.

9.1.3

Routine ALPHA-SORT
ROUTINE ALPHA_SORT=
!++

FUNCTIONAL DESCRIPTION:
Main routine of program. Loops until a null input line
is read from the terminal.
FORMAL PARAMETERS:
NONE.
IMPLICIT INPUTS:
NONE
ROUTINE VALUE:
Return SS$_NORMAL to VMS.
Return 0 to other environments (value is ignored).
SIDE EFFECTS:
NONE
!--

BEGIN
LABEL
LOOP_BODY;
WHILE TRUE DO
LOOP_BODY:
BEGIN
LOCAL
LEN;

9-6

BLISS-32 Code Examples

Number of chars
in line buffer

TTY_PUT_QU0( 1 INPUT: 1 ) ; 0
LEN= TTY_GET_LINE( LINE_BUFF, LINE_BUFF_SIZE );
IF .LEN EQL 0 THEN EXITLOOP;

! EDF exit.

IF .LEN EQL LINE_BUFF_SIZE
THEN
BEGIN
TTY_PUT_CRLF();
TTY_PUT_QUO( 'Input line is too long. 1 ) ;
TTY_PUT_CRLF();
LEAVE LOOP_BODY
! Exit block but
END;
! continue looping.
LEN = SORT_CHARS( .LEN, CH$PTR(LINE_BUFF) ); @

TTY_PUT _Quo c•oUTPUT >;
TTY_PUT_MSG( LINE_BUFF, .LEN);
TTY_PUT _CRLF ()
END;
= •

End of main loop.

Y.IF Y.BLISS(BLISS32)
Y.THEN
SS$_NORMAL
Y.ELSE
0

Y.FI
END;
END
ELUDOM

0
8
8

End of ALPHA_SORT
End of module

Prompt for input.
Sort characters.
Print output.

BLISS-32 Code Examples

9- 7

9.1.4

Cell-Handling Package
%TITLE 'Cell-Handling Package'
!++
! FACILITY:

CELL-HANDLING PACKAGE

ABSTRACT:
This package contains macros to create and delete cells,
as well as to insert cells on and remove them from
doubly-linked lists.
ENVIRONMENT:
The VAX Common RTL routines LIB$GET_VM and LIB$FREE_VM
are used to get and free heap storage.
The VAX-11 hardware queue instructions INSQUE and REMQUE
are used to insert and delete cells from lists. See the
VAX Architecture Handbook for details .

.+
! TABLE OF CONTENTS:

GET_CELL
REL_CELL
INS_CELL
REM_CELL

Allocate a cell and return its address.
Deallocate a cell.
Insert a cell in a list.
Remove a cell from a list and return a
completion status.

!!+
! EQUATED SYMBOLS:
!!+
!

Values returned by REM_CELL.
N.B. That the values are carefully chosen to be
identical with those returned by the VAX-11 REMQUE
builtin function.
'

LITERAL
EMPTYK=
LASTK=
NOTLASTK=

9-8

BLISS-32 Code Examples

3,
2,
O;

List was already empty
Last element removed, list now empty
Element removed, but more remain

EXTERNAL REFERENCES:
EXTERNAL ROUTINE 0
LIB$GET_VM : ADDRESSING_MODE(GENERAL),
LIB$FREE_VM : ADDRESSING_MODE(GENERAL);

•+
! Cell Data Structure Definitions 8
!-

FIELD 0
COMMON_FLDS=
SET
FLINK= [O, 0, 32, O],
BLINK= [1, 0, 32, 0],
SIZEF= [2, 0, 16, O]
TES;
FIELD
VALUEF=
LITERAL
HEADER_SIZE=
CELL_SIZE=

[2, 16, 8, O];
3,
3;

Successor pointer
Predecessor pointer
Cell size (in fullwords)

Value part
Size of a list-header
Size of a cell on the
list

MACRO 8
HEADER_STR= BLOCK[HEADER_SIZE] FIELD(COMMON_FLDS) %.
CELL_STR= BLOCK[CELL_SIZE] FIELD(COMMON_FLDS, VALUEF) Y.;

0
8
0

VMS Common RTL routines; GENERAL is required to get position
independent references.
Defining a data structure using FIELD, LITERAL, and MACRO declarations is the recommended programming technique.
Declare names for the fields and sizes of cells.
Declare macros for statically allocating cells and map the appropriate
structure on dynamically specified cells.
Note that you can reference COMMONJLDS (FLINK, BLINK, SIZEF)
for things declared as list headers or cells; but you can reference the
VALUEF only for cells.

BLISS-32 Code Examples

9-9

9.1.5

Macro REL-CELL
MACRO REL_CELL( CELL ) =
I++

FUNCTIONAL DESCRIPTION:
Deallocates storage for the cell at the specified
address, returning the storage to the heap.
FORMAL PARAMETERS:
CELL

- Address of a cell.

BEGIN
BIND
C = (CELL) : CELL_STR; 0
LIB$FREE_VM( Y.REF( .C[SIZEF] * Y.UPVAL ), Y.REF( C) ) f)
END Y.;

! End of REL_CELL

Declare Casa name bound to the address of a cell, and associate
CELL_STR with C.
Note that the above is done for two reasons: First, to permit a
structured-reference to the SIZEF field and second, to cause sideeffects in the argument passed to REL_CELL to occur only once. For
example, if the macro-formal was twice referenced and the macro
invoked with REL_CELL (REM_CELL(.HEADER)), then REM_CELL
would remove two cells, while REL _CELL released memory for only
the second cell.

Note also that it is good programming practice to parenthesize macro
formals.
f) Call the VMS Run-Time Library routine to release the appropriate
number of bytes (addressable units) of storage.
Note that the arguments are passed by reference using %REF. The
first argument is the address of a fullword containing the size (in
addressable units) of the data segment to be released, while the
second argument is the address of a fullword containing the address
of the data segment to be released.
The size (in fullword units) is multiplied by %UPVAL (units per value)
to convert to a size specified in addressable units.

9-10

BLISS-32 Code Examples

9.1.6

Macro INS_CELL
MACRO INS_CELL( THIS_CELL, PREV_CELL )
!++
! FUNCTIONAL DESCRIPTION:

Insert the cell whose address is THIS_CELL in the
doubly-linked list, putting it after the cell whose
address is PREV_CELL.
FORMAL PARAMETERS:
THIS_CELL
PREV_CELL

- Address of the cell to be inserted.
- Address of the cell after which
THIS_CELL is to be inserted.

SIDE EFFECTS:
Fields in THIS_CELL, PREV_CELL, and the successor to
PREV_CELL are modified.

BEGIN
BUILTIN
INSQUE;

! VAX-11 Insert Entry in
! Queue Instruction.

INSQUE( (THIS_CELL), (PREV_CELL) ); 0
END %;

! End of INS_CELL

The semicolon is present here to cause the macro to be effectively
NOVALUE. Any attempt to use this macro in a value-required context
will cause the compiler to issue a diagnostic message.

BLISS-32 Code Examples

9-11

9.1. 7 Macro GET_CELL
MACRO GET_CELL( SIZE ) =
!++
! FUNCTIONAL DESCRIPTION:

Allocates storage for a cell of the specified size and
initializes the forward and backward pointers to point
to the cell.
! FORMAL PARAMETERS:

SIZE

- Size of cell (number of BLISS-values in cell).

RETURN VALUE:
Address of the CELL allocated.
!--

BEGIN
LOCAL
CELL:

REF CELL_STR;

LIB$GET_VM( 1.REF((SIZE) * 1.UPVAL), CELL); 0
CELL[FLINK] = .CELL;
CELL[BLINK] = .CELL;
CELL[SIZEF] =(SIZE); @
.CELL
END %;

! End of GET_CELL

Call the VMS Run-Time Library routine to allocate the appropriate
number of bytes (addressable units) of storage.
Note that as in REL_CELL, the arguments are passed by reference
using %REF. The first argument is the address of a fullword containing
the size (in addressable units) of the data segment to be allocated,
while the second argument is the address of a fullword whose content
is set to the address of the data segment allocated.

The size (in fullword units) is multiplied by %UPVAL (units per value)
to convert to a size specified in addressable units.
Note that if the macro formal SIZE was not parenthesized, the call
GET_CELL( .X + 1 ) would result in a size computation of .X + 1 *
%UPVAL. For BLISS-32, %UPVAL has a value of 4; thus the size
requested would be .X + 4 and not ( .X + 1 ) * 4.

9-12 BLISS-32 Code Examples

9.1.8

Macro REM _CELL
MACRO REM_CELL( THIS_CELL )
•++

FUNCTIONAL DESCRIPTION:
Remove the specified cell from its list. Its forward
and backward pointers are left pointing to the cell.
FORMAL PARAMETERS:
THIS_CELL

- Address of the cell to be removed.

COMPLETION CODES:
EMPTYK
LASTK
NOTLASTK

- List was empty, no cell removed.
- List now empty, last cell removed.
- List not empty, a cell was removed.

SIDE EFFECTS:
Fields in THIS_CELL, its predecessor and successor are
modified.

BEGIN
BUILTIN
REMQUE;
LOCAL
TEMP;

VAX-11 Remove Entry from
Queue Instruction.
Temporary for entry removed
from QUEUE.

REMQUE( (THIS_CELL), TEMP)
END Y.;

End of REM_CELL

9.2 Example 2: The CALC Program
This program accepts a simple integer expression for basic calculation to
demonstrate the use of error recovery and parse/calculate routines. The
program consists of seven routines and three INCLUDE files.

BLISS-32 Code Examples

9-13

The CALC program uses the following facilities:
•
•
•

STARLET-For system trap values
TUTIO-Tutorial Terminal 1/0 Package
CONDIT-Condition handling routine

The following steps are used to run the CALC program:
1. Compile the CALC program:
$ BLISS CALC

Link the CALC program:
$ LINK CALC

Run the CALC program:
$ RUN CALC
CALC: A hierarchical calculator.
Enter expression and terminate with
equal sign (=) or carriage return.
An empty line exits the program.

CALC>

Examples of responses to the input prompt follow:
CALC> 3*({2+4)/2)=RESULT: 9
CALC>

or:
CALC> 2*4<CR>
RESULT: 8
CALC> <CR>
$

9-14 BLISS-32 Code Examples

9.2.1

Module CALCULATE
MODULE CALCULATE (MAIN = CALC_DRIVER)
I+

FUNCTION
Demonstrate the use of the ENABLE function to do
error recovery by implementing a simple hierarchical
integer calculator that will use enable routines and
the UNWIND feature to get out of any nested routines
and prepare to parse/calculate the next expression.
ALLOWED SYNTAX
The standard binary functions (+,-,*,/) are supported,
as are parenthesized expressions. An equal sign signals
the end of the expression. Unary functions are, however,
not supported. All numbers and results are integers; no
real or floating point numbers are accepted.
Thus the following are legal expressions:
3*{(3+2)/2)=
6=

and the following are not:

EXIT CONDITIONS
A carriage return, CTRL/C, or a CTRL/Y terminates the
program.
!-

BEGIN
FORWARD ROUTINE
CALC_DRIVER,
MAIN : NOVALUE,
READEXPRESSION,
READTERM,
READFACTOR,
READNUMBER,
READCHAR : NOVALUE,
CATCH_ERRORS;

Unwinds to here on errors.
Establisher routine; results to terminal.
Handles addition and subtraction.
Handles multiplication and division.
Dispatches based on digit or"(".
Convert from ASCII digits to integer.
Reads characters from the terminal.
Handler routine for all signals.

BUILTIN
BICPSW,
BISPSW;

Clear bits in the PSW.
Set bits in the PSW.

LIBRARY I SYS$LIBRARY: STARLET I ;

BLISS-32 Code Examples

9-15

SWITCHES LIST (NOSOURCE, NOOBJECT);
REQUIRE 'SYS$LIBRARY:TUTIO.R32'; 8
REQUIRE 'CONDIT.R32'; 49
SWITCHES LIST (SOURCE, OBJECT);

LITERAL
END_OF_EXPRESSION = Y.C'=',
CR = Y.O I 15 I •
TRUE = 1;
LITERAL 8
INVALID_EXPRESSION =
MISSING_RIGHT_PAREN =
ILLEGAL_CHARACTER =
OWN
CURCHAR : BYTE;

STS$VALUE (CODE= 1),
STS$VALUE (CODE= 2),
STS$VALUE (CODE= 3);

MACRO
IN_DIGITS = .CURCHAR GEQ 1.C'O' AND .CURCHAR LEQ 1.C'9' 1.,
IN_ADDING_OPS = .CURCHAR EQL 1.C'+' OR .CURCHAR EQL 1.C'-' Y..
IN_MUL_OPS = .CURCHAR EQL 1.C'*' OR .CURCHAR EQL 1.C'/' 1.;

STARLET is required for the PSL interrupt vector masks and to process
system trap values.
8 TUTIO contains the TTY__xxx routines.
49 CONDIT is required to provide the condition handling macros.
0 The LITERALS are user defined signal codes.
8 CURCHAR is the current character being acted upon.

9.2.2

Routine CALC_DRIVER
ROUTINE CALC_DRIVER =
!+

FUNCTION
Prime the pump by reading in the first character.
Provide an enclosing routine that will be returned
to as the handler routine CATCH_ERRORS unwinds ..
INPUTS
NONE.
OUTPUTS
NONE.

9-16

BLISS-32 Code Examples

IMPLICIT INPUTS
CURCHAR -

The current character being parsed.

IMPLICIT OUTPUTS
NONE.
ROUTINE VALUE
SS$_NORMAL
!-

BEGIN 0
TTY_PUT_QUO ('CALC: A hierarchical calculator.');
TTY_PUT_CRLF ();
TTY_PUT_QUO ('Enter expression and terminate with');
TTY_PUT_CRLF ();
TTY_PUT_QUO (' equal sign(=) or carriage return.');
TTY_PUT_CRLF ();
TTY_PUT_QUO ('An empty line exits the program.');
TTY_PUT_CRLF (); TTY_PUT_CRLF ();
TTY_PUT_QUO ('CALC> ');
READCHAR ();
WHILE .CURCHAR NEQ END_OF_EXPRESSION DO
BEGIN
MAIN ();
TTY_PUT_QUO ('CALC> ');
READCHAR ()
END;
RETURN SS$_NORMAL
END;

0 This code provides the user interface to the program and calls the
READCHAR routine for character input.
fJ SS$-NORMAL returns normal status to the monitor.

BLISS-32 Code Examples

9-17

9.2.3 Routine IUIAIN
ROUTINE MAIN

NOVALUE =

FUNCTION
The main driver routine for actual expression
parsing, prints the value on the terminal if
a successful calculation takes place and sets
up the condition handler.

INPUTS
NONE.
OUTPUTS
NONE.
IMPLICIT INPUTS
CURCHAR -

The current character being parsed.

IMPLICIT OUTPUTS
NONE.
ROUTINE VALUE
NONE
BEGIN
LOCAL
RESULT;
ENABLE
CATCH_ERRORS;

RESULT= READEXPRESSION ();
IF .CURCHAR EQL END_OF_EXPRESSION
@
BEGIN
TTY_PUT_QUO ('RESULT: ');
TTY_PUT_INTEGER (.RESULT, 10, 1);
TTY _PUT_CRLF ()
END
ELSE
SIGNAL (INVALID_EXPRESSION)

THEN

END;

0 ENABLE the CATCH-ERRORS routine to handle all errors.
9-18

BLISS-32 Code Examples

This code displays the result of the calculation on the screen.

9.2.4 Routine READEXPRESSION
ROUTINE READEXPRESSION =
!+

FUNCTION
Do the addition and subtraction Terms. The bit in
the Program Status Longword (that allows the user
to get control during integer overflow) is set before
the actual addition and cleared immediately after;
if overflow occurs here, the program knows what to do
about it.

INPUTS
NONE.
OUTPUTS
NONE.
IMPLICIT INPUTS
CURCHAR -

The current character being parsed.

IMPLICIT OUTPUTS
NONE.
ROUTINE VALUE
The result of an addition to or subtraction from
the current value of the expression.
!-

BEGIN
LOCAL
EXPRVALUE;
EXPRVALUE = READTERM ();
WHILE IN_ADDING_OPS DO
BEGIN
LOCAL
ADDOP;
ADDOP = .CURCHAR;
READCHAR ();
BISPSW CXREF (PSL$M_IV));

t»

BLISS-32 Code Examples

9-19

IF .ADDOP EQL Y.C'+'
THEN
EXPRVALUE = .EXPRVALUE + READTERM ()
ELSE
EXPRVALUE = .EXPRVALUE - READTERM () ;
BICPSW CY.REF (PSL$M_IV)) f.)
END;
.EXPRVALUE
END;

Tum on integer over.flow.
f.) Tum off integer over.flow.

9.2.5 Routine READTERM
ROUTINE READTERM =
I+

FUNCTION
Do multiplication and division. Turn user control of
overflow on and off as required. Division by zero is
detected by the hardware. The enable mechanism is
called and routine CATCH_ERRORS (the handler routine
for all errors) takes control. The proper message is
displayed and unwinding occurs back to the outermost
routine (CALC_DRIVER).
INPUTS
NONE.
OUTPUTS
NONE.
IMPLICIT INPUTS
CURCHAR -

The current character being parsed.

IMPLICIT OUTPUTS
NONE.
ROUTINE VALUE
Value of the expression calculated through
multiplication or division.
!-

9-20 BLISS-32 Code Examples

BEGIN
LOCAL
TERM_VALUE;
TERM_VALUE = READFACTOR ();
WHILE IN_MUL_OPS DO
BEGIN
LOCAL
MULOP : BYTE;
MULOP = .CURCHAR;
READCHAR ();
IF .MULOP EQL Y.C'*'
THEN
BEGIN
BISPSW CY.REF (PSL$M_IV));
TERM_VALUE = .TERM_VALUE * READFACTOR ();
BICPSW CY.REF (PSL$M_IV))
END
ELSE
TERM_VALUE = .TERM_VALUE I READFACTOR ()
END;
.TERM_VALUE
END;

9.2.8

Routine READFACTOR
ROUTINE READFACTOR =
!+
! FUNCTION

If the current character is an ASCII representation
of a digit, then call READNUMBER to get the· value
of the number. If the character is a"(", call
READEXPRESSION and return the result (The value of
the parenthesized expression).
INPUTS
NONE.
OUTPUTS
NONE.
IMPLICIT INPUTS
CURCHAR -

The current character being parsed.

BLISS-32 Code Examples

9-21

IMPLICIT OUTPUTS
NONE.
ROUTINE VALUE
Value of a number or a parenthesized expression.
!-

BEGIN
SELECTONE .CURCHAR OF
. SET
[%C'0' TO Y.C'9']:
RETURN READNUMBER (); 0
[%C' ( ']:
BEGIN f)
LOCAL
FACTOR_VALUE;
READCHAR ();
FACTOR_VALUE = READEXPRESSION (); 8
IF .CURCHAR EQL Y.C')'
THEN

BEGIN
READCHAR ();
RETURN .FACTOR_VALUE
END
ELSE C)
SIGNAL (MISSING_RIGHT_PAREN)
END;
[OTHERWISE] :
SIGNAL (illegal_character) 0
TES
END;

At this point the routine is parsing a number.
f) The number is a parenthesized expression.
8 Determine the value of the enclosed expression.
0 Determine if the expression is legal.
C) Determine if the expression has matching parenthesis.
0 Issue a message if something unexpected has been entered.

9-22 BLISS-32 Code Examples

9.2.7

Routine READNUMBER
ROUTINE READNUMBER =

•+

FUNCTION
Convert a string of ASCII digits to an integer number.
INPUTS
NONE.
OUTPUTS
NONE.
IMPLICIT INPUTS
CURCHAR -

The current character being parsed.

IMPLICIT OUTPUTS
NONE.
ROUTINE VALUE
Integer value of a string of ASCII digits.

BEGIN
LOCAL
NUM_VALUE : initialCO);
WHILE IN_DIGITS DO
BEGIN 0
LOCAL
DIGIT : BYTE;
DIGIT= .CURCHAR - Y.C'O';
BISPSW CY.REF CPSL$M_IV)); f)
NUM_VALUE = .NUM_VALUE * 10 + .DIGIT;
BICPSW CY.REF CPSL$M_IV));
READCHAR C)
END;
.NUM_VALUE
END;

Convert a string of ASCII digits to an integer number.
f) Check for too big a number.

BLISS-32 Code Examples

9-23

9.2.8

Routine READCHAR
ROUTINE READCHAR

NOVALUE =

!+
! FUNCTION

Read input from terminal until a non-blank character is
found. If a carriage return is found, call that an
end-of-expression.

INPUTS
NONE.
OUTPUTS
NONE.
IMPLICIT INPUTS
NONE.
IMPLICIT OUTPUTS
CURCHAR -

The current character to be parsed.

ROUTINE VALUE
NONE.
!-

DO
BEGIN
CURCHAR = TTY_GET_CHAR ();
IF .CURCHAR EQL CR
THEN

CURCHAR = END_OF_EXPRESSION
END
UNTIL .CURCHAR NEQ Y.C' '; fJ

0
8

End of line is also END_OF_EXPRESSION.
Loop until a nonblank character is encountered.

9-24 BLISS-32 Code Examples

9.2.9

Routine CATCH _ERRORS
ROUTINE CATCH_ERRORS (sig: REF VECTOR, mech, enab)
!+

FUNCTION
This is the condition handler for all expected errors.
Division by zero is detected by the hardware and if the
program has control (via the proper bit set in the PSL),
Integer Overflow is also detected. Otherwise, the program
traps out without enabling condition handling. Explicit
SIGNAL calls occur for all other detected conditions and
an appropriate message is displayed on the terminal.
After the user has been notified, an UNWIND is signalled.
The establisher routine is the main driver; returning
to its caller sets up the parsing for a completely
new expression.
The rationale for having all detected errors unwind is
that routines can be very busy calling each other, and
"fixing things up" on the fly is .unreasonable. Also,
once an error occurs, the value of the expression that
caused the error is worthless; thus, continued input for
the expression is refused and the program prepares for
the next expression.
INPUTS
SIG MECH -

Signal vector
Mechanism vector

ENBL -

Enable vector

OUTPUTS
NONE.
IMPLICIT INPUTS
NONE.
IMPLICIT'OUTPUTS
NONE.

BLISS-32 Code Examples

9-25

ROUTINE VALUE
NONE.
!-

BEGIN
BIND
COND = SIG [1] : CONDITION_VALUE;
SELECTONE TRUE OF 0
SET
[STS$MATCH (.COND, INVALID_EXPRESSION)]:
TTY_PUT_QUO ('
INVALID EXPRESSION');
[STS$MATCH (.COND, MISSING_RIGHT_PAREN)]:
TTY_PUT_QUO ('
Missing a right parenthesis');
[STS$MATCH (.COND, ILLEGAL_CHARACTER)]:
TTY_PUT_QUO (' ., Parsed an illegal character');
[STS$MATCH (.COND, SS$_INTDIV)]:
TTY_PUT_QUO ('
Attempted division by zero');
[STS$MATCH (.COND, SS$_INTOVF)]:
TTY_PUT_QUO ('
Integer overflow');
[OTHERWISE] : @
RETURN 0
TES;
TTY_PUT_QUO (';calculation stopped.');
TTY_PUT_CRLF ();
SETUNWIND () ;

o e

END;
END ELUDOM

0
8

Determine action to be taken based on the type of error encountered.
Error is possibly unexpected or an UNWIND error; in either case do
nothing.
0 Get out of the recursion and prepare to parse the next expression.
G Request normal UNWIND.

9-26 BLISS-32 Code Examples

Appendix A

Summary of Command Syntax
This appendix summarizes BLISS command syntax, qualifier defaults, and
abbreviations.

A. 1 Command-Line Syntax
compilation-request

$ BLISS [/qualifier ... ] input-spec, ...

input-spec

file-spec[+ ... ] [/qualifier ... ]

qualifier

check qualifier
general qualifiers
machine-code-list qualifier
optimization qualifier
output qualifiers
reference qualifier
source-list qualifier
terminal qualifier

Summary of Command Syntax

A-1

A.2 File Specification Summary
file-spec

{ node:: } { dev: } { (dir] } file { .type } { ;ver }

node

1- to 6-character alphanumeric network node name and optionally a 0- 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

1 to 39 alphanumeric characters, including underscore (- ),
hyphen ( - ), and dollar sign ( $)

type

0 to 39 alphanumeric characters preceded by a period

ver

Version number from 1 to 32767

A.3 Qualifier Syntax
check qualfier

/CHECK= { (check-value , ... ) }
check-value

check-value

FIELD
INITIAL
OPTIMIZE
REDECLARE

{

general qualifiers

machine-code-list
qualifier

A-2

Summary of Command Syntax

I NOFIELD
I NOINITIAL
I NOOPTIMIZE
I NOREDECLARE

/CODE
/DEBUG
/ERROR_LIMIT {:=value}
/TRACEBACK
/VARIANT {:value}

}

l/NOCODE

I /NODEBUG

/NOTRACEBACK

/M. ACHINE_CODE_LIST= { ( code-value ' · · · ) }
code-value

)

I NOOBJECT
I NOASSEMBLER
I NOBINARY
I NOCOMMENTARY
I NOSYMBOLIC
I NOUNIQUE_NAMES

code-value

OBJECT
ASSEMBLER
BINARY
COMMENTARY
SYMBOLIC
UNIQUE_NAMES

optimize qualifier

/OPTIMIZE= { ( o~ti1:11"ize-value , ... ) }
optimize-value

optimize-value

LEVEL : optimize-level
QUICK
SAFE
SPEED

{

I
I NOQUICK
I NOSAFE
I SPACE

optimize-level

{01112-13}

output qualifiers

/ ANALYSIS_DATA {=file-spec}
/LIST {=file-spec}
/LIBRARY {=file-spec}
/OBJECT {=file-spec}

{

}

I /NOANALYSIS-DATA
I /NOLIST
I /NOLIBRARY
I /NOOBJECT

source-list qualifier

/SOURCE_LIST= { ( source-value , ... ) }
source-value

source-value

EXP AND-MACROS
HEADER
LIBRARY
P AGE_SIZE : number of lines
REQUIRE
SOURCE
TRACE-MACROS

number of lines

{ 20 I 21 I 22 I . . . }

reference qualifier

{ /CROSS-REFERENCE { = {reference-value} } }

reference-value

{MULTIPLE I NOMULTIPLE }

}

I NOEXPAND__MACROS
INOHEADER
I NOLIBRARY
I
I NOREQUIRE
I NOSOURCE
INOTRACE_MACROS

Summary of Command Syntax

A-3

terminal qualifier
terminal-value

/TERMINAL= { (terminal-value, ... ) }
terminal-value
ERRORS
I NOERRORS
}
{ STATISTICS I NOSTATISTICS

A.4 Qualifier Defaults
The following qualifiers are assumed by default:
/CHECK=(FIELD,INITIAL,OPTIMIZE,NOREDECLARE)
/CODE
/ERROR_LIMIT=30
/LIST (in batch mode)
/MACHINE_CODE_LIST=(NOASSEMBLER,SYMBOLIC,BINARY,
OBJECT COMMENTARY,
NOUNIQUE_NAMES)
/NOANALYSIS_DATA
/NOCROSS-REFERENCE or /CROSS-REFERENCE(NOMULTIPLE)
/NODEBUG
/NO LIBRARY
/NOLIST (in interactive mode)
/OBJECT=input-file-name.OBJ
/OPTIMIZE=(NOQUICK,SP ACE,LEVEL:2,SAFE)
/SOURCE_LIST=(HEADER,PAGE_SIZE:58,NOLIBRARY,
NOREQUIRE, NOEXPAND-MACROS,
NOTRACE-MACROS,SOURCE)
/TERMINAL=(ERRORS,NOSTATISTICS)
/TRACEBACK
/VARIANT:O

A-4

Summary of Command Syntax

A.5 Abbreviations
The abbreviations for the positive forms of the qualifiers and qualifier
values are given below:
Qualifier

Value

Abbreviation

/ ANALYSJS_DATA

/CHECK

/CH
FIELD

INITIAL

OPTIMIZE

REDECLARE

/CODE

/CROSS-REFERENCE

/CR
MULTIPLE

/DEBUG

/ERROR_LIMIT

/LIBRARY

/LIB

/LIST

/LIS

/MACHINE-CODE_LIST

/M
ASSEMBLER

BINARY

COMMENTARY

OBJECT

SYMBOLIC

UNIQUE-NAMES

/OBJECT

/OB

/OPTIMIZE

/OP
LEVEL

QUICK

SAFE

Summary of Command Syntax

A-5

Qualifier

Value

Abbreviation

SPACE

SPA

SPEED

SPE

/SOURCE_LIST

/S
EXPAND_MACROS

HEADER

LIBRARY
PAGE_SIZE

L
p

REQUIRE

SOURCE

TRACE_MACROS

ERRORS

/TE
E

STATISTICS

/TERMINAL

/TRACEBACK

/TR

/VARIANT

For the negative form of a qualifier or value (where applicable), its
positive-form abbreviation can be prefixed by "NO".

A-6

Summary of Command Syntax

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 must be indented to the same level as the
BEGIN-END delimiters.
The format for a declaration is as follows:
declaration-keyword
declaration-item,

!comment

declaration-item;

!comment

where the declaration-keyword starts at the current indentation level and
each declaration-item is further indented one logical tab.
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 must appear on separate lines from
subparts, and subparts are indented one tab. For example, IF expressions
can be written in either of two formats:
IF test THEN consequence ELSE alternative;

or
IF test
THEN
consequence
ELSE
alternative;

Summary of Formatting Rules B-1

The examples used in Chapter 2 are indented correctly, although all
comments have been omitted in order to save space.

B-2

Summary of Formatting Rules

Appendix C

Module Template
This appendix contains a listing of the file MODULE.BU, 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 (Section C.1) appears first. It provides documentation explaining the module's function, use, and history.
The module's declarative part appears next (Section C.2). 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 (Section C.3), consisting of zero or more
routines, comes next. The template for a routine is in this section. Note
that a routine has three parts: a preface, a declarative part, and code.
Finally, every module has a closing part (Section C.4), which completes
the syntax of a module.
The module template can be used either as a checklist for module organization and content or as the starting point in creating a new module.
The file MODULE.BU is supplied as part of the BLISS support package,
on logical device SYS$LIBRARY.

Module Template C-1

C. 1 Module Preface
MODULE TEMPLATE (
!DENT = I

BEGIN
COPYRIGHT (C) 1982 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 OF ITS
SOFTWARE ON EQUIPMENT WHICH IS NOT SUPPLIED BY DIGITAL.
!++
! FACILITY:

ABSTRACT:
ENVIRONMENT:
AUTHOR:

, CREATION DATE:

MODIFIED BY:
, : VERSION
01

C-2

Module Template

C.2 Declarative Part of Module
!

TABLE OF CONTENTS:

FORWARD ROUTINE

INCLUDE FILES:

! MACROS:

! EQUATED SYMBOLS:
!
! OWN STORAGE:

! EXTERNAL REFERENCES:

EXTERNAL ROUTINE

Module Template c.,..J

C.3 Executable Part of Module
ROUTINE TEMP_EXAMPLE () :NOVALUE =
!++

! FUNCTIONAL DESCRIPTION:
FORMAL PARAMETERS:
NONE
IMPLICIT INPUTS:
NONE
IMPLICIT OUTPUTS:
NONE
ROUTINE VALUE:
COMPLETION CODES:
NONE
SIDE EFFECTS:
NONE
!--

BEGIN
LOCAL
END;

C-4 Module Template

!END OF TEMP_EXAMPLE

C.4 Closing Format
END
ELUDOM

!END OF MODULE

Module Template C-5

Appendix D

Implementation Limits
Each BLISS-32 compiler implementation has value limitations on the
use of certain language constructs or system interfaces. These values are
subject to change if experience indicates they are unsuitable.

D. 1 BLISS-32 Constructs
Certain BLISS-32 constructs have the following maximum limits on their
size and number:
Nested blocks containing declarations

Characters in a quoted string

1000

Actual parameters in a routine call

Structure formal parameters

Field components

Parameters of a FIELD attribute

128

Bytes initialized by a single PUT
(that is, the maximum byte count of a single PUT)

65,535

Length of a character sequence
(CH$ function argument)

65,535

Implementation Limits

0-1

D.2 System Interfaces
System interfaces have the following maximum limits:

D-2

Characters in an input source line

132

Simultaneously active (depth of nested)
REQUIRE files

Implementation Limits

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. Declarations must precede expressions within a
block.
User Action. Reinsert the declaration properly or create a new
block.

002

Superfluous operand preceding

<operator-name> n

Explanation. An excess or unnecessary left operand precedes
the operator named.
User Action. Remove the extra or unnecessary left operand.
Error Messages

E-1

003

BEGIN paired with right parenthesis

Explanation. A closed parenthesis has been encountered when
the compiler expected an END.
User Action. Provide the appropriate pairing or insert a missing
END keyword.
004

Missing operand preceding

<operator-name>

Explanation. Required left operand is missing from infix operator named.
User Action. Insert missing left operand.
005

Control expression must be parenthesized

Explanation. Parenthesis is required to achieve intended result.
User Action. Insert missing parenthesis.
006

Superfluous operand following

<operator-name> "

Explanation. An extra or unecessary right operand follows the
operator named.
User Action. Remove the excess or unecessary right operand.
007

Missing operand following

<operator-name>" B

Explanation. Required right operand is missing from operator
named.
User Action. Insert missing right operand.
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.

E-2

Error Messages

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.

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 in routine actual parameter
list
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. Insert commas, as necessary, and/or close parenthesis.

014

Missing FROM following CASE
Explanation. Case expression is incomplete.
User Action. Insert required keyword FROM.

015

Missing TO following FROM in CASE expression
Explanation. Case expression is incomplete.
User Action. Insert required keyword TO.

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.
Error Messages

E-3

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 expr~ssion

Explanation. Select line of select expression is incomplete.
User Action. Insert colon between select label expression's close
bracket and select action expression.
020

Missing semicolon or TES following a SELECT action

Explanation. Select line of select expression is incomplete.
User Action. Insert required semicolon or keyword TES following select action expression.
021

Address arithmetic involving REGISTER variable <variable~ame>

Explanation. An attempt has been made to use the value of a
register name in an expression.
User Action. Correct the expression.
022

Field reference used as an expression has no value

Explanation. The reference is invalid as a fetch or assignment
expression and cannot produce a value.
User Action. 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 commas or close bracket.
024

Value in field selector outside permitted range

Explanation. The value has exceeded the field size or machine
word boundaries of the dialect.
User Action. Correct the address, position, size, or sign expression value according to dialect restrictions.

E-4

Error Messages

025

Value of attribute outside permitted range

Explanation. The value used is larger than the legal range
permits, such as UNSIGNED(37).
User Action. 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 nonprinting ASCII characters
has been used (as other than data) in a BLISS module.
User Action. Only four nonprinting characters (blank, tab,
vertical tab, and form feed) can be used.
028

Illegal parameter in call to lexical function <lexical-functionname>

Explanation. A parameter used with the named lexical function
is invalid.
User Action. Check and correct parameter usage according to
the definition of the function.
029

Attribute illegal in this declaration

Explanation. Attributes are restricted in use to certain declarations.
User Action. 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. Remove the access formal from the structure size
expression.

Error Messages

E-5

031

Conflicting or multiple specified attributes
Explanation. Contradictory or superfluous attributes have been
used.
User Action. Check attribute usage in regard to specific definitions.

032

Two consecutive field selectors
Explanation. Irrational use of field selector portion of field
reference.
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 attribute
Explanation. An error has occurred in the coding of an attribute.
User Action. Correct the error using the appropriate syntax.

034

INITIAL value <integer> too large for field
Explanation. The integer value shown is too large for the
designated field.
User Action. Decrease the value or increase the allocation unit.

035

The <attribute-name> attribute contradicts corresponding
FORWARD declaration
Explanation. The attributes of a name in an own, 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 is larger
than the field specified by the storage attribute.
User Action. Check sign or bit count of range attribute.

E-6 Error Messages

03 7

Lower bound of a range exceeds upper bound
Explanation. The low bound value of the range of a case
expression must not exceed the high bound value.
User Action. Correct the low bound value.

038

Number of routine actual parameters exceeds implementation
limit of 64
Explanation. The number of input actual parameters for a
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 value has
been used in an expression.
User Action. Correct the expression.

040

LEAVE not within the block labelled by <label-name>
Explanation. The leave expression is not within the block of the
label named.
User Action. Insert the expression in the appropriate block.

041

Missing comma or right parenthesis in parameter list to lexical
function <lexical-function-name>
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 commas or close parenthesis.

042

Missing label name following LEAVE
Explanation. The leave expression is incomplete.
User Action. Insert the appropriate label name following the
keyword LEAVE.

Error Messages

E-7

043

Label <label-name> already labels another block
Explanation. The label name shown has been declared for
another labeled block.
User Action. Change the name of one block or the other.

044

EXITLOOP not within a loop
Explanation. An exit loop expression has been incorrectly used.
User Action. Insert the expression within the (innermost) loop
to be exited.

045

Missing structure name following REF
Explanation. The structure attribute using keyword REF is
incomplete.
User Action. Insert the missing structure name following the
keyword.

046

Register <register-number> cannot be reserved
Explanation. The register defined by the number shown is not
locally usable.
User Action. Specify another register.

047

Module prematurely ended by extra close bracket or missing
open bracket
Explanation. The number of close brackets in a module must
equal the number of open brackets.
User Action. Remove the extra right bracket or add the missing
left bracket.

048

Syntax error in module head
Explanation. The module head is incorrectly coded.
User Action. Correct the module name or the syntax of the
module switch list.

E-8

Error Messages

049

Invalid switch specified
Explanation. An invalid switches declaration has been used with
the dialect.
User Action. Correct the use of the switches declaration.

050

Name already declared in this block: <name>
Explanation. The name shown has been declared more than
once in the same block.
User Action. Remove. all but one of the declarations within the
block.

051

Syntax error in switch specification
Explanation. An error has occurred in the specification of the
module switches or switches declaration.
User Action. Correct 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. An illegal attribute has been used in the declaration.
User Action. Check the legality of the attributes used with the
declaration.

054

Name in attribute list not declared as a structure or linkage name:
<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.

Error Messages

E-9

055

Missing equal sign in BIND or LITERAL declaration
Explanation. The name and value of a literal, bind data, or bind
routine item must be separated by an equal sign.
User Action. Insert the missing equal sign.

056

Missing comma or semicolon following a declaration
Explanation. Each declaration in a list must be separated by a
comma, and the last must be followed by a semicolon.
User Action. Insert the missing commas or semicolon.

057

Value of structure size.:.expression for REGISTER must not exceed
4

Explanation. Structure size expression exceeds maximum allowed value.
User Action. Correct the value of the register structure size
expression.
058

Left parenthesis paired with END
Explanation. A pair of parentheses must be used to replace an
END pair.
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. Case expression is incomplete.
User Action. Insert required keyword SET.

061

Missing left bracket preceding a CASE- or SELECT-label
Explanation. Case or select expression is incomplete.
User Action. Insert missing open bracket.

E-1 0 Error Messages

062

MODULE declaration inside module body
Explanation. A module body cannot contain a module declaration.
User Action. Correct the module code.

063

More than one CASE-label matching the same CASE-index
Explanation. Only one case label value can match a given case
index value.
User Action. Correct either the label or index value.

064

Value in CASE-label outside the range given by FROM and TO
Explanation. Value of case label is not within the range specified.
User Action. Correct the case label or range values.

065

Missing equal sign in ROUTINE declaration
Explanation. An equal sign must precede the routine body in a
routine declaration.
User Action. 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 usually insert an appropriate
operator and continue (if not correct the expression).

067

Missing comma or right bracket following a CASE- or SELECTlabel
Explanation. Each label in a list, for a case or select expression,
must be separated by a comma and the list ended with a close
bracket.
User Action. Insert missing commas 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.

Error Messages

E-11

069

Size-expression required in STRUCTURE declaration when
storage is 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. Number of access formal parameters exceeds
maximum allowed.
User Action. Reduce the number of parameters.

071

Missing comma or closing bracket in formal parameter list for
<routine-or-macro-name>
Explanation. Each formal parameter in a list must be separated
by a comma and the list ended with a right bracket.
User Action. Insert missing commas 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 structure size
expression or structure body or the macro body.
User Action. Insert the missing equal sign.

074

Missing actual parameter list for macro <macro-name>
Explanation. The actual parameters are missing from the macro
call associated with the macro named.
User Action. Insert actual parameters to correspond with the
formal name parameters from the declaration.

E-12

Error Messages

075

Missing closing bracket or unbalanced brackets in actual parameter list for macro <macro-name>
Explanation. There must be a right bracket for every left bracket
used in the actual parameter list.
User Action. Correct the pairing of the open and close brackets.

076

Extra actual parameters for structure <name> referencing data
segment . <name>
Explanation. Superfluous access actual parameters in structure
reference for structure and data segment named.
User Action. Correct the structure reference code.

077

Missing colon following right bracket in CASE expression
Explanation. Case expression is incomplete.
User Action. Insert colon following close bracket.

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 name or correct declaration in an appropriate manner.

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. Insert missing commas or close bracket.

080

Illegal characters in quoted string parameter of <lexicalfunction-name>
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 for all
characters with %CH~R inserted before illegal ones.

Error Messages

E-13

081

Quoted string not terminated before end of line
Explanation. A quoted string character sequence extends over a
line.
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 PUT, INITIAL
or PRESET item
Explanation. Each item in the list must be separated by a
comma and the list must be ended with close parenthesis.
User Action. Insert any missing comma 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.

084

Expression must be a link-time constant
Explanation. The compiler requires a link time constant expression, 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 PUT
Explanation. The numeric value of a string literal exceeds the
word length for the dialect.
User Action. Reduce the length of the string or use a PUT
declaration.

086

Name declared FORWARD is not defined: <name>
Explanation. A name declared in a forward declaration must
also be declared by an own or global declaration within the same
block.
User Action. Make the proper declarations.

E-14

Error Messages

087

Size of initial value ( <integer-value> ) exceeds declared size
( <integer-value> )
Explanation. The initial value shown is greater than the memory
space reserved for it.
User Action. Decrease the initial value and/or increase the
declared size value.

088

Missing quoted string following <lexical-function-name>
Explanation. The lexical function shown requires a quoted
string.
User Action. Insert the required quoted string.

089

Syntax error in PSECT declaration
Explanation. The psect declaration is improperly coded.
User Action. Check and correct 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 semicolons or the keyword TES.

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 TO have no
matching CASE-label
Explanation. The compiler cannot match all of the low to high
bound values with the case label values given.
User Action. Evaluate the case label values relative to those of
the low to high bound values.

Error Messages

E-15

093

No structure attribute for variable <name> in structure reference
Explanation. The variable name shown has been declared, but
the structure attribute is missing.
User Action. Insert the appropriate structure attribute (structure
name and allocation actuals) for the declaration of 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. Define the routine with the appropriate declaration.

095

%REF built-in function must be used only as a routine actual
parameter
Explanation. Built-in function has been used improperly.
User Action. Correct the use of the function.

096

Module body contains executable expression or non-link-time
constant declaration
Explanation. An executable expression (such as .x) or a nonlink-time constant expression declaration should not appear
within the outermost level of the module body.
User Action. Correct the use of expressions and declarations
within the outermost level of the module body.

097

Length of quoted string parameter of <lexical-function> must
not exceed <integer-value>
Explanation. The quoted string of the function shown must not
contain more characters than the value shown.
User Action. Correct the length of the parameter.

E-16

Error Messages

098

Cannot satisfy REGISTER declarations
Explanation. Too many registers (in linkage, globals, built-in or
predeclared functions) are simultaneously active.
User Action. Redistribute explicit register usage to prevent
overlaps in time.

099

Simultaneously allocated two quantities to Register <integervalue >
Explanation. Two conflicting data segments have been allocated
at the same time for the register shown.
User Action. 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 an 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.

Error Messages

E-17

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 yet implemented in <language> :
<feature-keyword-name>
Explanation. Language feature shown is not yet supported in
this dialect.
User Action. Remove the language feature 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 attributes.

108

Allocation-unit must not follow INITIAL attribute
Explanation. The allocation unit attribute must precede the
initial attribute in a declaration.
User Action. Rearrange the order of the attributes.

109

Missing quoted string following REQUIRE or LIBRARY
Explanation. Quoted file name not found in a require or library
declaration.
User Action. Insert and/ or quote file name in declaration.

E-18

Error Messages

110

Open failure for REQUIRE or LIBRARY file
Explanation. The file specified in a require or library declaration
cannot be accessed by the compiler.
User Action. Check validity of file name or make file available
to compiler.

111

Comment not terminated before end of <source-file-name>
Explanation. An embedded 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> not terminated before end
of program
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 parenthesis or END following a subexpression of a block
Explanation. Each subexpression must be concluded by a semicolon and the block must be concluded with a close parenthesis
or an END.
User Action. Insert the appropriate terminators.

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 labeled expression must be contained within a
BEGIN-END or parenthesis pair.
User Action. Enclose the expressions within a block.

Error Messages

E-19

116

Value of structure size-expression must be a compile-time constant
Explanation. The size expression must meet the criteria for a
compile-time constant expression.
User Action. Evaluate and correct the size expression.

117

Value of structure size-expression must not be negative
Explanation. A structure size-expression must not indicate a
negative value.
User Action. Evaluate and correct the size expression value.

118

Missing left parenthesis in PUT or INITIAL attribute
Explanation. A PUT item or an initial attribute must be enclosed
in parentheses.
User Action. Insert the missing open parenthesis.

119

ALWAYS illegal in a SELECTONE expression
Explanation. The select label ALWAYS cannot be used with a
SELECTONE, SELECTONU, or SELECTONEA expression.
User Action. Correct the select expression.

120

Case range spanned by FROM and TO exceeds implementation
limit of 512
Explanation. Range of case expression cannot exceed the high
bound limit of 512.
User Action. 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 the percent sign for
the macro declaration.

E-20

Error Messages

122

Recursive invocation of non-recursive macro <macro-name>
Explanation. Only a conditional macro with one or more formal
names can be used recursively.
User Action. Correct the definition of the macro named.

123

Recursive invocation of structure <structure-name>
Explanation. A structure cannot invoke itself directly or indirectly.
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 been nested or a block
contains more lines than are allowed.
User Action. Decrease the number of nested expressions or the
number of lines in the block.

125

Operand preceding left bracket in structure reference is not a
variable name
Explanation. The operand preceding the access actual parameter
must be a variable name.
User Action. Evaluate and correct the operand.

126

Value of PUT replicator must not be negative
Explanation. The REP replicator must be a compile-time constant expression that does not indicate a negative value.
User Action. 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 outermost level of the routine, or check for the
exclusion of the END keyword from the routine.

Error Messages

E-21

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 its declaration.

129

Missing comma or right parenthesis in actual parameter list for
<routine-or-macro-name>
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 commas or close parenthesis in
the call to the routine or macro named.

130

Omitted actual parameter in call to <keyword-macro-name>
has no default value
Explanation. In reference call to keyword macro named, no
default value exists for the omitted actual parameter.
User Action. Provide an appropriate value for the omitted actual
parameter.

131

Extra actual parameters in call to <builtin-function-name>
Explanation. The number of actual parameters used in call
to a built-in function must not exceed the number of formal
parameters used in the built-in routine.
User Action. Correct actual parameter usage in call to built-in
function named.

132

Translation table entries in call to CH$TRANSTABLE must be
compile-time constants
Explanation. The translation items do not meet the criteria for
compile-time constant expressions.
User Action. Evaluate and correct the translation items in the
call.

E-22 Error Messages

133

Allocation unit (other than BYTE) in call to CH$TRANSTABLE
Explanation. Character positions in a translation table are
restricted to the length of a byte.
User Action. If an allocation unit attribute is necessary, insert
the keyword BYTE.

134

Length of table produced by CH$TRANSTABLE (<integervalue>) not an even number between 0 and 256
Explanation. The number of translation items used in the call
must be even.
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 shorter than sum of source lengths in
CH$COPY
Explanation. The sum of the source length parameters
(snl+sn2+ ... ) must not be greater than the value of the destination parameter (dn).
User Action. Increase the value of the destination parameter.

136

Character-size parameter of <character-function-name> must
be equal to 8
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.

137

Built-in routine has no value
Explanation. A machine specific function that cannot produce a
value has been used in a context where a value is required.
User Action. Evaluate the required use of the built-in function
and correct the coding.

Error Messages

E-23

138

Missing equal sign in GLOBAL REGISTER declaration
Explanation. The global register declaration is incomplete.
User Action. Insert the missing equal sign following the register
name.

139

Illegal use of %REF built-in function as actual parameter
<integer-value> of call to <routine-name>
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 built-in 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
call to routine <routine-name>
Explanation. An undotted register name has been used as an
actual parameter for the routine call shown
User Action. Provide a legal register name.

141

Routine <routine-name> has no value
Explanation. The mechanism for returning a value is suppressed.
User Action. Remove the novalue attribute from the routine
named.

142

Missing quoted string following CODECOMMENT
Explanation. A quoted string is required for each comment.
User Action. Enclose the affected comments 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 commas and/ or the colon.

E-24

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 zero
through 3.
User Action. Replace the switch value shown with an appropriate value.

146

ENABLE declaration must be in outermost block of a routine
Explanation. The enable declaration must reside in the outermost level of the establisher routine.
User Action. Correct the placement of the enable declaration.

147

More than one ENABLE declaration in a routine
Explanation. An establisher routine must not enable more than
one handler routine.
User Action. 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. Provide an appropriate routine name for the
declaration.

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.

Error Messages E-25

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 a volatile attribute for the actual parameter
named.
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. Insert the missing commas and/or close parenthesis.
152

LANGUAGE switch specification excludes <language-name>

Explanation. The language name shown is missing from the
language list in a switch declaration.
User Action. Insert the missing language name.
153

Missing OF following REP

Explanation. The replicator construct for the expression is
incomplete.
User Action. Insert the missing keyword OF following the
replicator.
154

Incorrect number of parameters in call to lexical function
<lexical-function-name>

Explanation. A lexical function must conform to its syntactic
definition.
User Action. Evaluate and correct parameter usage for lexical
function named.

E-26

Error Messages

155

Number of parameters of ENTRY switch exceeds implementation
limit of 128
Explanation. The module switch has too many parameters.
User Action. Reduce the number of parameters used in the
ENTRY switch.

156

Unknown name in BUILTIN declaration: <name>
Explanation. Only a name predefined for BLISS can be declared
as built-in.
User Action. Correct the name shown or delete it or use another
form of declaration for it.

157

Conditional out of sequence: <name>
Explanation. The keyword named is improperly sequenced in
the lexical conditional.
User Action. Evaluate and correct the order in which the keywords appear in the expression.

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 158, %INFORM: 'user text specified by function'

159

Conditional not terminated before end of <macro or source-filename>
Explanation. Lexical conditional is not properly terminated in
the file named.
User Action. Insert the missing termination keyword %FI.

Error Messages

E-27

160

Missing formal parameter or equal sign in call to keyword macro
<macro-name>

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. Insert the missing formal name or the missing
equal sign.
161

Formal parameter <parameter-name> multiply specified in call
to keyword macro <macro-name>

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 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> of call to routine
<routine-name> is illegal

Explanation. An invalid actual parameter has been used in a call
to the routine named.
User Action. Evaluate and correct the use of actual parameter
named in the call.
164

Language feature to be removed: <feature>

Explanation. Compiler reports that the use of feature named is
discontinued.
User Action. Evaluate and correct module.
165

Language feature not present in <language> : <feature>

Explanation. The compiler reports that the feature named is not
available to the dialect named.
User Action. Remove the feature from the module switch for
the dialect named.

E-28

Error Messages

166

Name declared STACK is not properly defined
Explanation. The name used as a stack data segment has not
been declared.
User Action. Correct or define name with stacklocal declaration.

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 fetch or assignment expression to an
invalid data segment.
User Action. Correct range attribute for data or structure declaration.

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

171

Missing comma on right bracket in FIELD declaration
Explanation. Comma must appear after right bracket of each
field definition (except the last) in list.
User Action. Insert missing commas.

172

Missing left bracket in FIELD declaration
Explanation. A left bracket must appear before each list of field
components in a list of field definitions. ·
User Action. Insert missing left brackets.

Error Messages

E-29

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 TES.
User Action. Insert missing commas 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 brackets.

175

Number of field components exceeds implementation limit of 32
Explanation. The number of components in a field definition
exceeds the limits allowed for a structure.
User Action. Decrease the number of components or create
separate structures.

176

Field name <name> invalid in structure reference to variable
<variable-name>
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 a field attribute; the name used must be identified by a field declaration
as a field or field set name.
User Action. Replace parameter with a declared field or field set
name.

178

Number of parameters of FIELD attribute exceeds implementation limit of 128
Explanation. Excessive number of field names have been specified in field attribute.
User Action. Decrease the number of field names or declare a
field set for the number in excess.

E-30

Error Messages

179

Missing equal sign in LINKAGE declaration
Explanation. An equal sign must appear between a linkage
name and a linkage type.
User Action. Insert the missing equal sign.

180

Invalid linkage type specified
Explanation. The linkage type specified for the dialect is illegal.
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 <register-number> in
LINKAGE declaration
Explanation. The register shown has been specified more than
once in the declaration.
User Action. Evaluate and correct register specifications.

183

Invalid parameter location specified
Explanation. The parameter location specified is illegal.
User Action. Check the legal uses of parameter locations and
correct the specifications.

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. Insert the missing commas and/or the close
parenthesis.

185

Invalid linkage modifier in LINKAGE declaration
·Explanation. An illegal modifier has been used as a linkage
option.
User Action. Check and correct the use of linkage option
modifiers for the dialect.

Error Messages

E-31

186

Missing left parenthesis in LINKAGE declaration
Explanation. A parameter location list must be preceded by an
open parenthesis.
User Action. Insert the missing open parenthesis.

187

Missing global register name in LINKAGE declaration
Explanation. A global linkage option has been used and the
global register name has not been specified.
User Action. Insert the missing global register name.

188

No match in linkage <name> for EXTERNAL REGISTER
variable <name>
Explanation. The register named in the global linkage option
must be the same as the register named in the associated external
register declaration.
User Action. Use the same register name in both the routine
and its linkage declaration.

189

Global register <name> specified by linkage <linkagename > not declared to call
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 the calling routine
with an external register declaration.

190

WORD or Radix-SO item number <integer> allocated at odd
byte boundary
Explanation. Data structure is improperly allocated.
User Action. Correct data allocation to place WORD or RADSO_
11 value shown at a word boundary.

191

Multiple GLOBAL declaration of name: <name>
Explanation. The global name shown has been declared more
than once in the same module.
User Action. Delete all the extra appearances of the global
declaration.

E-32 Error Messages

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.

193

<declaration-name> declaration not available when
OBJECT(ABSOLUTE) in effect
Explanation. This message is reserved for BLISS-16 future
expansion.
User Action. No action is required.

194

Library source module must contain only declarations
Explanation. Executable expressions must not appear in a library
source file.
User Action. Remove all but the declarations from the library
source file.

195

LIBRARY file has invalid format
Explanation. The internal formatting of the file is incorrect.
User Action. The specified file is probably not a precompiled
library file; change the file specification and recompile. If the
problem persists, submit an SPR.

196

LIBRARY file must be regenerated using current compiler release
Explanation. A library source file must be precompiled again
using the latest version of the compiler.
User Action. Use the latest version of the compiler to regenerate
the library file.

Error Messages

E-33

197

LIBRARY file must be generated using <language>
Explanation. The library file must be precompiled by the compiler associated with the dialect named.
User Action. Generate the library file with the compiler associated with the dialect named.

198

LIBRARY file contains internal consistency error
Explanation. A library file has been referenced that has been
precompiled with errors.
User Action. Recompile the library source file with a /LIBRARY
qualifier, and if the problem persists, submit an SPR.

199

Warnings issued during LIBRARY precompilation: <number>
Explanation. The number shown is the number of warnings
issued during the precompilation of the file.
User Action. Evaluate and correct all warnings and recompile.

200

Illegal declaration type in library source module
Explanation. Only certain types of declarations can be used in a
library source file.
User Action. Remove the invalid declarations from the library
source file and regenerate the file.

201

Illegal occurrence of bound name <name> in library source
module
Explanation. Bound names cannot be inserted in library source
file.
User Action. Remove the declaration for the name shown from
the file and regenerate the file.

202

Number of parameters of ARGTYPE linkage attribute modifier
exceeds implementation limit of 128
Explanation. Excessive number of parameters used with built-in
linkage function ARGTYPE.
User Action. Reduce the parameters to an acceptable number.

E-34

Error Messages

203

<name> linkage modifier not available with this linkage type
Explanation. The linkage option named cannot be used with the
linkage type specified.
User Action. 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 built-in 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 built-in function is unavailable for use due to a NOTUSED linkage modifier.
User Action. Delete or change the modifier in the associated
linkage declaration to allow the register to be used.

207

NOTUSED linkage modifier of caller is not a subset of that of
called routine
Explanation. The linkage type and linkage option of the caller
routine is incompatible with that of the called routine.
User Action. Evaluate and correct the linkage declarations.

208

Called routine does not preserve register declared NOTUSED by
caller
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.

Error Messages

E-35

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
oooa(oooooo)-o; where "o" is an octal digit and "a" is an alphabetic character.
User Action. Correct the string in regard to the version number
format.

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 use the data segment
named without first initializing it.
User Action. Insert an initial attribute in the data segment
declaration, or assign a value to the segment before fetching
from it.

212

Null expression appears in value-required context
Explanation. A null expression has been used where a value is
required.
User Action. Evaluate and provide a value for the expression.

E-36 · Error Messages

213

Expressions 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 the return or
exit expression.
214

Language feature not transportable

Explanation. The feature specified for the dialects 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 dialects defined by the language switch.
User Action. Evaluate the feature named and take appropriate
action.
216

Language feature not transportable: <keyword>

Explanation. The feature specified by the keyword shown is not
transportable to the dialects defined by the language switch.
User Action. Evaluate the feature shown and take appropriate
action.
217

GLOBAL or EXTERNAL name not unique in 6 characters:
<name>

Explanation. In BLISS-16 and BLISS-36, at least six characters
in a global or external name must be unique.
User Action. Evaluate and correct the global or external name.

Error Messages

E-37

218

Implicit declaration of BUILTIN <linkage-name> to be withdrawn
Explanation. The compiler implicitly declares the function
named as built-in when a FORTRAN linkage routine is being
compiled.
User Action. Add an explicit built-in declaration within the
proper scope.

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 block or delete the
entire block form.

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 and correct the preset attribute.

221

Missing left square-bracket in PRESET attribute
Explanation. Each preset item in a preset attribute must be
preceded by an open bracket.
User Action. Insert the missing open bracket before the preset
item.

222

Source line too long. Truncated to 132 characters.
Explanation. A line in the source file exceeds the implementation limit of 132 characters.
User Action. Decrease the size of the source line.

E-38 Error Messages

223

Name used in routine-call not declared as ROUTINE: <routinename>
Explanation. The routine designator used in a routine call must
yield a value declared as a routine name in a routine declaration.
User Action. Ensure that the name used in the routine call is
declared in a routine declaration.

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 to
invoke the interrupt 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 exceeds the
compatible and transportable range of the dialect.
User Action. Provide a linkage name that is within the compatible and transportable range of the dialect..

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 the offset and
field size parameters.

228

Builtin machop <name> has no value
Explanation. The instruction named did not produce a value
when executed by the machine specific function MACH OP.
User Action. Select a machine instruction that will produce a
value when ,executed.
Error Messages

E-39

229

Parameter <parameter-name> of builtin <name> has value
outside the range
Explanation. The parameter named for the built-in function
named indicates a value that exceeds the specified range.
User Action. Decrease the value of the parameter named to
conform with the specifications of the function named.

230

Parameter <parameter-name> of builtin <name> must be a
link-time constant expression
Explanation. The parameter named for the built-in function
named is an invalid expression.
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. The CLEARSTACK linkage option is illegal with
this dialect.
User Action. Delete the CLEARSTACK modifier from the linkage declaration.

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 OTSLINKAGE switch which specifies the. use of a
nonstandard file and linkage.
User Action. Evaluate and correct the coding for OTS.

233

OTS linkage <name> not declared before first routine declaration
Explanation. The linkage name specified by the OTSLINKAGE
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.

E-40 Error Messages

234

OTS linkage <name> may not use global registers or pass
parameters by register
Explanation. The linkage name specified by the OTSLINKAGE
switch must not specify register or global register parameter
locations.
User Action. Evaluate and correct the use of the parameter
locations in the linkage declaration named.

235

OTS linkage <name> not defined before it's used
Explanation. The linkage name shown has not been declared
prior to its use in an OTSLINKAGE switch.
User Action. Declare the linkage name shown with a linkage
declaration.

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 PUT expression in the module.

23 7

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

239

String exceeding implementation limits (<number> characters)
was truncated
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.

Error Messages

E-41

240

<reserved-word> declaration is illegal in STRUCTURE declaration
Explanation. The declaration defined by the reserved word
shown (such as OWN) is illegal in a structure declaration.
User Action. Remove the illegal declaration.

242

Output formal parameter <name> in routine declaration was
not described in linkage
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 the
output formal parameter named in the routine declaration.

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 the output
actual parameter specified in the caller routine.

244

Name declared UNDECLARE is not defined: <name>
Explanation. An undeclare declaration has been used with a
name that has not been declared.
User Action. Declare the name shown.

246

FORWARD declaration of <name> cannot be satisfied by
BIND declaration
Explanation. A name declared as FORWARD must be defined as
a ROUTINE, OWN, or GLOBAL name.
User Action. Evaluate and correct the use of the specified name
on the FORWARD declaration.

E-42

Error Messages

24 7

Character size parameter of <name> must be equal to a
compile-time constant in the range 1 to 36

Explanation. The character size value of the named character
function is either outside of the permissible range or not a
compile-time constant.
User Action. Provide a compile-time constant within the permissible range.
248

<number> is an illegal character size for a global byte pointer.
A local byte pointer will be generated

Explanation. A program with extended addressing was compiled
having a CH$PTR function size value that is invalid for creating
a global byte pointer.
User Action. Determine if a local byte pointer is acceptable; if
not, change the size value to reflect a valid global byte pointer.
249

EXTENDED addressing is not supported under TOPS-10

Explanation. The compiler has reported that it cannot support
extended addressing under TOPS-10.
User Action. Remove the extended addressing feature from the
program.
250

Referenced <LOCAL/STACKLOCAL/REGISTER> symbol
<name> is probably not initialized.

Explanation. This indicates a reference to the value of a local
or register symbol (with a dot) before that symbol has received
a value. This message may be printed erroneously ·when the
initialization of a variable occurs on one branch of a conditional
(IF, CASE, or SELECT), and a reference to the variable occurs
on another branch of the conditional, and the conditional is
contained in a loop.
Note that this error message may indicate the occurrence of a
common programmer mistake whereby the address of a variable
is stored in a control block and the control block is then passed
to a routine (such as a system service or RMS routine) which will
update the data at that address. If the variable does not have the
VOLATILE attribute, the compiler cannot know that its value is
potentially changed by the routine call.
User Action. Initialize the symbol prior to its first use.
Error Messages

E-43

251

Symbol <name> is declared <class> in an outer block
Explanation. A symbol name declared in an outer block is
inaccessible because it is also declared in an inner block.
User Action. Ensure that all references to the name in the inner
block refer to the symbol declared there and not to the one
declared in the outer block.

252

Test expression is always <true/false>
Explanation. During the optimization of an IF, WHILE, or
UNTIL structure, a test expression has been reduced to a constant
with the possible elimination of code.
User Action. Evaluate the test expression for proper operation.

253

Action <number>
text>

<never/always> true. <elimination-

Explanation. One or more of the action statements in a SELECT
or SELECTONE construct cannot be reached, and consequently
certain actions have been eliminated.
User Action. Evaluate the select statements for proper operation.

254

PRESET-attribute must be preceded by a structure-attribute
Explanation. To use a PRESET attribute to initialize the fields
of a structured data segment, there must be a structure attribute
to associate the name of the data segment specified in the preset
item with a structure definition.
User Action. Correct the use of the PRESET attribute.

255

Offset in PRESET-item cannot be negative
Explanation. The PRESET item should be a positive value.
User Action. Correct the value of the item.

256

Filespec TRUNCATED, too long for DEBUG DST /SFC Record:
<filespec>
Explanation. The filespec is too long to fit in the record that
describes it to the debugger.
User Action. Rename the file using a shorter name.

E-44

Error Messages

257

/MASTER_CROSS_REFERENCE qualifier has been superseded
by /ANALYSIS_DATA
Explanation. The /MASTER_CROSS_REFERENCE qualifier
is obsolete. The /ANALYSIS_DATA qualifier now allows you
to extract an expanded version of such information and use the
VAX Source Code Analyzer (SCA) to interactively query or report
it.
User Action. Use the /ANALYSIS_DATA qualifier to obtain
comprehensive cross-reference data.

259

Number of psects used exceeds implementation limit of 32768
Explanation. The number of psects used in the current module
exceeds the number allowed.
User Action. Reduce the number of psects to the required limit.

E. 1 BLISS Compiler Fatal Errors
The following fatal error messages indicate serious problems with the
environment or the compiler, or both. 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-10/20, your program may be too large to compile.
1/0 ERROR ON INPUT FILE
An error occurred while an input file was being accessed. This may be
preceded by other error messages that provide more specific information
about the error.
1/0 ERROR ON OBJECT FILE
An error occurred while the output object file was being accessed. This
may be preceded by other error messages that provide more specific
information about the error.
Error Messages

E-45

1/0 ERROR ON LISTING FILE
An error occurred while the output listing file was being accessed. This
may be preceded by other error messages that provide more specific
information about the error.
1/0 ERROR ON LIBRARY FILE
An error occurred while a BLISS precompiled library file was being
accessed. This may be preceded by other error messages that provide
more specific information about the error.
LIBRARY PRE-COMP/LA TION EXCEEDS COMPILER LIMIT
A precompiled BLISS library cannot be larger than approximately 2048
(DECsystem-10 /20) disk blocks; the library file will be deleted. VAX
libraries have no restrictions.
MACRO OR STRUCTURE DECLARATION WITHIN STRUCTURE
BODY
This is a permanent implementation restriction in the BLISS language.
REQUIRE DECLARATION WITHIN MACRO BODY
This is a permanent implementation restriction in the BLISS language.
FATAL ERROR IN COMMAND LINE
This message appears on VMS only, for BLISS-32 or BLISS-16. Your
command line was improperly formed. A previous error message provided
additional information to describe what was wrong.

1/0 ERROR DURING COMMAND LINE SCANNING
This message appears on TOPS-10 or TOPS-20 when a severe error is
encountered in command line parsing.
NESTED EXPRESSION TOO DEEP. SIMPLIFY AND
RECOMPILE
The source program contains more than 64 levels of nested blocks, each
containing declarations.
UNRECOVERABLESOURCEERRORS.CORRECTAND
RECOMPILE
This message appears on 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-46

Error Messages

Appendix F

Sample Output Listing
Figure F-1 contains the complete output listing for the module TESTFACT.
Chapter 2 examples use excerpts from this listing.

Sample Output Listing

F-1

Figure F-1 : Sample Output Listing

en
Cl)

TESTFACT

ll-Mar-1987 15:58:48
22-Jul-1983 16:06:56

VAX Bliss-32 V4.3
DISK$:[DIRECTORY]MYPROG.B32;13

Page

1
( 1)

Ci)
0

s
s

ra·
s·

CCI

0001
0002
0
WARN#048
Syntax
0003
0004
0005
0006
0007
0008
0009
0010
0011
0012
0013
0014
WARN#OOO
Undeclared
0015
2
0016

MODULE TESTFACT (MAIN = MAINPROG)
BEGIN
1
L1:0002
in module head
OWN
A,
B;

ROUTINE IFACT (N)
BEGIN
LOCAL
RESULT;
RESULT = 1;
INCR I FROM 2 TO .N DO
RESULT= .REULT*.I;
. . . . . . . . . . . . . . . . . . 1 L1:0014
RE ULT
.RESULT
END;

00000 A:
00004 B:

.TITLE

TESTFACT

. PSECT

$OWN$, NOEXE, 2

.BLKB
.BLKB
.EXTRN

50
51
50
F5
Routine Size:

0017
0018
0019
0020
0021
0022
0023

l
l

22 bytes,

OOOOG

CF
51

Routine Base:

ROUTINE RFACT (N) =
IF .N GTR l
THEN
. N * RF ACT ( . N ELSE

RE ULT

. PSECT

$CODE$,NOWRT,2

00000 IFACT:
00002
00005
00008
OOOOA 1$:
00010 2$:
00015

.WORD
MOVL
MOVL
BRB
MULL3
AOBLEQ
RET

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

0000 00000 RFACT:

.WORD

Save nothing

0000
01
DO
01
DO
11
06
CS
51
F3
AC
04

0008
0012
0013
0014
0016

$CODE$ + 0000

l )

; 0018

ZK-5996/1-HC

(Continued on next Dasz:e)

Figure F-1

(Cont.):

Sample Output Listing

TESTFACT

11-Mar-1987 15:58:48
22-Jul-1983 16:06:56

04
EF

AC
AF
50

AC
OE
01
01
AC

50
Routine Size:
0024
0025
0026
0027
0028
0029
0030
0031

26 bytes,

Routine Base:

Dl
15
C3
FB
C4
04
DO
04

00002
00006
00008
00000
00011
00015
00016 1$:
00019

CMPL
BLEQ
SUBL3
CALLS
MULL2
RET
MOVL
RET

VAZ. Bliss-32 V4.3
DISK$:[DIRECTORY]MYPROG.832;13

Page

2
( 1)

N, #1
1$
#1, N, -(SP)
111, RFACT
N, RO

0019

U, RO

0019
0023

Save nothing
#5
t1, IFACT
RO, A
#5
#1, RFACT
RO, B
#1, RO

0025
0027

0021

$CODE$ + 0016

ROUTINE MAINPROG =
BEGIN
A= IFACT(5);
B = RF ACT ( 5 ) ;
VMS wants a success return
END;

cs
00 00'
D3
0 0 0 0'

Routine Size:
0032
0033

28 bytes,

05
01
50
05
01
50
01

AF
CF
AF
CF
50

Routine Base:

0000 00000 MAINPROG:
.WORD
DD 00002
P\?SHL
FB 00004
CALLS
DO 00008
MOVL
DD OOOOD
PUSHL
FB OOOOF
CALLS
DO 00013
MOVL
DO 00018
MOVL
04 00018
RET

0028
0031

$CODE$ + 0030

END
ELUDOM

I»

"Cl

CD"
0

s.
s.

PSECT SUMMARY
Name

Bytes

Attributes

"Cl

r~:
:r
cc

$OWN$
$CODE$

NOVEC,
WRT,
NOVEC,NOWRT,

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

LCL,
LCL,

REL,
REL,

COR,NOPIC,ALIGN(2)
COR,NOPIC,ALIGN(2)

.,,

ZK-5996/2-HC

(Continued on next page)

7'
.rai
Cll

Figure F-1 (Cont.):

Sample Output Listing

TESTFACT

ll-Kar-1987 15:58:48
22-Jul-1983 16:06:56

CD'

.as
0

VAX Bliss-32 V4.3
DISK$:[DIRECTORY)MYPROG.B32;13

Page

3
( l)

Information:
warnings:
Errors:

s·

COMMAND QUALIFIERS

BLISS/LISTING MYPROG.832
Size:
76 code + 8 data bytes
Run Time:
00:00.2
Elapsed Time:
00:00.5
Lines/CPU Min:
8250
Lexemes/CPU-Min: 31000
Memory Used:
19 pages
Compilation Complete
ZK-5996/3-HC

Appendix G

Optional Programming Productivity
Tools
This appendix provides an overview of optional programming productivity
tools. These tools are not included with the BLISS-32 software; they must
be purchased separately. Using these tools can increase your productivity
as a BLISS-32 programmer. For information on how to purchase these
tools, contact your DIGITAL sales representative.

G. 1 Using LSE with BLISS-32
The VAX Language-Sensitive Editor (LSE) is a powerful and flexible text
editor designed specifically for software development. LSE has important
features that help you produce syntactically correct code in BLISS-32.
To invoke LSE, issue the LSEDIT command followed by a file name with
a .B32 file type at the DCL prompt. For example:
$ LSEDIT USER.B32

The following sections describe .some of the key features of LSE.
Section G.1.1 discusses how to enter source code using LSE and
Section G.1.2 describes LSE's compiler interface features. Section G.1.3
gives examples of how to generate BLISS-32 source code with L,SE.
For more details on advanced features of LSE, see the Guide to VAX

Language-Sensitive Editor and VAX Source Code Analyzer.

Optional Programming Productivity Tools G-1

G.1.1

Entering Source Code Using Tokens and Placeholders
LSE simplifies the tasks of developing and maintaining software systems.
LSE provides the functions of a traditional text editor, plus additional
powerful features: language-specific placeholders and tokens, aliases,
comment and indentation control, and templates for subroutine libraries.

Placeholders are markers in the source code that indicate locations where
you can provide program text. Placeholders help you to supply the
appropriate syntax in a given context. Generally, you do not need to type
placeholders; rather, they are inserted for you by LSE.
Placeholders are either optional or required. Required placeholders, which
are delimited by braces ( {} ), represent places in the source code where you
must provide program text. Optional placeholders, which are delimited
by brackets ( [] ), represent places in the source code where you can either
provide additional constructs or delete the placeholder.
There are three types of LSE placeholders:
Type of Placeholder

Description

Terminal

Provides text that describes valid replacements for
the placeholder

Nonterminal

Expands into additional language constructs

Provides a list of options corresponding to the
placeholder

You can move forward or backward from placeholder to placeholder. In
addition, you can delete or expand placeholders as needed. Section G.1.3
shows examples of expanding placeholders.

Tokens typically represent keywords in BLISS-32. When expanded, tokens
provide additional language constructs. You can type tokens directly into
the buffer. Generally, you use tokens when you want to add language
constructs and there are no placeholders in an existing program. For
example, typing IF and issuing the EXPAND command causes a template
for an IF construct to appear on your screen. You can also use tokens
to by-pass long menus in cases where expanding a placeholder, such as
{statement}, would result in a lengthy menu.
You can use tokens to insert text when editing an existing file by typing
the name for a function or keyword and issuing the EXPAND command.

G-2 Optional Programming Productivity Tools

LSE commands allow you to manipulate tokens and placeholders. These
commands and their default key bindings are as follows:
Command

Key Binding

Function

EXPAND

CTRL/E

Expands a placeholder

UNEXPAND

PFl-CTRL/E

Reverses the
effect of the most
recent placeholder
expansion

GOTO PLACEHOLDER/FORWARD

CTRL/N

Moves the cursor
to the next
placeholder

GOTO PLACEHOLDER/REVERSE

CTRL/P

Moves the cursor
to the previous
placeholder

ERASE PLACEHOLDER/FORWARD

CTRL/K

Erases a placeholder

UNERASE PLACEHOLDER

PFl-CTRL/K

Restores the most
recently erased
placeholder

None

Down arrow

Moves the indicator down through
a menu

None

Up arrow

Moves the indicator up through a
menu

None

{ENTER }
RETURN

Selects a menu
option

You can display a list of all defined tokens and placeholders, or a particular token or placeholder, with the LSE commands SHOW TOKEN and
SHOW PLACEHOLDER. To copy the listed information into a separate
file, first issue the appropriate SHOW command to put the list into the
$SHOW buffer. Then issue the following commands:
LSE> GOTO BUFFER $SHOW
LSE> WRITE filename

To obtain a hard copy of the list, use the PRINT command at DCL level
to print the file you created.
Optional Programming Productivity Tools G-3

G.1.2

Compiling Source Code
To compile your code and review compilation errors without leaving
the editing session, you can use the LSE commands COMPILE and
REVIEW. The COMPILE command issues a DCL command in a subprocess to invoke the BLISS-32 compiler. The compiler then generates
a file of compile-time diagnostic information that LSE can use to review
compilation errors. The diagnostic information is generated with the
/DIAGNOSTICS qualifier that LSE appends to the compilation command.
For example, if you issue the COMPILE command while in the buffer
USER.B32, the following DCL command executes:
$ BLISS USER.B32/DIAGNOSTICS=USER.DIA

LSE supports all of the BLISS-32 compiler's command qualifiers as well as
user-supplied command procedures. You can specify DCL qualifiers, such
as /LIBRARY, when invoking the compiler from LSE.
The REVIEW command displays any diagnostic messages that result from
a compilation. LSE displays the compilation errors in one window and
the corresponding source code in a second window so that you can review
your errors while examining the associated source code. This capability
eliminates tedious steps in the error correction process and helps ensure
that all the errors are fixed before you recompile your program.
LSE provides several commands to help you review errors and examine
your source code. These commands, and their default key bindings where
applicable, are as follows:
Command

Key· Binding

Function

COMPILE

None

Compiles the contents of the
source buffer. You can issue this
command with the /REVIEW
qualifier to put LSE in REVIEW
mode immediately after the
compilation.

REVIEW

None

Puts LSE into REVIEW mode and
displays any errors resulting from
the last compilation.

G-4 Optional Programming Productivity Tools

Command

Key Binding

Function

END REVIEW

None

Removes the buffer $REVIEW
from the screen; returns the cursor
to a single window containing the
source buffer.

GOTO SOURCE

CTRL/G

Moves the cursor to the source
buffer that contains the error.

NEXT STEP

CTRL/F

Moves the cursor to the next error
in the buffer $REVIEW.

PREVIOUS STEP

CTRL/B

Moves the cursor to the previous
error in the buffer $REVIEW.

{Down arrow
Up arrow

G.1.3

}

Moves the cursor within a buffer.

Examples
The following sections show examples of using some common tokens and
placeholders to write BLISS-32 code. The examples are expanded to show
the formats and guidelines LSE provides; however, not all of the examples
are fully expanded.
The examples show expansions of the following BLISS-32 features:

•
•
•
•
•

Module declaration
Routine declaration
IF statement
Select expression
CH$COMP ARE function

Instructions and explanations precede each example, and an arrow (--+
indicates the line in the code where an action has occurred.
See Section G.1.1 for the commands that manipulate tokens and placeholders.
Remember that braces and tildes ( --{ }-- ) enclose required placeholders;
brackets and tildes ( ,_, [] ,_, ) enclose optional placeholders. Note that
when you erase an optional placeholder, LSE also deletes any associated
text before and after that placeholder.

Optional Programming Productivity Tools G-5

NOTE

Keywords such as MODULE, ROUTINE, IF, SELECT, and
CH$COMPARE can be tokens as well as placeholders; therefore, any time you are in the BLISS-32 language environment
you can type one of these words and press CTRL/E to expand
the construct.
When you use LSE to create a new BLISS-32 program, the initial string [
,...., MODULE ,...., ] appears at the top of the screen.

G.1.4

Medule Declaration
Expand the token [ ,...., MODULE ,...., ].
[-%TITLE •[-quoted_chars-]•-]
MODULE {-name-} [-(module_switches)-]
BEGIN
c-software_copyright_statement-]
![-module_level_comments-J
c-module_level_declarations-]
c-routine_declaration-] ...
END
! End of module
ELUDOM

Erase the optional placeholder [ ,...., %TITLE '[ --quoted_chars-- ]',...., ]
and expand the placeholder [ --(module_switches)-- ] twice to display a
menu. Select the option {--special_switch,....,} to display another menu,
and select the option IDENT.
->MODULE {-name_}.(IDENT = •[-quoted_chars-]' , [-module_switches-] ... ) =
BEGIN
c-software_copyright_s.tatement-]
![-module_level_comments-]
c-module_level_declarations-]
c-routine_declaration-J ...
END
! End of module
ELUDOM

Expand the placeholder [ --module-1evel_comments-- ].

G-6 Optional Programming Productivity Tools

MODULE {-name-} (!DENT= 1 [-quoted_chars-] 1
[-software_copyright_statement-]
BEGIN

[-module_switches-] ... )

•++

FACILITY:

ABSTRACT:

AUTHORS:

MODIFICATION HISTORY:
[-module_level_declarations-]
[-routine_declaration-] ...
END
ELUDOM

G. 1.4.1

End of module

Routine Declaration

Expand the placeholder [ --routine_declaration _, ] to display a menu.
->

[-routine_declaration-]

Select the option COMPLEX_ROUTINE.
[-Y.SBTTL •[-quoted_chars-]•-]
-> [-GLOBAL-] ROUTINE {-name-} [-(formals)-]
[-routine_level_comments-]
BEGIN
[-declaration-] .. .
{-expression-} .. .
END;
[-routine_declaration-] ....

[-routine_attributes-]

Erase the placeholder [ --GLOBAL-- ], expand [ --(formals)-- ], and erase
[ --routine_attributes-- ].

Optional Programming Productivity Tools G-7

[-Y.SBTTL •[-quoted_chars-]•-]
->ROUTINE {-name-} ([-input_formals-] [-; output_formals-])
[-routine_level_comments-]
BEGIN
[-declaration-] .. .
{-expression-} .. .
END;
[routine_declaration-] ...

Erase the placeholder [ ......,input_formals......, ] and expand [ ......,output_
formals......, ].
[-Y.SBTTL '[-quoted_chars-]•-]
->ROUTINE {-name-} ( ; {-formal_items-} ... )
[-routine_level_comments-]
BEGIN
[-declaration-] .. .
{-expression-} .. .
END;
[-routine_declaration-] ...

Expand the placeholder {......,formal_items......, }.
[-Y.SBTTL •[-quoted_chars-]•-]
->ROUTINE {-name-}(; {-name-}: [-formal_attributes-] ... , [-formal_items-] ... )
[-routine_level_comments-]
BEGIN
[-declaration-] .. .
{-expression-} .. .
END;
[-routine_declaration-] ...

Type Outarg over the second {......,name--} placeholder and expand the
placeholder [ --formaLattributes-- ].
[-Y.SBTTL •[-quoted_chars-]•-]
-> ROUTINE <-name-} (; Outarg : {-map_attributes-} [-formal_attributes-] ,
[-formal_items-] ... )=
[-routine_level_comments-]
BEGIN
[-declaration-] .. .
{-expression-} .. .
END;
[-routine_declaration-] ...

Expand the placeholder {--map_attributes--} to display a menu. Select
the option {--structure_attribute--} to display a menu. Select the option
REF {--structure_type--}. Expand the placeholder {--structure_type--} to
display a menu. Select REF_VECTOR, and erase the optional placeholder
[{--number_oLelements--}[ --allocation_and_or_extension-- ]] and the
optional list placeholders [ --formal_attributes-- ] and
[ --formal_items-- ] ....

G-8

Optional Programming Productivity Tools

c-Y.sBTTL I c-quoted_chars-1•-1
->ROUTINE {-name-} (; Outarg : REF VECTOR[])
c-routine_level_comments-1
BEGIN
[-declaration-] .. .
{-expression-} .. .
END;
c-routine_declaration-1 ...

G. 1.4.2

IF Statement

Expand the placeholder {--expression,_} to display a menu.
BEGIN
[-declaration-] .. .
->{-expression-} .. .
END;

Select the option IF.
BEGIN
[-declaration-] ...
-> IF {-expression-}
THEN
eexpression-}
[-ELSE {-expression-}-];
c-expression-1 ...
END;

Expand the placeholder [ ,_ELSE {--expression,_,} ,_, ].
BEGIN
[-declaration-] ...
IF {-expression-}
THEN
-> ELSE
eexpression-};
c-expression-1 ...
END;

Optional Programming Productivity Tools

G-9

G. 1.4.3

Select Expression

Expand the placeholder {--expression,..,,,} to display a menu.
BEGIN
[-declaration-] .. .
->{-expression-} .. .
END;

Select the option SELECT.
BEGIN
[-declaration-] ...
-> SELECT[-select_type-] {-select_index-} OF
SET
[{-select_labels-} ... ]:
{-select_action-};
<- sel_lines-} ...
TES;
[-expression-] ...
END;

Expand the placeholder [ --select_type-- ] to display a menu and select
the option ONE. Type .value over the placeholder {--selecLindex--}.
BEGIN
[-declaration-] ...
-> SELECTONE .value OF
SET
[{-select_labels-} ... ]:
{-select_action-};
{-sel_lines-} ...
TES;
[-expression-] ...
END;

Expand the placeholder {--selecLJabels--} ... to display a menu and
select the option {--low_selector--} TO {--higLselector--}.
BEGIN
[-declaration-] ...
SELECTONE .value OF
SET
->
[{-low_selector-} TO {-high_selector-}, [-select_labels-] ... ]:
{-select_action-};
<- sel_lines-} ...
TES;
[-expression-] ...
END;

G-1 0 Optional Programming Productivity Tools

Type the value -128 over the placeholder {--low_selector--} and the
value 127 over the placeholder {,._ high_selector-- }. Erase the remaining
duplicated placeholder [selecLJ.abels] . . . .

BEGIN
[-declaration-] ...
SELECTONE .value OF
SET
[-128 TO 127]:
{-select_action-};
{-sel_lines-} ...
TES;
[-expression-] ...
END;

Expand the placeholder {-select_action ,._} to produce the placeholder
{,._expression,._} and type size = 1 over {,._expression,._}.

BEGIN
[-declaration-] ...
SELECTONE .value OF
SET
[-128 TO 127]:
size = 1;
[-sel_lines-] ...
TES;
[-expression-] ...
END;

Expand the placeholder {-seLJines--} ....
BEGIN
[-declaration-] ...
SELECTONE .value OF
SET
[-128 TO 127]:
size = 1;
->

[{-select_labels-} ... ]:
{-select_action-};
[-sel_lines-] ...
TES;
[-expression-] ...
END;

Expand the placeholder {--selecLJabels-} to display a menu and select
the option OTHERWISE.

Optional Programming Productivity Tools G-11

BEGIN
[-declaration-] ...
SELECTONE .value OF
SET
[-128 TO 127]:
size = 1;
->

[OTHERWISE, [-select_labels-] ... ]:
{-select_action-};
[-sel_lines-] ...
TES;
[-expression-] ...
END;

Erase the optional list placeholder [ --select-1abels-- ] .... Type size
= 4 over the placeholder {--select_action--}. Erase the optional list
placeholder [ --sel-1ines-- ].
BEGIN
[-declaration-] ...
SELECTONE .value OF
SET
[-128 TO 127]:
size = 1;
->

G.1.4.4

[OTHERWISE] :
size = 4;
TES;
[-expression-] ...
END;

CH$COMPARE Function
BEGIN
[-declaration-] .. .
{-expression-} .. .
END;

Type CH$COMPARE over the placeholder {--expression-..} ... and
expand CH$COMPARE.

G-12

BEGIN
[-declaration-] ...
CH$COMPARE ({-n1_ch-}, {-ptr_ch-}, {-n2_ch-}, {-ptr2_ch-}, [-fill_ch-]);
[-expression-] ...
END;

Optional Programming Productivity Tools

Type the value 5 over the placeholder {--nl_ch ,_} and CH$PTR (alpha)
over the placeholder {--ptrl_ch,....) }.
BEGIN
[-declaration-] ...
-> CH$COMPARE (5, CH$PTR (alpha), {-n2_ch-}, {-ptr2_ch-}, [-fill_ch-]);
[-expression-] ...
END;

Type the value 7 over the placeholder {--n2_ch ,_} and CH$PTR (beta)
over the placeholder {--ptr2_ch--}.
BEGIN
[-declaration-] ...
-> CH$COMPARE (5, CH$PTR (alpha), 7, CH$PTR (beta), [-fill_ch-]);
[-expression-] ...
END;

Expand the placeholder [--fill_ch ,_].
BEGIN
[-declaration-] ...
-> CH$COMPARE (5, CH$PTR (alpha), 7, CH$PTR (beta), {-character_code_literal-});
[-expression-] ...
END;

Expand the placeholder {--character_code-1.iteral,...., }.
BEGIN
[-declaration-] ...
-> CH$COMPARE (5, CH$PTR (alpha), 7, CH$PTR (beta), Y.C 1 {-quoted_character-} 1 ) ;
[-expression-] ...
END;

Type a blank over the placeholder {"'quotecLcharacter--}.
BEGIN
[-declaration-] ...
-> CH$COMPARE (5, CH$PTR (alpha), 7, CH$PTR (beta), Y.C' ');
[-expression-] ...
END

Optional Programming Productivity Tools G-13

G.2 Using the VAX Source Code Analyzer
The VAX Source Code Analyzer (SCA) is an interactive tool used to
cross-reference and analyze source code. It can be used with most VAX
programming languages. SCA helps developers monitor large, complex
software systems by displaying source information in response to user
queries. SCA stores data generated by. the BLISS-32 compiler in an SCA
library. The data in an SCA library contains information about all the
symbols, modules, and files encountered during a specific compilation of
the source.
SCA lets you query both cross-reference and static analysis information.
Cross-referencing supplies information about program symbols and source
files. SCA provides the following cross-referencing features:
•
•
•
•

Locating names and occurrences (uses) of these names
Querying several names or partial names (with wildcards allowed)
Limiting a query to specific characteristics (such as routine names,
variable names, or source files)
Limiting a query to specific occurrences (such as the primary declaration of a symbol, read or write occurrences of a symbol, or occurrences
of a file)

The static analysis query features of SCA provide structural information
on the interrelation of routines, symbols, and files. SCA provides the
following static analysis features:
•
•

Displaying routine calls to and from a specified routine
Analyzing routine calls for consistency as to the numbers and data
types of arguments passed, and the types of values returned

SCA is fully integrated with LSE to provide additional features. By using
SCA with LSE, you can view any portion of an entire system and edit
related source files.
Multimodular Development

The cross-referencing and static analysis features of SCA are especially
useful during the implementation and maintenance phases of a project
that involves many programming modules. For example, the project team
work area in Figure G-1 contains a set of source modules. (The team
might use a code management tool, such as VAX DEC/CMS, to keep track
of these modules in their various development stages.) When the team
G-14

Optional Programming Productivity Tools

compiles the source code, SCA generates the source information it requires
(that is, data analysis files with the file type .ANA); then the team loads
this information into a previously established project SCA library.
When a team member wants to do additional development work on
specific modules, that member sets up an individual work area, which
might contain the following:
•
•

Copies of source and object modules from the project libraries
Local SCA libraries that contain copies of the module information

To make available all the capabilities of SCA/LSE integration, the team
member informs LSE of the locations of that member's current sources and
related source information. Using LSE, all team members can effectively
"see through" their own individual work areas to the project work area
and possibly to other individual work areas.
The following sections provide a general overview of SCA and discuss
some of the commands that are available to you when you use SCA
within LSE. For detailed information on SCA, refer to the Guide to VAX

Language-Sensitive Editor and VAX Source Code Analyzer.

G.2.1

Setting Up an SCA Environment
If you do not have an existing SCA library, you must take the following

steps to set up an SCA environment:
1. Create an SCA library in a subdirectory.
2. Use the BLISS-32 compiler to generate the data analysis (.ANA) files
for each source module in your system.
3. Load these data analysis files into your local SCA library.
If you have an existing SCA library, you only need to select the library to

use SCA to conduct source information queries.

Optional Programming Productivity Tools G-15

Figure G-1:

Use of LSE and SCA for Multimodular Development
Project Work Area

Debugger,
Source,
Or
Reference
Copy
Area

CMS
Library

Load

Compile

.ANA
Files

SCA
Library

I
I
_J

I
I

Some
Source
Code
Modules

.ANA
Files

Pointers to Source
for LSE

Individual
SCA
Library

Pointers to SCA
Information for LSE
ZK-5850-HC

G-16

Optional Programming Productivity Tools

G.2. 1. 1

Creating an SCA Library

To create an SCA library, first create a subdirectory at the DCL level. For
example:
$CREATE/DIRECTORY PROJ:[USER.LIB1]

This command creates a subdirectory LIBl for a local SCA library.
To initialize a new SCA library, issue the command CREATE LIBRARY.
For example:
$ SCA CREATE LIBRARY [.LIB1]

This command initializes and activates library LIB 1.
G.2.1.2

Generating Data Analysis Files

SCA uses detailed source data that is generated by the BLISS-32 compiler.
When you specify the / ANALYSIS_DATA qualifier on the BLISS command, the generated data is output to a file with the default type .ANA.
For example:
$ BLISS/LIST/DIAGNOSTICS/ANALYSIS_DATA PG1,PG2,PG3

This command line compiles the input files PG1.B32, PG2.B32, and
PG3.B32, and generates four corresponding output files for each input file,
with the file types .OBJ, .LIS, .DIA, and .ANA. SCA puts these files in
your current default directory unless you specify otherwise.
G.2.1.3

Loading Data Analysis Files into a Local Library

Before you can examine the information in the .ANA files, you must load
the information into an SCA library using the LOAD command.
For example:
LSE> LOAD PG1,PG2,PG3

This command loads your library with the modules contained in the data
analysis files PGl.ANA, PG2.ANA, and PG3.ANA.

Optional Programming Productivity Tools G-17

G.2.1.4

Selecting an SCA Library

To select an existing SCA library to use with your current SCA session,
use the SCA command SET LIBRARY.
For example:
LSE> SET LIBRARY [.LIB1]

This command activates library LIB 1.

G.2.2

Using SCA for Cross-Referencing
Once you have set up your SCA environment, you can ask for symbol or
file information by using the SCA command FIND. The FIND command
has the following form:
FIND [/qualifier ... ] [name-expression[, ... ]]

The name expression can be explicit or can contain wildcards. For example:
LSE> FIND ABc,xn

You can query an SCA library for the following:
Name

A series of characters that uniquely identifies a symbol or a file

Item

An appearance of a symbol (such as a variable, constant, label,
or procedure) or a file

Occurrence

The use of a symbol or a file

To limit the information resulting from a query, you can use qualifiers on
the FIND command. For example:
·
LSE> FIND/REFERENCES=CALL BUILD_TABLE

This command causes SCA to report only references in the source code
where the routine BUILD_TABLE is called.

G-18

Optional Programming Productivity Tools

When you first issue a FIND command within LSE, you initiate a query
session. Within this context, the integration of LSE and SCA provides
commands that can be used only within LSE. These commands are as
follows:
Command

{

~:J1ous ~~~~RRENCE
} (

QUERY

STEP

Function
Lets you step through one or more
query buffer displays within LSE

GOTO SOURCE

Displays the source corresponding
to the current query item

GOTO DECLARATION

Positions the cursor on a symbol
declaration in one window, and
displays the source code that
contains the symbol declaration in
another window

Optional Programming Productivity Tools G-19

INDEX
A
Abbreviations
qualifiers• 1-26, A-5
qualifier values• A-5
value names• 1-26
ADA WI function • 4-9
ADDO function • 4-9
ADDF function• 4-10
ADDG function • 4-10
ADDH function• 4-11
ADDM function• 4-11
/ANAL YSIS_DAT A qualifier• 1-18, A-5
%ASCII literal• 6-6
ASHP function • 4-12
ASHO function • 4-13
ASSEMBLER qualifier value• 1-13

B
BICPSW function • 4-14
BINARY qualifier value• 1-13
BIND declaration• 5-2
BIND ROUTINE declaration• 5-2
BISPSW function• 4-14
BLISS-16 • 6-1
%BLISS 16 lexical• 6-7
%BLISS32 lexical• 6-7
BLISS-36 • 6-1
%BLISS36 lexical• 6-7
BLISS module template • C-1
closing format • C-5
declararative part• C-3
executable part • C-4

BLISS module template (cont'd.)
preface• C-2
%BPADDR literal• 6-5
BPT function • 4-14
%BPUNIT literal• 6-5
%BPV AL literal• 6-5
BUGL function • 4-15
BUGW function • 4-15
BUilTIN declaration• 5-2

c
CALLG function • 4-16
Characters • 1-3
/CHECK qualifier• 1-7, A-5
/CHECK values
FIELD• A-5
INITIAL• A-5
OPTIMIZE • A-5
REDECLARE• A-5
CHME function• 4-17
CHMK function • 4-17
CHMS function• 4-17
CHMU function • 4-17
%C literal • 6-6
CMPC3 function • 4-17
CMPC5 function • 4-18
CMPD function • 4-19
'cMPF function • 4-20
CMPG function• 4-21
CMPH function • 4-21
CMPM function• 4-22
CMPP function• 4-23
Code examples• 9-1
Code formatting • B-1

lndex-1

/CODE qualifier• 1-11, A-5
CODE switch• 1-24
Coding errors • 5-3
block values • 5-5
from linker • 5-10
indexed loop • 5-9
macro usage • 5-7
missing code• 5-7
missing dots• 5-4
nonvalued routines • 5-4
operator precedence • 5-5
PC usage• 5-8
routine calls • 5-5
semicolons• 5-5
signed fields • 5-6
unsigned fields • 5-6
valued routines • 5-4
Coding examples
ALPHA program• 9-1
CALC program• 9-13
Command line
semantics • 1-3
syntax• 1-3
summary• A-1
COMMENT ARY qualifier value• 1-13
Compilation
summary• 2-2, 2-3
Compiler• 7-1
optimization • 7-1
output• 2-1
overview • 7-1
phases• 7-2
CODE•7-2
code generation • 7-9
code optimization • 7-9
DELAY•7-2
FINAL• 7-2
FLOW•7-2
flow analysis • 7-3
heuristic • 7-8
lexical analysis• 7-2
LEXSYN•7-2
name binding• 7-8
OUTPUT•7-2
output files • 7-10
syntactic analysis• 7-2
TNBIND•7-2
switch effects • 7-1 O

2-lndex

Compiler (cont'd.)
switches • 7-1
CODE• 7-1
NOCODE•7-1
NOOPTIMIZE • 7-1
NOSAFE•7-1
NOZIP•7-1
OPTIMIZE• 7-1
OPTLEVEL • 7-1
SAFE•7-1
ZIP• 7-1
COMPILETIME declaration • 5-2
Concatenation• 1-2
indicator• 1-2
CRC function• 4-24
/CROSS_REFERENCE qualifier• 1-8, A-5
/CROSS_REFERENCE value
MULTIPLE• A-5
NOMULTIPLE • A-5
Cross-reference listing• 2-27
defined field• 2-30
header• 2-27
referenced field• 2-31
symbol field• 2-27
type field• 2-28
CVTDF function• 4-24
CVTDI function• 4-25
CVTDL function• 4-25
CVTFD function• 4-26
CVTFG function• 4-26
CVTFH function• 4-27
CVTFI function• 4-27
CVTFL function• 4-28
CVTGF function• 4-28
CVTGH function• 4-29
CVTGL function• 4-29
CVTHF function • 4-30
CVTHG function • 4-30
CVTHL function• 4-30
CVTID function • 4-31
CVTIF function • 4-31
CVTLD function• 4-32
CVTLF function • 4-32
CVTLH function • 4-33
CVTLP function• 4-33
CVTPL function • 4-34
CVTPS function • 4-34
CVTPT function • 4-35

CVTRDL function• 4-37
CVTRFL function• 4-37
CVTRGL function • 4-38
CVTRHL function • 4-38
CVTSP function• 4-39
CVTTP function• 4-40

D
Debugging • 3-3
address expressions • 3-6
arithmetic operators • 3-5
commands
summary• 3-19
syntax• 3-4
/DEBUG• 3-18
display mode• 3-4
entry mode • 3-4
field references • 3-11
HEXIDECIMAL • 3-4
REF structure reference • 3-16
scope of names • 3-17
source-line • 3-18
special characters • 3-6
structure references • 3-13
SYMBOLIC• 3-4
/DEBUG qualifier• 1-11, 3-18, A-5
DEBUG switch• 1-24
Declarations
BIND•5-2
BIND ROUTINE• 5-2
BUilTIN• 5-2
COMPILETIME • 5-2
EXTERNAL• 5-2
EXTERNAL LITERAL• 5-2
EXTERNAL ROUTINE• 5-2
FIELD•5-2
GLOBAL• 6-14
KEYWORDMACRO • 5-2
LIBRARY• 5-2
LINKAGE• 5-2
LITERAL• 5-2, 6-5
LOCAL•6-14
MACR0•5-2
OWN•6-14
REQUIRE• 5-2
STRUCTURE• 5-2

Declarations (cont'd.)
SWITCHES• 5-2
UNDECLARE • 5-2
Defaults
qualifiers• A-4
Delimiters • 1-3
DIVD function• 4-41
DIVF function • 4-41
DIVG function• 4-42
DIVH function • 4-42

E
Editors
LSE • G-1 to G-19
EDITPC function • 4-43
EDIV function • 4-44
%ELSE lexical• 6-7
EMUL function • 4-45
/ERROR_LIMIT qualifier• 1-11, A-5
Error messages • E-1
format of• 2-39
pointers• 2-41
types of• 2-39
ERRORS qualifier value • 1-23
ERRS switch• 1-24
%EXPAND•5-10
EXPAND_MACROS qualifier value• 1-21
EXTERNAL declaration • 5-2
EXTERNAL LITERAL declaration• 5-2
EXTERNAL ROUTINE declaration • 5-2

F
FFC function• 4-45
FFS function• 4-45
FIELD declaration • 5-2
FIELD qualifier value • 1-7
File-designator• 1-5, 1-19
Files
LIBRARY • 5-1
REQUIRE • 5-1
File type
defaults • l -5
%Fl lexical• 6-7
Format
error messages • 2-39

lndex-3

Format (cont'd.)
preface string• 2-6

%IF lexical• 6-7
Implementation limits• D-1
BLISS-32 constructs• D-1
System interfaces• D-2
INDEX function • 4-46
INITIAL qualifier value• 1-7
INSQHI function• 4-4 7
INSQTI function• 4-47
INSQUE function • 4-48

LIBRARY
declaration• 5-2
files • 5-1, 6-11
/LIBRARY qualifier• 1-18, A-5
LIBRARY qualifier value• 1-21
LINKAGE declaration• 5-2
Linking • 3-1
commands• 3-2
example• 3-2
/LIST qualifier• 1-18, A-5
LIST switch
ASSEMBLY • 1-24
BINARY• 1-24
COMMENT ARY • 1-24
EXPAND• 1-24
LIBRARY • 1-24
OBJECT• 1-24
REQUIRE • 1-24
SOURCE• 1-24
SYMBOLIC• 1-24
TRACE• 1-24
LITERAL declaration• 5-2, 6-5
LOCAL declaration • 6-14
LOCC function• 4-49
LSE (Language-Sensitive Editor) • 8-1, G-1 to G-19

KEYWORDMACRO declaration• 5-2

/MACHINE_CODE_LIST qualifier• 1-13, A-5
/MACHINE_CODE_LIST values
ASSEMBLER• A-5
BINARY• A-5
COMMENT ARY• A-5
OBJECT• A-5
SYMBOLIC• A-5
UNIQUE_NAMES • A-5
Machine-specific functions • 4-1
input parameters• 4-1
instruction summary • 4-3
output parameters• 4-2
MACRO declaration• 5-2
Macros • 5-10
conditional • 5-10
creating a set • 5-14
enumeration types • 5-13
iterative • 5-10
lexical functions • 5-10

G
GLOBAL declaration • 6-14

H
HALT function • 4-46
HEADER qualifier value• 1-21
HEXIDECIMAL • 3-4

L
Language-Sensitive Editor (LSE) • 8-1, G-1 to G-19
LEVEL qualifier value• 1-16
Lexical functions
-%BLISS 16 • 6-7
%BLISS32 • 6-7
%BLISS36 • 6-7
%ELSE •6-7
%EXPAND• 5-10
%Fl• 6-7
%IF• 6-7
%QUOTE • 5-10
%REMAINING• 6-7
%THEN•6-7
Libraries• 8-1

4-lndex

Macros (cont'd.)
machine dependencies • 5-11
set elements • 5-16
set memberships • 5-17
SET type • 5-13
string instructions• 5-11
MA TCHC function• 4-49
MFPR function • 4-51
Module-head switch• 1-24, 1-25
values
CODE• 1-24
DEBUG• 1-24
ERRS• 1-24
LIST
ASSEMBLY• 1-24
BINARY• 1-24
COMMENT ARY• 1-24
EXPAND• 1-24
LIBRARY• 1-24
OBJECT• 1-24
REQUIRE• 1-24
SOURCE• 1-24
SYMBOLIC• 1-24
TRACE• 1-24
NOZIP• 1-24
OPTLEVEL • 1-24
SAFE• 1-24
UNAMES • 1-24
ZIP• 1-24
MOVC3 function • 4-51
MOVC5 function • 4-52
MOVP function • 4-53
MOVPSL function• 4-54
MOVTC function • 4-54
MOVTUC function • 4-56
MTPR function • 4-5 7
MULD function• 4-5 7
MULF function• 4-58
MULG function• 4-59
MULH function • 4-59
MULTIPLE qualifier value • 1-9

N
NOP function• 4-60
NOZIP switch• 1-24

0
Object listing
default• 2-12
/OBJECT qualifier• 1-18, A-5
Operating procedures
compiling • 1-1
OPLEVEL switch• 1-24
/OPTIMIZE qualifier• 1-15, A-5
OPTIMIZE qualifier value• 1-7
/OPTIMIZE values
HEADER•A-6
LEVEL• A-5
LIBRARY • A-6
PAGE_SIZE • A-6
QUICK•A-5
REQUIRE • A-6
SAFE• A-5
SOURCE•A-6
SPACE• A-5
SPEED• A-5
TRACE_MACROS • A-6
Output listing• 2-3
header• 2-5
object part• 2-10
source part• 2-6
OWN declaration • 6-14

p
PAGE_SIZE qualifier value• 1-21
PIC• 5-10
PUT• 6-23
defined• 6-23
scalar• 6-24
strings• 6-24
Position-independent code • 5-10
Predeclared literals
%ASCll•6-6
%BPADDR • 6-5
%BPUNIT • 6-5
%BPVAL•6-5
%C•6-6
%UPVAL•6-5
PROBER function • 4-60
PROBEW function • 4-61

lndex-5

Cl
Qualifiers
abbreviations• 1-26, A-5
/ANAL YSIS_DA TA• 1-18
/CHECK• 1-7
/CODE• 1-11
/CROSS_REFERENCE • 1-8
/DEBUG • 1-11, 3-18
defaults• A-4
default settings• 1-25
/ERRQR_LIMIT • 1-11
/LIBRARY • 1-18
/LIST• 1-18
/MACHINE_CODE_LIST • 1-13
negative forms• 1-26
/OBJECT• 1-18
/OPTIMIZE• 1-15
positive forms• 1-26
/QUICK• 1-15
/SOURCE_LIST • 1-20
/TERMINAL• 1-23
/TRACEBACK• 1-11
/VARIANT• 1-11
/QUICK qualifier• 1-15
QUICK qualifier value • 1-16
%QUOTE • 5-10

R
REDECLARE qualifier value• 1-7
%REMAINING lexical• 6-7
REMQHI function• 4-61
REMQTI function• 4-61
REMQUE function • 4-62
REQUIRE
declaration• 5-2
files • 5-1 , 6-11
REQUIRE qualifier value• 1-21
ROT function• 4-63

s
SAFE qualifier value • 1-16
SAFE switch• 1-24
Sample output listing • F-1

6-lndex

SCA (Source Code Analyzer) • 8-1 , G-14 to G-19
SCANC function • 4-63
SKPC function• 4-64
/SOURCE_LIST qualifier• 1-20, A-6
/SOURCE_LIST values
EXPAND_MACROS • A-6
Source Code Analyzer (SCA) • 8-1, G-14 to G-19
SPACE qualifier value• 1-16
SPANC function • 4-65
SPEED qualifier value• 1-16
ST A TISTICS qualifier value• 1-23
STRUCTURE declaration• 5-2
SUBD function • 4-66
SUBF function • 4-67
SUBG function• 4-67
SUBH function• 4-68
SUBM function • 4-68
Switches
CODE• 1-24
DEBUG• 1-24
ERRS• 1-24
LIST• 1-24
NOZIP• 1-24
OPLEVEL • 1-24
SAFE• 1-24
UNAMES • 1-24
ZIP• 1-24
SWITCHES declaration• 1-24, 5-2
values
ERRS• 1-24
LIST
ASSEMBLY• 1-24
BINARY• 1-24
COMMENT ARY• 1-24
EXPAND• 1-24
LIBRARY • 1-24
OBJECT• 1-24
REQUIRE • 1-24
SOURCE • 1-24
SYMBOLIC• 1-24
TRACE• 1-24
NOZIP• 1-24
SAFE• 1-24
UNAMES • 1-24
ZIP• 1-24
SWITCHES-declaration • 1-25
SYMBOLIC• 3-4

· SYMBOLIC qualifier value • 1-13
System services • 8-1
routine interfaces • 8-3
sample program • 8-4

T
Terminal output• 2-2
/TERMINAL qualifier• 1-23, A-6
/TERMINAL values
ERRORS• A-6
ST A TISTICS • A-6
TESTBITCC function • 4-69
TESTBITCCI function • 4-69
TESTBITCS function • 4-69
TESTBITSC function• 4-69
TESTBITSS function • 4-69
TESTBITSSI function • 4-69
%THEN lexical• 6-7
Tools• 8-1
Tutorial Terminal 1/0 • 8-2
VAX Language-Sensitive Editor • 8-1 , G-1 to
G-19
VAX Source Code Analyzer • 8-1, G-14 to G-19
TRACE_MACROS qualifier value• 1-21
/TRACEBACK qualifier• 1-11, A-6
Transportability• 6-1
concepts• 6-2
guidelines• 6-1
parallel definitions• 6-2
parameterization• 6-2
strategies • 6-3
isolation • 6-3
simplicity• 6-4
techniques • 6-14
addresses • 6-17
data• 6-14
field selectors • 6-34
initialization• 6-26
PLIT•6-23
strings• 6-21
structures • 6-34
toots• 6-4
library files• 6-11
literals • 6-4
macros•6-7
names•6-10

Transportability
tools (cont'd.)
REQUIRE files• 6-11
routines • 6-13
switches• 6-8
Tutorial Terminal 1/0 (TUTIO) • 8-2

u
UNAMES switch• 1-24
UNDECLARE declaration• 5-2
UNIQUE_NAMES qualifier value• 1-13
%UPVAL literal• 6-5

v
Values
abbreviations• 1-26, A-5
/CHECK qualifier
FIELD• 1-7
INITIAL• 1-7
OPTIMIZE• 1-7
REDECLARE• 1-7
/CROSS_REFERENCE qualifier
MULTIPLE• 1-9
/MACHINE_CODE_LIST qualifier
ASSEMBLER• 1-13
BINARY• 1-13
COMMENT ARY • 1-13
SYMBOLIC• 1-13
UNIQUE_NAMES• 1-13
/OPTIMIZE qualifier
LEVEL• 1-16
QUICK• 1-16
SAFE• 1-16
SPACE• 1-16
SPEED• 1-16
/SOURCE-LIST qualifier
EXPAND_MACROS • 1-21
HEADER• 1-21
LIBRARY• 1-21
PAGE_SIZE• 1-21
REQUIRE• 1-21
TRACE_MACROS• 1-21

lndex-7

/TERMINAL qualifier
ERRORS• 1-23
ST A TISTICS • 1-23
/VARIANT qualifier• 1-11, A-6

x
XFC function• 4-70

z
ZIP switch• 1-24

lndex-8

BLISS-32 User Manual
AA-H322E-TE

READER'S
COMMENTS

Note: This form is for document comments only.
DIGIT AL will use comments submitted on this form
at the company's discretion. If you require a written
reply and are eligible to receive one under Software
Performance Report (SPR) service, submit your
comments on an SPR form.

Did you find this manual understandable, usable, and well organized? Please make
suggestions for improvement.

Did you find errors in this manual? 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 Higher-level language programmer
D Occasional programmer (experienced)
D User with little programming experience
D Student programmer
D Other (please specify)
Name _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ D a t e - - - - - - - - - - Organization - - - - - - - - - - - - - - - - - - - - - - - - - - Street ----------~------------------City _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ State _ _ _ _ _ Zip Code _ _ __
or Country

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO. 33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

DIGITAL EQUIPMENT CORPORATION
The Manager, Office Program
ZK02-1 /N20
110 SPIT BROOK ROAD
NASHUA, NH 03062 - 9990

111 .... •11. 11 ... •11 ... •1.11.1 •• 1.1 .. 1.1 .. 11 .... •1.11
---- Do Not Tear-Fold Here ----------------------------------------------------,

BLISS-32 User Manual
AA-H322E-TE

READER'S
COMMENTS

Did you find 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 Higher-level language programmer
D Occasional programmer (experienced)

D User with little programming experience
D Student programmer
D Other (please specify)
Name _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ D a t e - - - - - - - - - - Organization - - - - - - - - - - - - - - - - - - - - - - - - - - Street ----------------------------~
City _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ State _ _ _ _ _ Zip Code _ _ __
or Country

---~nmaadmiindTape----------------------~------------~~i;;~----in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO. 33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE

DIGITAL EQUIPMENT CORPORATION
The Manager, Office Program
ZK02-1 /N20
110 SPIT BROOK ROAD
NASHUA, NH 03062 - 9990

111 ••••• 11.11 •••• 11 •••• 1.11.1 •• 1.1 •• 1.1 •• 11 ••••• 1.11
---- Do Not Tear-Fold Here ----------------------------------------------------,

I
I
I
I
I
I
I
I
I
I