HP OpenVMS MACRO Compiler
Porting and User's
This manual describes how to port Macro-32 source code written for the
VAX MACRO compiler to the MACRO compiler for OpenVMS running on either
an HP OpenVMS Industry Standard 64 or HP OpenVMS Alpha system. It also
describes how to use the compiler.
This revised manual supersedes the OpenVMS MACRO-32 Porting and
User's Guide for OpenVMS Version 7.3.
OpenVMS I64 Version 8.2
OpenVMS Alpha Version 8.2
Hewlett-Packard Company Palo Alto, California
© Copyright 2005 Hewlett-Packard Development Company, L.P.
Confidential computer software. Valid license from HP required for
possession, use or copying. Consistent with FAR 12.211 and 12.212,
Commercial Computer Software, Computer Software Documentation, and
Technical Data for Commercial Items are licensed to the U.S. Government
under vendor's standard commercial license.
The information contained herein is subject to change without notice.
The only warranties for HP products and services are set forth in the
express warranty statements accompanying such products and services.
Nothing herein should be construed as constituting an additional
warranty. HP shall not be liable for technical or editorial errors or
omissions contained herein.
Intel and Itanium are trademarks or registered trademarks of Intel
Corporation or its subsidiaries in the United States and other
Printed in the US
The HP OpenVMS documentation set is available on CD-ROM.
This manual is for software engineers responsible for porting
- From VAX MACRO to OpenVMS MACRO running on OpenVMS Alpha systems
- From VAX MACRO to OpenVMS MACRO running on OpenVMS I64 systems
- From OpenVMS MACRO running on OpenVMS Alpha systems to OpenVMS MACRO
running on OpenVMS I64 systems
You should have programming skills and an understanding of the relevant
This manual is divided into two parts.
Part 1, Concepts and Methodology is composed of the the following chapters:
- Chapter 1, Preparing to Port Macro-32 Code, provides a methodology for porting VAX MACRO code to
an OpenVMS Alpha or OpenVMS I64 system.
- Chapter 2, How the MACRO Compiler Functions on Different Platforms, describes how and when to use the features of the
compiler, including specialized directives and macros.
- Chapter 3, Recommended and Required Source Changes, describes how to change those coding constructs that
cannot be compiled by the MACRO compiler.
- Chapter 4, Improving the Performance of Ported Code, describes several compiler features that you can use
to improve the performance of your ported code.
- Chapter 5, MACRO Support for 64-Bit Addressing, describes the 64-bit addressing support provided by
the MACRO compiler and associated components.
Part 2, Reference is composed of the following appendixes:
This manual refers readers to the following manuals for additional
information on certain topics:
- Porting Applications from HP OpenVMS Alpha to HP OpenVMS Industry Standard 64 for Integrity Servers describes how to port an application from OpenVMS Alpha
to OpenVMS I64 systems.
- Migrating an Environment from OpenVMS VAX to OpenVMS Alpha1 provides an overview of the VAX to Alpha
migration process and information to help you plan a migration. It
discusses the decisions you must make in planning a migration and the
ways to get the information you need to make those decisions. In
addition, it describes the migration methods and tools available so
that you can estimate the amount of work required for each method and
select the method best suited to a given application.
- Migrating an Application from OpenVMS VAX to OpenVMS Alpha describes how to build an OpenVMS Alpha version of
your OpenVMS VAX application by recompiling and relinking it. It
discusses dependencies your application may have on features of the VAX
architecture (such as assumptions about page size, synchronization, and
condition handling) that you may need to modify to create a native
OpenVMS Alpha version. In addition, the manual describes how you can
create applications in which native OpenVMS Alpha components interact
with translated OpenVMS VAX components.
- HP OpenVMS Calling Standard describes the mechanisms used to allow procedure calls
on OpenVMS VAX, OpenVMS Alpha, and OpenVMS I64 systems.
- VAX MACRO and Instruction Set Reference Manual1 provides information about VAX
instructions and the standard VAX MACRO assembly language directives.
- OpenVMS System Messages: Companion Guide for Help Message Users describes how to use the Help Message utility to
obtain information about the MACRO assembler messages and MACRO
For additional information about HP OpenVMS products and services,
visit the following World Wide Web address:
1 This manual has been archived. It is
no longer maintained and is not part of the OpenVMS documentation set.
However, you can view it online at
HP welcomes your comments on this manual. Please send comments to
either of the following addresses:
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698
How to Order Additional Documentation
For information about how to order additional documentation, visit the
following World Wide Web address:
The following product names may appear in this manual:
- HP OpenVMS Industry Standard 64 for Integrity Servers
- OpenVMS I64
All three names---the longer form and the two abbreviated forms---refer
to the version of the OpenVMS operating system that runs on the
Intel® Itanium® architecture.
The following conventions might be used in this manual:
A sequence such as Ctrl/
x indicates that you must hold down the key labeled Ctrl while
you press another key or a pointing device button.
A sequence such as PF1
x indicates that you must first press and release the key
labeled PF1 and then press and release another key or a pointing device
In examples, a key name enclosed in a box indicates that you press a
key on the keyboard. (In text, a key name is not enclosed in a box.)
In the HTML version of this document, this convention appears as
brackets, rather than a box.
A horizontal ellipsis in examples indicates one of the following
- Additional optional arguments in a statement have been omitted.
- The preceding item or items can be repeated one or more times.
- Additional parameters, values, or other information can be entered.
A vertical ellipsis indicates the omission of items from a code example
or command format; the items are omitted because they are not important
to the topic being discussed.
In command format descriptions, parentheses indicate that you must
enclose choices in parentheses if you specify more than one.
In command format descriptions, brackets indicate optional choices. You
can choose one or more items or no items. Do not type the brackets on
the command line. However, you must include the brackets in the syntax
for OpenVMS directory specifications and for a substring specification
in an assignment statement.
In command format descriptions, vertical bars separate choices within
brackets or braces. Within brackets, the choices are optional; within
braces, at least one choice is required. Do not type the vertical bars
on the command line.
In command format descriptions, braces indicate required choices; you
must choose at least one of the items listed. Do not type the braces on
the command line.
Bold type represents the introduction of a new term. It also represents
the name of an argument, an attribute, or a reason.
Italic type indicates important information, complete titles of
manuals, or variables. Variables include information that varies in
system output (Internal error
number), in command lines (/PRODUCER=
name), and in command parameters in text (where
dd represents the predefined code for the device type).
Uppercase type indicates a command, the name of a routine, the name of
a file, or the abbreviation for a system privilege.
A hyphen at the end of a command format description, command line, or
code line indicates that the command or statement continues on the
All numbers in text are assumed to be decimal unless otherwise noted.
Nondecimal radixes---binary, octal, or hexadecimal---are explicitly
Concepts and Methodology
Preparing to Port Macro-32 Code
This chapter describes a process that software engineers can use when
planning to port Macro-32 code from an OpenVMS VAX system to an
OpenVMS Alpha or HP OpenVMS Industry Standard 64 system.
This chapter contains the following topics:
See Appendix A for information on how to invoke the compiler.
1.1 Features of the MACRO Compiler
The OpenVMS MACRO compiler compiles Macro-32 source code written for
OpenVMS VAX systems (the VAX MACRO assembler) into machine code that
runs on OpenVMS Alpha and OpenVMS I64 systems.
This compiler is provided for porting Macro-32 code to OpenVMS Alpha and
OpenVMS I64 systems. For any new development, it is recommended that
you use mid- and high-level languages.
While some VAX MACRO code can be compiled without any changes, most
code modules will require the addition of entry point directives when
ported to OpenVMS Alpha or OpenVMS I64. Many code modules will require
other changes as well.
The compiler might detect only a few problems with a module at its
initial compilation and then, after you have corrected them, the
compiler might discover additional problems. In such cases, the
resolution of one problem can allow the compiler to further examine the
code and discover other problems the initial one concealed.
The compiler includes many features that make this process easier, such
- Qualifiers that allow you to control the kinds of messages the
compiler generates or to enforce VAX behavior in the generated code.
For example, the /FLAG qualifier enables you to specify the types of
informational messages the compiler reports. Many of these messages
identify porting problems, including VAX architectural dependencies.
The options to the /FLAG qualifier include reporting unaligned stack
and memory references and reporting unsupported directives. (For more
information about the /FLAG qualifier, see Appendix A, MACRO Compiler Qualifiers.)
- Directives that indicate routine entry points and describe them to
the compiler or enforce VAX behavior for sections of code. For example,
.CALL_ENTRY declares the entry point of a called routine to the
compiler. Section 2.3, Section 2.5, and Chapter 3 discuss
situations when the compiler requires special directives. (See
Appendix B, Specialized Directives.)
- For OpenVMS Alpha platforms, built-ins that allow you to access the
Alpha instructions that perform 64-bit operations and Alpha PALcode
instructions. (PALcode is shorthand for privileged architecture library
code.) For example, EVAX_ADDQ, with the appropriate operands, performs
the quadword add instruction. (See Appendix C, MACRO Compiler Built-Ins.)
- For OpenVMS I64 platforms, built-ins that allow you to access
certain I64 instructions. In addition, to aid in porting code
from Alpha to I64, many of the EVAX_builtins have been
reimplemented for I64. (See Appendix C, MACRO Compiler Built-Ins.)
The compiler also provides 64-bit addressing support, which is
documented in Chapter 5 and in Appendix E. Support for 64-bit
addressing was introduced in OpenVMS Alpha Version 7.0. This support is
provided for those rare instances when it is preferable to use VAX
MACRO to access 64-bit address space instead of using a high-level
language that is supported on OpenVMS Alpha or OpenVMS I64.
1.2 Differences Between the Compiler and the Assembler
It is important to remember that the MACRO compiler is a compiler, not
an assembler. It does not create output code that exactly matches the
input code. In its optimization process, the compiler might move,
replicate, or remove code and interleave instructions. Furthermore, the
faulting behavior of the ported code might not match that of VAX code.
These differences are described in the following sections.
1.2.1 Moving Code
Mispredicted branches are expensive on an OpenVMS Alpha or OpenVMS I64
system. The compiler attempts to determine the most likely code path
through the module and then generates code that consolidates that code
path. Code paths deemed unlikely are moved out of line to the end of
the module. Consider the following example:
JSB PROCESS ERROR
In this example, the compiler will treat the HALT as an unlikely code
path and detect that the two code streams do not rejoin at 10$. Because
of these conditions, it will determine that the branch is likely to be
taken. It will then move the intervening instructions out of line to
the end of the module, change the BLBS instruction to a BLBC that
branches to the moved code, and continue with in-line code generation
at the label 10$, as follows:
L1$: JSB PROCESS ERROR
You can change the compiler's determination of the likelihood of
conditional branches with the compiler directives .BRANCH_LIKELY and
.BRANCH_UNLIKELY (see Section 4.2).
1.2.2 Replicating Code
The compiler might replicate small sections of code multiple times to
eliminate excessive branching. For example, when compiling branches to
the following VAX code, the compiler will replicate the MOVL at each
branch to ERROR1 and then branch directly to COMMON_ERROR.
ERROR1: MOVL #ERROR1,R0
1.2.3 Removing Code
The compiler's optimizations might determine that some instructions do
not contribute to the code flow. In such instances, the instructions
might be removed. An example of this is a CMP or TST instruction with
no subsequent conditional branch, such as the following:
Removal of this CMPB instruction could cause a problem if its purpose
was to touch two memory locations to ensure that the memory pages were
faulted in before calling the routine. This would likely have to be
changed in porting to OpenVMS Alpha or OpenVMS I64 anyway because of
the different page sizes of VAX and Alpha or I64 systems. In
addition to changing the page size, you should replace the instruction
with MOVx instructions, such as the following:
Note that the two MOVB instructions operated on two different
registers. The compiler does not currently remove instructions that
load values into a register which is never subsequently read before
being overwritten. However, this optimization might be done in the
In general, code requiring that a memory read reference actually touch
memory should be examined carefully, as current or future optimizations
might move or remove the references.
1.2.4 Interleaving Instructions
Instruction scheduling, which is performed by default (see
Section 4.3), will interleave the Alpha or Itanium instructions
generated from one VAX instruction with the Alpha or Itanium
instructions generated by surrounding VAX instructions.
1.2.5 Reserved Operand Faults
On VAX systems, some VAX MACRO instructions might generate a reserved
operand fault if certain operands are out of a required range. For
example, on a bit manipulation instruction such as INSV, if the size
operand is greater than 32, a VAX system will generate a run-time
reserved operand fault.
On OpenVMS Alpha and OpenVMS I64 systems, if the operand that is out of
range is a compile-time constant, the compiler will flag this condition
with an error message. However, if this operand is variable at run
time, the compiler makes no attempt to generate run-time range checks
on it. If the operand is out of range, the resulting operation might
cause incorrect results yet not create a fault.
1.3 Step-by-Step Porting Process for OpenVMS VAX to OpenVMS Alpha or OpenVMS I64
The following steps have proven to be an efficient means for porting
VAX MACRO code to OpenVMS Alpha or OpenVMS I64:
- Inspect each module you intend to port, from beginning to end, for
coding practices that prohibit its successful porting. Such scrutiny is
necessary, because it is impossible for the compiler to account for the
myriad imaginative uses of VAX MACRO code that take advantage of a
comprehensive knowledge of the VAX architecture. Such uses, if not
detected and modified, can undermine an effort to port VAX MACRO code
to OpenVMS Alpha or OpenVMS I64.
- At each entry point in the module, add the appropriate entry-point
These directives are:
- .EXCEPTION_ENTRY (Alpha systems only)
You do not need to change the VAX MACRO entry point .ENTRY to
.CALL_ENTRY unless you want to use .CALL_ENTRY clauses. Nor do you need
to add the register arguments at this time.
See Section 2.3 for
guidelines for the correct placement of these directives.
Appendix B for a full syntax description of each.
- Invoke the compiler to compile the module. A suggested command
procedure for doing this appears in Section 2.12.
By default, the compiler flags unaligned stack and memory references,
routine branches, potentially problematic instructions, and
self-modifying code. If you specify /FLAG=HINTS on the command line,
the compiler will provide suggestions for the input
and output register arguments of the entry point
directives you inserted at Step 2.
- Take note of the problems reported by the compiler.
The MACRO compiler generally issues the same messages on
OpenVMS Alpha systems and on OpenVMS I64 systems, with the exception of
- AMAC on OpenVMS Alpha systems
- IMAC on OpenVMS I64 systems
AMAC-I-ARGLISHOME, argument list must be homed in caller
IMAC-I-ARGLISHOME, argument list must be homed in caller
You can invoke the Help Message utility for an explanation and user
action for each compiler message you receive.
For information about
the Help Message utility, refer to DCL help or the OpenVMS System Messages: Companion Guide for Help Message Users. Also,
Section 1.5 and Chapter 3 provide specific details about VAX MACRO
coding practices that cannot be directly translated to OpenVMS Alpha or
OpenVMS I64 code.
Remember that resolution of the problems
detected on this pass might allow the compiler to discover additional
problems on a subsequent pass.
- Edit the Macro-32 source code. Fix the problems indicated by the
compiler and look for others the compiler might have missed.
However, do not change code just to avoid compiler informational
diagnostic messages. Most of the information-level messages are there
to point out code that will result in less optimal performance on an
OpenVMS Alpha or OpenVMS I64 processor but will compile correctly.
If you have examined the offending instructions in the source code and
are convinced that all is well, leave the code alone. Remember that you
can use the command line qualifiers /FLAG and /WARN to control
diagnostic message generation. Also, the .ENABLE and .DISABLE
directives can turn off information level messages for segments of code
within a module.
- Add input, output,
preserve, and scratch arguments, as
appropriate, to the entry point directives you provided in Step 2 and
supply a list of pertinent registers for each specified argument.
Section 2.6 can help you determine which registers to list.
- For OpenVMS I64 systems only, add linkage directives
(.CALL_LINKAGE, .DEFINE_LINKAGE) to tell the compiler about routines
that return values in registers other than R0/R1 and about routines
written in a languge other than Macro-32 that are called with the JSB
instruction. In addition, add the .USE_LINKAGE directive at each
indirect CALLS/CALLG instruction if the routine has a non-standard
return; add the .USE_LINKAGE directive at each indirect JSB instruction
if the routine is written in a language other than Macro-32. See
Appendix B for more information.
- Repeat Steps 3 through 7 until the compiler generates informational
messages only for Macro-32 source code that you have verified produces
correct OpenVMS Alpha or OpenVMS I64 object code.
- If your module is common to both OpenVMS VAX and OpenVMS Alpha or
OpenVMS I64 systems (a coding convention discussed in Section 1.7),
your porting effort is not complete until the module is acceptable to
the VAX MACRO assembler as well as the compiler.
Once you have some experience in porting VAX MACRO modules, it will be
easier to recognize certain problems while inspecting the source and to
fix them before your initial invocation of the compiler.