Document revision date: 30 March 2001

## VAX MACRO and Instruction Set Reference Manual

Previous | Contents | Index

## 5.4 Branch Mode

In branch mode, the address is stored as an implied displacement from the PC. This mode can be used only in branch instructions. The displacement for conditional branch instructions and the BRB instruction is stored in a byte. The displacement for the BRW instruction is stored in a word (2 bytes). A byte displacement allows a range of 127 bytes forward and 128 bytes backward. A word displacement allows a range of 32,767 bytes forward and 32,768 bytes backward. The displacement is relative to the updated PC, the byte past the byte or word where the displacement is stored. See Chapter 9 for more information on the branch instructions.

Format

`address`

### Parameters

> #### address

> An expression that represents an address.

### Example

    ADDL3   (R1)+,R0,TOTAL          ; Total values and set condition
                                    ;   codes
    BLEQ    LABEL1                  ; Branch to LABEL1 if result is
                                    ;   less than or equal to 0
    BRW     LABEL                   ; Branch unconditionally to LABEL

## Chapter 6
VAX MACRO Assembler Directives

The general assembler directives provide facilities for performing 11 types of functions. Table 6-1 lists these types of functions and their directives.

The macro directives provide facilities for performing eight categories of functions. Table 6-2 lists these categories and their associated directives. Chapter 4 describes macro arguments and string operators.

The remainder of this chapter describes both the general assembler directives and the macro directives, showing their formats and giving examples of their use. For ease of reference, the directives are presented in alphabetical order. Appendix C contains a summary of all assembler directives.

Table 6-1 Summary of General Assembler Directives
Category | Directives1
--- | ---
Listing control directives | .SHOW (.LIST) .NOSHOW(.NLIST) .TITLE .SUBTITLE (.SBTTL) .IDENT .PAGE
Message display directives | .PRINT .WARN .ERROR
Assembler option directives | .ENABLE (.ENABL) .DISABLE(.DSABL) .DEFAULT
Data storage directives | .BYTE .WORD .LONG .ADDRESS .QUAD .OCTA .PACKED .ASCII .ASCIC .ASCID .ASCIZ .F_FLOATING (.FLOAT) .D_FLOATING (.DOUBLE) .G_FLOATING .H_FLOATING .SIGNED_BYTE .SIGNED_WORD
Location control directives | .ALIGN .EVEN .ODD .BLKA .BLKB .BLKD .BLKF .BLKG .BLKH .BLKL .BLKO .BLKQ .BLKW .END
Program sectioning directives | .PSECT .SAVE_PSECT (.SAVE) .RESTORE_PSECT (.RESTORE)
Symbol control directives | .GLOBAL (.GLOBL) .EXTERNAL (.EXTRN) .DEBUG .WEAK
Routine entry point definition directives | .ENTRY .TRANSFER .MASK
Conditional and subconditional assembly block directives | .IF .ENDC .IF_FALSE (.IFF) .IF_TRUE (.IFT) .IF_TRUE_FALSE (.IFTF) .IIF
Cross-reference directives | .CROSS .NOCROSS
Instruction generation directives | .OPDEF .REF1 .REF2 .REF4 .REF8 .REF16
Linker option record directive | .LINK

1The alternate form, if any, is given in parentheses.

Table 6-2 Summary of Macro Directives
Category | Directives1
--- | ---
Macro definition directives | .MACRO .ENDM
Macro library directives | .LIBRARY .MCALL
Macro deletion directive | .MDELETE
Macro exit directive | .MEXIT
Argument attribute directives | .NARG .NCHR .NTYPE
Indefinite repeat block directives | .IRP .IRPC
Repeat block directives | .REPEAT (.REPT)
End range directive | .ENDR

1The alternate form, if any, is given in parentheses.

## .ADDRESS

> Address storage directive

### Format

> .ADDRESS address-list

### Parameter

> #### address-list

> A list of symbols or expressions, separated by commas (,), which VAX MACRO interprets as addresses. Repetition factors are not allowed.

### Description

> .ADDRESS stores successive longwords containing addresses in the object module. Compaq recommends that you use .ADDRESS rather than .LONG for storing address data to provide additional information to the linker. In shareable images, addresses that you specify with .ADDRESS produce position-independent code.

### Example

    TABLE:  .ADDRESS  LAB_4, LAB_3, ROUTTERM         ; Reference table

## .ALIGN

> Location counter alignment directive

### Format

> .ALIGN integer[,expression]

> .ALIGN keyword[,expression]

### Parameters

> #### integer

> An integer in the range 0 to 9. The location counter is aligned at an address that is the value of 2 raised to the power of the integer.

> #### keyword

> One of five keywords that specify the alignment boundary. The location counter is aligned to an address that is the next multiple of the following values:

> Keyword | Size (in Bytes)
> --- | ---
> BYTE | 2^0 = 1
> WORD | 2^1 = 2
> LONG | 2^2 = 4
> QUAD | 2^3 = 8
> PAGE | 2^9 = 512

> #### expression

