Migrating an Application from OpenVMS VAX to OpenVMS Alpha

When a translated library has been replaced by a native version of the library, you need to define accordingly any logical names that point to it---that is, you need to redefine image_TV to image.

TIE Statistics and Feedback

In addition to the TIE's run-time support function, TIE statistics and feedback can help to improve translated image performance:

• The TIE can display statistics about the run-time execution of translated images. These statistics describe the image's use of TIE resources and the interactions between images.
• The TIE can record information about VAX entry points discovered while interpreting VAX code. When you retranslate the image, VEST uses the information to find and translate more VAX code.

DECmigrate for OpenVMS AXP Systems Translating Images describes these features in detail and explains how to define the logical names that enable and disable their use.

9.3.1 Problems and Restrictions

This section describes known problems and restrictions with the TIE.

9.3.1.1 Condition Handler Restriction

There is a permanent restriction on the type of condition handler that can be established for both native and translated images. A native routine cannot establish a translated condition handler, nor can a translated routine establish a native condition handler. If a native or translated image violates this restriction, the run-time results are unpredictable.

9.3.1.2 Exception Handler Restrictions

The following exception handler restrictions are permanent:

• Translated images with exception handlers that depend on receiving the correct program status longword (PSL) might not function properly. When exceptions are reported, the Alpha program status (PS) is reported in the signal array instead because there is no VAX PSL.
• Translated images with exception handlers that depend on modifying the PSL in the signal array do not function properly. The modified PSL is not propagated back to the faulting code.

The following floating-point restrictions are permanent:

• In some cases, floating-point instructions operating on the same data generate a trap on an Alpha system but not on a VAX system. Specifically, VAX floating-point instructions on OpenVMS Alpha generate traps for the "dirty zeros" that VAX hardware can handle correctly. "Dirty zeros" are floating-point values that are alternate encodings for zero. To retain compatibility with translated code that performs operations using dirty zeros, the TIE includes a condition handler that corrects the dirty zeros and retries the floating-point operation. However, the handler succeeds only if the qualifier /PRESERVE=FLOAT_EXCEPTIONS was used when the image was translated.
  Images that were not translated with /PRESERVE=FLOAT_EXCEPTIONS and that perform an operation on a dirty zero incur an HPARITH exception with a summary status that has bit 1 set. If your translated application incurs one of these exceptions, retranslate with /PRESERVE=FLOAT_EXCEPTIONS. VAX dirty zeros commonly result from not initializing floating data to 0. In this case, changes to source code may be necessary to port to OpenVMS Alpha an application that uses dirty zeros.
• Alpha D53 floating point (D_floating point as a 53-bit fraction instead of a 56-bit fraction) is VAX D_floating converted to G_floating representation. This conversion leads to the following problem. Consider the VAX instruction sequence:

  MOVD    (SP),R2 
  MOVD    R2,-(SP) 
  

  
  VEST translates these VAX instructions into Alpha code like the following:

  LDD     F2,0(R14)       ! Pick up D float 
  CVTDG   F2,F2           ! Convert to Canonical G Form with rounding 
  CVTGD   F2,F17          ! Convert back to D Form for storing 
  STD     F17,-8(R14)     ! Store the result 
  

  
  At run time, the VEST-generated code uses rounding to obtain the most accurate G_floating value when converting the D56 floating point to G canonical form. In some cases, the conversion to G canonical form may round up the D_floating value to create an exponent that cannot be represented in D_floating. When this happens, the CVTGD operation incurs an HPARITH trap with floating overflow as the summary reason.
  If a translated image incurs this problem at run time, it needs to be retranslated with the VEST qualifier /FLOAT=D56_FLOAT to execute properly.

Note the following interoperability restrictions:

• A native routine that either calls or is called by a translated image must be compiled with the /TIE qualifier and be linked with the /NONATIVE_ONLY qualifier. Checking for interoperability between native and translated images occurs at run time. If the /TIE and /NONATIVE_ONLY qualifiers are not used to compile and link the native routine, an error occurs at run time when the native routine and a translated image attempt to interoperate. If such an error occurs, recompile and relink the native routine appropriately.
• An access violation can occur at run time if a native routine that was not compiled with the /TIE qualifier makes an indirect call to a translated routine. The indirect call is made through a variable that contains the translated routine's address. When this happens, there is no autojacketing code in place to assist the native-to-translated call. The native code attempts to use the routine address as a native procedure descriptor. The code address of a native procedure is at offset PDSC$L_ENTRY, whose value is 8, from the base of the procedure descriptor. Because the translated routine address is treated as a procedure descriptor, the value at offset 8 from that address is used as the code to call. This usually results in an access violation.
  If you are encountering this problem, use a debugger to check the following:
  • Check that R27 points into a translated image.
  • Check that bits <31:2> of 8(R27) equal bits <31:2> of the access violation address. (All bits are not used because Alpha instructions are longword aligned.)
  • Check that R26 points into a native image.
  • Check that -4(R26) is a JSR R26,(26) instruction.
  If all these checks prove to be true, recompile the native routine with the /TIE qualifier to enable autojacketing at run time.

The following translated VAX C program restrictions are permanent:

• If a program uses the VAX C RTL routine brk() to release dynamic memory (that is, a break address lower than the current break address is requested), the next attempt by TIE to use a complex instruction routine may result in a fatal memory access violation. This may happen because the complex instruction routines are in a separate image, TIE$EMULAT_TV.EXE, which is dynamically activated by LIB$FIND_IMAGE_SYMBOL on the first use of one of the routines. Depending on when this occurs and the address passed to the brk() call that releases memory, the memory into which TIE$EMULAT_TV.EXE is loaded may also be released.
  To avoid this problem, never use brk() to release memory, or be sure to execute a complex VAX instruction before getting the break address that is later used to release memory. Using brk() to allocate memory is fine.
• A translated VAX C program that uses vfork() and any executive function may hang at run time. If the child process of the VAX C program aborts erroneously, it may hang waiting for a mailbox I/O to be completed. One workaround is to prevent the child process from aborting.

Translation support is provided to remove impediments for users moving to Alpha due to:

• Lack of full language support initially
• Unavailability of source code for recompilation
• Difficulty of recompiling code that depended heavily on certain features of the VAX architecture

For languages whose VAX versions are undergoing active development, native Alpha versions are now available. The TIE is being maintained to support those language features that were available as of the release of OpenVMS VAX Version 5.5-2.

Similarly, translation is supported for images whose use of system services and run-time library entry points is restricted to those that existed on OpenVMS VAX Version 5.5-2.

In cases where more recent VAX layered products have been installed, it may be necessary to take minor additional steps if application needs require rebuilding an image suitable for translation. For instance, with DECwindows Motif Version 1.2 or Version 1.2--3 for OpenVMS VAX, images must be built with the OSF Motif Version 1.1.3 library or the DECwindows XUI library rather than with the OSF Motif Version 1.2.2 or Version 1.2.3 library in order to be suitable for translation.

Similarly, for those using recent versions of DEC Fortran for VAX, an additional qualifier is required to compile Fortran programs that are suitable for translation.

For further information, see the release notes for particular VAX products.

As a safety measure for situations where future rebuilding and retranslation of OpenVMS VAX images is likely, it may be preferable to save copies of the relevant OpenVMS VAX Version 5.5-2 shareable images in a separate VAX directory and link new versions of VAX applications against those images. Using that technique the resulting images will be compatible with newer OpenVMS VAX shareable images (picking up any OpenVMS enhancements of existing features), and will also be properly built for translation to OpenVMS Alpha (by not requiring newer versions of shareable images).

The following sections list the translated images, image information files, and other related files that are provided with OpenVMS Alpha.

OpenVMS Alpha contains no translated message images. All message images have been made native.

Translated Images in SYS$LIBRARY:

• BASRTL2_D53_TV.EXE
• BASRTL2_D56_TV.EXE
• BASRTL_D56_TV.EXE
• BASRTL_TV_SUPPORT.EXE
• BLAS1RTL_D53_TV.EXE
• BLAS1RTL_D56_TV.EXE
• COBRTL_D56_TV.EXE
• DBLRTL_D56_TV.EXE
• EDTSHR_TV.EXE
• FORRTL2_TV.EXE
• FORRTL_D56_TV.EXE
• LIBRTL2_D56_TV.EXE
• LIBRTL_D56_TV.EXE
• MTHRTL_D53_TV.EXE
• MTHRTL_D56_TV.EXE
• PASRTL_D56_TV.EXE
• PLIRTL_D56_TV.EXE
• RPGRTL_TV.EXE
• SCNRTL_TV.EXE
• TECOSHR_TV.EXE
• TIE$EMULAT_TV.EXE
• UVMTHRTL_D53_TV.EXE
• UVMTHRTL_D56_TV.EXE
• VAXCRTLG_D56_TV.EXE
• VAXCRTL_D56_TV.EXE
• VMSRTL_TV.EXE

Translated Images in SYS$SYSTEM:

• DBLMSGMGR_TV.EXE
• EDF_TV.EXE
• EDT_TV.EXE
• MONITOR_TV.EXE
• TECO32_TV.EXE

Translated RTL Images in IMAGELIB:

• BASRTL2_D53_TV.EXE
• BASRTL_D56_TV.EXE
• BLAS1RTL_D53_TV.EXE
• COBRTL_D56_TV.EXE
• DBLRTL_D56_TV.EXE
• FORRTL2_TV.EXE
• FORRTL_D56_TV.EXE
• LIBRTL_D56_TV.EXE
• PLIRTL_D56_TV.EXE
• RPGRTL_TV.EXE
• SCNRTL_TV.EXE

Note that most of the translated RTLs are provided in D56 format rather than D53 format; some are provided in both formats. Where both formats are provided, the default format is D53. See Section 9.5 for more information about the translated run-time libraries.

Image Information Files in SYS$LIBRARY:

• ACLEDTSHR.IIF
• BASRTL2.IIF
• BASRTL.IIF
• BLAS1RTL.IIF
• COBRTL.IIF
• CONVSHR.IIF
• CRFSHR.IIF
• DBLRTL.IIF
• DCXSHR.IIF
• DISMNTSHR.IIF
• DTKSHR.IIF
• EDTSHR.IIF
• ENCRYPSHR.IIF
• EPC$SHR.IIF
• FDLSHR.IIF
• FORRTL.IIF
• FORRTL2.IIF
• INIT$SHR.IIF
• LBRSHR.IIF
• LIBRTL.IIF
• LIBRTL2.IIF
• MAILSHR.IIF
• MOUNTSHR.IIF
• MTHRTL.IIF
• NCSSHR.IIF
• P1_SPACE.IIF
• PASRTL.IIF
• PLIRTL.IIF
• PPLRTL.IIF
• PTD$SERVICES_SHR.IIF
• RPGRTL.IIF
• S0_SPACE.IIF
• SCNRTL.IIF
• SCRSHR.IIF
• SECURESHR.IIF
• SMBSRVSHR.IIF
• SMGSHR.IIF
• SORTSHR.IIF
• SPISHR.IIF
• TECOSHR.IIF
• TPUSHR.IIF
• UVMTHRTL.IIF
• VAXCRTL.IIF
• VAXCRTLG.IIF
• VMSRTL.IIF

System Logical Names Definitions

The following system logical names are defined to facilitate the translated environment:

• ACLEDTSHR_TV = ACLEDTSHR
• CDDSHR_TV = CDDSHR
• CONVSHR_TV = CONVSHR
• CRFSHR_TV = CRFSHR
• DCXSHR_TV = DCXSHR
• DISMNTSHR_TV = DISMNTSHR
• DTKSHR_TV = DTKSHR
• ENCRYPSHR_TV = ENCRYPSHR
• EPC$SHR_TV = EPC_SHR
• FDLSHR_TV = FDLSHR
• INIT$SHR_TV = INIT$SHR
• LBRSHR_TV = LBRSHR
• MAILSHR_TV = MAILSHR
• MOUNTSHR_TV = MOUNTSHR
• NCSSHR_TV = NCSSHR
• PPLRTL_TV = PPLRTL
• PTD$SERVICES_SHR_TV = PTD$SERVICES_SHR
• SCRSHR_TV = SCRSHR
• SECURESHR_TV = SECURESHR_JACKET
• SMBSRVSHR_TV = SMBSRVSHR
• SMGSHR_TV = SMGSHR
• SORTSHR_TV = SORTSHR
• SPISHR_TV = SPISHR
• TPUSHR_TV = TPUSHR
• BASRTL_TV = BASRTL_D56_TV
• BASRTL2_TV = BASRTL2_D53_TV
• BLAS1RTL_TV = BLAS1RTL_D53_TV
• COBRTL_TV = COBRTL_D56_TV
• DBLRTL_TV = DBLRTL_D56_TV
• FORRTL_TV = FORRTL_D56_TV
• LIBRTL_TV = LIBRTL_D56_TV
• LIBRTL2_TV = LIBRTL2_D56_TV
• MTHRTL_TV = MTHRTL_D53_TV
• PASRTL_TV = PASRTL_D56_TV
• PLIRTL_TV = PLIRTL_D56_TV
• VAXCRTL_TV = VAXCRTL_D56_TV
• VAXCRTLG_TV = VAXCRTLG_D56_TV
• DBLMSGMGR = DBLMSGMGR_TV
• EDTSHR_TV = EDTSHR
• TECO32 = TECO32_TV
• TECOSHR = TECOSHR_TV
• VMSRTL = VMSRTL_TV
• DBLRTLMSG = DBL$MSG
• PASMSG = PAS$MSG
• PLIMSG = PLI$MSG
• RPGMSG = RPG$MSG
• SCNMSG = SCN$MSG
• VAXCMSG = DECC$MSG

As part of the OpenVMS Alpha kit, Digital provides a set of translated run-time libraries.

Some of the routines in the VAX run-time libraries use the VAX D_floating data type for double-precision arithmetic.

In the translated versions of these libraries, the Alpha D56 D_floating data type is used by default (where the VAX run-time library used D_floating). This provides the full precision of the 56-bit mantissa in VAX D_floating, yielding consistency of results at a cost in execution-time performance.

For a handful of performance-critical math-related libraries, Digital also supplies versions of the translated run-time libraries that use the Alpha D53 D_floating data type for double-precision operations. For these libraries, the D53 forms are the default. The D53 forms provide better performance by sacrificing the low-order three bits of precision in the mantissa.

The following translated libraries are provided in D56 form only:

• BASRTL
• COBRTL
• DBLRTL
• FORRTL
• LIBRTL
• LIBRTL2
• PASRTL
• PLIRTL
• VAXCRTL
• VAXCRTLG

The following translated libraries are provided in both D56 and D53 (the default) form:

• BASRTL2
• BLAS1RTL
• MTHRTL
• UVMTHRTL

Accessing the D56 Form of the Run-Time Libraries

When you use the run-time libraries, the following happens by default:

• For BASRTL2, translated BASIC images that use MAT functions on double-precision data invoke BASIC run-time library routines that use the D53 data type.
• For BLAS1RTL, translated images that invoke BLAS$ functions with double-precision floating-point arguments get routines that use the D53 data type.
• For MTHRTL, translated images that invoke MTH$ double-precision floating-point functions get routines that use the D53 data type.
• For all others, the Alpha D56 floating-point data type is used by default.

Some users might need the full precision of D56 floating point. However, using the D56 routines imposes a very significant performance penalty. To access the D56 routines, redefine the run-time library's logical name to the D56 form, as shown in Table 9-2. The logical name can be defined on a per-process or systemwide basis, as appropriate for your site.

Table 9-2 Run-Time Library Logical Names

Library	Logical Name	D56 Name
BASRTL2	BASRTL2_TV	BASRTL2_D56_TV
BLAS1RTL	BLAS1RTL_TV	BLAS1RTL_D56_TV
MTHRTL	MTHRTL_TV	MTHRTL_D56_TV

9.5.1 CRF$FREE_VM and CRF$GET_VM: Translated Callers

Translated callers to CRF$FREE_VM and CRF$GET_VM will not work properly. The translated callers are expecting VAX JSB semantics, but instead, Alpha JSB semantics are present in the native code (naturally).

