 |
VAX MACRO and Instruction Set Reference Manual
.IRPC
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.
.LIBRARY
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.
Compaq 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
|
.LINK
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
| #1 |
.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:
| #2 |
$ LINK MYPROG, SYS$LIBRARY:MYLIB /INCLUDE=(MOD1, MOD2, MOD6)
|
| #3 |
.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:
| #4 |
.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
|
.LIST
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.
.LONG
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
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
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
- 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.
- 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.
- 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
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
- 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.
- 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.
.MCALL
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.
Note
.MCALL is provided for compatibility with MACRO-11; with one exception,
Compaq recommends that you not use it. When VAX MACRO finds an unknown
symbol in the opcode field, it automatically searches all macro
libraries. If it finds the symbol in a library, it uses the macro
definition and expands the macro reference. If VAX MACRO does not find
the symbol in the library, it displays an error message.
You must use .MCALL when a macro has the same name as an opcode (see
description of .MACRO).
|
Example
|
.MCALL INSQUE ; Substitute macro in
; library for INSQUE
; instruction
|
.MDELETE
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
|
.MEXIT
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
- When .MEXIT occurs in a repeat block, the assembler terminates the
current repetition of the range and suppresses further expansion of the
repeat range.
- When macros or repeat blocks are nested, .MEXIT exits to the next
higher level of expansion.
- 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.
|
