[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

VAX MACRO and Instruction Set Reference Manual


Previous Contents Index

The assembler automatically defines two program sections: the absolute program section and the unnamed (or blank) program section. Any symbol definitions that appear before any instruction, data, or .PSECT directive are placed in the absolute program section. Any instructions or data that appear before the first named program section is defined are placed in the unnamed program section. Any .PSECT directive that does not include a program section name specifies the unnamed program section.

A maximum of 254 user-defined, named program sections can be defined.

When the assembler encounters a .PSECT directive that specifies a new program section name, it creates a new program section and stores the name, attributes, and alignment of the program section. The assembler includes all data and instructions that follow the .PSECT directive in that program section until it encounters another .PSECT directive. The assembler starts all program sections at a location counter of 0, which is relocatable.

If the assembler encounters a .PSECT directive that specifies the name of a previously defined program section, it stores the new data or instructions after the last entry in the previously defined program section. The location counter is set to the value of the location counter at the end of the previously defined program section. You need not list the attributes when continuing a program section but any attributes that are listed must be the same as those previously in effect for the program section. A continuation of a program section cannot contain attributes conflicting with those specified in the original .PSECT directive.

The attributes listed in the .PSECT directive only describe the contents of the program section. The assembler does not check to ensure that the contents of the program section actually include the attributes listed. However, the assembler and the linker do check that all program sections with the same name have exactly the same attributes. The assembler and linker display an error message if the program section attributes are not consistent.

Program section names are independent of local symbol, global symbol, and macro names. You can use the same symbolic name for a program section and for a local symbol, global symbol, or macro name.

Notes

  1. The .ALIGN directive cannot specify an alignment greater than that of the current program section; consequently, .PSECT should specify the largest alignment needed in the program section. For efficiency of execution, an alignment of longword or larger is recommended for all program sections that have longword data.
  2. The attributes of the default absolute and the default unnamed program sections are listed in the following table. Note that the program section names include the periods (.) and enclosed spaces.
    Program SectionName Attributes and Alignment
    . ABS . NOPIC,USR,CON,ABS,LCL,NOSHR,NOEXE, NORD,NOWRT,NOVEC,BYTE
    . BLANK . NOPIC,USR,CON,REL,LCL,NOSHR,EXE,
    RD,WRT,NOVEC,BYTE

Example


.PSECT  CODE,NOWRT,EXE,LONG     ; Program section to contain 
                                ;   executable code 
.PSECT  RWDATA,WRT,NOEXE,QUAD 
                                ; Program section to contain 
                                ;   modifiable data 
      


.QUAD

Quadword storage directive

Format

.QUAD literal

.QUAD symbol


Parameters

literal

Any constant value. This value can be preceded by ^O, ^B, ^X, or ^D to specify the radix as octal, binary, hexadecimal, or decimal, respectively; or it can be preceded by ^A to specify the ASCII text operator. Decimal is the default radix.

symbol

A symbol defined elsewhere in the program. This symbol results in a sign-extended, 32-bit value being stored in a quadword.

Description

.QUAD generates 64 bits (8 bytes) of binary data.

Note

.QUAD is like .OCTA and different from other data storage directives (.BYTE, .WORD, and .LONG) in that it does not evaluate expressions and that it accepts only one value. It does not accept a list.


Example


.QUAD   ^A'..ASK?..'           ; Each ASCII character is stored 
                               ;   in a byte 
.QUAD   0                      ; QUAD 0 
.QUAD   ^X0123456789ABCDEF     ; QUAD hex value specified 
.QUAD   ^B1111000111001101     ; QUAD binary value specified 
.QUAD   LABEL                  ; LABEL has a 32-bit, 
                               ;   zero-extended value. 
      


.REFn

Operand generation directives

Format

.REF1 operand

.REF2 operand

.REF4 operand

.REF8 operand

.REF16 operand


Parameter

operand

An operand of byte, word, longword, quadword, or octaword context, respectively.

Description

VAX MACRO has the following five operand generation directives that you can use in macros to define new opcodes:
Directive Function
.REF1 Generates a byte operand
.REF2 Generates a word operand
.REF4 Generates a longword operand
.REF8 Generates a quadword operand
.REF16 Generates an octaword operand

The .REFn directives are provided for compatibility with VAX MACRO Version 1.0. Because the .OPDEF directive provides greater functionality and is easier to use than .REFn, you should use .OPDEF instead of .REFn.


Example


.MACRO  MOVL3 A,B,C 
.BYTE   ^XFF,^XA9 
.REF4   A                    ; This operand has longword context 
.REF4   B                    ; This operand has longword context 
.REF4   C                    ; This operand has longword context 
.ENDM   MOVL3 
 
MOVL3   R0,@LAB-1,(R7)+[R10] 
      

This example uses .REF4 to create a new instruction, MOVL3, which uses the reserved opcode FF. See the example in .OPDEF for a preferred method to create a new instruction.


.REPEAT

Repeat block directive

Format

.REPEAT expression

range

.ENDR


Parameters

expression

An expression whose value controls the number of times the range is to be assembled within the program. When the expression is less than or equal to zero, the repeat block is not assembled. The expression must be absolute and must not contain any undefined symbols (see Section 3.5).

range

The source text to be repeated the number of times specified by the value of the expression. The repeat block can contain macro definitions, indefinite repeat blocks, or other repeat blocks. .MEXIT is legal within the range.

Description

.REPEAT repeats a block of code a specified number of times, in line with other source code. The .ENDR directive specifies the end of the range.

Note

The alternate form of .REPEAT is .REPT.


Example

The macro definition is as follows:


        .MACRO  COPIES  STRING,NUM 
        .REPEAT NUM 
        .ASCII  /STRING/ 
        .ENDR 
        .BYTE   0 
        .ENDM   COPIES 
      

The macro calls and expansions of the macro defined previously are as follows:


        COPIES  <ABCDEF>,5 
        .REPEAT 5 
        .ASCII  /ABCDEF/ 
        .ENDR 
        .ASCII  /ABCDEF/ 
        .ASCII  /ABCDEF/ 
        .ASCII  /ABCDEF/ 
        .ASCII  /ABCDEF/ 
        .ASCII  /ABCDEF/ 
        .BYTE   0 
 
 VARB = 3 
        COPIES  <HOW MANY TIMES>,VARB 
        .REPEAT 3 
        .ASCII  /HOW MANY TIMES/ 
        .ENDR 
        .ASCII  /HOW MANY TIMES/ 
        .ASCII  /HOW MANY TIMES/ 
        .ASCII  /HOW MANY TIMES/ 
        .BYTE   0 
      


.RESTORE_PSECT

Restore previous program section context directive

Format

.RESTORE_PSECT


Description

.RESTORE_PSECT retrieves the program section from the top of the program section context stack, an internal stack in the assembler. If the stack is empty when .RESTORE_PSECT is issued, the assembler displays an error message. When .RESTORE_PSECT retrieves a program section, it restores the current location counter to the value it had when the program section was saved. The local label block is also restored if it was saved when the program section was saved. See the description of .SAVE_PSECT for more information.

Note

The alternate form of .RESTORE_PSECT is .RESTORE.

Example


      

.RESTORE_PSECT and .SAVE_PSECT are especially useful in macros that define program sections. The macro definition in the following example saves the current program section context and defines new program sections. Then, it restores the saved program section. If the macro did not save and restore the program section context each time the macro was invoked, the program section would change.


        .MACRO  INITD                  ; Initialize symbols 
                                       ;   and data areas 
        .SAVE_PSECT                    ; Save the current PSECT 
        .PSECT  SYMBOLS,ABS            ; Define new PSECT 
HELP_LEV=2                             ; Define symbol 
MAXNUM=100                             ; Define symbol 
RATE1=16                               ; Define symbol 
RATE2=4                                ; Define symbol 
        .PSECT  DATA,NOEXE,LONG        ; Define another PSECT 
TABL:   .BLKL   100                    ; 100 longwords in TABL 
TEMP:   .BLKB   16                     ; More storage 
        .RESTORE_PSECT                 ; Restore the PSECT 
                                       ;   in effect when 
                                       ;   MACRO is invoked 
        .ENDM 
      


.SAVE_PSECT

Save current program section context directive

Format

.SAVE_PSECT [LOCAL_BLOCK]


Parameter

LOCAL_BLOCK

An optional keyword that specifies that the current local label is to be saved with the program section context.

Description

.SAVE_PSECT stores the current program section context on the top of the program section context stack, an internal assembler stack. It leaves the current program section context in effect. The program section context stack can hold 31 entries. Each entry includes the value of the current location counter and the maximum value assigned to the location counter in the current program section. If the stack is full when .SAVE_PSECT is encountered, an error occurs.

.SAVE_PSECT and .RESTORE_PSECT are especially useful in macros that define program sections. See the description of .RESTORE_PSECT for another example using .SAVE_PSECT.

Note

The alternate form of .SAVE_PSECT is .SAVE.


Example


The macro definition is as follows: 
 
        .MACRO  ERR_MESSAGE,TEXT         ; Set up lists of messages 
                                         ;   and pointers 
                                         ; 
        .IIF    NOT_DEFINED      MESSAGE_INDEX, MESSAGE_INDEX=0 
        .SAVE_PSECT - 
                LOCAL_BLOCK              ; Keep local labels 
        .PSECT  MESSAGE_TEXT             ; List of error messages 
MESSAGE:: 
        .ASCIC  /TEXT/ 
        .PSECT  MESSAGE_POINTERS         ; Addresses of error 
        .ADDRESS -                       ;   messages 
                MESSAGE                  ; Store one pointer 
        .RESTORE_PSECT                   ; Get back local labels 
        PUSHL   #MESSAGE_INDEX           ; 
        CALLS   #1,PRINT_MESS            ; Print message 
MESSAGE_INDEX=MESSAGE_INDEX+1 
        .ENDM   ERR_MESSAGE 
      


Macro call: 
 
RESETS: CLRL    R4 
        BLBC    R0,30$ 
        ERR_MESSAGE     <STRING TOO SHORT> ; Add "STRING TOO SHORT" 
                                           ;   to list of error 
30$:    RSB                                ;   messages 
 
      

By using .SAVE_PSECT LOCAL_BLOCK, the local label 30$ is defined in the same local label block as the reference to 30$. If a local label is not defined in the block in which it is referenced, the assembler produces the following error message:


%MACRO-E-UNDEFSYM, Undefined Symbol
      


.SHOW

Listing directives

Format

.SHOW [argument-list]

.NOSHOW [argument-list]


Parameter

argument-list

One or more of the optional symbolic arguments defined in Table 6-8. You can use either the long form or the short form of the arguments. You can use each argument alone or in combination with other arguments. If you specify multiple arguments, you must separate them by commas (,), tabs, or spaces. If any argument is not specifically included in a listing control statement, the assembler assumes its default value (SHOW or NOSHOW) throughout the source program.

Table 6-8 .SHOW and .NOSHOW Symbolic Arguments
Long Form Short Form Default Function
BINARY MEB NOSHOW Lists macro and repeat block expansions that generate binary code. BINARY is a subset of EXPANSIONS.
CALLS MC SHOW Lists macro calls and repeat block specifiers.
CONDITIONALS CND SHOW Lists unsatisfied conditional code associated with the conditional assembly directives.
DEFINITIONS MD SHOW Lists macro and repeat range definitions that appear in an input source file.
EXPANSIONS ME NOSHOW Lists macro and repeat range expansions.


Description

.SHOW and .NOSHOW specify listing control options in the source text of a program. You can use .SHOW and .NOSHOW with or without an argument list.

When you use them with an argument list, .SHOW includes and .NOSHOW excludes the lines specified in Table 6-8. .SHOW and .NOSHOW control the listing of the source lines that are in conditional assembly blocks (see the description of .IF), macros, and repeat blocks.

When you use them without arguments, these directives alter the listing level count. The listing level count is initialized to 0. Each time .SHOW appears in a program, the listing level count is incremented; each time .NOSHOW appears in a program, the listing level count is decremented.

When the listing level count is negative, the listing is suppressed (unless the line contains an error). Conversely, when the listing level count is positive, the listing is generated. When the count is 0, the line is either listed or suppressed, depending on the value of the listing control symbolic arguments.

Notes

  1. The listing level count allows macros to be listed selectively; a macro definition can specify .NOSHOW at the beginning to decrement the listing count and can specify .SHOW at the end to restore the listing count to its original value.
  2. The alternate forms of .SHOW and .NOSHOW are .LIST and .NLIST.

Example


        .MACRO  XX 
          . 
          . 
          . 
        .SHOW                   ; List next line 
X=. 
        .NOSHOW                 ; Do not list remainder 
          .                     ;   of macro expansion 
          . 
          . 
        .ENDM 
 
        .NOSHOW EXPANSIONS      ; Do not list macro 
                                ;   expansions 
        XX 
X=. 
      


.SIGNED_BYTE

Signed byte data directive

Format

.SIGNED_BYTE expression-list


Parameters

expression-list

An expression or list of expressions separated by commas (,). You have the option of following each expression with a repetition factor delimited by square brackets ([]).

An expression followed by a repetition factor has the format:

expression1[expression2] 

expression1

An expression that specifies the value to be stored. The value must be in the range --128 to +127.

[expression2]

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

Description

.SIGNED_BYTE is equivalent to .BYTE, except that VAX MACRO indicates that the data is signed in the object module. The linker uses this information to test for overflow conditions.

Note

Specifying .SIGNED_BYTE allows the linker to detect overflow conditions when the value of the expression is in the range of 128 to 255. Values in this range can be stored as unsigned data but cannot be stored as signed data in a byte.


Example


.SIGNED_BYTE   LABEL1-LABEL2   ;  Data must fit 
.SIGNED_BYTE   ALPHA[20]       ;    in byte 
      


.SIGNED_WORD

Signed word storage directive

Format

.SIGNED_WORD expression-list


Parameters

expression-list

An expression or list of expressions separated by commas (,). You have the option of following each expression with a repetition factor delimited by square brackets ([]).

An expression followed by a repetition factor has the format:

expression1[expression2] 

expression1

An expression that specifies the value to be stored. The value must be in the range --32,768 to +32,767.

[expression2]

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

Description

.SIGNED_WORD is equivalent to .WORD except that the assembler indicates that the data is signed in the object module. The linker uses this information to test for overflow conditions. .SIGNED_WORD is useful after the case instruction to ensure that the displacement fits in a word.

Note

Specifying .SIGNED_WORD allows the linker to detect overflow conditions when the value of the expression is in the range of 32,768 to 65,535. Values in this range can be stored as unsigned data but cannot be stored as signed data in a word.


Example


        .MACRO  CASE,SRC,DISPLIST,TYPE=W,LIMIT=#0,NMODE=S^#,?BASE,?MAX 
                                        ; MACRO to use CASE instruction, 
                                        ;   SRC is selector, DISPLIST 
                                        ;   is list of displacements, TYPE 
                                        ;   is B (byte) W (word) L (long), 
                                        ;   LIMIT is base value of selector 
        CASE'TYPE       SRC,LIMIT,NMODE'<<MAX-BASE>/2>-1 
                                        ; Case instruction 
BASE:                                   ; Local label specifying base 
        .IRP   EP,<DISPLIST>            ;   to set up offset list 
        .SIGNED_WORD   EP-BASE          ; Offset list 
        .ENDR                           ; 
MAX:                                    ; Local label used to count 
        .ENDM   CASE                    ;   args 
 
        CASE    IVAR   <ERR_PROC,SORT,REV_SORT>         ; If IVAR=0, error 
        CASEW   IVAR,#0,S^#<<30001$-30000$>/2>-1 
 
30000$:                                 ; Local label specifying base 
        .SIGNED_WORD    ERR_PROC-30000$ ; Offset list 
        .SIGNED_WORD    SORT-30000$     ; Offset list 
        .SIGNED_WORD    REV_SORT-30000$ ; Offset list 
30001$:                                 ; Local label used to count args 
                                        ; =1, forward sort;  =2, backward 
                                        ;   sort 
 
        CASE    TEST    <TEST1,TEST2,TEST3>,L,#1 
        CASEL   TEST,#1,S^#<<30003$-30002$>/2>-1 
30002$:                                 ; Local label specifying base 
        .SIGNED_WORD    TEST1-30002$    ; Offset list 
        .SIGNED_WORD    TEST2-30002$    ; Offset list 
        .SIGNED_WORD    TEST3-30002$    ; Offset list 
30003$:                                 ; Local label used to count args 
                                        ; Value of TEST can be 1, 2, or 3 
 
      

In this example, the CASE macro uses .SIGNED_WORD to create a CASEB, CASEW, or CASEL instruction.


Previous Next Contents Index

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
4515PRO_011.HTML