To work around this problem, the translated callers need to use CALL instead of JSB.

9.6 Translated VAX C Run-Time Library

The following sections contain release notes pertaining to the translated VAX C run-time library.

9.6.1 Problems and Restrictions

This section describes known problems and restrictions with the OpenVMS Alpha translated VAX C Run-Time Library (VAX C RTL).

9.6.1.1 Functional Restrictions

The translated VAX C RTL is a translated version of the OpenVMS VAX Version 5.4 VAX C RTL. All problems and restrictions present in that release of the VAX C RTL exist unchanged in the translated VAX C RTL. The following items are known restrictions in the functionality of the translated VAX C RTL:

• The fmod() function does not produce correct results for D_FLOAT.
• D_FLOAT programs that use the SIGFPE signal may not catch all floating-point exceptions. Translating the program using /FLOAT=D56_FLOAT fixes most SIGFPE problems.
• The sbrk() function returns an address that does not match the value returned from SYS$EXPREG.
• D_FLOAT programs that use the HUGE_VAL constant or call the math functions (which may return HUGE_VAL) may fail unless they are translated with /FLOAT=D56_FLOAT.
• Under certain circumstances, some math functions (either D_FLOAT or G_FLOAT) may generate a high-performance arithmetic trap exception instead of setting errno to ERANGE or EDOM.

The following restrictions apply when the translated VAX C RTL interoperates with the native DEC C RTL:

• The longjmp function cannot be used to transfer control from:
  • A native routine to a translated routine
  • A translated routine to a native routine
• Memory allocated by malloc, calloc, and so forth must be freed in the same context. That is, if a translated routine allocates memory, the free call must occur in a translated routine. Allocating memory in a translated routine and freeing it in a native routine results in corruption of the heap. Likewise, allocating memory in a native routine and freeing that memory in a translated routine also corrupts the heap.
• Signal handlers established by the signal (and related) functions in translated routines are not invoked when the signal is raised. Only native signal handlers can be used to catch UNIX style signals.
• The signals SIGEMT, SIGTRAP, SIGIOT, and SIGFPE cannot be caught if those signals are raised by a translated image.
• The exec function can be used only to invoke similar images. That is, an exec function invoked in a native image cannot execute a translated image. Likewise, an exec function invoked in a translated image cannot execute a native image.
• An access violation occurs if vfork is executed in a native image to establish the context for a later system call and the system call is then invoked in a translated image.
• File pointers and file descriptors cannot be shared between native and translated images. An access violation or file corruption is likely to occur if a file is opened in a translated image and a native image attempts to read or write using that file pointer. The same results occur if a file is opened in a native image and a translated image attempts to read or write using that file pointer.

Programs that perform any of these restricted actions may receive access violations or other exceptions. No testing is performed to detect and prevent restricted operations from being performed.

9.7 Translated VAX COBOL Programs

The OpenVMS Alpha operating system supports the execution of translated VAX COBOL programs compiled with the VAX COBOL Version 5.0 compiler (or earlier compilers).

9.7.1 Problems and Restrictions

Programs compiled with the VAX COBOL Version 5.1 compiler are not supported by the OpenVMS Alpha operating system.

This chapter describes how to create native Alpha images that can make calls to and be called by translated VAX images.

10.1 Overview

DECmigrate for OpenVMS AXP Systems Translating Images describes how to use the VAX Environment Software Translator (VEST) to convert a VAX executable or shareable image into a functionally equivalent Alpha image. (DECmigrate for OpenVMS Alpha is an optional layered product that supports the migration of a VAX application to an Alpha system. VEST is a component of the DECmigrate utility.)

Using VEST, you can translate all the components of an application, such as the main executable image and all the shareable images that it calls. However, you can also create an application that is a mix of translated and native components. For example, you may want to create a native version of a shareable image that is called by your application to take advantage of native performance. You may also choose to use a mixture of native and translated components to allow you to create a native version of your application in stages.

You can use translated VAX images as you would a native Alpha image. However, to create native images that can interoperate with translated images requires some additional considerations, described in the following sections.

10.1.1 Compiling Native Images That Can Interoperate with Translated Images

