VAX MACRO and Instruction Set Reference Manual

Document revision date: 19 July 1999

Order Number: AA--PS6GC--TE

January 1999

This document describes the features of the VAX MACRO instruction set and assembler. It includes a detailed description of MACRO directives and instructions, as well as information about MACRO source program syntax.

Revision/Update Information: This manual supersedes the VAX MACRO and Instruction Set Reference Manual, Version 6.0

Software Version: OpenVMS VAX Version 7.1

The content of this document has not changed since OpenVMS Version 7.1.

Compaq Computer Corporation Houston, Texas

Reprinted January 1999

Compaq Computer Corporation makes no representations that the use of its products in the manner described in this publication will not infringe on existing or future patent rights, nor do the descriptions contained in this publication imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.

Possession, use, or copying of the software described in this publication is authorized only pursuant to a valid written license from Compaq or an authorized sublicensor.

Compaq conducts its business in a manner that conserves the environment and protects the safety and health of its employees, customers, and the community.

The following are trademarks of Compaq Computer Corporation: Alpha, Compaq, DECdirect, DECwindows, DIGITAL, OpenVMS, VAX, VAX DOCUMENT, VAXcluster, VMS, and the Compaq logo.

The following are third-party trademarks:

All other trademarks and registered trademarks are the property of their respective holders.

ZK4515

The OpenVMS documentation set is available on CD-ROM.

This document was prepared using VAX DOCUMENT, Version V3.2n.

Contents Index

Preface

This manual describes the VAX MACRO language and the VAX instruction set. It includes the format and function of each feature of the language. The VAX Architecture Reference Manual describes the instruction set in greater detail.

Intended Audience

This manual is intended for all programmers writing VAX MACRO programs. You should be familiar with assembly language programming, the VAX instruction set, and the OpenVMS operating system before reading this manual.

Document Structure

This manual is divided into two parts, each of which is subdivided into several chapters.

Part 1 describes the VAX MACRO language.

Chapter 1 introduces the features of the VAX MACRO language.
Chapter 2 describes the format used in VAX MACRO source statements.
Chapter 3 describes the following components of VAX MACRO source statements:
- Character set
- Numbers
- Symbols
- Local labels
- Terms and expressions
- Unary and binary operators
- Direct assignment statements
- Current location counter
Chapter 4 describes the arguments and string operators used with macros.
Chapter 5 summarizes and gives examples of using the VAX MACRO addressing modes.
Chapter 6 describes the VAX MACRO general assembler directives and the directives used in defining and expanding macros.

Part 2 describes the VAX data types, the instruction and addressing mode formats, and the instruction set.

Chapter 7 summarizes the terminology and conventions used in the descriptions in Part 2.
Chapter 8 describes the basic VAX architecture, including the following:
- Address space
- Data types
- Processor status longword
- Permanent exception enables
- Instruction and addressing mode formats
Chapter 9 describes the native-mode instruction set. The instructions are divided into groups according to their function and are listed alphabetically within each group.
Chapter 10 describes the extension to the VAX architecture for integrated vector processing.

This manual also contains the following five appendixes:

Appendix A lists the ASCII character set used in VAX MACRO programs.
Appendix B gives rules for hexadecimal/decimal conversion.
Appendix C summarizes the general assembler and macro directives (in alphabetical order), special characters, unary operators, binary operators, macro string operators, and addressing modes.
Appendix D lists the permanent symbols (instruction set) defined for use with VAX MACRO.
Appendix E describes the exceptions (traps and faults) that may occur during instruction execution.

Reader's Comments

Compaq welcomes your comments on this manual.

Print or edit the online form SYS$HELP:OPENVMSDOC_COMMENTS.TXT and send us your comments by:

Internet openvmsdoc@zko.mts.dec.com

Fax 603 884-0120, Attention: OSSG Documentation, ZKO3-4/U08

Mail Compaq Computer Corporation
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

Use the following World Wide Web address to order additional documentation:

http://www.openvms.digital.com:81/

If you need help deciding which documentation best meets your needs, call 800-344-4825.

Conventions

The following conventions are used in this manual:

Ctrl/ x A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.

PF1 x A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.

[Return] In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.)
In the HTML version of this document, this convention appears as brackets, rather than a box.

... A horizontal ellipsis in examples indicates one of the following possibilities:

Additional optional arguments in a statement have been omitted.
The preceding item or items can be repeated one or more times.
Additional parameters, values, or other information can be entered.

.
.
. A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.

( ) In command format descriptions, parentheses indicate that you must enclose the options in parentheses if you choose more than one.

[ ] In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)

[|] In command format descriptions, vertical bars separating items inside brackets indicate that you choose one, none, or more than one of the options.

{ } In command format descriptions, braces indicate required elements; you must choose one of the options listed.

bold text This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason.

italic text Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where dd represents the predefined code for the device type).

UPPERCASE TEXT Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.

Monospace text Monospace type indicates code examples and interactive screen displays.
In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.