> Specifies the fill value to be stored in each byte. The expression must not contain any undefined symbols and must be an absolute expression (see Section 3.5).

### Description

> .ALIGN aligns the location counter to the boundary specified by either an integer or a keyword.

Notes

1. The alignment that you specify in .ALIGN cannot exceed the alignment of the program section in which the alignment is attempted (see the description of .PSECT). For example, if you are using the default program section alignment (BYTE) and you specify .ALIGN with a word or larger alignment, the assembler displays an error message. fills the bytes skipped by the location counter (if any) with the value of that expression. Otherwise, the assembler fills the bytes with zeros.

2. Although most instructions can use byte alignment of data, execution speed is improved by the following alignments:

   Data Length | Alignment
   --- | ---
   Word | Word
   Longword | Longword
   Quadword | Quadword

### Example

    .ALIGN  BYTE,0      ; Byte alignment--fill with null
    .ALIGN  WORD        ; Word alignment
    .ALIGN  3,^A/ /     ; Quad alignment--fill with blanks
    .ALIGN  PAGE        ; Page alignment

## .ASCIx

> ASCII character storage directives

### Description

> VAX MACRO has the following four ASCII character storage directives:

> Directive | Function
> --- | ---
> ASCIC | Counted ASCII string storage
> ASCID | String-descriptor ASCII string storage
> ASCII | ASCII string storage
> ASCIZ | Zero-terminated ASCII string storage

> Each directive is followed by a string of characters enclosed in a pair of matching delimiters. The delimiters can be any printable character except the space or tab character, equal sign (=), semicolon (;), or left angle bracket (<). The character that you use as the delimiter cannot appear in the string itself. Although you can use alphanumeric characters as delimiters, use nonalphanumeric characters to avoid confusion.

> Any character except the null, carriage-return, and form-feed characters can appear within the string. The assembler does not convert lowercase alphabetic characters to uppercase.

> ASCII character storage directives convert the characters to their 8-bit ASCII value (see Appendix A) and store them one character to a byte.

> Any character, including the null, carriage-return, and form-feed characters, can be represented by an expression enclosed in angle brackets (<>) outside of the delimiters. You must define the ASCII values of null, carriage-return, and form-feed with a direct assignment statement. The ASCII character storage directives store the 8-bit binary value specified by the expression.

> ASCII strings can be continued over several lines. Use the hyphen (-) as the line continuation character and delimit the string on each line at both ends. Note that you can use a different pair of delimiters for each line. For example:

>     CR=13
>     LF=10

>            .ASCII       /ABC DEFG/
>            .ASCIZ       @Any character can be a delimiter@
>            .ASCIC       ? lowercase is not converted to UPPER?
>            .ASCII       ? this is a test!?<CR><KEY>(LF\TEXT)!Isn't it?!
>            .ASCII       \ Angle Brackets <are part <of> this> string \
>            .ASCII       / This string is continued / -
>                         \ on the next line \
>            .ASCII       <CR><KEY>(LF\TEXT)! this string includes an expression! -
>                         <128+CR>? whose value is a 13 plus 128?

## .ASCIC

> Counted ASCII string storage directive

### Format

> .ASCIC string

### Parameter

> #### string

> A delimited ASCII string.

### Description

> .ASCIC performs the same function as .ASCII, except that .ASCIC inserts a count byte before the string data. The count byte contains the length of the string in bytes. The length given includes any bytes of nonprintable characters outside the delimited string but excludes the count byte.

> .ASCIC is useful in copying text because the count indicates the length of the text to be copied.

### Example

    CR=13                                 ; Direct assignment statement
                                          ;   defines CR
           .ASCIC       #HELLO#<CR>       ; This counted ASCII string
                                          ;   is equivalent to the
           .BYTE        6                 ;   count followed by
           .ASCII       #HELLO#<CR>       ;   the ASCII string

## .ASCID

> String-descriptor ASCII string storage directive

### Format

> .ASCID string

### Parameter

> #### string

> A delimited ASCII string.

### Description

> .ASCID performs the same function as ASCII, except that .ASCID inserts a string descriptor before the string data. The string descriptor has the following format:

### Parameters

> #### length

> The length of the string (2 bytes).

> #### information

> Descriptor information (2 bytes) is always set to 010E.

> #### pointer

> Position-independent pointer to the string (4 bytes).

String descriptors are used in calling procedures (see the OpenVMS RTL String Manipulation (STR$) Manual).

### Example

    DESCR1:  .ASCID  /ARGUMENT FOR CALL/       ; String descriptor
    DESCR2:  .ASCID  /SECOND ARGUMENT/         ; Another string
                                               ;   descriptor
               .
               .
               .
             PUSHAL  DESCR1                    ; Put address of descriptors
             PUSHAL  DESCR2                    ;   on the stack
             CALLS   #2,STRNG_PROC             ; Call procedure

## .ASCII

> ASCII string storage directive

### Format

> .ASCII string

### Parameter

> #### string

> A delimited ASCII string.

### Description

