Migrating an Application from OpenVMS VAX to OpenVMS Alpha

A number of native compilers and other tools are available for software development and migration on an Alpha platform.

3.2.1.1 Native Alpha Compilers

Recompiling and relinking an existing VAX source produces a native Alpha image that executes within the Alpha environment with all the performance advantages of a RISC architecture. For Alpha code, Digital is using a series of highly optimizing compilers. These compilers have a common optimizing code generator. However, they use a different front end for each language, each of which is compatible with a current VAX compiler.

For OpenVMS Alpha Version 7.1, native Alpha compilers are available for the following languages:

• Ada
• BASIC
• C
• C++
• COBOL
• FORTRAN
• Pascal
• PL/I
• MACRO-32 (cross compiler)

Later releases of OpenVMS Alpha may provide native compilers for other languages, including LISP.

VAX user-mode programs that are written in any other language can be run on an Alpha system by translating them with VEST. Compilers for other languages may be available through third-party vendors.

In general, the Alpha compilers provide command-line qualifiers and language semantics to allow code with dependencies on the VAX architecture to run on an Alpha system with little modification. For a list of such dependencies, see Table 2-3.

Some compilers on OpenVMS Alpha systems support new features not supported by their counterparts on OpenVMS VAX systems. To provide compatibility, some compilers support compatibility modes. For example, the DEC C compiler for OpenVMS Alpha systems supports a VAX C compatibility mode that is invoked by specifying the /STANDARD=VAXC qualifier.

In some cases, the compatibility is limited. For example, VAX C implements built-in functions that allow access to special VAX hardware features. Since the hardware architecture of VAX computers differs from Alpha computers, these built-ins are not available in DEC C for OpenVMS Alpha systems even when the /STANDARD=VAXC qualifier is used.

The compilers can also compensate for some architectural dependencies that may exist in your code. For example, the MACRO--32 compiler provides the /PRESERVE qualifier that can preserve granularity or atomicity or both.

The DEC C compiler provides a header file that defines typedefs for each data type. These typedefs map a generic data-type name, such as int64, to the machine-specific data type, such as __int64. For example, if you must have a data type that is 64 bits long, use the int64 typedef.

Review the documentation for your compiler to become familiar with all its features that support portability.

Chapter 11 describes in greater detail the process of using Alpha compilers to migrate OpenVMS VAX programs to an OpenVMS Alpha system.

3.2.1.2 VAX MACRO--32 Compiler for OpenVMS Alpha

The VAX MACRO--32 Compiler for OpenVMS Alpha is used to convert existing VAX MACRO code into machine code that runs on OpenVMS Alpha systems. It is included with OpenVMS Alpha for that purpose.

While some VAX MACRO code can be compiled without any changes, most code modules will require the addition of entry point directives. Many code modules will require other changes as well.

Note

The MACRO--32 compiler will attempt to call LIB$ESTABLISH if it is contained in the source code.

If MACRO--32 programs establish dynamic handlers by storing a routine address at 0(FP), they will work correctly when compiled on an OpenVMS Alpha system. However, you cannot set the condition handler address from within a JSB (Jump to Subroutine) routine, only from within a CALL_ENTRY routine.

The compiler generates code that is optimized for OpenVMS Alpha systems, but many features of the VAX MACRO language that provide the programmer with a high level of control make it more difficult to generate optimal code for OpenVMS Alpha systems. For new program development for OpenVMS Alpha, Digital recommends the use of mid- and high-level languages. For more information on the MACRO--32 compiler, see Porting VAX MACRO Code to OpenVMS Alpha.

3.2.1.3 Other Development Tools

Several other tools in addition to the compilers are available to create native Alpha images:

• OpenVMS Linker
  The OpenVMS Linker accepts VAX object files or Alpha object files to produce either a VAX image or an Alpha image, respectively. It also functions as a cross linker because it can produce Alpha images while running on VAX hardware, or VAX images while running on Alpha.
• OpenVMS Debugger
  The OpenVMS Debugger running on OpenVMS Alpha has the same command interface as the current OpenVMS VAX debugger. The graphical interface on OpenVMS VAX systems is also available on OpenVMS Alpha systems.
• OpenVMS Librarian utility
  The OpenVMS Librarian utility creates either VAX or Alpha libraries.
• OpenVMS Message utility
  The OpenVMS Message utility allows you to supplement the OpenVMS system messages with your own messages.