- A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.

numbers All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

VAX MACRO Language

Part I provides an overview of the features of the VAX MACRO language. It includes an introduction to the structure and components of VAX MACRO source statements. Part I also contains a detailed discussion of the VAX MACRO addressing modes, general assembler directives, and macro directives.

Chapter 1
Introduction

VAX MACRO is an assembly language for programming VAX computers using the OpenVMS operating system. Source programs written in VAX MACRO are translated into object (or binary) code by the VAX MACRO assembler, which produces an object module and, optionally, a listing file. The features of the language are introduced in this chapter.

VAX MACRO source programs consist of a sequence of source statements. These source statements may be any of the following:

VAX native-mode instructions
Direct assignment statements
Assembler directives

Instructions manipulate data. They perform such functions as addition, data conversion, and transfer of control. Instructions are usually followed in the source statement by operands, which can be any kind of data needed for the operation of the instruction. The VAX instruction set is summarized in Appendix D of this volume and is described in detail in Chapter 9. Direct assignment statements equate symbols to values. Assembler directives guide the assembly process and provide tools for using the instructions. There are two classes of assembler directives: general assembler directives and macro directives.

General assembler directives can be used to perform the following operations:

Store data or reserve memory for data storage
Control the alignment of parts of the program in memory
Specify the methods of accessing the sections of memory in which the program will be stored
Specify the entry point of the program or a part of the program
Specify the way in which symbols will be referenced
Specify that a part of the program is to be assembled only under certain conditions
Control the format and content of the listing file
Display informational messages
Control the assembler options that are used to interpret the source program
Define new opcodes

Macro directives are used to define macros and repeat blocks. They allow you to perform the following operations:

Repeat identical or similar sequences of source statements throughout a program without rewriting those sequences
Use string operators to manipulate and test the contents of source statements

Use of macros and repeat blocks helps minimize programmer errors and speeds the debugging process.

Chapter 2
VAX MACRO Source Statement Format

A source program consists of a sequence of source statements that the assembler interprets and processes, one at a time, generating object code or performing a specific assembly-time process. A source statement can occupy one source line or can extend onto several source lines. Each source line can be up to 132 characters long; however, to ensure that the source line fits (with its binary expansion) on one line in the listing file, no line should exceed 80 characters.

VAX MACRO statements can consist of up to four fields, as follows:

Label field---symbolically defines a location in a program.
Operator field---specifies the action to be performed by the statement; can be an instruction, an assembler directive, or a macro call.
Operand field---contains the instruction operands, the assembler directive arguments, or the macro arguments.
Comment field---contains a comment that explains the meaning of the statement; does not affect program execution.

The label field and the comment field are optional. The label field ends with a colon (:) and the comment field begins with a semicolon (;). The operand field must conform to the format of the instruction, directive, or macro specified in the operator field.

Although statement fields can be separated by either a space or a tab (see Table 3-2), formatting statements with the tab character is recommended for consistency and clarity and is a Digital convention.

Field Begins in Column Tab Characters to Reach Column

Label 1 0

Operator 9 1

Operand 17 2

Comment 41 5

Field	Begins in Column	Tab Characters to Reach Column
Label	1	0
Operator	9	1
Operand	17	2
Comment	41	5

For example:

.TITLE ROUT1 .ENTRY START,^M<> ; Beginning of routine CLRL R0 ; Clear register LABT: SUBL3 #10,4(AP),R2 ; Subtract 10 LAB2: BRB CONT ; Branch to another routine

Continue a single statement on several lines by using a hyphen (-) as the last nonblank character before the comment field, or at the end of a line (when there is no comment). For example:

LAB1: MOVAL W^BOO$AL_VECTOR,- ; Save boot driver RPB$L_IOVEC(R7)

VAX MACRO treats the preceding statement as equivalent to the following statement:

LAB1: MOVAL W^BOO$AL_VECTOR,RPB$L_IOVEC(R7) ; Save boot driver

A statement can be continued at any point. Do not continue permanent and user-defined symbol names on two lines. If a symbol name is continued and the first character on the second line is a tab or a blank, the symbol name is terminated at that character. Section 3.3 describes symbols in detail.

Note that when a statement occurs in a macro definition (see Chapter 4 and Chapter 6), the statement cannot contain more than 1000 characters.

Blank lines are legal, but they have no significance in the source program except that they terminate a continued line.

The following sections describe each of the statement fields in detail.

2.1 Label Field

A label is a user-defined symbol that identifies a location in the program. The symbol is assigned a value equal to the location counter where the label occurs. The user-defined symbol name can be up to 31 characters long and can contain any alphanumeric character and the underscore (_), dollar sign ($), and period (.) characters. See Section 3.3.2 for a description of the rules for forming user-defined symbol names in more detail.

If a statement contains a label, the label must be in the first field on the line.

