HP OpenVMS Systems Documentation
Compaq ACMS for OpenVMS
ACMS supports the same set of features on both OpenVMS VAX and OpenVMS Alpha systems, including DECforms support. This part of the manual describes the following:
Although ACMS supports DECforms Version 2.1B on systems running OpenVMS Alpha Version 6.1 or higher, excluding OpenVMS Alpha Version 7.0, TDMS and DECforms Version 1.4 are not available on OpenVMS Alpha. Therefore, if your application uses either one of these products for any of its presentation services, refer to Chapter 18 for restrictions.
Refer to the ACMS Software Product Description (SPD) and the DECforms SPD for supported versions and platforms.
This chapter describes how to write applications using ACMS for OpenVMS
Alpha, focusing on information that is specific to ACMS on OpenVMS
16.1 Writing an ACMS Application for OpenVMS Alpha
For the most part, you write your ACMS applications the same way you would for OpenVMS VAX. The main difference is that with the exception of TDMS requests you build the source components on OpenVMS Alpha instead of OpenVMS VAX. Refer to Section 16.2.3 for restrictions on TDMS.
An ACMS application typically consists of the following source components:
Follow these steps to build an ACMS application for OpenVMS Alpha:
VAX and Alpha object libraries (OLBs) are incompatible. If a server procedure references procedures in an OLB, you must rebuild the OLB.
All form files (DECforms form image files and TDMS request libraries) used by an application must be on the same node on which the application is started because the application execution controller (EXC) checks that all files are present when the application starts. This is necessary in order for ACMS to cache the form files or request libraries to the submitter node when a user selects a task that uses DECforms or TDMS in exchange steps.
The form image files or request libraries must be in the location specified in the task group definition.
The following line from a task group definition file shows that the form file is in the directory pointed to by the AVERTZ_DEFAULT logical name:
. . . FORM IS vr_form IN "avertz_default:vr_form.form"; . . .
In this example, the VR_FORM.FORM form file must be in the AVERTZ_DEFAULT directory.
The following line from a task group definition file shows that the request library is in the directory pointed to by the AVERTZ_DEFAULT logical name:
. . . REQUEST LIBRARY IS "avertz_default:deprmsrlb.rlb"; . . .
In this example, the DEPRMSRLB.RLB request library must be in the
AVERTZ_DEFAULT directory on OpenVMS Alpha.
16.2.1 Formatting and Naming DECforms Form Image Files
The DECforms form image files (.EXE) on the application node must have the image format expected on the submitter node:
If all submitter nodes are of the same platform, either all OpenVMS Alpha nodes or all OpenVMS VAX nodes, create a form image file for the submitter node's platform and copy it to the application node in the location specified in the FORMS clause of the task group definition.
If the submitter nodes are a mixture of OpenVMS Alpha nodes and OpenVMS VAX nodes, create two form file images for each form (one for the OpenVMS Alpha submitter nodes and one for the OpenVMS VAX submitter nodes) and place them on the application node in the location specified in the FORMS clause of the task group definition.
Use the following naming convention to distinguish executables for each of the two platforms when you have a mixture of OpenVMS Alpha and OpenVMS VAX submitter nodes:
The DECforms form image files have the .EXE file type in the FORMS clause of the task group definition and are the only file types that require special attention. The DECforms form files have the .FORM file type or have no type specified in the FORMS clause. These files will function as they have in the past on both VAX and Alpha systems.
Table 16-1 illustrates the six possible environments.
|Option||Submitter Node(s)||Application Node||Form Image File|
|1||OpenVMS VAX||OpenVMS VAX||form_name.EXE (VAX image)|
|2||OpenVMS Alpha||OpenVMS VAX||form_name.EXE (Alpha image)|
|3||OpenVMS VAX||OpenVMS Alpha||form_name.EXE (VAX image)|
|4||OpenVMS Alpha||OpenVMS Alpha||form_name.EXE (Alpha image)|
|5||OpenVMS VAX and OpenVMS Alpha||OpenVMS VAX||form_name.EXE_VAX (VAX image) and form_name.EXE_AXP (Alpha image)|
|6||OpenVMS VAX and OpenVMS Alpha||OpenVMS Alpha||form_name.EXE_VAX (VAX image) and form_name.EXE_AXP (Alpha image)|
For options 1 through 4, create a form image file for the submitter node's platform (OpenVMS VAX or OpenVMS Alpha) and put it in the location specified in the FORMS clause of the task group definition on the application node.
For options 5 and 6 create two separate form image files, one for each platform (OpenVMS VAX and OpenVMS Alpha). Then rename the form image files using the naming convention defined above and put the new files in the location specified in the FORMS clause of the task group definition on the application node.
Options 2 and 3 assume that tasks using form images are not selected locally on the application node.
There are a few differences in building DECforms files on OpenVMS Alpha compared to OpenVMS VAX. An overview of the primary differences is provided here. For full details about using DECforms on OpenVMS Alpha, refer to the DECforms Version 2.x Release Notes and the DECforms manuals.
When translating the .IFDL file on OpenVMS Alpha, you have the option of taking advantage of the OpenVMS Alpha natural alignment (by default) or specifying that you do not want to use natural alignment by using the /NOMEMBER_ALIGNMENT qualifier. In order to use the default alignment, the workspace definitions must be longword aligned. When you specify/NOMEMBER_ALIGNMENT, the form-file and data-records are byte aligned, that is, they are using the "VAX Compatible" record layout scheme. You can use this qualifier if your form files need byte-alignment to be compatible with other parts of the application that are byte-aligned.
If you want to use the default "Aligned" record layout scheme, use the command:
$ FORMS TRANSLATE <form-name>
If you want to use the "VAX Compatible" record layout scheme, use this command:
$ FORMS TRANSLATE/NOMEMBER_ALIGNMENT <form-name>
Extract the object file the same way as on OpenVMS VAX:
$ FORMS EXTRACT OBJECT <form-name>
The link command for DECforms shareable images on OpenVMS Alpha has a different format than on OpenVMS VAX. When building applications that use shared images that contain either forms or procedural escape routines on OpenVMS Alpha, specify the following linker option when building these shared images:
The link command is as follows:
$ LINK/SHARE <form-name>, sys$input/opt - symbol_vector=(Forms$AR_Form_Table=Data)
If you declare symbols as universal symbols on OpenVMS VAX, declare
them using the SYMBOL_VECTOR= option on OpenVMS Alpha. In certain
cases, you must declare shared-procedural, escape-routine (PEU) entry
points in this option as well. Refer to the DECforms Version 2.x
Release Notes for information about using the SYMBOL_VECTOR= option for
linking DECforms images.
16.2.2 Caching with Multiple Submitter Platforms
To support forms caching, the application execution controller (EXC) checks that all form image files are present when the application starts. Therefore, if you use DECforms form image files on multiple submitter node platforms, you must define the following logical name on the application node:
This notifies the EXC that there are multiple submitter node platforms. The scope of the logical name can be systemwide. However, if you have multiple applications, you may want to define this logical name at the application level by using the APPLICATION LOGICALS clause in your application definition.
At startup, the EXC translates the logical name. If the value of the logical name is set to "T", "t", "Y", "y", or "1" and the file type in the FORMS clause of the task group definition specified is .EXE, the EXC looks for the presence of both form image files (form_name.EXE_VAX and form_name.EXE_AXP). If either file is missing, the application does not start. If the logical name is not defined or translates to something other than "T", "t", "Y", "y", or "1", the EXC looks for the file that is specified in the task group definition. If you have multiple submitter platforms and FORM image files are copied to the submitted nodes manually, the file type must be retained (for example, form_name.EXE_VAX and form_name.EXE_AXP).
If your ACMS application uses DECforms Version 1.4 or TDMS, you must
distribute it in order to use ACMS for OpenVMS Alpha. In this case, the
forms processing must be on an OpenVMS VAX submitter node. Some I/O
restrictions apply to ACMS in a distributed environment. See
Compaq ACMS for OpenVMS Managing Applications for more information on distributed forms processing.
16.3 Using Logical Names
Use logical names instead of hardcoded names to make your application more flexible and easier to maintain. If an application is moved to another directory or node, you simply redefine the logical names to reflect the new configuration. If you do not use logical names, you must modify and rebuild your application. You can use logical names to define the following:
Using logical names also makes distributing your application easier, because fewer changes in the source code are required.
When used in a multiplatform environment, form names cannot be logical names. See Section 16.2.2 for more information.
Table 16-2 lists the ADU clauses in which you can specify a logical name, and the ACMS definitions containing the clauses.
|IMAGE||Task, task group|
|WORKSPACES||Task, task group|
|DEFAULT OBJECT FILE||Task group|
|DEFAULT TASK GROUP FILE||Task group|
|MESSAGE FILES||Task group|
|PROCEDURE SERVER IMAGE||Task group|
|REQUEST LIBRARIES||Task group|
|APPLICATION DEFAULT DIRECTORY||Application|
|DEFAULT APPLICATION FILE||Application|
|DEFAULT MENU FILE||Menu|
This chapter describes how to migrate applications from OpenVMS VAX to OpenVMS Alpha, focusing on information specific to ACMS on OpenVMS Alpha. Two options are available for migrating your application:
For additional details on migrating applications, see the following OpenVMS Alpha documentation:
The format of an executable image is different on OpenVMS VAX and OpenVMS Alpha. In order for an ACMS application on OpenVMS Alpha to use an executable image, you must choose one of the following options:
If the OpenVMS Alpha compiler is currently not available for the language your source code is written in, or if the source code is not available, then translation is your only option.
Compiling and linking on OpenVMS Alpha is the preferred option because it achieves better performance than translating images.
You may need to make changes to source code that has dependencies on the underlying OpenVMS VAX architecture before you compile and link the source code on OpenVMS Alpha. The following list provides some examples of source code that needs to be modified:
When you migrate an application, you must consider that the default compiler behavior for alignment of fields within records/data structures may differ on OpenVMS VAX and OpenVMS Alpha. This is especially important if the data structures are shared or passed between OpenVMS VAX and OpenVMS Alpha. For example, the default behavior of the VAX C compiler is to not align fields on their natural boundaries within a data structure, whereas the default behavior of the DEC C compiler for OpenVMS Alpha is to align fields on their natural boundaries within a data structure.
See Migrating an Application from OpenVMS VAX to OpenVMS Alpha and the language documentation for more information
about OpenVMS VAX dependencies.
17.4 Compiling and Linking on OpenVMS Alpha
In some cases, you can use the ACMS databases that were built on OpenVMS VAX without building them again on OpenVMS Alpha. Table 17-1 describes when you can and cannot use databases built on OpenVMS VAX without rebuilding them on OpenVMS Alpha.
|The task group database (TDB) was built with the /DEBUG qualifier||You want to debug tasks on OpenVMS Alpha||You must rebuild the task group on OpenVMS Alpha|
|The TDB was built with the /NODEBUG qualifier||You are not going to compile and link server procedures on OpenVMS Alpha||You do not need to rebuild the task group on OpenVMS Alpha|
|You are compiling your server procedures on OpenVMS Alpha||You must rebuild the task group on OpenVMS Alpha|
|The application database (ADB) contains TASK access control lists (ACLs)||The User Identification Code (UIC) or identifiers in the ACLs have different values on the OpenVMS Alpha submitter node||You must rebuild the application on OpenVMS Alpha 1|
|The menu definition contains an optional clause that calls TDMS, that is, REQUEST IS||If you use this clause, you can still access the menu database from OpenVMS Alpha. However, the clause will be ignored and ACMS will display the default command line menu.|