Compaq ACMS for OpenVMS
Writing Applications


Previous Contents Index

17.5 Translating Images Using the VEST Utility

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:

Note

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.

17.5.3 Running VEST to Translate an Image

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:


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

17.5.3.1 Referencing Translated Procedure Server Images

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:

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.

Note

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:

  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:

17.6 Migrating DECforms Files to OpenVMS Alpha

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.


Chapter 18
I/O Options and Restrictions

This chapter describes the following:

18.1 Restrictions for Distributing an Application

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:

18.2 OpenVMS VAX Restrictions

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


1If you specify BLOCK WORK without explicitly assigning an I/O attribute, exchange and processing steps within the block use Request I/O by default.

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


1If you specify BLOCK WORK without explicitly assigning an I/O attribute, exchange and processing steps within the block use Request I/O by default.

18.3 OpenVMS Alpha Restrictions

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.

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


1If the task is selected from the OpenVMS Alpha Version 1.5 node, these are restrictions. However, you can use Compaq TP Desktop Connector (formerly ACMS Desktop) to perform FORM I/O on the block step on OpenVMS Alpha Version 1.5.
2If you use the RI or Compaq TP Desktop Connector (formerly ACMS Desktop) to perform REQUEST I/O on the block step, these are not restrictions.

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


1If you use the RI or Compaq TP Desktop Connector (formerly ACMS Desktop) to perform REQUEST I/O on the block step, these are not restrictions.
2If the task is selected from the OpenVMS Alpha Version 1.5 node, these are restrictions. However, you can use Compaq TP Desktop Connector (formerly ACMS Desktop) to perform FORM I/O on the block step on OpenVMS Alpha Version 1.5.


Previous Next Contents Index