A label is terminated by a colon (:) or a double colon (::). A single colon indicates that the label is defined only for the current module (an internal symbol). A double colon indicates that the label is globally defined; that is, the label can be referenced by other object modules.

Once a label is defined, it cannot be redefined during the source program. If a label is defined more than once, VAX MACRO displays an error message when the label is defined and again when it is referenced.

If a label extends past column 7, place it on a line by itself so that the following operator field can start in column 9 of the next line.

The following example illustrates some of the ways you can define labels:

EXP: .BLKL 50 ; Table stores expected values DATA:: .BLKW 25 ; Data table accessed by store ; routine in another module EVAL: CLRL R0 ; Routine evaluates expressions ERROR_IN_ARG: ; The arg-list contains an error INCL R0 ; increment error count TEST:: MOVO EXP,R1 ; This tests routine ; referenced externally TEST1: BRW EXIT ; Go to exit routine

The label field is also used for the symbol in a direct assignment statement (see Section 3.8).

2.2 Operator Field

The operator field specifies the action to be performed by the statement. This field can contain an instruction, an assembler directive, or a macro call.

When the operator is an instruction, VAX MACRO generates the binary code for that instruction in the object module. The binary codes are listed in Appendix D; the instruction set is described in Chapter 9. When the operator is a directive, VAX MACRO performs certain control actions or processing operations during source program assembly. The assembler directives are described in Chapter 6. When the operator is a macro call, VAX MACRO expands the macro. Macro calls are described in Chapter 4 and in Chapter 6 (.MACRO directive).

Use either a space or a tab character to terminate the operator field; however, the tab is the recommended termination character.

2.3 Operand Field

The operand field can contain operands for instructions or arguments for either assembler directives or macro calls.

Operands for instructions identify the memory locations or the registers that are used by the machine operation. These operands specify the addressing mode for the instruction, as described in Chapter 5. The operand field for a specific instruction must contain the number of operands required by that instruction. See Chapter 9 for descriptions of the instructions and their operands.

Arguments for a directive must meet the format requirements of that directive. Chapter 6 describes the directives and the format of their arguments.

Operands for a macro must meet the requirements specified in the macro definition. See the description of the .MACRO directive in Chapter 6.

If two or more operands are specified, they must be separated by commas (,). VAX MACRO also allows a space or tab to be used as a separator for arguments to any directive that does not accept expressions (see Section 3.5 for a discussion of expressions). However, a comma is required to separate operands for instructions and for directives that accept expressions as arguments.

The semicolon that starts the comment field terminates the operand field. If a line does not have a comment field, the operand field is terminated by the end of the line.

2.4 Comment Field

The comment field contains text that explains the function of the statement. Every line of code should have a comment. Comments do not affect assembly processing or program execution. You can cause user-written messages to be displayed during assembly by the .ERROR, .PRINT, and .WARN directives (see descriptions in Chapter 6).

The comment field must be preceded by a semicolon; it is terminated by the end of the line. The comment field can contain any printable ASCII character (see Appendix A).

To continue a lengthy comment to the next line, write the comment on the next line and precede it with another semicolon. If a comment does not fit on one line, it can be continued on the next, but the continuation must be preceded by another semicolon. A comment can appear on a line by itself.

Write the text of a comment to convey the meaning rather than the action of the statement. The instruction MOVAL BUF_PTR_1,R7, for example, should have a comment such as "Get pointer to first buffer," not "Move address of BUF_PTR_1 to R7."

For example:

MOVAL STRING_DES_1,R0 ; Get address of string ; descriptor MOVZWL (R0),R1 ; Get length of string MOVL 4(R0),R0 ; Get address of string

Contents

Index

privacy and legal statement

4515PRO.HTML

Internet	openvmsdoc@zko.mts.dec.com
Fax	603 884-0120, Attention: OSSG Documentation, ZKO3-4/U08
Mail	Compaq Computer Corporation OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

Ctrl/ x	A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.
PF1 x	A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.
`[Return]`	In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.) In the HTML version of this document, this convention appears as brackets, rather than a box.
...	A horizontal ellipsis in examples indicates one of the following possibilities: Additional optional arguments in a statement have been omitted. The preceding item or items can be repeated one or more times. Additional parameters, values, or other information can be entered.
. . .	A vertical ellipsis indicates the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.
( )	In command format descriptions, parentheses indicate that you must enclose the options in parentheses if you choose more than one.
[ ]	In command format descriptions, brackets indicate optional elements. You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)
[\|]	In command format descriptions, vertical bars separating items inside brackets indicate that you choose one, none, or more than one of the options.
{ }	In command format descriptions, braces indicate required elements; you must choose one of the options listed.
bold text	This text style represents the introduction of a new term or the name of an argument, an attribute, or a reason.
italic text	Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where dd represents the predefined code for the device type).
UPPERCASE TEXT	Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
Monospace text	Monospace type indicates code examples and interactive screen displays. In the C programming language, monospace type in text identifies the following elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.
-	A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.
numbers	All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.