Updated: 11 December 1998

VAX MACRO and Instruction Set Reference Manual

Indefinite repeat character directive

Format

.IRPC symbol,<STRING>

.

.

.

range

.

.

.

.ENDR

Parameters

symbol

A formal argument that is successively replaced with the specified characters enclosed in angle brackets (<>). If no formal argument is specified, the assembler displays an error message.

<STRING>

A sequence of characters enclosed in angle brackets and used in the expansion of the indefinite repeat range. Although the angle brackets are required only when the string contains separating characters, their use is recommended for legibility.

range

The block of source text to be repeated once for each occurrence of a character in the list. The range can contain macro definitions and repeat ranges. .MEXIT is legal within the range.

Description

.IRPC is similar to .IRP except that .IRPC permits single-character substitution rather than argument substitution. On each iteration of the indefinite repeat range, the formal argument is replaced with each successive character in the specified string. The .ENDR directive specifies the end of the range.

.IRPC is analogous to a macro definition with only one formal argument. At each expansion of the repeat block, this formal argument is replaced with successive characters from the actual argument string. The directive and its range are coded in line within the source program and do not require calling the macro by name.

.IRPC can appear either inside or outside another macro definition, indefinite repeat block, or repeat block (see description of .REPEAT).

Example

The macro definition is as follows:

      .MACRO  HASH_SYM        SYMBOL 
      .NCHR   HV,<SYMBOL> 
      .IRPC   CHR,<SYMBOL> 
HV = HV+^A?CHR? 
      .ENDR 
      .ENDM   HASH_SYM 
      

The macro call and expansion of the macro defined previously is as follows:

      HASH_SYM        <MOVC5> 
      .NCHR   HV,<MOVC5> 
      .IRPC   CHR,<MOVC5> 
HV = HV+^A?CHR? 
      .ENDR 
HV = HV+^A?M? 
HV = HV+^A?O? 
HV = HV+^A?V? 
HV = HV+^A?C? 
HV = HV+^A?5? 
      

This example uses the .NCHR directive to count the number of characters in an actual argument.

Macro library directive

Format

.LIBRARY macro-library-name

Parameters

macro-library-name

A delimited string that is the file specification of a macro library.

Description

.LIBRARY adds a name to the macro library list that is searched whenever a .MCALL or an undefined opcode is encountered. The libraries are searched in the reverse order in which they were specified to the assembler.

If you omit any information from the macro-library-name argument, default values are assumed. The device defaults to your current default disk; the directory defaults to your current default directory; the file type defaults to MLB.

Digital recommends that libraries be specified in the MACRO command line with the /LIBRARY qualifier rather than with the .LIBRARY directive. The .LIBRARY directive makes moving files cumbersome.

Example

.LIBRARY   /DISK:[TEST]USERM/     ; DISK:[TEST]USERM.MLB 
.LIBRARY   ?DISK:SYSDEF.MLB?      ; DISK:SYSDEF.MLB 
.LIBRARY   \CURRENT.MLB\          ; Uses default disk and directory 
      

Linker option record directive

Format

.LINK "file-spec" [/qualifier[=(module-name[,...])],...]

Parameters

file-spec[,...]

A delimited string that specifies one or more input files. The delimiters can be any matching pair of printable characters except the space, tab, 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.

The input files can be object modules to be linked, or shareable images to be included in the output image. Input files can also be libraries containing external references or specific modules for inclusion in the output image. The linker will search the libraries for the external references. If you specify multiple input files, separate the file specifications with commas (,).

If you do not specify a file type in an input file specification, the linker supplies default file types, based on the nature of the file. All object modules are assumed to have file types of OBJ.

Note that the input file specifications must be correct at link time. Make your references explicit, so that if the object module created by VAX MACRO is linked in a directory other than the one in which it was created, the linker will still be able to find the files referenced in the .LINK directive.

No wildcard characters are allowed in the file specification.

File Qualifiers

/INCLUDE=(module-name[,...])

Indicates that the associated input file is an object library or shareable image library, and that only the module names specified are to be unconditionally included as input to the linker.

At least one module name must be specified. If you specify more than one module name, separate the names with commas (,) and enclose the list in parentheses.

No wildcard characters are allowed in the module name specifications. Module names may not be longer than 31 characters, the maximum length of a VAX MACRO symbol.

/LIBRARY

Indicates that the associated input file is a library to be searched for modules to resolve any undefined symbols in the input files.

If the associated input file specification does not include a file type, the linker assumes the default file type of OLB. You can use both /INCLUDE and /LIBRARY to qualify a file specification. If you specify both /INCLUDE and /LIBRARY, the library is subsequently searched for unresolved references. In this case, the explicit inclusion of modules occurs first; then the linker searches the library for unresolved references.

/SELECTIVE_SEARCH

Directs the linker to add to its symbol table only those global symbols that are defined in the specified file and are currently unresolved. If /SELECTIVE_SEARCH is not specified, the linker includes all symbols from that file in its global symbol table.

