DECmigrate for OpenVMS is a layered product that facilitates migrating
OpenVMS VAX applications to OpenVMS Alpha systems. The VAX
Environment Software Translator (VEST) is a DECmigrate utility
that converts an OpenVMS VAX executable or shareable image into a
translated image for an OpenVMS Alpha system. If DECmigrate is
installed on your system, you can use it to translate OpenVMS VAX
17.5.1 Overview of the VEST Utility
VEST accepts as input an OpenVMS VAX image file (for example, a
procedure server image or a user-written agent image) and creates a
translated image that can be used on an OpenVMS Alpha system. When the
translated image runs, the OpenVMS Alpha system transparently supports
the image with an environment that allows it to run as if it were on an
OpenVMS VAX system. In that support environment, the average translated
image runs as fast as or faster than the original running on an
equivalent OpenVMS VAX system.
17.5.2 ACMS Images that Can Be Translated
You can translate the following ACMS images:
The VEST utility cannot translate all OpenVMS VAX images. There are some restrictions. For example, images linked prior to VAX VMS Version 4.0 and most privileged images cannot be translated. For more information on images that cannot be translated, see DECmigrate for OpenVMS AXP Systems Translating Images.
The example in this section shows the steps involved in translating a procedure server image. These same steps can be used for translating a user-written agent or a program that calls the ACMS Queued Task Services.
Perform the following steps to translate an OpenVMS VAX image:
$ VEST/DEPENDENCY VR_READ_SERVER.EXE %VEST-I-READIMAGE, Reading image file VR_READ_SERVER.EXE; %VEST-I-READIMAGE, Reading image file SYS$COMMON:[SYSLIB]ACMTWPSHR.EXE; %VEST-I-READIMAGE, Reading image file SYS$COMMON:[SYSLIB]ACMSHR.EXE; %VEST-I-READIMAGE, Reading image file SYS$COMMON:[SYSLIB]DTI$SHARE.EXE; %VEST-I-READIMAGE, Reading image file SYS$COMMON:[SYSLIB]LIBRTL.EXE; %VEST-I-READIMAGE, Reading image file SYS$COMMON:[SYSLIB]COBRTL.EXE;
Although DTI$SHARE appears as a dependency, there is no IIF file for this shareable image. It appears as a dependency because the ACMS shareable images have a dependency on it.
$ VEST VR_READ_SERVER.EXE
Modify your task group definition to use a logical name rather than a file specification in the PROCEDURE SERVER IMAGE clause. The server in the following example references a server by the name of VR_READ_SERVER:
SERVERS ARE vr_read_server: PROCEDURE SERVER IMAGE IS "avertz_default:vr_read_server.exe"; INITIALIZATION PROCEDURE IS vr_read_init; RUNDOWN ON CANCEL IF INTERRUPTED; PROCEDURES ARE vr_compute_bill_proc, vr_find_cu_proc, vr_find_si_proc, vr_find_ve_vrh_proc, vr_find_res_proc, vr_res_details_proc; DEFAULT OBJECT FILE IS "avertz_default:vr_read_server.obj"; END SERVER;
If you translate the VR_READ_SERVER procedure server image, the translated name is VR_READ_SERVER_TV.EXE.
Modify the PROCEDURE SERVER IMAGE clause and replace the server name with a logical name. For example, replace "avertz_default:vr_read_server.exe" with "vr_read_server_log". Then rebuild the task group with the new logical name.
Before you start your ACMS application, you need to define a logical name, vr_read_server_log, that points to the translated image. One way of doing this is:
$ DEFINE/SYSTEM VR_READ_SERVER_LOG DISK1$:[ACMS.ALPHA.IMAGES]VR_READ_SERVER_TV.EXE
If you want to reference the OpenVMS VAX version of the executable image, define the logical name to point to the OpenVMS VAX image. You do not need to modify and build the task group again. For example:
$ DEFINE/SYSTEM VR_READ_SERVER_LOG DISK1$:[ACMS.VAX.IMAGES]VR_READ_SERVER.EXE
As the example in Section 17.5.3 shows, you need to reflect the name change when you reference a translated image. If you are running a user-written agent or a program that calls the ACMS Queued Task Services, you can accommodate the change in the image name in one of the following ways:
For more information on translating images, see DECmigrate for OpenVMS AXP Systems Translating Images.
17.5.4 Debugging Translated Images
Debugging translated images involves debugging at the machine code level. You can use either the OpenVMS Delta Debugger or the OpenVMS Debugger to debug images that have been translated with the VEST utility.
Although the OpenVMS Debugger supports debugging by symbol name and by source code line, you cannot use these methods to debug translated images.
You must be able to debug at the machine code level to effectively debug translated images.
To debug a translated image:
$ VEST/SHOW=MACHINE vax_image.exe
For detailed information on how to debug translated images, see the following documentation:
The best method for migrating DECforms .FORM or .EXE files from an OpenVMS VAX system is to copy the .IFDL files to the OpenVMS Alpha system and build them on the OpenVMS Alpha system. This provides the best DECforms performance.
DECforms form image files (.EXE) must either be built on the OpenVMS Alpha system or translated from OpenVMS VAX files. For information about building DECforms files on OpenVMS Alpha, refer to Section 126.96.36.199. For information about using the VEST utility, refer to Section 17.5.
DECforms .FORM files are compatible between OpenVMS VAX and OpenVMS
Alpha. Therefore, you can copy .FORM files built on one platform to the
other platform. Note, however, that the alignment of the form and data
structures are "Aligned" on the OpenVMS Alpha system and "VAX
Compatible" on the OpenVMS VAX system. If you copy the .FORM files, be
sure that any programs interfacing with the forms are compiled with the
default alignment for that OpenVMS system.
17.6.1 Upgrading to DECforms Version 2.1 from Prior Versions
DECforms .FORM and .EXE files are backwards compatible. Form files
built with Version 2.0 of DECforms and earlier work with DECforms
Version 2.1. However, because there have been changes to the internal
structure of the .FORM files with the Version 2.1 release of DECforms,
the performance is better if you rebuild the .FORM and .EXE files using
DECforms Version 2.1.
17.6.2 Using DECforms on Multiple Platforms
If your application uses DECforms on both OpenVMS Alpha and OpenVMS VAX submitter nodes, see Section 16.2.
This chapter describes the following:
It is important to know the I/O methods that the tasks in your application use when you are determining whether or not you can distribute the application. There are defaults for the I/O attributes, and, in some cases, it is not obvious by looking at the task definition to see what the I/O attributes of the task are.
You can use the ADU DUMP GROUP command to display the contents of the task group database. The output of this command shows the I/O type of each task in the task group. The ADU DUMP GROUP command lists the I/O type of each block, exchange, and processing step for each task in the task group. For example:
ADU> DUMP GROUP VR_TASK_GROUP.TDB/OUTPUT=VR_TASK_GROUP_DUMP.DMP
You cannot distribute tasks that have the following:
Table 18-1 shows the legal combinations of I/O attributes on block and processing steps and whether or not the resulting task is available to a user on a local or a remote node.
The combinations listed in Table 18-1 apply when all the nodes in a distributed system are OpenVMS VAX nodes. The restrictions listed in Table 18-1 existed prior to ACMS Version 4.0. They are included here for purposes of review.
|Block Step1||Processing Step||Selectable on Local Node||Selectable on Remote Node|
|No BLOCK step (Single-step task)||NO I/O||Yes||Yes|
|TERMINAL I/O (Default)||Yes||No|
|BLOCK WITH NO I/O||NO I/O (Default)||Yes||Yes|
|BLOCK WITH FORM I/O||NO I/O (Default)||Yes||Yes|
|BLOCK WITH REQUEST I/O (Default)||
NO I/O (Default)
|BLOCK WITH STREAM I/O||NO I/O (Default)||Yes||Yes|
Table 18-2 shows the legal combinations of I/O attributes on block and exchange steps. Note that there are no restrictions. These OpenVMS VAX combinations existed prior to ACMS Version 4.0. They are included here for purposes of review.
|Block Step1||Exchange Step||Selectable on Local Node||Selectable on Remote Node|
|BLOCK WITH REQUEST I/O (Default)||READ, WRITE||Yes||Yes|
|BLOCK WITH FORM I/O||SEND, RECEIVE, or TRANSCEIVE||Yes||Yes|
|BLOCK WITH STREAM I/O||READ, WRITE||Yes||Yes|
A system configured with an OpenVMS Alpha submitter node has the following restrictions:
The additional restrictions are:
Table 18-3 shows the additional restrictions for processing steps on an OpenVMS Alpha system. Table 18-4 shows the restrictions for exchange steps on an OpenVMS Alpha system.
|Block Step||Processing Step||Selectable from Local Alpha Node||Selectable from VAX to an Application on Remote Alpha Node||Selectable from Alpha to an Application on Remote VAX or Remote Alpha|
|No BLOCK step (Single-step task)||NO I/O||Yes||Yes||Yes|
|TERMINAL I/O (Default)||Yes||No||No|
|BLOCK WITH NO I/O||NO I/O (Default)||Yes||Yes||Yes|
|BLOCK WITH FORM I/O||NO I/O (Default)||Yes 1||Yes||Yes 1|
|TERMINAL I/O||Yes 1||No||No|
|BLOCK WITH REQUEST I/O (Default)||NO I/O (Default)||No 2||Yes||No 2|
|TERMINAL I/O||No 2||No||No|
|BLOCK WITH STREAM I/O||NO I/O (Default)||Yes||Yes||Yes|
|Block Step||Exchange Step||Selectable from Local Alpha Node||Selectable from VAX to an Application on Remote Alpha Node||Selectable from Alpha to an Application on Remote VAX or Remote Alpha|
|BLOCK WITH REQUEST I/O (Default)||READ, WRITE||No 1||Yes||No 1|
|REQUEST||No 1||Yes||No 1|
|BLOCK WITH FORM I/O||SEND, RECEIVE, or TRANSCEIVE||Yes 2||Yes||Yes 2|
|BLOCK WITH STREAM I/O||READ, WRITE||Yes||Yes||Yes|