Compaq ACMS for OpenVMS
Writing Applications


Previous Contents Index


Chapter 3
Using DECforms with ACMS

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:

3.1.2 Processing External Requests

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.

3.2 Writing and Compiling DECforms Escape Units

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

Note

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

3.2.2 Calling an Escape Unit in a Form Source IFDL File

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:

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.

Note

When you use DECforms, form objects and escape unit objects cannot be linked with agents.

The following list describes the advantages and disadvantages of each method for linking escape units:

3.4.1 Managing Escape Unit Files

Escape units are executed in the context of the agent process. Consequently, the application and system managers must consider the following:

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 not activated.

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:

3.7 User Interface Features with DECforms

DECforms user interface features include the following:

3.8 Comparison of DECforms and TDMS

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.

Table 3-1 DECforms and TDMS Terminology
DECforms Term TDMS Equivalent
Form Request
Form file Request library file
Form record CDD record definition
IFDL source file Request definition file
Panel Form
Panel field Form field
Panel Editor Form editor (Layout Phase)
Layout (No equivalent)
Viewport (No equivalent)
Request response (No equivalent)
Request calls TDMS programming calls
Literals Background text
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.

Note

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.


Previous Next Contents Index