/SHAREABLE

Requests that the linker include a shareable image file. No wildcard characters are allowed in the file specification.

The following table contains the abbreviations of the qualifiers for the .LINK directive. Note that to ensure readability, as well as compatibility with future releases, it is recommended that you use the full names of the qualifiers.

Abbreviation	Qualifier
/I	/INCLUDE
/L	/LIBRARY
/SE	/SELECTIVE_SEARCH
/SH	/SHAREABLE

Description

The .LINK directive allows you to include linker option records in an object module produced by VAX MACRO. The qualifiers for the .LINK directive perform functions similar to the functions performed by the same qualifiers for the DCL command LINK.

You should use the .LINK directive for references that are not linker defaults, but that you always want to include in a particular image. Using the .LINK directive enables you to avoid having to explicitly name these references in the DCL command LINK.

For detailed information on the qualifiers to the DCL command LINK, see the OpenVMS DCL Dictionary. For a complete discussion of the operation of the linker itself, see the OpenVMS Linker Utility Manual.

Examples

.LINK "SYS$LIBRARY:MYLIB" /INCLUDE=(MOD1, MOD2, MOD6) 
      

This statement, when included in the file MYPROG.MAR, causes the assembler to request that MYPROG.OBJ be linked with modules MOD1, MOD2, and MOD6 in the library SYS$LIBRARY:MYLIB.OLB (where SYS$LIBRARY is a logical name for the disk and directory in which MYLIB.OLB is listed). The library is not searched for other unresolved references. The statement is equivalent to linking the file with the DCL command:

$ LINK MYPROG, SYS$LIBRARY:MYLIB /INCLUDE=(MOD1, MOD2, MOD6) 
      

.LINK \SYS$LIBRARY:MYOBJ\                       ; Link with object module 
                                                ;   SYS$LIBRARY:MYOBJ.OBJ 
 
.LINK 'SYS$LIBRARY:YOURLIB' /LIBRARY            ; Search object library 
                                                ;   SYS$LIBRARY:YOURLIB.OLB 
                                                ;   for unresolved references 
 
.LINK *SYS$LIBRARY:MYSTB.STB* /SELECTIVE_SEARCH ; Search symbol table 
                                                ;   SYS$LIBRARY:MYSTB.STB 
                                                ;   for unresolved references 
 
.LINK "SYS$LIBRARY:MYSHR.EXE" /SHAREABLE        ; Link with shareable image 
                                                ;   SYS$LIBRARY:MYSHR.EXE 
      

To increase efficiency and performance, include several related input files in a single .LINK directive. The following example shows how the five options illustrated previously can be included in one statement:

.LINK   'SYS$LIBRARY:MYOBJ',- 
        'SYS$LIBRARY:YOURLIB' /LIBRARY,- 
        'SYS$LIBRARY:MYLIB' /INCLUDE=(MOD1, MOD2, MOD6),- 
        'SYS$LIBRARY:MYSTB.STB' /SELECTIVE_SEARCH,- 
        'SYS$LIBRARY:MYSHR.EXE' /SHAREABLE 
      

Listing directive

Format

.LIST [argument-list]

Parameter

argument-list

One or more of the symbolic arguments defined in Table 6-8. You can use either the long form or the short form of the arguments. If multiple arguments are specified, separate them with commas (,), spaces, or tabs.

Description

.LIST is equivalent to .SHOW. See the description of .SHOW for more information.

Longword storage directive

Format

.LONG expression-list

Parameters

expression-list

One or more 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.

[expression2]

An expression that specifies the number of times the value is 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

.LONG generates successive longwords (4 bytes) of data in the object module.

Example

LAB_3:  .LONG   LAB_3,^X7FFFFFFF,^A'ABCD' ; 3 longwords of data 
        .LONG   ^XF@4                     ; 1 longword of data 
        .LONG   0[22]                     ; 22 longwords of data 
      

Note

Each expression in the list must have a value that can be represented in 32 bits.

Macro definition directive

Format

.MACRO macro-name [formal-argument-list]

.

.

.

range

.

.

.

.ENDM [macro name]

Parameters

macro-name

The name of the macro to be defined; this name can be any legal symbol up to 31 characters long.

formal-argument-list

The symbols, separated by commas (,), to be replaced by the actual arguments in the macro call.

range

The source text to be included in the macro expansion.

Description

.MACRO begins the definition of a macro. It gives the macro name and a list of formal arguments (see Chapter 4). If the name specified is the same as the name of a previously defined macro, the previous definition is deleted and replaced with the new one. The .MACRO directive is followed by the source text to be included in the macro expansion. The .ENDM directive specifies the end of the range.

Macro names do not conflict with user-defined symbols. Both a macro and a user-defined symbol can have the same name.

When the assembler encounters a .MACRO directive, it adds the macro name to its macro name table and stores the source text of the macro (up to the matching .ENDM directive). No other processing occurs until the macro is expanded.