• MACRO--64 Assembler for OpenVMS Alpha
  The MACRO--64 assembler for OpenVMS Alpha systems is the native assembler for all Alpha computers. Unlike the VAX MACRO assembler, which is included with the OpenVMS VAX operating system, the MACRO--64 assembler is not included with the OpenVMS Alpha operating system. It can be purchased separately. In general, the mid- and high-level language compilers generate higher performance code for OpenVMS Alpha systems than the MACRO--64 assembler. Therefore, Digital recommends you use mid- and high-level compilers for new program development for OpenVMS Alpha systems. For more information about the MACRO--64 assembler, see the MACRO--64 Assembler for OpenVMS AXP Systems Reference Manual.
• ANALYZE/IMAGE
  The Analyze/Image utility can analyze either VAX or Alpha images.
• ANALYZE/OBJECT
  The Analyze/Object utility can analyze either VAX or Alpha objects.
• DECset
  DECset, a comprehensive set of CASE tools, includes the Language Sensitive Editor (LSE), Source Code Analyzer (SCA), Code Management System (CMS), Module Management System (MMS), and other components.

The process of translating a VAX image to run on an Alpha system is described in detail in DECmigrate for OpenVMS AXP Systems Translating Images. In general, the process is straightforward, although you may have to modify your code somewhat to get it to translate without error.

3.2.2.1 VAX Environment Software Translator (VEST) and Translated Image Environment (TIE)

The main tools for migrating VAX user-mode images to OpenVMS Alpha are a static translator and a run-time support environment:

• The VAX Environment Software Translator (VEST) is a utility that analyzes a VAX image and creates a functionally equivalent translated image. Using VEST, you will be able to do the following:
  • Determine whether a VAX image is translatable.
  • Translate the VAX image to an Alpha image.
  • Identify specific incompatibilities with OpenVMS Alpha 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 Alpha shareable image that supports translated images at run time. TIE provides the translated image with an environment similar to OpenVMS VAX and processes all interactions with the native Alpha system. Items that TIE provides include:
  • VAX instruction interpreter, which supports:
    • Execution of VAX instructions (including instruction atomicity) that is similar to their execution on a VAX system
    • Complex VAX instructions, as subroutines
  • VAX compatible exception handler
  • Jacket routines that allow communication between native and translated code
  • Emulated VAX stack
  TIE is invoked automatically for any translated image; you do not need to call it explicitly.

VEST locates and translates as much VAX code as possible into Alpha code. TIE interprets any VAX code that cannot be converted into Alpha instructions; for example:

• Instructions that VEST could not statically identify
• H_ and D56 (56-bit D_floating) floating-point operations

Note that you cannot specify dynamic interpretation of a VAX image on an Alpha system. You must use VEST to translate the image before it can run on OpenVMS Alpha.

Translating a VAX image produces an image that runs as a native image on Alpha hardware. The Alpha image is not merely an interpreted or emulated version of the VAX image, but contains Alpha instructions that perform operations identical to those performed by the instructions in the original VAX image. The Alpha .EXE file also contains the original VAX image in its entirety, which allows TIE to interpret any code that VEST could not translate.

VEST's analysis capability also makes it useful for evaluating programs that you intend to recompile, rather than translate.

See DECmigrate for OpenVMS AXP Systems Translating Images for a complete description of VEST and TIE. The manual explains in detail all the output that VEST generates, such as flowgraphs, and how to interpret it. The manual also explains how information provided in image information files (IIFs) created by VEST can help you improve the translated image's run-time performance.

3.3 Debugging and Testing the Migrated Application

Once you have migrated your application to OpenVMS Alpha, you may have to debug it.

You will also need to test the application for correct operation.

3.3.1 Debugging

The OpenVMS operating system provides the following debuggers:

• The OpenVMS Debugger supports debugging of both VAX and native Alpha programs. This debugger does not support the debugging of translated images.
  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, although you can if you wish.
  Although the OpenVMS Debugger does not generally work for translated images, it is helpful in one area. Since the translated image mimics the VAX registers, you can use the commands SHOW CALLS and SHOW STATE to get some VAX context for more detailed debugging.
• The Delta Debugger supports debugging of VAX and Alpha programs. This debugger also supports the debugging of translated images.
  The Delta 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 System-Code Debugger is a symbolic debugger that allows you to debug nonpageable code and device drivers running at any IPL.
• The Heap Analyzer provides a graphical representation of memory use in real time. This allows you to quickly identify inefficient memory usage in your application such as allocations that are made too often, memory blocks that are too large, fragmentation, or memory leaks.

Debugging must take place on Alpha hardware.

3.3.1.1 Debugging with the OpenVMS Debugger

On OpenVMS Alpha systems you can use the debugger with programs written in the following Digital languages:

• DEC Ada
• DEC BASIC
• DEC C
• DEC C++
• DEC COBOL
• DEC Fortran (VAX systems)
• Digital Fortran (Alpha systems)
• MACRO--32 (compiled with the MACRO-32 compiler)
• MACRO--64
• DEC Pascal
• DEC PL/I

