HP OpenVMS Systems Documentation

Porting Applications from HP OpenVMS Alpha to HP OpenVMS Industry Standard 64 for Integrity Servers

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:

1. Setting up the migration environment.
2. Compiling your application on an Alpha system with the latest versions of the Alpha compilers.
3. Testing the application on an Alpha system to establish baselines for evaluating the migration.
4. Recompiling and relinking an application on an I64 system.
5. Debugging the migrated application.
6. Testing the migrated application.
7. 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 Section 3.3.

4.1.1 Hardware

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:

• CPUs
• Disks
• Memory

In an I64 environment, the following configuration is recommended for this release:

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

4.1.2 Software

To create an efficient migration environment, check the following elements:

• Migration tools
  You need a compatible set of migration tools, including the following:
  • Compilers
  • Translation tools
    • HP OpenVMS Migration Software for Alpha to Integrity Servers and
    • TIE
  • RTLs
  • 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.

Translation

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.

4.1.2.1 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 image.
• 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 include:
  • 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 code
  • Emulated Alpha stack
  TIE is invoked automatically for any translated image; you do not need to call it explicitly.

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:

• 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 I64.

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 not translate.

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

For native code to interoperate with translated code, it must meet the following requirements:

• 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 entry points.
• 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 is required.

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 CTL$GQ_TIE_SYMVECT.

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.

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.

4.5.1 Debugging

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 translated image.
• XDelta Debugger
  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.

4.5.2.1 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 I64 systems.

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.

4.5.2.2 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 architecture

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:

1. Get a complete set of standard data for the application prior to the migration.
2. Migrate your Alpha test suite along with the application (if the tests are not already available on I64).
3. Validate the test suite on an I64 system.
4. Run the migrated tests on the migrated application.

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 the following:

• Compiler differences
• Architectural differences
• Integration, such as modules written in different languages

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

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

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 name.
    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 $

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 another language.
• Code that has been conditionalized for running on Alpha or VAX systems
  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 switching
• Privileged code