[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

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

Order Number: BA442--90001

January 2005

This manual provides a framework for application developers who are migrating applications from HP OpenVMS Alpha to HP OpenVMS Industry Standard 64 for Integrity Servers.

Revision/Update Information: This is a new manual.

Software Version: OpenVMS I64 Version 8.2

OpenVMS Alpha Version 8.2

Hewlett-Packard Company Palo Alto, California

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, Itanium, and Xeon are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

Java is a U.S. trademark of Sun Microsystems, Inc.

UNIX is a registered trademark of The Open Group.

Printed in the US

ZK6673

Contents

Index

Preface

Intended Audience

Porting Applications from HP OpenVMS Alpha to HP OpenVMS Industry Standard 64 for Integrity Servers is intended for application developers who are planning to migrate applications from the OpenVMS Alpha operating system to the HP OpenVMS Industry Standard 64 for Integrity Servers (I64) operating system.

Document Structure

This document is organized as follows:

Chapter 1 includes an overview of the OpenVMS I64 8.2 operating system, including its evolution and its benefits.

Chapter 2 discusses fundamental differences between the OpenVMS Alpha and OpenVMS I64 operating systems.

Chapter 3 outlines a process for assessing applications in preparation for porting to OpenVMS I64.

Chapter 4 discusses specific tasks that must be completed to prepare source modules for migration, as well as information about compiling, linking, testing, and deploying ported applications.

Chapter 5 discusses the OpenVMS I64 development environment.

Chapter 6 discusses porting considerations related to the primary compilers that will be available for OpenVMS I64.

Chapter 7 discusses other factors to consider when undertaking a porting effort.

Appendix A contains a sample checklist for use when evaluating applications prior to porting.

Appendix B lists the HP layered products that are supported on OpenVMS Alpha but not on OpenVMS I64.

Appendix C describes how to use KP routines when porting application-specific stack-switching code to I64.

The Glossary defines important terms and abbreviations used in this manual.

Reader's Comments

HP welcomes your comments on this manual. Please send comments to either of the following addresses:

Internet	openvmsdoc@hp.com
Postal Mail	Hewlett-Packard Company 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:

http://www.hp.com/go/openvms/doc/order

Conventions

The following conventions may be used in this manual:

Ctrl/ x	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.
PF1 x	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 button.
`[Return]`	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 possibilities: 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	Bold type represents the introduction of a new term. It also represents the name of an argument, an attribute, or a reason.
italic type	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	Uppercase type indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
`Example`	This typeface indicates code examples, command examples, and interactive screen displays. In text, this type also identifies URLs, UNIX commands and pathnames, PC-based commands and folders, and certain elements of the C programming language.
-	A hyphen at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.
numbers	All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

Chapter 1
Introduction

This chapter contains an introduction to OpenVMS Industry Standard 64 for Integrity Servers (I64) systems and an overview of the migration process.

For more information, refer to the HP OpenVMS Version 8.2 Release Notes.

1.1 OpenVMS Industry Standard 64 for Integrity Servers

The OpenVMS I64 architecture has a 64-bit model and basic system functions similar to the Alpha architecture; thus the great majority of applications running on OpenVMS Alpha today can be easily ported to the I64 architecture with few changes.

The OpenVMS Alpha and OpenVMS I64 architecture variants of OpenVMS are produced from a single-source code base; thus, nonhardware dependent features may be incorporated into both versions without multiple changes to the source code, thereby minimizing the time required to perform qualification testing, and helping to ensure the availability of critical applications on both OpenVMS platforms.

HP intends to maintain a strict policy of ensuring forward source compatibility so that "well-behaved" applications that currently run on recommended versions of OpenVMS Alpha run successfully on OpenVMS I64 systems. If an application takes advantage of published system services and library interfaces, there should be a high level of confidence that the application will move without modifications to the latest version of OpenVMS I64.

OpenVMS I64 has the same look and feel familiar to OpenVMS customers. Minor changes were made to accommodate the new architecture, but the basic structure and capabilities of OpenVMS are the same.

1.2 Overview of the Porting Process

This section provides an overview of the porting process as it applies to most applications.

1.2.1 Evaluating the Application

Evaluating the application identifies the steps necessary for its migration to HP OpenVMS I64. The result of the evaluation should be a migration plan that answers the following questions:

How to migrate the application
How much time, effort, and cost the migration requires
Whether you require support from HP services

Evaluation should include the following three stages:

A general inventory of the application, including identifying dependencies on other software
Source analysis to identify dependencies on other software
Selection of a migration method (rebuilding from sources or using a binary translator)

Completing these steps yields the information necessary to write an effective migration plan.

The first step in evaluating an application for migration is to determine exactly what has to be migrated. This includes not only the application itself, but everything that the application requires in order to run properly. To begin evaluating your application, identify and locate the following items:

Parts of the application
- Source modules for the main program
- Shareable images
- Object modules
- Libraries (object module, shareable image, text, or macro)
- Data files and databases
- Message files
- Documentation
Other software on which your application depends; such as:
- Run-time libraries
- HP layered products
- Third-party layered products
Required operating environment
- System characteristics
  What sort of system is required to run and maintain your application? For example, how much memory is required, how much disk space, and so on?
- Build procedures
  This includes HP tools such as Code Management System (CMS) and Module Management System (MMS).
- Test Suite
  Your tests must be able both to confirm that the migrated application runs correctly and to evaluate its performance.

Many of these items have already been migrated to OpenVMS I64; for example:

HP software bundled with the OpenVMS operating system
- Run-time libraries
- Other shareable libraries, such as those supplying callable utility routines and other application library routines
HP layered products
- Compilers and compiler RTLs
- Database managers
- Networking environment
Third-party products
Many third-party products now run on OpenVMS I64. To determine whether a particular application has been migrated, contact the application vendor.

You are responsible for migrating your application and your development environment, including build procedures and test suites.

When you have completed the evaluation of your application, continue with a more detailed evaluation of each module and image, as described in Chapter 4.

Chapter 2
Fundamental Differences to Consider

This chapter discusses the fundamental differences between the Alpha and I64 architectures.

2.1 Calling Standard

As with other components, the implementation of the OpenVMS Calling Standard on the Intel® Itanium® processor family sought to differ as little as possible from the OpenVMS VAX and Alpha conventions. The design methodology started with Itanium conventions and made changes only where necessary. This helped to maintain compatibility with historical OpenVMS design while minimizing the cost and difficulty of porting applications and the operating system itself to the Itanium architecture.

The following sections contain a high-level description of differences between the Itanium® Software Conventions and Runtime Architecture Guide and the OpenVMS Calling Standard. For more detailed information, see the HP OpenVMS Calling Standard.

2.1.1 Changes to the OpenVMS Calling Standard

Table 2-1 describes the major changes to the OpenVMS Calling Standard to for OpenVMS I64.

**Table 2-1 OpenVMS Calling Standard Changes**
Item	Description
Data model	OpenVMS on Alpha systems is deliberately ambiguous about the data model in use: many programs are compiled using what appears to be an ILP32 model, yet most of the system operates as though using either a P64 or LP64 model. The sign extension rules for integer parameters play a key role in making this more or less transparent. OpenVMS I64 preserves this characteristic, while the Itanium architecture conventions define a pure LP64 data model.
Data terminology	This specification uses the terms word and quadword to mean 2 bytes and 8 bytes, respectively, while the Itanium terminology uses these words to mean 4 bytes and 16 bytes, respectively.
General register usage	General registers are used for integer arithmetic, some parts of VAX floating-point emulation, and other general-purpose computation. OpenVMS uses the same (default) conventions for these registers except for the following cases: R8 and R9 (only) are used for return values. R10 and R11 are used as scratch registers and not for return values. R25 is used for an AI (argument information) register.
Floating-point register usage	Floating-point registers are used for floating-point computations, some parts of VAX floating-point emulation, and certain integer computations. OpenVMS uses the same (default) conventions for these registers except in the following cases: F8 and F9 (only) are used for return values. F10 through F15 are used as scratch registers and not for return values.
Parameter passing	OpenVMS parameter passing is similar to the Itanium conventions. Note the following differences in the OpenVMS standard: The OpenVMS standards adds an argument information register (for argument count and parameter type information). No argument is ever duplicated in both general and floating-point registers. For parameters that are passed in registers, the first parameter is passed in either the first general-register slot (R32) or the first floating-point register slot (F16), the second parameter in either the second general register (R33) or second floating-point register (F17) slot, and so on. Floating-point parameters are not packed into the available floating-point registers, and a maximum of eight parameters total are passed in registers. For 32-bit parameters passed in the general registers, the 32-bit value is sign extended to the full 64-bit width of the parameter slot by replicating bit 31 (even for unsigned types). There is no even slot alignment for arguments larger than 64 bits. There is no special handling for HFA (homogeneous floating-point aggregates) in general, although some rules for complex types have a similar benefit. OpenVMS implements __float128 pass-by value semantics using a reference mechanism. OpenVMS supports only little-endian representations. OpenVMS supports three additional VAX floating-point types for backward compatibility: F_floating (32 bits), D_floating (64 bits), and G_floating (64 bits). Values of these types are passed using the general registers.
Return values	Return values up to at most 16 bytes in size may be returned in registers; larger return values are returned using a hidden parameter method using the first or second parameter slot.

2.1.2 Extensions to the OpenVMS Calling Standard

Table 2-2 describes additions to or extensions of the OpenVMS Calling Standard.

**Table 2-2 OpenVMS Calling Standard Extensions**
Item	Description
Floating-point data types	The OpenVMS calling standard includes support for the VAX F_floating (32-bit), D_floating (64-bit), and G_floating (64-bit) data types found on VAX and Alpha systems; it omits support for the 80-bit double-extended floating-point type of the Itanium architecture.
VAX compatible record layout	The OpenVMS standard adds a user-optional, VAX-compatible record layout.
Linkage options	OpenVMS allows additional flexibility and user control in the use of the static general registers as inputs, outputs, global registers and whether used at all.
Memory stack overflow checking	OpenVMS defines how memory stack overflow checking should be performed.
Function descriptors	OpenVMS defines extended forms of function descriptors to support additional functionality for bound procedure values and translated image support.
Unwind information	OpenVMS adds an operating system-specific data area to the unwind information block of the Itanium architecture. The presence of an operating system-specific data area is indicated by a flag in the unwind information header.
Handler invocation	OpenVMS does not invoke a handler while control is in either a prologue or epilogue region of a routine. This difference in behavior is indicated by a flag in the unwind information header.
Translated images	OpenVMS adds support (signature information and special ABIs) for calls between native and translated VAX or Alpha images.

2.2 Floating-Point Arithmetic

This section discusses the differences in floating-point arithmetic on OpenVMS VAX, OpenVMS Alpha, and OpenVMS I64 systems.

2.2.1 Overview

The Alpha architecture supports both IEEE and VAX floating-point formats in hardware. OpenVMS compilers generate code using the VAX formats by default, with options on Alpha to use IEEE formats. The Itanium architecture implements floating-point arithmetic in hardware using the IEEE floating-point formats, including IEEE single and IEEE double.

If an application was originally written for OpenVMS VAX or OpenVMS Alpha using the default floating-point formats, it can be ported to OpenVMS I64 in one of two ways: continue to use VAX floating-point formats utilizing the conversion features of the HP compilers or convert the application to use IEEE floating-point formats. VAX floating-point formats can be used in those situations where access to previously generated binary floating-point data is required. HP compilers generate the code necessary to convert the data between VAX and IEEE formats.

For details about the conversion process, see the "OpenVMS Floating-Point Arithmetic on the Intel® Itanium® Architecture" white paper. See the Related Documents section in the Preface for the web location of this white paper.

IEEE floating-point format should be used in those situations where VAX floating-point formats are not required. The use of IEEE floating-point formats will result in more efficient code.