> .ASCII stores the ASCII value of each character in the ASCII string or the value of each byte expression in the next available byte.

### Example

    CR=13                                   ; Assignment statements
    LF=10                                   ;   define CR and LF

           .ASCII   "DATE: 17-NOV-1988"     ; Delimiter is "
           .ASCII   /EOF/<CR><LF>       ; Delimiter is /

## .ASCIZ

> Zero-terminated ASCII string storage directive

### Format

> .ASCIZ string

### Parameter

> #### string

> A delimited ASCII string.

### Description

> .ASCIZ performs the same function as .ASCII, except that .ASCIZ appends a null byte as the final character of the string. When a list or text string is created with an .ASCIZ directive, you need only perform a search for the null character in the last byte to determine the end of the string.

### Example

     FF=12                                  ; Define FF

            .ASCIZ  /ABCDEF/                ; 6 characters in string,
                                            ;   7 bytes of data
            .ASCIZ  /A/<FF>/B/              ; 3 characters in strings

## .BLKx

> Block storage allocation directives

### Format

> .BLKA expression

> .BLKB expression

> .BLKD expression

> .BLKF expression

> .BLKG expression

> .BLKH expression

> .BLKL expression

> .BLKO expression

> .BLKQ expression

> .BLKW expression

### Parameter

> #### expression

> An expression specifying the amount of storage to be allocated. All the symbols in the expression must be defined and the expression must be an absolute expression (see Section 3.5). If the expression is omitted, a default value of 1 is assumed.

### Description

> VAX MACRO has the following 10 block storage directives.

> Directive | Function
> --- | ---
> .BLKA | Reserves storage for addresses (longwords).
> .BLKB | Reserves storage for byte data.
> .BLKD | Reserves storage for double-precision floating-point data (quadwords).
> .BLKF | Reserves storage for single-precision floating-point data (longwords).
> .BLKG | Reserves storage for G_floating data (quadwords).
> .BLKH | Reserves storage for H_floating data (octawords).
> .BLKL | Reserves storage for longword data.
> .BLKO | Reserves storage for octaword data.
> .BLKQ | Reserves storage for quadword data.
> .BLKW | Reserves storage for word data.

> Each directive reserves storage for a different data type. The value of the expression determines the number of data items for which VAX MACRO reserves storage. For example, .BLKL 4 reserves storage for 4 longwords of data and .BLKB 2 reserves storage for 2 bytes of data.

> The total number of bytes reserved is equal to the length of the data type times the value of the expression as follows:

> Directive | Number of Bytes Allocated
> --- | ---
> .BLKB | Value of expression
> .BLKW | 2 value of expression
> .BLKA | "
> .BLKF | 4 value of expression
> .BLKL | "
> .BLKD | 8 value of expression
> .BLKG | "
> .BLKQ | "
> .BLKH | 16 value of expression
> .BLKO | "

### Example

    .BLKB   15            ; Space for 15 bytes
    .BLKO   3             ; Space for 3 octawords (48 bytes)
    .BLKL   1             ; Space for 1 longword (4 bytes)
    .BLKF   <3*4>         ; Space for 12 single-precision
                          ;   floating-point values (48 bytes)

## .BYTE

> Byte storage directive

### Format

> .BYTE expression-list

### Parameter

> #### expression-list

> One or more expressions separated by commas (,). Each expression is first evaluated as a longword expression; then the value of the expression is truncated to 1 byte. The value of each expression should be in the range 0 to 255 for unsigned data or in the range -128 to +127 for signed data.

> Optionally, each expression can be followed by a repetition factor delimited by square brackets ([]). An expression followed by a repetition factor has the following format:

> `expression1[expression2]`

> #### expression1

> An expression that specifies the value to be stored.

> #### [expression2]

> An expression that specifies the number of times the value will be repeated. The expression must not contain any undefined symbols and it must be absolute (see Section 3.5). The square brackets are required.

### Description

> .BYTE generates successive bytes of binary data in the object module.

Notes

1. The assembler displays an error message if the high-order 3 bytes of the longword expression have a value other than 0 or ^XFFFFFF.
2. At link time, a relocatable expression can result in a value that exceeds 1 byte in length. In this case, the linker issues a truncation diagnostic message for the object module in question. For example:

       A:      .BYTE   A       ; Relocatable value 'A' will
                               ;   cause linker truncation
                               ;   diagnostic if the statement
                               ;   has a virtual address of 256
                               ;   or above

3. The .SIGNED_BYTE directive is the same as .BYTE except that the assembler displays a diagnostic message if a value in the range 128 to 255 is specified. See the description of .SIGNED_BYTE for more information.

### Example

    .BYTE   <1024-1000>*2           ; Stores a value of 48
    .BYTE   ^XA,FIF,10,65-<21*3>    ; Stores 4 bytes of data
    .BYTE   0                       ; Stores 1 byte of data
    .BYTE   X,X+3[5*4],Z            ; Stores 22 bytes of data

Previous | Next | Contents | Index

| privacy and legal statement |
4515PRO_006.HTML