The OpenVMS Debugger includes several features that address the architectural differences of OpenVMS Alpha code. These enable you to more easily debug code that you are porting to OpenVMS Alpha systems. For example, you can use the /UNALIGNED_DATA qualifier with the SET command to cause the debugger to break directly after any instruction that accesses unaligned data (such as a load word instruction which accesses data that is not on a word boundary).

You can use the /RETURN qualifier with the SET command for any routine. It is not limited to routines called with a CALLS or CALLG instruction as it is on an OpenVMS VAX system. For more information about features specific to OpenVMS Alpha systems, see the OpenVMS Debugger Manual.

When you debug your migrated application on an Alpha system with the OpenVMS Debugger, bear in mind the following considerations:

• You can use the debugger with programs written in any language for which there is an Alpha compiler available.
• The debugger does not support debugging of installed resident images. For more information on installed resident images, see the Bookreader version of the OpenVMS System Manager's Manual: Tuning, Monitoring, and Complex Systems.
• The debugger does not support debugging of inlined routines. If you attempt to debug an inlined routine, the debugger issues a message that it cannot access the routine:

  DBG> %DEBUG-E-ACCESSR, no read access to address 00000000 
  

For more information on debugging with the OpenVMS Debugger, see the OpenVMS Debugger Manual.

3.3.1.2 Debugging with the Delta Debugger

The Delta/XDelta Debugger (DELTA/XDELTA), running on OpenVMS Alpha systems, provides enhancements to existing commands and several new commands necessitated by the Alpha architecture. The enhancements include the display of base registers in decimal instead of hexadecimal notation and the ability to look at the internal process identification (PID) number of another process. For more information about how the Delta/XDelta Debugger operates on OpenVMS Alpha systems, see the OpenVMS Delta/XDelta Debugger Manual.

You can use the Delta Debugger to debug applications that are partly or completely translated.

Translated Applications

When attempting to debug a translated image, you should:

• Make sure that the program you are translating works correctly under OpenVMS VAX Version 7.1.
• Make sure that VEST and any IIF files for run-time libraries are of the same release as the version of OpenVMS Alpha you are using.
• Use the VEST qualifiers /DEBUG, /LIST, and /SHOW=MACHINE_CODE to capture Alpha and VAX instructions. (Note that in the listing, an asterisk identifies a VAX instruction.) Have the VAX map and listing for the VAX image at hand for comparison.

Mixed Applications

To debug an application that is partly native Alpha code and partly translated code, make sure that the native parts of the application were compiled using the /TIE qualifier; in addition, you must link the application with the /NO_NATIVE_ONLY linker option.

For more information on debugging with the Delta Debugger, see the OpenVMS Delta/XDelta Debugger Manual.

For more information on debugging translated images, contact a Digital support representative.

3.3.1.3 Debugging with the OpenVMS Alpha System-Code Debugger

The OpenVMS Alpha System-Code Debugger is available for debugging nonpageable system code and device drivers running at any IPL. The OpenVMS Alpha System-Code Debugger is a symbolic debugger. You can specify variable names, routine names, and so on, precisely as they appear in your source code. You can also display the source code where the software is executing and step through it by source line.

Note that running the System-Code Debugger requires two Alpha systems.

You can use this debugger to debug code written in the following languages:

• C
• BLISS
• VAX MACRO

Note

A BLISS compiler is available on the OpenVMS Freeware CD that ships with OpenVMS VAX Version 7.1 and OpenVMS Alpha Version 7.1.

The OpenVMS Alpha System-Code Debugger recognizes the syntax, data typing, operators, expressions, scoping rules, and other constructs of a given language. If your program is written in more than one language, you can change the debugging context from one language to another during a debugging session.

For more information about Step 2 drivers and the OpenVMS Alpha System-Code Debugger, see Writing OpenVMS Alpha Device Drivers in C.

3.3.2 Analyzing System Crashes

OpenVMS provides two tools for analyzing system crashes: the System Dump Analyzer and the Crash Log Utility Extractor.

3.3.2.1 System Dump Analyzer

The System Dump Analyzer (SDA) utility on OpenVMS Alpha systems is almost identical to the utility provided on OpenVMS VAX systems. Many commands, qualifiers, and displays are identical, although there are some additional commands and qualifiers, including several for accessing functions of the Crash Log Utility Extractor (CLUE) utility. Some displays have been adapted to show information specific to OpenVMS Alpha systems, such as processor registers and data structures.

While the SDA interface has changed only slightly, the contents of VAX and Alpha dump files and the entire process of analyzing a system crash from a dump differ significantly between the two computers. The Alpha execution paths leave more complex structures and patterns on the stack than VAX execution paths do.

