HP OpenVMS Systems Documentation
Compaq ACMS for OpenVMS
Chapter 3 describes how the implementation of DECforms affects ACMS
task and application definitions. Separate sections in this chapter
explain the ACMS interface to DECforms, making calls to DECforms
external requests, new DECforms user interface features, writing and
compiling DECforms escape units, and a comparison of DECforms and TDMS.
3.1 ACMS Interface to DECforms
The ACMS interface to DECforms is made up of six calls. These calls enable, disable, or cancel a form as well as send, receive, and transceive (a combination of send and receive) information to and from the form. ACMS makes these calls to DECforms external requests, which are requests called from outside the form.
The next section explains how external requests are called by ACMS. The
second section outlines how DECforms processes external requests.
3.1.1 Calls to External Requests
ACMS automatically makes calls to three external requests:
You make calls to the remaining three external requests in the EXCHANGE step of an ACMS task definition:
In processing external requests, DECforms follows a specific order of
steps, called phases. See DECforms Programmer's Reference Manual for more
details on how phases proceed with DECforms.
3.1.3 Responses to External Requests
With DECforms, use responses to control the operation of forms processing. You can think of a DECforms response as a way of directing how DECforms responds or behaves. By declaring responses, you can determine much of what DECforms does in its interaction with the user's terminal, the form, and the ACMS application.
The following list describes DECforms responses that you can use to direct the actions of forms processing. The descriptions include references to the DECforms documentation for additional information.
In DECforms, you can use escapes to call subroutines from the form. These subroutines, which are called escape units, perform actions outside the form, such as data validation or database lookup. (Escape units are similar to UARs in FMS.)
Many agents, including the CP agent supplied by ACMS, perform work on behalf of multiple users. These agents are multithreaded or asynchronous. However, DECforms escape units provide only a synchronous interface. When you use an escape unit in a multithreaded or asynchronous agent, be careful not to do anything that might delay the CP agent in its processing other users' requests. For example, do not perform terminal or disk I/O from an escape unit executing in a multithreaded or asynchronous agent.
Using DECforms escape units is a two-step procedure. You must write the
escape unit, and you must also edit the form IFDL source file to call
the escape unit from the form. The following sections explain the steps
necessary to write and implement DECforms escape units.
3.2.1 Writing an Escape Unit
You can write an escape unit in COBOL or in any other high-level programming language that supports the OpenVMS calling standard. Example 3-1 shows a COBOL program that counts the number of employees added to the EMPLOYEE_INFO_RECORD_1.
|Example 3-1 Example of an Escape Unit|
*************************************************** IDENTIFICATION DIVISION. PROGRAM-ID. EMPLOYEE_COUNT. *************************************************** ENVIRONMENT DIVISION. CONFIGURATION SECTION. SOURCE-COMPUTER. VAX-11. OBJECT-COMPUTER. VAX-11. *************************************************** DATA DIVISION. WORKING-STORAGE SECTION. LINKAGE SECTION. 01 EMPL_COUNT PIC S9(9) COMP. *************************************************** PROCEDURE DIVISION USING COUNTER. 00-DO-ADD. ADD 1 TO COUNTER. END PROGRAM EMPLOYEE_COUNT.
One use for the COUNTER value is to display its value on a panel after a message such as "Total number of employees is."
After you write an escape unit, you create an object (.OBJ) file by compiling the escape unit. For example:
$ COBOL employee_count
To use a DECforms escape unit, you must also enter a response step in the form source IFDL file to call that escape unit. The function of the escape unit created in Example 3-1 is to count employees as they are added to the database. You need to place the call to the escape unit within an external response, which directs DECforms to vary its processing of an external request. For example:
RECEIVE RESPONSE EMPLOYEE_INFO_FORM DISPLAY EMPLOYEE_INFO_PANEL_1 CALL 'EMPLOYEE_COUNT' USING EMPL_NUMBER END RESPONSE
In the previous example, the CALL response step calls the escape unit
EMPLOYEE_COUNT and passes the form data item EMPL_NUMBER to the escape
unit. For each EMPL_NUMBER sent to it, the escape unit adds 1 to the
COUNTER variable and returns the new value to the form. When the escape
unit finishes, DECforms ends the response.
3.3 Linking DECforms Form Objects
After you have edited your form's IFDL source file and translated it into a binary .FORM file, you need to create an object module and a shareable image of the form to use in your application. First, use the DECforms EXTRACT OBJECT command as follows:
$ FORMS EXTRACT OBJECT EMPLOYEE_INFO_FORM.FORM
This command creates a form object module, or .OBJ file. Then link the object into a shareable image:
$ LINK/SHARE EMPLOYEE_INFO_FORM.OBJ
The result of the LINK/SHARE command is an image (.EXE) of the file,
which can be shared by multiple users.
3.4 Linking Escape Units
The two methods for linking the escape units used in an application are:
$ LINK/SHARE EMPLOYEE_INFO_FORM.OBJ, EMPLOYEE_ESC_UNIT.OBJ
$ LINK/SHARE=SHARE_ESC_UNIT.EXE EMPLOYEE_ESC_UNIT1.OBJ, - _$ EMPLOYEE_ESC_UNIT2.OBJ, ESC_UNIT.OPT/OPT
When you link escape units into a separate image, you must use an options file to declare all escape unit names as universal. For example:
UNIVERSAL = EMPLOYEE_ESC_UNIT1 UNIVERSAL = EMPLOYEE_ESC_UNIT2
If you link escape units separately, you can place them in a write-protected directory for security. However, ACMS does not automatically cache escape unit images that are stored separately. Instead, the system manager must manually distribute the escape unit image files. Compaq ACMS for OpenVMS Managing Applications explains caching ACMS and DECforms files in more detail.
When you use DECforms, form objects and escape unit objects cannot be linked with agents.
Certain agents, such as the CP agent that ACMS supplies, run in a privileged environment. Any escape units that execute in a privileged agent also execute in the same privileged environment. Be sure to develop escape units to execute in a privileged agent in the same way as you develop any other privileged code. Carefully review the code for any possible security violations before you run it live on the system.
Place the escape unit images in a write-protected directory; also write-protect the images themselves. After you place the file in a protected directory, you can define the logical names that make the escape units available to the agent process.
You may not, however, need to place the escape units executed by a
nonprivileged agent in a protected directory. In some cases, such as
debugging, you may want the person running the CP agent to be able to
change the escape units executed. Use the methods described in this
section to make the escape unit images available to the CP agent.
3.4.2 Replacing Form Files
If you need to change a DECforms file in binary format (.FORM), stop the application and restart it before using the new file. This procedure ensures that EXC has the correct file information for caching purposes.
DECforms files in image format (.EXE) require different treatment. Before using a new form image file for DECforms files in image format, stop the terminal subsystem so that the CP can map the new version of the form image. This action is necessary because OpenVMS maps these images into the processes that are using them, and there is no way to unmap the images.
Form image files are recommended for production environments, because they require fewer resources in multithreaded environments than files in binary format. The following procedure is suggested for customers who need to replace form image files without stopping the agent process.
The ACMS task group definition must specify the form file with a logical name rather than a file specification. Define the logical name outside ACMS in a logical name table accessed by both the EXC process and the application manager.
To replace a form file:
When you follow this procedure, the application picks up the new name of the form file and passes it to the agent. The agent then asks OpenVMS to map the renamed file. Because the OpenVMS image activation code sees the new name of the form file, it considers the file to be different from any files that are already mapped in. The renamed form file is mapped in, and the agent process begins to use it.
Note that the OpenVMS image activation code uses only the file name
portion of the file specification to determine whether or not it is a
new image. Changing other parts of the file specification (for example,
device, directory, file extension, or version number) has no effect.
Each image can be activated only once in a process. If an image file
has been activated, then a different image file with the same name is
3.5 Creating Forms Trace Files
To create DECforms forms trace files, define the DECforms logical names FORMS$TRACE and FORMS$TRACE_FILE. If you are using the CP, define the two DECforms logical names in the the system name table.
If you define FORMS$TRACE but not FORMS$TRACE_FILE, DECforms writes the
trace file to the CP default directory. In this case, you must ensure
that the CP default directory exists. Otherwise, the CP does not enable
forms because it cannot create trace files for the forms. If this
happens, ACMS does not let users sign in. This situation occurs even if
you define the ACMS$DEFAULT_MENU_FORMS_PRODUCT logical name to be TDMS.
3.6 Naming Forms Image Files
If you use DECforms forms image files, adhere to the following restrictions when you name the image files:
An error was returned from a DECforms request %FORMS-F-INVFHDSIZ, invalid form header size.
Although there are not always exact equivalents between DECforms and TDMS, Table 3-1 is useful in understanding the differences and the similarities of these two forms products.
|DECforms Term||TDMS Equivalent|
|Form file||Request library file|
|Form record||CDD record definition|
|IFDL source file||Request definition file|
|Panel field||Form field|
|Panel Editor||Form editor (Layout Phase)|
|Request response||(No equivalent)|
|Request calls||TDMS programming calls|
|Function keys||Program request keys and redefined keys|
Refer to DECforms Guide to Converting VAX TDMS Applications for more information about TDMS and DECforms terminology.
You can use the TDMS Converter to convert TDMS forms or TDMS requests, or both, to a DECforms IFDL source file. There are many differences between the two forms products, and ACMS continues to support TDMS forms. Therefore, it is recommended that you use DECforms to develop new forms, but that you continue to use TDMS forms for existing ACMS applications. See DECforms Guide to Converting VAX TDMS Applications for more information on conversions.