Porting Applications from HP OpenVMS Alpha to HP
OpenVMS Industry Standard 64 for Integrity Servers
Migrating Source Modules
This chapter describes the steps common to porting all applications. It
then describes certain types of code and coding practices that may need
to be changed before you can recompile your application.
If you have thoroughly analyzed your code and planned the migration
process, the final stage of migrating source modules should be fairly
straightforward. You may be able to recompile or translate many
programs with no change. Programs that do not recompile or translate
directly will frequently need only straightforward changes to get them
running on an I64 system. Certain types of code will require changes.
Migrating your application involves the following steps:
- Setting up the migration environment.
- Compiling your application on an Alpha system with the latest
versions of the Alpha compilers.
- Testing the application on an Alpha system to establish baselines
for evaluating the migration.
- Recompiling and relinking an application on an I64 system.
- Debugging the migrated application.
- Testing the migrated application.
- Integrating the migrated application into a software system.
These steps, except for setting up the migration environment, are
illustrated in Figure 4-1.
Figure 4-1 Migrating an Application from Alpha to I64
If your source files possess any of the following characteristics, you
may need to change them:
- Use VAX Macro-32 or Alpha Macro-64 assembly language
- Use conditions to produce the same application for different
platforms from a common code base
- Rely on the Alpha architecture, such as the Alpha object code format
- Use floating point-data types
- Use threads
- Contain unaligned data
- Rely explicitly on the OpenVMS Alpha Calling Standard
- Use privileged interfaces or operate at inner access modes
For more information, see Section 4.8.
4.1 Setting Up the Migration Environment
The native I64 environment is comparable to the development environment
on Alpha systems. Most of the program development tools that you are
accustomed to using on OpenVMS Alpha are available. Some modifications
have been made to these tools to account for the differences in the two
architectures and the calling standard. Most of these modifications are
invisible to users.
An important element of the I64 migration process is the availability
of support from HP Services, which can provide help in modifying,
debugging, and testing your application. For more information, see
There are several issues to consider when planning what hardware you
will need for your migration. To begin, consider what resources are
required in your normal Alpha development environment:
In an I64 environment, the following configuration is recommended for
- HP rx2600 Integrity Server with one or two processors
- 1 to 24 GB of memory
- One to four 36-GB disks
- DVD/CD-ROM drive
For more information, refer to the HP OpenVMS Version 8.2 Release Notes.
To create an efficient migration environment, check the following
- Migration tools
You need a compatible set of migration tools, including the following:
- Translation tools
HP OpenVMS Migration Software for Alpha to Integrity Servers and
- System libraries
Include files for C programs
- Logical names
Logical names must be consistently defined to
point to Alpha and I64 versions of tools and files.
Compile and link procedures
These procedures may need to be
adjusted for new tools and the new environment.
- Test tools
You need to port the Alpha test tools to OpenVMS I64, unless they
are already ported. You also need test tools that are designed to test
for OpenVMS I64 characteristics, such as changes to the OpenVMS Calling
Standard that are specific to OpenVMS I64.
- Tools for maintaining sources and building images, such as:
CMS (Code Management System)
MMS (Module Management System)
Native Alpha Development
The standard development tools you have on Alpha are also available as
native tools on I64 systems.
The software translator HP OpenVMS Migration Software for Alpha to
Integrity Servers runs on both Alpha and I64 systems. The Translated
Image Environment (TIE), which is required to run a translated image,
is part of OpenVMS I64, so final testing of a translated image must
either be done on an I64 system or at an I64 Migration Center. In
general, the process of translating an Alpha image to run on an I64
system is straightforward, although you may have to modify your code
somewhat to get it to translate without error.
22.214.171.124 HP OpenVMS Migration Software for Alpha to Integrity Servers and Translated Image Environment (TIE)
The main tools for migrating Alpha user-mode images to OpenVMS I64 are
a static translator and a run-time support environment:
The HP OpenVMS Migration Software for Alpha to Integrity Servers is a
utility that analyzes an Alpha image and creates a functionally
equivalent translated image. Using HP OpenVMS Migration Software for
Alpha to Integrity Servers, you will be able to do the following:
- Determine whether an Alpha image is translatable.
- Translate the Alpha image to an I64 image.
- Identify specific incompatibilities with OpenVMS I64 within the
image and, when appropriate, obtain information on how to correct those
incompatibilities in the source files.
- Identify ways to improve the run-time performance of the translated
The Translated Image Environment (TIE) is an I64 shareable image that
supports translated images at run time. TIE provides the translated
image with an environment similar to OpenVMS Alpha and processes all
interactions with the native I64 system. Items that TIE provides
TIE is invoked automatically for any translated image; you do not need
to call it explicitly.
- Alpha instruction interpreter, which supports:
- Execution of Alpha instructions (including instruction atomicity)
that is similar to their execution on an Alpha system
- Complex Alpha instructions, as subroutines
- Alpha compatible exception handler
Jacket routines that allow communication between native and translated
- Emulated Alpha stack
HP OpenVMS Migration Software for Alpha to Integrity Servers locates
and translates as much Alpha code as possible into I64 code. TIE
interprets any Alpha code that cannot be converted into I64
instructions; for example:
Since interpreting instructions is a slow process, HP OpenVMS Migration
Software for Alpha to Integrity Servers attempts to find and translate
as much Alpha code as possible to minimize the need for interpreting it
at run time. A translated image runs at slower than a comparable native
Alpha image, depending on how much Alpha code TIE needs to interpret.
- Instructions that HP OpenVMS Migration Software for Alpha to
Integrity Servers could not statically identify
- VAX (F_, G_ and D_floating) floating-point operations
Note that you cannot specify dynamic interpretation of a Alpha image on
an I64 system. You must use HP OpenVMS Migration Software for Alpha to
Integrity Servers to translate the image before it can run on OpenVMS
Translating a Alpha image produces an image that runs as a native image
on I64 hardware. The I64 image is not merely an interpreted or emulated
version of the Alpha image, but contains I64 instructions that perform
operations identical to those performed by the instructions in the
original Alpha image. The I64 .EXE file also contains the original
Alpha image in its entirety, which allows TIE to interpret any code
that HP OpenVMS Migration Software for Alpha to Integrity Servers could
The HP OpenVMS Migration Software for Alpha to Integrity Servers's
analysis capability also makes it useful for evaluating programs that
you intend to recompile, rather than translate.
4.1.3 Coexistence with Translated Images
Application components can be migrated from OpenVMS VAX and OpenVMS
Alpha to OpenVMS I64 by binary translation. Because executable and
shareable images can be translated on an individual basis, it is
possible (even likely) to construct an environment in which native and
translated images are mixed in a single image activation.
Translated images use the calling standard of their original
implementation; that is, the argument lists of VAX translated images
have the same binary format as they did on the VAX platform. Because
the OpenVMS I64 calling standard differs from the OpenVMS VAX and
OpenVMS Alpha calling standards, direct calls between native and
translated images are not possible. Instead, such calls must be handled
by interface routines (called jacket routines) that transform the
arguments from one calling standard to the other.
The jacket routines are provided by TIE. In addition to argument
transformation, TIE also handles the delivery of exceptions to
translated code. TIE is loaded as an additional shareable image
whenever a translated image (either main program or shareable image) is
activated. The image activator interposes calls to jacket routines as
necessary when it resolves references between native and translated
For native code to interoperate with translated code, it must meet the
- All function descriptors must contain signature data. The
signature data is used by the jacket routines to transform arguments
and return values between their native and VAX or Alpha formats. Native
I64 images contain function descriptors for both outbound calls and all
- All calls to function variables (that is, where the identity of
the called function is contained in a variable) must be made through
the library routine OTS$CALL_PROC. OTS$CALL_PROC determines at run time
whether the function being called is native or translated and calls
native code directly and translated code via the TIE.
These requirements are met by compiling code using the /TIE qualifier
and linking it using the /NONATIVE_ONLY qualifier. /TIE is supported by
most OpenVMS I64 compilers including the Macro-32 compiler. (It is not
supported on C++.) Both qualifiers must be given explicitly in the
compile and LINK commands, since the defaults are /NOTIE and
/NATIVE_ONLY, respectively. Signatures are not supported by the I64
assembler; therefore, routines coded in I64 assembly language cannot be
directly called from translated images. I64 assembly language can call
translated code only with an explicit call to OTS$CALL_PROC.
Translated image support carries a minor performance penalty: all calls
to function variables are made via OTS$CALL_PROC, at a cost of about 10
instructions for most cases. Performance-critical code should only be
built /TIE and /NONATIVE_ONLY if interoperation with translated images
An additional consideration applies to executable and shareable images
that are linked /NOSYSSHR. Ordinarily, references to OTS$CALL_PROC are
resolved by the shareable image LIBOTS.EXE and require no special
attention. Linking an image /NOSYSSHR skips the search of the shareable
image library and instead resolves external references from object
modules in STARLET.OLB. OTS$CALL_PROC makes a reference to a data cell
defined in the system symbol table, and if simply included from
STARLET.OLB would result in an unresolved reference to
Most images linked /NOSYSSHR are so built to avoid interaction with any
external images, so calls to translated code are not an issue. For this
reason, STARLET.OLB contains a subset version of OTS$CALL_PROC that
does not support calls to translated images. This module, named
OTS$CALL_PROC_NATIVE, is loaded by default, and images linked /NOSYSSHR
by default cannot call out to translated code.
In addition, STARLET.OLB also contains the module OTS$CALL_PROC, which
is the full version. It has no entry in the library symbol table and is
only loaded by explicit reference. For the rare cases where images
linked /NOSYSSHR need to be able to call out to translated shareable
images, the full version of OTS$CALL_PROC must be explicitly included
from STARLET.OLB and the image must also be linked against the system
symbol table. Two options are required in the link command file:
- SYS$LIBRARY:STARLET.OLB/INCLUDE=OTS$CALL_PROC must be present in
the input file list.
- The /SYSEXE qualifier must be included on the LINK command.
4.2 Compiling Applications on Alpha With Current Compiler Version
Before recompiling your code with a native I64 compiler, HP recommends
that you first compile the code to run on Alpha with the latest version
of the compiler. For example, if the application is written in Fortran,
make sure that the application has been recompiled with Fortran Version
7.5 (Fortran 90) to run on Alpha. Fortran Version 7.5 is the version
that was ported to I64.
Using the latest version of the compiler to recompile your application
on OpenVMS Alpha might uncover problems that are attributable to the
change in the compiler version only. For example, newer versions of
compilers may enforce programming language standards that were
previously ignored, exposing latent problems in your application code.
Newer versions may also enforce changes to the standard that were not
in effect when the earlier versions were created. Fixing such problems
on OpenVMS Alpha simplifies porting that application to I64.
For a list of the native OpenVMS I64 compilers, see Section 5.1.
4.3 Testing Applications on Alpha for Baseline Information
The first step in testing is to establish baseline values for your
application by running your test suite on the Alpha application. You
can do this before or after you port your application to I64. You can
then compare the results of these tests with the results of similar
tests on an I64 system, as described in Section 4.6.
4.4 Recompiling and Relinking on an I64 System
In general, migrating your application involves repeated cycles of
revising, compiling, linking, and debugging your code. During the
process, you resolve all syntax and logic errors noted by the
development tools. Syntax errors are usually simple to fix; logic
errors typically require significant modifications to your code.
Your compile and link commands will likely require some changes, such
as new compiler and linker switches. For more information about the
compiler switches, see Chapter 6. If you are porting VAX MACRO code,
refer to the HP OpenVMS MACRO Compiler Porting and User's Guide.
4.5 Debugging the Migrated Application
Once you have migrated your application to OpenVMS I64, you may have to
debug it. This section describes the OpenVMS tools available for
debugging your application.
For more information about these tools, see Chapter 5, Chapter 6,
and the HP OpenVMS Debugger Manual.
The OpenVMS I64 operating system provides the following debuggers:
- OpenVMS Debugger
The OpenVMS Debugger is a symbolic debugger;
that is, the debugger allows you to refer to program locations by the
symbols you used for them in your program---the names of variables,
routines, labels, and so on. You do not need to specify memory
addresses or machine registers when referring to program locations.
The OpenVMS Debugger does not support debugging of translated
images. However, you can debug a native application that uses a
The XDelta Debugger is an address location
debugger; that is, the debugger requires you to refer to program
locations by address location. This debugger is primarily used to debug
programs that run in privileged processor mode or at an elevated
interrupt level. The related Delta Debugger is not yet available.
The System-Code Debugger is a symbolic debugger that allows you to
debug nonpageable code and device drivers running at any IPL.
4.5.2 Analyzing System Crashes
OpenVMS provides two tools for analyzing system crashes: the System
Dump Analyzer and the Crash Log Utility Extractor.
126.96.36.199 System Dump Analyzer
The System Dump Analyzer (SDA) utility on OpenVMS I64 systems is almost
identical to the utility provided on OpenVMS Alpha systems. Many
commands, qualifiers, and displays are identical, including several for
accessing functions of the Crash Log Utility Extractor (CLUE) utility.
Some displays have been adapted to show information specific to OpenVMS
To use SDA on an Alpha system, you must first familiarize yourself with
the OpenVMS calling standard for Alpha systems. Similarly, to use SDA
on an I64 system, you must familiarize yourself with the OpenVMS
Calling Standard for I64 systems before you can decipher the pattern of
a crash on the stack. For more information, refer to the HP OpenVMS Calling Standard.
188.8.131.52 Crash Log Utility Extractor
The Crash Log Utility Extractor (CLUE) is a tool for recording a
history of crash dumps and key parameters for each crash dump, and for
extracting and summarizing key information. Unlike crash dumps, which
are overwritten with each system failure and are available only for the
most recent failure, the summary crash history file with a separate
listing file for each failure is a permanent record of system failures.
4.6 Testing the Migrated Application
You must test your application to compare the functionality of the
migrated version with that of the Alpha version.
The first step in testing is to establish baseline values for your
application by running your test suite on the Alpha application, as
described in Section 4.3.
Once your application is running on an I64 system, there are two types
of tests you should apply:
- Standard tests used for the Alpha version of the application
- New tests to check specifically for problems due to the change in
4.6.1 Alpha Tests Ported to I64
Because the changes in your application are combined with use of a new
architecture, testing your application after it is migrated to OpenVMS
I64 is particularly important. Not only can the changes introduce
errors into the application, but the new environment can bring out
latent problems in the Alpha version.
Testing your migrated application involves the following steps:
Both regression tests and stress tests are useful here. Stress tests
are important to test for platform differences in synchronization,
particularly for applications that use multiple threads of execution.
- Get a complete set of standard data for the application prior to
- Migrate your Alpha test suite along with the application (if the
tests are not already available on I64).
- Validate the test suite on an I64 system.
- Run the migrated tests on the migrated application.
4.6.2 New I64 Tests
Although your standard tests should go a long way toward verifying the
function of the migrated application, you should add some tests that
look at issues specific to the migration. Points to focus on include
- Compiler differences
- Architectural differences
- Integration, such as modules written in different languages
4.6.3 Uncovering Latent Bugs
Despite your best efforts, you may encounter bugs that were in your
program all along but that never caused a problem on an OpenVMS Alpha
For example, failure to initialize some variable in your program might
have been benign on an Alpha system but could produce an arithmetic
exception on an I64 system. The same could be true of moving between
any other two architectures, because the available instructions and the
way compilers optimize them is bound to change. There is no magic
answer for bugs that have been in hiding, but you should test your
programs after porting them and before making them available to other
4.7 Integrating the Migrated Application into a Software System
After you have migrated your application, check for problems that are
caused by interactions with other software and that may have been
introduced during the migration.
Sources of problems in interoperability can include the following:
- Alpha and I64 systems within an OpenVMS Cluster environment must
use separate system disks. You must make sure that your application
refers to the appropriate system disk.
- Image names
In a mixed architecture environment, be sure that
your application refers to the correct version.
- Native Alpha and native I64 versions of an image have the same
If you attempt to run an Alpha image on an I64 system, the
following error message is displayed:
$ run alpha_image.exe
%DCL-W-ACTIMAGE, error activating image alpha_image.exe
-CLI-E-IMGNAME, image file alpha_image.exe
-IMGACT-F-NOT_I64, image is not an HP OpenVMS Industry Standard 64 image
4.8 Modifying Certain Types of Code
Certain coding practices and types of code will require changes. The
coding practices and types of code that may or will require changes are:
- Alpha Macro 64-Assembler code
This code must be rewritten in
- Code that has been conditionalized for running on Alpha or VAX
This code must be revised to express an I64 condition.
- Code that uses OpenVMS system services that have dependencies on
the Alpha architecture
- Code with other dependencies on the Alpha architecture
- Code that uses floating-point data types
- Code that uses a command definition file
- Code that uses threads, especially custom-written tasking or stack
- Privileged code