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

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:

• Procedure server images
• User-written agent images
• Images that call the ACMS Queued Task Services

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:

1. Before you translate the image, use the VEST/DEPENDENCY command to identify references to shareable images:

   $ 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;

   
   The output of this command identifies the shareable images that may be required in order to translate the vr_read_server.exe image. For some of the shareable images listed, there must be a corresponding Image Information File (IIF file). An IIF file is a text file that provides VEST with additional information to be used during the image translation. ACMS provides three image information files. These are:

   • ACMSHR.IIF
   • ACMTWPSHR.IIF
   • ACMRRSHR.IIF
   
   The ACMS installation procedure places the IIF files in the SYS$LIBRARY directory on your OpenVMS Alpha system. You must reference the IIF files when you issue the VEST command. Reference the IIF files in one of the following ways:
   • Define the VEST$INCLUDE logical name to point to the directory where the IIF files are located.
   • Copy the required IIF files to the directory where you plan to issue the VEST command.
   • Specify the /INCLUDE_DIRECTORY qualifier when you issue the VEST command and specify the directory where the IIF files are located.
   
   Based on the output of the VEST/DEPENDENCY command, the vr_read_server.exe procedure server image has dependencies on the following shareable images:

   ACMTWPSHR.EXE
   ACMSHR.EXE
   DTI$SHARE.EXE
   LIBRTL.EXE
   COBRTL.EXE

   
   You need an IIF file for each of the ACMS shareable images that are listed from the VEST/DEPENDENCY command. In addition, you need an IIF file for the language the source code was written in. In this case, the source code was written in COBOL. If calls are made to library routines from the COBOL source code, then an IIF file for the LIBRTL shareable image is also required.

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

2. Translate the image:

   $ VEST VR_READ_SERVER.EXE

   
   If the translation is successful, VEST creates the translated image in your current directory and names it by appending "_TV" to the output image file name as follows:

   VR_READ_SERVER_TV.EXE

3. Reflect the name change from VR_READ_SERVER.EXE to VR_READ_SERVER_TV.EXE.
   If the image you are translating is a procedure server image, and if logical names for procedure servers were not used, modify your task group definition. See Section 17.5.3.1 for more information.
   If the image you are translating is a user-written agent or a program that calls the ACMS Queued Task Services, see Section 17.5.3.2 for more information.

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

17.5.3.2 Running Translated Images

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:

• Use the translated name (file-spec_TV) when you issue the RUN command, or define a logical name to point the old name to the location and name of the translated image.
• If you use command procedures, modify your command procedures to use the translated name or define a logical name to point the old name to the location and name of the translated image.
• If you use a foreign command symbol, modify the symbol name to point to the location and name of the translated image or define a logical name to point the old name to the location and name of the translated image.

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.

To debug a translated image:

1. Map OpenVMS Alpha program counters to OpenVMS VAX program counters.
   Use the machine code listing generated by the VEST utility to do this. Issue the following command to generate the machine code listing:

   $ VEST/SHOW=MACHINE vax_image.exe

   
   VEST writes the output of this command in the VAX_IMAGE_TV.LIS file. The output shows the OpenVMS VAX machine code and the corresponding OpenVMS Alpha machine code.

2. Identify the routines or instructions in the machine code listing where you want to set breakpoints.
3. Locate the translated addresses corresponding to the routines or instructions in the machine code listing.
4. Set breakpoints at the translated addresses.

For detailed information on how to debug translated images, see the following documentation:

• OpenVMS Delta/XDelta Debugger Manual
• OpenVMS Debugger Manual
• DECmigrate for OpenVMS AXP Systems Translating Images

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 16.2.1.1. 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:

• I/O options and restrictions when distributing an application
• I/O options and restrictions when one of the nodes in a distributed environment is an OpenVMS Alpha node
• Task and menu selection on OpenVMS Alpha

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:

• TERMINAL I/O in a processing step
• REQUEST I/O in a processing step
• Clauses that run in a DCL server and require terminal I/O
  Tasks that run in a DCL server and require terminal I/O can be selected only from the system where the application is started. The following task definition clauses run in a DCL server:
  • DATATRIEVE COMMAND
  • DCL COMMAND
  • IMAGE
  
  The OpenVMS image specified in the IMAGE clause must be compatible with the platform on which the application is executing.

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.

Table 18-1 Processing Step I/O Options and Restrictions on OpenVMS VAX

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
	REQUEST I/O	Yes	No
BLOCK WITH NO I/O	NO I/O (Default)	Yes	Yes
	TERMINAL I/O	Yes	No
	REQUEST I/O	Yes	No
BLOCK WITH FORM I/O	NO I/O (Default)	Yes	Yes
	TERMINAL I/O	Yes	No
BLOCK WITH REQUEST I/O (Default)	NO I/O (Default) TERMINAL I/O REQUEST I/O	Yes Yes Yes	Yes No No
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.

Table 18-2 Exchange Step I/O Options on OpenVMS VAX

Block Step1	Exchange Step	Selectable on Local Node	Selectable on Remote Node
BLOCK WITH REQUEST I/O (Default)	READ, WRITE	Yes	Yes
	REQUEST	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:

• There is no DECforms that is compatible with ACMS on OpenVMS Alpha Version 1.5. ACMS requires DECforms Version 2.1 as the minimum version on OpenVMS Alpha. DECforms Version 2.1 is not supported on OpenVMS Alpha Version 1.5.
• TDMS is not available on OpenVMS Alpha.

The additional restrictions are:

• Any task that has DECforms FORM I/O can execute on OpenVMS Alpha, but must be selected from an OpenVMS VAX submitter node if the application is running on OpenVMS Alpha Version 1.5.
• Any task that has TDMS REQUEST I/O in exchange steps can execute on OpenVMS Alpha, but must be selected from an OpenVMS VAX submitter node.
• Any local task that has TDMS REQUEST I/O in processing steps cannot execute on OpenVMS Alpha.
• You cannot select a task from OpenVMS Alpha that uses TDMS in exchange steps. Also, you cannot select a task from OpenVMS Alpha Version 1.5 that uses DECforms in exchange steps. These tasks fail on selection.
  From OpenVMS Alpha, you can, however, select the following types of tasks:
  • Tasks that require no terminal interaction
  • Tasks that specify FORM/IO in the task definition if using OpenVMS Version 6.1
  • Tasks that specify STREAM I/O in the task definition
  • Local tasks that specify TERMINAL I/O in the task definition (see Table 18-3 for more information)

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.

Table 18-3 Processing Step I/O Options and Restrictions on OpenVMS Alpha

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
	REQUEST I/O	No	No	No
BLOCK WITH NO I/O	NO I/O (Default)	Yes	Yes	Yes
	TERMINAL I/O	Yes	No	No
	REQUEST I/O	No	No	No
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
	REQUEST I/O	No	No	No
BLOCK WITH STREAM I/O	NO I/O (Default)	Yes	Yes	Yes

Table 18-4 Exchange Step I/O Options and Restrictions on OpenVMS Alpha

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