The symbols in the formal argument list are associated with the macro name and are limited to the scope of the definition of that macro. For this reason, the symbols that appear in the formal argument list can also appear elsewhere in the program.

Notes

1. If a macro has the same name as a VAX opcode, the macro is used instead of the instruction. This feature allows you to temporarily redefine an opcode.
2. If a macro has the same name as a VAX opcode and is in a macro library, you must use the .MCALL directive to define the macro. Otherwise, because the symbol is already defined (as the opcode), the assembler will not search the macro libraries.
3. You can redefine a macro with new source text during assembly by specifying a second .MACRO directive with the same name. Including a second .MACRO directive within the original macro definition causes the first macro call to redefine the macro. This feature is useful when a macro performs initialization or defines symbols, when an operation is performed only once. The macro redefinition can eliminate unneeded source text in a macro or it can delete the entire macro. The .MDELETE directive provides another way to delete macros.

Example

The macro definition is as follows:

        .MACRO  USERDEF 
        .PSECT  DEFIES,ABS 
MYSYM=  5 
HIVAL=  ^XFFF123 
LOWVAL= 0 
        .PSECT  RWDATA,NOEXE,LONG 
TABLE:  .BLKL   100 
LIST:   .BLKB   10 
        .MACRO  USERDEF                  ; Redefine it to null 
        .ENDM   USERDEF 
        .ENDM   USERDEF 
      

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

        USERDEF                          ; Should expand data 
        .PSECT  DEFIES,ABS 
MYSYM=  5 
HIVAL=  ^XFFF123 
LOWVAL= 0 
        .PSECT  RWDATA,NOEXE,LONG 
TABLE:  .BLKL   100 
LIST:   .BLKB   10 
        .MACRO  USERDEF                  ; Redefine it to null 
        .ENDM   USERDEF 
 
        USERDEF                          ; Should expand nothing 
      

In this example, when the macro is called the first time, it defines some symbols and data storage areas and then redefines itself. When the macro is called a second time, the macro expansion contains no source text.

Mask directive

Format

.MASK symbol[,expression]

Parameters

symbol

A symbol defined in an .ENTRY directive.

expression

A register save mask.

Description

.MASK reserves a word for a register save mask for a transfer vector. See the description of .TRANSFER for more information and for an example of .MASK.

Notes

1. If .MASK does not contain an expression, the assembler directs the linker to copy the register save mask specified in .ENTRY to the word reserved by .MASK.
2. If .MASK contains an expression, the assembler directs the linker to combine this expression with the register save mask specified in .ENTRY and store the result in the word reserved by .MASK. The linker performs an inclusive OR operation to combine the mask in the entry point and the value of the expression. Consequently, a register specified in either .ENTRY or .MASK will be included in the combined mask. See the description of .ENTRY for more information on entry masks.

Macro call directive

Format

.MCALL macro-name-list

Parameters

macro-name-list

A list of macros to be defined for this assembly. Separate the macro names with commas (,).

Description

.MCALL specifies the names of the system and user-defined macros that are required to assemble the source program but are not defined in the source file.

If any named macro is not found upon completion of the search (that is, if the macro is not defined in any of the macro libraries), the assembler displays an error message.

Example

.MCALL  INSQUE         ; Substitute macro in 
                       ;   library for INSQUE 
                       ;   instruction 
      

Macro deletion directive

Format

.MDELETE macro-name-list

Parameters

macro-name-list

A list of macros whose definitions are to be deleted. Separate the names with commas (,).

Description

.MDELETE deletes the definitions of specified macros. The number of macros actually deleted is printed in the assembly listing on the same line as the .MDELETE directive.

.MDELETE completely deletes the macro, freeing memory as necessary. Macro redefinition with .MACRO merely redefines the macro.

Example

.MDELETE     USERDEF,$SSDEF,ALTR 
      

Macro exit directive

Format

.MEXIT

Description

.MEXIT terminates a macro expansion before the end of the macro. Termination is the same as if .ENDM were encountered. You can use the directive within repeat blocks. .MEXIT is useful in conditional expansion of macros because it bypasses the complexities of nested conditional directives and alternate assembly paths.

Notes

1. When .MEXIT occurs in a repeat block, the assembler terminates the current repetition of the range and suppresses further expansion of the repeat range.
2. When macros or repeat blocks are nested, .MEXIT exits to the next higher level of expansion.
3. If .MEXIT occurs outside a macro definition or a repeat block, the assembler displays an error message.

Example

.MACRO   P0L0    N,A,B 
   .
   .
   .
.IF EQ  N                    ; Start conditional assembly block 
   .
   .
   .
.MEXIT                       ; Terminate macro expansion 
.ENDC                        ; End conditional assembly block 
   .
   .
   .
.ENDM   P0L0                 ; Normal end of macro 
      

In this example, if the actual argument for the formal argument N equals zero, the conditional block is assembled, and the macro expansion is terminated by .MEXIT.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

4515PRO_009.HTML