HP OpenVMS systems documentation

This appendix describes the invocation format of the MACRO Compiler for OpenVMS Systems and each of its qualifiers.

Format

MACRO/MIGRATION filespec[+...]

Parameters

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.

Note 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.

Description

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

Qualifiers

/DEBUG=(option[,...])

/NODEBUG

Includes 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.

Note 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.

/DIAGNOSTICS[=filespec]

/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).

/DISABLE=(option[,...])

/NODISABLE

Provides initial settings for the compiler functions that can be controlled by the .DISABLE and .ENABLE MACRO directives.

You can specify one or more of the following functions:

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.

Note 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: /DISABLE=(xxxx, yyyy)

/ENABLE=(option[,...])

/NOENABLE

Provides initial settings for the compiler functions that can be controlled by the .DISABLE and .ENABLE MACRO directives.

You can specify one or more of the following functions:

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.

Note 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: MAC::== MACRO/MIGRATION/NOTIE/DISABLE=FLAGGING To enable FLAGGING using the symbol MAC, issue the following command: $ MAC /NODISABLE/ENABLE=FLAGGING

/FLAG=(option[,...])

/NOFLAG

Specifies 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 (I64 only)	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 (I64 only)	Prints compiler version to SYS$ERROR.
DIRECTIVES	Reports unsupported directives.
HINTS	Reports input/output/auto-preserved register hints.
INDIRECT_CALLS (I64 only)	Reports CALLS/CALLG instructions that have an indirect target and are not preceded by a .USE_LINKAGE directive.
INDIRECT_JSB (I64 only)	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 (I64 only)	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).

Note 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.

/LIBRARY

/NOLIBRARY

Positional qualifier.

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:

1. The libraries specified with the .LIBRARY directive are searched first, in reverse order of the order in which they were declared.
2. 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).
3. If the macro definition is not found in any of the libraries specified in the command line, a search of STARLET.MLB.

/LIST[=filespec]

/NOLIST

Creates 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.

/MACHINE

/NOMACHINE (default)

Enables machine code listing, if it and the /LIST qualifier are both specified in the command line.

/OBJECT[=filespec]

/NOOBJECT

Creates 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.

/OPTIMIZE[=(option[,...])]

/NOOPTIMIZE

Enables or disables optimization options. All options are enabled by default except VAXREGS. (See Section 4.3.1.)

The options are:

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.

/PRESERVE[=(option[,...])]

/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.)

The options are:

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.

Warning 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=count

Specifies 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.

/SHOW[=(function[,...])]

/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.

/SYMBOLS

/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.

/UNALIGNED

/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.

Note 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