To create a native image that can call or be called by a translated image, you must specify the /TIE qualifier when compiling the source files of the native Alpha image. Any source module that contains a procedure that is made available to external callers must be compiled with the /TIE qualifier. When you specify the /TIE qualifier, the compilers create procedure signature blocks (PSBs) that are needed by the Translated Image Environment (TIE) at execution time in order to properly jacket calls between translated and native images. The TIE is part of the operating system.

You must also specify the /TIE qualifier when compiling a source module that contains a procedure that performs a callback (or calls out to a specified procedure) that may be in a translated image. In this case, the /TIE qualifier causes the compilers to generate a call to a special run-time library routine, OTS$CALL_PROC, that ensures that the outbound call to a translated procedure is handled properly.

In addition to the /TIE qualifier, you may need to specify other compiler qualifiers to ensure correct interoperation between a translated image and a native shareable image. For example, if the translated callers of a native shareable image use the VAX D_floating format for double-precision floating-point operations (the default for VAX languages), you must specify the /FLOAT=D_FLOAT qualifier because the default format for double-precision data on Alpha systems is not VAX D_floating. Consult compiler documentation to determine the exact qualifier syntax to specify VAX D_floating format. Note that, because the VAX D_floating data type is not supported by the Alpha architecture, its use adversely affects performance.

Depending on application-specific semantics, you may also need to specify other compiler qualifiers to force byte granularity, data alignment, and AST atomicity.

10.1.2 Linking Native Images That Can Interoperate with Translated Images

To create a native Alpha image that can call a translated VAX image, you must explicitly link the native object modules with the /NONATIVE_ONLY qualifier. (Note that /NATIVE_ONLY is the default used by the linker for this qualifier.) This qualifier causes the linker to include in the image the PSB information created by the compilers.

Because the /NONATIVE_ONLY qualifier affects only outgoing calls from native images to translated images, you do not need to specify it when creating a native Alpha image that will be called by a translated VAX image. The linker's default behavior (/NATIVE_ONLY qualifier) can prevent native images from calling translated images but not from being called by translated images.

Note that the layout of the symbol vector in the native version of the shareable image must match the layout of the symbol vector in the translated shareable image it replaces. For more information about replacing translated shareable images with native shareable images, see Section 10.3.

10.2 Creating a Native Image That Can Call a Translated Image

To create a native Alpha image that can make calls to a translated VAX shareable image, perform the following steps:

1. Translate the VAX shareable image. See DECmigrate for OpenVMS AXP Systems Translating Images for information about using VEST to translate VAX images.
2. Create a native Alpha version of the main program. Compile the source modules using a compiler that produces native Alpha code, specifying the /TIE qualifier on the command line.
3. Link the native object module with the translated VAX shareable image. Specify the translated image in a linker options file as you would any other shareable image.

To illustrate interoperability, consider the programs in Example 10-1 and Example 10-2. Example 10-1 calls the routine mysub that is defined in Example 10-2.

Example 10-1 Source Code for Main Program (MYMAIN.C)

#include <stdio.h> 
 
int mysub(); 
 
main() 
{ 
   int num1, num2, result; 
 
   num1 = 5; 
   num2 = 6; 
 
   result = mysub( num1, num2 ); 
   printf("Result is: %d\n", result); 
} 

Example 10-2 Source Code for Shareable Image (MYMATH.C)

int myadd(value_1, value_2) 
 int value_1; 
 int value_2; 
{ 
  int result; 
 
  result = value_1 + value_2; 
  return( result ); 
} 
 
int mysub(value_1,value_2) 
 int value_1; 
 int value_2; 
{ 
 int result; 
 
 result = value_1 - value_2; 
 return( result ); 
} 
 
int mydiv( value_1, value_2 ) 
  int value_1; 
  int value_2; 
{ 
  int result; 
 
  result = value_1 / value_2; 
  return( result ); 
} 
 
int mymul( value_1, value_2 ) 
  int value_1; 
  int value_2; 
{ 
  int result; 
 
  result = value_1 * value_2; 
  return( result ); 
} 

  6459P010.HTM
  OSSG Documentation
  22-NOV-1996 13:07:19.67

Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal