HP OpenVMS Systems Documentation
HP OpenVMS MACRO Compiler
This appendix describes the invocation format of the MACRO Compiler for OpenVMS Systems and each of its qualifiers.
For OpenVMS Alpha and OpenVMS I64, the MACRO command defaults to /MIGRATION.
filespec[+...]Specifies a VAX MACRO assembly language source file to be compiled. If you specify more than one file, separate the file specifications with plus signs (+). File specifications separated by plus signs are concatenated into one input file and produce a single object file and, if indicated, a listing file.
Unlike the VAX assembler, the MACRO compiler does not support the creation of separate object files when the source files are separated by a comma (,).
You cannot include a wildcard character in a file specification. For each file specification, the compiler command supplies a default file type of MAR.
The compiler creates output files of one version higher than the highest version existing in the target directory.
The qualifiers to the MACRO/MIGRATION command serve as either command (global) qualifiers or positional qualifiers. A command qualifier affects all the files specified in the command. A positional qualifier affects only the file that it qualifies. All MACRO/MIGRATION qualifiers except /LIBRARY are usable as either command or positional qualifiers. The /LIBRARY qualifier is a positional qualifier only.
Many of the qualifiers take one or more arguments. If you specify only one argument, you can omit the parentheses.
The compiler supports most of the standard MACRO qualifiers. Some of these qualifiers have additional options unique to the compiler and some of them are missing one or more VAX MACRO options. The compiler also supports several qualifiers unique to the compiler. All of these qualifiers are shown in Table A-1.
Table A-1 Compiler Qualifiers Standard MACRO Qualifiers Unique Qualifiers /DEBUG /FLAG /DIAGNOSTICS /MACHINE /DISABLE 1 /OPTIMIZE /ENABLE 1 /PRESERVE /LIBRARY /RETRY_COUNT /LIST /SYMBOLS /OBJECT /TIE /SHOW /UNALIGNED /WARN
/NODEBUGIncludes or excludes local symbols in the symbol table or traceback information in the object module. You can specify one or more of the following options:
Option Description ALL Makes local symbols and traceback information in the object module available to the debugger. This qualifier is equivalent to /ENABLE=(DEBUG,TRACEBACK). NONE Makes local symbols and traceback information in the object module unavailable to the debugger. This qualifier is equivalent to /DISABLE=(DEBUG,TRACEBACK). SYMBOLS Makes all local symbols in the object module available and all traceback information unavailable to the debugger. This qualifier is equivalent to /ENABLE=SYMBOLS. TRACEBACK Makes traceback information in the object module available and local symbols unavailable to the debugger. This qualifier is equivalent to /ENABLE=TRACEBACK.
The default value for /DEBUG is ALL. The /DEBUG qualifier overrides /ENABLE=(DEBUG,TRACEBACK) or /DISABLE=(DEBUG,TRACEBACK), regardless of their order on the command line.
Debugging can be simplified by specifying /NOOPTIMIZE. This qualifier prevents the movement of generated code across source line boundaries.
For more information about debugging, see the HP OpenVMS Debugger Manual.
/NODIAGNOSTICS (default)Creates a file containing assembler messages and diagnostic information. If you omit the file specification, the default file name is the same as the source program; the default file type is DIA.
No wildcard characters are allowed in the file specification.
The diagnostics file is reserved for use with layered products, such as the VAX Language-Sensitive Editor (LSE).
/NODISABLEProvides initial settings for the compiler functions that can be controlled by the .DISABLE and .ENABLE MACRO directives.
Option Description DEBUG Excludes local symbol table information in the object file for use with the debugger. If the /DEBUG qualifier is also specified, it overrides /DISABLE=(DEBUG,TRACEBACK) or /ENABLE=(DEBUG,TRACEBACK), regardless of their order on the command line. FLAGGING Deactivates compiler flagging. GLOBAL Disables the assumption that undefined symbols are external symbols. OVERFLOW Deactivates production of overflow trap code for the following opcodes: ADD x, ADWC, INC x, ADAWI, SUB x, SBWC, DEC x, MNEG x, MUL x, CVT xy, (where x is greater than y, for example CVTLB), AOB xx, ACBL, and SOB xx. QUADWORD Disables support for quadword literal and address expressions. SUPPRESSION Prevents the listing of unreferenced symbols in the symbol table. TRACEBACK Disables the provision of traceback information to the debugger. If the /DEBUG qualifier is also specified, it overrides /DISABLE=(DEBUG,TRACEBACK) or /ENABLE=(DEBUG,TRACEBACK), regardless of their order on the command line.
By default, at compiler activation, FLAGGING, GLOBAL, and SUPPRESSION are enabled, and DEBUG, OVERFLOW, QUADWORD, and TRACEBACK are disabled.
The /NODISABLE qualifier has the same effect as omitting the /DISABLE qualifier. It can also be used to negate the effects of any /DISABLE qualifiers specified earlier in the command line.
If /DISABLE is used two or more times in the command line, the last /DISABLE will override all previous uses of /DISABLE. The options not specified in the final /DISABLE will revert to their default values.
Furthermore, if /ENABLE and /DISABLE are used in the same command line for the same option, /DISABLE will always prevail, regardless of its position in the command line.
Workaround: If you want to disable two or more options, specify them in the following way:
/NOENABLEProvides initial settings for the compiler functions that can be controlled by the .DISABLE and .ENABLE MACRO directives.
Option Description DEBUG Includes local symbol table information in the object file for use with the debugger. If the /DEBUG qualifier is also specified, it overrides /ENABLE=(DEBUG,TRACEBACK) or /DISABLE=(DEBUG,TRACEBACK), regardless of their order on the command line. FLAGGING Activates compiler flagging. GLOBAL Assumes undefined symbols are external symbols. OVERFLOW Activates production of overflow trap code for the following opcodes: ADD x, ADWC, INC x, ADAWI, SUB x, SBWC, DEC x, MNEG x, MUL x, CVT xy (where x is greater than y, for example CVTLB), AOB xx, ACBL, and SOB xx. QUADWORD Provides support for quadword literal and address expressions. SUPPRESSION Provides listing of unreferenced symbols in the symbol table. TRACEBACK Provides traceback information to the debugger. If the /DEBUG qualifier is also specified, it overrides /ENABLE=(DEBUG,TRACEBACK) or /DISABLE=(DEBUG,TRACEBACK), regardless of their order on the command line.
By default, at compiler activation, FLAGGING, GLOBAL, TRACEBACK, and SUPPRESSION are enabled, and DEBUG, OVERFLOW, and QUADWORD are disabled.
The /NOENABLE qualifier has the same effect as not specifying the /ENABLE qualifier. It can also be used to negate the effects of any /ENABLE qualifiers specified earlier in the command line.
For every option of the /ENABLE qualifier, if /ENABLE and /DISABLE are used in the same command line for the same option, /DISABLE will always prevail, regardless of its position in the command line.
You may want to enable an option previously disabled through the use of a symbol. For example, you may have incorporated the following frequently used options into the DCL symbol MAC, as follows:
To enable FLAGGING using the symbol MAC, issue the following command:
$ MAC /NODISABLE/ENABLE=FLAGGING
/NOFLAGSpecifies which classes of informational messages the compiler reports. The options are:
Option Description ALIGNMENT Reports unaligned stack and memory references. ALL Enables all options. ARGLIST Reports that the argument list has been homed. (See Section 2.4.1.) BAD_FIELD_USAGE
Reports BBC/BBS instructions that attempt to use bits beyond 31. CODEGEN Reports run-time code generation, such as self-modifying code. (See Section 3.2.2.) COMPILER_VERSION
Prints compiler version to SYS$ERROR. DIRECTIVES Reports unsupported directives. HINTS Reports input/output/auto-preserved register hints. INDIRECT_CALLS
Reports CALLS/CALLG instructions that have an indirect target and are not preceded by a .USE_LINKAGE directive. INDIRECT_JSB
Reports JSB instructions that have an indirect target and are not preceded by a .USE_LINKAGE directive. INSTRUCTIONS Reports instructions that use absolute addresses that might compile correctly, but should be examined anyway, because the desired absolute address might be different on the system. JUMPS Reports branches between routines. LINKAGE
Reports linkage information provided to the OpenVMS linker. NONE Disables all options. STACK Reports all messages caused by user stack manipulation.
At compiler activation, the default is /FLAG=(ALIGNMENT, ARGLIST, CODEGEN, DIRECTIVES, INSTRUCTIONS, JUMPS, STACK).
Use of the /NOFLAG and /FLAG qualifiers together to activate a specific subset of cross-compiler messages does not work as expected. When used together, as in /NOFLAG/FLAG=(keyword,keyword), instead of activating only the messages specified by the keywords, all cross-compiler messages are activated. However, use of /FLAG=(none,keyword) activates only those messages specified by the keyword.
Note that specifying /NOFLAG or /FLAG=NONE does not disable the reporting of coding constructs that would prevent a successful compilation. The compiler continues to report code that you must change, such as an up-level stack reference.
The associated input file to the /LIBRARY qualifier must be a macro library. The default file type is MLB. The /NOLIBRARY qualifier has the same effect as not specifying the /LIBRARY qualifier, or negates the effects of any /LIBRARY qualifiers specified earlier in the command line.
The compiler can search up to 16 libraries, one of which is always STARLET.MLB. This number applies to a particular compilation, not necessarily to a particular MACRO command. If you enter the MACRO command so that more than one source file is compiled, but the source files are compiled separately, you can specify up to 16 macro libraries for each separate compilation. More than one macro library in a compilation causes the libraries to be searched in reverse order of their specification.
A macro call in a source program causes the compiler to begin the following sequence of searches if the macro is undefined:
- The libraries specified with the .LIBRARY directive are searched first, in reverse order of the order in which they were declared.
- If the macro definition is not found in any of the libraries specified with the .LIBRARY directive, a search of the libraries specified in the MACRO command line (in the reverse order in which they were specified).
- If the macro definition is not found in any of the libraries specified in the command line, a search of STARLET.MLB.
/NOLISTCreates or omits an output listing, and optionally provides an output file specification for it. The default file type for the listing file is LIS. No wildcard characters are allowed in the file specification.
An interactive MACRO command does not produce a listing file by default. The /NOLIST qualifier, present either explicitly or by default, causes errors to be reported on the current output device.
The /LIST qualifier is the default for a MACRO command in a batch job. The /LIST qualifier allows you to control the defaults applied to the output file specification by the placement of the qualifier in the command line.
/NOMACHINE (default)Enables machine code listing, if it and the /LIST qualifier are both specified in the command line.
/NOOBJECTCreates or omits an object module. It also defines the file specification. By default, the compiler creates an object module with the same file name as the first input file. The default file type for object files is OBJ. No wildcard characters are allowed in the file specification.
The /OBJECT qualifier controls the defaults applied to the output file specification by the placement of the qualifier in the command line.
/NOOPTIMIZEEnables or disables optimization options. All options are enabled by default except VAXREGS. (See Section 4.3.1.)
Option Description [NO]PEEPHOLE Peephole optimization [NO]SCHEDULE Code scheduling [NO]ADDRESSES Common base address loading [NO]REFERENCES Common data referencing [NO]VAXREGS OpenVMS Alpha systems only: Allow the use of VAX registers (R0 through R12) as temporary registers when they appear to be unused ALL All optimizations NONE No optimizations
Note that, on OpenVMS Alpha systems, /OPTIMIZE=ALL turns on VAXREGS, which may generate incorrect code unless all register usage of all routines in the module have been correctly declared.
/NOPRESERVE (default)Directs the compiler to generate special OpenVMS Alpha or OpenVMS I64 code throughout a module for all VAX MACRO instructions that rely on VAX guarantees of operation atomicity or granularity. (See Section 2.11.)
Option Description GRANULARITY Preserves the rules of VAX granularity of writes. Specifying /PRESERVE=GRANULARITY causes the compiler to use Alpha Load-locked and Store-conditional instruction sequences or the Itanium compare-exchange (cmpxchg) instruction in code it generates for VAX instructions that perform byte, word, or unaligned longword writes. ATOMICITY Preserves atomicity of VAX modify operations. Specifying /PRESERVE=ATOMICITY causes the compiler to use Alpha Load-locked and Store-conditional instruction sequences or the Itanium compare-exchange (cmpxchg) instruction in code it generates for VAX instructions with modify operands.
/PRESERVE and /PRESERVE=(GRANULARITY,ATOMICITY) are equivalent. When preservation of both granularity and atomicity is enabled, and the compiler encounters a VAX coding construct that requires both granularity and atomicity guarantees, it enforces atomicity over granularity.
If you are aware of specific sections of VAX MACRO code that require VAX granularity and atomicity guarantees, you may not need the compiler to enforce these guarantees for the entire module. Instead, you can use the .PRESERVE and .NOPRESERVE directives (see Appendix B) to apply the guarantees only to those sections. Because the compiler does not need to generate expanded code for the entire module, these these directives can help optimize the code.
Atomicity is guaranteed on multiprocessing systems as well as uniprocessing systems when you specify /PRESERVE=ATOMICITY.
When the /PRESERVE qualifier is present, you can control the number of times compiler-generated code retries a granular or atomic update by specifying the /RETRY_COUNT qualifier.
If /PRESERVE=ATOMICITY is turned on, any unaligned data references will result in a fatal reserved operand fault. See Section 2.11.5. If /PRESERVE=GRANULARITY is turned on, unaligned word references to addresses assumed aligned will also cause a fatal reserved operand fault.
/RETRY_COUNT=countSpecifies to the compiler the number of times the following operations should be performed in generated code:
- Retries of operations performed in source by a VAX interlocked instruction
- Retries of atomic or granular updates if the /PRESERVE qualifier or .PRESERVE directive is present
If the /RETRY_COUNT qualifier is not present, the compiler generates code that performs an infinite number of retries of these operations.
/NOSHOW[=(function[,...])]Provides initial settings for the functions controlled by the compiler directives .SHOW and .NOSHOW.
You can specify one or more of the following functions:
Option Description CONDITIONALS Lists unsatisfied conditional code associated with .IF and .ENDC MACRO directives. CALLS Lists macro calls and repeat range expansions. DEFINITIONS Lists macro definitions. EXPANSIONS Lists macro expansions. BINARY Lists binary code generated by the expansion of macro calls.
/NOSYMBOLS (default)Generates a symbol table and psect synopsis table for the listing file if it and the /LIST qualifier are both specified in the command line.
/TIE (default on OpenVMS Alpha)
/NOTIE (default on OpenVMS I64)Ensures that proper external callouts are generated for translated images. Translated images are images that were translated with the DECMigrate (also known as VEST) facility. The Translated Image Environment (TIE) allows translated images to execute as if on an OpenVMS VAX system. Use /NOTIE for better performance if you do not make calls to translated images.
/NOUNALIGNED (default)Forces the compiler to use unaligned loads and stores for all register-based memory references (except those that are FP--based or SP--based or are references to local aligned static data).
By default, the compiler assumes that addresses in registers used as base pointers (except those that are FP--based or SP--based) are longword-aligned at routine entry, and generates code to load BYTE, WORD, and LONG data accordingly. This can result in run-time alignment faults, with significant performance impact, if the assumption is incorrect. Specifying /UNALIGNED causes the compiler to generate code assuming pointers are unaligned. This code is significantly larger, but is more efficient than handling an alignment fault.
The compiler does not track quadword register alignment. For quadword memory references (such as in VAX MOVQ instructions), the compiler assumes the base address is quadword aligned, unless it has determined the address may not be longword-aligned in its register tracking code. Quadword references in OpenVMS Alpha and OpenVMS I64 built-in uses are always assumed to be quadword aligned. Since these must be in new code, the data should be properly aligned.
Previous Next Contents Index