To use SDA on a VAX computer, you must first familiarize yourself with the OpenVMS calling standard for VAX systems. Similarly, to use SDA on an Alpha system, you must familiarize yourself with the OpenVMS calling standard for Alpha systems before you can decipher the pattern of a crash on the stack.

The changes to SDA include the following:

• The displays of the SHOW CRASH and SHOW STACK commands contain additional information that make debugging fatal system exception bugchecks simpler.
• The SHOW EXEC command display includes additional information about executive images if they were loaded using image slicing. Slicing is a function performed by the executive image loader for executive images and by the OpenVMS Install utility for user-mode images. Slicing an executive image (or a user-mode image) greatly improves performance by reducing contention for the limited number of translation buffer entries.
• The MAP command, a new SDA command, enables you to map an address in memory to an image offset in a map file.
• A new symbol, FPCR, has been added to the symbol table. This symbol represents a floating-point register.

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 crash and are available only for the most recent crash, the crash history file (on OpenVMS VAX) and the summary crash history file with a separate listing file for each crash (on OpenVMS Alpha), are permanent records of system crashes.

The implementation differences between OpenVMS VAX and OpenVMS Alpha are shown in Table 3-1.

Table 3-1 CLUE Differences Between OpenVMS VAX and OpenVMS Alpha

Attribute	OpenVMS VAX	OpenVMS Alpha
Access method	Invoked as a separate utility.	Accessed through SDA.
History file	A cumulative file that contains a one-line summary and detailed information from the crash dump file for each crash.	A cumulative file that contains only a one-line summary for each crash dump. The detailed information for each crash is put in a separate listing file.
Uses in addition to debugging crash dumps	None.	CLUE commands can be used interactively to examine a running system.
Documentation	Bookreader versions of the OpenVMS System Manager's Manual and OpenVMS System Management Utilities Reference Manual	Bookreader versions of the OpenVMS System Manager's Manual and OpenVMS Alpha System Dump Analyzer Utility Manual

3.3.3 Testing

You must test your application to compare the performance and functionality of the migrated version with those of the original VAX version.

The first step in testing is to establish baseline values for your application by running your test suite on the VAX application.

Once your application is running on an Alpha system, there are two types of tests you will want to apply:

• The standard tests used for the VAX 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 Alpha is particularly important. Not only can the changes introduce errors into the application, but the new environment may bring out latent problems in the VAX 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 test suite along with the application (if the tests are not already available on Alpha).
3. Validate the test suite on an Alpha system.
4. Run the migrated tests on the migrated application.

While 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---changes in optimization and data alignment
• Architectural differences---changes in instruction atomicity, memory atomicity, and read/write ordering, for example
• Integration---modules written in different languages, or modules that had to be translated

Despite your best efforts, and following all the previous suggestions, you may encounter bugs that were in your program all along, but never caused a problem on an OpenVMS VAX system. For example, a failure to initialize some variable in your program might have been benign on a VAX computer but could produce an arithmetic exception on an Alpha computer. The same could be true 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 before making them available to other users.

3.4 Integrating the Migrated Application into a Software System

After you have migrated your application by recompiling or translating it, 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 VAX 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 environment, be sure that your application refers to the correct version.
  • Native VAX and native Alpha versions of an image have the same name.
  • The translated version of an image has the string "_TV" added to its name.
• Recompiled images may expect naturally aligned data, while translated images have unaligned data, like the original VAX image.

This chapter introduces the general process of moving an application that runs on a VAX system to an Alpha system by recompiling and relinking the source files that make up the application.

In general, if your application is written in a high-level programming language, you should be able to run it on an Alpha system with a minimum of effort. High-level languages insulate applications from dependence on the underlying machine architecture. In addition, the programming environment on Alpha systems for the most part duplicates the programming environment on VAX systems. Using native Alpha versions of the language compilers and the OpenVMS Linker utility (linker), you can recompile and relink the source files that make up your application to produce a native Alpha image.

If your application is written in VAX MACRO, you may be able to run it on an Alpha system with a minimum amount of effort, although it is more likely to contain some dependencies on the underlying VAX architecture, some of which may require your intervention.

Privileged applications, which run in inner modes or at elevated interrupt priority levels (IPLs), may require significant changes because of assumptions incorporated in the code about the internal operation of the operating system. Typically, such applications have also required significant changes after a major release of the OpenVMS VAX operating system.

Note

Remember that it is possible to introduce architectural dependencies even in applications written in high-level languages. In addition, hidden bugs in your application may come to light during the move to a new platform.

Many of the languages supported on VAX systems, such as FORTRAN and C, are also supported on Alpha systems. For information about the compilers for some common programming languages on Alpha systems, see Chapter 11.

  6459P004.HTM
  OSSG Documentation
  22-NOV-1996 13:07:09.21

Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal